sdd-mcp-server 4.0.0 → 5.0.0

package/skills/sdd-requirements/SKILL.md

@@ -6,34 +6,42 @@ disable-model-invocation: true
 
 # SDD Requirements
 
-## Prerequisites
-
-- The feature must exist through `sdd-init`.
-- Check its durable phase with `sdd-status`.
-- Read the feature description and relevant steering. Ask only for material information that cannot be derived.
-
-## Workflow
-
-1. Identify users, goals, in-scope behavior, exclusions, constraints, assumptions, dependencies, and measurable success.
-2. Write independently testable functional and non-functional requirements using EARS:
-   - ubiquitous: `The system SHALL ...`
-   - event: `WHEN ... THEN the system SHALL ...`
-   - state: `WHILE ... THE system SHALL ...`
-   - optional: `WHERE ... THE system SHALL ...`
-   - unwanted behavior: `IF ... THEN the system SHALL ...`
-3. Give every requirement a stable ID and specific acceptance criteria. Replace ambiguous words such as “fast”, “appropriate”, “should”, or “may” with observable bounds.
-4. Include security, privacy, accessibility, compatibility, error, and performance requirements only where relevant; do not invent scope.
-5. Check completeness, consistency, feasibility, traceability, and testability; use `sdd-validate-gap` when existing code is in scope.
-6. Write `.spec/specs/{feature}/requirements.md`. Request requirements approval only after the artifact is complete; never self-approve silently.
+The user invokes this Skill; all MCP calls below are internal. Never ask the user to call a backend tool or expose revision, hash, fingerprint, or backend JSON except in explicit debug output.
+
+## Resolve and Restore
+
+1. Internally read status before doing method work.
+2. With a supplied missing feature, internally initialize it from the user's name and complete goal. If clarification is required, present the structured questions, collect answers, and retry initialization. Use the returned canonical feature name.
+3. With no supplied name: ask for a name and goal when no feature exists; resume the sole incomplete feature; when several are incomplete, list them and ask the user to select. Never infer identity from process memory.
+4. Load compact approved context. For a failed or unapproved requirements revision, load that draft only with full mode and explicit unapproved inclusion.
+5. If status reports an observed artifact identity for an orphan or manual edit, read that exact requirements file before revising. Never acknowledge its hash without inspecting and deliberately incorporating or replacing its content.
+
+If durable state reports a conflict or host permission failure, present an actionable blocker and make no artifact change.
+
+## Method and Artifact Contract
+
+1. Identify users, goals, scope, exclusions, constraints, assumptions, dependencies, and measurable success.
+2. Write independently testable EARS requirements. Every requirement uses a unique `### FR-N: ...` or `### NFR-N: ...` section and same-line metadata labels:
+   - `**Objective:** ...`
+   - `**EARS Specification:** ... SHALL ...`
+   - `**Acceptance Criteria:** 1. ...` with at least one numbered item on the same line.
+3. Replace ambiguous words with observable bounds. Include security, privacy, accessibility, compatibility, errors, and performance only when relevant.
+4. Check completeness, consistency, feasibility, traceability, and testability; run gap analysis internally when existing code is in scope.
+
+Internally submit the complete Markdown with the exact revision and artifact identity last observed. Submission, not direct file editing, is the canonical write. Present the saved path and a concise validation result. A failed validation is a durable draft: revise it using the observed draft content and identity; do not request approval.
+
+## Human Gate
+
+When validation passes, ask one explicit question: **“Approve these requirements?”** Only an unambiguous affirmative answer in this Skill flow permits the internal approval call for the exact reviewed revision and artifact. Never self-approve or treat host tool permission as approval. After approval, reread status and report the persisted outcome.
 
 ## Specialist Delegation
 
-Target renderers provide the `planner` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only the goal, verified context, constraints, open decisions, and output contract. The specialist must not delegate again. Keep the handoff and returned summary at or below 2,048 estimated tokens. If the advisor or routed model is unavailable, record one fallback and continue in the parent without retrying or selecting a generic child. Where a native per-turn model override applies, execute in this turn.
+Target renderers provide the `planner` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only the goal, verified context, constraints, open decisions, and output contract. The specialist must not delegate again. Keep the handoff and returned summary at or below 2,048 estimated tokens. If unavailable, record one fallback and continue in the parent without retrying or selecting a generic child.
 
 ## Output
 
-Return the saved path, key scope decisions, validation evidence, and approval as the next action.
+Return the canonical saved path, key scope decisions, concise validation evidence, the approval question or persisted approval, and durable blockers. Do not present raw MCP operations as next steps.
 
 ## Optional Reference
 
