feat(tsugu): schema 3 — the workspace holds only what transfers#37
Merged
Conversation
…d, drop intake/run Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…single-layer state, personal config
…ersonal config, drop intake machinery
…ledge/, packet goes personal
…otstrap, drop intake writes/landed
…ke/runs/packets/templates, stamp schema 3)
…trap, live converge Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replace schema-2 description (intake, runs/, landed:, convergence packet committed) with schema-3 model: committed .tsugu/ = policy.md + context.md + knowledge/ only; personal folder (~/.claude/tsugu/<key>/) holds observation sources, opt-in skills, and derived packet; single-layer state; spec pointer now includes 006. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…t version The "Multi-agent: reserved" section used v1/v2 for the multi-agent arbitration roadmap, which now collides with this release being "tsugu v2 (schema 3)". Reword to "today" / "a future multi-agent iteration" so the roadmap axis is not confused with the schema/product version. (Carry-over from the T2 SKILL.md review.) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… mode (review P1) Codex's branch review found the settlement gap was wider than the spec framed it: in exclude mode the work branch is NEVER contained in default (accepted code lands by path on a separate public branch), so settlement depends entirely on the slug-paired public branch surviving — and a forge auto-deleting it on a NORMAL merge would make landed work look in-progress, repeatable by a scheduled prepare. The narrative backstop was written only for the forced-squash case. Generalize both SKILL.md and git-recipes: the retain-handoff recommendation + context.md narrative backstop now cover BOTH non-contained-work-tip cases — a forced squash AND every exclude-mode landing. The exclude-mode converge disposition now writes the "handed off — may have landed" narrative and keeps the public branch alive until the completion tail. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…e guarantee (review P2) Two contradictions Codex flagged in SKILL.md: - prepare says "invokes no user-installed skill" while the personal config has an opt-in skills list — state the prohibition as default-only with the opt-in list as the explicit exception, at the point of prohibition. - converge step 3 regenerates the personal packet (a write) but the next paragraph guaranteed steps 1-3 are "read-only / side effects begin only at step 4". Narrow "read-only" to mean no git/shared-state changes; the personal packet is a derived ephemeral view, not a shared side effect. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…is spec" (review T1) migrations.md now ships under spec 006's deliverable, so "this spec's layout" for schema 2 read wrong (schema 2 = spec 005; 006 is schema 3). Name spec 005 explicitly. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…waiting merge" (review round 2) Codex round 2 caught that the exclude-mode generalization over-stated the shared behavior: it said BOTH the forced-squash and exclude-mode cases "stay decided, awaiting merge". Wrong for exclude mode — a normally merged public branch IS contained in default, so partition row 1 classifies it SETTLED. The two cases share only that the work branch's OWN tip is never contained (so disposition reads off the slug-paired ref); they DIFFER in outcome: exclude mode settles once the public tip is contained, while a forced squash stays pending and re-surfaces until the human confirms. The shared failure mode (ref auto-deleted → in-progress → retain-handoff + narrative backstop) is unchanged. Reword SKILL.md + git-recipes to draw the distinction. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…aiting-merge" (review round 3) Last stale phrasing from the exclude-mode generalization: the retain-handoff bullet said the surviving ref "carries the awaiting-merge state". For a normally merged exclude-mode public branch it carries SETTLED evidence (public tip contained), not awaiting-merge. Reword to "preserves the disposition evidence" covering both (settled-via-public-tip in exclude mode, awaiting-merge in the squash case). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…s a squash (review round 4) The completion tail runs for ALL landings (normal include/exclude merges too), but SKILL.md and git-recipes called the durable artifact "the squash commit." Only a forced squash produces one. Reword to "the landed commits on the default branch — the merge in a normal landing, or the squash commit where a squash was forced." Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the tsugu plugin to schema 3 (“the workspace holds only what transfers”), collapsing committed .tsugu/ into a shared WIP-knowledge layer (policy.md, context.md, knowledge/) and moving all per-human/per-machine configuration and derived views to a global personal folder (~/.claude/tsugu/<project-key>/).
Changes:
- Removes the committed intake/runs/packet machinery and repo-seeded templates; shifts to a single-layer “branches only” queue model.
- Introduces personal (never-committed) config (
config.md) and defines personal packet storage/regeneration behavior. - Updates tsugu’s SKILL/README/references/migration docs and marketplace metadata for schema 3 and the 2→3 migration.
Reviewed changes
Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| plugins/tsugu/skills/tsugu/templates/run.md | Removes the run-note template (runs/ no longer exists in schema 3). |
| plugins/tsugu/skills/tsugu/templates/policy.md | Updates policy template to tsugu-schema: 3 and schema-3 semantics. |
| plugins/tsugu/skills/tsugu/templates/packet.md | Marks packet as personal/derived and never committed. |
| plugins/tsugu/skills/tsugu/templates/intake.md | Removes the intake-note template (intake/ no longer exists in schema 3). |
| plugins/tsugu/skills/tsugu/templates/context.md | Removes links to per-session/per-slug committed artifacts (runs/packets). |
| plugins/tsugu/skills/tsugu/templates/config.md | Adds a personal config template for sources + opt-in skills (never committed). |
| plugins/tsugu/skills/tsugu/SKILL.md | Rewrites the skill’s “spine” and lifecycle docs for schema 3 behavior. |
| plugins/tsugu/skills/tsugu/references/policy-and-intake.md | Reframes policy as shared-only; documents personal config and bootstrap. |
| plugins/tsugu/skills/tsugu/references/notes-and-packet.md | Updates note model to only committed context.md + knowledge/, plus personal packet. |
| plugins/tsugu/skills/tsugu/references/migrations.md | Adds the 2→3 migration procedure and clarifies sequential 1→2→3. |
| plugins/tsugu/skills/tsugu/references/git-recipes.md | Updates recipes for single-layer queue, knowledge promotion, and personal-folder usage. |
| plugins/tsugu/skills/tsugu/README.md | Updates user-facing overview to schema 3 and the personal-folder split. |
| plugins/tsugu/commands/prepare.md | Updates prepare command invariants for schema 3 + personal config bootstrap. |
| plugins/tsugu/commands/init.md | Updates init command description/invariants for 1→2→3 and schema-3 workspace shape. |
| plugins/tsugu/commands/converge.md | Updates converge command invariants: live branch reads + personal derived packet. |
| plugins/tsugu/.claude-plugin/plugin.json | Updates plugin description to schema 3 semantics. |
| CLAUDE.md | Updates repository-level tsugu summary to schema 3. |
| .claude-plugin/marketplace.json | Bumps tsugu version to 0.3.0 and updates marketplace description. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…icy.md (Copilot review)
…default/exception contradiction (Copilot review)
…ontext.md, not just policy.md (Copilot review)
…it-dir across all docs (Copilot review)
…plugin dropped (Copilot review) Copilot caught that migration 1→2 step 6 refreshes .tsugu/templates/ (incl. intake.md, schema-1 branch.md) "from the plugin", but the shipped schema-3 plugin no longer ships those templates (they were deleted), so a literal 1→2→3 path for a schema-1 repo references templates that don't exist. Fix: 1→2 step 6 now notes the schema-2-only templates (branch.md/intake.md/run.md) aren't shipped under schema 3 — refresh only what the current plugin provides, skip the rest. The 1→2→3 note now says to apply only the DURABLE 1→2 changes (context/→knowledge rename, surviving policy fields, mainline context.md) and skip the transient intake/runs/templates scaffolding that 2→3 deletes anyway, so the combined path never depends on an unshipped template. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…nly filesystem scaffolding (Codex review) Codex caught that the previous "skip the transient scaffolding" shortcut was too broad: it would also skip migration 1→2 step 4 (re-wrap ## Intake Sources into the structured name/read/notes form). But 2→3 step 1 relocates those entries verbatim into the personal config.md, which REQUIRES that structure — skipping step 4 would copy unstructured legacy entries and leave the migrated sources unusable. Refine the 1→2→3 note into an explicit Apply/Skip split: Apply the durable changes PLUS step 4's intake-source rewrapping (required by 2→3); Skip only the filesystem scaffolding (intake//runs/ dirs, templates/ seeding, the unshipped branch.md/intake.md/run.md templates). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…2→3 (Codex review) The explicit Apply list omitted 1→2 step 8 — stamping tsugu-schema: 2 — which the N→N+1 contract requires before 2→3 begins. State it: 1→2 completes with the schema-2 stamp, then 2→3 runs and stamps schema 3 last. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Implements spec 006 (
docs/superpowers/specs/006-tsugu-workspace-transfer-design.md) and plan 006 (docs/superpowers/plans/006-tsugu-workspace-transfer.md). Closes #36.What changes
Committed
.tsugu/collapses to a WIP-knowledge layer — a richer sibling ofAGENTS.md/CLAUDE.md:Everything tied to one human's session, sources, or rhythm moves to a per-machine personal global folder
~/.claude/tsugu/<project-key>/(config.mdfor observation sources + opt-in skills;packets/for the converge decision-view). Nothing personal touches the repo — the split is enforced by where the file lives, not agent judgment.Removed: the entire intake-note machinery (
intake/,runs/,landed:, theopen→claimed→donelifecycle, reconciliation, repo-seededtemplates/). State is now single-layer — work branches only; settled = containment, pending = a slug-paired handoff branch.Redefined, not dropped:
public-branch-tsugunow governs whether the committed WIP-knowledge layer (prep DAG +context.md) lands on the public branch;knowledge/lands on the coordination ref in both modes.Settlement without
landed:: a non-containment-preserving landing (forced squash) re-surfaces live at eachconvergeuntil the human drops both branches — held visible by the retained handoff branch, with acontext.mdnarrative backstop. Generalized in review to cover everyexclude-mode landing (the work branch is never contained there).Migration
tsugu-schema: 3with a documented 2→3 migration (relocate personal sections to the global folder;git rm --ignore-unmatchthe removed paths, history left intact; redefinepublic-branch-tsugu; stamp last). 1→2 kept, so schema-1 repos run 1→2→3.How it was built
Subagent-driven execution (fresh implementer per task) + a Claude + Codex local review gate over the whole branch. The combined gate caught a real settlement gap the per-file passes missed (exclude-mode work branches are never contained → depend on the public branch surviving); 5 Codex convergence rounds drove it to clean.
metadata.versionleft at 1.4.0 (no plugin set change); tsugu bumped 0.2.0 → 0.3.0.🤖 Generated with Claude Code