refactor: refocus ArcheFlow as workspace orchestrator, not feature-dev competitor
- README: lead with af-sprint (parallel multi-project), af-review (post-impl quality) - Sprint skill: L/XL code tasks use feature-dev style (explore→plan→impl→self-review) instead of PDCA. Reserve PDCA for writing/research domains. - Session start: route to af-sprint/af-review/af-run based on task type - Explicitly state: for single-feature dev, use feature-dev plugin instead
This commit is contained in:
95
README.md
95
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 |
|
||||
|
||||
Reference in New Issue
Block a user