The workflow

The template has two stages: project planning and feature development.

First, you describe what you want to build. Agents help turn that description into requirements, an architecture, and a roadmap, which you review and approve. Then each feature moves through implementation, automated checks, an independent code review, and a pull request.

If the requirements change later, you update the plan through a separate review and approval process.

The diagram shows the complete workflow, from planning a project to merging a feature. Play the walkthrough to follow one example, including what happens when a test fails or a review finds an issue.

Click any step to learn what happens and which script is responsible, or a stage to see all its steps. The same information is on this page, below the diagram.

The two stages, step by step

After a merge you can start the next feature. If the plan needs to change, return to the planning process.

How you can run it

Step by step

Run each script yourself and look at the result before you move on. This suits a feature that is complex, risky, or unfamiliar.

One command per feature

Run ./scripts/run-feature.sh <issue>. The workflow handles implementation, verification, review, fixes, and the pull request without interrupting you for routine decisions. It stops if an agent needs your input, if a step keeps failing, or when the maximum number of review rounds is reached.

Experimental: several features together

We have also tried a supervising agent that coordinates several feature runs. This is not part of the template. It needs extra coordination: what to do about conflicts between features, failed runs, and merges. A built-in task queue and parallel execution are among the possible improvements.

Situations the workflow handles

The plan has to change

You do not edit an approved plan by hand. A change request goes through review and approval again: update an approved plan.

A run is interrupted

The implementer keeps a handoff note with what is done and what remains, so the work continues without the earlier conversation: start-feature.sh <issue> --resume, or run-feature.sh <issue> again. An unattended run retries a temporary failure itself. When an agent needs a decision from you, it stops and leaves its question in the note.

Results are no longer current

A verification result belongs to the exact content that was checked: change the code and the checks run again. A review belongs to the content that was reviewed: when that changes, the scripts ask for a new review. If the base branch was merged into the feature in the meantime, a later review has to cover the complete feature, not only the recent changes. The approval of the plan lapses in the same way when the requirements or the roadmap change. See project checks and workflow checks for the details.

An agent hits a usage limit

When the provider of an agent refuses a session because a usage or rate limit is reached, the script shows the provider's own message and says that it is a usage limit, not a defect: run the step again after the time the provider names. An unattended run retries the step and writes the limit into its log, so you can see afterward why it stopped.

The network fails while a feature starts

Reading the issue is tried again when the connection or GitHub fails for a moment; an issue that does not exist, or a refusal, stops at once with its reason. An unattended run tries the start again, like any other temporary failure.

The base branch moved after a feature was finished

Merge the base branch into the feature branch and publish again: git merge origin/main, then ./scripts/publish-feature.sh <issue>. The pull request is still described by the commit of the finished feature and still closes the issue. Any other commit after the finish needs a new finish first.

A review has findings

Each finding gets one of three recorded decisions: fix it now (FIX_NOW), defer it to a follow-up issue (DEFER), or accept it with a reason (ACCEPT). See decide what to do with review findings.

You need a review although a check fails

review-feature.sh <issue> --unverified "<reason>" reviews work whose verification fails, and records the reason. It is an exception, not a pass: the checks still count as failed, and the feature cannot be committed until they pass.

Your checks, and the checks of the workflow

Your project's tests and linters are one list; the tests of the workflow scripts are another. See project checks and workflow checks.

Learning from your runs

Every run leaves a record of what it took, so that you can see where the time and the tokens go, and which problems keep coming back. The scripts and the agent adapter keep it; no agent estimates anything, and nothing leaves your machine unless you ask for it (what is recorded on your machine).

Some care is built in, so that the numbers do not mislead:

• Tokens an agent did not report are unknown, not zero: a total says "at least" when some are missing. A feature without any record is named, not counted as zero.
• The elapsed time is the time something ran; the agent time is the sum of the agent calls, which is higher when work ran side by side.
• A comparison names what differs between the features: the template version, the prompts, the configuration, and the models. It also says that a difference between totals or averages does not show its cause.
• An analysis cites the runs and observations every conclusion rests on. One observation never becomes a rule, a finding needs at least two runs, and "not enough evidence" is a valid outcome. An observation that an earlier analysis already used is not counted again as new.

An analysis changes nothing in your repository. Each proposal says where it belongs: a decision record, an agent instruction, a skill, the documentation, a check in a script, an issue, or the workflow template. A project cannot repair the workflow scripts itself, because it takes them over from the template; a proposal about them is an issue for the template. You decide what to do with a proposal, and it goes through the review that applies there. Records and analyses never stop a feature: a record that cannot be written is reported, and the work goes on.

Every step in detail

Stage 1 · Plan the project

Stage 2 · Build each feature

Reference documentation

• Workflow specification: the detailed process and who is responsible for what.
• Development guide: every command and option.
• Worked example: one project from planning to a finished feature.