How Capy works
One agent.
Fourteen hats.
There is one agent here, called Capy, and it is not a team in a trench coat. What changes between planning your request, writing the migration, designing the screen and shipping it is which hat Capy is wearing — which skills it brings, and which written contract it works to. Fourteen hats, every one editable, so the expertise applied to a job is something you can actually change.
The hats
The fourteen hats
Not a roster of people, and not agents queuing to be assigned. Each of these is a set of skills and a written contract Capy works to when the job calls for it.
Assists you
Assists you
Product
Product
Software
Software
Software
Software
Operations
Design
Software
Software
Marketing
Marketing
Two of them are about how much you hand over — the assistant that talks things through, and full execution for when you would rather it just went and did it. The rest are the expertise it brings to the work itself. Any hat can be flagged as requiring your review before what it produced goes anywhere.
One run, six phases
How Capy works a task
The same execution cycle every time, whichever hat is on. You can watch it happen: run streaming shows the commands and the output as they arrive.
Observe
Read the task, the request behind it, the contract for the role, and the state of the repository it has been given.
Analyse
Work out what the change actually requires, which conventions already exist, and what could go wrong if it is done carelessly.
Plan
Decide the smallest safe change and the order to make it in — before touching a file, not while explaining a mess afterwards.
Execute
Do the work on its own branch in its own worktree. Where the right answer is genuinely unclear, stop and ask a human instead of guessing.
Validate
Check the work against what the request asked for. Run what there is to run. Confirm nothing outside the task's remit has moved.
Report
Write the structured report: summary, files modified, risks, assumptions, recommendations and blockers. Then hand the branch to the gates.
The handover
Every task ends the same way
Six headings, in the same order, on every run whichever hat was on. Consistency is the entire point — a report you have to decode is a report you stop reading.
- Summary — what changed and why, in language you can forward to someone who was not watching.
- Files Modified — the surface area of the change, so you know where to look before you open the diff.
- Risks — what this could break. Written by the agent that did the work, while it still remembers.
- Assumptions — the calls it made that you might have made differently. This is usually the most valuable heading.
- Recommendations — the follow-up work it noticed and deliberately did not do.
- Blockers — why it could not finish, if it could not finish. Silence is never the answer.
## Summary
Added the 3-D Secure step to the card checkout flow for cards
issued in the EEA. Existing non-EEA payments are untouched.
## Files Modified
- app/payments/checkout.py
- app/payments/sca.py (new)
- templates/checkout/step2.html
- tests/payments/test_sca.py (new)
## Risks
- The challenge redirect adds a third-party hop to the flow.
A slow issuer will look like a slow checkout.
- Webhook retries are idempotent by payment reference only.
## Assumptions
- Cards are treated as EEA by issuer country, not by the
billing address. Confirm this matches your acquirer.
## Recommendations
- Add an alert on challenge-abandonment rate before launch.
## Blockers
- None.
The mechanics
Why the hat matters at all
If it is one agent either way, why name the hat? Because naming it is what focuses the work: a written contract, a capability the plan can ask for by name, one report shape whatever was applied, and permission to stop.
Role contracts
Every role is a document you can read
A hat is not a prompt buried in our source. It is a Markdown contract describing what that expertise covers, how it should be applied, and what it must never do. Open it. Argue with it. Change it, and the next run works to your version.
- Editable — write your conventions into the QA Engineer's contract and they apply on every task, not on the ones you remember to mention.
- Scoped — a contract says where that expertise stops. That boundary is why a copy change does not quietly turn into an architecture rewrite.
- Legible — if you want to know why an agent did something, the answer is in a document rather than in a support ticket.
## Responsibilities
- Verify the change is the smallest one that satisfies the task
- Reject unrelated modifications
- Confirm tests cover the new behaviour
## Limits
- Never implement the fix yourself — return it to the author
Capability substitution
When the hat you asked for isn't the one that fits
A plan asks for a capability, not for a person. Where the work needs expertise the named hat does not cover, Capy applies the one that does — and writes down that it did.
- Capability, not job title — the plan asks for a capability, and the hat holding it takes the task. There is no roster to check and nobody to wait for.
- Recorded, never silent — you can see that the Developer hat covered the database work, which matters when you read the diff later.
- It stops rather than stretches — if no hat genuinely covers the capability the work needs, the run halts and asks you instead of improvising.
Structured reports
The handover is the product
Specialists do not talk to each other in free text. Work moves between them as a branch plus a report with the same six headings every time, which is what lets a reviewer start reading rather than start interpreting.
- The same shape every time — one format across fourteen roles means you learn to read it once.
- Assumptions in writing — the judgement calls are stated, so disagreeing with one is a conversation rather than an archaeology exercise.
- Blockers are first-class — a task that cannot finish says why. Nothing is more expensive than plausible silence.
Added the 3-D Secure challenge step to the card payment path.
### Files Modified
- app/payments/challenge.py — new challenge handler
- app/payments/gateway.py — route into challenge
- tests/payments/test_challenge.py — 11 cases
### Risks
- Wallet payments untested against the live sandbox
### Recommendations
- Run T-06 before deploying to production
Escalation
It is allowed to stop and ask you
The most useful thing an agent can do with genuine ambiguity is refuse to resolve it alone. Capy can pause mid-run, put a question to you, and wait — the task holds until you answer.
- A question, not a guess — an agent that invents a business rule at 2am has produced work that looks finished and is not.
- Review gates are the other stop — any hat flagged as requiring review halts dependent work until a human approves, however far the rest is allowed to run.
- Escalation reaches you — questions and gates arrive at a person even on Autonomous. Autonomy changes the routine, not the exceptions.
Your side of it
How you tune it
Staff each project separately
Each project has its own set of hats and its own contracts. The marketing site and the billing service do not have to be worked the same way.
Rewrite a contract
Tighten a standard, loosen one, or add the rule your codebase has always had and never written down.
Decide who stops the line
Flag any hat as requiring human review. Work done under it then holds dependent tasks until a person approves.
Choose the model and effort
Override both per project, or for a single request that deserves more thought than the rest of the queue.
Set the autonomy level
Manual, Supervised or Autonomous. How much of the routine runs without you; never how the gates behave.
Watch a run live
Streaming shows the commands Capy runs and the output it gets back, while it is still running them.
Vocabulary
The words we use, and what they mean
We use the same terms in the product, the docs and here. If one of them means something specific, it is defined below rather than left to context.
Hat
Assists you
Worker agent
Capability vs role
Temporary responsibility
Review gate
requires_review. Dependent work waits for a human approval, at every autonomy level, with no override for urgency.Escalation
Run
Questions
About the agent itself
Why fourteen hats instead of just one very capable agent?
It is one very capable agent. The hats are how it is pointed at the right skills for the job in front of it — shipping an iOS build and writing a launch announcement need different expertise, and saying which one is being applied keeps both the work and the record legible.
Each hat is also a narrow contract, and a narrow contract is easier to read, edit and trust than one enormous set of instructions covering everything at once. Less irrelevant context also costs less to run, but that is a consequence rather than the reason.
So who reviews the work, if it is all one agent?
You do, and we are not going to dress that up. Validation is a real phase of every run with its own contract, and work done under the QA or Security hat genuinely checks the change against what was asked rather than against itself — but it is the same agent, so it is self-checking, not independent review.
The independent review is the gate you set. Flag any hat as requiring human review and dependent work stops until a person approves it, however far you have let the rest run. Every task also arrives on its own branch, so what you are approving is a diff you can read and throw away.
What does an agent see of my codebase?
The repositories connected to the project it is working on, checked out into the worktree for its own task. Not another task's working directory, and not another project's repositories.
Is my code used to train models?
No. Your repositories are cloned to run your work and nothing more. We do not train on your code, your prompts or your reports. The security page sets out where your data lives and who can reach it.
What happens if an agent gets it wrong?
The work is on its own branch, in its own worktree, and has not touched your base branch. Reject it and the branch goes away. If it reached production, the health check catches it, your rollback command runs, and an investigation opens.
Can I add a role of my own?
Yes, on any plan. A custom hat is a contract in the same Markdown format as the fourteen that ship with the product, and Capy works to it exactly the same way.
How do I know which hat did what?
Every task carries its owner, its branch and its completion report, and any capability substitution is recorded against it. The board shows the attribution without you having to reconstruct it from commits.
Want to read a contract before you sign up? Ask us for one.
Meet the team on your own codebase
Connect a repository and file one request. The Project Manager plans it, you read the plan, and nothing else moves until you say so.
No card required · Contracts are editable from day one · Manual autonomy by default