feature-workflow

name

feature-workflow

description

The user's six-stage feature pipeline (discuss → plan in native plan mode → validate + approve → delegated execute → one /codex challenge per feature → ship), the parallel multi-agent mechanism picker, and the token-discipline rules for long-running agents. Invoke BEFORE starting any non-trivial feature — multiple steps, or work that benefits from a formal review cycle — and before any parallel/multi-agent fan-out. One-shot edits and small fixes outside an active pipeline skip it.

Feature workflow

For pipeline-path work (global CLAUDE.md → Feature workflow): a design/product/UI choice, 4+ files, irreversible, or a real multi-step arc. One-shot work (≤3 files, no design choice, reversible) skips this skill entirely — but not the codex cross-review: it still runs one /codex challenge on its diff under the stage-5 rules before the change counts as done.

One master session owns the feature end-to-end. It stays thin by running every token-heavy stage out of main context — in a subagent or an agent-team agent. The master coordinates and ingests summaries; it does not implement substantial work or hand-author specs. Plan files live in the repo at docs/prompts/<feature>-plan.md.

Six stages, each delegated out of main context by the master session:

1. Discuss approach → /office-hours. Explore the problem space, surface constraints, decide what's worth building. No code.
2. Plan in native plan mode → the master calls EnterPlanMode first, then delegates codebase discovery and the draft to a team-planner subagent, which RETURNS the plan text (subagents cannot write files while the master is in plan mode — the harness blocks it regardless of agent frontmatter). The master writes the returned text verbatim into the plan file named in the plan-mode system message — that file is the canonical plan until approval. Transcribing is not authoring: the master never composes, expands, or restructures the spec inline; "scope"/"plan"/"design" requests go to the planner subagent. Revisions are the same shape — a fresh planner spawn (plan-file path + what changed) returns only the changed sections, and the master splices them in with Edit.
3. Validate + approve → spawn team-plan-reviewer (read-only, one pass) with the plan-file path; it checks the plan against the code and returns blocking / advisory findings. Blocking → fresh planner revision → splice → done (no re-review unless the revision was material; never more than two review passes). Advisory → reported to the user at the gate, never looped on. Then resolve the planner's taste/open decisions with one AskUserQuestion (≤5 materially-divergent items, each offering the simplest option — often "leave it out"), splice the answers in, and call ExitPlanMode — Claude's native approval gate. "No, keep planning" feedback goes to a fresh planner revision spawn and back through ExitPlanMode; on approval the master copies the plan file to docs/prompts/<feature>-plan.md, commits it, records the feature-base sha (git rev-parse HEAD) for the stage-5 range, and mirrors the plan into the native task list (TaskCreate): one task per execution step plus the fixed tail — codex verdict clean or stopped at plateau with remainder reported; standalone-P2/test-gap/theoretical fix-or-defer asked and tech-debt entries committed; test suite exits 0 with output shown; handoff written; no live agents. Chain them with TaskUpdate addBlockedBy where a step actually consumes an earlier one's output — it edits a file that step created, builds on a decision it made, or verifies its work; steps that need nothing from each other stay unblocked. The codex task is blocked by every step, the fix-or-defer task by codex, tests/handoff/no-live-agents by everything before. The plan doc stays the source; the task list is its live summary (Ctrl+T). Then start stage 4 unprompted.
4. Execute → delegate each step to a subagent; commit per step. Spawn executors unnamed — name: reroutes delivery to the teammate mailbox, where a report arrives only if the agent remembers to send it; unnamed spawns auto-deliver their final report. Sequential steps go to step-executor (session's own branch, no worktree — it's the only writer in flight); independent steps that run at the same time go to agent-teams and its team-executor instead. State each step's acceptance criteria once and stop there — no "re-verify", "double-check", or per-round verification rituals in spawn prompts: Opus-5-generation models verify their own work unprompted, and explicit instructions compound into waste. Size and split spawns here, not later: a plan step is sized so a step-executor finishes in roughly ≤100 tool calls (split it in the plan if it can't), and every spawn carries exactly one concern — one step, or one fix. Never bundle several playtest fixes, regressions, or finding sets into a single spawn; a fixer gets the plan section, the diff range, and the one finding set it is fixing. Fixing reported-broken behavior is red-then-green, test-first: the test is written and run red before the fix is applied — one red run, then the fix, one green run, both shown. Reverting a finished fix to show the test red is the fallback for a fix that was already written, not the default mechanics: the revert-restore dance costs two extra test runs per fix (minutes each on iOS) for evidence the test-first ordering gives for free. This is an acceptance criterion, not a verification ritual: it is the deliverable that distinguishes a fix from a plausible edit, and a suite that was never seen red is the reason a bug survives round after round of green runs. It applies to fixers and to any step whose job is a stated bug; a step that builds new behavior just states its criteria. Test cadence: a step's acceptance criteria name the build and the targeted suites that cover it; the whole test suite runs once after the last step lands (the master schedules it as the final execution task) and again after the fix loop — never per step. The 2026-08-22 clipsy arc ran the full xcodebuild test 3–6 times per step — 282 runs, 207 minutes of build time across 17 steps — for regressions the per-step suite did not catch anyway. Per-step review: when a step's commit lands, the master launches a codex challenge on that step's diff (<prev-step-sha>..<step-sha>) as one background Bash — same launch pattern as stage 5, worktree pinned at the step's sha, since the next step's executor is writing — while that next executor runs; the triage lands at the following step boundary, and P0/P1 findings go to a fixer before the step after that spawns. Per-step rounds flag correctness and requirement gaps only — no style, no speculative hardening — and they are bug-catching, not the gate: stage 5's whole-range challenge still decides clean. Why: the 2026-08-23 arc reviewed only at the end and met 14 P1s at once over 11 steps — each step had built on the previous steps' unreviewed bugs, and the fix loop then ran 12 rounds. the global spawn-pin rule applies. Its two pipeline exceptions: Opus for an executor when the plan marks that step Opus with a one-line reason and the plan-reviewer let it stand, and Opus for a fixer only in the same-mechanism structural case below. Every other fixer is Sonnet, and fixers spawn as (effort medium), not (effort high) — a bounded finding set at a known spends extra effort on ramp-up, not accuracy. When an agent's report asks something — "say the word if you want it mirrored" — that question goes to the next gate verbatim, as its own AskUserQuestion or an explicit option, never replaced by the master's framing of the same decision. Triaging a report into your own agenda and dropping the embedded ask is how a question that reached you still never reaches the owner. Same care in reverse: the owner can type directly into a running agent's chat and that message reaches only that agent, so an unexplained diff from a live agent is a question for the agent — read its transcript — not a rogue-agent finding. mark a step's task when its executor is spawned and when its commit lands and acceptance criteria are shown () — never completed with failing tests or a partial fix; a blocker becomes a new task, not a silent skip; a task is deferred only with the user's say-so, with the reason in the task. The arc is complete when no task is open, and the closing report shows the final .
5. Independent review per feature → after the last step is committed, ONE gstack /codex challenge on the feature's whole diff — Skill(codex, "challenge <feature-base-sha>..HEAD"), where <feature-base-sha> is the commit the first step started from (recorded at plan approval). The master runs it, backgrounded: Skill(codex, "challenge …") loads the challenge prompt; the master pins a detached worktree at the sha (git worktree add --detach <scratch>/review-<sha> <sha>), launches the skill's codex exec … --json | python … pipeline as ONE Bash call with run_in_background: true, stdout redirected to the verdict file, with gtimeout 2400 in place of the skill's _gstack_codex_timeout_wrapper 600, and spawns the kit's codex-triage agent when the completion notification lands — never a subagent for the run itself (why: Token discipline). Stage-4 per-step rounds and fixer-commit deltas never satisfy this gate — the gate is the whole range at a single HEAD; never codex:codex-rescue; bare codex exec only if the gstack skill is unavailable — same challenge prompt, same diff range, same file-plus-triage output contract, and the fallback named in the report; /codex review (pass/fail) only when the user asks for it by name. In parallel with the whole-range run, one spec-reviewer spawn (Sonnet, read-only) checks <feature-base-sha>...HEAD against the approved plan file — unimplemented or incomplete requirements, scope creep, wrong-logic-vs-spec; gaps only, no style. A missing requirement routes into the P0/P1 lane; scope creep is reported at the gate. Nothing else in the pipeline verifies the finished range against the spec — the plan-reviewer ran before execution, and a long fix loop mutates the diff well past what step acceptance criteria covered. Triage real / regression / test-gap / theoretical, and give every real finding a priority: P0 = crash, data loss, security, or a regression breaking a core flow — fixed immediately, and always blocks ship; P1 = wrong behavior reachable in normal use (any other regression is at least P1, never P2); P2 = real but reachable only through unusual or pathological input; test-gap and theoretical carry no priority — priority exists to route the fix loop, and neither class ever enters it. Every finding also carries the runner's own confidence, 0–1 — a finding the runner half-believes is a conf:0.4 line, never a paragraph arguing itself down. Clean = zero P0/P1. Fix loop: the loop runs on P0/P1 only — one fresh Sonnet fixer per finding set → re-challenge — and each set also picks up any P2 sharing a file or mechanism with its P0/P1s (arc-3 round 1 already routed one P1 plus its adjacent P2 cluster to a single fixer; the marginal cost is near zero). a round whose P0/P1 count does not strictly decrease forces the structural branch — an Opus mechanism-fixer under the same-mechanism clause (Token discipline), or AskUserQuestion when the structural fix exceeds the plan's design contract — never another patch round. Exit at zero P0/P1, or after two consecutive non-decreasing rounds: stop, defer the remainder, report. Why counts, not rounds: arc-3's P1s went 8→8→10 across three rounds of instance patches, then declined strictly every round once an Opus structural fixer replaced the mechanism; arc-2 plateaued at 6 for two rounds and ran to 12 rounds under a standing "loop until zero" instruction with no convergence guard. Standalone P2, test-gap and theoretical findings are never looped on: once the verdict is clean or stopped, ask ONE AskUserQuestion listing them — (one fixer spawn for the set) / / — where deferring writes one each — — to the project's TODO/tech-debt file (, or if none) and commits it with the feature; the description stays in the committed verdict file and is fetched only when the fix is scheduled, so the TODO file stays an index, not an archive. A feature with no repo diff needs no verdict. Diff-review agents run at effort medium (review accuracy holds at lower effort — Opus 5 guide); plan review stays at , reading the plan against the whole codebase rather than a bounded diff.

