feat(tsugu): v1.1 — agent-first revisions (spec 005)#35
Merged
Conversation
… per-ref (spec 005 C2)
…ranch-tsugu, merge method, housekeeping, intake form (spec 005 B/C/D)
…g-keyed run filenames (spec 005 C4 + ripple)
…e arms, completion tail, knowledge/ paths (spec 005 C1/C4)
…ainment check, pending-check symmetry (Task 4 review)
…+location, slug-keyed runs, load rules (spec 005 C2/C3)
…ording (Task 5 review, minor)
…n moment + recorded form, landed:/reconciliation (spec 005 B/C4-C6)
…p-6 condition, sharpen idempotency contract + step-7 path (Task 7 review)
…erge absorbs settle (spec 005 A/C)
…nverge as stale-after recorder, mark policy field list non-exhaustive (Task 8 review)
…#1) Step 2 said 'update Branch Prefixes to the work-only default', overwriting any repo-customized work prefixes — contradicting the migration contract's promise to preserve curated prefix customizations. Now narrows by removing only public/* and keeps configured prefixes; default applies only when never customized. Spec 005 D step 2 amended to match.
…review #2) On a push-protected repo the coordination-ref rename (step 5) is deferred until after the policy PR merges, but the tsugu-schema:2 stamp (step 8) rode that same PR — so an interruption after merge, before the rename, left schema reading 2 with the rename never retried. Now the stamp defers with step 5 into the post-merge commit, never the PR; the schema never reads complete over a half-applied migration. Spec 005 D contract + steps 5/8 amended to match.
…te (Codex review #3) Request-by-branch work is supported without an intake note, but the completion tail unconditionally required flipping one before cleanup — leaving such work unable to complete the prescribed tail. The flip now applies only when a linked intake note exists; note-less request-by-branch work skips it. SKILL.md, git-recipes completion tail, and spec 005 C1/C4 amended to match.
…review #4) The queue-summary lines in SKILL.md and git-recipes treated an open OR claimed note with no linked branch as pick-up work — but a claimed note whose branch vanished is a reconciliation case for the human (spec 005 C4), never auto-resumable by a scheduled prepare. Only open unclaimed notes now enter the auto-queue; orphaned claimed notes stay reconciliation cases. Spec C4 already states this correctly — no spec change needed.
…it with it (Codex review #2 follow-on) The prior fix claimed the schema stamp and the coordination-ref rename share one post-merge commit. But policy.md (stamp) lives on the default branch while a push-protected coordination-ref is often a separate branch — they cannot be one commit. Restated as an ordering invariant: the stamp always rides the policy init/* PR, which merges only after the rename is confirmed on its own ref (same PR when coordination-ref=default; separate coord branch renamed first otherwise). Stamp stays genuinely last, gated on rename completion. Spec 005 D amended.
…for landed: (Codex review #3 follow-on) Making the completion-tail flip conditional left a gap: a forced squash loses containment and must record landed: <sha>, but that SHA lives in the intake note — which note-less request-by-branch work was now skipping, losing the landing record. Refined: note-less work skips the flip only for a containment-derivable landing; a forced-squash landing first materializes a slug-keyed intake note to carry the validated SHA, then flips it. SKILL.md, git-recipes, spec C1/C4.
…t statement (Codex review #2 follow-on round 2) The follow-on fix added the correct ordering invariant but left the earlier clause ('the rename is performed only after the PR merges') intact, creating a circular requirement against the new 'PR merges only after the rename' rule for the separate-coordination-ref case. Reconciled migrations.md, SKILL.md, and spec 005 to one coherent statement: stamp rides the policy PR as the last write; the rename completes first on its ref (same PR when coordination-ref=default, else the separate coord branch is renamed first); readers accept both names meanwhile.
… follow-on round 3) Step 5 in migrations.md and spec 005 still read 'deferred until the policy PR merges' (rename after the PR) — the reversed ordering the contract fix removed. Restated: the rename completes on its ref before the stamp lands (same PR when coordination-ref=default; separate coord branch renamed first otherwise). No 'rename after PR merges' phrasing remains anywhere.
There was a problem hiding this comment.
Pull request overview
This PR ships spec 005’s “agent-first” revisions for the tsugu plugin, restructuring the user-facing command surface and updating the documentation/templates to support derived-state coordination and schema-stamped migrations.
Changes:
- Replaces the single
/tsugurouter with three namespaced commands:/tsugu:init,/tsugu:prepare,/tsugu:converge. - Updates
.tsugu/note model and policy schema: introducestsugu-schema: 2, adds handoff prefixes + public-branch mode, replacesbranch.mdwith per-refcontext.md, and renames.tsugu/context/→.tsugu/knowledge/. - Adds/updates reference docs for migrations, policy/intake semantics, and git recipes to match derived-state lifecycle and completion tail.
Reviewed changes
Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| plugins/tsugu/skills/tsugu/templates/run.md | Updates run-note filename convention to be slug-keyed. |
| plugins/tsugu/skills/tsugu/templates/policy.md | Bumps policy template to schema 2 and adds new policy fields (handoff prefixes, push, public-branch mode, etc.). |
| plugins/tsugu/skills/tsugu/templates/packet.md | Reframes “public branch” into “handoff branch” semantics for converge. |
| plugins/tsugu/skills/tsugu/templates/intake.md | Adds write-once linked-branch clarification and new write-once landed: field semantics. |
| plugins/tsugu/skills/tsugu/templates/context.md | New per-ref narrative context.md template replacing written branch state. |
| plugins/tsugu/skills/tsugu/templates/branch.md | Removes legacy branch.md template (status/claim fields). |
| plugins/tsugu/skills/tsugu/SKILL.md | Updates the skill’s design narrative/rules to the 3-routine, derived-state model and schema migration contract. |
| plugins/tsugu/skills/tsugu/references/policy-and-intake.md | Documents schema stamp, new policy fields, intake-source configuration moment, and landed: reconciliation semantics. |
| plugins/tsugu/skills/tsugu/references/notes-and-packet.md | Replaces branch.md model with per-ref context.md and defines new knowledge/ promotion semantics. |
| plugins/tsugu/skills/tsugu/references/migrations.md | Adds explicit migration contract and detailed schema 1→2 steps. |
| plugins/tsugu/skills/tsugu/references/git-recipes.md | Updates recipes for work/handoff prefixes, derived partitioning, exclude-mode public branch flow, and completion tail. |
| plugins/tsugu/skills/tsugu/README.md | Updates user-facing documentation to the 3-routine surface and derived-state model. |
| plugins/tsugu/commands/tsugu.md | Removes the single /tsugu router command. |
| plugins/tsugu/commands/init.md | Adds /tsugu:init command entrypoint. |
| plugins/tsugu/commands/prepare.md | Adds /tsugu:prepare command entrypoint. |
| plugins/tsugu/commands/converge.md | Adds /tsugu:converge command entrypoint (with optional branch argument). |
| plugins/tsugu/.claude-plugin/plugin.json | Updates plugin metadata/description to reflect 3 routines + derived state. |
| docs/superpowers/specs/005-tsugu-agent-first-design.md | Updates the spec to match the final implementation decisions (completion tail nuances, migration ordering, etc.). |
| CLAUDE.md | Updates repository-level plugin listing/documentation for the new tsugu surface. |
| .claude-plugin/marketplace.json | Bumps marketplace version for tsugu to 0.2.0 and updates description. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…t bracket shorthand (Copilot review) The frontmatter description and routing line used the shorthand '/tsugu [init|prepare|converge]', which implies a bare '/tsugu init' command that no longer exists (the single router was removed). Switched both to the namespaced form, consistent with commands/*.md, README, and CLAUDE.md. The bare '/tsugu' trigger keyword is retained.
…prepare/* (Copilot review) The one-line description hardcoded 'prepare/* branches', but prepare operates over all configured work prefixes (prepare/* investigate/* review/*). Broadened to 'work-prefix branches (prepare/* by default)' to match SKILL.md and git-recipes.
…local-gate follow-on) '(prepare/* by default)' implied prepare/* was the sole default; the default work-prefix set is prepare/* investigate/* review/*. Listed all three.
… review r3) prepare step 1 and converge step 1 wrote 'git fetch --prune' while the prose resolves <remote>; multi-remote repos must fetch the configured remote only (git-recipes already does). Added <remote> to both, matching the resolve rule.
…iew r3) SKILL.md prepare step 8 and the README prepare blurb named only prepare/*, but prepare works across all configured work prefixes. Step 8 now says 'the work branch (<work-prefix>/<slug>)'; the README lists prepare/* investigate/* review/*.
…ot review r3) The boundary line listed 'push' as freely-allowed, reading as a contradiction with the schema-2 push-prepare-branches: knob that can forbid auto-push. Qualified to 'create/commit (push per ## Push)' so the generated policy.md is internally consistent.
…dex local-gate follow-on) Companion fix to the policy.md template: the reference doc's Private-Git-Space description also listed 'push' as unconditional. Qualified to 'push per ## Push's push-prepare-branches:' so template and its docs agree.
…ore checks (Copilot review r4) The exclude-mode settled check used <remote>/<handoff-prefix>/<slug> before slug was derived and required the reader to know which handoff prefix was used — copying it would run an invalid/guessed ref. Restructured: derive slug first, resolve the slug-paired handoff ref by searching the configured handoff prefixes, then both containment checks and the pending test use $branch / $handoff. The exclude check and pending test are guarded on a handoff ref existing.
…red first-match classification (Codex local-gate follow-on) Two issues in the r4 snippet rewrite: (1) the handoff search hardcoded feat|fix|public instead of the configured ## Handoff Prefixes — now filters the $handoff_refs list enumerated in 'Read the queue' step 4; (2) the flat checks could emit both settled and pending for a settled item with a handoff ref — the partition is first-match-wins, so it's now an ordered if/elif/else (settled → pending → in-progress).
…hes slug literally (Codex local-gate follow-on) Three correctness points on the exact-checks snippet: (1) containment now branches on public-branch-tsugu (include → work branch; exclude → handoff branch) instead of ORing both; (2) a validated landed: in the intake note now counts as settled (the forced-squash case), via note_has_valid_landed standing for the documented SHA-resolve+contained check; (3) the slug-paired handoff ref is matched by literal final-path-component comparison (a slug with ./+ would mis-glob under regex), first match wins.
…tself to structural rows (Codex local-gate follow-on) A request-by-branch whose tip equals default satisfies --is-ancestor and would emit settled, contradicting the zero-commit exemption. Added a leading tip==default guard emitting 'exempt'. Also scoped the snippet with a comment: it covers the structural rows (exempt/settled/pending/in-progress); the finer recency, zero-commit claim-recency, and invalid-landed reconciliation rules remain prose applied on top.
| **review-loop:** Assisted, not autonomous, multi-reviewer convergence loop. Local reviewers run first — a Claude subagent always, plus Codex via `codex exec review` (headless) when `codex` is on `PATH`; tmux optional for a live-watch pane — then GitHub Copilot for PR targets. Helper scripts in `skills/review-loop/scripts/` (`copilot.sh`, `pr-comments.sh`) are referenced via `${CLAUDE_PLUGIN_ROOT}`. Target scope is any changed artifact: code or design artifacts (specs, plans, docs). One slash command: `/review-loop [PR# | branch | blank]`. Spec: `docs/superpowers/specs/002-review-loop-plugin-design.md` (Codex channel superseded by `docs/superpowers/specs/003-review-loop-headless-codex-design.md`). | ||
|
|
||
| **tsugu:** Git-native skill for unattended work preparation and human–agent convergence (継ぐ — "to inherit / continue / carry forward"). Using git's DAG as the coordination substrate, an agent prepares engineering work privately on git branches (often while the human is away), records evidence in committed `.tsugu/` notes, and packages a convergence packet; the human then converges (decides together what becomes public) and the work is settled (cut a clean public branch with no `.tsugu/` in the diff / open a PR, human-gated). Four routines: `init` (set up the repo's `.tsugu/` workspace + `policy.md`; idempotent), `prepare` (private git work on `prepare/*` branches + tests + evidence while the human is absent; external silence), `converge` (present packet + branches and decide with the human; invokes no skill — the human triggers skills by keyword), `settle` (accept/reject/pause; promote reusable knowledge to shared context; clean up branches/worktrees). **Never auto-merges** (no public coordination without approval). **Light / script-free** — recipes are documented guidance; no scripts shipped. **Invokes no user-installed skill by default** — native git + its own built-in subagents only; a repo's `.tsugu/policy.md` may opt-in to named skills locally. One slash command: `/tsugu [init|prepare|converge|settle]`. Spec: `docs/superpowers/specs/004-tsugu-skill-design.md`. | ||
| **tsugu:** Git-native skill for unattended work preparation and human–agent convergence (継ぐ — "to inherit / continue / carry forward"). Using git's DAG as the coordination substrate, an agent prepares engineering work privately on git branches (often while the human is away), records evidence in committed `.tsugu/` notes, and packages a convergence packet; the human then converges (decides together what becomes public, completes the landing, and reads the morning status view). Three routines: `init` (set up the repo's `.tsugu/` workspace + `policy.md`; idempotent), `prepare` (private git work on `prepare/*` branches + tests + evidence while the human is absent; external silence), `converge` (decision + completion + morning status view — present packet + branches, decide with the human, accept/reject/park, promote reusable knowledge, clean up; invokes no skill — the human triggers skills by keyword). **State is derived, not stored** — no status fields; a work item is the set of refs sharing one slug (`prepare/<slug>`, `intake/<slug>.md`, handoff branch), and landing is read from the DAG via containment, so **merge commits are recommended**. By default `.tsugu/` MAY land on the mainline (`public-branch-tsugu: include|exclude` in `policy.md`). Per-ref narrative lives in `context.md`; promoted reusable knowledge in `.tsugu/knowledge/`. **Never auto-merges** (no public coordination without approval). **Light / script-free** — recipes are documented guidance; no scripts shipped. **Invokes no user-installed skill by default** — native git + its own built-in subagents only; a repo's `.tsugu/policy.md` may opt-in to named skills locally. Three slash commands: `/tsugu:init|prepare|converge`. Spec: `docs/superpowers/specs/004-tsugu-skill-design.md` + `docs/superpowers/specs/005-tsugu-agent-first-design.md`. |
Owner
Author
| @@ -0,0 +1,15 @@ | |||
| --- | |||
| description: Human-absent preparation — fetch, derive the queue from refs, work privately on the configured work-prefix branches (defaults prepare/* investigate/* review/*), push evidence. External silence | |||
Owner
Author
There was a problem hiding this comment.
Fixed in eaf7ca2 — now 'push evidence when policy permits', reflecting push-prepare-branches:.
…plicitly (Copilot review r5) The tsugu blurb said prepare works on 'prepare/* branches' (it spans the configured work prefixes — defaults prepare/* investigate/* review/*) and used the shorthand /tsugu:init|prepare|converge. Listed the three commands explicitly.
…Copilot review r5) The repo-level README still described the pre-005 surface — four routines incl. settle and /tsugu [init|prepare|converge|settle] — contradicting CLAUDE.md and the plugin docs. Plan 005 updated CLAUDE.md but missed this root README blurb. Rewrote to three routines, namespaced commands, derived state, no settle.
The description said 'push evidence' unconditionally, but push-prepare-branches: no can disable auto-push. Now 'push evidence when policy permits'.
… landing (Codex local-gate follow-on) 'complete the landing in the same session' overstated synchronicity: converge cuts the handoff / opens the PR in-session, but the merge is human-gated and may land later. Reworded to 'complete the disposition ... the merge lands when you approve it'.
…t; read: is an agent-resolved pointer (Copilot review r3 security; user direction)
Tsugu does not auto-execute anything committed in .tsugu/. The intake-source read:
is reframed from an executed shell command into a declarative POINTER (file path /
MCP tool / where-to-look) that the prepare AGENT resolves with its own permissioned,
interceptable tools — eliminating the headless-prepare remote-code-execution vector
(policy.md is repo content). Where a command is genuinely needed, the agent issues
it as its own gated tool call, never an auto-eval of config. Adds the central
no-force principle to the SKILL.md spine ('offers data and trusts the agent') and a
one-line essence ('guides agents to cooperate through git; helps the human come back
to prepared work'). Applied to SKILL.md, policy.md template, policy-and-intake.md,
and spec 005 §B (recorded form + ask-once question).
…curity guarantee (Codex local-gate follow-on) (1) The config-moment ask and recorded-form intros still said 'read instruction'/ 'shell command'; aligned to 'read pointer' so the no-force framing is consistent. (2) The spine claimed .tsugu/ content is 'never a remote-execution vector' — overstated. Agent mediation stops automatic config-as-code execution but the content is still untrusted input that may try to influence the agent; reworded to claim prevention of auto-execution, not elimination of every vector.
…ex local-gate follow-on) Last residual 'read: instruction' wording in migrations.md step 4 and spec 005 D step 4, aligned to 'read: pointer' for consistency with the no-force reframing. (The historical implementation plan keeps the old wording — it's an executed artifact already on main, not part of this branch's surface.)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Ships spec 005 (
docs/superpowers/specs/005-tsugu-agent-first-design.md) — the agent-first revisions to thetsuguplugin — across 20 files. Executed via subagent-driven development (fresh implementer + two-stage review per task), then thereview-looplocal gate (Claude + headless Codex).What changed (lines A–D of spec 005)
/tsugu:tsugurouter becomes three namespaced commands/tsugu:init,/tsugu:prepare,/tsugu:converge;settleis removed as a routine —convergeabsorbs decision and completion in one human-present session.read:/ hint).branch.md→ per-ref pure-narrativecontext.md; slug pairing + containment partition;.tsugu/context/→.tsugu/knowledge/; the completion tail (promote → flip → cleanup);landed:write-once record for forced squashes;public-branch-tsugu: include|exclude.references/migrations.md(new) —tsugu-schemaversion stamp + the schema 1→2 steps, idempotent, stamp written last.plugin.json,marketplace.json(tsugu → 0.2.0), and rootCLAUDE.mdupdated to the three-routine surface.Review
Local gate converged clean (Claude + Codex). Codex surfaced 6 design-edge findings that the per-file reviews couldn't see; all fixed in plugin and spec 005:
landed:.prepareexcludes orphanedclaimednotes (reconciliation cases, not auto-pickup).Spec 005 was amended in lockstep so spec and implementation stay in sync.
Notes
/tsugu:initmigrations available to dogfooding repos.Plan:
docs/superpowers/plans/005-tsugu-agent-first-plan.mdSpec:
docs/superpowers/specs/005-tsugu-agent-first-design.md🤖 Generated with Claude Code