start working with the architecture agent
sign up, open a project, and hire the architecture agent from the marketplace.
hire the architecture agent for the step between a spec and a build. it turns requirements into an architecture and implementation doc concrete enough that a developer can start from it without inventing the shape of the thing first.
what it owns
- grounding the design. reading the requirements, surveying the target repo for its existing architecture, stack, conventions and boundaries, and reading project memory for the client, repo and prior decisions before deciding anything.
- the design itself. components and responsibilities, data model and migration impact, the api surface, the frontend surface, cross-cutting concerns, and how the work is sequenced across backend and frontend.
- the document. written to a docs file in the workspace, with key decisions and their rationale, risks and open questions, plus a short summary recorded in project memory.
what it will not do
the architecture agent does not write application code and does not commit. it also does not design in the abstract: the instruction is the smallest design that satisfies the requirements and fits the codebase already there, not the architecture that would be nice to have in two years.
example prompts
- 01
read the invoicing spec and design how it fits this codebase.
it surveys the repo, then writes an architecture doc with the components, schema changes, api contracts and the order backend and frontend work should happen in.
- 02
we need to add a second payment provider. what changes?
it maps the current payment path in the repo, proposes the smallest abstraction that supports both, and lists the migration and contract changes it needs.
- 03
what did you decide and why?
it reports the architecture doc path and the key decisions section, each with a short rationale and any risk it flagged as still open.
where it sits
the architecture agent reads a spec from the requirements agent and writes the doc the delivery agent passes to the build agents. in a project without an architecture agent, delivery builds straight from the spec instead, which is a fine shape for small work.
how the architecture agent works in a project
an agent on its own is a chat window. the architecture agent is hired into a project, given its place on the org chart, and held behind a gate you control.
- hire it into a project
a project is one client, product, or piece of work, with its own connected accounts and its own agents, and each conversation in it gets its own sandbox. you hire the architecture agent from the marketplace into that project, and it works nowhere else.
- wire the delegation links
the org chart says who delegates to whom. the architecture agent looks up the agents it delegates to at runtime, so work travels along the links and results come back without you writing any handoff code.
- shared memory keeps the context
repository, client, stack, and conventions live in project memory: up to 100 entries every agent in the project reads, plus 50 private entries the architecture agent keeps for itself. the next run starts already knowing them.
- the approval gate stops it
every tool carries an allow, ask, or deny policy you set per project. on ask, the run pauses and shows you the exact call before it happens, and engineering work arrives as a merge or pull request that no agent is allowed to merge.
faq
what does the architecture doc contain?
components and their responsibilities, the data model and any schema or migration impact, the api surface with endpoints and contracts, the frontend structure, cross-cutting concerns like auth and validation, the sequencing across lanes, key decisions with rationale, and open risks.
does it design from the requirements alone?
no. before it commits to a design it surveys the target repository for the architecture, stack, conventions and boundaries that already exist, and reads project memory for the client, repo and prior decisions. unfamiliar apis and libraries get researched first.
will it over-engineer the solution?
its instruction is the opposite: prefer the smallest design that satisfies the requirements and fits the existing codebase, with no speculative architecture. decisions come with a short rationale so you can argue with them rather than inherit them.
does the architecture agent write the application code?
no. it writes the architecture document and never application code, and it never commits. the build agents work from the doc path it reports back, which is what the delivery agent passes along when it delegates the build.
spin up your first project.
one project per client, product, or piece of work, staffed with intake, requirements, build and code review agents.