-Read [REFERENCE.md](REFERENCE.md) only for EARS examples, document structure, or the extended quality checklist.
+Read [REFERENCE.md](REFERENCE.md) only for EARS examples, exact document shape, or the extended quality checklist.

package/skills/sdd-tasks/REFERENCE.md

@@ -5,17 +5,17 @@ Read only for formatting and decomposition help.
 ## Task Template
 
 ```markdown
-### N.M Outcome
-Affected artifacts:
-Requirements/design traceability:
-Dependencies:
-RED: focused failing behavior test and command
-GREEN: smallest complete behavior
-REFACTOR: bounded cleanup
-Acceptance criteria:
-Verification:
+### 1.1 Observable outcome
+**Covers:** FR-1, NFR-1, D-1
+**Dependencies:** none
+**TDD:** required
+**Affected artifacts:** src/example.ts, src/example.test.ts
+**Acceptance criteria:** The stated behavior and failure boundary are observable.
+**Verification:** Run the focused test, then the affected checks.
 ```
 
+Use comma-separated values for `Covers`, `Dependencies`, and `Affected artifacts`; use literal `none` for an empty set. For non-behavioral work, write `**TDD:** not-applicable — <specific reason>`.
+
 ## Decomposition
 
 Prefer a vertical behavior slice over separate “write all tests” and “write all code” phases. Split when a task has distinct observable outcomes, ownership boundaries, or independently verifiable failure modes. Merge tasks that would otherwise require a serial handoff with no standalone value. Mark concurrency only when slices do not edit the same contract or require one another's output.

package/skills/sdd-tasks/SKILL.md

@@ -6,30 +6,42 @@ disable-model-invocation: true
 
 # SDD Tasks
 
-## Prerequisites
+The user invokes this Skill; backend lifecycle calls are internal. Never tell the user to call a raw MCP tool or expose revision, hash, fingerprint, or backend JSON except in explicit debug output.
 
-- Resolve the feature with `sdd-status`.
-- Design must be generated and approved. Stop rather than planning from an unapproved draft.
-- Read the approved requirements and design, including interfaces, dependencies, risks, and acceptance criteria.
+## Resolve and Restore
 
-## Workflow
+1. Internally resolve status. If no feature name is supplied, resume the sole incomplete feature or ask the user to select when several exist.
+2. Design and requirements must be approved. If durable status says otherwise, present the persisted blocker and make no file change.
+3. Load the latest approved compact context before method work. Load an unapproved tasks draft only with full mode and explicit unapproved inclusion.
+4. The saved test-case-review choice is authoritative. Ask once only when status has no choice; reuse it on every revision.
+5. If status reports an observed artifact identity for an orphan or manual edit, read that exact tasks file before revising. Never acknowledge its hash without inspecting and deliberately incorporating or replacing its content.
 
-1. Map every design component and requirement to implementation and verification work.
-2. Split work into small, ordered slices that each produce observable value. State affected artifacts, dependencies, and acceptance criteria.
-3. For behavioral work, make RED → GREEN → REFACTOR explicit: first a focused failing test, then minimal implementation, then cleanup with the test green.
-4. Cover happy paths, boundaries, errors, state transitions, security controls, migration, and integration where applicable. Do not impose a test ratio when the architecture calls for a different mix.
-5. Mark genuinely independent slices so they may run concurrently; never invent parallelism or a serial specialist.
-6. Ask whether the optional test case review checkpoint is required. If enabled, record behavior/edge/error cases and require `sdd-review-test-cases` before tasks approval.
-7. Write `.spec/specs/{feature}/tasks.md`. Request tasks approval only after dependencies, traceability, and completion criteria are validated.
+If the runtime is unavailable because of host permission, report an actionable reload/trust or policy blocker; never substitute manual backend instructions.
+
+## Method and Artifact Contract
+
+1. Map every requirement and design decision to small, ordered implementation and verification slices.
+2. Use unique `### N.M ...` task sections with same-line labels `**Covers:**`, `**Dependencies:**`, `**TDD:**`, `**Affected artifacts:**`, `**Acceptance criteria:**`, and `**Verification:**`.
+3. `Covers`, dependencies, and affected artifacts are comma-separated; an empty set is exactly `none`. Dependencies name existing task IDs and must be acyclic.
+4. `TDD` is exactly `required` or `not-applicable — <reason>`. Behavioral work uses RED → GREEN → REFACTOR and covers relevant boundaries, errors, transitions, security, migration, and integration.
+5. Mark concurrency only for genuinely independent slices.
+
+Internally submit complete Markdown with the exact revision and artifact identity last observed and the persisted review choice. Submission is the canonical write. Present the saved path and concise validation outcome. A failed validation remains a durable draft to revise and cannot advance.
+
+## Human Gates
+
+If test-case review is required, present the concrete behavior, boundary, and error cases. Only explicit confirmation records the internal checkpoint for the exact tasks revision and artifact. This is separate from approval.
+
+After validation and any required review, ask **“Approve these implementation tasks?”** Only an unambiguous affirmative answer in this Skill flow permits internal approval of the exact reviewed artifact. Never self-approve. Reread status after each checkpoint and approval.
 
 ## Specialist Delegation
 