Tell the runner to trace out of the diff. The prompt says to follow the diff into the state machines, invariants and shared components it perturbs without changing their lines, and to report findings there. This is an instruction to the reviewer, not a list the master enumerates in advance — the master naming the coupling would both pre-empt what the review exists to discover and imply the unnamed parts are out of scope. Why it earns a line: in the clipsy arc, retiring an always-open model broke an exit state machine in files the diff never edited, and three delta-scoped rounds came back clean before a whole-range gate found two P1s in it.

A range too big for one prompt is split, and the slices are still one gate. "ONE challenge" above is a rule about coverage and cadence — one gate per feature, over the whole range, not per step or per fixer commit — not a rule that one process must do it. When a single run can't cover the range, splitting is how that rule is honored rather than broken. The trigger is behavioral — the run times out, truncates, or the runner reports it could not read the whole range — not a byte threshold. Split by subsystem so the slices jointly cover the whole range with no gap, run them as concurrent runners against the same sha, and hand ALL slice output files to a single codex-triage spawn, which merges and dedupes them into the one triaged verdict — the master never triages slices separately or hand-recomputes cross-slice dedup (arc-2's master did, twice, on its way to a ~460k context of agent reports). The coverage claim is only as good as the gaplessness, so state the slice boundaries in the verdict; overlapping slices are fine, a gap is a failed gate. Record the reviewed range in the verdict file — <base-sha>..<head-sha> — because the next session cannot otherwise tell what has already been gated, which is exactly how the clipsy arc reached 47 unpushed commits with a whole-range gate that had never run.

