feature-loop

Feature Loop

Advance the autonomous Feature Loop by one stage, run it to completion, then exit. You are running unattended (no human answering mid-run), whatever fired you — an Orca automation, a cron+claude launcher, a Claude routine, or a human typing /feature-loop. Architecture + rationale: docs/adr/0022-autonomous-feature-loop.md.

Runtime modes (auto-detected)

The loop needs two runtime primitives: a way to run isolated workers (for DESIGN and parallel BUILD) and a run-lock. It picks a mode automatically; everything else in this skill is identical across modes.

• Orca mode — if orca status --json reports a ready runtime. Workers are Orca worktrees + agents, coordinated via the /orchestration skill. You get a UI and cross-session lifecycle.
• Local mode — otherwise (no Orca). Workers are git worktree add checkouts driven by Claude Code sub-agents (the Agent tool, launched concurrently in one message). No Orca, no extra setup — runs anywhere Claude Code runs.

Detect once: run orca status --json; if it errors or the runtime isn't ready, use local mode. Mode-specific steps are tagged ‹orca› / ‹local› below.

Worker primitive — "run <brief> on branch <branch> in isolation"

• ‹orca›: orca worktree create --name <name> --base-branch <branch> --agent claude --prompt "<brief>" --json, then track via /orchestration (dispatch --inject, wait for worker_done).
• ‹local›: git worktree add <path> <branch> (creating the branch if needed), then launch a sub-agent (Agent tool, general-purpose) whose prompt is: "Work only in <path>. <brief>. Commit to <branch>. Report what you changed and any assumptions." Launch several in one message for concurrency.

Run-lock primitive (Step 0)

• Portable default: a lockfile at .git/feature-loop.lock holding PID + timestamp. If it exists, is fresh (< 2h), and its PID is alive → BUSY, exit. Otherwise write it, and delete it on exit.
• ‹orca› additionally: a live feature/<slug> worktree in orca worktree ps also counts as BUSY.

Headless override (applies to every stage)

The stage skills (/grill-with-docs, /to-spec, /to-tickets, /implement) are written for a human and will try to ask the operator questions. There is no operator mid-run. Wherever a sub-skill would consult the human — grill questions, /to-spec confirming seams, /to-tickets quizzing the breakdown — you stand in as the headless answerer:

1. Ground in this order: GOAL.md (the anchor) → ADRs + CONTEXT.md → the codebase. Reason from the goal first.
2. "I don't know, here's my assumption" beats a confident guess. When a question isn't determined by the artifacts, record an explicit assumption with a goal-aligned default and proceed.
3. Escalate only on the irreversible. If an ungroundable choice touches a schema/data migration, a destructive op, or a public/external contract, park the feature and ask (see PARKED). Everything else proceeds.
4. The grill's output is a design record — decisions, assumptions, open questions — that feeds /to-spec.

Step 0 — detect mode, take the lock, read the world

1. Detect the runtime mode (above).
2. Acquire the run-lock. If held → exit immediately, no-op.
3. Read state once:

gh issue list --state open --json number,title,body,labels   # per docs/agents/issue-tracker.md
gh pr list --state open --json number,headRefName,labels
git log -n 10 --oneline

The priority ladder — derive the one current state

Check top-down. First match wins, so exactly one state is selected. The active feature is the set of issues + PR + branch tied to one feature milestone (named <slug>). Candidates are not yet in a milestone — the key is created only when one is picked (DESIGN), so the label namespace never grows.

#	Condition (first match wins)	State → action
0	Run-lock already held (see Step 0)	BUSY → exit, no-op
1	Active feature has an unanswered ready-for-human escalation	PARKED → exit, no-op
2	Open PR exists for the active feature	SHIP → review / merge / retry
3	Open tickets in the active feature milestone remain	BUILD → parallel implement
4	A spec issue exists for the active feature, no tickets yet	SLICE → /to-tickets
5	Feature issue has approved, no spec yet	DESIGN → grill + /to-spec
6	Candidate slate exists (feature-candidate + needs-approval), none approved yet	WAIT → exit, no-op
7	Nothing active and no candidate slate awaiting a pick	GENERATE → propose 3 candidates

