claude-archeflow-plugin/CLAUDE.md

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