Brief the defect and the invariant, never the patch. A fixer's spawn prompt carries what is broken and what must hold afterward. If the master has a fix in mind it goes in labeled as a hypothesis to verify and overrule, because the fixer is the one who will read the call sites. Three rounds of the clipsy arc were spent undoing master-prescribed fixes that the fixer's own trace later disproved — the pattern is a self-regression that the next round then reports as a P1. 6. Ship → /ship (PR) → /land-and-deploy (merge + deploy + post-deploy verify).

Rules:

• The always-on hard gates in global CLAUDE.md apply throughout: push approval, the /codex merge gate, verified-claims, AFK-is-not-approval.
• The master never touches product code — the global hard gate, in force from the moment this skill loads. Never redo or re-derive a subagent's work once its report is back.
• A missing report is a read-the-transcript signal, never a wait. An API error that ends a subagent early is never delivered as its result — the master gets nothing. If a delegate goes quiet past its expected window, read its transcript under the session's subagents/ dir: the work is often already complete. Salvage it, and respawn a fresh agent for only the remainder.
• Interactive gates never go to subagents. Subagents are headless — they cannot call AskUserQuestion or ExitPlanMode, so a delegated gate either auto-picks silently or dies. Gates run in the master session; only headless work (drafting, reviewing, executing) is delegated.
• Plan-approval is the trigger, not a suggestion. The moment build approval lands, transition unprompted into the delegated tail — spawn the first executor in the same turn and run stages 4–6 to completion without returning to the user except at the real gates (a structural fix exceeding the plan's design contract, the standalone-P2/test-gap/theoretical question, push approval).
• If the master nevertheless approaches the context ceiling (~500k tokens; 600k absolute max), do a deliberate, user-assisted handoff to a fresh master session — don't silently push past it. /context-save + /context-restore are the bridge.
• Master budget: a normal feature arc finishes under ~400k with no compression machinery. Crossing ~400k mid-arc is a defect signal, not a reason to compress or hand off: stop, post the cost checkpoint, and name what's flooding the context so the flow gets fixed. During the unattended tail, post a one-line cost checkpoint at every step boundary (elapsed time, approx context size), and END the session the moment the arc completes — never leave a finished session idling (each cache expiry re-pays the full context at premium pricing).
• Make handoff artifacts cold-start-ready without being asked: one standalone root README a fresh session needs no other file for, and attach plans to their task/ticket so a future session finds them by reference.
• Plan reviews used individually (/plan-eng-review etc.) run via sub-agents — review token burn doesn't belong in main context.
• If work is interrupted mid-step, commit WIP: so a resume is clean.

Parallel multi-agent

For genuinely parallel, independent work only; sequential pipelines belong to the feature workflow above. Pick the mechanism by need:

• Background subagents (DEFAULT): independent units, contracts known up front. Concurrent writers each need a worktree — spawn them as team-executor, which carries isolation: worktree in its frontmatter so no spawn call has to remember. Read-only fan-out needs no worktree. Set worktree.baseRef: "head" first, or executor worktrees branch from the remote default branch instead of your in-progress work.
• Workflows: large (10s+), deterministic/repeatable/resumable fan-outs with cross-checking.
• Named teammates (experimental, almost never needed): only to dialogue live with a delegated agent running in parallel, off the master tab, AND a shared tree is acceptable — teammates are NOT worktree-isolated. Needs CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 + teammateMode: auto + iTerm2.
• Keep teammateMode: "in-process" (the built-in default). Pane modes (auto/iterm2/tmux) spawn full named-teammate sessions that do NOT self-close; "off" is not a valid value. The delegate→build→review→fix workflow never needs live dialogue. Full pane/teardown mechanics live in the agent-teams skill.
• Kill delegated agents the moment their unit closes. Once an agent's output is ingested (commit merged, verdict triaged, report received), stop it in the same turn — agents are per-unit disposables, never kept warm. Before declaring an arc complete, enumerate live agents and confirm zero remain; the user must never have to kill leftovers by hand.
• Serial pipelines never run as named teammates. Fire-and-return background subagents produce one summary each; a teammate that is somehow unavoidable gets stopped the moment its unit closes.
• When to offer (lead only): if a task has independent parallel parts AND the user hasn't specified the approach AND the project's CLAUDE.md hasn't set a preference → ask whether to fan out before starting. If you are a worker, never re-ask — just do your assigned task.
• How: invoke the agent-teams skill for the full playbook (mechanism choice, roles, models, worktree/merge flow, the plan-only approval gate). Don't inline the playbook here.

Token discipline

Cost ≈ turn-count × context size: every agent turn re-pays its entire context as cache-read, so burn grows quadratically in a long-lived agent. Agent lifetime is the lever — not result size or output verbosity.

• Retirement is mechanical: maxTurns in the agent frontmatter, not a prose budget. The inline "~200k context / ~250 turns → commit WIP and stop" line was in every executor spawn of the 2026-08-22 clipsy arc and not one obeyed it — Steps 6, 11 and 12 ran to 514k–627k peak context (deduped by message id). step-executor/team-executor cap at 200 turns, fixer at 150, codex-triage at 60; each agent's own instructions tell it to commit WIP: plus a scratchpad handoff once it passes ~three-quarters of its cap. When the cap cuts an agent mid-flight, the master reads its transcript under subagents/, commits the WIP: itself, and respawns a fresh agent for only the remainder — it never raises the cap, and spawn prompts carry no budget line.
• The codex run lives in the master, backgrounded; a fresh codex-triage agent per round. A challenge on a real feature range takes 14–22 minutes of codex exec (measured on the three 2026-08-22 clipsy rounds), and two ceilings sit at ten: the Bash cap (BASH_MAX_TIMEOUT_MS, 600 s unless raised) and gstack's own absolute gtimeout 600 around codex exec (gstack-codex-probe:141 — a hard kill, not a stall detector). A subagent cannot wait that out: a foreground call shaped as a compound pipeline is stopped at the cap, not moved to the background (docs: only simple commands auto-background; sleep-led, git-containing and unparseable compounds are killed), and a backgrounded call is ended at the subagent's final response, so the verdict lands in a context that no longer exists. The retired codex-runner agent tried foreground-plus-re-block and lost 3.4 h over two rounds polling a marker file for a run the cap had already killed, while a stale interactive codex TUI PID made ps | grep codex read "still alive". The master is the one context the harness does re-wake on a background completion, so the run is a single run_in_background Bash in the master — detached worktree pinned at the sha, the skill's pipeline minus its 600 s wrapper (gtimeout 2400), stdout to the verdict file, the whole call wrapped in a retry loop (up to 3 attempts, 5-minute spacing) so an API or CLI outage during an unattended run self-heals instead of dying silently — the 2026-08-24 close-out lost 3 h 17 m to a single 529 outage nothing retried. After launching, the master ends its turn or does work that doesn't depend on the verdict. Triage is a fresh spawn (Sonnet, medium) per round: it reads the round's output file(s) — all slices of a split round go to the one spawn — checks each finding against the pinned checkout, and returns the ≤2,000-char verdict; a round needs only the range and the file(s), never prior rounds' context. Post-review fixes go to a fresh agent (Sonnet at effort medium, frontmatter default) that commits its fix on the branch like any executor, never back to the original executor at peak context. A fixer spawn prompt is briefed like an executor's: the plan section (path + line range), the diff range, and the verdict's P0/P1 findings (plus their adjacent P2s) only — a fixer prompt missing the plan pointer is a briefing defect, not a shortcut.