---
name: sprint
description: |
Workspace sprint runner. Reads queue.json, spawns parallel agent teams across projects,
manages lifecycle (commit, push, next task), tracks progress. The main operational mode
for ArcheFlow in multi-project workspaces.
User: "af-sprint"
User: "Run the sprint"
User: "af-sprint --slots 5 --dry-run"
---
# Workspace Sprint Runner
Read the task queue, spawn parallel agents across projects, collect results, commit+push,
spawn next batch. Repeat until the queue is drained or budget is exhausted.
## When to Use
This is the **primary operational mode** for ArcheFlow in multi-project workspaces.
Use it when the user says "run the sprint", "work the queue", "go autonomous", or
invokes `af-sprint`.
Do NOT use `archeflow:run` for individual tasks within a sprint -- the sprint runner
handles task dispatch internally, using `archeflow:run` only when a task warrants
full PDCA orchestration.
## Invocation
```
af-sprint # Run sprint with defaults (4 slots, AUTONOM mode)
af-sprint --slots 5 # Max 5 parallel agents
af-sprint --dry-run # Show what would run, don't execute
af-sprint --priority P0,P1 # Only process P0 and P1 items
af-sprint --project writing.colette # Only process items for this project
```
---
## Execution Protocol
### Step 0: Orient
Load queue from `docs/orchestra/queue.json`. Check mode (`AUTONOM` / `ATTENDED` / `PAUSED`).
Show one-line status: `sprint: AUTONOM | 7 pending (1xP0, 1xP2, 5xP3) | 4 slots`
- `AUTONOM` -- proceed without asking
- `ATTENDED` -- show plan, wait for user approval before each batch
- `PAUSED` -- report status only, do not start tasks
### Step 1: Select Batch
Pick tasks for the next batch. Rules:
1. **Priority cascade**: P0 first, then P1, then P2. Never start P3 unless user explicitly includes it.
2. **Dependency check**: Skip tasks whose `depends_on` items aren't all `completed`.
3. **One agent per project**: Never run two tasks on the same project simultaneously.
4. **Cost-aware concurrency**: L/XL tasks (expensive) max 2 concurrent. Fill remaining slots with S/M tasks. Target mix: 1-2 expensive + 2-3 cheap.
5. **Slot limit**: Never exceed `--slots` (default 4).
### Step 2: Assess and Dispatch
For each task in the batch, decide the execution strategy:
| Signal | Strategy |
|--------|----------|
| Estimate S, clear scope | **Direct** -- Agent with task description, no orchestration |
| Estimate M, multi-file | **Direct+** -- Agent with "read code first, run tests after" |
| Estimate L/XL, code | **Feature-dev** -- Agent explores, plans, implements, tests, self-reviews, commits |
| Estimate L/XL, writing | **PDCA** -- Use af-run with writing domain archetypes |
| validate/test/lint/check tasks | **Direct** -- cheap analytical, no orchestration |
| review/audit/security tasks | **Review** -- spawn Guardian + relevant reviewers only |
### L/XL Code Task Template
Give the agent a structured process:
```
Agent(prompt: "You are working on at . Task:
1. EXPLORE: Read CLAUDE.md, docs/status.md, relevant source files.
2. PLAN: Identify files to change, write brief plan (what, where, why).
3. IMPLEMENT: Follow existing code patterns strictly.
4. TEST: Run project test suite, fix failures.
5. SELF-REVIEW: Re-read diff -- error handling, protocol compliance, test coverage.
6. COMMIT + PUSH: Conventional commits, signed, pushed.
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED")
```
### Agent Spawn Template
Spawn ALL batch agents in a **single message** (parallel execution). Each agent gets:
```
Agent(
description: ": ",
prompt: "You are working on at . Task:
Rules:
- Read the project's CLAUDE.md first
- Commit: git -c user.signingkey=/home/c/.ssh/id_ed25519_dev.pub commit
- NO Co-Authored-By trailers, conventional commits
- Push: GIT_SSH_COMMAND='ssh -i /home/c/.ssh/id_ed25519_dev -o IdentitiesOnly=yes' git push origin main
- Run tests if the project has them
- Report: what you did, what changed, any blockers
STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED",
isolation: "worktree" # Only for L/XL tasks; S/M run directly
)
```
### Step 3: Mark Running
Update the queue after spawning:
```bash
./scripts/ws start # or update queue.json status to "running" directly
```
### Step 4: Collect Results
Parse status token from agent output. Based on status:
- `DONE` -- mark completed, note result
- `DONE_WITH_CONCERNS` -- mark completed, log concerns for user review
- `NEEDS_CONTEXT` -- mark pending, add concern to notes, skip for now
- `BLOCKED` -- mark failed, add blocker to notes
Update: `./scripts/ws done -r ""` or `./scripts/ws fail -r ""`
### Step 5: Report and Loop
Show batch status, then **immediately select next batch** (no user prompt in AUTONOM mode):
```
-- Sprint Batch 1 --------------------------------------------------
+ writing.colette fanout run done (45s)
+ book.3sets validation done (30s)
! book.sos meta-book concept needs_context
+ tool.archeflow af-review mode done (60s)
Queue: 3 completed, 1 blocked, 3 remaining
--------------------------------------------------------------------
```
### Step 6: Sprint Complete
When no more tasks are schedulable:
1. Update `docs/control-center.md` Handoff section
2. Run `./scripts/ws log --summary ""`
3. Show final report with duration, tasks completed/blocked/remaining, projects touched, commits
---
## Mode Behavior
| Mode | Dispatch | Between batches | Stops for |
|------|----------|----------------|-----------|
| **AUTONOM** | Immediate | One-line status, no pause | BLOCKED or budget exhaustion |
| **ATTENDED** | Show batch, wait for approval | Show results, ask "Continue? [y/n/edit]" | User decision |
| **PAUSED** | No dispatch | -- | Always (status display only) |
## Error Recovery
- **Agent crash**: Mark `failed`, continue with next batch
- **Git push fails**: Log error, do NOT retry -- user handles conflicts
- **Queue corrupted**: Run `./scripts/ws validate`, stop if invalid
- **Budget exceeded**: Stop sprint, report remaining tasks and estimated cost
- **All blocked**: Report dependency graph, suggest which blockers to resolve first