How to bootstrap a single-stack repository¶
Use this page when your repository has one stack, for example one Python package. You get one agent pair: a specialist and its verifier. The pair is for Claude Code and for OpenCode.
For a repository with more than one stack, see how to bootstrap a monorepo.
Before you start¶
- Install
delegate. See step 1 of the tutorial. - Work in a git repository. The examples below use a Python package.
Steps¶
1. Write the delegation document¶
The document holds the gate commands and the hotspots of the repository. The verifier brief takes the gates from the first block under the heading Verification gates.
# Delegation: the rules of this repository
## Verification gates
```bash
python3 -m pytest -rs
```
## Hotspots
Only the coordinator changes these paths:
- `docs/agents/delegation.md`
- `workflow.toml`
The engine adds two hotspots to the hotspots of each stack: `.claude/agents/` and `.opencode/agents/`. You do not list them. An agent definition is never part of the work that a run builds.
2. Write the skill with your style rules¶
Each agent preloads the skills that you name. A skill is a Markdown file in .claude/skills/<name>/SKILL.md. The bootstrap command refuses a skill that does not exist.
---
name: house-style
description: The style rules of this repository. Use when you write or change code here.
---
# House style
- A test calls the public function and checks the result.
- A function has type hints.
3. Bootstrap the pair¶
delegate bootstrap --repo . --name python \
--domain "A Python package with unit tests." \
--tier standard \
--skill house-style \
--reference docs/agents/delegation.md \
--gate-command "python3 -m pytest"
The option --gate-command is important. The verifier may run your gate command, and it may run no other build command. Give one --gate-command for each gate that the verifier must run.
The command writes these files:
- The context skill and the declaration, in
.claude/skills/python-context/. - The agents
python-specialistandpython-verifier, in.claude/agents/and in.opencode/agents/.
Run the command a second time with the same arguments. It changes no byte. See the bootstrap reference for every option, and for the output language and the tracked-file build.
4. Check the pair¶
delegate validate --claude-code .claude/agents --opencode .opencode/agents --skills-dir .claude/skills
The command prints ok and exits 0 when the files are valid. See the finding codes for the cases where it does not.
5. Commit the files¶
The engine builds each ticket in a git worktree that starts from your base branch. The worktree holds only what you committed.
6. Name the pair in a workflow¶
The workflow file names the agents that --name python made. The names are python-specialist and python-verifier.
base-branch = "main"
run-branch = "run/demo"
mode = "assure"
adapter = "claude-code"
[stacks.python]
specialist = "python-specialist"
verifier = "python-verifier"
gates = ["python3 -m pytest"]
# The engine also reserves .claude/agents/ and .opencode/agents/ in every stack.
hotspots = ["docs/agents/delegation.md", "workflow.toml"]
# The time limits of one gate run and of one agent session, in minutes.
gate-timeout = 30
agent-timeout = 90
[[tickets]]
id = "1"
text = "The export command writes a CSV file."
stack = "python"
blocked-by = []
Check the file. The command builds nothing.
The command prints the plan and the quality check of the workflow, and exits 0. A warn line of the quality check names a setting to add or change. See how to write a workflow for a run for each setting, the workflow reference for every field, and the tutorial to build the ticket.