---

description: Drive a feature end-to-end from a GitHub issue ID or description — resolve the issue, branch an isolated git worktree off origin/main, research and clarify inside it, implement, open a PR argument-hint: <issue-number | issue-url | feature description>

/feature — issue to PR, end to end

Input: $ARGUMENTS — either a GitHub issue reference (123, #123, or an issue URL) or a free-text feature description. If empty, ask the user what to build before doing anything else.

Operating principles

• Worktree isolation. All implementation happens in a dedicated git worktree under .claude/worktrees/, branched from origin/main (phase 3). The shared checkout is never switched or dirtied, so multiple /feature sessions can run concurrently.
• Stay lean. You are the orchestrator: hold decisions, plans, and diffs under review — not file contents. Delegate reading, exploring, and code-writing to subagents (Agent tool). Do not pull whole source files into your own context when a subagent summary will do.
• But read the seams yourself. Lean is not blind. Before fanning out, read the few files that define the contract the agents will share: the composition root they all merge into, the base type they derive from, the file whose conventions they must match. Skip it and each agent invents its own answer to the same question, with the integration pass paying for all of them.
• Read by reading list, never end-to-end. The two biggest module docs — docs/app/design-system.md and docs/app/keyboard-editor.md, ~1 200 dense lines each — are tens of thousands of tokens apiece, so a fan-out where every agent opens both spends more on paging docs than on writing the feature. Phase 4 therefore produces a reading list of path:startLine-endLine ranges, and every agent — implementers and reviewers alike — reads those ranges, via Read's offset/limit. Reading either doc end to end is a defect, not diligence: CLAUDE.md's "read design-system.md before writing any view or style" means the sections that govern your view, and the reading list is what names them.
• Contracts live in the repo, not in prompts. When more than two agents work on one subsystem, have the first agent commit the shared convention as an artifact — a base type, a header comment, a doc section — and tell the rest to read it. Pasting a convention into N prompts guarantees drift: the copies go stale as the work teaches you things, and later agents get instructions the code has outgrown.
• Name the traps, not the principle. Agents working in parallel make the same mistake in parallel. A principle ("make state precedence explicit") produced an identical defect in four files at once; the enumerated list of qualifiers that actually recur would have prevented all four. Spell out the failure modes you know as a checklist — a principle is what you write when you don't yet know them.
• Settle mechanically what a command can settle. Findings — from a review agent, an implementer's self-check, or your own reading — fall in two classes. Mechanical: a grep, a build or one filtered test settles it outright ("names a token that isn't defined", "calls a method that doesn't exist"). Judgment: no command decides it ("breaks the design law that absent features aren't rendered", "leaves the profile half-saved"). Run the command for the first class; spend agents only on the second. This holds in both modes — it is what the standard path's review agent should do, and what gates the ultracode verifier fan-out in phase 6. The guard against dressing a judgment finding as a mechanical one: you must be able to state, before running the check, which output means confirmed and which means refuted; if you cannot, it is a judgment finding. A check that comes back confirming also skips the fan-out and goes straight to the fix list — a definitive answer needs no second opinion either.
• One PR is one reviewable change. Generation time scales with the size of the diff; verification does not — a build and a test run cost a fraction of writing the code. A feature that runs for hours is almost always one scoped too large, not one checked too thoroughly; the longest here landed a hundred-plus files at once. Size is the decision with the hours riding on it, and phase 4 is where it gets made, before any code exists.
• Docs before source. This repo is documented agent-first: subagents read docs/app/ (and specs/ for domain questions) before opening source files — through the reading list, per above.
• Documentation is part of the feature, not an afterthought. Per CLAUDE.md, every change ships with its documentation: the module's agent-first doc in docs/app/ (create it if the module is new), CLAUDE.md (new modules, changed commands), README.md when user-facing behavior changes. A feature without its doc updates is incomplete and must not reach the PR phase.
• Unit tests are part of the feature, not an afterthought. Per CLAUDE.md's testing rules, every change ships with unit tests for the behavior it adds and maintains the tests of the code it touches. The full suite must pass before the PR phase.
• Ultracode. If a system-reminder says ultracode is enabled for this session, orchestrate research and implementation with the Workflow tool as described in phase 6. Otherwise use individual subagents and skip the heavy machinery.

Phase 1 — Sync

git fetch --prune origin. Do not check out or pull main, and do not require a clean shared checkout — the shared checkout is never touched; the feature branches from origin/main inside its own worktree in phase 3. Independent of phase 2: issue both in one batch.

Phase 2 — Resolve the input, and get an issue number

You need an issue number N before phase 3, because the branch and worktree are named for it.

• Issue reference → gh issue view <n> --json number,title,body,labels. Its content is the starting spec. Add ,comments only when resuming a prior run on this issue — phase 5 posts full specs as comments, so a re-fetch otherwise drags every earlier spec back into context. If the lookup fails, tell the user and ask whether the input was meant as a description instead.
• Free text → create the issue now, with the user's description as the body and a title you propose: gh issue create --title "…" --body "…". Capture the new number. The refined spec is posted as a comment in phase 5, exactly as for an issue that already existed — creating it early costs nothing and is what lets research run against a current tree.

Phase 3 — Worktree

Before research, not after. The shared checkout is routinely several merges behind origin/main, and research against a stale tree is worse than none: subagents cannot tell a stale tree from a current one, so they report confidently either way and the errors surface only at integration. Two research passes have already been thrown away to this, having proposed rebuilding things that already existed on main.

1. Determine the primary checkout's root: the first worktree line of git worktree list --porcelain. Do not use --show-toplevel — the session may already be inside another worktree.
2. Create the worktree and its branch from origin/main: git worktree add "<root>/.claude/worktrees/feature-N-short-slug" -b feature/N-short-slug origin/main If the branch or worktree already exists (a previous run for the same issue), don't fight it: ask the user whether to resume in the existing worktree as-is or delete and recreate it.
3. Switch the session into it: EnterWorktree with path: "<root>/.claude/worktrees/feature-N-short-slug". Every subsequent phase — researching, implementing, testing, committing, pushing — runs inside the worktree.

Phase 4 — Research and clarify

Runs inside the worktree from phase 3, so every agent reads the tree the feature will actually be built on. Re-fetch before each new wave of agents; the repo can move under you mid-feature.

1. Delegate codebase research to an Explore agent: which modules/files the feature touches, existing patterns to follow, relevant constraints from specs/. Point it at docs/app/README.md first — it routes a question to the right module doc, which is cheaper than searching for it. You receive a summary, not file dumps. Tell agents to locate code by symbol name, not line number.
2. Have that agent finish with the reading list the previous principle describes: for each implementer, the docs/app/ and specs/ ranges it actually needs, as path:startLine-endLine (it has grep -n '^#' for free — headings alone are not enough, because an agent handed a heading opens the file to find it). The research agent pays the paging cost once and hands down pointers.
3. Ask the user clarifying questions with AskUserQuestion — one batched call, max 4 questions, and only questions whose answers change the implementation (scope, behavior, UX trade-offs). Skip entirely if the issue is unambiguous.
4. Write a short spec: problem, approach, acceptance criteria, affected modules, required unit tests (what new behavior gets tested, which existing tests need updating), the screens whose rendered frames phase 7 will check — name them now, or the visual gate arrives with nothing planned for it — and required doc updates. Per CLAUDE.md's documentation rules that is the module's own docs/app/ doc; a new module also needs its row in docs/app/README.md. CLAUDE.md and README are touched only for genuinely repo-wide changes, never to describe what the feature does.
5. Write the spec and the reading list to a file; give agents the path, not the text. Pasting them into N prompts and re-pasting on every fix round costs more each round than the file did once, and the copies drift as the work teaches you things. Put it outside the worktree (the session scratchpad is the obvious home): phase 6 runs git add -A, which would otherwise stage your working notes into the feature's diff. The durable copy is the phase-5 issue comment.
6. Size the spec before committing to it. Estimate the files it implies. Past the point where one reviewer could hold the whole change in their head — a couple of dozen files is a fair rule of thumb — stop and put a split to the user: independently shippable issues in dependency order, with your recommendation for what lands first. Here it costs one message; at phase 7 the diff is already too big to review and every remaining option is bad.

Phase 5 — Record the spec on the issue

Post the refined spec as a comment on issue N (gh issue comment <n> --body …) — for an issue that already existed and for one you created in phase 2 alike. Use gh issue edit only if the body is empty or wrong (typically the stub you just wrote).

If phase 4 ended in a split, this is where the follow-up issues get created, and the worktree from phase 3 continues with whichever piece lands first.

Phase 6 — Implement

Standard mode: delegate to one or more general-purpose agents. Give each the path to the phase-4 spec file and its own reading-list ranges. Their instructions must include: follow docs/guides/Coding Conventions.md, keep classes small (SOLID), write unit tests for everything they implement and maintain the existing tests they touch, and update docs/app/, CLAUDE.md, and README as part of the change.

Review by stat, not by bulk. git add -A first so newly created files count, then read git diff HEAD --stat. That, plus each agent's acceptance-criteria self-check below, tells you where to look; pull a file's full text only when the stat, a self-check or a review agent gives you a reason to. Reading a feature-sized diff in full spends the orchestrator's context on what it least needs verbatim, surfaces nothing a review agent reading the same diff would miss, and makes you pay again on every iteration. This does not contradict read the seams: