ArcheFlow -- Workspace Orchestration for Claude Code

Run parallel agent teams across your entire project portfolio. ArcheFlow reads a task queue, spawns agents across multiple projects simultaneously, collects results, commits, and keeps going. Built for developers managing 10-30 repos who want throughput, not ceremony.

Zero dependencies. No build step. Install and go.

Status: Experimental. ArcheFlow is a research prototype exploring the intersection of analytical psychology (Jungian archetypes), process engineering (PDCA cycles), and multi-agent software engineering. It is functional and actively developed, but not production-ready. APIs, skill formats, and orchestration behavior may change between versions.

What It Does

ArcheFlow solves three problems:

1. Workspace Sprint Runner (/af-sprint) -- The primary mode. Reads your task queue, picks the highest-priority items across different projects, spawns 3-5 agents in parallel, collects results, commits+pushes, and immediately starts the next batch. Turns a 25-item backlog into done work while you watch (or don't).

2. Post-Implementation Review (/af-review) -- Run security and quality review on any diff, branch, or commit range. No planning, no implementation orchestration -- just Guardian analysis of what could go wrong. The highest-ROI mode for catching design-level bugs that linters miss.

3. Deep Orchestration (/af-run) -- For complex tasks that need structured exploration, design, implementation, and multi-perspective review. Uses archetypal roles (Explorer, Creator, Maker, Guardian) through PDCA cycles. Best for security-sensitive changes, multi-module refactors, and creative writing.

When to use what

Situation	Command	Why
Work the backlog	/af-sprint	Parallel agents, maximum throughput
Review before merging	/af-review	Catch design bugs, not style nits
Complex feature (L/XL)	/af-run or feature-dev	Structured exploration + review
Simple fix (S/M)	Just do it	No orchestration overhead needed
Creative writing	/af-run --domain writing	Archetypes shine here -- no linters exist for prose

What ArcheFlow is NOT

ArcheFlow is not a feature development tool. For single-feature implementation with user interaction at every step (clarify requirements, choose architecture, review), use Claude Code's feature-dev plugin or work directly. ArcheFlow adds value through parallel execution across projects and domain-specific quality review (writing, research), not by competing with single-task development tools.

Quick Start

1. Install

From the marketplace (recommended):

# Add the marketplace (one time)
/plugin marketplace add https://git.xorwell.de/c/claude-archeflow-plugin

# Install the plugin
/plugin install archeflow@claude-archeflow-plugin

From Git URL directly:

/plugin marketplace add https://git.xorwell.de/c/claude-archeflow-plugin.git
/plugin install archeflow --scope user

Local development:

claude --plugin-dir ./archeflow

After installing, run /reload-plugins or restart Claude Code. ArcheFlow activates automatically on session start.

Verify installation

/plugin         # Opens plugin manager — check "Installed" tab
/af-status      # Should show "no active run"

Scopes

• --scope user — available in all your projects (recommended)
• --scope project — only in the current project
• --scope local — only in the current directory

2. Run your first sprint

> /af-sprint

ArcheFlow reads your task queue (docs/orchestra/queue.json), picks the highest-priority items, and spawns parallel agents:

── af-sprint: Batch 1 ──────────────────────────
  🔸 writing.colette    config parser expansion    [P2, M]  running
  🔸 product.jobradar   search API endpoint        [P3, M]  running
  🔸 tool.git-alm       SVG export + minimap       [P3, M]  running
  🔸 product.game-factory completion tracking      [P3, S]  running
────────────────────────────────────────────────

[5 min later]

── Batch 1 complete ────────────────────────────
  ✓ writing.colette    config parser              done (3m24s)
  ✓ product.jobradar   search API                 done (5m01s)
  ✓ tool.git-alm       SVG export                 done (4m30s)
  ✓ product.game-factory tracking                 done (2m15s)

4 tasks · 4 projects · all committed + pushed
Next batch: 2 items ready → dispatching...
────────────────────────────────────────────────

3. Review before merging

> /af-review --branch feat/batch-api

Guardian analyzes the diff for error handling gaps, security issues, and data loss scenarios:

── af-review: writing.colette ─────────────────
🛡️ Guardian: 2 findings (1 HIGH, 1 MEDIUM)
  [HIGH] Timeout marks variant as done — loses batch state (fanout.py:552)
  [MEDIUM] No JSON error handling on corrupted state (batch.py:310)
────────────────────────────────────────────────

4. Deep orchestration (when needed)

For complex, security-sensitive, or creative tasks:

> /af-run "Add JWT authentication" --workflow standard

This runs the full PDCA cycle with archetypal roles. See "Deep Orchestration" below for details.

The Seven Archetypes

Archetype	Phase	Virtue	Shadow	Role
🔍 Explorer	Plan	Contextual Clarity	Rabbit Hole	Researches codebase, maps dependencies, synthesizes findings
🏗️ Creator	Plan	Decisive Framing	Over-Architect	Designs solution proposals with architecture decisions and test strategy
⚒️ Maker	Do	Execution Discipline	Rogue	Implements code in an isolated git worktree, commits per phase
🛡️ Guardian	Check	Threat Intuition	Paranoid	Reviews for security vulnerabilities, reliability risks, breaking changes
🤔 Skeptic	Check	Assumption Surfacing	Paralytic	Challenges assumptions, identifies untested scenarios, proposes alternatives
🃏 Trickster	Check	Adversarial Creativity	False Alarm	Adversarial testing, boundary attacks, edge case exploitation
📚 Sage	Check	Maintainability Judgment	Bureaucrat	Holistic quality review -- code quality, test coverage, engineering judgment

Shadow detection is quantitative, not vibes. Explorer output exceeding 2000 words without a recommendation triggers Rabbit Hole. Guardian blocking three consecutive items triggers Paranoid. First detection: correction prompt. Second: replace agent. Third: escalate to user.

Skills Reference

ArcheFlow ships with 24 skills organized by function.

Core Orchestration

Skill	Description
archeflow:run	Automated PDCA execution loop -- single-command orchestration with --start-from, --dry-run, and cycle-back
archeflow:orchestration	Step-by-step PDCA execution guide for manual orchestration
archeflow:plan-phase	Explorer and Creator output formats and protocols
archeflow:do-phase	Maker implementation rules and worktree commit strategy
archeflow:check-phase	Shared reviewer protocols and output format
archeflow:act-phase	Post-Check decision logic: collect findings, route fixes, exit or cycle

Quality and Safety

Skill	Description
archeflow:shadow-detection	Quantitative dysfunction detection and automatic correction
archeflow:attention-filters	Context optimization per archetype -- each agent gets only what it needs
archeflow:convergence	Detects convergence, stalling, and oscillation in multi-cycle runs
archeflow:artifact-routing	Inter-phase artifact protocol -- naming, storage, routing, archiving

Process Intelligence

Skill	Description
archeflow:process-log	Event-sourced JSONL logging with DAG parent relationships
archeflow:memory	Cross-run memory that learns recurring findings and injects lessons
archeflow:effectiveness	Archetype scoring on signal-to-noise, fix rate, cost efficiency
archeflow:progress	Live progress file watchable from a second terminal

Integration

Skill	Description
archeflow:colette-bridge	Bridges ArcheFlow with the Colette writing platform
archeflow:git-integration	Git-per-phase commits, branch-per-run, rollback to any phase boundary
archeflow:multi-project	Cross-repo orchestration with dependency DAG and shared budget

Configuration

Skill	Description
archeflow:custom-archetypes	Create domain-specific roles (database reviewer, compliance auditor, etc.)
archeflow:workflow-design	Design custom workflows with per-phase archetype assignment and exit conditions
archeflow:domains	Domain adapters for writing, research, and other non-code workflows
archeflow:cost-tracking	Budget enforcement, per-agent cost aggregation, model tier recommendations
archeflow:templates	Template gallery for sharing workflows, teams, and setup bundles
archeflow:autonomous-mode	Unattended overnight sessions with progress logging and safe stopping

Meta

Skill	Description
archeflow:using-archeflow	Session-start skill -- activation criteria, workflow selection, quick reference

Library Scripts

Eight shell scripts in lib/ power the process infrastructure.

Script	Purpose	Usage
archeflow-event.sh	Append structured JSONL events to a run log	archeflow-event.sh <run_id> <type> <phase> <agent> '<json>'
archeflow-dag.sh	Render ASCII DAG from JSONL events	archeflow-dag.sh events.jsonl --color
archeflow-report.sh	Generate Markdown process report	archeflow-report.sh events.jsonl --output report.md --dag
archeflow-progress.sh	Regenerate live progress file from events	archeflow-progress.sh <run_id>
archeflow-score.sh	Score archetype effectiveness from completed runs	archeflow-score.sh extract events.jsonl
archeflow-memory.sh	Cross-run memory: add, list, decay, inject lessons	archeflow-memory.sh add "Always check for null"
archeflow-git.sh	Per-phase commits, branch creation, merge, rollback	archeflow-git.sh commit <run_id> <phase>
archeflow-init.sh	Template gallery: init, save, clone, list	archeflow-init.sh init writing-short-story

Workflows

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

ArcheFlow picks the workflow automatically based on task complexity, or you can specify:

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

Workflows adapt at runtime. If Guardian finds 2+ CRITICALs in a fast workflow, it escalates to standard. If reviewers find nothing in standard, it fast-paths past the remaining cycle.

Custom Workflows

Define your own workflows in .archeflow/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 }

