Agent Codeyard

Workflow reference

Every step of the workflow: what happens, who acts, the command, what goes in and comes out, the gate, and when it stops or retries.

On this page

Plan the project

Once at the start, and again when the plan changes.

Describe the idea

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

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
Command
./scripts/start-planning.sh [name]
Inputs and outputs
  • result docs/PROJECT_REQUIREMENTS.md, approved
Gate or decision
  • your decision You approve the requirements; declining stops the planning and keeps the worktree

Create the plan

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

Review 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.

Who acts
Planning reviewer, read-only
Command
./scripts/review-planning.sh
Inputs and outputs
  • result A review round with its findings by severity
Gate or decision
  • next Address the findings, or approve the plan when there are none

Address the review findings

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
You and the planning agent
Command
./scripts/revise-planning.sh
Gate or decision
  • your decision You approve the decisions; an escalated finding needs your answer
Stops, retries and exceptions
  • repeat Review again after every change, until a round changes nothing

Approve the plan

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.md and 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

Merge the planning pull request

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

Change an approved plan

When the requirements or the direction change, write the change down in a short file. The planning agent updates the documents it touches, and the change goes through the review and your approval again. A small change to the architecture or an ADR has a lighter route.

Who acts
You and the planning agents
Command
./scripts/start-planning.sh <name> --change <file>, with --grill when the requirements change
Stops, retries and exceptions
  • small amendment ./scripts/finish-planning.sh --amend

Build each feature

For every roadmap feature, in its own branch and worktree.

Create a feature Issue

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

Implement the feature

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 --resume to 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

Run the checks

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
Command
./scripts/verify.sh
Gate or decision
  • rule The verification has to pass before a review and before the commit
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 as BUDGET, and the verification still passes

Review the code

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 --changes for 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

Decide on the findings

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.

Who acts
The triage agent proposes; step by step you approve, unattended it decides
Command
./scripts/triage-review.sh <review-json>
Inputs and outputs
  • result Recorded decisions, published on the Issue
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

Fix and review again

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
Implementer agent
Command
./scripts/apply-triage.sh <triage-json>
Gate or decision
  • next ./scripts/review-feature.sh <issue> --changes, then ./scripts/review-feature.sh <issue>

Commit the feature

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 with low: review: none is 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

Open the pull request

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

Review and merge

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.sh lists what needs you
Inputs and outputs
  • after the merge ./scripts/cleanup-worktree.sh <issue>

Run a feature unattended

One command runs the implementation, the checks, the review rounds with their triage and fixes, the commit and the pull request. It retries a temporary failure, and stops when an agent needs you or it cannot safely go on, with the reason and the command that resolves it.

Who acts
Script that coordinates the agents
Command
./scripts/run-feature.sh <issue> [--risk <level>]
Inputs and outputs
  • result An open pull request, or the reason the run stopped
Stops, retries and exceptions
  • limits Four implementer sessions, three repairs of a failed verification, five review rounds
  • important It never merges