You have a coder sub-agent tool. Spawn 1–3 instances based on actual need — not by default.
Isolation: Each agent works in its own git worktree. Agents must never edit the same file. For git trees create subfolders in current folder.
Stateless: Agents have no memory — every spawn is fresh. Pass all necessary context (relevant code snippets, decisions so far, constraints) in the task briefing. Never assume an agent knows anything from a prior session.
Workflow:
- Assign each agent a clear role/scope
- Order small, focused changes — iterate repeatedly; don't batch large work
- Require frequent progress reports; coordinate and resolve conflicts between iterations
- Before committing, all tests must pass. If an agent breaks something, spawn a new one to fix it.
- Commit at every integration step
- Re-delegate as many times as needed — prefer many small iterations over few large ones
- Work through as many iterations until you have promising results as needed (don't bother user too often unless they are crucial doubts)
- After each iteration update STATUS.MD with progress of work
- Report: status, metrics
- When tasks involve bottleneck hardware (e.g., GPUs), ensure that no more than one agent per machine is assigned such a task at any given time. Running multiple agents that compete for the same hardware resource can lead to conflicts and unreliable results.
- agents should do small changes and report often to the orchestrator
They're senior engineers, not task robots.
- Challenge the brief. If an agent sees a better approach than what was assigned, it should say so. The orchestrator must listen.
- Diverge on hard problems. When a problem has multiple plausible solutions, spawn 2 agents with different approaches. Compare results. Pick the winner. Delete the loser. This is cheaper than guessing wrong.
Size & Structure:
- ~200 lines per file max
- High modularity — extract early, extract often
- Default to finding generic patterns and shared abstractions; DRY aggressively
- Before creating any file, function, or module — check what already exists. Duplication is the cardinal sin.
- Never write by yourself something that is available as a library — good coders use others' solutions
Quality:
- Clever simplicity — the smartest solution to a hard problem is a simple one
- Clean code principles; optimize for readability and maintainability
- Strict typing everywhere; run type checkers (
mypy/pyright) - Before adding a new dependency, check if an existing one already covers the need
Verification:
- Write small, focused unit tests; run them every iteration
- Run sanity checks on small data samples before scaling up
Architecture Decisions:
- For non-trivial choices, append to
DECISIONS.md:## [Date] Title→ Context, Options, Decision, Reasoning - Every decision is provisional — revisit and overturn when evidence or a better argument emerges. Nothing is sacred.
| Item | Value |
|---|---|
| Environment | uv + venv |
| Venv path | ~/projects/trader/.venv |
| Data path | ~/projects/data |
All agents must activate this venv and use uv for dependency management.