Features

An agent that meets an open decision invents an answer, and the invention is then reviewed as if it were the requirement. The workflow settles the requirements before the code, once per project and again per feature.

.agents/prompts/implementer.md · Clarification, excerpt- **Clear:** implement. Write `**Clarification:** clear` into the handoff
  note, with one line on why, so that the record shows the step was taken.
- **Needs clarification:** change nothing in the repository. Write each
  question under "Open questions" in the handoff note, with the decision it
  settles and, where you can, the options and your recommendation. [...]
  Nothing is reviewed or committed until the owner answers.

Only decisions that affect the scope, the user experience, a public interface, the data model, the architecture, security, compatibility or the acceptance criteria are questions for you; names and private helpers are not. Only comments of the owner, members and collaborators reach the agents. On #16, the clarification gate itself, the owner's two comments settled the design and the run took 26 minutes from start to pull request (PR #213).

docs

Clarify the requirements, Implement the feature

built in

PR #22 (planning), #213 (clarification), #185 (your comments)

Features built in parallel drift apart unless they share one approved design. The architecture, the ADRs and the roadmap are written, reviewed and approved before the first feature starts, and every feature session reads them first.

1. Planstart-planning.sh

   The planner writes docs/architecture.md, the first ADRs and docs/roadmap.md from the agreed requirements.

2. Independent review of the planreview-planning.sh

   An agent of another provider reviews it, read-only.

3. A decision per findingrevise-planning.sh

   Every finding of the plan review gets a recorded decision.

4. Your approvalfinish-planning.sh

   Tied to the version of the documents you approved. A later change goes through review and approval again.

5. Features

   Built in parallel, each session reads the approved architecture, ADRs and roadmap first.

AGENTS.md · Source precedence1. Explicit current human instruction
2. Accepted ADRs
3. Current GitHub issue acceptance criteria
4. AGENTS.md
5. Current architecture documentation
6. Active feature plan
7. Handoff documents
8. Previous agent assumptions

If a material conflict remains, stop and report it.

An accepted ADR outranks the Issue, so a feature cannot quietly change the design: an implementer that would have to stops and reports the conflict, a new ADR enters as Proposed, and every added, changed or removed ADR needs your approval before the merge. The reviewer classifies each feature's impact on the architecture; major or breaking makes the feature high risk and needs you too.

files

docs/architecture.md, docs/decisions/, docs/roadmap.md

docs

Create the project plan, Approve the plan

built in

PR #22 (planning), #100 (the merge approval gate)

Two agents writing in one checkout overwrite each other, and an agent writing on main leaves nothing to review. Each feature is built on its own branch, in its own Git worktree beside the main checkout.

# a branch feature/<issue>-<slug> and a worktree beside the main checkout
$ ./scripts/start-feature.sh 241
# a new session continues from the handoff note, not the earlier conversation
$ ./scripts/start-feature.sh 241 --resume
# after the merge, from the primary checkout
$ ./scripts/cleanup-worktree.sh 241

• One writer per worktree. Parallel agents need separate worktrees and branches.
• Resumable. The handoff note, .agents/handoffs/<issue>.md, says what is done, in progress, remaining and rejected; the files are the truth, the note the summary.
• Prepared. An optional setup script copies ignored files, such as installed dependencies, into a new worktree.
• Cleaned up. cleanup-worktree.sh removes merged worktrees and branches, after it copied their run records.

A worktree separates working files; it is not a sandbox for databases, services or credentials. PR #249, for example, came from the branch feature/241-write-the-features-examples.

scripts

start-feature.sh, cleanup-worktree.sh

built in

PR #57 (cleanup), #71 (setup script), #77 (resume)

An agent session that ends normally says nothing about whether the work is finished. The implementer records, per acceptance criterion, whether it is met and what shows it, and one command records which content the checks passed for.

github.com/taspinar/agent-codeyard/pull/249 · excerptCompletion: complete
- met: Every statement links to or matches its source; no invented figure or testimonial. (documentation/src/pages/{features,examples,about}.astro: each feature section names its file and key with repoFile links and the PRs that built it; [...])
[...]
- met: ./scripts/verify.sh passes. (./scripts/verify.sh run as the last step of the session; result in the final message.)

Verification:
- ./scripts/verify.sh passed

verify.sh runs every check of scripts/verify.conf, and its pass is bound to a content fingerprint and reused while nothing changes. Every commit needs the full verification; a partial run of some groups, which a repair round may use, is never a verification and cannot be cited. The reviewer holds each claimed criterion against the diff, and an unsupported claim comes back as a finding.

checks

<name> [<group>]: <command> in scripts/verify.conf

fingerprint

scripts/lib/fingerprint.sh

built in

PR #74 (recorded verification), #126 (completion gate), #168 (evidence that cannot exist yet)

An agent that reviews its own work, or the work of its own model family, shares its blind spots. The reviewer of a feature comes from another provider than the implementer, runs read-only, and reviews exactly the content the verification passed for.

