Christian Nennemann
55de51aabe
sprint: 302 -> 164 lines (removed pseudocode, redundant tables, Prerequisites) using-archeflow: 185 -> 55 lines (removed archetypes table, PDCA diagram, progress indicators, dry-run example, full skills reference)
165 lines
6.3 KiB
Markdown
165 lines
6.3 KiB
Markdown
---
|
|
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.
|
|
<example>User: "af-sprint"</example>
|
|
<example>User: "Run the sprint"</example>
|
|
<example>User: "af-sprint --slots 5 --dry-run"</example>
|
|
---
|
|
|
|
# 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 <project> at <path>. Task: <description>
|
|
|
|
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: "<project>: <task-short>",
|
|
prompt: "You are working on <project> at <path>. Task: <description>
|
|
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 <task-id> # 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 <task-id> -r "<summary>"` or `./scripts/ws fail <task-id> -r "<reason>"`
|
|
|
|
### 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 "<sprint 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
|