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 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

# 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
│   ├── agent-diagnostic/            # 3-Sets analysis for agent configuration
│   ├── 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.):

# .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:

# .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 }

Agent Diagnostic — The 3-Sets Lens

Before orchestrating, ArcheFlow diagnoses each agent across three dimensions:

Set	Question	Fix
Tool-Set	Does the agent have the right capabilities?	Add missing tools, remove noisy ones
Skill-Set	Is the model tier matched to the task?	Adjust model, don't compensate with tools
Mind-Set	Is the archetype prompt focused and aligned?	Sharpen prompt, don't compensate with model

The chain principle: The weakest set caps the output. An Opus model with a vague prompt wastes money. A Haiku with a focused archetype and the right tools outperforms it at 1/50th the cost.

The alignment principle: Three modestly configured agents that are aligned outperform three individually excellent but misaligned agents.

Based on the 3-Sets Method — an integrative diagnostic framework for Tool-Set, Skill-Set, and Mind-Set alignment.

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.

4. Fix the weakest set, not the strongest. Don't upgrade the model when the problem is a bad prompt. Don't add tools when the problem is wrong model tier. Diagnose first, then invest where it matters.

License

MIT