Spec Schema

Flow-Next specs follow the template in plugins/flow-next/templates/spec.md.

Required sections

• Goal and context
• Architecture and data models
• API contracts
• Edge cases and constraints
• Acceptance Criteria
• Boundaries
• Decision context

Recommended shape

---
id: fn-12-add-pr-cognitive-aid
title: Add PR cognitive aid generation
---

## Goal and Context

## Architecture and Data Models

## API Contracts

## Edge Cases and Constraints

## Acceptance Criteria

**R1:** ...
**R2:** ...

## Boundaries

## Decision Context

The exact template in the Flow-Next repository is the source of truth. This page explains how to think about the sections when writing or reviewing.

Auxiliary sections are written only when they apply - ## Strategy Alignment and ## Strategy Conflicts when STRATEGY.md has content, ## Glossary Conflicts on a doc-aware vocabulary mismatch, ## Conversation Evidence from capture, ## Resolved via Codebase / ## Resolved via Project Docs from interview, and ## Parked unknowns for genuinely-unknown items. Park an item only when it fails the fog-or-ticket test: decidable now means decide it, schedulable means make it a task, and only true fog gets parked. Parked items graduate into the real sections as interview or plan resolves them, so the section empties as the spec matures.

Spec ids

The file name is the identity. Two schemes coexist in the same repo; both resolve everywhere a spec id is accepted.

Scheme	Full id example	Bare alias	When it is used
Native sequential	fn-12-add-pr-cognitive-aid	fn-12	Default (tracker.specIds=flow, or no tracker)
Tracker-keyed	wor-17-slug, gh-123-slug, gl-456-slug	wor-17, gh-123, gl-456	Created with --tracker-first, or when tracker.specIds=tracker with an active bridge

• The full …-slug form is the filesystem, branch, and task identity. A shared bare ordinal (two fn-122-… files with different slugs) is untidy, not a broken identity.
• Ids never change. Linking a tracker does not rename an existing fn-N spec; switching to tracker.specIds=tracker only affects new specs. Mixed stores are permanent and expected.
• Native fn-N allocation takes the max across the working tree, every registered git worktree, and every ref - which shrinks parallel-create races inside one repo. Separate unfetched clones can still collide; tracker-keyed ids avoid that race by using the tracker as the allocator.

Full hybrid model: Spec & task ids and Tracker Sync. Team recommendation: Collaboration.

Writing acceptance criteria

Acceptance criteria use stable R-IDs:

**R1:** The command creates `.flow/specs/<id>.md`.
**R2:** The command writes task files under `.flow/tasks/`.
**R3:** Validation fails if a task references a missing dependency.

Source tags

/flow-next:capture marks criteria with source tags:

• [user]: verbatim user requirement
• [paraphrase]: restated user requirement
• [inferred]: agent-inferred fill
• [strategy:<track>]: derived from STRATEGY.md

The read-back surfaces inferred counts before writing.

Section ownership

Section	Primary owner	Review question
Goal and context	PO, PM, user, maintainer	Does this describe the real outcome?
Acceptance criteria	PO + tech lead	Can we verify every requirement?
Boundaries	PO + tech lead	What must not be built?
Architecture and data models	Tech lead	Does this match the repo and constraints?
API contracts	Tech lead	Are integrations and compatibility clear?
Edge cases and constraints	PO + engineering	Are failure modes explicit enough?
Decision context	Whoever made the tradeoff	Will this still make sense in six months?

R-ID rules

• Use R1, R2, R3 in order.
• Freeze meanings after review.
• Leave gaps when removing accepted criteria.
• Append new criteria at the end.
• Map tasks back to R-IDs with satisfies: [R1, R3].

R-IDs are not formatting. They are how Flow-Next connects requirements to tasks, review receipts, and PR explanations.

Project-wide criteria (G-IDs)

A criterion that belongs to the project rather than to one spec (“every route change regenerates the API contract”) uses the same grammar with a G prefix, in .flow/criteria.md:

- **G1:** Every route change regenerates the API contract.
- **G2:** No new dependency without a health check (scope: package.json).

Spec completion review judges every G-ID against the whole implementation and records met / violated / n/a per criterion in the review receipt. The same never-renumber rule applies. Full model: Standing Criteria.

G-IDs are never restated as R-IDs in a spec’s ## Acceptance Criteria. A copy would drift as criteria.md evolves and be judged twice. Reference the G-ID in prose; an R-ID covers only what the spec adds beyond the standing rule.

Flow-Next 1.1.4 treats ## Acceptance Criteria as canonical. The parser still accepts legacy ## Acceptance and ## Acceptance criteria headings so older specs keep working.

Inferred criteria

Treat [inferred] criteria as provisional. They are useful because they show where the agent filled gaps, but they need human review before implementation. A high inferred count is a signal to run /flow-next:interview, not a signal to trust the draft harder.