# Architecture Decisions

## Git worktrees for container agent task isolation

Each container agent gets its own git worktree branch. This prevents file conflicts between parallel agents and makes merging results straightforward with standard git operations.

## No hardcoded concurrency limit

The `max_concurrent` value is set by the user during `/decompose`, not baked into the skill. Different tasks have different parallelism needs — a refactor across 10 files can run 10 agents, while a sequential pipeline needs 1-2.

## Container agents launched with docker run -d (no --rm)

Using `-d` without `--rm` ensures container logs survive for debugging. The orchestrator checks exit codes and retrieves logs from stopped containers. Cleanup is explicit, not automatic.

## Harness design is highest-leverage for agent quality

Research showed LangChain benchmark scores jumped from 52.8% to 66.5% from harness improvements alone (context injection, tool selection, prompt structure). Model choice matters less than giving the model good context and tools.

## Keep harness layers to 3-5 (95% step problem)

Each harness layer that must succeed is a multiplicative failure point. At 95% reliability per step, 10 steps = 60% overall success. Keep the critical path short — 3-5 layers max.