task

/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

• Dependencies install (pnpm install)
• All tests pass (pnpm test:all)
• Types check (pnpm typecheck)
• Biome clean (pnpm lint)
• Formatter clean (pnpm format:check)
• Code reviewed (PR: by another agent; local merge: /review panel)
• Plan file has Outcomes & Learnings filled in
• PR/commit description written with context for reviewer
• Branch merged to primary (via PR or /local-merge)
• Key learnings consolidated with /reflect and pushed to primary

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.