-Target renderers provide the `planner` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only approved design decisions, constraints, dependencies, and task output contract. The specialist must not delegate again. Keep the handoff and returned summary at or below 2,048 estimated tokens. If the advisor or routed model is unavailable, record one fallback and continue in the parent without retrying or selecting a generic child. Where a native per-turn model override applies, execute in this turn.
+Target renderers provide the `planner` route. When a native advisor is required, dispatch exactly one compact handoff with `specialistDepth: 1`; include only approved decisions, constraints, dependencies, and the task contract. The specialist must not delegate again. Keep the handoff and returned summary at or below 2,048 estimated tokens. If unavailable, record one fallback and continue in the parent without retrying or selecting a generic child.
 
 ## Output
 
-Return the saved path, requirement/design traceability, checkpoint choice, validation evidence, and approval as the next action.
+Return the canonical saved path, traceability, saved checkpoint choice, concise validation evidence, the current human decision, and durable blockers. Do not present raw MCP operations as next steps.
 
 ## Optional Reference
 
-Read [REFERENCE.md](REFERENCE.md) only for task templates, sizing heuristics, dependency diagrams, or the extended checklist.
+Read [REFERENCE.md](REFERENCE.md) only for the exact task template, sizing heuristics, dependency diagrams, or extended checklist.

package/templates/CLAUDE.md

@@ -1,24 +1,18 @@
 # CLAUDE.md — Spec-Driven Development
 
-This project uses `sdd-mcp-server` with manual-only skills and the canonical v4 MCP runtime.
+This project uses `sdd-mcp-server` with manual-only Skills and its hidden governed runtime.
 
-## Development paths
+## Start
 
-### Simple task
+After installation, reload Claude Code and accept the project MCP trust prompt. Invoke `/simple-task` for a small feature, bug fix, or focused enhancement.
 
-Invoke `/simple-task` for a small feature, bug fix, or focused enhancement.
-
-### Formal SDD
-
-For work requiring approved requirements, design, and TDD tasks:
+For formal work, invoke only the phase Skills:
 
 ```text
-sdd-init → /sdd-requirements → sdd-approve → /sdd-design → sdd-approve → /sdd-tasks → optional test review → sdd-approve → /sdd-implement
+/sdd-requirements <feature-name> → explicit approval → /sdd-design → explicit approval → /sdd-tasks → optional explicit test review → explicit approval → /sdd-implement
 ```
 
-Use the installed `sdd-*` MCP tools for state changes and compact context by default. Feature-scoped calls use `featureName`, not `projectId`.
-
-For continuation, call `sdd-context-load` with `featureName`; retain the returned `fingerprint` and send it as `ifNoneMatch` on the next identical request. A `not-modified` result means the prior payload remains current and must not be requested or repeated again.
+Each Skill restores durable status and approved compact context, performs validation and persistence internally, and asks for any required human decision. Do not ask the user to call MCP tools or paste workflow JSON. A cloned project still requires the host's project trust; organization or project deny rules may override local permissions.
 
 ## Model execution
 

package/templates/codex-AGENTS.md

@@ -1,20 +1,18 @@
 # AGENTS.md — Spec-Driven Development (SDD)
 
-This project uses the SDD workflow powered by `sdd-mcp-server`.
+This project uses `sdd-mcp-server` with manual-only Skills and its hidden governed runtime.
 
-## Development Paths
+## Start
 
-### Simple Tasks
-For small features, bug fixes, and quick enhancements — just start coding with best practices.
+After installation, reload Codex and accept project trust when prompted. Use `$simple-task` for a small feature, bug fix, or focused enhancement.
 
-### Full SDD Workflow
-For complex features requiring formal specification:
+For formal work, invoke only:
 
-```
-Initialize → Requirements → Design → Tasks → Implement
+```text
+$sdd-requirements <feature-name> → explicit approval → $sdd-design → explicit approval → $sdd-tasks → optional explicit test review → explicit approval → $sdd-implement
 ```
 
-Each phase builds on the previous and requires review before proceeding.
+Each Skill restores durable status and approved compact context, performs validation and persistence internally, and asks for required human decisions. Do not ask the user to call MCP tools or paste workflow JSON.
 
 ## Installed Components