claude-archeflow-plugin/README.md

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

```bash
# 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:**

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

**Local development:**

```bash
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 19 skills organized by function. The `run` skill is self-contained -- no prerequisites needed.

### Core Orchestration

| Skill | Description |
|-------|-------------|
| `archeflow:run` | Self-contained PDCA orchestration -- Plan/Do/Check/Act with adaptation rules, pipeline strategy, and cycle-back |
| `archeflow:sprint` | Queue-driven parallel agent dispatch across projects (primary mode) |
| `archeflow:review` | Guardian-led code review on diff/branch/commit range |
| `archeflow:check-phase` | Shared reviewer protocol -- finding format, evidence requirements, attention filters |
| `archeflow:act-phase` | Finding collection, fix routing, exit decisions |

### Quality and Safety

| Skill | Description |
|-------|-------------|
| `archeflow:shadow-detection` | Corrective action framework -- archetype shadows, system shadows, policy boundaries |
| `archeflow:memory` | Cross-run memory that learns recurring findings and injects lessons |

### Integration

| Skill | Description |
|-------|-------------|
| `archeflow:colette-bridge` | Bridges ArcheFlow with the Colette writing platform |
| `archeflow:git-integration` | Per-phase commits, branch-per-run, rollback |
| `archeflow:multi-project` | Cross-repo orchestration with dependency DAG and shared budget |
| `archeflow:cost-tracking` | Budget enforcement, per-agent cost aggregation, model tier recommendations |

### Configuration

| Skill | Description |
|-------|-------------|
| `archeflow:domains` | Domain adapters for writing, research, and non-code workflows |
| `archeflow:custom-archetypes` | Create domain-specific roles (database reviewer, compliance auditor, etc.) |
| `archeflow:workflow-design` | Design custom workflows with per-phase archetype assignment |
| `archeflow:templates` | Template gallery for sharing workflows, teams, and setup bundles |
| `archeflow:autonomous-mode` | Unattended sessions with corrective action checkpoints |
| `archeflow:progress` | Live progress file watchable from a second terminal |
| `archeflow:presence` | User-facing output format -- show outcomes, not mechanics |

### Meta

| Skill | Description |
|-------|-------------|
| `archeflow:using-archeflow` | Session-start activation -- decision tree, workflow selection, commands |

## Library Scripts

Ten 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-decision.sh` | Log a `decision.point` (phase, archetype, input, decision, confidence) | `archeflow-decision.sh <run_id> check guardian 'diff' 'needs_changes' 0.85` |
| `archeflow-replay.sh` | Timeline + weighted what-if over recorded verdicts | `archeflow-replay.sh compare <run_id> --weights sage=2,guardian=1` |
| `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/`:

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

```yaml
# 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:

```yaml
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/`:

```markdown
# .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/`:

```yaml
# .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
├── agents/                      # 7 archetype personas (behavioral protocols)
│   ├── explorer.md, creator.md  #   Plan phase agents
│   ├── maker.md                 #   Do phase agent
│   └── guardian.md, skeptic.md, #   Check phase agents
│       trickster.md, sage.md
├── skills/                      # 19 skills (consolidated from 27)
│   ├── run/                     #   Self-contained PDCA orchestration (core)
│   ├── sprint/                  #   Queue-driven parallel agent dispatch
│   ├── review/                  #   Guardian-led code review
│   ├── check-phase/             #   Shared reviewer protocol + attention filters
│   ├── act-phase/               #   Finding collection + fix routing
│   ├── shadow-detection/        #   Corrective action framework (3 layers)
│   ├── memory/                  #   Cross-run learning
│   └── ...                      #   + 12 config/integration skills
├── lib/                         # 10 shell scripts (events, git, memory, etc.)
├── hooks/                       # Auto-activation (SessionStart)
├── examples/                    # Walkthroughs, templates, custom archetypes
└── docs/                        # Roadmap, changelog
```

Skills define behavioral rules, agents define personas, lib scripts handle tooling, hooks wire it together at session start. The `run` skill is self-contained -- it absorbed 8 previously separate skills (orchestration, plan-phase, do-phase, artifact-routing, process-log, convergence, effectiveness, attention-filters) into one 459-line operational guide.

## 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](CHANGELOG.md) for detailed release notes.

## License

MIT