Update Project

Sync an existing project's Specification-First methodology files with the latest plugin version. Preserves user customizations while bringing in methodology improvements.

For v1.x → v2.0 this performs a one-shot structural migration: the flat context.yaml + coding-principles.md move into contexts/default/, and the append-only decisions.md Markdown log splits into per-decision YAML files under decisions/.

When to Use

• The plugin was updated and the project's methodology.version in context.yaml is older
• The user explicitly asks to sync or update the methodology
• New templates or structural changes were introduced in a newer plugin version

How It Works

The plugin's templates carry an inline methodology version (currently 2.8.1). The user's context.yaml has a methodology.version field set during bootstrap. When these differ, this skill helps merge the changes.

Steps

1. Check versions

Read the user's methodology version:

• v2.x project: read .{project}/contexts/<default-or-only>/context.yaml → methodology.version.
• v1.x project: read .{project}/context.yaml (flat) → methodology.version. Missing field = treat as 0.0.0.

Compare with the plugin's current version from .claude-plugin/plugin.json (version field).

If they match, tell the user they're up to date. Done.

2. Pick the migration path

For v1 → v2 run step 3a (the structural migration), step 3c (the 2.1.0 additions), 3d, 3e, 3f, 3g, 3h, 3i, 3j and 3k. For 2.0.x run 3c, 3b, 3d, 3e, 3f, 3g, 3h, 3i, 3j and 3k. For 2.1.x run 3d, 3e, 3f, 3b, 3g, 3h, 3i, 3j and 3k. For 2.2.x run 3e, 3f, 3b, 3g, 3h, 3i, 3j and 3k. For 2.3.x run 3f, 3g, 3h, 3i, 3j and 3k. For 2.4.x run 3g, 3h, 3i, 3j and 3k. For 2.5.x run 3h, 3i, 3j and 3k. For 2.6.x run 3i, 3j and 3k. For 2.7.x run 3j and 3k. For 2.8.0 run 3k. For later 2.x → 2.y skip to step 3b (additive merge). A path through 3g commits, runs the script, shows its report and commits before 3h.

3a. v1 → v2 big-bang migration

The migration is mechanical and structural-only. No content is rewritten — files are MOVED, formats are CONVERTED. Show the operator the full plan before touching anything; require explicit approval.

Confirm with the operator before starting that:

