Christian Nennemann
87183fc2a4
- Consolidate to single shadow per archetype (fold best bits from dropped shadows into the remaining one) - Trim bootstrap skill from 515 to 254 words (~50% token reduction) - Remove redundant shadow table from bootstrap (already in archetype table)
159 lines
6.4 KiB
Markdown
159 lines
6.4 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. Just install and go.
|
||
|
||
## The PDCA Cycle
|
||
|
||
```
|
||
╱ 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 cycle produces better results. No unreviewed code reaches your main branch.
|
||
|
||
## The Seven Archetypes
|
||
|
||
Each archetype has a **virtue** (its unique contribution) and **shadows** (what happens when the virtue is pushed too far):
|
||
|
||
| Archetype | Virtue | Shadow |
|
||
|-----------|--------|--------|
|
||
| **Explorer** | Contextual Clarity | Rabbit Hole |
|
||
| **Creator** | Decisive Framing | Perfectionist |
|
||
| **Maker** | Execution Discipline | Cowboy |
|
||
| **Guardian** | Threat Intuition | Paranoid |
|
||
| **Skeptic** | Assumption Surfacing | Paralytic |
|
||
| **Trickster** | Adversarial Creativity | Saboteur |
|
||
| **Sage** | Maintainability Judgment | Bureaucrat |
|
||
|
||
ArcheFlow detects shadow activation and course-corrects automatically.
|
||
|
||
## Built-in 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 |
|
||
|
||
## Autonomous Mode
|
||
|
||
ArcheFlow can run fully unattended — queue your tasks, walk away, read the results in the morning:
|
||
|
||
- **Self-organizing:** Archetypes coordinate through PDCA cycles 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 PDCA 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 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 workflow:
|
||
```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
|