c/claude-archeflow-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: corrective action framework + CLAUDE.md rewrite + v0.8.0 cleanup

Browse Source 
- 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)
This commit is contained in:
Christian Nennemann
2026-04-06 20:52:27 +02:00
parent 752177528f
commit 130c04fa58
5 changed files with 260 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

168
CLAUDE.md
View File

@@ -1,71 +1,119 @@
# 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
```
PDCA quality cycles with Jungian archetype roles, corrective action framework, sprint runner, and post-implementation review. Zero dependencies — pure Bash + Markdown.
## 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
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
```
## Domain Rules
## Commands
- 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
| 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 |
## Do NOT
## Core Concepts
- 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)
### 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