/task

Surface Routing

Before starting, pick the right tool for the job:

Activity	Tool	Why
Architecture planning	Claude Code /plan	Opus, 1M context
Feature implementation	Claude Code	Hooks, subagents, worktrees
Quick single-file fix	VS Code Claude ext	Faster for small scope
DevOps / terminal	Codex CLI	Strong at terminal tasks
Background refactor	Codex Cloud	Fire-and-forget PR
Code review	GitHub Actions	Async, no session cost
Test writing	subagent: test-writer (CC) / inline (Codex)	Isolated context
Documentation	subagent: doc-writer (CC) / inline (Codex)	Cheap, focused
Research	Claude.ai Projects	Persistent, web search

Cross-Tool Notes

This skill uses Claude Code features. Portable equivalents for Codex/Cursor:

Claude Code	Codex / Cursor
`TaskCreate` / `TaskUpdate`	Markdown checklist in `.branch-context.md`
`EnterWorktree`	Use absolute paths + `git -C` for all ops
`/orient`, `/brainstorming`, etc.	Read `.agents/skills/<name>/SKILL.md` and follow manually
Subagent dispatch (`implementer`, `test-writer`)	Execute sequentially in main session
Agent Teams	Not supported — use sequential work
`/review`, `/plan-review`	Read `.agents/skills/review/SKILL.md` and follow manually

Args

Invocation	Behavior
`/task <description>`	Start new task
`/task #<issue>`	Start from GitHub issue
`/task`	Start new task — ask what to work on

Copilot Mode

In copilot mode (operating-mode.md), the workflow is a menu, not a pipeline:

Present available steps. Execute what the human asks. Don't enforce order.
Worktree-first is relaxed — primary worktree writes are allowed.
Invariants below still apply except where operating-mode.md explicitly overrides.
If the human says "follow the workflow," run step-by-step but pause for approval at each transition.

Invariants

These rules are agent-interpreted guidance, not machine-enforced. They cannot be skipped regardless of task type or scope unless noted. Omission is not permission — any step not explicitly listed as skippable is required.

REQUIRE task_list.all_steps_populated BEFORE step_1
REQUIRE worktree BEFORE code
REQUIRE orient.complete BEFORE plan
REQUIRE tests BEFORE implementation  # TDD: RED → GREEN → REFACTOR
REQUIRE review(plan).pass BEFORE build UNLESS scope == one_sentence OR task_type IN [fix, hotfix]
REQUIRE validate.pass BEFORE review(build)
REQUIRE review(build).pass BEFORE archive
REQUIRE task_list.no_pending_steps BEFORE ship
REQUIRE branch.base IS CURRENT(origin/main) UNLESS stacking
REQUIRE plan.commit BEFORE review(plan)
REQUIRE batch.commit BEFORE batch.next

WHEN ci.down:
  USE local_merge AT step_8
WHEN files_touched MATCH [AGENTS.md, config.toml, sync.sh, skills]:
  REQUIRE codex_specialist IN review_panel

Steps

Persist significant decisions to .branch-context.md during Steps 3-5 — not just at reflect/bail time.

Step 0 — Bootstrap

Create a task list with ALL steps for the detected path. Every step is a task — no exceptions. The task list is the enforcement mechanism: pending tasks are visible proof of unfinished required work.

Claude Code: TaskCreate one task per step. Populate all steps upfront (adjust after orient detects path). Mark each in_progress before starting, completed when done.
Codex/Cursor: add a markdown checklist to .branch-context.md with all steps.

Step 1 — Orient

Invoke /orient with args (Codex: read .agents/skills/orient/SKILL.md). It produces:

task_type: feat / fix / chore / docs / test / refactor
scope: can the entire diff be described in one sentence? Yes → short path (skip Steps 3-4). No → full path. Note: short description ≠ small change — "update all deps" sounds short but may touch dozens of files.

After orient completes, populate the task list with remaining steps for the detected path:

Hotfix (fix/*, hotfix/*): ALWAYS skip Steps 3-4 regardless of scope. No plan, no plan review — go directly to Step 5.
One-sentence scope (any task type): skip Steps 3-4.
Everything else: full path (Steps 0-9).

Step 2 — Isolate

Invoke /isolate with the branch name from Step 1 (Codex: read .agents/skills/isolate/SKILL.md). It handles freshness (fetch origin main), worktree creation from origin/main, directory selection, gitignore safety, dependency install, and baseline test verification. If already in a worktree, it freshens the branch instead of creating a new one.

Path discipline: cd does not persist between Claude Code Bash calls. After worktree creation, use absolute paths for all file operations and git -C <absolute-path> for git commands. Never rely on cd carrying over.

Step 3 — Plan

Hotfix (fix/*, hotfix/*): SKIP — proceed to Step 5. No architect agent, no plan file. Add a one-paragraph diagnosis to the commit message instead. Log: "Step 3 — Plan: SKIPPED (hotfix fast path)."

One-sentence scope: SKIP — proceed to Step 5. Log: "Step 3 — Plan: SKIPPED (one-sentence scope)."

Full scope:

3a. Brainstorm. Invoke /brainstorming with the task description. One round — refine the idea, confirm constraints, explore 2-3 approaches.

3b. Write plan. Write a plan to ai-workspace/plans/<name>.md using the template at ai-workspace/plans/TEMPLATE.md. Fill all template fields including:

Branch, created date, status
Threat model (advisory or adversarial)
Scope ceiling
Task description and scope
Steps with checkboxes (include files to create/modify and testing strategy)
Confidence scaffold (recommended for adversarial threat models)

Do NOT review the plan here — that's Step 4.

Step 4 — Review Plan

No plan (hotfix or one-sentence scope): SKIP — proceed to Step 5.

Has plan:

Run /review against the plan file (Codex: read .agents/skills/review/SKILL.md and follow manually).

Auto-assemble the plan review panel:
- Always: technical-editor
- Code architecture: add architect-reviewer
- AGENTS.md / config.toml / sync.sh / skills: add codex-specialist
- Auth / credentials / permissions: add security-auditor
- UI / component / CSS: add ui-designer
Gate: P2 (fix P0-P2, record P3+)
Cap: 3 rounds

On APPROVE: proceed to Step 5. On ESCALATE after 3 rounds: stop and present unresolved findings to human.

Step 5 — Build

Invoke /build (Codex: read .agents/skills/build/SKILL.md). It handles plan parsing, batch-sequential/task-parallel subagent dispatch, TDD, inter-batch regression checks, and the validate hard gate. For hotfixes or one-sentence scope, it implements directly with TDD. Step 6 cannot begin until /build reports validate passing.

Hotfix protocol (applies when task_type is fix or hotfix):

MUST fix the defect only — nothing else (minimal change principle).
MUST NOT refactor during a hotfix; create a separate branch for cleanup.
MUST test the specific failing case first (RED), then fix (GREEN).
MUST document the root cause in the commit message body.
MUST NOT modify agent profiles without explicit approval.

Step 6 — Review Build

Run /review against the changed files (git diff main...HEAD) (Codex: read .agents/skills/review/SKILL.md and follow manually).

Auto-assemble the code review panel (differs from Step 4's plan panel):
- Always: code-reviewer
- Code architecture: add architect-reviewer
- AGENTS.md / config.toml / sync.sh / skills: add codex-specialist
- Auth / credentials / permissions: add security-auditor
- UI / component / CSS: add design-reviewer
Gate: P2
Cap: 3 rounds

On APPROVE: proceed to Step 7. On ESCALATE: stop and present unresolved findings to human.

Step 7 — Archive

Has plan:

Invoke /archive (Codex: fill Outcomes & Learnings in plan file, rename to .done.md). It fills Outcomes & Learnings in the plan file and renames to .done.md.

No plan (hotfix / one-sentence):

Ensure root cause or change rationale is documented in the commit message body. No plan file to archive.

Step 8 — Ship

Invoke /ship (Codex: read .agents/skills/ship/SKILL.md). It handles validation, option presentation (PR + auto-merge vs local merge vs keep vs discard), CI up/down routing, shallow-clone merge for the local path, and worktree cleanup. CI status comes from conversation context — if the user said CI is down, /ship uses the local merge path.

When files touched include AGENTS.md, config.toml, sync.sh, or skills → codex-specialist must be in the review panel (enforced at Step 6).

Step 9 — Reflect

Invoke /reflect (Codex: read .agents/skills/reflect/SKILL.md). It handles:

Reading .branch-context.md for session learnings
Writing to MEMORY.md on main
Filing follow-up issues if needed
Cleaning up branch artifacts

Definition of Done

Bail

Invoke /bail at any step to abort cleanly. It handles: learnings capture to .branch-context.md, issue update, PR close if open, worktree cleanup. Bail replaces Step 9 (Reflect) — it captures learnings itself. Clean up any open task list items.

task