256 lines
9.5 KiB
Markdown
256 lines
9.5 KiB
Markdown
# ArcheFlow
|
||
|
||
**Multi-agent orchestration with Jungian archetypes for Claude Code.**
|
||
|
||
ArcheFlow gives Claude Code a structured way to coordinate multiple agents through quality cycles. Instead of one agent doing everything, specialized archetypes collaborate through **PDCA cycles** — Plan, Do, Check, Act — where each iteration builds on feedback from the last.
|
||
|
||
Zero dependencies. No build step. Install and it activates automatically.
|
||
|
||
## Install
|
||
|
||
```bash
|
||
# From Git
|
||
claude plugin install --url https://git.xorwell.de/c/claude-archeflow-plugin
|
||
|
||
# Local development
|
||
claude --plugin-dir ./archeflow
|
||
```
|
||
|
||
That's it. No config needed. ArcheFlow activates automatically at session start and kicks in when you give implementation tasks.
|
||
|
||
## How It Works
|
||
|
||
When you give Claude an implementation task (feature, refactor, multi-file change), ArcheFlow automatically:
|
||
|
||
1. **Assesses the task** and picks a workflow (fast/standard/thorough)
|
||
2. **Plan** — 🔍 Explorer researches → 🏗️ Creator designs a proposal
|
||
3. **Do** — ⚒️ Maker implements in an isolated git worktree
|
||
4. **Check** — 🛡️ Guardian + 🤔 Skeptic + 📚 Sage review in parallel
|
||
5. **Act** — All approved? Merge. Issues? Cycle back with structured feedback.
|
||
|
||
No unreviewed code reaches your main branch. Ever.
|
||
|
||
```
|
||
╱ Act ──────────── Done ✓
|
||
╱ ↑
|
||
╱ Check (Guardian + Skeptic + Sage review in parallel)
|
||
╱ ↑
|
||
╱ Do (Maker implements in isolated worktree)
|
||
╱ ↑
|
||
╱ Plan (Explorer researches → Creator designs) ← Cycle 2
|
||
╱ ↑
|
||
╱ Act ─┘ (issues found → feed back)
|
||
│ ↑
|
||
│ Check
|
||
│ ↑
|
||
│ Do
|
||
│ ↑
|
||
│ Plan ← Cycle 1
|
||
```
|
||
|
||
## The Seven Archetypes
|
||
|
||
Each archetype has a **virtue** (its unique contribution) and a **shadow** (dysfunction when pushed too far). ArcheFlow detects shadows and course-corrects automatically.
|
||
|
||
| 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 |
|
||
|
||
## Workflows
|
||
|
||
| Workflow | Cycles | Archetypes | Best For |
|
||
|----------|:---:|------------|----------|
|
||
| `fast` | 1 | Creator → Maker → Guardian | Bug fixes, small changes |
|
||
| `standard` | 2 | Explorer + Creator → Maker → Guardian + Skeptic + Sage | Features, refactors |
|
||
| `thorough` | 3 | Explorer + Creator → Maker → All 4 reviewers | Security-critical, public APIs |
|
||
|
||
ArcheFlow picks the workflow automatically based on task risk, or you can specify:
|
||
|
||
```
|
||
"Implement input validation for the API (use thorough workflow)"
|
||
```
|
||
|
||
## Usage Examples
|
||
|
||
### Basic — just describe your task
|
||
```
|
||
> Add user authentication with JWT tokens
|
||
|
||
# ArcheFlow activates automatically:
|
||
# 🔍 Explorer researches auth patterns in codebase
|
||
# 🏗️ Creator designs JWT implementation
|
||
# ⚒️ Maker implements in worktree
|
||
# 🛡️ Guardian reviews for security
|
||
# 🤔 Skeptic challenges JWT assumptions
|
||
# 📚 Sage checks code quality
|
||
# → All approved → merged to main
|
||
```
|
||
|
||
### Force a specific workflow
|
||
```
|
||
> Fix the off-by-one error in pagination (use fast workflow)
|
||
```
|
||
|
||
### Load skills manually
|
||
```
|
||
> /archeflow:orchestration # Step-by-step execution guide
|
||
> /archeflow:shadow-detection # Shadow monitoring rules
|
||
> /archeflow:autonomous-mode # Overnight batch processing
|
||
```
|
||
|
||
### Autonomous mode — queue tasks and walk away
|
||
```
|
||
> Enter autonomous mode with these tasks:
|
||
> 1. "Add input validation to all API endpoints" (thorough)
|
||
> 2. "Refactor auth middleware to use JWT" (standard)
|
||
> 3. "Fix pagination bug in search results" (fast)
|
||
```
|
||
|
||
ArcheFlow processes them sequentially, logs progress to `.archeflow/session-log.md`, and stops on 3 consecutive failures.
|
||
|
||
## When ArcheFlow Activates (and When It Doesn't)
|
||
|
||
**Activates for:**
|
||
- New features touching 2+ files
|
||
- Refactoring across modules
|
||
- Security-sensitive changes
|
||
- Bug fixes with unclear root cause
|
||
- Code review requests
|
||
|
||
**Stays out of the way for:**
|
||
- Single-line fixes, typos
|
||
- Answering questions
|
||
- Reading/exploring code
|
||
- Single-file config changes
|
||
- Git operations
|
||
|
||
## Key Features
|
||
|
||
### Cross-Cycle Feedback
|
||
When a reviewer rejects, findings are structured and routed:
|
||
- Guardian/Skeptic findings → Creator (design must change)
|
||
- Sage/Trickster findings → Maker (implementation refinement)
|
||
- Resolution tracked across cycles — no regression
|
||
|
||
### Attention Filters
|
||
Each archetype receives only relevant context. Guardian gets the git diff + risk section, not the full 2000-word research. Saves 30-50% tokens per agent.
|
||
|
||
### Shadow Detection
|
||
Quantitative thresholds detect dysfunction:
|
||
- Explorer output >2000 words without recommendation? → Rabbit Hole
|
||
- Guardian CRITICAL:WARNING ratio >2:1? → Paranoid
|
||
- Maker has no tests in changeset? → Rogue
|
||
|
||
First detection: correction prompt. Second: replace agent. Third: escalate to user.
|
||
|
||
### Orchestration Metrics
|
||
Every run tracks: phases, duration, agent count, findings by severity, shadow detections.
|
||
|
||
## Debugging
|
||
|
||
### ArcheFlow isn't activating
|
||
1. Check the plugin is installed: `claude plugin list`
|
||
2. Verify the hook runs: `CLAUDE_PLUGIN_ROOT=./archeflow node ./archeflow/hooks/session-start`
|
||
3. Should output JSON with `additionalContext` containing "ArcheFlow — Active"
|
||
4. If empty output: check `skills/using-archeflow/SKILL.md` exists
|
||
|
||
### Agent isn't following its archetype
|
||
- Check the agent definition in `agents/<archetype>.md`
|
||
- Verify the orchestration skill passes correct context (see attention filters)
|
||
- Look for shadow activation — is the agent stuck in a loop?
|
||
|
||
### Worktree issues
|
||
```bash
|
||
# List active worktrees
|
||
git worktree list
|
||
|
||
# Clean up abandoned worktrees
|
||
git worktree prune
|
||
```
|
||
|
||
### Shadow false positives
|
||
If an agent is correctly doing intensive work but gets flagged:
|
||
- Explorer reading 20 files in a monorepo with scattered deps → not a rabbit hole
|
||
- Guardian blocking with 2 genuine CVEs → not paranoid
|
||
- Check the Shadow Immunity rules in `skills/shadow-detection/SKILL.md`
|
||
|
||
### Checking what ArcheFlow sees at session start
|
||
```bash
|
||
CLAUDE_PLUGIN_ROOT=./archeflow node ./archeflow/hooks/session-start | python3 -m json.tool
|
||
```
|
||
|
||
## Plugin Structure
|
||
|
||
```
|
||
archeflow/
|
||
├── .claude-plugin/plugin.json # Plugin manifest
|
||
├── agents/ # Archetype personas (7 agents)
|
||
│ ├── explorer.md 🔍
|
||
│ ├── creator.md 🏗️
|
||
│ ├── maker.md ⚒️
|
||
│ ├── guardian.md 🛡️
|
||
│ ├── skeptic.md 🤔
|
||
│ ├── trickster.md 🃏
|
||
│ └── sage.md 📚
|
||
├── skills/ # Behavioral rules (10 skills)
|
||
│ ├── using-archeflow/ # Auto-loaded at session start
|
||
│ ├── orchestration/ # Step-by-step PDCA execution
|
||
│ ├── plan-phase/ # Explorer + Creator protocols
|
||
│ ├── do-phase/ # Maker implementation rules
|
||
│ ├── check-phase/ # Reviewer protocols
|
||
│ ├── shadow-detection/ # Dysfunction detection + correction
|
||
│ ├── attention-filters/ # Context optimization per archetype
|
||
│ ├── autonomous-mode/ # Unattended overnight sessions
|
||
│ ├── custom-archetypes/ # Creating domain-specific roles
|
||
│ └── workflow-design/ # Designing custom workflows
|
||
├── hooks/ # Auto-activation
|
||
│ ├── hooks.json # SessionStart trigger
|
||
│ └── session-start # Bootstrap script (Node.js)
|
||
├── docs/ # Plans, roadmap
|
||
│ ├── roadmap.md
|
||
│ └── plan-*.md
|
||
└── examples/ # Walkthrough examples
|
||
```
|
||
|
||
## Extending ArcheFlow
|
||
|
||
### Custom Archetypes
|
||
Add domain-specific roles (database reviewer, compliance auditor, etc.):
|
||
```markdown
|
||
# .archeflow/archetypes/db-specialist.md
|
||
## Identity
|
||
**ID:** db-specialist
|
||
**Role:** Reviews database schemas and migration safety
|
||
**Lens:** "Will this scale? Will this corrupt data?"
|
||
```
|
||
|
||
### Custom Workflows
|
||
```yaml
|
||
# .archeflow/workflows/api-design.yaml
|
||
pdca:
|
||
plan: { archetypes: [explorer, creator] }
|
||
do: { archetypes: [maker] }
|
||
check: { archetypes: [guardian, skeptic, trickster] }
|
||
act: { exit_when: all_approved, max_cycles: 2 }
|
||
```
|
||
|
||
## Philosophy
|
||
|
||
ArcheFlow is built on three beliefs:
|
||
|
||
1. **Strength has a shadow.** Every capability becomes destructive when unchecked. The Explorer who won't stop researching. The Guardian who blocks everything. The Maker who ships without review. ArcheFlow names these shadows and corrects them.
|
||
|
||
2. **Quality is a spiral, not a gate.** A single review pass misses things. PDCA cycles spiral upward — each cycle catches what the previous one missed, until the reviewers have nothing left to find.
|
||
|
||
3. **Autonomy needs structure.** Agents left to their own devices produce mediocre results. Agents given clear roles, typed communication, and quality gates produce exceptional work — even overnight, even unattended.
|
||
|
||
## License
|
||
|
||
MIT
|