# 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