Run the matched stage to completion, then exit. (State lives in GitHub, not this process — if a run dies mid-stage, the next invocation re-derives and resumes: e.g. BUILD with 2 of 5 tickets closed re-runs for the remaining 3.)

State playbooks

GENERATE

Read GOAL.md. Derive "done so far" from closed issues + recent commits + ADRs. Propose three distinct feature candidates — genuinely different options (different Pillars or angles, not three flavours of one idea) — each of which moves a Pillar toward the North-star, respects the Non-goals, never proposes anything in the Horizon (not-now) list, and is a single demoable tracer-bullet slice (no epics). Open one GitHub issue per candidate; label each feature-candidate + needs-approval, and record a short kebab slug in the issue body (a Slug: <slug> line). No per-feature label or milestone yet — the correlation key is created only when a candidate is picked (DESIGN), so the label namespace stays fixed.

Then rank the slate and recommend one (as grilling always ships a recommended answer — the operator still decides). Add the recommended label to the top pick and post a ## Feature Loop recommendation comment on each candidate naming the pick (#N), a 2–3 sentence rationale, and the main trade-off. Rank by:

1. North-star + high-pillar alignment.
2. Tracer-bullet foundational value — prefer a slice that lays a seam the others would extend over one that presupposes it.
3. Risk-adjustment (reversibility / blast radius) — down-rank schema/data-migration or wide multi-entity rewrites. Weighs most heavily when few features have merged yet (an unproven pipeline earns trust on safe slices first); relaxes as the track record grows.
4. Demoability.

Exit — the operator picks one by adding approved (usually, not necessarily, the recommended one); that choice is the one human gate.

WAIT / PARKED

No-op and exit. The operator picks one candidate (adds approved) or answers a parked escalation (comment + flip ready-for-human back to approved) on their own time; a later invocation picks it up.

DESIGN

First, clear the slate: close the other open feature-candidate + needs-approval issues (the unpicked candidates) with a brief "not selected this round" comment — regenerable from GOAL.md later.

Read the picked candidate's Slug: <slug> (else derive one from its title). Create the feature milestone <slug> and assign the feature issue to it — this is the correlation key from here on:

gh api repos/{owner}/{repo}/milestones -f title="<slug>" -f description="Feature Loop: <slug>"
gh issue edit <feature#> --milestone "<slug>"

Then run one worker on branch feature/<slug> with the brief: run /grill-with-docs (headless answerer) then /to-spec. Publish the spec as a GitHub issue referencing the feature issue, assigned to milestone <slug> + labelled ready-for-agent, with the design record captured in it. Any ADRs/CONTEXT.md the grill produces are committed on the feature branch. Exit.

SLICE

Run /to-tickets against the spec (headless answerer approves the breakdown). Publish the tickets in dependency order, each assigned to milestone <slug> (gh issue edit <n> --milestone "<slug>") with their Blocked by field populated. Exit.

BUILD

Read the ticket Blocked by DAG. Dispatch every currently-unblocked ticket as a worker (see primitive), each on a branch off the current feature/<slug> tip, brief = run /implement (TDD at agreed seams) for that ticket. Cap concurrency at 3 (‹orca›: --max-concurrent 3; ‹local›: at most 3 sub-agents per wave). As each worker finishes, merge its branch into feature/<slug> (/resolving-merge-conflicts on a conflict, or dispatch a fix worker), close the ticket, and release the next now-unblocked wave. When all tickets in milestone <slug> are closed, exit.

SHIP

Open one PR feature/<slug> → main (gh pr create). Run the merge bar:

• Hard: npm run test green, npm run typecheck clean, lint/build green, and /code-review Spec axis reports no missing/wrong requirement.
• Advisory: /code-review Standards axis (log findings; never blocks).

Bar green → auto-merge (gh pr merge --squash --delete-branch) and close the milestone (gh api repos/{owner}/{repo}/milestones/<number> -X PATCH -f state=closed) so it drops out of the active view. Next invocation GENERATEs the next slate. Bar red → run /implement to fix, up to 3 attempts; still red → park: label the feature ready-for-human, comment the /code-review findings, notify the operator (‹orca› inbox/push, ‹local› the comment is the

---

Content truncated.