Workflow

Workflow (state on disk → the phase that comes next)

You do none of the work here. You route. This skill reads where an effort already stands, names the phase that comes next, and invokes it. Then it does the same again, until it reaches something that needs a person.

It exists because the lifecycle has eight phases and remembering which one is next is not a good use of anybody's attention — and because the answer is already written on disk. Every artefact the lifecycle produces is committed, and the spec's Status: header is a state machine nobody was reading.

Three ways in, all the same thing: the command /lifecycle:advance, the skill lifecycle:workflow, or just saying "advance" or "what's next" in a sentence.

This repo describes itself in .agents/, at the repository root. Read the files that bind your step, and treat them as authority over anything you would otherwise assume.

Three rules:

• A missing file is a real answer: that thing is not configured here. Say so in one line and take the safest reading — do not invent the repo's conventions, and do not fall back on another project's. If the whole directory is absent, stop and tell the user to run /onboard instead of guessing.
• .agents/ beats your own judgement, and loses to the user. It was written deliberately, so a rule you disagree with is reported once, not routed around.
• Read only what your step needs. Every line costs on every turn of a long run.

Arguments

Start with --dry when you are not sure the state is what you think it is. It costs one turn and it is the whole point of having the state written down.

Write the command in its namespaced form whenever you name it back to the user — a plugin command is /<plugin>:<command>, and the bare /advance is an unknown command. Telling somebody to type a command that does not resolve costs them a round for nothing.

Step 1 — Find the effort

In this order, and say which rule matched in one line:

1. A path in the argument. A spec file, or the directory holding one.
2. The current branch name. .agents/naming.md maps a branch to its effort directory.
3. The most recently modified effort directory whose spec is neither Built nor Superseded by <path>.
4. Nothing found → there is no work in flight. Say so and offer /frame.

Two efforts in flight and no argument is an ambiguity, not a guess. List them with their statuses and ask which one. Picking the most recent is exactly the wrong move when somebody has just come back to older work.

Step 2 — Read the state

Read only these. Every one is a fact on disk; none of it is inferred from the conversation, which is what makes this work in a fresh session.

git log outranks your memory and outranks a stale header. A ticket whose commit is on the branch is done whether or not somebody ticked its box — say so, and fix the header.

Step 3 — The state table

Read top to bottom and take the first row that matches.

A phase .agents/lifecycle.md turns off is skipped, and you say you skipped it. That file is the authority on which phases exist here; a repo that does not use /plan-check should not be told it is missing one.

A state not in this table is a real finding. Say what you observed, say it does not match a known state, and stop. Never pick the nearest row. A plan.md beside a spec that says Built, a populated issues/ with no plan, a Verdict: line you cannot parse — each of those means something happened that this table does not model, and guessing costs more than asking.

Step 4 — Report, then run

Report before you run, in this shape, so a wrong reading is caught in one line rather than three phases later:

effort    <path>            (matched by: branch name)
status    Specced
beside    plan.md ✓   plan-check.md ✗   issues/ —
next      /plan, then /plan-check
halting   before /build, to show you the shape

running /plan …

Then invoke the phase as a skill. You are not reimplementing it.

• --dry stops here. Report and return.
• --once runs this one phase, reports, and returns.
• Otherwise keep going: after a phase completes, go back to step 2 and re-read the state from disk. Re-read it; do not assume the phase moved it where you expected. A phase that failed halfway leaves a state the table can route on, and trusting your expectation is how a run marches past a problem.

Step 5 — Halt properly

A halt is a result, not a failure. Say three things and stop:

1. where the work now stands — the new status, and the artefact that proves it;
2. why you stopped — a human gate, a verdict, a cap, an unknown state;
3. the exact next command, or the exact question that needs answering.

halted   /build is ready to run but wants one go-ahead on the shape
stands   Specced · plan.md + plan-check.md committed · Verdict: Ready to build
next     /build          (or /advance again — it will offer the same go-ahead)

Never halt silently, and never halt without naming the next move. A driver that stops without saying why is worse than no driver, because the user now has to work out both where they are and whether something broke.

What halts a run, in full

• Every interactive phase — /onboard, /frame, /grill. Their whole value is that a person answers, and answering for them defeats the purpose.
• /build's single go-ahead. It is the one interruption in the unattended half, and it is deliberate.
• A verdict or a cap — Not ready twice, a fix loop past its round cap, a failing gate.
• An unknown state, per step 3.
• Outside working hours, where .agents/working-agreement.md sets them. Run the phase you are on if somebody is clearly there, then say you are not starting another chain tonight. Do not begin an unattended chain that will finish with a question nobody is awake to answer.

What this skill must never do

• Never do a phase's work itself. If /plan is next, invoke /plan. A router that starts planning is a second planner nobody reviews.
• Never skip a gate because the answer looks obvious. The gates are where the expensive mistakes get caught.
• Never edit a spec, a plan or a ticket — beyond correcting a status line that git log contradicts, which you report in one line.
• Never advance an effort the user did not name when two are in flight.

Dispatching the agents

This skill spawns none. It invokes skills, and those skills dispatch their own agents.