053 — At code level 3 a story is written and built in a worktree of its own (#193)
Roadmap: #193
Why
At level 3 several stories are in flight at once: one being
interviewed, others being built or reviewed by agents. tp idea story
writes the story file into whatever checkout it is run in, and the
branch is then cut by hand, so one checkout is switched from story to
story. An interview of five ideas switched it ten times, each switch a
chance to scaffold on the wrong branch, carry an uncommitted file
across, or cut from a main nobody pulled.
tp wt gives a worktree, but for the flow before the ladder: a
WT-prefixed task branch, and a wt clean that merges locally into
whatever the main checkout has out. At level 3 the branch is
story/<N>-<slug>, cut from the remote base, and the merge is the
forge's. The worktree is the story's, so the story's commands make and
remove it.
What changes
tp idea story N [TITLE]: fetches the release remote, cutsstory/<N>-<slug>from its base branch in a new worktree beside the main checkout,<repo>-<N>-<slug>, and writes the story file there, with the sandbox.claude/settings.jsonthattp wt startwrites. The checkout it is run in is not written to. It prints the story's path.tp story tidy: removes the worktree and the local branch of every story that has landed on the base branch.tp story query: a landed story's tidy step namestp story tidy.tp wt start,reviewandcleanat level 3: refused, namingtp idea storyandtp story tidy.docs/idea.md,docs/story.md,docs/worktrees.md, and the "ready" row ofCLAUDE.md.
Acceptance
maturity.code: 3. The slug is the story file's. "Beside the main
checkout" holds from wherever the command is run, another story's
worktree included.
tp idea story N [TITLE], issue N open and labelled idea or
roadmap:
| Run from | story/<N>-<slug> and <repo>-<N>-<slug> |
Outcome |
|---|---|---|
| the main checkout, on the base branch, clean | neither exists | the worktree made on the branch, cut from the remote base's tip; the story file and the sandbox settings in it; the issue relabelled story; the path printed |
| the main checkout, its base branch behind the remote | neither exists | the same: cut from the remote's tip, the local base not moved |
| a story's worktree, or a tree with uncommitted changes | neither exists | the same; where it was run is as it was |
| any | the branch exists, local or on the remote | error naming it; no worktree, no file, the issue's labels unchanged |
| any | the directory exists | error naming it; the same |
| any | neither exists, the fetch failing | error; the same |
| any | the worktree made, the forge refusing the label | error naming the worktree and the label, as story 043 does the file |
tp story tidy, run in any checkout or worktree of the repository:
| Story's branch | Its worktree | Outcome |
|---|---|---|
| in the remote base | clean | the worktree removed, the local branch deleted; the story named |
| in the remote base | uncommitted or untracked changes | kept, and named with why |
| in the remote base | the one the command is run in | kept, and named with the main checkout to run it from |
| in the remote base | none: a branch in the main checkout, not checked out | the local branch deleted |
| not in the remote base | any | untouched, not named |
| none landed | — | says so |
| Command | Outcome |
|---|---|
tp story query on a landed story |
the tidy step is tp story tidy, run from the main checkout |
tp wt start, review, clean |
error naming tp idea story N and tp story tidy |
tp wt list, agent, dashboard; tp claude |
as today |
any of these at maturity.code 0 or 1 |
as today: tp idea story and tp story tidy are refused, tp wt is as it was |
Out of scope
- Level 1:
tp wtthere is left as it is. - Opening VS Code on the worktree, and
tp wt agentand the dashboard finding a story's worktree: they take aWTtask name still. - Starting a builder in the worktree once the story is defined.
- Adopting a worktree Claude Code made under
.claude/worktrees/. - Story numbers from the issue, the third point of #193: story 051.
- The roadmap line's worktree: story 052, built on this one.
- Removing the remote branch: the forge does, when the pull request merges.
Decisions
None.
Done when
- tests express the acceptance table and pass
- spec updated
- changelog entry
- issue closed with a link to the release