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.

Install

# From Git
claude plugin install --url https://git.xorwell.de/c/claude-archeflow-plugin

# Local development
claude --plugin-dir ./archeflow

ArcheFlow activates automatically at session start and kicks in when you give implementation tasks.

How It Works

When you give Claude an implementation task, ArcheFlow automatically:

Assesses the task and picks a workflow (fast/standard/thorough)
Plan — Explorer researches, Creator designs a proposal
Do — Maker implements in an isolated git worktree
Check — Reviewers assess in parallel
Act — All approved? Merge. Issues? Cycle back with structured feedback.

No unreviewed code reaches your main branch. Ever.

Plan  → Explorer researches, Creator proposes
Do    → Maker implements in isolated worktree
Check → Reviewers assess in parallel (approve/reject)
Act   → All approved? Merge. Issues? Cycle back to Plan.

Each cycle catches what the last one missed.

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	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, or you can specify:

"Implement input validation for the API (use thorough workflow)"

Usage

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 workflow

> Fix the off-by-one error in pagination (use fast workflow)

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)

Dry run

> What would ArcheFlow do for "Add JWT authentication"?

Dry run for: "Add JWT authentication"
  Workflow: standard (2 cycles)
  Agents:  Explorer → Creator → Maker → Guardian + Skeptic + Sage
  Est. agents: 6 per cycle, 12 max
  Worktree: yes (isolated branch)
  Proceed? [y/n]

When ArcheFlow Activates (and When It Doesn't)

Activates for: New features (2+ files), refactoring, security changes, bug fixes with unclear root cause, code review requests.

Stays out of the way for: Single-line fixes, answering questions, exploring code, single-file configs, git operations.

Key Features

Cross-Cycle Feedback — When a reviewer rejects, findings are structured and routed to the right agent. Guardian findings go to Creator (design must change). Sage findings go to Maker (implementation refinement). Resolution is tracked across cycles.

Attention Filters — Each archetype receives only relevant context. Guardian gets the diff + risk section, not the full research report. Saves 30-50% tokens per agent.

Shadow Detection — Quantitative thresholds detect dysfunction. Explorer output >2000 words without a recommendation? Rabbit Hole. Guardian blocking everything? Paranoid. First detection: correction prompt. Second: replace agent. Third: escalate to user.

Workflow Adaptation — Workflows adjust at runtime. If Guardian finds 2+ CRITICALs in a fast workflow, it escalates to standard. If Guardian finds nothing in standard, it fast-paths past the remaining reviewers.

Parallel Teams — Run up to 3 independent tasks through their own PDCA cycles simultaneously. Each team gets its own worktree. First-finished-first-merged.

Extending ArcheFlow

Custom Archetypes

Add domain-specific roles (database reviewer, compliance auditor, etc.). Put them in your project's .archeflow/archetypes/:

# .archeflow/archetypes/db-specialist.md
---
name: db-specialist
description: Reviews database schemas and migration safety
model: sonnet
---

You are the **Database Specialist**.
Your lens: "Will this scale? Will this corrupt data?"
...

Custom Workflows

# .archeflow/workflows/api-design.yaml
name: api-design
pdca:
  plan: { archetypes: [explorer, creator] }
  do: { archetypes: [maker] }
  check: { archetypes: [guardian, skeptic, trickster] }
  act: { exit_when: all_approved, max_cycles: 2 }

See examples/ for complete examples including custom archetypes, team presets, and workflows.

Skills Reference

Skill	What it does
`archeflow:orchestration`	Step-by-step PDCA execution guide
`archeflow:shadow-detection`	Dysfunction detection and correction
`archeflow:autonomous-mode`	Unattended overnight sessions
`archeflow:plan-phase`	Explorer + Creator output formats
`archeflow:do-phase`	Maker implementation rules
`archeflow:check-phase`	Shared reviewer protocols
`archeflow:attention-filters`	Context optimization per archetype
`archeflow:custom-archetypes`	Creating domain-specific roles
`archeflow:workflow-design`	Designing custom workflows

Plugin Structure

archeflow/
├── .claude-plugin/plugin.json    # Plugin manifest
├── agents/                       # 7 archetype personas
│   ├── explorer.md
│   ├── creator.md
│   ├── maker.md
│   ├── guardian.md
│   ├── skeptic.md
│   ├── trickster.md
│   └── sage.md
├── skills/                       # 10 behavioral skills
│   ├── using-archeflow/          # Auto-loaded at session start
│   ├── orchestration/            # PDCA execution guide
│   ├── plan-phase/               # Plan phase protocols
│   ├── do-phase/                 # Do phase protocols
│   ├── check-phase/              # Check phase protocols
│   ├── shadow-detection/         # Dysfunction detection
│   ├── attention-filters/        # Context optimization
│   ├── autonomous-mode/          # Unattended sessions
│   ├── custom-archetypes/        # Creating new roles
│   └── workflow-design/          # Custom workflows
├── hooks/                        # Auto-activation
│   ├── hooks.json
│   └── session-start
├── examples/                     # Walkthroughs + templates
│   ├── feature-implementation.md
│   ├── security-review.md
│   ├── custom-workflow.yaml
│   ├── custom-archetypes/
│   ├── teams/
│   └── workflows/
└── docs/
    └── roadmap.md

Philosophy

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.
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.
Autonomy needs structure. Agents given clear roles, typed communication, and quality gates produce exceptional work — even overnight, even unattended.

License

MIT