diff --git a/skills/sprint/SKILL.md b/skills/sprint/SKILL.md index 0ea144d..f8222c4 100644 --- a/skills/sprint/SKILL.md +++ b/skills/sprint/SKILL.md @@ -20,16 +20,10 @@ This is the **primary operational mode** for ArcheFlow in multi-project workspac 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 +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 ``` @@ -46,21 +40,12 @@ af-sprint --project writing.colette # Only process items for this project ### Step 0: Orient -```bash -# Load queue and workspace state -QUEUE=$(cat docs/orchestra/queue.json) -MODE=$(echo "$QUEUE" | jq -r '.mode') -``` +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` -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 -``` +- `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 @@ -69,234 +54,111 @@ 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 +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). -```python -# 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 | +| 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 (feature-dev style) +### L/XL Code Task Template -For complex code tasks, give the agent a structured process instead of PDCA: +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 project at . - Task: - - 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. - - - - 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: ": ", - prompt: "You are working on project at . - Task: - - + prompt: "You are working on at . Task: 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 + - 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", - subagent_type: "general-purpose", - isolation: "worktree" # Only for L/XL tasks; S/M tasks run directly + isolation: "worktree" # Only for L/XL tasks; S/M 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: - +Update the queue after spawning: ```bash -# For each spawned task -./scripts/ws start # or manually update queue.json status to "running" -``` - -If `./scripts/ws start` doesn't exist, update queue.json directly: -```python -task["status"] = "running" -# Write back to docs/orchestra/queue.json +./scripts/ws start # or update queue.json status to "running" directly ``` ### Step 4: Collect Results -As agents complete, process their 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 -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**: - ```bash - ./scripts/ws done -r "" - # or - ./scripts/ws fail -r "" - ``` +Update: `./scripts/ws done -r ""` or `./scripts/ws fail -r ""` ### Step 5: Report and Loop -After batch completes, show sprint status: +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 (missing outline) - ✓ tool.archeflow af-review mode done (60s) - +-- 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 -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): - +When no more tasks are schedulable: 1. Update `docs/control-center.md` Handoff section -2. Run `./scripts/ws log --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 -──────────────────────────────────────────────── -``` +2. Run `./scripts/ws log --summary ""` +3. Show final report with duration, tasks completed/blocked/remaining, projects touched, commits --- ## 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 ` | Mark task completed | -| `./scripts/ws fail ` | 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 | - ---- +| 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 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. +- **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 diff --git a/skills/using-archeflow/SKILL.md b/skills/using-archeflow/SKILL.md index bf3efc6..728c35a 100644 --- a/skills/using-archeflow/SKILL.md +++ b/skills/using-archeflow/SKILL.md @@ -5,180 +5,51 @@ description: Use at session start when implementing features, reviewing code, de # ArcheFlow -- Active -Multi-agent orchestration using archetypal roles and PDCA quality cycles. - -## Session Start - -On activation, print ONE line: +On activation, print ONE line then proceed silently: ``` archeflow v0.7.0 · 25 skills · domain ``` -Where `` is auto-detected: `writing` if `colette.yaml` exists, `research` if paper/thesis files exist, `code` otherwise. Then proceed silently — no further announcement unless `archeflow:run` is invoked. +Domain auto-detected: `writing` if `colette.yaml` exists, `research` if paper/thesis files, `code` otherwise. -During runs, follow the `archeflow:presence` skill for output format: show outcomes not mechanics, one line per phase, value at the end. +## When to Use What -## IMPORTANT: When to Use What - -### Use `/af-sprint` (primary mode) when: -- User says "run the sprint", "work the queue", "go autonomous" -- Multiple tasks are pending across projects -- The workspace queue (docs/orchestra/queue.json) has pending items - -### Use `/af-review` when: -- User wants to review code before merging -- A diff, branch, or commit range needs quality check -- Security-sensitive changes need Guardian analysis - -### Use `/af-run` (deep orchestration) when: -- **Writing/research tasks** -- archetypes add value where linters don't exist -- **Security-sensitive code changes** -- auth, encryption, API keys -- **Complex multi-module refactors** with unclear approach - -### Do NOT use ArcheFlow for: -- **Single-feature code development** -- use `feature-dev` plugin or work directly -- **Simple fixes** -- just do them -- **Questions, exploration, reading** -- no code changes needed - -Choose the workflow based on risk: - -| Signal | Workflow | Command | -|--------|----------|---------| -| Small fix, low risk, single concern | `fast` | Creator --> Maker --> Guardian | -| Feature, multiple files, moderate risk | `standard` | Explorer + Creator --> Maker --> Guardian + Skeptic + Sage | -| Security-sensitive, breaking changes, public API | `thorough` | Explorer + Creator --> Maker --> All 4 reviewers | +| Need | Command | When | +|------|---------|------| +| **Work the queue** | `/af-sprint` | Multiple tasks pending across projects, "run the sprint" | +| **Deep orchestration** | `/af-run` | Writing/research tasks, security-sensitive code, complex multi-module refactors | +| **Code review** | `/af-review` | Review diff/branch/commits before merging, security-sensitive changes | +| **Single feature** | `feature-dev` or direct | Clear scope, one project -- no orchestration needed | ## When to Skip ArcheFlow -Do NOT use ArcheFlow for these -- just do them directly: +Do NOT use for: single-line fixes, questions, reading/exploring, config tweaks, git ops. -- Single-line fixes, typos, formatting -- Answering questions (no code changes) -- Reading/exploring code without making changes -- Config changes to a single file -- Git operations (commit, push, branch) +## Workflow Selection -**Mini-Reflect fallback:** Even when skipping ArcheFlow, apply a quick reflection for non-trivial single-file changes: (1) restate what you're changing, (2) name one assumption, (3) check if it could break anything. This takes ~10 seconds and catches misunderstandings before they become commits. - -## Archetypes - -| Archetype | Avatar | Virtue | Shadow | Phase | -|-----------|--------|--------|--------|-------| -| **Explorer** | 🔍 | Contextual Clarity | Rabbit Hole | Plan | -| **Creator** | 🏗️ | Decisive Framing | Over-Architect | Plan | -| **Maker** | ⚒️ | Execution Discipline | Rogue | Do | -| **Guardian** | 🛡️ | Threat Intuition | Paranoid | Check | -| **Skeptic** | 🤔 | Assumption Surfacing | Paralytic | Check | -| **Trickster** | 🃏 | Adversarial Creativity | False Alarm | Check | -| **Sage** | 📚 | Maintainability Judgment | Bureaucrat | Check | - -## PDCA Cycle - -``` -Plan --> Explorer researches, Creator proposes -Do --> Maker implements in isolated worktree -Check --> Reviewers assess in parallel (approve/reject) -Act --> All approved? Merge. Issues? Cycle back to Plan. -``` - -## Progress Indicators - -During orchestration, emit phase markers so the user can track progress: - -``` ---- ArcheFlow: ------------------------- -Workflow: standard (2 cycles max) - -🔍 [Plan] Explorer researching... done (35s) -🏗️ [Plan] Creator designing proposal... done (25s, confidence: 0.8) -⚒️ [Do] Maker implementing... done (90s, 4 files, 8 tests) -🛡️ [Check] Guardian reviewing... APPROVED -🤔 [Check] Skeptic challenging... APPROVED (1 INFO) -📚 [Check] Sage reviewing... APPROVED - [Act] All approved -- merging... merged to main - ---- Complete: 3m 10s, 1 cycle ----------------- -``` - -Update each line as agents complete. This gives the user real-time visibility without interrupting the flow. - -## Dry-Run Mode - -When the user asks "what would ArcheFlow do?" or uses `--dry-run`, show the plan without executing: - -``` -Dry run for: "Add JWT authentication" - Workflow: standard (2 cycles) - Agents: 🔍 Explorer --> 🏗️ Creator --> ⚒️ Maker --> 🛡️ Guardian + 🤔 Skeptic + 📚 Sage - Est. agents: 6 per cycle, 12 max - Worktree: yes (isolated branch) - Proceed? [y/n] -``` - -## Quick Start - -When the user gives an implementation task: - -1. Assess: does this need ArcheFlow? (see criteria above) -2. If yes: load `archeflow:orchestration` skill -3. Pick workflow (fast/standard/thorough) -4. Execute the PDCA steps from the orchestration skill -5. Emit progress indicators throughout (see above) +| Signal | Workflow | Pipeline | +|--------|----------|----------| +| Small fix, low risk | `fast` | Creator --> Maker --> Guardian | +| Feature, multi-file, moderate risk | `standard` | Explorer + Creator --> Maker --> Guardian + Skeptic + Sage | +| Security, breaking changes, public API | `thorough` | Explorer + Creator --> Maker --> All 4 reviewers | ## Available Commands | Command | What it does | |---------|-------------| -| `archeflow:run` | Automated PDCA loop -- single command to orchestrate a full run | -| `archeflow:orchestration` | Load manual PDCA execution guide | -| `archeflow:shadow-detection` | Load shadow monitoring rules | -| `archeflow:autonomous-mode` | Load autonomous/overnight session protocol | -| `archeflow:status` | Show current orchestration state (phase, cycle, active agents) | -| `archeflow:history` | Show past orchestration summaries from `.archeflow/session-log.md` | +| `/af-sprint` | Queue-driven parallel agent runner (primary mode) | +| `/af-run ` | PDCA orchestration loop (`--dry-run`, `--start-from`, `--workflow`) | +| `/af-review` | Guardian-led code review on diff/branch/range | +| `/af-status` | Current run state, active agents, findings | +| `/af-report` | Full process report for a run | +| `/af-init` | Initialize ArcheFlow in a project | +| `/af-score` | Archetype effectiveness scores | +| `/af-memory` | Cross-run lesson memory | +| `/af-fanout` | Colette book fanout via agents | +| `/af-dag` | DAG of current/last run | -### `archeflow:status` -Read `.archeflow/state.json` (if exists) and report: -- Current task, phase, and cycle -- Active agents and their status -- Findings so far (by severity) -- Time elapsed +## Mini-Reflect Fallback -### `archeflow:history` -Read `.archeflow/session-log.md` and show the last 5 orchestration summaries in compact format. - -## Skills Reference (All 24) - -### Core Orchestration -- **archeflow:run** -- Automated PDCA execution loop with `--start-from` and `--dry-run` -- **archeflow:orchestration** -- Step-by-step manual execution guide -- **archeflow:plan-phase** -- Explorer and Creator output formats and protocols -- **archeflow:do-phase** -- Maker implementation rules and worktree commit strategy -- **archeflow:check-phase** -- Shared reviewer protocols and output format -- **archeflow:act-phase** -- Post-Check decision logic: collect findings, route fixes, exit or cycle - -### Quality and Safety -- **archeflow:shadow-detection** -- Quantitative dysfunction detection and correction -- **archeflow:attention-filters** -- Context optimization per archetype -- **archeflow:convergence** -- Detects convergence, stalling, and oscillation in multi-cycle runs -- **archeflow:artifact-routing** -- Inter-phase artifact protocol for naming, storage, and routing - -### Process Intelligence -- **archeflow:process-log** -- Event-sourced JSONL logging with DAG parent relationships -- **archeflow:memory** -- Cross-run learning from recurring findings -- **archeflow:effectiveness** -- Archetype scoring on signal-to-noise, fix rate, cost efficiency -- **archeflow:progress** -- Live progress file watchable from a second terminal - -### Integration -- **archeflow:colette-bridge** -- Bridges ArcheFlow with the Colette writing platform -- **archeflow:git-integration** -- Git-per-phase commits, branch-per-run, rollback -- **archeflow:multi-project** -- Cross-repo orchestration with dependency DAG and shared budget - -### Configuration -- **archeflow:custom-archetypes** -- Create domain-specific roles -- **archeflow:workflow-design** -- Design custom workflows with per-phase archetype assignment -- **archeflow:domains** -- Domain adapters for writing, research, and non-code workflows -- **archeflow:cost-tracking** -- Budget enforcement and model tier recommendations -- **archeflow:templates** -- Template gallery for sharing workflows, teams, and setup bundles -- **archeflow:autonomous-mode** -- Unattended overnight sessions - -### Meta -- **archeflow:using-archeflow** -- This skill: session-start activation and quick reference +Even when skipping ArcheFlow, apply for non-trivial changes: +1. Restate what you're changing +2. Name one assumption +3. Check if it could break anything