The Agent Development Lifecycle (ADLC) is the ordinary software lifecycle, written for work that agents do. It runs from deciding what an agent should do, through writing, testing, packaging, deploying and proving it, to updating it and finally retiring it. Each stage names the role that holds it, what the stage is given, what it hands back, and how anyone can tell the stage is finished. Every handoff is a written artifact, so the next stage can start the moment the last one ends.
The lifecycle is published at agenticdevelopment.ai. This repository holds working agents for its roles.
The ADLC is a reference, not a mandate. Use it as it stands, or shape it to your organization:
- add stages your work needs, such as a legal review or a load test;
- drop stages you do not need;
- fill any role with your own agent, a vendor's agent, or a person;
- run the stages in your own order, under your own processes.
The roles are written down separately at agentroles.ai, so an agent you build can hold a role here as fully as the agents in this repository do. The processes that run the lifecycle, such as making a new agent or retiring one, are published at agentprocesses.ai.
Whatever lifecycle you run, it ends in a valid Agent Package. A package is the declaration of what the agent does and refuses, its parts, a manifest and a digest, in the open format defined at commonagent.net/package.html. The package is the shared gate: a platform that installs agents checks the package, not the path that produced it. Build your agent any way you like, and hand over a package that validates.
The ADLC plugin lets one coding assistant build an agent from a request to a package, in two phases: the spec, which the person approves, then everything else in any order, with every gate checked from the first draft. To install it, type these two lines at the Claude Code prompt, one after the other:
/plugin marketplace add CommonAgent/adlc
/plugin install adlc@adlc
A build folder the plugin lays out, and an agent repository it publishes,
carry a .claude/settings.json that names this marketplace, so Claude Code
offers the plugin to whoever opens the folder and trusts it.
On Windows, if a clone stops with "Filename too long", run
git config --global core.longpaths true and clone again.
Then /adlc:start <folder> <what the agent should do>. The folder it lays out
carries its instructions as AGENTS.md, so another coding assistant or a
person can work it the same way, and node .adlc/check.mjs says, at any
moment, which phase the folder is in and what each gate still needs. Approving the
spec is the person's: in Claude Code they type approve, and the plugin runs the
approval for them; elsewhere they run node .adlc/approve.mjs. The assistant
can do neither.
When the build has passed, node .adlc/deploy.mjs put --email <address> --name "<your name>" --own-agent <name> --repo <owner/name> puts the agent on AgentMesh, the public one unless --instance
names another. It pushes the agent to a public GitHub repository, and AgentMesh
emails the person a link whose page has one button; nothing is installed until
they press it. wait follows it until it runs, and try sends it one message
and shows the reply.
put --local runs the same agent on a local AgentMesh in Docker on your own
computer instead: the open-source Agent Messaging Server from its public
images, and the agent in a container beside it. It needs Docker and nothing
else, no account and no email; try --local sends it a message, and a model
the agent calls is reached with your own MODEL_* settings.
node .adlc/local.mjs link --email <address> --name "<your name>" links the
local mesh to AgentMesh (Agent Messaging §21.8 to §21.13): after the button in
the emailed link, the local agents are yours on AgentMesh and are reached there
by name, through one connection your computer dials out and keeps open, and
they can reach the agents there. try --via-agentmesh sends one a message from
your own agent on AgentMesh.
These are AgentMesh's own role agents, published as reference implementations. Each one holds a role on agentroles.ai. Each one can be replaced by any agent that holds the same role.
| Stage | Role | Folder | Runs on its own? |
|---|---|---|---|
| Requirements through Code, one builder | the builder (the spec writer, solution architect, test writer and code writer roles, held together) | agents/reference-builder | Yes, with the coding harness command and the ADLC plugin; the plugin's check runs every gate |
| Reverse engineering (when needed) | reverse engineer | agents/reverse-engineer | Yes, with a model endpoint (the four model settings) and git; running the code's tests is optional |
| Architecture and Design (architecture) | solution architect | agents/solution-architect | Yes, with a model endpoint (the four model settings) |
| Requirements, Architecture and Design (design) | spec writer | agents/spec-writer | Yes, with a model endpoint (the four model settings) |
| Requirements, Architecture and Design (design) | solution planner | agents/solution-planner | Yes, with a model endpoint (the four model settings) |
| Impact | impact analyst | agents/impact-analyst | Yes; filing what is owed needs the platform's ledger |
| Source | catalog | agents/catalog | The matching logic does; the agent runs inside the AgentMesh services |
| Test | test writer | agents/test-writer | Yes, with a model endpoint (the four model settings) |
| Code | code writer | agents/code-writer | Yes, with a coding harness |
| Review | code critic | agents/code-critic | Yes, with a model endpoint (the four model settings) |
| Security review | security reviewer | agents/security-reviewer | Yes; one judgment uses the model the install places, and it reviews without one |
| Package, Release | package maker | agents/package-maker | The builder does; packing a run's work needs a fleet host |
| Deploy, Update, Rollback, Reconfigure, Decommission | deployment manager | agents/deployment-manager | No, it needs an AgentMesh fleet host |
| Conformance | conformance checker | agents/conformance-checker | The checks do; the agent needs a fleet host |
| Usability (Prove, optional) | usability tester | agents/usability-tester | Yes; running an agent as a person needs an account on the platform, or its test-account key |
| Audit (Prove) | auditor | agents/agent-auditor | Yes; reading the deploy queue's records, filing debts and filing the signed report need the platform's audit key, ledger key and the auditor's signing key |
| Docs | documenter | agents/documenter | No, it runs inside the AgentMesh services |
| Docs (the documentation) | doc writer | agents/doc-writer | Yes, as a built package |
| Publish | publisher | agents/publisher | Yes, with a place to publish to |
| Monitor, Cost | watcher | agents/watcher | The report does; asking each agent needs a host that sends what it leaves and hands it the answers, and the spend needs a read-only account token |
| Incident response | incident recorder | agents/incident-recorder | Yes, as a built package |
The Architecture and Design stage has two parts, and the architecture comes
first. The solution architect, or a person, names the systems the agent
reaches and the product bound to each one in each environment, and records
every decision with its reason. The spec writer and the solution planner then
design within those systems. The rules the record applies are written down as
the stage's standard, in
standards/architecture-standard.md.
The standards/ folder holds the standing assets every Builder
reads at a version it pins: the architecture standard, the audit checklist
and the known kinds of standing asset. It also holds
standards/stages.json: the stages (Reverse
engineering, numbered 0, for code that already exists, and the 24 after it),
the starting points and the stage each enters at, the roles that hold them, which an organization may bind to the reference agent, its own
agent, a contracted supplier, a person or an outside tool, and the open
evidence formats (such as SARIF and CycloneDX) in which a holder outside the
service hands its evidence back.
agents/image is not an agent. It holds the tools the deployment manager uses to turn an Agent Package into a container image's build context, and they run with node alone.
Each folder's README says what the agent needs and states plainly anything that only runs inside AgentMesh today.
agents/<role>/holds one agent. The packages written for the lifecycle (reverse engineer, solution architect, spec writer, solution planner, test writer, code writer, code critic, publisher) are package sources: the agent's own files (agent-descriptor.json,agent-runtime-requirements.json,plugin.jsonandskills/<slug>/SKILL.md, the layout Common Agent 13.2 says a package is authored in), the scripts, their tests and their reference files. The package maker turns a source like this into an Agent Package.agents/<role>/host/holds what a fleet host needs to run that agent: its descriptor, its listing and the brain the fleet supervisor wakes per message.agents/image/holds the image tools: the emitter that turns a package into a build context, the entrypoint that answers one message in a container, the wake host a container agent sleeps behind, and the base image contexts.host/holds the one-time bootstrap that installs the package maker, the deployment manager and the conformance checker on a fleet host.env/holds the environment reader the agents and host templates use, with an example environment to copy.plugin/holds the ADLC plugin for Claude Code: its two skills, its hooks, andkit/, the check and the generators a build folder carries under.adlc/. The kit is the agents' own checks and generators, copied byte for byte byplugin/sync.mjs;node plugin/sync.mjs --checkfails when a copy differs from its master.checks/holds the repository's own checks:addresses.mjsfinds every network address written into an agent's scripts (Common Agent 12.6 rule 2), againstknown-addresses.json, the addresses written before the check, which only shrinks.
A package reaches its model through one shared caller,
agents/package-maker/shared/model-caller.mjs, copied byte for byte into each
package that calls a model. It reads MODEL_NAME, MODEL_ENDPOINT,
MODEL_KEY and MODEL_PROTOCOL from what the install places;
host/README.md says what a host sets.
Node 22 or later, and Python 3.11 or later for the package maker and the deployment manager. From the repository root:
export AGENTMESH_ENV=example
for a in reverse-engineer solution-architect spec-writer solution-planner test-writer code-writer code-critic publisher incident-recorder doc-writer impact-analyst security-reviewer watcher agent-auditor usability-tester reference-builder; do
(cd agents/$a && node --test test/*.test.mjs)
done
node --test agents/conformance-checker/test/*.test.mjs
(cd agents/deployment-manager && python3 -m unittest discover -p "test_*.py" && node --test "test/*.test.mjs")
node --test "agents/image/test/*.test.mjs"
(cd agents/package-maker && node --test connection.test.mjs request.test.mjs model-caller.test.mjs)
node --test host/test/*.test.mjs
node checks/addresses.mjs && node --test checks/test/*.test.mjs
node plugin/sync.mjs --check && node --test plugin/test/*.test.mjs
(cd agents/catalog && npm install && npm test)CI runs the same set on every push. Some suites of the package maker, the
deployment manager and the image tools build real packages from the AgentMesh
repository; their READMEs say which, and ADLC_PACKAGES points them at a
folder of packages when you have one.
The code keeps its working notes. Comments cite AgentMesh design documents
(docs/...), technical debt items by number, and dated decisions by the owner.
Those documents live in the AgentMesh repository and are not published here;
the code and its tests are the authority.