Documentation that keeps pace with the code

Strict mode ties work completion to documentation. An agent cannot silently close a task: it must either apply a spec revision or record a meaningful reason why the spec was unaffected.

Two modes, one explicit choice

The mode is stored on the project and written to .flownix during initialization, so the agent knows the rule before its first status change. It can be switched from the web app or from an agent while a project is being connected.

Three policies, not three values of one field

There are three fields, and they answer different questions. They can be set independently, but spec_first only means anything together with the other two — the server refuses to enable it without them.

You switch them in the project header — a panel with three toggles. The panel knows about the dependency between them: enabling spec_first sends all three settings in one request and says beforehand what will be enabled along with it, and it will not let you remove a prerequisite while it is on. Changing policies requires an organization admin.

A feature in spec-first mode

1. The agent creates the feature — that is the change, and its content carries the proposal.
2. propose_doc_delta produces a draft: it stands in no review queue and asks nobody anything.
3. The agent and the human work the document out — update_doc_delta with the full body, as many times as it takes. Rejected decisions stay as comments on the feature.
4. submit_doc_delta — and the agent stops. Now the delta is addressed to a human.
5. The human approves or rejects. On a rejection the same delta is reworked, and the rejected revision stays readable in the round history.
6. Only after approval does the agent cut tasks — from the document that was accepted.

Creating a task earlier is refused with spec_first_not_approved. The refusal names the feature, the state of its deltas, and both ways out: drive the document to approval, or declare that no described behaviour changes.

A task in strict mode

1. The agent reads spec_mode from .flownix and opens the current documentation.
2. It performs the work and decides whether a documented contract or behaviour changed.
3. If it changed, the agent proposes the document's complete next state and applies the revision.
4. If it did not, the agent records a concrete reason with declare_no_spec_impact.
5. The server verifies the evidence before it accepts the done status.

Neither a patch nor a skip button

The format: OpenSpec as the industry standard

A Flownix spec is not free-form Markdown. Documents are written in the OpenSpec format, an open standard for spec-driven development: an agent writes specs by the same rules in every project, the server can check their structure, and a project exchanges specs with the outside world without losing meaning.

# Auth

## Purpose
Authentication and session management.

## Requirements

### Requirement: Token issuance
The system SHALL issue a JWT upon successful login.

#### Scenario: Valid credentials
- GIVEN a user with valid credentials
- WHEN the user submits the login form
- THEN a JWT is returned

One requirement is one observable behaviour with one RFC 2119 keyword (SHALL, MUST, SHOULD, MAY) in uppercase. Every requirement carries at least one scenario: a requirement nobody can check is a wish, not a contract. How it is built — the queue, the library, the table schema — belongs in the plan, not the spec.

The validate_spec tool checks a saved document by slug, or raw text saved nowhere yet, and answers with what to fix. It changes nothing, so you can call it before creating a node for the spec at all.

A ratchet: making it worse is forbidden, living with the old state is not

Strict mode holds the quality of a spec, not merely the fact that it was edited. The rule is single: a delta is rejected when it introduces issues the previous version of the document did not have. Issues inherited from the previous version come back as warnings and block nothing.

That is what keeps switching strict mode on from breaking an existing project. Every document written before it is free-form, and straight validation would mean no task in the project can be closed until somebody rewrites all the documentation by hand. Instead the format tightens through ordinary edits.

OpenSpec entity mapping

Exchanging the openspec/ directory

A project exports to an openspec/ tree and imports back from one — including a repository built by the OpenSpec tool itself.

• export_openspec returns a list of files: specs/<domain>/spec.md per document, changes/<slug>/ per open feature, changes/archive/<date>-<slug>/ per closed one. The agent writes them to disk with its own tools — the MCP server runs over HTTP and never reaches your repository.
• import_openspec takes the same tree back. It is idempotent by document domain and by the changes/<name> directory: importing an unchanged tree again creates no duplicates and proposes no empty deltas, so it is safe to call after every pull.

Reversibility is proven by a test rather than declared: import(export(project)) into an empty project reproduces the canonical render of every spec, the same branch composition and the same delta states.

MCP tools

Fourteen operations cover policy discovery and updates, the revision lifecycle including the draft, format checking, exchanging the openspec/ tree, and an honest no-impact path.

Who benefits from strict mode

Next

• Closing a task in strict mode — what is required on the way out
• Spec-first mode — the order of work when the document is accepted first
• The skill system — which skill leads the work under which policy