feat: ArcheFlow — multi-agent orchestration plugin for Claude Code
Zero-dependency Claude Code plugin using Jungian archetypes as behavioral protocols for multi-agent orchestration. - 7 archetypes (Explorer, Creator, Maker, Guardian, Skeptic, Trickster, Sage) - ArcheHelix: rising PDCA quality spiral with feedback loops - Shadow detection: automatic dysfunction recognition and correction - 3 built-in workflows (fast, standard, thorough) - Autonomous mode: unattended overnight sessions with full visibility - Custom archetypes and workflows via markdown/YAML - SessionStart hook for automatic bootstrap - Examples for feature implementation and security review
This commit is contained in:
156
README.md
Normal file
156
README.md
Normal file
@@ -0,0 +1,156 @@
|
||||
# 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 the **ArcheHelix** — a rising PDCA spiral where each iteration builds on feedback from the last.
|
||||
|
||||
Zero dependencies. No build step. Just install and go.
|
||||
|
||||
## The ArcheHelix
|
||||
|
||||
```
|
||||
╱ 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
|
||||
```
|
||||
|
||||
Each turn of the helix produces better results. No unreviewed code reaches your main branch.
|
||||
|
||||
## The Seven Archetypes
|
||||
|
||||
| Archetype | Role | Shadow |
|
||||
|-----------|------|--------|
|
||||
| **Explorer** | Researches context, maps dependencies | Rabbit Hole — endless research, no synthesis |
|
||||
| **Creator** | Designs the solution | Perfectionism — infinite revision, never ships |
|
||||
| **Maker** | Implements in isolated worktree | Cowboy Coding — ships without tests |
|
||||
| **Guardian** | Security & reliability review | Paranoia — blocks everything |
|
||||
| **Skeptic** | Challenges assumptions | Paralysis — questions everything, approves nothing |
|
||||
| **Trickster** | Adversarial testing | Saboteur — breaks things without purpose |
|
||||
| **Sage** | Holistic quality review | Bureaucrat — over-documents, under-delivers |
|
||||
|
||||
Every archetype has a **shadow** — the destructive inversion of its strength. ArcheFlow detects shadow activation and course-corrects automatically.
|
||||
|
||||
## Built-in Workflows
|
||||
|
||||
| Workflow | ArcheHelix Turns | 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 |
|
||||
|
||||
## Autonomous Mode
|
||||
|
||||
ArcheFlow can run fully unattended — queue your tasks, walk away, read the results in the morning:
|
||||
|
||||
- **Self-organizing:** Archetypes coordinate through the ArcheHelix without human input
|
||||
- **Self-correcting:** Failed reviews trigger automatic revision cycles
|
||||
- **Safe:** All code stays on worktree branches until all reviewers approve
|
||||
- **Visible:** Full session log with every decision, finding, and merge
|
||||
- **Cancellable:** Stop at any time. Incomplete work stays on branches.
|
||||
- **Reversible:** Every merge is individually revertable
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
# From the plugin marketplace (when published)
|
||||
claude plugin install archeflow
|
||||
|
||||
# From Git
|
||||
claude plugin install --url https://git.xorwell.de/c/claude-archeflow-plugin
|
||||
|
||||
# Local development
|
||||
claude --plugin-dir ./archeflow
|
||||
```
|
||||
|
||||
## What's Inside
|
||||
|
||||
```
|
||||
archeflow/
|
||||
├── .claude-plugin/plugin.json # Plugin manifest
|
||||
├── skills/
|
||||
│ ├── using-archeflow/ # Bootstrap — loaded at session start
|
||||
│ ├── orchestration/ # Step-by-step ArcheHelix execution
|
||||
│ ├── plan-phase/ # Explorer + Creator protocols
|
||||
│ ├── do-phase/ # Maker implementation rules
|
||||
│ ├── check-phase/ # Reviewer protocols (all 4)
|
||||
│ ├── shadow-detection/ # Recognizing and correcting dysfunction
|
||||
│ ├── autonomous-mode/ # Unattended overnight sessions
|
||||
│ ├── custom-archetypes/ # Creating domain-specific roles
|
||||
│ └── workflow-design/ # Designing custom ArcheHelix workflows
|
||||
├── agents/
|
||||
│ ├── explorer.md # Research agent (Haiku)
|
||||
│ ├── creator.md # Design agent (Sonnet)
|
||||
│ ├── maker.md # Implementation agent (Sonnet)
|
||||
│ ├── guardian.md # Security reviewer (Sonnet)
|
||||
│ ├── skeptic.md # Assumption challenger (Sonnet)
|
||||
│ ├── trickster.md # Adversarial tester (Haiku)
|
||||
│ └── sage.md # Quality reviewer (Sonnet)
|
||||
├── hooks/
|
||||
│ ├── hooks.json # SessionStart hook config
|
||||
│ └── session-start # Bootstrap script
|
||||
└── examples/
|
||||
├── feature-implementation.md # Standard workflow walkthrough
|
||||
├── security-review.md # Thorough workflow walkthrough
|
||||
└── custom-workflow.yaml # Custom workflow template
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
ArcheFlow is **pure skills and agents** — no runtime, no server, no dependencies.
|
||||
|
||||
- **Skills** teach Claude Code *when* and *how* to orchestrate (behavioral rules)
|
||||
- **Agents** define each archetype's persona and review protocol
|
||||
- **Hooks** inject ArcheFlow context at session start automatically
|
||||
- **Git worktrees** provide isolation — each Maker works on a separate branch
|
||||
|
||||
Claude Code's native `Agent` tool spawns the archetypes. Git worktrees provide isolation. Markdown artifacts provide communication between phases. Nothing else needed.
|
||||
|
||||
## 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
|
||||
Design your own ArcheHelix configuration:
|
||||
```yaml
|
||||
# .archeflow/workflows/api-design.yaml
|
||||
archehelix:
|
||||
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. The ArcheHelix spirals 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
|
||||
Reference in New Issue
Block a user