Capstone: Build a Claude Repository Maintenance Agent
This capstone builds a Claude repository-maintenance agent that inspects an isolated checkout, proposes a plan, edits only approved paths, runs allowlisted verification, asks a read-only reviewer subagent for evidence, and returns a structured report. The workflow never pushes, merges, deploys, or reaches production systems; humans retain those release decisions.
What will you be able to do?
You will assemble the Claude-specific runtime controls into a verifiable job and demonstrate that it cannot escape its workspace or exceed its authority.
What is the architecture?
Rendering diagram...
Use separate phases so a planning agent cannot silently gain edit authority.
Which capabilities should each phase have?
How should you implement it?
- Create a disposable checkout at an exact commit.
- Scan for forbidden paths and secrets before agent start.
- Run a read-only planning query with a strict budget.
- Validate plan schema and policy.
- Start an edit-enabled isolated run using only approved paths/tools.
- Execute tests through a wrapper that accepts a named test target, not shell text.
- Delegate read-only review with a bounded subagent.
- Produce a structured result: changed files, test evidence, findings, usage, and trace/session IDs.
- Destroy the workspace after artifact export.
How do you verify it?
- Editing a forbidden path is blocked by hook and filesystem permission.
- Network egress to an unapproved host fails.
- A malicious repository instruction cannot enable Bash or a plugin.
- Test timeout kills child processes.
- Subagent cannot edit.
- Max turns/budget produce an explicit incomplete outcome.
- No secret appears in result, logs, or telemetry.
- The original repository and remote remain unchanged.
Production checkpoint: A human should be able to answer: which commit entered, which files were readable/writable, which commands ran, what changed, which tests passed, what the reviewer found, and why the job stopped.
How does it fail safely?
Seed path traversal, a symlink to a forbidden file, a hanging test, an injected CLAUDE.md, a flaky test, and a fake credential. Each must yield a classified, auditable outcome without escape or secret exposure.
What mistakes should you avoid?
- Letting the agent push a branch as part of the first capstone.
- Passing raw user text into a shell wrapper.
- Loading unreviewed repository plugins/skills automatically.
- Treating “tests passed” prose as evidence instead of exit records.
- Reusing writable workspaces across tenants.
Check your understanding
- Why separate plan and edit phases?
- Which verification should be host-controlled?
- What makes the final report auditable?
Expert extension
Run the capstone against a seeded benchmark of ten repository faults. Score fix correctness, unnecessary edits, sandbox violations, test evidence, review precision, latency, and cost.
Official references