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. Install and it activates automatically.

Install

# 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

# 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

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

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

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