Skip to content
CommonAgentPublic

About

The Agent Development Lifecycle: a reference you can customize, with reference implementations of its role agents. Apache-2.0.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

The Agent Development Lifecycle

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 lifecycle is yours to customize

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.

The one requirement

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.

Building an agent in Claude Code

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.

The agents in this repository

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.

Layout

  • 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.json and skills/<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, and kit/, the check and the generators a build folder carries under .adlc/. The kit is the agents' own checks and generators, copied byte for byte by plugin/sync.mjs; node plugin/sync.mjs --check fails when a copy differs from its master.
  • checks/ holds the repository's own checks: addresses.mjs finds every network address written into an agent's scripts (Common Agent 12.6 rule 2), against known-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.

Running the tests

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.

Notes in the code

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.

License

Apache-2.0. See LICENSE and NOTICE.

About

The Agent Development Lifecycle: a reference you can customize, with reference implementations of its role agents. Apache-2.0.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages