Skip to content

feat(agents): enforce worktree-per-ticket in /implement's first step - #222

Merged
jinyeow merged 5 commits into
mainfrom
feat/221-implement-enforces-worktree-per-ticket
Sep 3, 2026
Merged

feat(agents): enforce worktree-per-ticket in /implement's first step#222
jinyeow merged 5 commits into
mainfrom
feat/221-implement-enforces-worktree-per-ticket

Conversation

@jinyeow

@jinyeow jinyeow commented Sep 2, 2026

Copy link
Copy Markdown
Owner

Problem

AGENTS.d/git-worktrees.md documents the bare-worktree layout's core rule: a new branch means
a new worktree, never git checkout -b inside the default-branch worktree. The rule was
advisory only, so nothing stopped /implement from running directly on main.

Solution

/implement's own first step now detects the repo's default branch (never hardcoded, so it
still works on a repo whose default isn't main) and, if the current branch is the default
branch, branches off automatically before doing anything else: git worktree add in the
bare-worktree layout, git checkout -b in a normal clone. No hook, no marker file, no new
state, just plain skill-instruction text.

dispatch-implement's dispatch step now branches off once, before dispatching any child
(parallel or sequential), whenever the invoking session itself starts on the default branch.
Otherwise /implement's new check would spawn one throwaway worktree per ticket, and the
integration step would cherry-pick every child's commits back onto the default branch.

Full rationale and rejected alternatives (a PreToolUse hook + marker file, a hard-blocking
hook, confirm-before-create) are recorded in
docs/adr/implement-enforces-worktree-per-ticket-in-its-own-first-step.md.

Review

Reviewed with quick-review (Fable folded reviewer plus Codex on gpt-5.6-sol); all 7
findings raised were fixed: a bare-worktree-detection bug (git worktree list always shows
the current worktree, so the original check misclassified every normal clone), an
EnterWorktree scoping gap for pinned subagents, an explicit stop-and-ask fallback for Codex
CLI/Pi's unverified cd persistence, multi-ticket branch naming for dispatch-implement, and
three documentation-quality fixes.

Fixes #221

…QR221-01, #QR221-02, #QR221-03]

- ai-agents/skills/implement/SKILL.md: bare-worktree detection now requires more than one
  git worktree list entry, not just the current worktree showing (always true)
- ai-agents/skills/implement/SKILL.md: scope the EnterWorktree path claim to the main
  session's own launch directory; add the pinned-subagent fallback (stop and hand back, or
  EnterWorktree name:)
- ai-agents/skills/implement/SKILL.md: add an explicit stop-and-ask fallback when Codex
  CLI/Pi cd persistence can't be confirmed and no runtime primitive exists

Refs: AB#221
…tch [#QR221-04]

- ai-agents/skills/dispatch-implement/SKILL.md: step 5's parent branch-off now names the
  branch explicitly for a multi-ticket run (epic/spec slug when shared, else the first
  ticket listed) instead of relying on /implement's single-ticket naming rule

Refs: AB#221
- docs/adr/implement-enforces-worktree-per-ticket-in-its-own-first-step.md: reword the
  title and three body instances of 'X, not Y' phrasing to state the positive directly,
  per AGENTS.md; leave the Rejected alternatives section's contrast untouched
- align the title's wording with the filename ('worktree-per-ticket')

Refs: AB#221
… reference [#QR221-06, #QR221-07]

- ai-agents/skills/dispatch-implement/SKILL.md: step 5's branch-off paragraph now states
  the instruction plus one why-sentence, with a resolvable pointer to the ADR instead of
  restating its rejected-alternative rationale inline
- ai-agents/skills/dispatch-implement/SKILL.md: step 6 drops the changelog-style 'same as
  before this ADR' phrasing (unlinked, references history rather than current state)

Refs: AB#221
…mplement enforcement

- ai-agents/AGENTS.d/git-worktrees.md: don't hardcode the default branch name; note that
  /implement's first step now enforces the branch-per-ticket rule automatically

Refs: AB#221
@jinyeow jinyeow changed the title fix(implement): correct worktree-detection and cd-persistence gaps [#QR221-01, #QR221-02, #QR221-03] feat(agents): enforce worktree-per-ticket in /implement's first step Sep 2, 2026
@jinyeow
jinyeow merged commit aafbd5f into main Sep 3, 2026
5 checks passed
@jinyeow
jinyeow deleted the feat/221-implement-enforces-worktree-per-ticket branch September 3, 2026 23:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Enforce worktree-per-ticket in /implement's own first step

1 participant