Writing Specs

A Flow-Next spec is a durable implementation contract. It should remove ambiguity without turning into pseudocode.

The spec should say what must be true when the work is done, why that matters, and what is out of bounds. The agent should still be free to discover the implementation path inside those boundaries.

Include

• Problem and target user
• Business outcome
• Acceptance criteria with stable R-IDs
• Constraints and non-goals
• Edge cases
• API or data contract expectations
• Decision context and trade-offs

Avoid

• File-by-file implementation orders
• Premature abstractions
• Pseudocode
• “Maybe later” features
• Renumbering R-IDs after review

Spec authoring loop

flowchart LR
  Draft["Draft intent"] --> Business["Business interview"]
  Business --> Technical["Technical interview"]
  Technical --> Review["Plan review"]
  Review -->|gaps| Technical
  Review -->|ready| Plan["/flow-next:plan"]

Solo developers can collapse the business and technical passes into one conversation. Teams should keep them distinct so product ownership and engineering ownership are visible in the artifact.

Template discovery

The bundled canonical scaffold lives at ${PLUGIN_ROOT}/templates/spec.md. In Flow-Next 1.1.3+, /flow-next:capture, /flow-next:interview, and /flow-next:plan resolve the scaffold through a four-tier cascade. First match wins:

1. <repo_root>/SPEC.md
2. <repo_root>/spec.md
3. .flow/templates/spec.md
4. bundled ${PLUGIN_ROOT}/templates/spec.md

Use the repo-root SPEC.md or spec.md when a project needs a customized scaffold. That matches Flow-Next’s other repo-root guidance files such as STRATEGY.md, CLAUDE.md, AGENTS.md, and GLOSSARY.md.

.flow/templates/spec.md is the project-local post-setup copy used by older 1.1.x installs. The bundled plugin template is the fallback and source of truth when the repo has not opted into customization.

Case-insensitive filesystems such as macOS APFS and Windows NTFS collapse SPEC.md and spec.md to one inode, so Flow-Next treats that as a single tier-one hit. On case-sensitive filesystems where both files exist distinctly, SPEC.md wins and Flow-Next warns.

Setup template copy

/flow-next:setup Step 4a offers a repo-root spec template when neither <repo_root>/SPEC.md nor <repo_root>/spec.md exists:

Copy template / Skip / abort

On consent, setup writes <repo_root>/SPEC.md from the bundled template. It always writes uppercase SPEC.md, preserves file mode 0644, and never creates lowercase spec.md.

On re-setup, Flow-Next uses a byte-compare gate:

Keep mine / Overwrite with canonical / abort

The compare normalizes CRLF to LF and ignores trailing-newline differences, so real project customizations are not silently clobbered.

Good acceptance criteria

**R1:** Users can create a spec from conversation context.
**R2:** Each generated acceptance criterion is source-tagged as [user], [paraphrase], or [inferred].
**R3:** The agent shows a read-back before writing files.

Scope split for teams

Business pass:

/flow-next:interview fn-1 --scope=business

Technical pass:

/flow-next:interview fn-1 --scope=technical --strategy --docs

Both passes write to the same spec file. They are states of one evolving artifact, not separate documents.

Product-owner pass

The business pass should answer:

• Who is affected?
• What behavior must exist?
• What customer or operational outcome defines success?
• What is explicitly not in scope?
• What can the agent infer, and what must remain human-owned?

Good product acceptance criteria are observable:

**R1:** A maintainer can run a single command to generate a PR body from an implemented spec.
**R2:** The PR body lists every acceptance criterion and whether it has evidence.
**R3:** Deferred review findings appear in the PR body instead of being hidden in agent context.

Technical pass

The technical pass should add:

• System boundaries and integration points.
• Data model or file format expectations.
• Security, permissions, and migration constraints.
• Test strategy and evidence expectations.
• Known risky files or modules.

Do not write a step-by-step implementation unless the sequence is itself a requirement. Let /flow-next:plan map the spec to the codebase after the spec is stable.

Before planning

Run the checklist:

• Every requirement has an R-ID.
• Non-goals are explicit.
• Ambiguous words like “fast”, “simple”, “secure”, or “nice” are translated into observable criteria.
• Product assumptions are marked as product assumptions, not engineering facts.
• Technical constraints are constraints, not preferences.
• The spec can be reviewed by someone who never saw the original chat.