superspec-plan

• Drive OpenSpec via CLI only (NO OpenSpec slash commands; i.e., commands starting with /opsx or /openspec).
• Prefer JSON output for every OpenSpec call (use --json).
• Keep changes scoped to design and tasks artifacts only.

1. If the user provides a change name, use it as .
2. Else run:

- openspec list --json

Ask the user to confirm/select a change name from the JSON output.

1. If there are no changes (or the user wants a new one), STOP and tell the user to run /superspec-research first to create proposal/specs for a new change.

Always print:

• Selected change:

Repeat until BOTH design and tasks are complete.

0. Inspect status

Run:

• openspec status --change --json

Parse the JSON to determine, for artifacts design and tasks:

• whether each is ready vs complete
• whether either is blocked (and why)

If the JSON schema is unclear, show the JSON and ask the user what the status fields mean; do not guess.

1. Blocked behavior

If design is blocked due to missing proposal or specs, STOP and tell the user to run /superspec-research.

If tasks is blocked due to missing proposal or specs (directly or indirectly), STOP and tell the user to run /superspec-research.

If either artifact is blocked for some other reason, STOP, show the status JSON, and ask the user what to do.

Note: If tasks is blocked only due to missing design, create design first (this skill owns design).

2. Create/Update design

If design is ready (and not complete):

1. Run:

- openspec instructions design --change --json

1. From the JSON, extract at minimum:

- outputPath (where to write)

- template and/or instruction content

- dependency inputs (especially proposal.md and delta specs under specs/**/spec.md)

1. Read the dependencies indicated by the JSON (proposal + delta specs) and write design.md to the concrete outputPath using the provided template/instructions.

If outputPath is not a concrete file path (unexpected), STOP and show the full JSON.

Design must be grounded strictly in proposal + delta specs (no extra scope), and should cover:

• technical approach and key decisions
• data/control flow
• interfaces/contracts that change
• specific files/modules expected to change
• test strategy mapped to scenarios
• ## Test Commands (mechanical) with default Verify Command(s) per Test Obligation Type (unit|integration|e2e)

After writing, print:

• Wrote design:

3. Create/Update tasks

If tasks is ready (and not complete):

1. Run:

- openspec instructions tasks --change --json

1. From the JSON, extract at minimum:

- outputPath (where to write)

- template and/or instruction content

- dependency inputs (especially design.md)

1. Read the dependencies indicated by the JSON (especially design.md and delta specs under specs/**/spec.md) and write tasks.md to the concrete outputPath.

Hard requirements for tasks.md:

• ONLY checkbox tasks, one per line, in this exact form:

- - [ ] X.Y

• Tasks are ordered by dependency.
• Each task is individually verifiable (a human can check it off with a clear done condition).
• No non-checkbox bullets, no paragraphs, no headers.

TDD compilation rules (non-negotiable):

• Compile tasks at Scenario granularity.
• For each #### Scenario: in delta specs under specs/**/spec.md, generate exactly 5 tasks with tags:

- - [ ] N.1 [TDD][RED] Spec: Scenario: Write failing test: ::

- - [ ] N.2 [TDD][VERIFY_RED] Run: (expect FAIL contains: "")

- - [ ] N.3 [TDD][GREEN] Implement minimal production code to satisfy Scenario:

- - [ ] N.4 [TDD][VERIFY_GREEN] Run: (expect PASS)

- - [ ] N.5 [TDD][REFACTOR] Refactor (no behavior change), keep tests green

• Verify Command resolution order:

1) Scenario ##### Test Obligation -> Verify Command

2) design.md -> ## Test Commands (mechanical) (type-matched default)

3) STOP and ask the user (do not guess)

• [NON-TDD] allowed ONLY for: docs-only, config-only (no behavior change), generated outputs, formatting/renaming only.

- For each [NON-TDD] unit generate exactly 2 tasks:

- - [ ] N.1 [NON-TDD][DO]

- - [ ] N.2 [NON-TDD][VERIFY]

- VERIFY must be mechanical (command output / file existence / OpenSpec validate), not a manual check.

If outputPath is not a concrete file path (unexpected), STOP and show the full JSON.

After writing, print:

• Wrote tasks:

4. Re-check

After creating design or tasks, re-run:

• openspec status --change --json

Stop the loop only when both artifacts show complete.

• Always show Selected change: .
• For each artifact you write, show exactly which artifact and the concrete path(s).
• On any error, show the exact command that failed (including --json).

• Writing non-checkbox tasks (anything other than - [ ] X.Y ...) in tasks.md.
• Using OpenSpec slash commands (anything starting with /opsx or /openspec) instead of the openspec CLI.
• Skipping the blocked rule (if proposal/specs are missing, stop and send the user to /superspec-research).