# archeflow — Multi-Agent Orchestration Plugin for Claude Code

Workspace-level orchestration: parallel agent teams across project portfolios, PDCA cycles with Jungian archetype roles, sprint runner, and post-implementation review. Installed as a Claude Code plugin.

## Tech Stack

- **Runtime:** Bash (lib scripts) + Claude Code skill system (Markdown skills)
- **No build step, no dependencies** — pure bash + markdown
- **Plugin format:** Claude Code plugin (skills/, hooks/, agents/, templates/)

## Key Commands

```bash
# Use via Claude Code slash commands:
/af-sprint          # Main mode: work the queue across projects
/af-run <task>      # Deep orchestration with PDCA cycles
/af-review          # Post-implementation security/quality review
/af-status          # Current run status
/af-init            # Initialize ArcheFlow in a project
/af-score           # Archetype effectiveness scores
/af-memory          # Cross-run lesson memory
/af-report          # Full process report
/af-fanout          # Colette book fanout via agents
```

## Architecture

```
skills/                 Slash command implementations (one dir per skill)
  sprint/               /af-sprint — queue-driven parallel agent runner
  run/                  /af-run — PDCA orchestration
  review/               /af-review — Guardian-led code review
  plan-phase/           PDCA Plan phase
  do-phase/             PDCA Do phase
  check-phase/          PDCA Check phase
  act-phase/            PDCA Act phase
  memory/               Cross-run lessons learned
  cost-tracking/        Token/cost awareness
  domains/              Domain detection (code, writing, research)
  ...                   ~25 skill directories
hooks/
  hooks.json            Hook definitions
  session-start/        Auto-activation on session start
agents/                 Archetype agent definitions
  explorer.md           Divergent thinking, research
  creator.md            Design, architecture
  maker.md              Implementation
  guardian.md            Security, risk, quality gates
  sage.md               Wisdom, patterns, trade-offs
  skeptic.md            Devil's advocate
  trickster.md          Edge cases, unconventional approaches
lib/                    Bash helper scripts (git, DAG, events, progress, etc.)
templates/bundles/      Pre-configured workflow bundles
docs/                   Roadmap, dogfood notes, test reports
```

## Domain Rules

- Skills are Markdown files with frontmatter — follow existing skill format exactly
- Agents are archetype personas — maintain their distinct voice and perspective
- Dogfood observations go to `archeflow/.archeflow/memory/lessons.jsonl`
- Cost tracking: prefer cheap models for bulk ops, expensive for creative/review
- PDCA cycle order is mandatory: Plan -> Do -> Check -> Act

## Do NOT

- Add runtime dependencies — this must stay zero-dependency
- Change archetype personalities without updating all referencing skills
- Skip the Check phase in PDCA cycles (quality gate)
- Modify hooks.json format without testing plugin reload
- Use ArcheFlow to orchestrate simple single-file tasks (overhead not justified)