Example: Short Fiction Workflow

ArcheFlow is not limited to code. The included kurzgeschichte workflow orchestrates short story development with custom archetypes (story-explorer, story-sage), Colette voice profile integration, and scene-by-scene commits:

# examples/workflows/kurzgeschichte.yaml
name: kurzgeschichte
team: story-development
phases:
  plan:
    archetypes: [story-explorer, creator]
  do:
    archetypes: [maker]
  check:
    archetypes: [guardian, story-sage]
  act:
    exit_when: all_approved
    max_cycles: 2

Domain Adapters

ArcheFlow defaults to code-oriented terminology, but domain adapters remap concepts for other workflows:

Domain	What Changes
code	Default. Diffs, tests, security review, merge to main.
writing	Prose quality, voice consistency, dialect authenticity. Auto-activates when colette.yaml is detected.
research	Source quality, argument coherence, citation accuracy.

Custom domains can be defined in .archeflow/domains/.

Examples

The examples/ directory contains complete walkthroughs:

• feature-implementation.md -- End-to-end feature build with standard workflow
• security-review.md -- Thorough review of security-sensitive code
• custom-workflow.yaml -- Template for defining your own workflow
• custom-archetypes/ -- Story-explorer and story-sage for fiction writing
• teams/ -- Team preset for story development
• workflows/kurzgeschichte.yaml -- Short fiction workflow with Colette integration

