Authoring a loop for your own repo
A consumer repo needs a pipeline file and the agent files it names, both
committed before the first run. init writes them; the layout is:
<repo>/agentic-dev-loop/pipeline.yaml
<repo>/agentic-dev-loop/sdk_agents/dev.agent.md
<repo>/agentic-dev-loop/sdk_agents/review.agent.md
<repo>/agentic-dev-loop/sdk_agents/qa.agent.md
Start with agentic-dev-loop init
init writes the onboarding surface from a bundled toolchain profile:
agentic-dev-loop/pipeline.yaml, the three agent files,
agentic-dev-loop/.engine-version (the exact installed engine version), any
missing premise files, gitignore additions, and an env-file template. It
detects solution files, package.json directories, lockfiles, README, and
AGENTS.md, asks only what detection cannot answer, and refuses to overwrite
an existing agentic-dev-loop/ directory. A consumer-authored profile file
can be passed by path instead of a bundled name.
agentic-dev-loop doctor --fast probes the host and repo before you run:
hard failures stop you here (engine pin mismatch, engine runtime
availability, API version, git repo, .env* files); warnings print and
continue. agentic-dev-loop upgrade installs the latest engine release and
rewrites the pin, so the host install and the committed pin converge in one
explicit action. Run both yourself; the CLI never runs them for you.
The agent files
Each sdk_agents/<name>.agent.md is a markdown prompt plus YAML frontmatter:
name matches a step's agent: value; tools lists the tool names the step
may use (terminal always; verdict steps also need record_verdict; a repo
can add more via extensions). A step configured with verdicts: whose agent
file does not grant record_verdict fails at load, never at routing time.
---
name: review # matches a step's `agent:` value
tools: [terminal, record_verdict]
---
# Review Agent
## WORKFLOW # numbered steps
## RULES # absolute never/always rules
## SANDBOX NOTES # the sandbox truth for THIS step
## OUTPUT # the verdict contract
Three roles, three contracts:
| Role | Verdict contract | Typical sandbox |
|---|---|---|
| dev | none - the final response is captured as the produces: summary |
rw mount, offline |
| review | record_verdict with APPROVED / NEEDS CHANGES; the prose keeps the findings for humans |
ro mount, offline |
| qa | record_verdict with PASS / FAIL; map unverifiable: UNVERIFIABLE if you want a third way |
shaped by the repo: rw + network + class: browser when it boots servers and drives a browser; ro + offline when it probes the CLI only |
Conventions that make a good agent file:
- State the sandbox truth in the prompt. Every agent file carries a
SANDBOX NOTESsection naming exactly what its step allows: mounts ro or rw, network on or off, and which gates have already run. - Gates are the source of truth - cite the record, never re-run. Review and qa never re-run builds or suites; qa maps every acceptance criterion to existing coverage and probes only the remainder.
- dev enumerates its impossible set and stops at it. List the commands the sandbox cannot run (offline package fetches, browser downloads), one attempt per command - keeps the productive loop and kills doomed retries.
- Failure output is a required fix in dev's next context. Agent verdict
steps land their failing output under Previous attempt feedback; command
gates (test, restore) land it under Mechanical gate output, with the exit
code under Verified state. Steps route
on_fail: { goto: dev, retry: true }, and the dev prompt makes every listed failure a required fix. - No git mutations, ever. The
commitstep is the single commit point.
The pipeline file
The full field reference is in the pipeline.yaml reference; this is the stage lineup and what to adapt per repo.
| Stage | Kind | Typical shape | Why |
|---|---|---|---|
| dev | agent | rw, offline | does the work; edits are untracked |
| restore | command | network + presets: [package-registries] |
fetches what dev pinned (deps_policy: open) or the locked install |
| test | command | offline is fine (warm cache) | exit code is the verdict; the source of truth |
| editor-tests | command | network + presets: [package-registries] |
frontend suites that cannot run offline; a separate step keeps its failure diagnosis and timeout independent of the backend suite |
| conformance | command | network + presets: [package-registries] |
repo-specific fitness checks |
| review | agent | ro, offline | static conformance verdict |
| qa | agent | per repo (see table above) | live-behaviour probes; inject secrets only if the probes need them |
| commit | action | host-side | the single commit point |
Adaptation checklist for a new repo:
llm:- model,base_url,api_key_env.llms:(optional) - named profiles for multi-provider lanes (keep review on the strongest model); a step opts in withllm: <name>.profile:- name a bundled profile (python,dotnet-node) or a consumer profile path.caches:- profile-supplied toolchain caches plus any run-specific dirs; caches are never synced back, and a step'ssetup:hook runs with them mounted so it can warm them.sync_excludes:- build output trees (**/bin/**,**/obj/**).secrets:- refs only, resolved from host env; each step opts in to the refs it needs.egress:-presets: [package-registries]for fetch steps;class: browser(broad-but-logged) for browser-tier qa only.deps_policy:andlockfiles:- see dependency policy.- The dev prompt's impossible set - write it for your toolchain.
additional_files:- the repo'sAGENTS.md, coding standards, design docs: shared context for every agent step.
Validate before the first run - dry-run loads and prints the resolved plan with no LLM, no Docker, no state writes:
Then commit the tooling and run for real.