diff --git a/README.md b/README.md index 0a0f1de..e34617c 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,37 @@ -# ArcheFlow -- Multi-Agent Orchestration for Claude Code +# ArcheFlow -- Workspace Orchestration for Claude Code -**Structured quality through archetypal collaboration.** ArcheFlow coordinates multiple Claude Code agents through PDCA cycles, where each agent embodies a Jungian archetype with defined strengths and known failure modes. +**Run parallel agent teams across your entire project portfolio.** ArcheFlow reads a task queue, spawns agents across multiple projects simultaneously, collects results, commits, and keeps going. Built for developers managing 10-30 repos who want throughput, not ceremony. Zero dependencies. No build step. Install and go. > **Status: Experimental.** ArcheFlow is a research prototype exploring the intersection of -> analytical psychology (Jungian archetypes), process engineering (Deming's PDCA cycles), and +> analytical psychology (Jungian archetypes), process engineering (PDCA cycles), and > multi-agent software engineering. It is functional and actively developed, but not production-ready. > APIs, skill formats, and orchestration behavior may change between versions. ## What It Does -Large coding tasks benefit from multiple perspectives, but "just spawn more agents" creates chaos. Agents duplicate work, miss each other's output, argue in circles, or go rogue. The problem is not intelligence -- it is coordination. +ArcheFlow solves three problems: -ArcheFlow solves this by giving each agent an *archetype*: a behavioral protocol that defines what the agent cares about, what context it receives, and how its output feeds into the next phase. Seven archetypes collaborate through **Plan-Do-Check-Act cycles**, where each iteration builds on structured feedback from the last. No unreviewed code reaches your main branch. +**1. Workspace Sprint Runner** (`/af-sprint`) -- The primary mode. Reads your task queue, picks the highest-priority items across different projects, spawns 3-5 agents in parallel, collects results, commits+pushes, and immediately starts the next batch. Turns a 25-item backlog into done work while you watch (or don't). -The key insight: archetypes are not just system prompts. Each one has a **virtue** (its unique contribution) and a **shadow** (the dysfunction it falls into when pushed too far). ArcheFlow monitors for shadow activation and course-corrects automatically -- replacing an agent that blocks everything, reining in one that researches forever, or escalating when a maker goes off-script. +**2. Post-Implementation Review** (`/af-review`) -- Run security and quality review on any diff, branch, or commit range. No planning, no implementation orchestration -- just Guardian analysis of what could go wrong. The highest-ROI mode for catching design-level bugs that linters miss. + +**3. Deep Orchestration** (`/af-run`) -- For complex tasks that need structured exploration, design, implementation, and multi-perspective review. Uses archetypal roles (Explorer, Creator, Maker, Guardian) through PDCA cycles. Best for security-sensitive changes, multi-module refactors, and creative writing. + +### When to use what + +| Situation | Command | Why | +|-----------|---------|-----| +| Work the backlog | `/af-sprint` | Parallel agents, maximum throughput | +| Review before merging | `/af-review` | Catch design bugs, not style nits | +| Complex feature (L/XL) | `/af-run` or `feature-dev` | Structured exploration + review | +| Simple fix (S/M) | Just do it | No orchestration overhead needed | +| Creative writing | `/af-run --domain writing` | Archetypes shine here -- no linters exist for prose | + +### What ArcheFlow is NOT + +ArcheFlow is not a feature development tool. For single-feature implementation with user interaction at every step (clarify requirements, choose architecture, review), use Claude Code's `feature-dev` plugin or work directly. ArcheFlow adds value through **parallel execution across projects** and **domain-specific quality review** (writing, research), not by competing with single-task development tools. ## Quick Start @@ -59,50 +75,61 @@ After installing, run `/reload-plugins` or restart Claude Code. ArcheFlow activa - `--scope project` — only in the current project - `--scope local` — only in the current directory -### 2. Run your first orchestration - -Just describe a task. ArcheFlow activates automatically for multi-file changes: +### 2. Run your first sprint ``` -> Add input validation to all API endpoints +> /af-sprint ``` -Or invoke it explicitly: +ArcheFlow reads your task queue (`docs/orchestra/queue.json`), picks the highest-priority items, and spawns parallel agents: ``` -> archeflow:run "Add JWT authentication" --workflow standard +── af-sprint: Batch 1 ────────────────────────── + 🔸 writing.colette config parser expansion [P2, M] running + 🔸 product.jobradar search API endpoint [P3, M] running + 🔸 tool.git-alm SVG export + minimap [P3, M] running + 🔸 product.game-factory completion tracking [P3, S] running +──────────────────────────────────────────────── + +[5 min later] + +── Batch 1 complete ──────────────────────────── + ✓ writing.colette config parser done (3m24s) + ✓ product.jobradar search API done (5m01s) + ✓ tool.git-alm SVG export done (4m30s) + ✓ product.game-factory tracking done (2m15s) + +4 tasks · 4 projects · all committed + pushed +Next batch: 2 items ready → dispatching... +──────────────────────────────────────────────── ``` -### 3. What happens - -ArcheFlow selects a workflow (fast, standard, or thorough) and runs a PDCA cycle: +### 3. Review before merging ``` -Plan --> Explorer researches codebase context, Creator designs a proposal -Do --> Maker implements in an isolated git worktree -Check --> Reviewers assess in parallel (Guardian, Skeptic, Sage, Trickster) -Act --> All approved? Merge. Issues found? Cycle back with structured feedback. - -Each cycle catches what the last one missed. +> /af-review --branch feat/batch-api ``` -Progress is visible in real time: +Guardian analyzes the diff for error handling gaps, security issues, and data loss scenarios: ``` ---- ArcheFlow: Add JWT authentication --------- -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 ----------------- +── af-review: writing.colette ───────────────── +🛡️ Guardian: 2 findings (1 HIGH, 1 MEDIUM) + [HIGH] Timeout marks variant as done — loses batch state (fanout.py:552) + [MEDIUM] No JSON error handling on corrupted state (batch.py:310) +──────────────────────────────────────────────── ``` +### 4. Deep orchestration (when needed) + +For complex, security-sensitive, or creative tasks: + +``` +> /af-run "Add JWT authentication" --workflow standard +``` + +This runs the full PDCA cycle with archetypal roles. See "Deep Orchestration" below for details. + ## The Seven Archetypes | Archetype | Phase | Virtue | Shadow | Role | diff --git a/skills/sprint/SKILL.md b/skills/sprint/SKILL.md index 3e70123..0ea144d 100644 --- a/skills/sprint/SKILL.md +++ b/skills/sprint/SKILL.md @@ -105,11 +105,44 @@ 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 | **Pipeline** | Spawn Agent() with af-run --strategy pipeline | -| Estimate L/XL, complex | **PDCA** | Spawn Agent() with af-run --strategy pdca | +| 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: ": ", + 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): diff --git a/skills/using-archeflow/SKILL.md b/skills/using-archeflow/SKILL.md index 7c1f969..bf3efc6 100644 --- a/skills/using-archeflow/SKILL.md +++ b/skills/using-archeflow/SKILL.md @@ -17,16 +17,27 @@ Where `` is auto-detected: `writing` if `colette.yaml` exists, `research During runs, follow the `archeflow:presence` skill for output format: show outcomes not mechanics, one line per phase, value at the end. -## IMPORTANT: When to Activate +## IMPORTANT: When to Use What -You MUST use ArcheFlow orchestration (load `archeflow:orchestration` skill and follow its steps) for any task that matches: +### 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 -- **New features** -- any feature touching 2+ files -- **Refactoring** -- structural changes across modules -- **Security-sensitive changes** -- auth, encryption, input handling, API keys -- **Bug fixes with unclear root cause** -- use Explorer to investigate first -- **Code review requests** -- spawn Guardian + relevant reviewers -- **Multi-file changes** -- anything beyond a single-file edit +### 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: