About

Coding agents can plan a project, implement features, write tests and review changes. Using them across a whole development process raises questions they do not answer themselves.

How do you keep the requirements consistent? How do you know a change was reviewed and tested, and that the review and the tests saw the code that is merged? How do you let agents work on their own without giving up the decisions that matter? The answers are established engineering practices, applied to work with agents. Three shaped Codeyard most:

• Clear requirements reduce rework. Every plan starts with a round of questions and your approval, and every feature with the implementer's check that the Issue settles what it needs.
• Independent reviews catch what the author misses. Under the shipped risk policy, every feature is reviewed by a read-only agent of another provider before it can be committed, and every finding gets an explicit decision. A project can let low-risk features skip the review; their merge then needs the owner.
• Approval does not rest on an agent's judgement alone. Rules about what a change touches come first; the reviewer's assessment comes on top and can only make the outcome stricter.
• Not an assistant. Codeyard writes no code: Claude Code and Codex do. Codeyard is the workflow around them, in shell scripts and plain files in your repository, with no platform to host.

• Manual first. Deciding on findings, the planning loop and the unattended run were each a manual routine before they were a script.
• Evidence before automation. Recorded reviews and verification came before the command that runs a feature alone; without them an unattended run would have nothing to stop on.
• A script decides, not an agent. Whether a step succeeded, whether a review is current, what the risk level is: computed from the repository, never taken from an agent's report.
• Effort follows risk. A documentation fix and a change to the gate do not get the same treatment; high-risk work keeps every control under every profile.
• Controls only get stricter. Any source can raise a level or require approval; nothing an agent controls can lower it, and the rules are read from the base branch.
• Driven by real use. Once real work depended on the template, most changes answered something that had gone wrong, and since October the run records show what.

The ideas behind the workflow are not new: it combines established engineering practice with coding agents, inside a development process on GitHub. It started manual and automated the steps that proved useful and repeatable. Several lessons came from Physics by Construction, a project that uses this workflow and where parts of its design were tried first; a fix found there came back in PR #179.

1. A manual workflowSeptember 2026

   Instructions for agents, a few policies, a setup guide, and a rhythm of plan, act and evaluate. A feature was planned in an Issue, built in its own worktree, and read by a second agent. The first scripts took over what was the same every time; soon each review finding got an explicit decision, and the implementer fixed only what was decided.

   #5, #8, #12, #14

2. Structured planningSeptember 2026

   A planning process before the first feature: from an idea to agreed requirements, an architecture and a roadmap.

   #22

3. Records instead of reports2 October

   Checks that relied on the agent's own word (the tests passed, the review covers the current code) became records a script can check: one command for the checks, structured review and triage data tied to the reviewed version, read-only reviewers, and a planning review with an approval tied to the approved documents.

   #31, #35, #39, #42, #43, #49, #50, #51

4. Reliability from real use6–7 October

   A feature resumes from a handoff note, a passed verification is reused for unchanged content, an approved plan has a change process, a later review can read only what changed, and a project takes over template changes with a script.

   #61, #71, #74, #76, #77, #79, #81

5. Unattended runs8–10 October

   One command takes a feature from its Issue to an open pull request; it does not merge. A script, not an agent, decides whether a step succeeded and retries a temporary failure; “blocked” means only that a person has to decide; whether a change needs the owner's approval is no longer left to the agent that made it.

   #89, #90, #91, #95, #100, #101

6. Learning from runs13–21 October

   The scripts commit and close an Issue only when the implementer's completion record says the work is complete. Every run records its durations and tokens; a report, the experience of each run and an analysis by a read-only agent follow. The owner can give triage decisions directly, with an audit trail, and a feature can wait for evidence that cannot exist yet.

   #126, #136, #138, #139, #140, #164, #168

7. Effort by risk26–28 October

   Every feature gets a computed risk level that selects the models and what the review rounds require; workflow profiles make low-risk work lighter in one line. The owner's comments reach every agent of a feature, and the implementer asks before it invents an answer. Budgets measure without failing, and approval requests are tied to the content tree.

   #185, #194, #197, #198, #199, #200, #202, #211, #213, #214

8. Corrections from the first analysis27–29 October

   Agent attribution became configurable and is disabled by default; Codex may write the runtime files it needs. The five proposals of the run analysis of 28 October were built: earlier review decisions in every round, a recorded reason for every stop, timed checks, warnings about undeclared models. Test escalation was narrowed to removed or changed lines, and the owner can raise the level before the first session.

   #183, #208, #215, #222, #223, #224, #225, #228, #229

9. This website30 October

   An MIT licence, then the redesign of this site, tracked in #234.

   #244, #245, #246, #247, #248

10. The first site finished30–31 October

    Features, Examples and About written from the repository's own records; accessibility, performance and publication checked, with a guide for a rename and a custom domain; the browser check detects a missing browser instead of installing one on every run.

    #249, #251, #252

11. The product-first redesign31 October

    A product-first homepage, from the problem through the route of one feature, risk, review and the owner's gates to the records of one real feature. The workflow map became an explorer with the detail of each step, Features were organised around engineering problems and Examples by risk, and the workflow reference moved into the regrouped docs.

    #260, #261, #262, #263

12. Agent Codeyard31 October

    The site took the name Agent Codeyard, with a social preview image for every page; the repository, its URLs and the scripts kept their names, so generated projects are unaffected.

    #264

For every framework we asked one question: would this improve the workflow we have, or add complexity it does not need?

Two talks shaped the approach: Matt Pocock, “Full Walkthrough: Workflow for AI Coding”, on clarifying requirements, vertical slices and dependencies between tasks; and Eric Zakariasson, “Building your own software factory”, on isolated environments, parallel agents and better verification evidence.

Among skill collections we looked at Cloudflare's security audit skill, Trail of Bits' skills, Addy Osmani's agent skills, Anthropic's skills and Impeccable. None is bundled: a project selects the skills its work needs.

A new feature has to add clear value without making the workflow harder to use for a single developer. What exists in part is said so.

Built since the earlier list of this site: feature clarification (PR #213), a model per risk level, check groups, partial checks and budgets. What the template deliberately does not do: require a central platform, turn the roadmap into a backlog in advance, or require test-first development for every change.

maintainer

Agent Codeyard is an open-source project by Ahmet Taspinar, founder of JIDAI.

source

github.com/taspinar/agent-codeyard

licence

MIT, in LICENSE. A project created from the template chooses its own licence.

contributing

CONTRIBUTING.md: changes start from an Issue, on a feature branch, following AGENTS.md

security

SECURITY.md: report security-sensitive findings privately

open work

The Issues of the repository