# archeflow — Multi-Agent Orchestration Plugin for Claude Code

PDCA quality cycles with Jungian archetype roles, corrective action framework, sprint runner, and post-implementation review. Zero dependencies — pure Bash + Markdown.

## Architecture

```
skills/              Slash commands and internal protocols (one SKILL.md per dir)
  run/               /af-run — self-contained PDCA orchestration (core skill)
  sprint/            /af-sprint — queue-driven parallel agent dispatch
  review/            /af-review — Guardian-led code review
  check-phase/       Shared reviewer protocol (used by run + review)
  act-phase/         Finding collection, fix routing, exit decisions
  shadow-detection/  Corrective action framework (archetype + system + policy)
  memory/            Cross-run lessons learned
  cost-tracking/     Token/cost awareness and budget enforcement
  domains/           Domain detection (code, writing, research)
  colette-bridge/    Writing context loader from colette.yaml
  multi-project/     Cross-repo orchestration with dependency DAG
  git-integration/   Per-phase commits, branch strategy, rollback
  templates/         Workflow/team bundle gallery
  autonomous-mode/   Unattended session protocol
  using-archeflow/   Session-start activation (auto-loaded via hook)
agents/              Archetype personality definitions (one .md per archetype)
lib/                 Bash helper scripts (events, git, memory, progress, etc.)
hooks/               Session-start hook (injects using-archeflow)
templates/bundles/   Pre-configured workflow bundles
```

## Commands

| Command | Purpose |
|---------|---------|
| `/af-run <task>` | PDCA orchestration with full agent cycle |
| `/af-sprint` | Work the queue across projects |
| `/af-review` | Review existing code changes |
| `/af-status` | Current/last 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 |

## Core Concepts

### PDCA Cycle
```
Plan (Explorer + Creator) -> Do (Maker in worktree) -> Check (Guardian first, then others) -> Act (fix, merge, or cycle)
```

### Archetypes
Explorer (research), Creator (design), Maker (implement), Guardian (security), Skeptic (assumptions), Trickster (edge cases), Sage (quality). Each has a virtue and a shadow — see `shadow-detection` skill.

### Corrective Action Framework
Three layers, one escalation protocol:
- **Archetype shadows** — individual agent dysfunction
- **System shadows** — orchestration-level issues (echo chamber, tunnel vision, scope creep)
- **Policy boundaries** — operational limits (checkpoints, budgets, circuit breakers)

### Workflows
| Risk Level | Workflow | Agents |
|------------|----------|--------|
| Low | `fast` | Creator -> Maker -> Guardian |
| Medium | `standard` | Explorer + Creator -> Maker -> Guardian + Skeptic + Sage |
| High | `thorough` | Explorer + Creator -> Maker -> All 4 reviewers |

## Guardrails

### DO

- Keep skills self-contained. The `run` skill needs zero prerequisites — it was consolidated for a reason.
- Write skills as operational instructions Claude can follow, not software specifications.
- Use tables for reference data, numbered steps for protocols.
- Emit events via `./lib/archeflow-event.sh` — but never let logging block orchestration.
- Maintain the corrective action framework when adding new agent types.
- Test skill changes by running `/af-run --dry-run` and verifying the flow.
- Keep archetype personalities distinct — each agent definition in `agents/` has a specific voice.

### DO NOT

- **Add runtime dependencies.** This must stay zero-dependency (Bash + Markdown only).
- **Bloat skills back up.** The consolidation from 27 to ~15 skills was intentional. Do not create new skills for internal implementation details — inline them.
- **Write bash pseudo-code in skills.** Skills are Claude instructions, not shell scripts. Use one-liner commands or lib script references, not multi-line bash blocks.
- **Duplicate protocol definitions.** Finding format lives in `check-phase`. Routing table lives in `act-phase`. Shadow detection lives in `shadow-detection`. One source of truth per concept.
- **Skip the Check phase** in PDCA cycles. It's the quality gate.
- **Change archetype personalities** without updating all referencing skills and agent definitions.
- **Use ArcheFlow for trivial tasks.** Single-file fixes, config changes, questions — just do them directly.
- **Let skills exceed ~200 lines.** If a skill is growing past this, it probably needs splitting or the content belongs in a lib script.

### Skill Writing Rules

1. **Frontmatter**: `name` (kebab-case), `description` (one-liner + `<example>` tags for user-invocable skills)
2. **Structure**: Imperative voice. Lead with what to do, not why. Tables > prose. Steps > paragraphs.
3. **Agent templates**: Keep Agent() spawn templates concise. Include only the prompt, subagent_type, and isolation mode.
4. **Cross-references**: Use `archeflow:<skill-name>` backtick syntax to reference other skills. Avoid circular dependencies.
5. **Bash commands**: One-liners only in skills. Multi-step logic belongs in `lib/` scripts.

### Cost Awareness

- Prefer cheap models (haiku) for analytical tasks (validation, diff scoring)
- Use capable models (sonnet/opus) for creative tasks (writing, complex design)
- Budget enforcement via `cost-tracking` skill and `.archeflow/config.yaml`
- Track token spend per agent in events for post-run analysis

### Git Rules

- Signing: `git config gpg.format ssh`, key at `~/.ssh/id_ed25519_dev.pub`
- Push: `GIT_SSH_COMMAND="ssh -i /home/c/.ssh/id_ed25519_dev -o IdentitiesOnly=yes" git push origin main`
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
- No Co-Authored-By trailers
- All work on worktree branches until explicitly merged
- Merges use `--no-ff` (individually revertable)

## Dogfooding

When using ArcheFlow to develop ArcheFlow itself:
- Log observations to `.archeflow/memory/lessons.jsonl`
- Note friction points, shadow false positives, skill gaps
- Test skill changes with `/af-run --dry-run` before committing