diff --git a/.claude/commands/specsync/audit.md b/.claude/commands/specsync/audit.md index a8f516f6..c4c9c6c5 100644 --- a/.claude/commands/specsync/audit.md +++ b/.claude/commands/specsync/audit.md @@ -5,5 +5,5 @@ description: Audit active SpecSync change workspaces and living specs (not archi Audit active SpecSync change workspaces and living specs. 1. Run `specsync change audit`. -2. Report active-workspace and living-spec issues only. Archives are history — do not re-validate every archived CHG's terminal evidence. +2. Report active-workspace and living-spec issues only. Archives are history: do not re-validate every archived change's terminal evidence. 3. Use this for "is the SDD workspace healthy?" not "did my feature tests pass?" (that is `change check` / `/specsync:check`). diff --git a/.claude/commands/specsync/check.md b/.claude/commands/specsync/check.md index d13b14dc..b9c4bf24 100644 --- a/.claude/commands/specsync/check.md +++ b/.claude/commands/specsync/check.md @@ -7,7 +7,7 @@ Run scoped SpecSync change verification. Arguments: `$ARGUMENTS` -1. Prefer `specsync change check $ARGUMENTS` when an id or partial id is provided; otherwise run `specsync change check`. -2. Expect **scoped** verification only — this change's materialization and in-process spec↔code sync. Do not run a full archive integrity walk. -3. Stream/wait for exit. On success, follow the printed **Next:** action (review, PR, or finalize path). +1. Prefer `specsync change check $ARGUMENTS` when an id or partial id is provided; otherwise run `specsync change check`. For ship-ready product-tip evidence, include `--commit`. +2. Expect **scoped** verification only: this change's materialization and in-process spec↔code sync. Do not run a full archive integrity walk. +3. Stream/wait for exit. On success, follow the printed **Next:** action (review, PR, or ship/finalize path). 4. Do **not** run `specsync change audit` unless the user asked for project health over active workspaces and living specs. diff --git a/.claude/commands/specsync/create-change.md b/.claude/commands/specsync/create-change.md index b4e8b028..0d1686ac 100644 --- a/.claude/commands/specsync/create-change.md +++ b/.claude/commands/specsync/create-change.md @@ -3,9 +3,10 @@ description: Create and guide a verified spec-sync SDD change through its determ argument-hint: --- -1. Run `specsync change new "$ARGUMENTS" --json`. -2. Read the returned `questions` array and interview the user one question at a time. -3. Record each answer with `specsync change answer "" --json`. -4. Continue until the question list is empty, then show the selected artifacts and next action. -5. Do not approve, implement, verify, accept, or archive until the corresponding human gate or work stage is reached. -6. After implementation, run scoped verification with `specsync change check ` (or `/specsync:check`). Use `specsync change audit` only for active-workspace project health — never expect check to rewalk archived terminal evidence. +1. SDD is opt-in via `specsync change adopt`. If change commands fail because the workflow is off, adopt only when the user asked to turn SDD on. +2. Run `specsync change new "$ARGUMENTS" --json`. +3. Read the returned `questions` array and interview the user one question at a time. +4. Record each answer with `specsync change answer "" --json`. +5. Continue until the question list is empty, then show the selected artifacts and next action. +6. Do not run `specsync change approve --actor ""`, implement, `specsync change check --commit`, `specsync change review --reviewer ""`, or `specsync change ship`/`finalize` until that gate is reached. Do not use v1 `start`/`verify`/`accept`/`archive` as the happy path. +7. After implementation, run `specsync change check --commit` (or the installed check command with --commit when preparing ship evidence). Use `specsync change audit` only for active-workspace project health. Never expect check to rewalk archived terminal evidence. diff --git a/.claude/skills/spec-sync/SKILL.md b/.claude/skills/spec-sync/SKILL.md index fe205f95..356fb27e 100644 --- a/.claude/skills/spec-sync/SKILL.md +++ b/.claude/skills/spec-sync/SKILL.md @@ -1,24 +1,32 @@ --- name: spec-sync -description: Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation. +description: Keep markdown module specs in specs// synchronized with source code using specsync check (the product). Use this whenever creating, editing, or reviewing a spec or its source, or when the user mentions spec-sync, SDD, change adopt, companion files, or the 6.0 change lifecycle (approve, check --commit, review, ship). --- # Spec-Sync Workflow This project uses [spec-sync](https://github.com/CorvidLabs/spec-sync) for bidirectional spec-to-code validation. Specs live in `specs//.spec.md`. -## Companion files +`specsync check` is the product. Bidirectional spec-to-code validation does not require an +active change. SDD (`specsync change`) is opt-in: `specsync init` writes it off; +`specsync change adopt` turns it on. ## Verified change lifecycle (6.0) -For every meaningful source, test, public documentation, schema, or configuration change: +Happy path verbs: `change new` -> `answer` -> `approve --actor` -> implement -> +`check --commit` -> `review --reviewer` -> `ship`/`finalize`. `start` / `verify` / +`accept` / `archive` are v1 recovery, not the happy path. Change ids are slugs, not +`CHG-NNNN`. + +When SDD is adopted and the work is a meaningful source, test, public documentation, +schema, or configuration change: 1. Run `specsync change new "" --json` and conduct the returned interview with the user. 2. Use `specsync change answer "" --json` until no questions remain. 3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable `REQ--` IDs, a normative SHALL statement, and acceptance criteria. -4. Ask the user for the single scope approval, then run `specsync change approve `. -5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check []` +4. Ask the user for the single scope approval, then run `specsync change approve --actor ""`. +5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check [] --commit` for **scoped** verification of this change only (materialize deltas + spec↔code sync). Do **not** treat check as a full archive integrity walk. Use `specsync change audit` when you need project health over **active** workspaces and living specs. Archives are history. @@ -26,15 +34,16 @@ For every meaningful source, test, public documentation, schema, or configuratio change package, implementation diff, canonical spec delta, and targeted evidence once, then record it with `specsync change review --reviewer ""`. The reviewer MAY be the same person who approved the definition. Do not invent a second identity for solo work. -7. Run `specsync change finalize ` to create the same-PR metadata/archive-only commit, then - merge through GitHub. SpecSync does not merge the pull request. +7. Run `specsync change ship ` (or `finalize`) for the same-PR archive tip. Do not commit + between review and ship. Merge on GitHub. SpecSync does not merge the pull request. ## Lifecycle verbs -- `specsync change check [id]` — verify **this** change (materialize + spec↔code sync). Default daily path. -- `specsync change audit` — project health over **active** workspaces and living specs. Not archive history. -- Archives are history; do not re-validate terminal evidence for every archived CHG on each check. -- Slash commands: `/specsync:check`, `/specsync:audit` (Claude/Cursor/Gemini via `specsync agents install`). +- `specsync check` - validate all specs against source. Default daily path. No change required. +- `specsync change check [id]` - verify **this** change (materialize + spec↔code sync). Add `--commit` for ship-ready product-tip evidence. +- `specsync change audit` - project health over **active** workspaces and living specs. Not archive history. +- Archives are history; do not re-validate terminal evidence for every archived change on each check. +- Slash commands after `specsync agents install`: Claude and Gemini use `/specsync:create-spec`, `/specsync:create-change`, `/specsync:check`, `/specsync:audit`. Cursor uses the flat names `/specsync-create-spec`, `/specsync-create-change`, `/specsync-check`, `/specsync-audit`. Never invent or self-grant the scope approval. If an approved definition changes, its digest becomes stale and must be approved again. `specsync change status` always @@ -45,11 +54,11 @@ evidence, but new changes use this single workflow. Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: -- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. -- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. -- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. -- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. -- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. +- **`tasks.md`** - Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** - Acceptance criteria and user stories. These are permanent invariants, not tasks: do not check them off. Update if requirements change. +- **`context.md`** - Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** - Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* - Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. ## Before modifying any module @@ -59,35 +68,44 @@ Each canonical spec may have policy-selected companion files. Read and update th ## After completing work -1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered -2. Update `context.md` — record decisions made, update current status +1. Mark completed items in `tasks.md`: check off finished tasks, add new ones discovered +2. Update `context.md`: record decisions made, update current status 3. If requirements changed, update `requirements.md` acceptance criteria 4. If test coverage changed, update `testing.md` with new test files or edge cases 5. If UI/layout changed, update `design.md` with revised layout, components, or tokens ## Before creating a PR -Run `specsync check --strict` — all specs must pass with zero warnings. +Run `specsync check --strict`: all specs must pass with zero warnings. If SDD is adopted, push +the product tip from `change check --commit` with the PR. Record `change review` and +`change ship`/`finalize` only after that tip is on the PR and required checks have run. Do not +record review or ship before the PR exists. ## When adding new modules Run `specsync scaffold ` to create a spec, companion files, a registry -entry, and auto-detected source files — or `specsync new ` for a +entry, and auto-detected source files, or `specsync new ` for a minimal spec-only draft. Complete the spec before writing code. The `/specsync:create-spec` command (or tool-equivalent) runs this for you, and accepts either a bare module name or a natural-language feature description (e.g. `/specsync:create-spec "I want a feature that lets users export their -data as CSV"`) — pass a description and it will pick a module name and use +data as CSV"`): pass a description and it will pick a module name and use the description to draft the spec's Purpose and Requirements. ## Key commands -- `specsync check` — validate all specs against source code -- `specsync check --json` — machine-readable validation output -- `specsync change check [id]` — scoped verification for one SDD change -- `specsync change audit` — active workspaces + living specs (not archive history) -- `specsync coverage` — show which modules lack specs -- `specsync score` — quality score for each spec (0-100) -- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection -- `specsync new ` — quick-create a minimal spec (add `--full` for companions) -- `specsync resolve --remote` — verify cross-project dependencies +- `specsync check` - validate all specs against source code +- `specsync check --json` - machine-readable validation output +- `specsync change adopt` - turn on the opt-in verified change workflow +- `specsync change new ""` / `change answer` - open a change and finish the interview +- `specsync change approve --actor ""` - record the single scope approval +- `specsync change check [id]` - scoped verification for one SDD change (`--commit` for ship evidence) +- `specsync change review --reviewer ""` - record scoped implementation review +- `specsync change ship ` / `change finalize` - same-PR archive tip; do not commit between review and ship +- `specsync change status [id]` - one next action and a `Handoff:` line +- `specsync change audit` - active workspaces + living specs (not archive history) +- `specsync coverage` - show which modules lack specs +- `specsync score` - quality score for each spec (0-100) +- `specsync scaffold ` - full scaffold: spec + companions + registry entry + source detection +- `specsync new ` - quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` - verify cross-project dependencies diff --git a/.codex/skills/spec-sync/SKILL.md b/.codex/skills/spec-sync/SKILL.md index fe205f95..356fb27e 100644 --- a/.codex/skills/spec-sync/SKILL.md +++ b/.codex/skills/spec-sync/SKILL.md @@ -1,24 +1,32 @@ --- name: spec-sync -description: Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation. +description: Keep markdown module specs in specs// synchronized with source code using specsync check (the product). Use this whenever creating, editing, or reviewing a spec or its source, or when the user mentions spec-sync, SDD, change adopt, companion files, or the 6.0 change lifecycle (approve, check --commit, review, ship). --- # Spec-Sync Workflow This project uses [spec-sync](https://github.com/CorvidLabs/spec-sync) for bidirectional spec-to-code validation. Specs live in `specs//.spec.md`. -## Companion files +`specsync check` is the product. Bidirectional spec-to-code validation does not require an +active change. SDD (`specsync change`) is opt-in: `specsync init` writes it off; +`specsync change adopt` turns it on. ## Verified change lifecycle (6.0) -For every meaningful source, test, public documentation, schema, or configuration change: +Happy path verbs: `change new` -> `answer` -> `approve --actor` -> implement -> +`check --commit` -> `review --reviewer` -> `ship`/`finalize`. `start` / `verify` / +`accept` / `archive` are v1 recovery, not the happy path. Change ids are slugs, not +`CHG-NNNN`. + +When SDD is adopted and the work is a meaningful source, test, public documentation, +schema, or configuration change: 1. Run `specsync change new "" --json` and conduct the returned interview with the user. 2. Use `specsync change answer "" --json` until no questions remain. 3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable `REQ--` IDs, a normative SHALL statement, and acceptance criteria. -4. Ask the user for the single scope approval, then run `specsync change approve `. -5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check []` +4. Ask the user for the single scope approval, then run `specsync change approve --actor ""`. +5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check [] --commit` for **scoped** verification of this change only (materialize deltas + spec↔code sync). Do **not** treat check as a full archive integrity walk. Use `specsync change audit` when you need project health over **active** workspaces and living specs. Archives are history. @@ -26,15 +34,16 @@ For every meaningful source, test, public documentation, schema, or configuratio change package, implementation diff, canonical spec delta, and targeted evidence once, then record it with `specsync change review --reviewer ""`. The reviewer MAY be the same person who approved the definition. Do not invent a second identity for solo work. -7. Run `specsync change finalize ` to create the same-PR metadata/archive-only commit, then - merge through GitHub. SpecSync does not merge the pull request. +7. Run `specsync change ship ` (or `finalize`) for the same-PR archive tip. Do not commit + between review and ship. Merge on GitHub. SpecSync does not merge the pull request. ## Lifecycle verbs -- `specsync change check [id]` — verify **this** change (materialize + spec↔code sync). Default daily path. -- `specsync change audit` — project health over **active** workspaces and living specs. Not archive history. -- Archives are history; do not re-validate terminal evidence for every archived CHG on each check. -- Slash commands: `/specsync:check`, `/specsync:audit` (Claude/Cursor/Gemini via `specsync agents install`). +- `specsync check` - validate all specs against source. Default daily path. No change required. +- `specsync change check [id]` - verify **this** change (materialize + spec↔code sync). Add `--commit` for ship-ready product-tip evidence. +- `specsync change audit` - project health over **active** workspaces and living specs. Not archive history. +- Archives are history; do not re-validate terminal evidence for every archived change on each check. +- Slash commands after `specsync agents install`: Claude and Gemini use `/specsync:create-spec`, `/specsync:create-change`, `/specsync:check`, `/specsync:audit`. Cursor uses the flat names `/specsync-create-spec`, `/specsync-create-change`, `/specsync-check`, `/specsync-audit`. Never invent or self-grant the scope approval. If an approved definition changes, its digest becomes stale and must be approved again. `specsync change status` always @@ -45,11 +54,11 @@ evidence, but new changes use this single workflow. Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: -- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. -- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. -- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. -- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. -- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. +- **`tasks.md`** - Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** - Acceptance criteria and user stories. These are permanent invariants, not tasks: do not check them off. Update if requirements change. +- **`context.md`** - Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** - Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* - Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. ## Before modifying any module @@ -59,35 +68,44 @@ Each canonical spec may have policy-selected companion files. Read and update th ## After completing work -1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered -2. Update `context.md` — record decisions made, update current status +1. Mark completed items in `tasks.md`: check off finished tasks, add new ones discovered +2. Update `context.md`: record decisions made, update current status 3. If requirements changed, update `requirements.md` acceptance criteria 4. If test coverage changed, update `testing.md` with new test files or edge cases 5. If UI/layout changed, update `design.md` with revised layout, components, or tokens ## Before creating a PR -Run `specsync check --strict` — all specs must pass with zero warnings. +Run `specsync check --strict`: all specs must pass with zero warnings. If SDD is adopted, push +the product tip from `change check --commit` with the PR. Record `change review` and +`change ship`/`finalize` only after that tip is on the PR and required checks have run. Do not +record review or ship before the PR exists. ## When adding new modules Run `specsync scaffold ` to create a spec, companion files, a registry -entry, and auto-detected source files — or `specsync new ` for a +entry, and auto-detected source files, or `specsync new ` for a minimal spec-only draft. Complete the spec before writing code. The `/specsync:create-spec` command (or tool-equivalent) runs this for you, and accepts either a bare module name or a natural-language feature description (e.g. `/specsync:create-spec "I want a feature that lets users export their -data as CSV"`) — pass a description and it will pick a module name and use +data as CSV"`): pass a description and it will pick a module name and use the description to draft the spec's Purpose and Requirements. ## Key commands -- `specsync check` — validate all specs against source code -- `specsync check --json` — machine-readable validation output -- `specsync change check [id]` — scoped verification for one SDD change -- `specsync change audit` — active workspaces + living specs (not archive history) -- `specsync coverage` — show which modules lack specs -- `specsync score` — quality score for each spec (0-100) -- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection -- `specsync new ` — quick-create a minimal spec (add `--full` for companions) -- `specsync resolve --remote` — verify cross-project dependencies +- `specsync check` - validate all specs against source code +- `specsync check --json` - machine-readable validation output +- `specsync change adopt` - turn on the opt-in verified change workflow +- `specsync change new ""` / `change answer` - open a change and finish the interview +- `specsync change approve --actor ""` - record the single scope approval +- `specsync change check [id]` - scoped verification for one SDD change (`--commit` for ship evidence) +- `specsync change review --reviewer ""` - record scoped implementation review +- `specsync change ship ` / `change finalize` - same-PR archive tip; do not commit between review and ship +- `specsync change status [id]` - one next action and a `Handoff:` line +- `specsync change audit` - active workspaces + living specs (not archive history) +- `specsync coverage` - show which modules lack specs +- `specsync score` - quality score for each spec (0-100) +- `specsync scaffold ` - full scaffold: spec + companions + registry entry + source detection +- `specsync new ` - quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` - verify cross-project dependencies diff --git a/.cursor/commands/specsync-audit.md b/.cursor/commands/specsync-audit.md index 7ea2fc4e..a4d67f7a 100644 --- a/.cursor/commands/specsync-audit.md +++ b/.cursor/commands/specsync-audit.md @@ -1,5 +1,5 @@ Audit active SpecSync change workspaces and living specs. 1. Run `specsync change audit`. -2. Report active-workspace and living-spec issues only. Archives are history — do not re-validate every archived CHG's terminal evidence. +2. Report active-workspace and living-spec issues only. Archives are history: do not re-validate every archived change's terminal evidence. 3. Use this for "is the SDD workspace healthy?" not "did my feature tests pass?" (that is `change check` / `/specsync:check`). diff --git a/.cursor/commands/specsync-check.md b/.cursor/commands/specsync-check.md index 4b12629b..e9d7cb40 100644 --- a/.cursor/commands/specsync-check.md +++ b/.cursor/commands/specsync-check.md @@ -2,7 +2,7 @@ Run scoped SpecSync change verification. Arguments: $ARGUMENTS -1. Prefer `specsync change check $ARGUMENTS` when an id or partial id is provided; otherwise run `specsync change check`. -2. Expect **scoped** verification only — this change's materialization and in-process spec↔code sync. Do not run a full archive integrity walk. -3. Stream/wait for exit. On success, follow the printed **Next:** action (review, PR, or finalize path). +1. Prefer `specsync change check $ARGUMENTS` when an id or partial id is provided; otherwise run `specsync change check`. For ship-ready product-tip evidence, include `--commit`. +2. Expect **scoped** verification only: this change's materialization and in-process spec↔code sync. Do not run a full archive integrity walk. +3. Stream/wait for exit. On success, follow the printed **Next:** action (review, PR, or ship/finalize path). 4. Do **not** run `specsync change audit` unless the user asked for project health over active workspaces and living specs. diff --git a/.cursor/commands/specsync-create-change.md b/.cursor/commands/specsync-create-change.md index 923abd29..f0d9a5c8 100644 --- a/.cursor/commands/specsync-create-change.md +++ b/.cursor/commands/specsync-create-change.md @@ -2,9 +2,10 @@ Create a verified spec-sync SDD change. Arguments: $ARGUMENTS -1. Run `specsync change new "$ARGUMENTS" --json`. -2. Read the returned `questions` array and interview the user one question at a time. -3. Record each answer with `specsync change answer "" --json`. -4. Continue until the question list is empty, then show the selected artifacts and next action. -5. Do not approve, implement, verify, accept, or archive until the corresponding human gate or work stage is reached. -6. After implementation, run scoped verification with `specsync change check ` (or `/specsync:check`). Use `specsync change audit` only for active-workspace project health — never expect check to rewalk archived terminal evidence. +1. SDD is opt-in via `specsync change adopt`. If change commands fail because the workflow is off, adopt only when the user asked to turn SDD on. +2. Run `specsync change new "$ARGUMENTS" --json`. +3. Read the returned `questions` array and interview the user one question at a time. +4. Record each answer with `specsync change answer "" --json`. +5. Continue until the question list is empty, then show the selected artifacts and next action. +6. Do not run `specsync change approve --actor ""`, implement, `specsync change check --commit`, `specsync change review --reviewer ""`, or `specsync change ship`/`finalize` until that gate is reached. Do not use v1 `start`/`verify`/`accept`/`archive` as the happy path. +7. After implementation, run `specsync change check --commit` (or the installed check command with --commit when preparing ship evidence). Use `specsync change audit` only for active-workspace project health. Never expect check to rewalk archived terminal evidence. diff --git a/.cursor/skills/spec-sync/SKILL.md b/.cursor/skills/spec-sync/SKILL.md index fe205f95..356fb27e 100644 --- a/.cursor/skills/spec-sync/SKILL.md +++ b/.cursor/skills/spec-sync/SKILL.md @@ -1,24 +1,32 @@ --- name: spec-sync -description: Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation. +description: Keep markdown module specs in specs// synchronized with source code using specsync check (the product). Use this whenever creating, editing, or reviewing a spec or its source, or when the user mentions spec-sync, SDD, change adopt, companion files, or the 6.0 change lifecycle (approve, check --commit, review, ship). --- # Spec-Sync Workflow This project uses [spec-sync](https://github.com/CorvidLabs/spec-sync) for bidirectional spec-to-code validation. Specs live in `specs//.spec.md`. -## Companion files +`specsync check` is the product. Bidirectional spec-to-code validation does not require an +active change. SDD (`specsync change`) is opt-in: `specsync init` writes it off; +`specsync change adopt` turns it on. ## Verified change lifecycle (6.0) -For every meaningful source, test, public documentation, schema, or configuration change: +Happy path verbs: `change new` -> `answer` -> `approve --actor` -> implement -> +`check --commit` -> `review --reviewer` -> `ship`/`finalize`. `start` / `verify` / +`accept` / `archive` are v1 recovery, not the happy path. Change ids are slugs, not +`CHG-NNNN`. + +When SDD is adopted and the work is a meaningful source, test, public documentation, +schema, or configuration change: 1. Run `specsync change new "" --json` and conduct the returned interview with the user. 2. Use `specsync change answer "" --json` until no questions remain. 3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable `REQ--` IDs, a normative SHALL statement, and acceptance criteria. -4. Ask the user for the single scope approval, then run `specsync change approve `. -5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check []` +4. Ask the user for the single scope approval, then run `specsync change approve --actor ""`. +5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check [] --commit` for **scoped** verification of this change only (materialize deltas + spec↔code sync). Do **not** treat check as a full archive integrity walk. Use `specsync change audit` when you need project health over **active** workspaces and living specs. Archives are history. @@ -26,15 +34,16 @@ For every meaningful source, test, public documentation, schema, or configuratio change package, implementation diff, canonical spec delta, and targeted evidence once, then record it with `specsync change review --reviewer ""`. The reviewer MAY be the same person who approved the definition. Do not invent a second identity for solo work. -7. Run `specsync change finalize ` to create the same-PR metadata/archive-only commit, then - merge through GitHub. SpecSync does not merge the pull request. +7. Run `specsync change ship ` (or `finalize`) for the same-PR archive tip. Do not commit + between review and ship. Merge on GitHub. SpecSync does not merge the pull request. ## Lifecycle verbs -- `specsync change check [id]` — verify **this** change (materialize + spec↔code sync). Default daily path. -- `specsync change audit` — project health over **active** workspaces and living specs. Not archive history. -- Archives are history; do not re-validate terminal evidence for every archived CHG on each check. -- Slash commands: `/specsync:check`, `/specsync:audit` (Claude/Cursor/Gemini via `specsync agents install`). +- `specsync check` - validate all specs against source. Default daily path. No change required. +- `specsync change check [id]` - verify **this** change (materialize + spec↔code sync). Add `--commit` for ship-ready product-tip evidence. +- `specsync change audit` - project health over **active** workspaces and living specs. Not archive history. +- Archives are history; do not re-validate terminal evidence for every archived change on each check. +- Slash commands after `specsync agents install`: Claude and Gemini use `/specsync:create-spec`, `/specsync:create-change`, `/specsync:check`, `/specsync:audit`. Cursor uses the flat names `/specsync-create-spec`, `/specsync-create-change`, `/specsync-check`, `/specsync-audit`. Never invent or self-grant the scope approval. If an approved definition changes, its digest becomes stale and must be approved again. `specsync change status` always @@ -45,11 +54,11 @@ evidence, but new changes use this single workflow. Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: -- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. -- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. -- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. -- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. -- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. +- **`tasks.md`** - Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** - Acceptance criteria and user stories. These are permanent invariants, not tasks: do not check them off. Update if requirements change. +- **`context.md`** - Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** - Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* - Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. ## Before modifying any module @@ -59,35 +68,44 @@ Each canonical spec may have policy-selected companion files. Read and update th ## After completing work -1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered -2. Update `context.md` — record decisions made, update current status +1. Mark completed items in `tasks.md`: check off finished tasks, add new ones discovered +2. Update `context.md`: record decisions made, update current status 3. If requirements changed, update `requirements.md` acceptance criteria 4. If test coverage changed, update `testing.md` with new test files or edge cases 5. If UI/layout changed, update `design.md` with revised layout, components, or tokens ## Before creating a PR -Run `specsync check --strict` — all specs must pass with zero warnings. +Run `specsync check --strict`: all specs must pass with zero warnings. If SDD is adopted, push +the product tip from `change check --commit` with the PR. Record `change review` and +`change ship`/`finalize` only after that tip is on the PR and required checks have run. Do not +record review or ship before the PR exists. ## When adding new modules Run `specsync scaffold ` to create a spec, companion files, a registry -entry, and auto-detected source files — or `specsync new ` for a +entry, and auto-detected source files, or `specsync new ` for a minimal spec-only draft. Complete the spec before writing code. The `/specsync:create-spec` command (or tool-equivalent) runs this for you, and accepts either a bare module name or a natural-language feature description (e.g. `/specsync:create-spec "I want a feature that lets users export their -data as CSV"`) — pass a description and it will pick a module name and use +data as CSV"`): pass a description and it will pick a module name and use the description to draft the spec's Purpose and Requirements. ## Key commands -- `specsync check` — validate all specs against source code -- `specsync check --json` — machine-readable validation output -- `specsync change check [id]` — scoped verification for one SDD change -- `specsync change audit` — active workspaces + living specs (not archive history) -- `specsync coverage` — show which modules lack specs -- `specsync score` — quality score for each spec (0-100) -- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection -- `specsync new ` — quick-create a minimal spec (add `--full` for companions) -- `specsync resolve --remote` — verify cross-project dependencies +- `specsync check` - validate all specs against source code +- `specsync check --json` - machine-readable validation output +- `specsync change adopt` - turn on the opt-in verified change workflow +- `specsync change new ""` / `change answer` - open a change and finish the interview +- `specsync change approve --actor ""` - record the single scope approval +- `specsync change check [id]` - scoped verification for one SDD change (`--commit` for ship evidence) +- `specsync change review --reviewer ""` - record scoped implementation review +- `specsync change ship ` / `change finalize` - same-PR archive tip; do not commit between review and ship +- `specsync change status [id]` - one next action and a `Handoff:` line +- `specsync change audit` - active workspaces + living specs (not archive history) +- `specsync coverage` - show which modules lack specs +- `specsync score` - quality score for each spec (0-100) +- `specsync scaffold ` - full scaffold: spec + companions + registry entry + source detection +- `specsync new ` - quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` - verify cross-project dependencies diff --git a/.gemini/commands/specsync/audit.toml b/.gemini/commands/specsync/audit.toml index b2aa57a6..d73caf0b 100644 --- a/.gemini/commands/specsync/audit.toml +++ b/.gemini/commands/specsync/audit.toml @@ -4,6 +4,6 @@ prompt = """ Audit active SpecSync change workspaces and living specs. 1. Run `specsync change audit`. -2. Report active-workspace and living-spec issues only. Archives are history — do not re-validate every archived CHG's terminal evidence. +2. Report active-workspace and living-spec issues only. Archives are history: do not re-validate every archived change's terminal evidence. 3. Use this for "is the SDD workspace healthy?" not "did my feature tests pass?" (that is `change check` / `/specsync:check`). """ diff --git a/.gemini/commands/specsync/check.toml b/.gemini/commands/specsync/check.toml index 442cfe4c..e1a49558 100644 --- a/.gemini/commands/specsync/check.toml +++ b/.gemini/commands/specsync/check.toml @@ -5,8 +5,8 @@ Run scoped SpecSync change verification. Arguments: {{args}} -1. Prefer `specsync change check {{args}}` when an id or partial id is provided; otherwise run `specsync change check`. -2. Expect **scoped** verification only — this change's materialization and in-process spec↔code sync. Do not run a full archive integrity walk. -3. Stream/wait for exit. On success, follow the printed **Next:** action (review, PR, or finalize path). +1. Prefer `specsync change check {{args}}` when an id or partial id is provided; otherwise run `specsync change check`. For ship-ready product-tip evidence, include `--commit`. +2. Expect **scoped** verification only: this change's materialization and in-process spec↔code sync. Do not run a full archive integrity walk. +3. Stream/wait for exit. On success, follow the printed **Next:** action (review, PR, or ship/finalize path). 4. Do **not** run `specsync change audit` unless the user asked for project health over active workspaces and living specs. """ diff --git a/.gemini/commands/specsync/create-change.toml b/.gemini/commands/specsync/create-change.toml index eb6d279f..707b5178 100644 --- a/.gemini/commands/specsync/create-change.toml +++ b/.gemini/commands/specsync/create-change.toml @@ -3,10 +3,11 @@ description = "Create and guide a verified spec-sync SDD change through its dete prompt = """ Arguments: {{args}} -1. Run `specsync change new "{{args}}" --json`. -2. Read the returned `questions` array and interview the user one question at a time. -3. Record each answer with `specsync change answer "" --json`. -4. Continue until the question list is empty, then show the selected artifacts and next action. -5. Do not approve, implement, verify, accept, or archive until the corresponding human gate or work stage is reached. -6. After implementation, run scoped verification with `specsync change check ` (or `/specsync:check`). Use `specsync change audit` only for active-workspace project health — never expect check to rewalk archived terminal evidence. +1. SDD is opt-in via `specsync change adopt`. If change commands fail because the workflow is off, adopt only when the user asked to turn SDD on. +2. Run `specsync change new "{{args}}" --json`. +3. Read the returned `questions` array and interview the user one question at a time. +4. Record each answer with `specsync change answer "" --json`. +5. Continue until the question list is empty, then show the selected artifacts and next action. +6. Do not run `specsync change approve --actor ""`, implement, `specsync change check --commit`, `specsync change review --reviewer ""`, or `specsync change ship`/`finalize` until that gate is reached. Do not use v1 `start`/`verify`/`accept`/`archive` as the happy path. +7. After implementation, run `specsync change check --commit` (or the installed check command with --commit when preparing ship evidence). Use `specsync change audit` only for active-workspace project health. Never expect check to rewalk archived terminal evidence. """ diff --git a/.gemini/skills/spec-sync/SKILL.md b/.gemini/skills/spec-sync/SKILL.md index fe205f95..356fb27e 100644 --- a/.gemini/skills/spec-sync/SKILL.md +++ b/.gemini/skills/spec-sync/SKILL.md @@ -1,24 +1,32 @@ --- name: spec-sync -description: Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation. +description: Keep markdown module specs in specs// synchronized with source code using specsync check (the product). Use this whenever creating, editing, or reviewing a spec or its source, or when the user mentions spec-sync, SDD, change adopt, companion files, or the 6.0 change lifecycle (approve, check --commit, review, ship). --- # Spec-Sync Workflow This project uses [spec-sync](https://github.com/CorvidLabs/spec-sync) for bidirectional spec-to-code validation. Specs live in `specs//.spec.md`. -## Companion files +`specsync check` is the product. Bidirectional spec-to-code validation does not require an +active change. SDD (`specsync change`) is opt-in: `specsync init` writes it off; +`specsync change adopt` turns it on. ## Verified change lifecycle (6.0) -For every meaningful source, test, public documentation, schema, or configuration change: +Happy path verbs: `change new` -> `answer` -> `approve --actor` -> implement -> +`check --commit` -> `review --reviewer` -> `ship`/`finalize`. `start` / `verify` / +`accept` / `archive` are v1 recovery, not the happy path. Change ids are slugs, not +`CHG-NNNN`. + +When SDD is adopted and the work is a meaningful source, test, public documentation, +schema, or configuration change: 1. Run `specsync change new "" --json` and conduct the returned interview with the user. 2. Use `specsync change answer "" --json` until no questions remain. 3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable `REQ--` IDs, a normative SHALL statement, and acceptance criteria. -4. Ask the user for the single scope approval, then run `specsync change approve `. -5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check []` +4. Ask the user for the single scope approval, then run `specsync change approve --actor ""`. +5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check [] --commit` for **scoped** verification of this change only (materialize deltas + spec↔code sync). Do **not** treat check as a full archive integrity walk. Use `specsync change audit` when you need project health over **active** workspaces and living specs. Archives are history. @@ -26,15 +34,16 @@ For every meaningful source, test, public documentation, schema, or configuratio change package, implementation diff, canonical spec delta, and targeted evidence once, then record it with `specsync change review --reviewer ""`. The reviewer MAY be the same person who approved the definition. Do not invent a second identity for solo work. -7. Run `specsync change finalize ` to create the same-PR metadata/archive-only commit, then - merge through GitHub. SpecSync does not merge the pull request. +7. Run `specsync change ship ` (or `finalize`) for the same-PR archive tip. Do not commit + between review and ship. Merge on GitHub. SpecSync does not merge the pull request. ## Lifecycle verbs -- `specsync change check [id]` — verify **this** change (materialize + spec↔code sync). Default daily path. -- `specsync change audit` — project health over **active** workspaces and living specs. Not archive history. -- Archives are history; do not re-validate terminal evidence for every archived CHG on each check. -- Slash commands: `/specsync:check`, `/specsync:audit` (Claude/Cursor/Gemini via `specsync agents install`). +- `specsync check` - validate all specs against source. Default daily path. No change required. +- `specsync change check [id]` - verify **this** change (materialize + spec↔code sync). Add `--commit` for ship-ready product-tip evidence. +- `specsync change audit` - project health over **active** workspaces and living specs. Not archive history. +- Archives are history; do not re-validate terminal evidence for every archived change on each check. +- Slash commands after `specsync agents install`: Claude and Gemini use `/specsync:create-spec`, `/specsync:create-change`, `/specsync:check`, `/specsync:audit`. Cursor uses the flat names `/specsync-create-spec`, `/specsync-create-change`, `/specsync-check`, `/specsync-audit`. Never invent or self-grant the scope approval. If an approved definition changes, its digest becomes stale and must be approved again. `specsync change status` always @@ -45,11 +54,11 @@ evidence, but new changes use this single workflow. Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: -- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. -- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. -- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. -- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. -- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. +- **`tasks.md`** - Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** - Acceptance criteria and user stories. These are permanent invariants, not tasks: do not check them off. Update if requirements change. +- **`context.md`** - Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** - Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* - Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. ## Before modifying any module @@ -59,35 +68,44 @@ Each canonical spec may have policy-selected companion files. Read and update th ## After completing work -1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered -2. Update `context.md` — record decisions made, update current status +1. Mark completed items in `tasks.md`: check off finished tasks, add new ones discovered +2. Update `context.md`: record decisions made, update current status 3. If requirements changed, update `requirements.md` acceptance criteria 4. If test coverage changed, update `testing.md` with new test files or edge cases 5. If UI/layout changed, update `design.md` with revised layout, components, or tokens ## Before creating a PR -Run `specsync check --strict` — all specs must pass with zero warnings. +Run `specsync check --strict`: all specs must pass with zero warnings. If SDD is adopted, push +the product tip from `change check --commit` with the PR. Record `change review` and +`change ship`/`finalize` only after that tip is on the PR and required checks have run. Do not +record review or ship before the PR exists. ## When adding new modules Run `specsync scaffold ` to create a spec, companion files, a registry -entry, and auto-detected source files — or `specsync new ` for a +entry, and auto-detected source files, or `specsync new ` for a minimal spec-only draft. Complete the spec before writing code. The `/specsync:create-spec` command (or tool-equivalent) runs this for you, and accepts either a bare module name or a natural-language feature description (e.g. `/specsync:create-spec "I want a feature that lets users export their -data as CSV"`) — pass a description and it will pick a module name and use +data as CSV"`): pass a description and it will pick a module name and use the description to draft the spec's Purpose and Requirements. ## Key commands -- `specsync check` — validate all specs against source code -- `specsync check --json` — machine-readable validation output -- `specsync change check [id]` — scoped verification for one SDD change -- `specsync change audit` — active workspaces + living specs (not archive history) -- `specsync coverage` — show which modules lack specs -- `specsync score` — quality score for each spec (0-100) -- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection -- `specsync new ` — quick-create a minimal spec (add `--full` for companions) -- `specsync resolve --remote` — verify cross-project dependencies +- `specsync check` - validate all specs against source code +- `specsync check --json` - machine-readable validation output +- `specsync change adopt` - turn on the opt-in verified change workflow +- `specsync change new ""` / `change answer` - open a change and finish the interview +- `specsync change approve --actor ""` - record the single scope approval +- `specsync change check [id]` - scoped verification for one SDD change (`--commit` for ship evidence) +- `specsync change review --reviewer ""` - record scoped implementation review +- `specsync change ship ` / `change finalize` - same-PR archive tip; do not commit between review and ship +- `specsync change status [id]` - one next action and a `Handoff:` line +- `specsync change audit` - active workspaces + living specs (not archive history) +- `specsync coverage` - show which modules lack specs +- `specsync score` - quality score for each spec (0-100) +- `specsync scaffold ` - full scaffold: spec + companions + registry entry + source detection +- `specsync new ` - quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` - verify cross-project dependencies diff --git a/.specsync/agent-artifacts.json b/.specsync/agent-artifacts.json index d4574457..7bc49f1b 100644 --- a/.specsync/agent-artifacts.json +++ b/.specsync/agent-artifacts.json @@ -3,83 +3,83 @@ "artifacts": { ".claude/commands/specsync/audit.md": { "tool": "claude", - "template_version": 4, - "digest": "6d8662ba5837b27234cf116b612a0262f1c68c5a8a46f1cd04d32347c02d86ed" + "template_version": 5, + "digest": "90f09855129f006a9a9e1413a175d1a85034c0e11cb22b293ae3dc8e664adbaa" }, ".claude/commands/specsync/check.md": { "tool": "claude", - "template_version": 4, - "digest": "d702ffea18c2a51bb3ccc3c2228691df8190b4aeab728b949b938df377146536" + "template_version": 5, + "digest": "becd0e524cf267d999227ca241844805f75154ed7b1c600a6e4df38202d7bebe" }, ".claude/commands/specsync/create-change.md": { "tool": "claude", - "template_version": 4, - "digest": "826e4f473728c8c6f680455b580a9937189370132b0299fccaf10a4a7390d2e3" + "template_version": 5, + "digest": "292bb4c773ccbec62f5ff01000bf9a723664b3906e2b870882e4b528f6a618dd" }, ".claude/commands/specsync/create-spec.md": { "tool": "claude", - "template_version": 4, + "template_version": 5, "digest": "b1bff9be92176be0d8ad24d09fdf5ef2a9494f1c2b0f19b2161d739e55cca948" }, ".claude/skills/spec-sync/SKILL.md": { "tool": "claude", - "template_version": 4, - "digest": "605bb5e15a39e406e00bf3276afe7bcef56bf55b16e8399cb23a7c9264fa7d05" + "template_version": 5, + "digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a" }, ".codex/skills/spec-sync/SKILL.md": { "tool": "codex", - "template_version": 4, - "digest": "605bb5e15a39e406e00bf3276afe7bcef56bf55b16e8399cb23a7c9264fa7d05" + "template_version": 5, + "digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a" }, ".cursor/commands/specsync-audit.md": { "tool": "cursor", - "template_version": 4, - "digest": "f985b018f264a57bdc2c116c40515cc7e39e773d24011b4c3b274739a0655b27" + "template_version": 5, + "digest": "c34e6379fa03b4d82b9fb6ab0261657c6f225967e00f186f97c650f6f9bc9157" }, ".cursor/commands/specsync-check.md": { "tool": "cursor", - "template_version": 4, - "digest": "65d7ca5c8408f2b6035fa048313560cbb289bd16930cf13795ff252a09bbf3c6" + "template_version": 5, + "digest": "665cad000436c972f6bd61e73894e87eb3f68850e1da077869751a8c359b98a3" }, ".cursor/commands/specsync-create-change.md": { "tool": "cursor", - "template_version": 4, - "digest": "058565cf4e6fb0920212f39f51eddee0b10fd2a1bf2c6a9fe0841a6b49540a2d" + "template_version": 5, + "digest": "ed1e5d4ffef9b25f6547db85488cc7d2a5423cf2fc7b42104e1d75c6a07654a5" }, ".cursor/commands/specsync-create-spec.md": { "tool": "cursor", - "template_version": 4, + "template_version": 5, "digest": "96a88bac62a30f969fe784a6e5f7c113849db5b25caa2d9fea920a7cffc44d93" }, ".cursor/skills/spec-sync/SKILL.md": { "tool": "cursor", - "template_version": 4, - "digest": "605bb5e15a39e406e00bf3276afe7bcef56bf55b16e8399cb23a7c9264fa7d05" + "template_version": 5, + "digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a" }, ".gemini/commands/specsync/audit.toml": { "tool": "gemini", - "template_version": 4, - "digest": "3ed5c3f6021094e467f2b62b5ff0662dbee17e5115227599ca5565b080bbd6ea" + "template_version": 5, + "digest": "b5977aa1489e8318e237102c06e8cc826ba2f7544097c0cf7c462c22d8dcaf65" }, ".gemini/commands/specsync/check.toml": { "tool": "gemini", - "template_version": 4, - "digest": "0a1a97f92e65fbdb710f90d94cd3aa80fc61466245c4c4bcae081da709368fde" + "template_version": 5, + "digest": "e6feb1a376f518333fd00649b4f8a3896f043de22a9794758fc72ee90c339279" }, ".gemini/commands/specsync/create-change.toml": { "tool": "gemini", - "template_version": 4, - "digest": "38e8c2b702c02c36eb782f909a9e1a3ca25ddeda4b2afafb46a92548f1399fd5" + "template_version": 5, + "digest": "becc843a2d886f4607c5fc4ac0b9c117d44910bfaea6db0858370a239a168aa7" }, ".gemini/commands/specsync/create-spec.toml": { "tool": "gemini", - "template_version": 4, + "template_version": 5, "digest": "d61f2b1c01cd34c5865c94abc14589721c524c1c1f1a5fd556c624249dc1d1bf" }, ".gemini/skills/spec-sync/SKILL.md": { "tool": "gemini", - "template_version": 4, - "digest": "605bb5e15a39e406e00bf3276afe7bcef56bf55b16e8399cb23a7c9264fa7d05" + "template_version": 5, + "digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a" } } } diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/accepted-state.json b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/accepted-state.json new file mode 100644 index 00000000..9c75d1e8 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/accepted-state.json @@ -0,0 +1,55 @@ +{ + "schema_version": 1, + "workflow_version": 2, + "workflow_origin_version": 2, + "id": "teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle", + "slug": "teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle", + "title": "Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle", + "description": "Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle", + "kind": "documentation", + "state": "accepted", + "canonical_applied": true, + "base_commit": "6f11e34ef65710dd8839bfaaa6e6bc9004d6a530", + "created_at": 1789009962, + "updated_at": 1789013455, + "affected_specs": [ + "agents" + ], + "affected_paths": [ + "src/agents.rs", + ".claude/skills/spec-sync/SKILL.md", + ".codex/skills/spec-sync/SKILL.md", + ".cursor/skills/spec-sync/SKILL.md", + ".gemini/skills/spec-sync/SKILL.md", + ".claude/commands/specsync/create-change.md", + ".claude/commands/specsync/check.md", + ".claude/commands/specsync/audit.md", + ".cursor/commands/specsync-create-change.md", + ".cursor/commands/specsync-check.md", + ".cursor/commands/specsync-audit.md", + ".gemini/commands/specsync/create-change.toml", + ".gemini/commands/specsync/check.toml", + ".gemini/commands/specsync/audit.toml" + ], + "no_spec_change": false, + "no_spec_change_rationale": null, + "acceptance_criteria": [ + "Generated Claude/Cursor/Codex/Gemini SKILL.md files lead with specsync check as the product and SDD opt-in via change adopt.", + "Generated create-change/check/audit commands use 6.0 happy-path verbs: approve --actor, check --commit, review --reviewer, ship/finalize; v1 start/verify/accept/archive are labeled recovery only.", + "AGENT_ARTIFACT_TEMPLATE_VERSION is 5 so specsync agents install refreshes stale host skills.", + "cargo test agents:: passes.", + "specsync check --spec agents passes." + ], + "selected_artifacts": [ + "context", + "docs", + "design", + "tasks", + "requirements" + ], + "dependencies": [], + "answers": { + "architecture_risk": "no", + "public_contract": "yes" + } +} diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/approvals.json b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/approvals.json new file mode 100644 index 00000000..1a7d0ee8 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/approvals.json @@ -0,0 +1,63 @@ +{ + "approvals": [ + { + "gate": "definition", + "actor": "Leif", + "timestamp": 1789010250, + "digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "note": null, + "approved_scope": { + "schema_version": 1, + "change_id": "teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle", + "title": "Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle", + "description": "Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle", + "kind": "documentation", + "affected_specs": [ + "agents" + ], + "affected_paths": [ + ".claude/commands/specsync/audit.md", + ".claude/commands/specsync/check.md", + ".claude/commands/specsync/create-change.md", + ".claude/skills/spec-sync/SKILL.md", + ".codex/skills/spec-sync/SKILL.md", + ".cursor/commands/specsync-audit.md", + ".cursor/commands/specsync-check.md", + ".cursor/commands/specsync-create-change.md", + ".cursor/skills/spec-sync/SKILL.md", + ".gemini/commands/specsync/audit.toml", + ".gemini/commands/specsync/check.toml", + ".gemini/commands/specsync/create-change.toml", + ".gemini/skills/spec-sync/SKILL.md", + "src/agents.rs" + ], + "no_spec_change": false, + "no_spec_change_rationale": null, + "acceptance_criteria": [ + "AGENT_ARTIFACT_TEMPLATE_VERSION is 5 so specsync agents install refreshes stale host skills.", + "Generated Claude/Cursor/Codex/Gemini SKILL.md files lead with specsync check as the product and SDD opt-in via change adopt.", + "Generated create-change/check/audit commands use 6.0 happy-path verbs: approve --actor, check --commit, review --reviewer, ship/finalize; v1 start/verify/accept/archive are labeled recovery only.", + "cargo test agents:: passes.", + "specsync check --spec agents passes." + ], + "dependencies": [], + "supersedes": [], + "answers": { + "architecture_risk": "no", + "public_contract": "yes" + } + }, + "approved_delta_digests": { + "agents": "f11aaefdc462e47661f08dd82e90386b4004305747e7a78c5b306a87766b6455" + } + }, + { + "gate": "finalization", + "actor": "specsync:finalization", + "timestamp": 1789013455, + "digest": "a208ba963ff4fb51b0f19eebb5e7d3f5142b5eef0835c910196697fca8338dec", + "note": "Same-PR finalization closing digest" + } + ], + "reopenings": [] +} diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/change.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/change.md new file mode 100644 index 00000000..16c22fc0 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/change.md @@ -0,0 +1,28 @@ +--- +id: teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle +state: archived +type: documentation +base_commit: 6f11e34ef65710dd8839bfaaa6e6bc9004d6a530 +--- + +# Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle + +## Intent + +Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle + +## Affected Canonical Specs + +- `agents` + +## Acceptance Criteria + +- Generated Claude/Cursor/Codex/Gemini SKILL.md files lead with specsync check as the product and SDD opt-in via change adopt. +- Generated create-change/check/audit commands use 6.0 happy-path verbs: approve --actor, check --commit, review --reviewer, ship/finalize; v1 start/verify/accept/archive are labeled recovery only. +- AGENT_ARTIFACT_TEMPLATE_VERSION is 5 so specsync agents install refreshes stale host skills. +- cargo test agents:: passes. +- specsync check --spec agents passes. + +## No-spec Rationale + +Not applicable diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/context.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/context.md new file mode 100644 index 00000000..6fa2a35d --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/context.md @@ -0,0 +1,20 @@ +--- +change: teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle +artifact: context +--- + +# Context + +SpecSync 6.0.0 shipped 2026-09-09. Generated host skills and slash commands still taught the +pre-ship SDD-first story: every meaningful edit starts a change, `approve` without `--actor`, +`change check` without `--commit`, `finalize` without the review/ship pairing, and no +`change adopt` on-switch. + +`SKILL_BODY` in `src/agents.rs` is the single source for Claude, Cursor, Codex, and Gemini +`SKILL.md`. Command bodies live in `CREATE_CHANGE_STEPS_MD`, `CHECK_CHANGE_STEPS_MD`, and +`AUDIT_CHANGE_STEPS_MD`. `AGENT_ARTIFACT_TEMPLATE_VERSION` must bump so `specsync agents install` +refreshes managed artifacts. + +Out of scope: unifying `hooks.rs` snippets with `SKILL_BODY` (already recorded as a deliberate +split in `specs/agents/context.md`); adding slash commands for `ship`/`status`/`adopt`/`review`; +the shared catalog skill in the separate `skills` repo; committing untracked `.agents/` grok copies. diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/deltas/agents.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/deltas/agents.md new file mode 100644 index 00000000..af527bb1 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/deltas/agents.md @@ -0,0 +1,18 @@ +## ADDED + +### REQUIREMENT REQ-agents-007 + +Generated SDD skill and command text SHALL lead with `specsync check` as the product and SHALL +describe the verified change workflow as opt-in via `specsync change adopt`. When that workflow +is adopted, generated prose SHALL teach the 6.0 happy path and SHALL label v1 lifecycle verbs as +recovery only. + +Acceptance Criteria + +- Tracked Claude, Codex, Cursor, and Gemini `SKILL.md` files contain `` `specsync check` is the product `` + and `specsync change adopt`. +- Those files teach `approve --actor`, `check --commit`, `review --reviewer`, and `ship`/`finalize`. +- Those files label `start` / `verify` / `accept` / `archive` as v1 recovery, not the happy path. +- Generated create-change, check, and audit commands use the same happy-path verbs. +- `AGENT_ARTIFACT_TEMPLATE_VERSION` is 5 or higher so `specsync agents install` refreshes stale copies. +- A unit test fails if tracked `SKILL.md` files drop the check-is-product sentences. diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/design.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/design.md new file mode 100644 index 00000000..2ba29011 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/design.md @@ -0,0 +1,16 @@ +--- +change: teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle +artifact: design +--- + +# Design + +No new agent tools, paths, or slash commands. Template rewrite plus version bump. + +- Edit `SKILL_BODY` and the three command step templates in `src/agents.rs`. +- Bump `AGENT_ARTIFACT_TEMPLATE_VERSION` 4 to 5 so content-aware install overwrites the old + SDD-first body on managed artifacts. +- Regenerate tracked host files from those templates (existing byte-parity tests). +- Add `REQ-agents-007` and a tracked-file pin test for the check-is-product sentences, matching + the same-actor pin already in `tracked_skill_files_carry_the_current_same_actor_guidance`. +- Keep `hooks.rs` snippets unchanged in this change. diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/docs.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/docs.md new file mode 100644 index 00000000..67542ca5 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/docs.md @@ -0,0 +1,17 @@ +--- +change: teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle +artifact: docs +--- + +# Docs + +Generated host docs (installer output, not the Astro site): + +- `.claude/.codex/.cursor/.gemini` `SKILL.md`: `specsync check` is the product; SDD opt-in via + `specsync change adopt`; 6.0 happy path with `--actor`, `--commit`, `--reviewer`, `ship`/`finalize`; + v1 `start`/`verify`/`accept`/`archive` labeled recovery; slug ids; same-actor review kept. +- `create-change` / `check` / `audit` commands: same happy-path verbs; `--commit` for ship evidence. +- Canonical `specs/agents/agents.spec.md` purpose, changelog, and `REQ-agents-007`. +- Companion `specs/agents/context.md` and `tasks.md` current-status notes. + +Site blog and hub copy live in CorvidLabs/site (PR #401), not this change. diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/finalization.json b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/finalization.json new file mode 100644 index 00000000..d966f55f --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/finalization.json @@ -0,0 +1,12 @@ +{ + "schema_version": 2, + "change_id": "teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle", + "implementation_commit": "9fe7f7f8234b3c50032a9f3083454d369c392e08", + "implementation_tree": "669843c9694149800b7d1dfab74071694bca7db7", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "workspace_digest": "5191b50e51df56aafa54e52f0287482a09ca590c37fcb38bcc254b4a375bf444", + "closing_digest": "a208ba963ff4fb51b0f19eebb5e7d3f5142b5eef0835c910196697fca8338dec", + "review_digest": "3e8972ebb3f9fde162a98db33d51c7e6cdf0be072ee25ad1b755c664bbd93214", + "finalization_digest": "0cae39ef20a62b4e264eced972e980e9a192b701fe0a1052fab1e2970ba6a520", + "timestamp": 1789013455 +} diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/lesson-bundle.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/lesson-bundle.md new file mode 100644 index 00000000..1811c0c2 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/lesson-bundle.md @@ -0,0 +1,75 @@ +# Lesson bundle — teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle + +Material for folding this change's lessons into the affected specs' `context.md`. +Synthesise from what actually happened below; do not restate the change description. + +## What this change was + +- **Title**: Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle +- **Kind**: Documentation +- **Specs**: agents +- **Paths**: src/agents.rs, .claude/skills/spec-sync/SKILL.md, .codex/skills/spec-sync/SKILL.md, .cursor/skills/spec-sync/SKILL.md, .gemini/skills/spec-sync/SKILL.md, .claude/commands/specsync/create-change.md, .claude/commands/specsync/check.md, .claude/commands/specsync/audit.md, .cursor/commands/specsync-create-change.md, .cursor/commands/specsync-check.md, .cursor/commands/specsync-audit.md, .gemini/commands/specsync/create-change.toml, .gemini/commands/specsync/check.toml, .gemini/commands/specsync/audit.toml +- **Acceptance**: Generated Claude/Cursor/Codex/Gemini SKILL.md files lead with specsync check as the product and SDD opt-in via change adopt. +- **Acceptance**: Generated create-change/check/audit commands use 6.0 happy-path verbs: approve --actor, check --commit, review --reviewer, ship/finalize; v1 start/verify/accept/archive are labeled recovery only. +- **Acceptance**: AGENT_ARTIFACT_TEMPLATE_VERSION is 5 so specsync agents install refreshes stale host skills. +- **Acceptance**: cargo test agents:: passes. +- **Acceptance**: specsync check --spec agents passes. + +## Evidence + +- Verification commit: `9fe7f7f8234b3c50032a9f3083454d369c392e08` +- Base commit: `6f11e34ef65710dd8839bfaaa6e6bc9004d6a530` +- Verified by: `specsync check --spec agents` + +## From the change's context.md + +# Context + +SpecSync 6.0.0 shipped 2026-09-09. Generated host skills and slash commands still taught the +pre-ship SDD-first story: every meaningful edit starts a change, `approve` without `--actor`, +`change check` without `--commit`, `finalize` without the review/ship pairing, and no +`change adopt` on-switch. + +`SKILL_BODY` in `src/agents.rs` is the single source for Claude, Cursor, Codex, and Gemini +`SKILL.md`. Command bodies live in `CREATE_CHANGE_STEPS_MD`, `CHECK_CHANGE_STEPS_MD`, and +`AUDIT_CHANGE_STEPS_MD`. `AGENT_ARTIFACT_TEMPLATE_VERSION` must bump so `specsync agents install` +refreshes managed artifacts. + +Out of scope: unifying `hooks.rs` snippets with `SKILL_BODY` (already recorded as a deliberate +split in `specs/agents/context.md`); adding slash commands for `ship`/`status`/`adopt`/`review`; +the shared catalog skill in the separate `skills` repo; committing untracked `.agents/` grok copies. + +## From the change's design.md + +# Design + +No new agent tools, paths, or slash commands. Template rewrite plus version bump. + +- Edit `SKILL_BODY` and the three command step templates in `src/agents.rs`. +- Bump `AGENT_ARTIFACT_TEMPLATE_VERSION` 4 to 5 so content-aware install overwrites the old + SDD-first body on managed artifacts. +- Regenerate tracked host files from those templates (existing byte-parity tests). +- Add `REQ-agents-007` and a tracked-file pin test for the check-is-product sentences, matching + the same-actor pin already in `tracked_skill_files_carry_the_current_same_actor_guidance`. +- Keep `hooks.rs` snippets unchanged in this change. + +## From the change's testing.md + +# Testing + +- Unit: `cargo test agents::` — 42 passed, including + `tracked_skill_files_teach_check_is_the_product` and + `tracked_skill_files_carry_the_current_same_actor_guidance`. +- Spec: `specsync check --strict agents` — pass. +- Installer: `specsync agents install` in this tree refreshed 16 managed artifacts to + `template_version` 5. + +## Requirement evidence + +| ID | Evidence | +|----|----------| +| REQ-agents-007 | Tracked Claude/Codex/Cursor/Gemini `SKILL.md` files contain `` `specsync check` is the product ``, `specsync change adopt`, `approve --actor`, `check --commit`, `review --reviewer`, and `v1 recovery`. Pin: `tracked_skill_files_teach_check_is_the_product`. `AGENT_ARTIFACT_TEMPLATE_VERSION` is 5; `.specsync/agent-artifacts.json` records template_version 5 on all 16 artifacts. | + +## Where these lessons go + +- `specs/agents/context.md` diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/requirements.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/requirements.md new file mode 100644 index 00000000..cc8cdb88 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/requirements.md @@ -0,0 +1,25 @@ +--- +change: teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle +artifact: requirements +--- + +# Requirements + +## Functional + +### REQ-agents-007 + +Generated SDD skill and command text SHALL lead with `specsync check` as the product and SHALL +describe the verified change workflow as opt-in via `specsync change adopt`. When that workflow +is adopted, generated prose SHALL teach the 6.0 happy path and SHALL label v1 lifecycle verbs as +recovery only. + +Acceptance Criteria + +- Tracked Claude, Codex, Cursor, and Gemini `SKILL.md` files contain `` `specsync check` is the product `` + and `specsync change adopt`. +- Those files teach `approve --actor`, `check --commit`, `review --reviewer`, and `ship`/`finalize`. +- Those files label `start` / `verify` / `accept` / `archive` as v1 recovery, not the happy path. +- Generated create-change, check, and audit commands use the same happy-path verbs. +- `AGENT_ARTIFACT_TEMPLATE_VERSION` is 5 or higher so `specsync agents install` refreshes stale copies. +- A unit test fails if tracked `SKILL.md` files drop the check-is-product sentences. diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/review-attempts.json b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/review-attempts.json new file mode 100644 index 00000000..23756082 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/review-attempts.json @@ -0,0 +1,21 @@ +{ + "schema_version": 1, + "reviews": [ + { + "schema_version": 2, + "change_id": "teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle", + "reviewer": "corvid-agent", + "provenance": { + "schema_version": 1, + "provider": "github_actions_check", + "required_check": "SpecSync scoped review" + }, + "verdict": "pass", + "implementation_commit": "9fe7f7f8234b3c50032a9f3083454d369c392e08", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "5191b50e51df56aafa54e52f0287482a09ca590c37fcb38bcc254b4a375bf444", + "timestamp": 1789013448 + } + ] +} diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/review.json b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/review.json new file mode 100644 index 00000000..8cf78a8d --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/review.json @@ -0,0 +1,16 @@ +{ + "schema_version": 2, + "change_id": "teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle", + "reviewer": "corvid-agent", + "provenance": { + "schema_version": 1, + "provider": "github_actions_check", + "required_check": "SpecSync scoped review" + }, + "verdict": "pass", + "implementation_commit": "9fe7f7f8234b3c50032a9f3083454d369c392e08", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "5191b50e51df56aafa54e52f0287482a09ca590c37fcb38bcc254b4a375bf444", + "timestamp": 1789013448 +} diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/state.json b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/state.json new file mode 100644 index 00000000..db69997b --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/state.json @@ -0,0 +1,55 @@ +{ + "schema_version": 1, + "workflow_version": 2, + "workflow_origin_version": 2, + "id": "teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle", + "slug": "teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle", + "title": "Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle", + "description": "Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle", + "kind": "documentation", + "state": "archived", + "canonical_applied": true, + "base_commit": "6f11e34ef65710dd8839bfaaa6e6bc9004d6a530", + "created_at": 1789009962, + "updated_at": 1789013543, + "affected_specs": [ + "agents" + ], + "affected_paths": [ + "src/agents.rs", + ".claude/skills/spec-sync/SKILL.md", + ".codex/skills/spec-sync/SKILL.md", + ".cursor/skills/spec-sync/SKILL.md", + ".gemini/skills/spec-sync/SKILL.md", + ".claude/commands/specsync/create-change.md", + ".claude/commands/specsync/check.md", + ".claude/commands/specsync/audit.md", + ".cursor/commands/specsync-create-change.md", + ".cursor/commands/specsync-check.md", + ".cursor/commands/specsync-audit.md", + ".gemini/commands/specsync/create-change.toml", + ".gemini/commands/specsync/check.toml", + ".gemini/commands/specsync/audit.toml" + ], + "no_spec_change": false, + "no_spec_change_rationale": null, + "acceptance_criteria": [ + "Generated Claude/Cursor/Codex/Gemini SKILL.md files lead with specsync check as the product and SDD opt-in via change adopt.", + "Generated create-change/check/audit commands use 6.0 happy-path verbs: approve --actor, check --commit, review --reviewer, ship/finalize; v1 start/verify/accept/archive are labeled recovery only.", + "AGENT_ARTIFACT_TEMPLATE_VERSION is 5 so specsync agents install refreshes stale host skills.", + "cargo test agents:: passes.", + "specsync check --spec agents passes." + ], + "selected_artifacts": [ + "context", + "docs", + "design", + "tasks", + "requirements" + ], + "dependencies": [], + "answers": { + "architecture_risk": "no", + "public_contract": "yes" + } +} diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/tasks.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/tasks.md new file mode 100644 index 00000000..f9ab1afb --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/tasks.md @@ -0,0 +1,14 @@ +--- +change: teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle +artifact: tasks +--- + +# Tasks + +- [x] Rewrite `SKILL_BODY` for check-is-product and the 6.0 happy path. +- [x] Rewrite create-change / check / audit command templates. +- [x] Bump `AGENT_ARTIFACT_TEMPLATE_VERSION` to 5. +- [x] Regenerate tracked Claude, Codex, Cursor, and Gemini skills and commands. +- [x] Add `REQ-agents-007` plus canonical spec changelog and companions. +- [x] Pin tracked skill files with a unit test for the check-is-product sentences. +- [x] Run `cargo test agents::` and `specsync check --spec agents`. diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/testing.md b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/testing.md new file mode 100644 index 00000000..ace82b01 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/testing.md @@ -0,0 +1,19 @@ +--- +change: teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle +artifact: testing +--- + +# Testing + +- Unit: `cargo test agents::` — 42 passed, including + `tracked_skill_files_teach_check_is_the_product` and + `tracked_skill_files_carry_the_current_same_actor_guidance`. +- Spec: `specsync check --strict agents` — pass. +- Installer: `specsync agents install` in this tree refreshed 16 managed artifacts to + `template_version` 5. + +## Requirement evidence + +| ID | Evidence | +|----|----------| +| REQ-agents-007 | Tracked Claude/Codex/Cursor/Gemini `SKILL.md` files contain `` `specsync check` is the product ``, `specsync change adopt`, `approve --actor`, `check --commit`, `review --reviewer`, and `v1 recovery`. Pin: `tracked_skill_files_teach_check_is_the_product`. `AGENT_ARTIFACT_TEMPLATE_VERSION` is 5; `.specsync/agent-artifacts.json` records template_version 5 on all 16 artifacts. | diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/verification-attempts.json b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/verification-attempts.json new file mode 100644 index 00000000..aeb3181d --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/verification-attempts.json @@ -0,0 +1,399 @@ +{ + "schema_version": 1, + "attempts": [ + { + "timestamp": 1789010290, + "commit": "6f11e34ef65710dd8839bfaaa6e6bc9004d6a530", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "2e567b5de187a949deeb8318cc4c0487af06f8d535bb64bb0d158a629b664ad3", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789010321, + "commit": "6f11e34ef65710dd8839bfaaa6e6bc9004d6a530", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "2e567b5de187a949deeb8318cc4c0487af06f8d535bb64bb0d158a629b664ad3", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789010327, + "commit": "48b76de70c20b3189045f45d8cddabe199936db9", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "2e567b5de187a949deeb8318cc4c0487af06f8d535bb64bb0d158a629b664ad3", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789010385, + "commit": "6f11e34ef65710dd8839bfaaa6e6bc9004d6a530", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "6c791b6ee49cd7f7e6ad40a4c8887d2a1b535ff31cc982e6b760da45560c2321", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789010390, + "commit": "3194a10c25d45a41b0a1f7c2dcc05854613613ce", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "6c791b6ee49cd7f7e6ad40a4c8887d2a1b535ff31cc982e6b760da45560c2321", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789011112, + "commit": "ad5181cd171b3c7a19d0962963840c4c62b07ae6", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "7873ebf799e29d8db81abe3e0a1d7a1781aef0f4bd006eedd66eb141edf24f04", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789011119, + "commit": "b0844cc947ebbb92a3a968ee4138e302106b924e", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "7873ebf799e29d8db81abe3e0a1d7a1781aef0f4bd006eedd66eb141edf24f04", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789013355, + "commit": "4b71e92fa44dfcb687814ce219d11215ba231f66", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "5191b50e51df56aafa54e52f0287482a09ca590c37fcb38bcc254b4a375bf444", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789013364, + "commit": "b938d6f9ddc45bf22af9c137ae3afe2a9ca55f59", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "5191b50e51df56aafa54e52f0287482a09ca590c37fcb38bcc254b4a375bf444", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789013445, + "commit": "9fe7f7f8234b3c50032a9f3083454d369c392e08", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "5191b50e51df56aafa54e52f0287482a09ca590c37fcb38bcc254b4a375bf444", + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + }, + { + "timestamp": 1789013445, + "commit": "9fe7f7f8234b3c50032a9f3083454d369c392e08", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "5191b50e51df56aafa54e52f0287482a09ca590c37fcb38bcc254b4a375bf444", + "acceptance_input_digest": "059c96275f5aa7f68889723454268e79ffd28738de89233553bf8c14912202c4", + "acceptance_manifest": { + "schema_version": 1, + "entries": [ + { + "path": ".claude/commands/specsync/audit.md", + "kind": "file", + "mode": 33188, + "payload_digest": "90f09855129f006a9a9e1413a175d1a85034c0e11cb22b293ae3dc8e664adbaa", + "entry_digest": "836db867012e1c79aea019f6799b19d192e00f2d5c48d1ade78e0f2d3fef04dd", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".claude/commands/specsync/check.md", + "kind": "file", + "mode": 33188, + "payload_digest": "becd0e524cf267d999227ca241844805f75154ed7b1c600a6e4df38202d7bebe", + "entry_digest": "2043a9686a70134a25f0766f13de34f0066f6efb91c2a3d2af0483e2195281ed", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".claude/commands/specsync/create-change.md", + "kind": "file", + "mode": 33188, + "payload_digest": "292bb4c773ccbec62f5ff01000bf9a723664b3906e2b870882e4b528f6a618dd", + "entry_digest": "65c7683e1e88825914e4855fe4838e40134d453d9b02dbf018887bb52a586d0f", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".claude/skills/spec-sync/SKILL.md", + "kind": "file", + "mode": 33188, + "payload_digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a", + "entry_digest": "3994addf8c4569c3a59845fa2371724a4907281bb4bbbaecc16d162ff8668990", + "owners": [ + "agents" + ] + }, + { + "path": ".codex/skills/spec-sync/SKILL.md", + "kind": "file", + "mode": 33188, + "payload_digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a", + "entry_digest": "b08250748593ce6d0be739dccf3fa73e7576426bf9f325a7d2731fb45d945676", + "owners": [ + "agents" + ] + }, + { + "path": ".cursor/commands/specsync-audit.md", + "kind": "file", + "mode": 33188, + "payload_digest": "c34e6379fa03b4d82b9fb6ab0261657c6f225967e00f186f97c650f6f9bc9157", + "entry_digest": "d232609267fe7bb8781a728d308a04223034afa00d0a5c8f7b8b199f237bd4a5", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".cursor/commands/specsync-check.md", + "kind": "file", + "mode": 33188, + "payload_digest": "665cad000436c972f6bd61e73894e87eb3f68850e1da077869751a8c359b98a3", + "entry_digest": "d3e60235642054271fa31f5d0b39126def98b0f966c76fa53d9225fe0b92f0fe", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".cursor/commands/specsync-create-change.md", + "kind": "file", + "mode": 33188, + "payload_digest": "ed1e5d4ffef9b25f6547db85488cc7d2a5423cf2fc7b42104e1d75c6a07654a5", + "entry_digest": "2ad37903f17dee3116f1f2d5172eb1399f1f89f9b389f3f9ae4bd96a0570d939", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".cursor/skills/spec-sync/SKILL.md", + "kind": "file", + "mode": 33188, + "payload_digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a", + "entry_digest": "4de4a1e1301dae6ad51985e981917b5e0c3959d5e6d05ec8f249fa7ac9a2e124", + "owners": [ + "agents" + ] + }, + { + "path": ".gemini/commands/specsync/audit.toml", + "kind": "file", + "mode": 33188, + "payload_digest": "b5977aa1489e8318e237102c06e8cc826ba2f7544097c0cf7c462c22d8dcaf65", + "entry_digest": "49456ec3d60e8eb7f4bbd5e8fa53eb31d3a2d8fba8805076829d5503c5b343a4", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".gemini/commands/specsync/check.toml", + "kind": "file", + "mode": 33188, + "payload_digest": "e6feb1a376f518333fd00649b4f8a3896f043de22a9794758fc72ee90c339279", + "entry_digest": "7202ad606066d3f18b45096cd92176de10b42d9d332777b6ce29cdfaafac8b99", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".gemini/commands/specsync/create-change.toml", + "kind": "file", + "mode": 33188, + "payload_digest": "becc843a2d886f4607c5fc4ac0b9c117d44910bfaea6db0858370a239a168aa7", + "entry_digest": "13d96fa6ea8255761d3bad26d2187ebce3e8e0d8f520bb0e02163b9e4fc5c9c7", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".gemini/skills/spec-sync/SKILL.md", + "kind": "file", + "mode": 33188, + "payload_digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a", + "entry_digest": "a3c48d3a12a62ccc6939d52c283a106cdc9423d62ff17ee98e82092b6c8e0d13", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/agents.spec.md", + "kind": "file", + "mode": 33188, + "payload_digest": "531fa05864e99543dcbe225f9d34b4e64868ec90cc5219c4ad8b6ee0473716ea", + "entry_digest": "0e37327e3e2a883005b693d620b424fb3878e86c5103a2c63f37fd579353f4d4", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/context.md", + "kind": "file", + "mode": 33188, + "payload_digest": "ecc86448643f63f2c741582626d695c6291834b19035af63fd4b920a23c165a7", + "entry_digest": "9d4f1822f597397715f0e5076605ba03caf18290cf1e73175e5f857dd1a788b3", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/requirements.md", + "kind": "file", + "mode": 33188, + "payload_digest": "e1f348a27ddab9596b753809af37e4f324e07812af3183a9b531a5e111ef7af3", + "entry_digest": "d8cd36d9397034c690b32ac0f700a54cd94632542c5688037a60886ebfd5befd", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/tasks.md", + "kind": "file", + "mode": 33188, + "payload_digest": "54692c8daa0bcc3f902e56e52d12cf49933bb5189badbf336291ff9a4623cacd", + "entry_digest": "4d52d974b8e38b1f7d5b46ad32afa439090b08269b39539d4fb1d2cc1f570bab", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/testing.md", + "kind": "file", + "mode": 33188, + "payload_digest": "be8fda3ba161253c21d53da3b9c94194f91ce0a5b86b7209766326381b3b189e", + "entry_digest": "6e713c90780c052f807b6fd8b90ded3a73dc6818a88e948ff02c107648d2c89d", + "owners": [ + "agents" + ] + }, + { + "path": "src/agents.rs", + "kind": "file", + "mode": 33188, + "payload_digest": "0ad141e0c019acbda5641946c7d93fb7f1b5074d2c0951bf6f5e3e33464d4ce0", + "entry_digest": "3b302be9fd162e85391fe7392130bfa3f53f7fd6c4512ace47f440f8fd3165b6", + "owners": [ + "agents" + ] + } + ] + }, + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] + } + ] +} diff --git a/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/verification.json b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/verification.json new file mode 100644 index 00000000..37b50f87 --- /dev/null +++ b/.specsync/archive/changes/2026-09-10-teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle/verification.json @@ -0,0 +1,214 @@ +{ + "timestamp": 1789013445, + "commit": "9fe7f7f8234b3c50032a9f3083454d369c392e08", + "contract_digest": "5e65007df34cbbc0407a3c5243736c39047b102abbaba09e527bbff93862ade3", + "execution_digest": "8f2b64d4d0216f373b60ef01a5fc805e3a5f2082d6b9a6d0ae5187da3b264bfe", + "workspace_digest": "5191b50e51df56aafa54e52f0287482a09ca590c37fcb38bcc254b4a375bf444", + "acceptance_input_digest": "059c96275f5aa7f68889723454268e79ffd28738de89233553bf8c14912202c4", + "acceptance_manifest": { + "schema_version": 1, + "entries": [ + { + "path": ".claude/commands/specsync/audit.md", + "kind": "file", + "mode": 33188, + "payload_digest": "90f09855129f006a9a9e1413a175d1a85034c0e11cb22b293ae3dc8e664adbaa", + "entry_digest": "836db867012e1c79aea019f6799b19d192e00f2d5c48d1ade78e0f2d3fef04dd", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".claude/commands/specsync/check.md", + "kind": "file", + "mode": 33188, + "payload_digest": "becd0e524cf267d999227ca241844805f75154ed7b1c600a6e4df38202d7bebe", + "entry_digest": "2043a9686a70134a25f0766f13de34f0066f6efb91c2a3d2af0483e2195281ed", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".claude/commands/specsync/create-change.md", + "kind": "file", + "mode": 33188, + "payload_digest": "292bb4c773ccbec62f5ff01000bf9a723664b3906e2b870882e4b528f6a618dd", + "entry_digest": "65c7683e1e88825914e4855fe4838e40134d453d9b02dbf018887bb52a586d0f", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".claude/skills/spec-sync/SKILL.md", + "kind": "file", + "mode": 33188, + "payload_digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a", + "entry_digest": "3994addf8c4569c3a59845fa2371724a4907281bb4bbbaecc16d162ff8668990", + "owners": [ + "agents" + ] + }, + { + "path": ".codex/skills/spec-sync/SKILL.md", + "kind": "file", + "mode": 33188, + "payload_digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a", + "entry_digest": "b08250748593ce6d0be739dccf3fa73e7576426bf9f325a7d2731fb45d945676", + "owners": [ + "agents" + ] + }, + { + "path": ".cursor/commands/specsync-audit.md", + "kind": "file", + "mode": 33188, + "payload_digest": "c34e6379fa03b4d82b9fb6ab0261657c6f225967e00f186f97c650f6f9bc9157", + "entry_digest": "d232609267fe7bb8781a728d308a04223034afa00d0a5c8f7b8b199f237bd4a5", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".cursor/commands/specsync-check.md", + "kind": "file", + "mode": 33188, + "payload_digest": "665cad000436c972f6bd61e73894e87eb3f68850e1da077869751a8c359b98a3", + "entry_digest": "d3e60235642054271fa31f5d0b39126def98b0f966c76fa53d9225fe0b92f0fe", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".cursor/commands/specsync-create-change.md", + "kind": "file", + "mode": 33188, + "payload_digest": "ed1e5d4ffef9b25f6547db85488cc7d2a5423cf2fc7b42104e1d75c6a07654a5", + "entry_digest": "2ad37903f17dee3116f1f2d5172eb1399f1f89f9b389f3f9ae4bd96a0570d939", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".cursor/skills/spec-sync/SKILL.md", + "kind": "file", + "mode": 33188, + "payload_digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a", + "entry_digest": "4de4a1e1301dae6ad51985e981917b5e0c3959d5e6d05ec8f249fa7ac9a2e124", + "owners": [ + "agents" + ] + }, + { + "path": ".gemini/commands/specsync/audit.toml", + "kind": "file", + "mode": 33188, + "payload_digest": "b5977aa1489e8318e237102c06e8cc826ba2f7544097c0cf7c462c22d8dcaf65", + "entry_digest": "49456ec3d60e8eb7f4bbd5e8fa53eb31d3a2d8fba8805076829d5503c5b343a4", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".gemini/commands/specsync/check.toml", + "kind": "file", + "mode": 33188, + "payload_digest": "e6feb1a376f518333fd00649b4f8a3896f043de22a9794758fc72ee90c339279", + "entry_digest": "7202ad606066d3f18b45096cd92176de10b42d9d332777b6ce29cdfaafac8b99", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".gemini/commands/specsync/create-change.toml", + "kind": "file", + "mode": 33188, + "payload_digest": "becc843a2d886f4607c5fc4ac0b9c117d44910bfaea6db0858370a239a168aa7", + "entry_digest": "13d96fa6ea8255761d3bad26d2187ebce3e8e0d8f520bb0e02163b9e4fc5c9c7", + "owners": [ + "@exact:delivery" + ] + }, + { + "path": ".gemini/skills/spec-sync/SKILL.md", + "kind": "file", + "mode": 33188, + "payload_digest": "43c7263643b23c5f3518bce1c341070b38295576ffd7d477534ff0603887818a", + "entry_digest": "a3c48d3a12a62ccc6939d52c283a106cdc9423d62ff17ee98e82092b6c8e0d13", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/agents.spec.md", + "kind": "file", + "mode": 33188, + "payload_digest": "531fa05864e99543dcbe225f9d34b4e64868ec90cc5219c4ad8b6ee0473716ea", + "entry_digest": "0e37327e3e2a883005b693d620b424fb3878e86c5103a2c63f37fd579353f4d4", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/context.md", + "kind": "file", + "mode": 33188, + "payload_digest": "ecc86448643f63f2c741582626d695c6291834b19035af63fd4b920a23c165a7", + "entry_digest": "9d4f1822f597397715f0e5076605ba03caf18290cf1e73175e5f857dd1a788b3", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/requirements.md", + "kind": "file", + "mode": 33188, + "payload_digest": "e1f348a27ddab9596b753809af37e4f324e07812af3183a9b531a5e111ef7af3", + "entry_digest": "d8cd36d9397034c690b32ac0f700a54cd94632542c5688037a60886ebfd5befd", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/tasks.md", + "kind": "file", + "mode": 33188, + "payload_digest": "54692c8daa0bcc3f902e56e52d12cf49933bb5189badbf336291ff9a4623cacd", + "entry_digest": "4d52d974b8e38b1f7d5b46ad32afa439090b08269b39539d4fb1d2cc1f570bab", + "owners": [ + "agents" + ] + }, + { + "path": "specs/agents/testing.md", + "kind": "file", + "mode": 33188, + "payload_digest": "be8fda3ba161253c21d53da3b9c94194f91ce0a5b86b7209766326381b3b189e", + "entry_digest": "6e713c90780c052f807b6fd8b90ded3a73dc6818a88e948ff02c107648d2c89d", + "owners": [ + "agents" + ] + }, + { + "path": "src/agents.rs", + "kind": "file", + "mode": 33188, + "payload_digest": "0ad141e0c019acbda5641946c7d93fb7f1b5074d2c0951bf6f5e3e33464d4ce0", + "entry_digest": "3b302be9fd162e85391fe7392130bfa3f53f7fd6c4512ace47f440f8fd3165b6", + "owners": [ + "agents" + ] + } + ] + }, + "passed": true, + "commands": [ + { + "command": "specsync check --spec agents", + "success": true, + "exit_code": 0 + } + ], + "requirement_ids": [ + "REQ-agents-007" + ] +} diff --git a/specs/agents/agents.spec.md b/specs/agents/agents.spec.md index 417eb895..1d042644 100644 --- a/specs/agents/agents.spec.md +++ b/specs/agents/agents.spec.md @@ -1,6 +1,6 @@ --- module: agents -version: 14 +version: 16 status: stable files: - src/agents.rs @@ -16,9 +16,10 @@ depends_on: [] ## Purpose -Installs native, tool-owned verified-SDD skills for Claude Code, Cursor, Codex, and Gemini CLI. -Generated artifacts are tracked in `.specsync/agent-artifacts.json` so upgrades and uninstall can -distinguish exact managed bytes from user customization. +Installs native, tool-owned skills for Claude Code, Cursor, Codex, and Gemini CLI. Generated skill +text teaches `specsync check` as the product and the opt-in 6.0 change lifecycle. Generated artifacts +are tracked in `.specsync/agent-artifacts.json` so upgrades and uninstall can distinguish exact +managed bytes from user customization. ## Public API @@ -96,6 +97,12 @@ distinguish exact managed bytes from user customization. - **When** `install_agent(root, AgentTool::Claude)` is called - **Then** the file is overwritten with the current template content and `Ok(true)` is returned +### Scenario: Generated skill teaches check as the product + +- **Given** the current `SKILL_BODY` template +- **When** tracked Claude, Codex, Cursor, and Gemini `SKILL.md` files are read +- **Then** each file says `specsync check` is the product, names `specsync change adopt` as the SDD on-switch, and labels v1 `start`/`verify`/`accept`/`archive` as recovery + ## Error Cases | Condition | Behavior | @@ -123,6 +130,7 @@ distinguish exact managed bytes from user customization. | Date | Author | Change | |------|--------|--------| +| 2026-09-10 | leif | v15: generated skills lead with check as the product; SDD opt-in via change adopt; 6.0 happy path (`approve --actor`, `check --commit`, `review --reviewer`, `ship`/`finalize`); template version 5 | | 2026-09-01 | leif | Generated SDD skill allows the definition approver to record scoped review (solo ship) | | 2026-08-30 | SpecSync | v12: generated `change check` skill describes spec↔code sync, not targeted tests | | 2026-07-10 | codex | v3: teach all four skills the verified SDD lifecycle and add create-change commands where supported | @@ -140,3 +148,4 @@ distinguish exact managed bytes from user customization. | 2026-09-02 | SpecSync | tell-agents-when-it-is-safe-to-clear-context: Tell agents when it is safe to clear context | | 2026-09-02 | SpecSync | allow-the-scope-approver-to-record-scoped-review-so-solo-projects-can-ship-when-github-does-not-require-a-second: Allow the scope approver to record scoped review so solo projects can ship when GitHub does not require a second reviewer. | | 2026-09-02 | SpecSync | finish-the-same-actor-scoped-review-user-facing-copy-so-cli-adopting-and-generated-agent-skills-no-longer-demand-a: Finish the same-actor scoped-review user-facing copy so CLI, ADOPTING, and generated agent skills no longer demand a second identity | +| 2026-09-10 | SpecSync | teach-generated-agent-skills-the-specsync-6-0-check-is-product-lifecycle: Teach generated agent skills the SpecSync 6.0 check-is-product lifecycle | diff --git a/specs/agents/context.md b/specs/agents/context.md index 2b5dcf2c..3ef71dff 100644 --- a/specs/agents/context.md +++ b/specs/agents/context.md @@ -19,7 +19,12 @@ spec: agents.spec.md ## Current Status -Updated for 5.0 SDD. All four tools receive the verified lifecycle skill; Claude, Cursor, and Gemini also receive four commands — create-spec, create-change, check, and audit (`command_paths()` returns all four). Installation remains content-aware and safe for shared command directories, with unit coverage for upgrade, idempotency, and uninstall behavior. +Updated for shipped 6.0.0. Generated `SKILL_BODY` leads with `specsync check` as the product and +SDD as opt-in via `specsync change adopt`. Happy path is `new` -> `answer` -> `approve --actor` -> +implement -> `check --commit` -> `review --reviewer` -> `ship`/`finalize`. Template version 5. +All four tools receive that skill; Claude, Cursor, and Gemini also receive four commands — +create-spec, create-change, check, and audit. `hooks.rs` snippets remain a separate, shorter +surface and are not unified with `SKILL_BODY` in this change. ## Notes diff --git a/specs/agents/requirements.md b/specs/agents/requirements.md index 0b35d7a0..3ba6d5d3 100644 --- a/specs/agents/requirements.md +++ b/specs/agents/requirements.md @@ -117,3 +117,20 @@ Acceptance Criteria - Tracked `.claude/skills/spec-sync/SKILL.md`, `.codex/skills/spec-sync/SKILL.md`, `.cursor/skills/spec-sync/SKILL.md`, and `.gemini/skills/spec-sync/SKILL.md` contain that same-actor guidance. - A unit test fails if those tracked files drift from the current template on this point. +### REQ-agents-007 + +Generated SDD skill and command text SHALL lead with `specsync check` as the product and SHALL +describe the verified change workflow as opt-in via `specsync change adopt`. When that workflow +is adopted, generated prose SHALL teach the 6.0 happy path and SHALL label v1 lifecycle verbs as +recovery only. + +Acceptance Criteria + +- Tracked Claude, Codex, Cursor, and Gemini `SKILL.md` files contain `` `specsync check` is the product `` + and `specsync change adopt`. +- Those files teach `approve --actor`, `check --commit`, `review --reviewer`, and `ship`/`finalize`. +- Those files label `start` / `verify` / `accept` / `archive` as v1 recovery, not the happy path. +- Generated create-change, check, and audit commands use the same happy-path verbs. +- `AGENT_ARTIFACT_TEMPLATE_VERSION` is 5 or higher so `specsync agents install` refreshes stale copies. +- A unit test fails if tracked `SKILL.md` files drop the check-is-product sentences. + diff --git a/specs/agents/tasks.md b/specs/agents/tasks.md index 524f9359..9ec5a8fb 100644 --- a/specs/agents/tasks.md +++ b/specs/agents/tasks.md @@ -29,6 +29,7 @@ spec: agents.spec.md - [x] Native create-change commands for Claude, Cursor, and Gemini - [x] Human approval safeguards and deterministic JSON interview guidance - [x] Keep checked-in create-spec commands byte-identical to installer templates and classify complete non-flag input +- [x] Generated skills lead with check as the product and the 6.0 happy path (template version 5) ## Gaps diff --git a/specs/agents/testing.md b/specs/agents/testing.md index 64deeb94..0c99ae47 100644 --- a/specs/agents/testing.md +++ b/specs/agents/testing.md @@ -12,6 +12,7 @@ spec: agents.spec.md | `src/agents.rs` (content-aware reinstall) | cargo test agents:: | `install_overwrites_stale_skill_content`, `install_overwrites_stale_command_content` | | `src/agents.rs` (status/uninstall) | cargo test agents:: | `is_installed_returns_false_for_empty_dir`, `uninstall_returns_false_when_not_installed`, `uninstall_claude_removes_skill_and_command`, `uninstall_preserves_sibling_commands`, `uninstall_cursor_flat_file_does_not_touch_commands_dir`, `uninstall_gemini_removes_skill_and_command`, `uninstall_codex_removes_skill_only` | | `src/agents.rs` (create-spec parsing/parity) | cargo test agents:: | `create_spec_commands_classify_the_complete_remaining_input`, `checked_in_create_spec_commands_match_generated_assets`; covers `REQ-agents-003` flag-position, full-input classification, checked-in byte parity, and reinstall idempotency | +| `src/agents.rs` (6.0 skill contract) | cargo test agents:: | `tracked_skill_files_carry_the_current_same_actor_guidance`, `tracked_skill_files_teach_check_is_the_product`; covers `REQ-agents-006` and `REQ-agents-007` | ## Manual Testing diff --git a/src/agents.rs b/src/agents.rs index f294044e..7f8a0b77 100644 --- a/src/agents.rs +++ b/src/agents.rs @@ -14,18 +14,26 @@ use std::path::{Path, PathBuf}; // identical to each other (Cursor/Copilot use a terser style) and unifying // them is out of scope here — this body is purely for the new SKILL.md files. -const SKILL_BODY: &str = r#"## Companion files +const SKILL_BODY: &str = r#"`specsync check` is the product. Bidirectional spec-to-code validation does not require an +active change. SDD (`specsync change`) is opt-in: `specsync init` writes it off; +`specsync change adopt` turns it on. ## Verified change lifecycle (6.0) -For every meaningful source, test, public documentation, schema, or configuration change: +Happy path verbs: `change new` -> `answer` -> `approve --actor` -> implement -> +`check --commit` -> `review --reviewer` -> `ship`/`finalize`. `start` / `verify` / +`accept` / `archive` are v1 recovery, not the happy path. Change ids are slugs, not +`CHG-NNNN`. + +When SDD is adopted and the work is a meaningful source, test, public documentation, +schema, or configuration change: 1. Run `specsync change new "" --json` and conduct the returned interview with the user. 2. Use `specsync change answer "" --json` until no questions remain. 3. Complete the adaptively selected artifacts and semantic deltas. Requirements use stable `REQ--` IDs, a normative SHALL statement, and acceptance criteria. -4. Ask the user for the single scope approval, then run `specsync change approve `. -5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check []` +4. Ask the user for the single scope approval, then run `specsync change approve --actor ""`. +5. Implement code, canonical specs, and tests on the same branch. Run `specsync change check [] --commit` for **scoped** verification of this change only (materialize deltas + spec↔code sync). Do **not** treat check as a full archive integrity walk. Use `specsync change audit` when you need project health over **active** workspaces and living specs. Archives are history. @@ -33,15 +41,16 @@ For every meaningful source, test, public documentation, schema, or configuratio change package, implementation diff, canonical spec delta, and targeted evidence once, then record it with `specsync change review --reviewer ""`. The reviewer MAY be the same person who approved the definition. Do not invent a second identity for solo work. -7. Run `specsync change finalize ` to create the same-PR metadata/archive-only commit, then - merge through GitHub. SpecSync does not merge the pull request. +7. Run `specsync change ship ` (or `finalize`) for the same-PR archive tip. Do not commit + between review and ship. Merge on GitHub. SpecSync does not merge the pull request. ## Lifecycle verbs -- `specsync change check [id]` — verify **this** change (materialize + spec↔code sync). Default daily path. -- `specsync change audit` — project health over **active** workspaces and living specs. Not archive history. -- Archives are history; do not re-validate terminal evidence for every archived CHG on each check. -- Slash commands: `/specsync:check`, `/specsync:audit` (Claude/Cursor/Gemini via `specsync agents install`). +- `specsync check` - validate all specs against source. Default daily path. No change required. +- `specsync change check [id]` - verify **this** change (materialize + spec↔code sync). Add `--commit` for ship-ready product-tip evidence. +- `specsync change audit` - project health over **active** workspaces and living specs. Not archive history. +- Archives are history; do not re-validate terminal evidence for every archived change on each check. +- Slash commands after `specsync agents install`: Claude and Gemini use `/specsync:create-spec`, `/specsync:create-change`, `/specsync:check`, `/specsync:audit`. Cursor uses the flat names `/specsync-create-spec`, `/specsync-create-change`, `/specsync-check`, `/specsync-audit`. Never invent or self-grant the scope approval. If an approved definition changes, its digest becomes stale and must be approved again. `specsync change status` always @@ -52,11 +61,11 @@ evidence, but new changes use this single workflow. Each canonical spec may have policy-selected companion files. Read and update the ones present; do not create empty companions only for ceremony: -- **`tasks.md`** — Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. -- **`requirements.md`** — Acceptance criteria and user stories. These are permanent invariants, not tasks — do not check them off. Update if requirements change. -- **`context.md`** — Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. -- **`testing.md`** — Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. -- **`design.md`** *(opt-in)* — Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. +- **`tasks.md`** - Work items for this module. Check off tasks (`- [x]`) as you complete them. Add new tasks if you discover work needed. +- **`requirements.md`** - Acceptance criteria and user stories. These are permanent invariants, not tasks: do not check them off. Update if requirements change. +- **`context.md`** - Architectural decisions, key files, and current status. Update when you make design decisions or change what's in progress. +- **`testing.md`** - Test strategy: automated test locations, manual QA checklists, and edge cases/boundary conditions. +- **`design.md`** *(opt-in)* - Layout, component hierarchy, design tokens, and asset references. Present when `companions.design` is enabled in config. ## Before modifying any module @@ -66,38 +75,47 @@ Each canonical spec may have policy-selected companion files. Read and update th ## After completing work -1. Mark completed items in `tasks.md` — check off finished tasks, add new ones discovered -2. Update `context.md` — record decisions made, update current status +1. Mark completed items in `tasks.md`: check off finished tasks, add new ones discovered +2. Update `context.md`: record decisions made, update current status 3. If requirements changed, update `requirements.md` acceptance criteria 4. If test coverage changed, update `testing.md` with new test files or edge cases 5. If UI/layout changed, update `design.md` with revised layout, components, or tokens ## Before creating a PR -Run `specsync check --strict` — all specs must pass with zero warnings. +Run `specsync check --strict`: all specs must pass with zero warnings. If SDD is adopted, push +the product tip from `change check --commit` with the PR. Record `change review` and +`change ship`/`finalize` only after that tip is on the PR and required checks have run. Do not +record review or ship before the PR exists. ## When adding new modules Run `specsync scaffold ` to create a spec, companion files, a registry -entry, and auto-detected source files — or `specsync new ` for a +entry, and auto-detected source files, or `specsync new ` for a minimal spec-only draft. Complete the spec before writing code. The `/specsync:create-spec` command (or tool-equivalent) runs this for you, and accepts either a bare module name or a natural-language feature description (e.g. `/specsync:create-spec "I want a feature that lets users export their -data as CSV"`) — pass a description and it will pick a module name and use +data as CSV"`): pass a description and it will pick a module name and use the description to draft the spec's Purpose and Requirements. ## Key commands -- `specsync check` — validate all specs against source code -- `specsync check --json` — machine-readable validation output -- `specsync change check [id]` — scoped verification for one SDD change -- `specsync change audit` — active workspaces + living specs (not archive history) -- `specsync coverage` — show which modules lack specs -- `specsync score` — quality score for each spec (0-100) -- `specsync scaffold ` — full scaffold: spec + companions + registry entry + source detection -- `specsync new ` — quick-create a minimal spec (add `--full` for companions) -- `specsync resolve --remote` — verify cross-project dependencies +- `specsync check` - validate all specs against source code +- `specsync check --json` - machine-readable validation output +- `specsync change adopt` - turn on the opt-in verified change workflow +- `specsync change new ""` / `change answer` - open a change and finish the interview +- `specsync change approve --actor ""` - record the single scope approval +- `specsync change check [id]` - scoped verification for one SDD change (`--commit` for ship evidence) +- `specsync change review --reviewer ""` - record scoped implementation review +- `specsync change ship ` / `change finalize` - same-PR archive tip; do not commit between review and ship +- `specsync change status [id]` - one next action and a `Handoff:` line +- `specsync change audit` - active workspaces + living specs (not archive history) +- `specsync coverage` - show which modules lack specs +- `specsync score` - quality score for each spec (0-100) +- `specsync scaffold ` - full scaffold: spec + companions + registry entry + source detection +- `specsync new ` - quick-create a minimal spec (add `--full` for companions) +- `specsync resolve --remote` - verify cross-project dependencies "#; // ─── Create-spec command body (shared prose, per-tool argument syntax) ─────── @@ -181,31 +199,32 @@ const CREATE_SPEC_DESCRIPTION: &str = "Scaffold a new spec-sync module spec from const CREATE_CHANGE_DESCRIPTION: &str = "Create and guide a verified spec-sync SDD change through its deterministic interview"; -const CREATE_CHANGE_STEPS_MD: &str = r#"1. Run `specsync change new "$ARGUMENTS" --json`. -2. Read the returned `questions` array and interview the user one question at a time. -3. Record each answer with `specsync change answer "" --json`. -4. Continue until the question list is empty, then show the selected artifacts and next action. -5. Do not approve, implement, verify, accept, or archive until the corresponding human gate or work stage is reached. -6. After implementation, run scoped verification with `specsync change check ` (or `/specsync:check`). Use `specsync change audit` only for active-workspace project health — never expect check to rewalk archived terminal evidence."#; +const CREATE_CHANGE_STEPS_MD: &str = r#"1. SDD is opt-in via `specsync change adopt`. If change commands fail because the workflow is off, adopt only when the user asked to turn SDD on. +2. Run `specsync change new "$ARGUMENTS" --json`. +3. Read the returned `questions` array and interview the user one question at a time. +4. Record each answer with `specsync change answer "" --json`. +5. Continue until the question list is empty, then show the selected artifacts and next action. +6. Do not run `specsync change approve --actor ""`, implement, `specsync change check --commit`, `specsync change review --reviewer ""`, or `specsync change ship`/`finalize` until that gate is reached. Do not use v1 `start`/`verify`/`accept`/`archive` as the happy path. +7. After implementation, run `specsync change check --commit` (or the installed check command with --commit when preparing ship evidence). Use `specsync change audit` only for active-workspace project health. Never expect check to rewalk archived terminal evidence."#; const CHECK_CHANGE_DESCRIPTION: &str = "Run scoped SpecSync change verification for one change (materialize deltas + spec↔code sync)"; -const CHECK_CHANGE_STEPS_MD: &str = r#"1. Prefer `specsync change check $ARGUMENTS` when an id or partial id is provided; otherwise run `specsync change check`. -2. Expect **scoped** verification only — this change's materialization and in-process spec↔code sync. Do not run a full archive integrity walk. -3. Stream/wait for exit. On success, follow the printed **Next:** action (review, PR, or finalize path). +const CHECK_CHANGE_STEPS_MD: &str = r#"1. Prefer `specsync change check $ARGUMENTS` when an id or partial id is provided; otherwise run `specsync change check`. For ship-ready product-tip evidence, include `--commit`. +2. Expect **scoped** verification only: this change's materialization and in-process spec↔code sync. Do not run a full archive integrity walk. +3. Stream/wait for exit. On success, follow the printed **Next:** action (review, PR, or ship/finalize path). 4. Do **not** run `specsync change audit` unless the user asked for project health over active workspaces and living specs."#; const AUDIT_CHANGE_DESCRIPTION: &str = "Audit active SpecSync change workspaces and living specs (not archive history)"; const AUDIT_CHANGE_STEPS_MD: &str = r#"1. Run `specsync change audit`. -2. Report active-workspace and living-spec issues only. Archives are history — do not re-validate every archived CHG's terminal evidence. +2. Report active-workspace and living-spec issues only. Archives are history: do not re-validate every archived change's terminal evidence. 3. Use this for "is the SDD workspace healthy?" not "did my feature tests pass?" (that is `change check` / `/specsync:check`)."#; -const SKILL_TRIGGER_DESCRIPTION: &str = "Keep markdown module specs in specs// synchronized with source code using spec-sync. Use this whenever creating, editing, or reviewing code in a module that has (or should have) a spec, or whenever the user mentions specs, spec-sync, companion files (tasks.md/requirements.md/context.md/testing.md/design.md), or asks to add/update a module's documentation."; +const SKILL_TRIGGER_DESCRIPTION: &str = "Keep markdown module specs in specs// synchronized with source code using specsync check (the product). Use this whenever creating, editing, or reviewing a spec or its source, or when the user mentions spec-sync, SDD, change adopt, companion files, or the 6.0 change lifecycle (approve, check --commit, review, ship)."; const AGENT_ARTIFACT_MANIFEST_VERSION: u32 = 1; -const AGENT_ARTIFACT_TEMPLATE_VERSION: u32 = 4; +const AGENT_ARTIFACT_TEMPLATE_VERSION: u32 = 5; const AGENT_ARTIFACT_MANIFEST_PATH: &str = ".specsync/agent-artifacts.json"; // `.specsync/agent-artifacts.json` is committed and shared, and `load_agent_artifact_manifest` @@ -1126,6 +1145,11 @@ mod tests { ) .unwrap(); assert!(change_command.contains("specsync change new")); + assert!(change_command.contains("specsync change adopt")); + assert!(change_command.contains("approve --actor")); + assert!(change_command.contains("review --reviewer")); + assert!(skill.contains("/specsync-create-change")); + assert!(skill.contains("record review or ship before the PR exists")); assert!(skill.contains("specsync change check")); assert!(skill.contains("specsync change audit")); assert!(skill.contains("Lifecycle verbs")); @@ -1719,4 +1743,43 @@ mod tests { ); } } + + #[test] + fn tracked_skill_files_teach_check_is_the_product() { + let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")); + for relative in [ + ".claude/skills/spec-sync/SKILL.md", + ".codex/skills/spec-sync/SKILL.md", + ".cursor/skills/spec-sync/SKILL.md", + ".gemini/skills/spec-sync/SKILL.md", + ] { + let path = root.join(relative); + let body = fs::read_to_string(&path) + .unwrap_or_else(|error| panic!("read {}: {error}", path.display())); + assert!( + body.contains("`specsync check` is the product"), + "{relative} must lead with check as the product" + ); + assert!( + body.contains("specsync change adopt"), + "{relative} must name change adopt as the SDD on-switch" + ); + assert!( + body.contains("approve --actor"), + "{relative} must teach approve --actor" + ); + assert!( + body.contains("check --commit"), + "{relative} must teach check --commit" + ); + assert!( + body.contains("review --reviewer"), + "{relative} must teach review --reviewer" + ); + assert!( + body.contains("v1 recovery"), + "{relative} must label start/verify/accept/archive as v1 recovery" + ); + } + } }