Spec Writer

Spec Writer

Bundled runtime

Before executing a CLI line below, replace its leading SSF with node "<plugin-root>/scripts/spec-superflow.mjs"; <plugin-root> is the absolute directory two levels above this file. Never run SSF literally or call an ssf from PATH.

Create or refine planning artifacts when the change has moved beyond exploration.

New planned changes

For a new request (no state or workflow auto), or workflow_variant planned, write proposal.md and tasks.md together without pausing between individual artifacts. Proposal holds the goal, in/out scope, acceptance and risks; tasks holds ordered deliverables and proof commands. Add specs only for behavior needing durable scenarios and design only for unresolved architectural decisions. Do not create execution-contract.md or duplicate the task list in another plan.

Check shared interfaces against the real source once, then self-check the problem, scope, dependencies and proof. Present one approval request only if this concrete plan lacks approval. After approval run SSF workflow start <dir> --path planned --confirm --reason "<user decision>" and continue implementation. No intermediate planning/bridging transitions or independent reader agent. A semantic revision uses the same command after approval; a nonsemantic correction uses execution resync and retains failed-review history. The remaining sections apply only to existing legacy changes.

Required Inputs

Read .spec-superflow.yaml (especially dp_0_decisions, dp_0_confirmed) and any existing planning artifacts. If dp_0_confirmed is not true, stop and route back to workflow-start for DP-0.

Config Check

Run: SSF runtime config --get artifacts.order — generate in configured order (default: proposal → specs → design → tasks). Run with artifacts.skip — skip any listed artifacts.

Artifact Roles

• proposal.md: why and scope
• specs/: required behavior (testable)
• design.md: architecture decisions and trade-offs (not line-by-line)
• tasks.md: dependency-aware implementation steps

Working Rules

Honor DP-0: Read dp_0_decisions, respect confirmed constraints, don't silently expand scope. Pause on unconfirmed decisions.

proposal.md

Must state: observed problem, what changes, in/out scope, impact areas, and proof of completion. Prefer concrete facts over empty adjectives such as “better”, “robust”, or “efficient”.

specs/

Every requirement must be testable. Use SHALL or MUST. Every requirement must have at least one #### Scenario: with WHEN/THEN. Group under ADDED/MODIFIED/REMOVED Requirements headers.

design.md