Specs

Who can use it: Developers write specs and Architects approve them. All firm staff read and comment. Clients don’t see specs.

A spec says how a feature will be built. Each feature has one. The client agreed what in the requirement; the spec is the firm’s technical plan.

Use case

REQ-4 is signed off. Arjun creates the spec: a new GET /orders endpoint, a “Reorder” button on the order screen, and a stock check that skips unavailable items. Meera comments: “Cap the history at 20 on the server, not just in the app.” Arjun updates the spec and resubmits, and Meera approves it.

stateDiagram-v2
    [*] --> Draft: Developer creates
    Draft --> InReview: Submit
    InReview --> Approved: Architect approves
    InReview --> Draft: Request changes
    Approved --> Draft: Reopen (no tasks yet)
    state "In review" as InReview

Write and submit

1. Open the feature’s Spec tab and create the spec. You can do this once the requirement is signed off.
2. Write it in Markdown and save as often as you like. Every save is a version.
3. Submit it. While it’s in review, people can comment but nobody can edit it.

Review

An Architect either approves the spec or requests changes, which sends it back to draft.

Caution

Approval waits until the Architecture doc is signed off.

An approved spec is frozen. An Architect can reopen it, but only until the first task exists. After that, discard and clone the feature.

All specs in one place

Specifications in the project lists every feature’s spec. Filter by feature and status, and open one to go to that feature’s Spec tab.