claude-archeflow-plugin/README.md

# 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