• The repo is committed clean (so git diff shows exactly the migration changes).
• Any in-flight work in phases/active/ is at a safe checkpoint (the migration does not touch spec YAMLs but the operator should know what state they're starting from).

3a.1. Move root context + principles into contexts/default/

.{project}/context.yaml          → .{project}/contexts/default/context.yaml
.{project}/coding-principles.md  → .{project}/contexts/default/coding-principles.md

Use git mv so history is preserved.

Inside the moved context.yaml:

• Update the schema reference: # yaml-language-server: $schema=context.schema.json → # yaml-language-server: $schema=../../context.schema.json.
• Add meta.workdir: "." (single-stack default — the existing project's code lives at the repo root from this context's perspective).
• Bump methodology.version to the plugin's current version (from .claude-plugin/plugin.json).

If a .{project}/context.schema.json exists alongside, leave it at the project root. The relative path adjustment above handles the new depth.

3a.2. Split the decisions.md log into per-spec YAMLs

Read .{project}/decisions.md. The v1 format groups decisions under ## p{NN}: Title headings with - [Category] Decision -- rationale bullets.

One YAML file per spec, all bullets under the heading become entries in that file's decisions: array. NOT one file per bullet.

For each ## p{NN}: Title heading:

• Collect all - [Category] body bullets underneath (until the next heading).
• For each bullet:
  • category = {Category}. Normalise off-canonical labels (Scope already canonical; map Fix/Decision/Note/Quality/Cleanup/Reuse/Safety → Implementation; Flow → Architecture; Configuration → Tooling). Warn on anything else and default to Implementation.
  • Split body at the first — (em-dash) or -- (double-dash with spaces) — left side becomes chose:, right side becomes reason:. If there's no separator, the entire body becomes chose: and reason: is omitted.
  • over: is OMITTED unless the body text clearly names a rejected alternative. No <TBD> placeholders — the schema makes over: optional.

• Emit one file:

  # yaml-language-server: $schema=../decision.schema.json
  spec: p{NN}
  decisions:
    - category: {Category}
      chose: "{...}"
      reason: |
        {...}
    - category: {Category}
      chose: "{...}"
      ...

• File path: .{project}/decisions/p{NN}.yaml. The filename IS the spec ID — no slug, no per-bullet suffix.

Convert any pre-existing .{project}/decisions/*.md files in the same shape: read each, derive the spec ID from its heading (or from the filename prefix as fallback, e.g. p0146d-observation-fields.md → p0146d.yaml), MERGE its bullets into the same spec's YAML if decisions.md also had entries for that spec, otherwise emit a fresh spec YAML. git rm each .md after.

After the split:

• git rm .{project}/decisions.md.
• The big-bang means the Markdown log is gone — every entry now lives in its spec's YAML file.

For a 1000-bullet decisions.md spanning 200 specs, expect ~200 YAML files — one per spec.

3a.3. Add the schemas

Copy templates/decision.schema.json and templates/spec.schema.json from the plugin into .{project}/ if they're missing. Editors pick them up from there.

3a.4. Emit warnings for notes/ and concepts/ directories

If .{project}/notes/ or .{project}/concepts/ exist:

• Do NOT automatically move them. Per operator instruction: these are not decisions — they are the concepts that lead to specs, which only afterwards yield decisions.
• Emit a warning listing every file under those directories and recommend the operator choose, per file:
  • (a) Copy the file out of .{project}/ (e.g. into a docs/notes/ or a separate branch) before continuing — they're conceptual exploration, not part of the spec-first artifact set.
  • (b) Rename to phases/done/p{NN}-base-concept-{topic}.yaml with a reserved ID range the operator picks. The file becomes a "base-concept spec" — documented foundation that was never executed as work but shaped subsequent specs. (phases/ is still the v1 directory here; 3g moves it to specs/.)

The migration does NOT pick one — operator decides per file.

3a.5. Update state.{done,active,planned} entries (optional housekeeping)

The state.{done,active,planned} sections in the moved context.yaml still reference spec YAMLs by path. v1 paths like .{project}/phases/... are left alone here — 3g's script rewrites them to specs/. If the operator wants to add new applies_to: annotations to existing spec YAMLs, that's done lazily as each spec comes back into focus, not as part of this migration.

3b. 2.x → 2.y additive merge

For each methodology file, compare the user's version with the plugin's template:

Present a summary of what's new or changed per file. Be specific: "New field meta.workdir added to context.yaml", not "context.yaml was updated".

3b.1. Propose merge

For each file with changes:

• Additive changes (new fields, new sections): propose adding them while keeping all existing user content intact.
• Modified sections (updated wording, reordered steps): show the diff and let the user choose between old and new.
• Removed sections: flag them but don't auto-delete. The user decides.

Never overwrite user customizations silently. The user's contexts/<name>/context.yaml stack, arch, quality, and state sections are theirs — only touch the methodology-related structure.

3c. 2.1.0 additions: memory store + root CLAUDE.md read order

Two retroactive changes bring pre-2.1.0 projects to parity with fresh bootstraps.

3c.1. Create the memory store (structural-only)

If .{project}/memory/ is missing:

• Create .{project}/memory/ and copy templates/memory/MEMORY.md into it as the empty index.
• Structural-only — no auto-distillation of history. Do NOT convert the project's decisions, git log, or spec records into memory entries as part of this migration. The store opens empty; memories accumulate from future sessions and runs (entry convention: one Markdown file per memory beside the index, frontmatter name kebab-slug / description one line / metadata.type in feedback | project | reference — see templates/memory/example-memory.md), and a feedback entry becomes policy only after operator ratification.

3c.2. Patch the root CLAUDE.md read-order block

A project bootstrapped before 2.1.0 typically still carries the v1 read order in its root CLAUDE.md (flat context.yaml, the retired decisions.md append log, phases/active/*.md). Sessions obey CLAUDE.md first, so they look in the wrong place before recovering — fix it here:

• Locate the context-file read-order block in the project's root CLAUDE.md.
• Replace ONLY that block with the v2 order (as in templates/prompt.md):
  1. glob contexts/*/context.yaml, read down to state:, search state.done instead of reading it
  2. each context's coding-principles.md
  3. specs/active/*.yaml
  4. decisions/*.yaml
  5. memory/MEMORY.md (recall entry detail from memory/<name>.md on demand)
• If CLAUDE.md has no memory/recall discipline section yet, offer to add the one from templates/prompt.md alongside.

Because the root CLAUDE.md lives OUTSIDE the methodology directory, this edit ALWAYS requires explicit operator approval: show the exact before/after diff of the block and apply only after the operator approves. Leave every other section of CLAUDE.md untouched.

3d. 2.2.0: date-minted ids and premise keys in the schemas

Replace the project's copies of the two schemas with the plugin's templates: spec.schema.json (git rm the old phase-spec.schema.json) and decision.schema.json. 2.2.0 accepts date-minted ids (2026-08-24-8a3f, series 2026-08-24-8a3fa) beside every counter id the project already carries, and lets a spec state scope, facts and assumptions. No id is renamed. Root CLAUDE.md: if it tells sessions to mint the next counter id, point it at create-spec's minting rule instead.

3e. 2.3.0: context schema and the loop

Copy templates/context.schema.json into .{project}/ (it is what every context.yaml's $schema comment already points at; its top level is open, so no existing key fails). Offer the commented verify: and evidence_roots: blocks from templates/contexts/default/context.yaml. Root CLAUDE.md: offer the 12-step workflow from templates/prompt.md — a worktree per spec, review-spec before code, deliver-spec at the end — with the same before/after approval as 3c.2. Nothing is renamed.

3f. 2.4.0: execute-phase is apply-spec, ship-phase is deliver-spec

Nothing in the project is renamed. If the root CLAUDE.md or any project document names execute-phase or ship-phase, replace them with apply-spec and deliver-spec. The old skill names answered in 2.4.0 only; 2.5.0 removes them.

3g. 2.5.0: the noun is spec

1. Commit everything — the script refuses a directory with uncommitted or untracked files.

2. Run the script on the project's methodology directory:

   python3 "${CLAUDE_SKILL_DIR}/scripts/migrate-specs-layout.py" .{project}

3. Show the operator its report verbatim — what moved, what was edited, and the files it lists as still naming the old path (the root CLAUDE.md among them); those are the operator's to edit.
4. Commit.

Exit 1 means refused and nothing changed: show the reason. Exit 0 with "nothing to move" means the project is already on specs/.

3h. 2.6.0: create-phase is gone

Nothing in the project is renamed. If the root CLAUDE.md or any project document names create-phase, replace it with create-spec. The old skill name answered in 2.5.0 only; 2.6.0 removes it.

3i. 2.7.0: the plugin gates spec commits

From 2.7.0 the plugin ships a commit gate: a PreToolUse hook that, on every git commit whose message carries ({id}), runs every context's verify: stages from the repository root and blocks the commit on the first red stage. Nothing in the project is renamed. Walk the operator through four checks:

1. Schemas. Copy templates/spec.schema.json and templates/context.schema.json into .{project}/ again. They declare upgrade_impact, proven_live and gate; the old copies refuse those keys.
2. Who owns the gate. Ask whether the project already runs its own commit gate (a PreToolUse hook in .claude/settings.json, or another hook that runs the build and tests at commit). If it does, add gate: project at the top level of ONE contexts/<name>/context.yaml, so the plugin's hook steps aside and only one gate runs. Two contexts with different values block every spec commit. If it does not, nothing to add: the plugin's gate is the default.
3. The verify stages are the full proof. With the plugin's gate, the stages are what runs at every spec commit and nothing else does. Check they cover build and tests; a project with none passes every commit with the notice "no verify stages declared".
4. Root instructions. In AGENTS.md (or CLAUDE.md in a project that has not split yet), offer the new wording of steps 8 and 12 from templates/prompt.md (test what you changed while iterating; the full stages run once, at the spec commit), with the same before/after approval as 3c.2.

The gate needs python3 and PyYAML (as review-spec does). Without PyYAML it lets spec commits through with a notice and deliver-spec runs the stages itself. Its ledger is spec-first-gate.log in the git common directory, so nothing new appears in git status.

3j. 2.8.0: AGENTS.md for every agent, and the gate as a git hook

From 2.8.0 the instructions are agent-neutral and the commit gate can also run as a git commit-msg hook. Both are offers; apply only what the operator approves.

1. Schema. Copy templates/context.schema.json into .{project}/ again; it allows gate: git.
2. AGENTS.md. Offer to move the root CLAUDE.md's project instructions into a new root AGENTS.md based on templates/prompt.md (each step names its plugin command and says how to do it by hand, the review brief included), and to make CLAUDE.md start with @AGENTS.md, keeping only what holds for Claude Code alone. An existing AGENTS.md is merged, never overwritten. Show the before/after of both files and apply after approval, as in 3c.2. From here on, 3b, 3c.2 and 3i's step 4 edit AGENTS.md.
3. gate: git, only if the team uses other agents or commits by hand. Before any context declares it, every teammate must be on plugin 2.8.0 or later: a 2.7.0 plugin reads gate: git as unknown and blocks every spec commit. Then add gate: git to ONE context and run python3 <plugin>/hooks/install-git-hook.py in every clone; re-run it after every plugin upgrade, so the copied gate stays current. The hook needs python3 and PyYAML in each clone and runs on POSIX systems only. Under Claude Code its stages run inside one Bash call, so they must finish in 570 s; a project with a longer suite keeps the plugin's gate. Where a clone has no hook, or a commit uses --no-verify, the plugin's hook still gates Claude Code's commits.
4. Existing commit-msg hooks. The installer refuses to replace a commit-msg hook it did not write (a git-secrets hook from a global git template is common). Merge the two by hand, or leave gate: on the plugin.

3k. 2.8.1: search the spec index, don't read it

A project's state.done grows by one line per spec and at a thousand specs runs to a hundred thousand tokens. From 2.8.1 the read order says to read each context.yaml down to state: and to search state.done for the area at hand. Replace item 1 of the read-order block in the root AGENTS.md, or CLAUDE.md where there is none, with the line from templates/prompt.md. The file lives outside the methodology directory, so show the before/after and apply only after the operator approves, as in 3c.2.

4. Ask approval

Show the complete list of proposed changes and ask the user to approve before writing anything.

5. Apply changes

Write the approved changes. Update methodology.version in every contexts/<name>/context.yaml to match the plugin version.

6. Log the update

Append a decision entry to the spec YAML the project uses for meta updates (or mint a fresh id for the update, as create-spec does, and create decisions/{id}.yaml):

# yaml-language-server: $schema=../decision.schema.json
spec: 2026-08-24-8a3f           # the id you minted, or an existing meta-spec id the project uses

decisions:
  - category: Tooling
    chose: "Updated Spec-First methodology from v{old} to v{new}"
    over: "Staying on v{old}"
    reason: |
      {Summary of key changes: contexts/ layout, YAML decisions, ...}
      Migration mode: {v1-to-v2 big-bang | 2.x additive merge}.

Safety

• Git is your safety net. If something goes wrong, the user can git diff and revert.
• Before the v1 → v2 migration, require the working tree to be clean (or explicitly confirmed otherwise) so the migration's effects are isolated in git diff.
• Use git mv for file moves so history is preserved.
• Never modify files outside the project's methodology directory unless explicitly told to (e.g., updating CLAUDE.md at root).
• Always show diffs before writing.
• Preserve every line of user-written content in contexts/<name>/context.yaml (stack, arch, quality, state sections).
• For the v1 → v2 decisions-log split: when a bullet's body has no obvious over: (rejected alternative), OMIT the over: field. The schema makes it optional — never invent placeholder text.