Christian Nennemann
130c04fa58
- Extend shadow-detection with 3-layer corrective action framework: archetype shadows, system shadows (tunnel vision, echo chamber, etc.), and policy boundaries (checkpoints, budget gates, circuit breakers) - Rewrite CLAUDE.md with proper guardrails (DO/DO NOT, skill writing rules, 200-line max per skill, no bash pseudo-code in skills) - Update plugin.json to v0.8.0 with consolidated 19-skill list - Update README architecture tree and skills reference - Update using-archeflow version string to v0.8.0 / 19 skills - Remove 8 empty skill directories (absorbed into run skill)
120 lines
6.1 KiB
Markdown
120 lines
6.1 KiB
Markdown
# 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
|