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.

Prerequisites

• docs/orchestra/queue.json — task queue (managed by ./scripts/ws)
• ./scripts/ws — workspace CLI for queue operations
• Each project is a separate git repo under the workspace root

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 and workspace state
QUEUE=$(cat docs/orchestra/queue.json)
MODE=$(echo "$QUEUE" | jq -r '.mode')

Check mode:

• AUTONOM → proceed without asking
• ATTENDED → show plan, wait for user approval before each batch
• PAUSED → report status only, do not start tasks

Show one-line status:

sprint: AUTONOM · 7 pending (1×P0, 1×P2, 5×P3) · 4 slots

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:
   • Estimate task cost from estimate field: S=cheap, M=moderate, L=expensive, XL=very expensive
   • Expensive tasks (L, XL): max 2 concurrent
   • Cheap tasks (S, M): fill remaining slots
   • Target mix: 1-2 expensive + 2-3 cheap = 4-5 total
5. Slot limit: Never exceed --slots (default 4).

# Pseudocode for batch selection
batch = []
used_projects = set()
expensive_count = 0

for priority in ["P0", "P1", "P2"]:
    for task in queue_items(priority, status="pending"):
        if len(batch) >= MAX_SLOTS:
            break
        if task.project in used_projects:
            continue  # One agent per project
        if not deps_satisfied(task):
            continue
        if task.estimate in ("L", "XL"):
            if expensive_count >= 2:
                continue
            expensive_count += 1
        batch.append(task)
        used_projects.add(task.project)

Step 2: Assess and Dispatch

For each task in the batch, decide the execution strategy:

Signal	Strategy	What happens
Estimate S, clear scope	Direct	Spawn Agent() with task description, no orchestration
Estimate M, multi-file	Direct+	Spawn Agent() with task + "read code first, run tests after"
Estimate L/XL, code	Feature-dev style	Agent explores → implements → self-reviews (see below)
Estimate L/XL, writing	PDCA	Use af-run with writing domain archetypes
Task contains "validate", "test", "lint", "check"	Direct	Cheap analytical task, no orchestration
Task contains "review", "audit", "security"	Review	Spawn Guardian + relevant reviewers only

L/XL Code Task Template (feature-dev style)

For complex code tasks, give the agent a structured process instead of PDCA:

Agent(
  description: "<project>: <task-short>",
  prompt: "You are working on project <project> at <path>.
    Task: <task description>

    Follow this process:
    1. EXPLORE: Read CLAUDE.md, docs/status.md, and the relevant source files.
       Understand existing patterns before writing anything.
    2. PLAN: Identify 2-3 files to change. Write a brief plan (what, where, why).
       If ambiguous, list your assumptions.
    3. IMPLEMENT: Make the changes. Follow existing code patterns strictly.
    4. TEST: Run the project's test suite. Fix any failures.
    5. SELF-REVIEW: Before committing, re-read your diff. Check:
       - Error handling: what happens when this fails?
       - Protocol compliance: am I using the right function signatures?
       - Tests: did I test the important paths?
    6. COMMIT + PUSH: Conventional commits, signed, pushed.

    <standard rules>

    STATUS: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED"
)

This gives the agent feature-dev's structured exploration without the multi-agent overhead. For writing/research L/XL tasks, use af-run instead — archetypes add value where linters don't exist.

Agent spawn template:

For each task in the batch, spawn an Agent in the SAME message (parallel dispatch):

Agent(
  description: "<project>: <task-short>",
  prompt: "You are working on project <project> at <path>.
    Task: <task description>
    <notes if any>

    Rules:
    - Read the project's CLAUDE.md first
    - Commit with: git -c user.signingkey=/home/c/.ssh/id_ed25519_dev.pub commit
    - NO Co-Authored-By trailers
    - Conventional commits
    - Push when done: 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",
  subagent_type: "general-purpose",
  isolation: "worktree"  # Only for L/XL tasks; S/M tasks run directly
)

CRITICAL: Spawn all batch agents in a SINGLE message. This enables parallel execution. Do not spawn them sequentially.

Step 3: Mark Running

After spawning, update the queue:

# For each spawned task
./scripts/ws start <task-id>  # or manually update queue.json status to "running"

If ./scripts/ws start doesn't exist, update queue.json directly:

task["status"] = "running"
# Write back to docs/orchestra/queue.json

Step 4: Collect Results

As agents complete, process their results:

1. Parse status token from agent output (last line: STATUS: DONE|...)
2. 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
3. Update queue:

   ./scripts/ws done <task-id> -r "<summary of what was done>"
   # or
   ./scripts/ws fail <task-id> -r "<reason>"
   

Step 5: Report and Loop

After batch completes, show sprint status:

── Sprint Batch 1 ──────────────────────────────
  ✓ writing.colette    fanout run           done (45s)
  ✓ book.3sets         validation           done (30s)
  △ book.sos           meta-book concept    needs_context (missing outline)
  ✓ tool.archeflow     af-review mode       done (60s)

Queue: 3 completed, 1 blocked, 3 remaining
Next batch: 2 items ready
────────────────────────────────────────────────

Then immediately select and dispatch the next batch (Step 1). Don't wait for user input in AUTONOM mode.

Step 6: Sprint Complete

When no more tasks are schedulable (all done, blocked, or P3-only):

1. Update docs/control-center.md Handoff section
2. Run ./scripts/ws log --summary "<sprint summary>" if available
3. Show final sprint report:

── Sprint Complete ─────────────────────────────
Duration: 12 min
Tasks: 5 completed, 1 blocked, 1 remaining (P3)
Projects touched: 4
Commits: 7
────────────────────────────────────────────────

---

Mode Behavior

AUTONOM

• Dispatch immediately, no user confirmation
• Commit + push after each agent completes
• Only pause for BLOCKED tasks or budget exhaustion
• Report between batches (one-line status)

ATTENDED

• Show the selected batch before dispatching
• Wait for user to approve: "Proceed with this batch? [y/n]"
• After each batch, show results and ask: "Continue to next batch? [y/n/edit]"
• "edit" lets the user reprioritize before next batch

PAUSED

• Show queue status only
• Do not dispatch any agents
• Useful for reviewing state between sessions

---

When to Use ArcheFlow Orchestration Within Sprint

Most sprint tasks should be direct agent dispatch (no PDCA/pipeline overhead). Only escalate to full orchestration when:

Signal	Action
Task is S/M, clear scope, single project	Direct dispatch
Task is L/XL	Use pipeline or PDCA strategy
Task mentions "security", "auth", "encryption"	Add Guardian review
Task is a review/audit	Spawn reviewers only (af-review mode)
Task failed in a previous sprint	Escalate to PDCA with Explorer

The sprint runner's job is throughput, not perfection. Ship fast, fix forward.

---

Integration with Existing Tools

Tool	How sprint uses it
./scripts/ws next	Get next schedulable task
./scripts/ws done <id>	Mark task completed
./scripts/ws fail <id>	Mark task failed
./scripts/ws orient	Initial workspace overview
./scripts/ws validate	Pre-flight queue validation
git per project	Commit + push after each agent
archeflow:run	Only for L/XL tasks needing PDCA

---

Error Recovery

• Agent crashes mid-task: Mark task as failed, add error to notes, continue with next batch
• Git push fails: Log the error, do NOT retry. User will handle push conflicts manually.
• Queue file corrupted: Run ./scripts/ws validate. If invalid, stop sprint and report.
• Budget exceeded: Stop sprint, report remaining tasks and estimated cost.
• All tasks blocked: Report dependency graph, suggest which blockers to resolve first.