From idea to reviewed pull request.
A project is planned once. Each feature then moves through its own implementation, verification, review and approval path. Agents do the work, checks provide the evidence, and you keep the decisions and the merge.
The route of your change
Medium riskstandard profilestep by step The implementer is claude opus and the reviewer codex gpt-6-luna, an agent of another provider; the findings get the full triage. You run each script and approve the triage of every review with findings.
Select a step on the map for what happens, who acts, the command and what can go wrong.
Start with a short description of the project in your own words. It does not need every detail: the next step asks about what it leaves open.
- Who acts
- You
- Inputs and outputs
- input
docs/PROJECT_DESCRIPTION.md, or a file anywhere passed with--description
result The recorded input of the planning; no agent changes it
Nothing in the reference for this step.
In the reference: Describe the idea
Project Grill asks only the questions that materially affect the product or the technical direction: the goals, the users, the scope, the constraints. It writes the requirements as a draft; the script shows them and records them as approved only after you confirm.
- Who acts
- You and Project Grill, in the planning worktree
- Gate or decision
- your decision You approve the requirements; declining stops the planning and keeps the worktree
- Command
./scripts/start-planning.sh [name]- Inputs and outputs
- result
docs/PROJECT_REQUIREMENTS.md, approved
Nothing in the reference for this step.
In the reference: Clarify the requirements
Project Grill asks only the questions that materially affect the product or the technical direction: the goals, the users, the scope, the constraints. It writes the requirements as a draft; the script shows them and records them as approved only after you confirm.
- Who acts
- You and Project Grill, in the planning worktree
- Gate or decision
- your decision You approve the requirements; declining stops the planning and keeps the worktree
- Command
./scripts/start-planning.sh [name]- Inputs and outputs
- result
docs/PROJECT_REQUIREMENTS.md, approved
Nothing in the reference for this step.
In the reference: Clarify the requirements
A fresh planning session reads the approved requirements and proposes the architecture, a roadmap of features with IDs and dependencies, and an ADR for each technical decision that needs one.
- Who acts
- Planning agent
- Command
- The same run of
start-planning.sh - Inputs and outputs
- result
docs/architecture.md,docs/roadmap.md,docs/decisions//
- Stops, retries and exceptions
- stops if The agent fails or needs a decision from you; the worktree stays as it is
In the reference: Create the plan
An agent that cannot edit files checks the plan for missing requirements, inconsistent decisions and risks, and records its findings in a form the scripts validate.
The planning agent proposes a decision per finding: adopt, reject, defer or escalate to you. You approve the decisions, and a changed plan is reviewed again.
- Who acts
- who Planning reviewer, read-only
who You and the planning agent - Gate or decision
- next Address the findings, or approve the plan when there are none
your decision You approve the decisions; an escalated finding needs your answer
- Command
- script
./scripts/review-planning.sh
script./scripts/revise-planning.sh - Inputs and outputs
- result A review round with its findings by severity
- Stops, retries and exceptions
- repeat Review again after every change, until a round changes nothing
In the reference: Review the plan · Address the review findings
The approval is recorded with a fingerprint of the requirements and the roadmap. When either changes later, the approval is stale, and no feature Issue is created from it.
- Who acts
- You
- Command
./scripts/finish-planning.sh- Inputs and outputs
- result
docs/PLANNING_APPROVAL.mdand the planning commit
- Stops, retries and exceptions
- refused if The review is stale, the latest round has a critical or major finding, or a finding has no decision or is escalated
In the reference: Approve the plan
The approved planning is merged into main; features start from that version of the plan.
- Who acts
- You, or a maintainer by your repository's rules
- Inputs and outputs
- result The approved plan on main
Nothing in the reference for this step.
In the reference: Merge the planning pull request
Create the GitHub Issue of a roadmap feature when you are ready to build it, so that it matches the current requirements and architecture.
- Who acts
- Script, started by you
- Command
./scripts/create-feature-issue.sh <feature-id>- Inputs and outputs
- result A GitHub Issue
- Stops, retries and exceptions
- refused if The approval of the plan is missing or stale
In the reference: Create a feature Issue
The implementer works in its own branch and worktree. Its first session decides whether the feature is clear: when the Issue with your comments, the requirements, the architecture, the accepted ADRs and the code settle every decision that matters, it implements; when they do not, it changes nothing, writes its questions in the handoff note with options and a recommendation, and stops. It writes the code and the tests, runs the checks itself, and records how far the Issue is done, with evidence per acceptance criterion.
- Who acts
- Implementer agent; the model follows the risk level
- Command
./scripts/start-feature.sh <issue> [slug], or--resumeto continue- Inputs and outputs
- result Changes in the feature worktree, a completion record and a summary of the changes
- Stops, retries and exceptions
- not done if The completion record does not say complete or awaiting evidence, or the handoff note lists remaining work
blocked if The feature needs clarification or another decision of yours: answer in the handoff note or in a comment on the Issue, then resume; the next session implements
In the reference: Implement the feature
The tests, linters and builds of scripts/verify.conf. A pass is recorded for exactly the content it checked and reused while that content does not change.
- Who acts
- Verification script
- Gate or decision
- rule The verification has to pass before a review and before the commit
- Command
./scripts/verify.sh
- Stops, retries and exceptions
- fails The implementer repairs the failing check; an unattended run resumes it with the failing checks, at most three times
partial check A policy can name groups of checks for the repair rounds between the first review and the last; a partial run is never a verification, and the commit needs every check
budget A check declared as a budget measures: over its target it is reported asBUDGET, and the verification still passes
In the reference: Run the checks
An agent of another provider than the implementer, which cannot edit files, checks every acceptance criterion against the code and the tests, reports problems with their severity, and rates the impact on the architecture. The completion record is a claim; the reviewer reports one that the code does not support. Under the shipped risk policy every feature is reviewed; a project can let low-risk features skip it with low: review: none, which the light profile sets, and such a feature is committed as not reviewed.
- Who acts
- Reviewer agent, read-only
- Command
./scripts/review-feature.sh <issue>, or--changesfor the recent fixes only- Inputs and outputs
- result A review tied to the current content; a change afterwards needs a new review
- Stops, retries and exceptions
- refused if The verification does not pass, unless
--unverified "<reason>"records why; the commit still needs the checks to pass
refused if The reviewer would be of the provider that implemented
In the reference: Review the code
Each finding gets a recorded decision: fix it now, defer it to a follow-up Issue, or accept it with a reason. Critical and major findings are always fixed. For a low- or medium-risk feature the policy can ask for the light triage, which prefers to defer or accept a suggestion or a minor finding over a fix round; a high-risk feature always gets the full triage.
The implementer fixes only the findings decided as fix now, and the checks run again. The content changed, so it is reviewed again: the changes, then the complete feature.
- Who acts
- who The triage agent proposes; step by step you approve, unattended it decides
who Implementer agent - Gate or decision
- your decision Step by step you approve the decisions, or give your own with
--decisions <file>--reason "<why>"; unattended, read them on the Issue afterwards
next./scripts/review-feature.sh <issue> --changes, then./scripts/review-feature.sh <issue>
- Command
- script
./scripts/triage-review.sh <review-json>
script./scripts/apply-triage.sh <triage-json> - Inputs and outputs
- result Recorded decisions, published on the Issue
Nothing in the reference for this step.
In the reference: Decide on the findings · Fix and review again
The commit records the completion with its evidence, the verification, the review and its triage, and the risk level with its reasons. When the merge needs your approval, the commit carries an approval request that names the content tree that was verified and reviewed; it asks and records, it grants nothing.
- Who acts
- Script
- Command
./scripts/finish-feature.sh <issue> "<summary>"
- Stops, retries and exceptions
- refused if The completion record is missing or does not say complete or awaiting evidence, the verification does not pass, or the latest review is stale, does not cover the complete feature, or has a critical or major finding
without review Low risk withlow: review: noneis committed as not reviewed; the owner can also skip the review with--no-review "<reason>", which is recorded
important This step does not push or merge
In the reference: Commit the feature
The branch is pushed and the pull request opened with the evidence, the risk level and whether the merge needs your approval. CI runs the checks again. Unfinished work becomes a draft that leaves the Issue open; evidence that exists only after the merge is recorded later with ./scripts/record-post-merge.sh.
- Who acts
- Script
- Command
./scripts/publish-feature.sh <issue>- Inputs and outputs
- result An open pull request that closes the Issue when the feature is complete
Nothing in the reference for this step.
In the reference: Open the pull request
Read the pull request, its checks and the published triage before you merge. Your approval is needed when the change touches a protected path, when the reviewer rated the impact on the architecture major or breaking, or when nobody rated it, as for a feature without a review. Codeyard states and checks this; GitHub enforces it only with the rulesets and code owners you configure.
- Who acts
- You, or a maintainer by your repository's rules; no script merges
- Command
./scripts/check-guardrails.shlists what needs you- Inputs and outputs
- after the merge
./scripts/cleanup-worktree.sh <issue>
Nothing in the reference for this step.
In the reference: Review and merge
Plan the project
- Describe the ideadocs/PROJECT_DESCRIPTION.md
In your own words; no agent changes it.
- Clarify the requirementsstart-planning.sh
Project Grill asks about the goals, the users, the scope and the constraints, then drafts docs/PROJECT_REQUIREMENTS.md.
- Approve the requirementsby you
The planning goes on only after your approval.
- Create the planarchitecture, roadmap, ADRs
A fresh planning session writes docs/architecture.md, docs/roadmap.md and the ADRs that are needed.
- Review the planreview-planning.sh
An independent, read-only reviewer. With findings, revise-planning.sh proposes a decision per finding, you approve them, and the plan is reviewed again, until a round changes nothing.
- Approve the planfinish-planning.sh
Records your approval with a fingerprint of the requirements and the roadmap; a later change to them makes it stale. Refused while the review is stale or a required decision is missing.
- Merge the planning pull requestby you
The plan is on main. A later change of the plan goes through this line again: start-planning.sh <name> --change <file>.
Build each feature
- Create a feature Issuecreate-feature-issue.sh
One roadmap feature; refused while the approval of the plan is stale.
- Implement the featureclaude opus
If the Issue leaves a decision open that matters, the implementer changes nothing, writes its questions in the handoff note and stops; nothing is reviewed or committed until you answer. Answer in the note or in a comment on the Issue, then resume with start-feature.sh <issue> --resume.
- Run the checksverify.sh
If a check fails, the implementer repairs it and the checks run again.
- Review the codecodex gpt-6-luna
Another provider than the implementer, read-only: every acceptance criterion against the code and the tests, and the impact on the architecture.
- Decide on the findingsfull triage, you approve
Per finding: fix now, defer to a follow-up Issue, or accept with a reason; critical and major findings are always fixed. You approve the decisions, which are published on the Issue. Findings to fix are fixed, checked and reviewed again: the changes, then the complete feature.
- Commit the featurefinish-feature.sh
Refused unless the completion record says complete or awaiting evidence, the verification passed for this content, and the latest review is current, covers the complete feature and has no critical or major finding.
- Open the pull requestpublish-feature.sh
Pushes the branch and opens the pull request with the verification, the review, the risk level and whether the merge needs your approval; CI runs the checks again. Unfinished work becomes a draft that leaves the Issue open.
- Mergeby you
Your approval is needed when a protected path changed or the reviewer rated the impact on the architecture major or breaking. No script merges.
Step by step or unattended
From docs/development.md.
The steps are the same. What differs is who decides about the review findings, and where the run can stop. Neither way merges: the merge is always yours.
Step by step
- Review findings
- You approve the proposed decisions.
- Stepping in
- Between any two steps.
- A question
- The session ends with its questions in the handoff note.
- Result
- You move through the steps yourself.
Unattended run-feature.sh
- Review findings
- The triage agent decides and records; you read the decisions afterwards.
- Stepping in
- It retries a temporary failure, has the implementer repair a failing check, and stops when it cannot safely go on.
- A question
- The run stops with status 3 and names the handoff note.
- Result
- An open pull request, or why the run stopped. Never a merge.
Every step in detail
Moved to the documentation.
Every command, input, output, gate and stop condition, step by step, is in the workflow reference.
Plan the project: Describe the idea · Clarify the requirements · Create the plan · Review the plan · Address the review findings · Approve the plan · Merge the planning pull request · Change an approved plan
Build each feature: Create a feature Issue · Implement the feature · Run the checks · Review the code · Decide on the findings · Fix and review again · Commit the feature · Open the pull request · Review and merge · Run a feature unattended