name: intent-driven-strict version: 1 description: >- Intent-driven OpenSpec workflow - proposal -> Gherkin-style specs -> design -> adr -> tasks. Validates implementation tasks against live framework/library/tool documentation in a hard gate between tasks and apply. Flow: proposal -> specs -> design -> adr -> tasks -> validate -> apply. artifacts: - id: proposal generates: proposal.md description: Initial proposal document outlining the change template: proposal.md instruction: > Create the proposal document that establishes WHY this change is needed. Sections: - **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now? - **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**. - **Capabilities**: Identify which behaviour specs will be created or modified: - **New Capabilities**: List capabilities being introduced. Each becomes a new `specs//spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`). - **Modified Capabilities**: List existing capabilities whose behaviour is changing. Only include if spec-level behaviour changes, not just implementation details. Each needs an OpenSpec Markdown delta file at `specs//spec.md`. Check `openspec/specs/` for existing spec names. Leave empty if no behaviour changes. - **Impact**: Affected code, APIs, dependencies, or systems. IMPORTANT: The Capabilities section is critical. It creates the contract between proposal and specs phases. Research existing specs before filling this in. Each capability listed here will need a corresponding spec file. Durable architectural decisions worth carrying across changes are distilled into ADR files at /adr/ by a later step after design. Keep it concise (1-2 pages). Focus on the "why" not the "how" - implementation details belong in design.md. This is the foundation - specs, design, adr, and tasks all build on this. requires: [] - id: specs generates: specs/**/*.md description: OpenSpec Markdown specs with Gherkin-style behaviour scenarios template: spec.md instruction: > Create OpenSpec Markdown spec files that define WHAT the system should do. The Markdown structure is the OpenSpec merge wrapper; the requirement and scenario content inside that wrapper should be written in Gherkin style. Create one spec file per capability listed in the proposal's Capabilities section. - New capabilities: use the exact kebab-case name from the proposal (specs//spec.md). - Modified capabilities: use the existing spec folder name from openspec/specs// when creating the delta spec at specs//spec.md. Delta operations (use ## headers exactly so OpenSpec archive can merge): - **ADDED Requirements**: New behaviour capabilities. - **MODIFIED Requirements**: Changed behaviour - MUST include the full updated requirement content, not a partial diff. - **REMOVED Requirements**: Deprecated behaviours - MUST include **Reason** and **Migration**. - **RENAMED Requirements**: Name changes only - use FROM:/TO: format. OpenSpec wrapper requirements: - Each requirement MUST use `### Requirement: `. - Each scenario MUST use `#### Scenario: `. This exact four-hash heading is required for OpenSpec validation and archive. - Every requirement MUST have at least one scenario. Gherkin-style content requirements: - Treat each requirement as the feature or business rule being specified. You may include `Feature:` or `Rule:` prose in the requirement body when it clarifies the behaviour. - Each scenario MUST describe behaviour with `GIVEN`, `WHEN`, and `THEN` steps. Use `AND` or `BUT` for follow-on steps. - Write observable outcomes in `THEN` steps. Avoid implementation details such as database table names, private methods, or UI selectors unless they are part of the domain contract. - Do not create `.feature` files for this artifact. External Gherkin linting is outside this schema; `spec.md` is required for OpenSpec merge. MODIFIED requirements workflow: 1. Locate the existing requirement in openspec/specs//spec.md. 2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios). 3. Paste under `## MODIFIED Requirements` and edit it so the copied block represents the full desired behaviour after the change. 4. Ensure header text matches exactly (whitespace-insensitive). Common pitfall: Using MODIFIED with partial content loses detail at archive time. If adding new concerns without changing existing behaviour, use ADDED instead. requires: - proposal - id: design generates: design.md description: Technical design document with implementation details template: design.md instruction: > Create the design document that explains HOW to implement the change. When to include design.md (create only if any apply): - Cross-cutting change (multiple services/modules) or new architectural pattern - New external dependency or significant data model changes - Security, performance, or migration complexity - Ambiguity that benefits from technical decisions before coding Prior decisions (read existing ADRs first): Before writing, list every file in /adr/. Build the supersession graph from each ADR's Supersedes field - an ADR is no longer in force if a later ADR's Supersedes points at it. Only the currently-in-force ADRs (accepted, not superseded) constrain this design. Older superseded ADRs are historical context only and MUST NOT be treated as live commitments. New design choices MUST be coherent with the in-force set. If a current ADR needs to be revisited, do not propose modifying it; flag it under Open Questions and let the adr step record a new superseding ADR. Sections: - **Context**: Background, current state, constraints, stakeholders - **Goals / Non-Goals**: What this design achieves and explicitly excludes - **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision. - **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] -> Mitigation - **Migration Plan**: Steps to deploy, rollback strategy (if applicable) - **Open Questions**: Outstanding decisions or unknowns to resolve. Include any in-force ADRs that this design suggests revisiting; the adr step will record the supersession. Focus on architecture and approach, not line-by-line implementation. Reference the proposal for motivation and specs for requirements. Good design docs explain the "why" behind technical decisions. requires: - proposal - id: adr generates: adr.md description: Per-change ADR review manifest and durable decision handoff template: adr.md instruction: > Complete ADR review for this change by writing a concise manifest at openspec/changes//adr.md. This change-local file is the artifact completion marker for the adr step. Existing files under /adr/ are required context for the review, but they MUST NOT satisfy completion for a new change. If the change introduces a major durable architectural decision, also create an Architecture Decision Record under /adr/. The path /adr/ means the target repository's top-level adr/ folder beside openspec/, not any folder inside openspec/. Repository-level ADR files persist across changes and MUST be written outside openspec/. IRON RULE - ADRs are immutable once accepted. You MUST NOT edit a prior ADR file under any circumstance, not its Status, not its body, not its date. To change a previously accepted decision, record a NEW ADR whose Status is "accepted, supersedes ADR-NNNN" and whose `Supersedes:` field names the prior one. Design consumers derive what is currently in force by walking Supersedes links across the folder. The prior ADR's contents stay frozen as a historical record. Process: 1. Read every existing ADR in /adr/. Build the supersession graph from each ADR's Supersedes field. Note the highest sequence number in use. 2. Re-read design.md. Identify decisions that meet ALL of these: - Establish a long-term architectural commitment (pattern, technology, boundary, contract) - not a tactical implementation detail. - Will affect future changes beyond this one. - Either aren't already captured by a currently-in-force ADR, OR intentionally diverge from one. If diverging, the new ADR supersedes the prior. 3. For each qualifying decision, create a NEW repository-level file at /adr/NNNN-kebab-title.md, where NNNN is a 4-digit sequence one greater than the highest existing. Include title, Status, Date, optional Supersedes, and MADR-short sections: Context, Decision, and Consequences. If this decision replaces a prior in-force ADR, set Status to "accepted, supersedes ADR-NNNN", populate the `Supersedes:` field, and explain in Context why the prior decision is being revisited. Do NOT touch the prior ADR's file. 4. Write openspec/changes//adr.md using the template. The manifest MUST state that ADR review completed for this change, list the in-force ADR context reviewed, and reference every repository-level ADR file created for this change. It MUST NOT duplicate full Context, Decision, or Consequences content from repository-level ADR files. 5. If nothing meets the bar, do not invent ADRs. The manifest MUST explicitly state that no major durable architectural decisions were introduced and no new repository-level ADR files were created. Filename convention: NNNN-kebab-title.md (e.g., 0042-use-postgres-for-catalog.md). Sequence is monotonic across the whole repo and never reused. requires: - design - id: tasks generates: tasks.md description: Implementation checklist with trackable tasks template: tasks.md instruction: > Create the task list that breaks down the implementation work. **IMPORTANT: Follow the template below exactly.** The apply phase parses checkbox format to track progress. Tasks not using `- [ ]` won't be tracked. Guidelines: - Group related tasks under ## numbered headings. - Each task MUST be a checkbox: `- [ ] X.Y Task description`. - Tasks should be small enough to complete in one session. - Order tasks by dependency (what must be done first?). - If implementation changes behaviour specs, include a task to run `openspec validate --type change --strict` before archive. Reference specs for what to build, design for how to build it, and /adr/ for durable architectural commitments to honor. Each task should be verifiable - you know when it's done. requires: - specs - adr - id: validate generates: validate.md description: Validates implementation tasks against live framework/library/tool documentation (hard gate before apply) template: validate.md instruction: | Validate every task in tasks.md against **live documentation** of the framework/library/tool each task uses. This is a HARD GATE: if any task is invalid, apply MUST NOT proceed until tasks.md is revised (and, where approved, the related artifacts that reference the same invalid detail). PRECHECK: - tasks.md must exist. - Read tasks.md AND any spec/design/adr artifacts referenced by the tasks so validation accounts for what the tasks are implementing. PROCESS: 1. GROUP TASKS BY TECHNOLOGY Cluster tasks into coherent groups, one per framework/library/tool surface (e.g., web framework, database driver/ORM, test ecosystem, observability SDKs, CI/Docker). Each task must be assigned to exactly one group. Keep groups small enough that a single validator can cover them thoroughly. 2. DEPLOY ONE VALIDATOR PER GROUP Try to dispatch one read-only sub-agent per technology group, in parallel, each instructed to: - Validate every task in its group against **live documentation** of the relevant framework/library/tool. - Return a per-claim verdict: **valid** or **invalid** (and if invalid, exactly what to fix and how to do it right), with the source URL as evidence. - Access documentation in this strict order: 1. Context7 tools within the mcphub MCP server (resolve the library ID, then query its docs). 2. jina or exa tools within the mcphub MCP server — fallback, e.g. if the library or tool isn't available in Context7. 3. A native web fetch tool, if available (e.g., `WebFetch`, etc.). - Prefer official documentation over third-party blogs; cite the URL supporting each verdict. - RESEARCH ONLY — sub-agents MUST NOT write or edit any files. FALLBACK: if deploying sub-agents fails, is unavailable, or produces empty/garbled results (no environment support, tool error, quota/timeout, etc.), do NOT silently skip validation and do NOT fabricate a verdict. Instead, carry out the same grouping and per-group validation directly in the main agent (session), following the exact same documentation-access order and read-only discipline. Only STOP and surface the error to the human if the main agent also has no way to reach live documentation — an unvalidated change must not proceed with a READY verdict. 3. CONSOLIDATE FINDINGS Collect every validator report into a single summary written to validate.md: - INVALID findings with exact fix and source URL. - VALID confirmations (notable ones only). - Cross-cutting fixes needed (a single invalid API reference often appears in multiple tasks, specs, and design prose). 4. EMIT VERDICT (machine-readable) You MUST emit exactly one of these lines at the end of validate.md: `VERDICT: READY` — all tasks valid; apply may proceed. `VERDICT: NEEDS_FIX` — at least one task invalid; apply blocked. This single line is the source of truth any enforcement tooling reads. The apply.instruction checks it as a hard gate. 5. PROMPT FOR REVISION APPROVAL (if NEEDS_FIX) If invalid tasks or task details are found, prompt the user for approval to revise using the AskUserQuestion tool, offering: - Revise tasks.md + related artifacts that reference the same invalid detail (proposal/design/specs) — recommended for internal coherence - Revise tasks.md only - Hold off on revising Do NOT edit any files until the user approves. If no invalid findings exist, state that the change is ready to apply. 6. APPLY APPROVED REVISIONS Once approved: - Edit tasks.md (and the approved related artifacts) to match the validated live documentation. - Re-run `openspec validate --type change --strict` — the change must still be valid after edits. - Grep for any residual invalid references across the change's artifacts to confirm none remain. - Per OpenSpec git discipline, commit the revised proposal artifacts to main before apply starts. STALENESS: a verdict applies only to the exact tasks.md contents that were validated. If tasks.md changes after the verdict is issued — for any reason other than applying the approved revisions — the verdict is VOID and a new validation round is required before apply may proceed. Never rely on a READY verdict issued for content that no longer exists. requires: - tasks apply: requires: - tasks - validate tracks: tasks.md instruction: | GATE (hard, agent-honored): validate.md must exist and contain `VERDICT: READY`. If validate.md is missing, OR if it contains `VERDICT: NEEDS_FIX`, OR if tasks.md has been modified since validate.md was written (verdict is VOID — see staleness rule in validate.instruction), STOP and inform the user that validation is required before apply may proceed. Do NOT silently proceed. Once the gate passes: read context files, work through pending tasks, mark complete as you go. Pause if you hit blockers or need clarification. If implementation reveals a task references invalid API/library usage, STOP and re-run the validate artifact before continuing — the verdict is stale.