Flownix
Начать
Sections
On this page

Work from the document: spec-first mode

The order in which a feature's document is worked out and accepted before its first task exists. Drafts, review rounds, the decomposition gate, and the ways out of it.

In the ordinary mode the spec catches up with the work: the agent expands the task tree, writes the code, and updates the document before closing. Spec-first reverses it — the document first, tasks after it is accepted — and this is not advice but server behaviour: creating a task under a feature whose document is not accepted is refused.

For the policies themselves and how they differ, see the explanation. This page is about the order of work.

Why it exists

The scenario the mode grew out of: "the tech lead and I sit down and work the document out, throw some decisions away, redo them, then accept the change — and only then start on the code."

Before spec-first there was nothing to do that with. To keep a working revision of a document you had to propose it, and proposing meant putting a question to a human: every intermediate wording landed in their review queue. A rejection produced a new row, and "what exactly did we throw away" had to be reconstructed from the action log.

Turning it on

The project header has a policy panel: three switches — strict mode, proposal approval, spec-first.

Enabling them one at a time is neither necessary nor possible: spec-first does not work without the other two, and the server refuses to enable it alone. The panel knows this — it sends all three settings in one request and tells you beforehand what will be enabled along with it.

The same rule in reverse: while spec-first is on, a prerequisite cannot be removed. The strict-mode and approval switches are disabled, and the hint suggests turning spec-first off first. That one can always be turned off — the mode has an exit.

An agent can do it too — set_project_policy with all three fields at once — but the button arrived in v0.18.0 and is now the shorter path.

The order of work

1. Open the change

A change is a feature. There is no separate entity for it: a feature already has child tasks, document references, a comment thread and a status, and introducing a second concept beside it would mean threading that concept through the whole tree for grouping the feature provides for free.

So the first step is a feature whose content holds the proposal: why, what changes, the boundaries, and which alternatives were rejected. Nothing else is created at this step — no plan, no tasks.

2. Find the document, don't invent a second one

Change the document that already covers the area. A second document about the same subject is worse than a stale one: the reader finds one of them and never learns the other exists. A new one is created only when nothing covers the area.

3. The draft

The agent proposes a delta — the full new body of the document — on behalf of that feature. In spec-first it is born a draft.

Draft

A working revision. Stands in no review queue, holds no gate, and is edited in place as many times as needed. It asks nobody anything.

Proposal

A question addressed to a human. Stands in the queue, holds the gates, and is not edited in place — only a reviewer's decision moves it.

The difference is practical: a draft is not "a delta nobody has looked at yet" but a delta nobody was asked to look at. If the agent reports that it is waiting for your approval right after creating a delta, it is wrong: submission puts the question, not creation.

4. Work it out

A draft is edited as many times as it takes — by the agent and by you, directly in the delta card. The body is sent in full every time: applying a delta replaces the document wholesale, and a fragment would collapse the spec to itself.

Format issues on a draft edit are shown but do not prevent saving. A document is written in passes: a requirement exists before its scenario does, and refusing to save a requirement without one would mean the scenario could never be added. The format is enforced strictly at submission.

Rejected decisions are worth recording as a comment on the feature, with the reason. This is not bureaucracy: what a team discarded is the most useful and worst-preserved part of a discussion, and without it the next agent proposes the same thing again.

5. Submit, then stop

Submitting for review is a separate action. From that moment the delta enters the queue, starts holding the gates, and is no longer edited in place.

Then the agent stops. Not "moves on to something adjacent while waiting" — stops: it cannot approve the delta itself, and work done while waiting turns out to be work against a document that was never accepted.

6. Approve or reject

A human decides, in the interface. A rejection requires a reason: "rejected" without one does not tell the author what to redo.

After a rejection the same delta is reworked, not a new one. It returns to draft, and the round history keeps the rejected body together with the reason. That is what the history is for: after rework the rejected revision cannot be read anywhere else — it was never a version of the document.

The feature card shows the history as a feed: the round, the action, who did it — human or agent — and what changed relative to the previous round. What changed, not a line diff: there are many rounds, and a wall of lines would turn the history into something nobody opens.

7. Cut the tasks

Only now. And from the accepted document, not from the idea you started with: if the document drifted from the original intent during the discussion, the document wins — that is what was approved.

8. Execute

From here the usual order applies — execute a task. The delta is applied together with closing the work, not earlier: a spec says what the system does, and it starts saying so when the system actually does it.

When the gate refuses

The refusal looks like this:

shell
FailedPrecondition: spec_first_not_approved: no task can be created under feature AF-FEAT-12 —
the project has spec_first on, and tasks are cut from an ACCEPTED document, not before it.
the feature has no deltas. Do one of two things: ...

It names the feature, the state of its deltas, and both ways out. There are exactly two, and both are legitimate:

  1. Drive the document to approval — back to steps 3–6.
  2. Declare that no described behaviour changes — on the feature itself, with a real reason.

The second exists for refactoring features and for projects that enabled the mode on a finished tree. Without it, enabling the mode would make everything undecomposable.

Things not worth doing, all of which look like progress: creating the task under the epic to bypass the feature (the gate stands on the feature, but the point is that tasks grow out of a document); moving it under the feature afterwards — a move is gated identically; turning the policy off to get around the policy. The last one is not a workaround but a decision to abandon the mode, and if it genuinely does not fit this work, that is a conversation rather than a call.

What changes for the agent

None of the above is something the agent infers — it reads it in the skills. plan-feature checks the project policy before creating the first node and, with spec-first on, hands the work to the spec-first-change skill, which owns the procedure end to end. How that works — the skill system.

A practical consequence: after enabling the mode, make sure your agent's skills are current. An agent with an older set will go expand the task tree and hit the refusal — nothing breaks, but a step is wasted.

Next