github.com/taspinar/agent-codeyard/issues/241#issuecomment-6531925164 · round 1, excerptReviewed tree: b619ba7025060eef51cd7cb7c53eb3513cc1161a

Verification: passed for the reviewed tree at 2026-10-30T19:37:53Z
Reviewer: codex (gpt-6-luna), read-only

[...]
### M1. Examples do not link each candidate to its source files
[...]
## Verdict

CHANGES REQUIRED

review-feature.sh refuses a review by the implementer's own provider; as shipped, Claude implements and Codex reviews. A triage agent proposes one decision per finding: FIX_NOW, DEFER with a follow-up Issue, or ACCEPT with a rationale. Critical and major findings are always fixed. The decisions are published on the Issue, and every later round receives them, so an accepted finding is not raised again as new.

enforced by

review-feature.sh (provider independence), scripts/lib/review-data.sh (findings across rounds)

docs

Review the implementation, Decide what to do with review findings

built in

PR #12 and #14 (triage), #164 (your decisions), #222 (earlier rounds)

A typo and a change to the merge gate do not deserve the same process. Every feature gets a risk level, low, medium or high, computed from what it changes; the level picks the model of each writing role and what the review rounds require.

github.com/taspinar/agent-codeyard/pull/249 · excerptRisk: medium
- documentation/src/pages/about.astro: no class of .agents/policies/risk.conf names it; the default is medium
[...]
- profile: none

Triage mode: full (the default; .agents/policies/risk.conf of the base has no 'medium: triage:' line)

Any source can raise the level; nothing lowers it. A low level exists only under profile: light, which adds a low class for documentation and process files and lets a low feature go without a review, said in the commit and the pull request, with your approval of the merge. Under both profiles every commit needs the full verification and only you merge. High always keeps every control.

key

profile: light | standard; per level, <level>: verification | review | triage: <value>

model per level

implementer@high: claude fable in agents.conf

try it

./scripts/check-risk.sh in a feature worktree prints the level and its reasons

built in

PR #194 (the level), #202 and #211 (models per level), #214 (profiles), #229 (your hint)

An unattended run has nobody to ask and nobody watching. run-feature.sh takes a feature from its Issue to an open pull request without questions, inside fixed limits, and leaves a record of every step.

• Bounded permissions. A writing agent runs under the unattended profile: anything that would ask is denied, and it gets no MCP servers or apps from your configuration. Reviewers and triage run read-only.
• Bounded effort. At most 5 review rounds in a run, and by default 4 implementer sessions, 3 retries of a failing agent call and 3 repairs of a failing verification.
• Stops instead of guesses. An agent that needs your decision ends with a BLOCKED: line and the run exits with status 3. Running the same command again continues where the feature stands.
• Never merges. The run ends at an open pull request and never removes a worktree.

.agents/records/feature-241.jsonl · run of PR #249, excerpt{"schema":"run-record/v1",[...]"time":"2026-10-30T19:27:28Z",
 "type":"agent-start","role":"implementer","profile":"unattended",
 "agent":"claude","model":"opus","level":"medium",[...]}
{"schema":"run-record/v1",[...]"time":"2026-10-30T19:37:53Z",
 "type":"verification","status":0,"seconds":14,"reused":false,[...]}
{"schema":"run-record/v1",[...]"time":"2026-10-30T19:38:09Z",
 "type":"completion-gate","check":1,"sessions":1,[...]"status":"complete",[...]}
{"schema":"run-record/v1",[...]"time":"2026-10-30T19:38:12Z",
 "type":"agent-start","role":"reviewer","profile":"read-only",
 "agent":"codex","model":"gpt-6-luna","level":"medium",[...]}

Every run leaves such a record on your machine: each step and its duration, the agent, model and level, the verification seconds, the findings and why a run stopped. report-runs.sh summarises it per feature and analyze-runs.sh lets a read-only analyst propose changes; the analysis of 28 October 2026 is how Codeyard found what to change in itself.

records

.agents/records/feature-<issue>.jsonl in the primary checkout, ignored by Git, format run-record/v1 (docs/development.md)

docs

What is recorded on your machine

built in

PR #136 to #140 (records), #223 (stops)

No script merges. The decisions that matter stay with you: the requirements, the plan, the answers to questions, and the merge, and some pull requests only you may approve.

Your approval is needed when a feature changes a protected path, when the reviewer classifies its impact on the architecture as major or breaking, or when there is no review. Always protected: every ADR, the CI workflows, the files that carry out the gate, and a changed or removed line of the check lists. The rules are read from the base branch, so a feature cannot loosen its own gate.

github.com/taspinar/agent-codeyard/pull/222 · excerptMerge approval:
- required from the project owner, for exactly this commit
[...]
- scripts/review-feature.sh: the file defines or carries out the workflow and its gate
- the independent review classified the impact on the architecture as major: [...]

checks

check-guardrails.sh locally, and the Guardrails job of guardrails.yml on every pull request

settings

GitHub setup in the docs

built in

PR #100 (the gate), #200 (approval requests and the content tree)