Understanding specs

A spec connects the project’s goals to a proposed implementation. It supplies context for planning, coding, and review; it should be checked against the actual requirements and current codebase.

A useful reading order is goal → architecture → milestone → story → acceptance criteria. Deep specifications can add implementation subtasks to a story.

An illustrative outline, with the subtasks a Deep spec adds:

Goal                  Keep a small team's work visible
Architecture          Web app, API, and project data
Milestone             A working issue board
  Story               Filter issues by assignee
    Acceptance        Only matching issues appear; an empty view explains why
    Subtasks (Deep)   Add the filter control; apply the assignee predicate;
                      check the matching and empty states

Read the artifactsCopy Anchor Link

Human-oriented output can include roles, personas, and effort estimates. Coding-agent output emphasizes implementation and omits human staffing detail. The API exposes Markdown, structured JSON, and available graphs; see inputs and outputs for exact fields.

Refine before buildingCopy Anchor Link

Ask the agent to resolve missing requirements, adjust constraints, or refine acceptance criteria. Use the available plan and story editing controls for the project. Confirm the updated artifact before launching work that depends on it.

Changing a plan does not retroactively update shipped code. Request the corresponding implementation change, and check that an active task is using the intended requirements.

Example acceptance criteriaCopy Anchor Link

Story: Export invoices
- The exported rows match the current filters.
- The file includes the currency for every monetary amount.
- Users cannot export invoices outside their account.
- An empty result displays an explanation instead of an empty download.

Track planned work in the roadmap and inspect implementation evidence in verification.