claude-archeflow-plugin/skills/sprint/SKILL.md

name, description

name	description
sprint	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:

./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