Configuration

Project Configuration

Create .archeflow/config.yaml in your project root:

workflow: standard          # Default workflow
budget: 50000               # Max tokens per run
git:
  enabled: true             # Per-phase commits
  merge_strategy: squash    # squash or no-ff

Custom Archetypes

Add domain-specific roles in .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?"

Team Presets

Define reusable teams in .archeflow/teams/:

# .archeflow/teams/backend-review.yaml
name: backend-review
archetypes: [explorer, creator, maker, guardian, db-specialist]

Environment Variables

• ARCHEFLOW_BUDGET -- Override default token budget
• ARCHEFLOW_WORKFLOW -- Override default workflow selection

Architecture

archeflow/
├── .claude-plugin/plugin.json   # Plugin manifest (v0.5.0)
├── agents/                      # 7 archetype personas (behavioral protocols)
│   ├── explorer.md              #   Plan: research and context mapping
│   ├── creator.md               #   Plan: solution design and proposals
│   ├── maker.md                 #   Do: implementation in isolated worktree
│   ├── guardian.md              #   Check: security and reliability review
│   ├── skeptic.md               #   Check: assumption challenging
│   ├── trickster.md             #   Check: adversarial testing
│   └── sage.md                  #   Check: holistic quality review
├── skills/                      # 24 behavioral skills
│   ├── run/                     #   Automated PDCA loop
│   ├── orchestration/           #   Manual PDCA execution guide
│   ├── plan-phase/              #   Plan protocols
│   ├── do-phase/                #   Do protocols
│   ├── check-phase/             #   Check protocols
│   ├── act-phase/               #   Act phase decision logic
│   ├── shadow-detection/        #   Dysfunction detection
│   ├── attention-filters/       #   Context optimization
│   ├── convergence/             #   Cycle convergence detection
│   ├── artifact-routing/        #   Inter-phase artifact protocol
│   ├── process-log/             #   Event-sourced JSONL logging
│   ├── memory/                  #   Cross-run learning
│   ├── effectiveness/           #   Archetype scoring
│   ├── progress/                #   Live progress file
│   ├── colette-bridge/          #   Colette writing platform bridge
│   ├── git-integration/         #   Per-phase git commits
│   ├── multi-project/           #   Cross-repo orchestration
│   ├── custom-archetypes/       #   Domain-specific roles
│   ├── workflow-design/         #   Custom workflow design
│   ├── domains/                 #   Domain adapters
│   ├── cost-tracking/           #   Budget and cost management
│   ├── templates/               #   Template gallery
│   ├── autonomous-mode/         #   Unattended sessions
│   └── using-archeflow/         #   Session-start activation
├── lib/                         # 8 shell scripts (process infrastructure)
├── hooks/                       # Auto-activation (SessionStart)
├── examples/                    # Walkthroughs, templates, custom archetypes
└── docs/                        # Roadmap, changelog

The flow: skills define behavioral rules (what agents should do), agents define personas (how they think), lib scripts handle tooling (event logging, git, reporting), and hooks wire it all together at session start. Events are emitted at every phase transition, forming a DAG that can be rendered, reported, or scored after the run.

Philosophy

1. Strength has a shadow. Every capability becomes destructive when unchecked. The Explorer who never stops researching. The Guardian who blocks everything. The Maker who ships without review. ArcheFlow names these shadows and corrects them automatically.

2. Quality is a spiral, not a gate. A single review pass misses things. PDCA cycles spiral upward -- each iteration catches what the previous one missed, until the reviewers have nothing left to find.

3. Autonomy needs structure. Agents given clear roles, typed communication, and quality gates produce exceptional work -- even overnight, even unattended.

Version History

See CHANGELOG.md for detailed release notes.

License

MIT