From df0c81ae891865f8841d22b35ab05b28cf47d5fe Mon Sep 17 00:00:00 2001 From: Christian Nennemann Date: Fri, 3 Apr 2026 06:03:37 +0200 Subject: [PATCH] docs: comprehensive README with install, usage, debugging, and examples --- README.md | 240 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 168 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 1c5615f..b811a06 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,31 @@ ArcheFlow gives Claude Code a structured way to coordinate multiple agents through quality cycles. Instead of one agent doing everything, specialized archetypes collaborate through **PDCA cycles** — Plan, Do, Check, Act — where each iteration builds on feedback from the last. -Zero dependencies. No build step. Just install and go. +Zero dependencies. No build step. Install and it activates automatically. -## The PDCA Cycle +## Install + +```bash +# From Git +claude plugin install --url https://git.xorwell.de/c/claude-archeflow-plugin + +# Local development +claude --plugin-dir ./archeflow +``` + +That's it. No config needed. ArcheFlow activates automatically at session start and kicks in when you give implementation tasks. + +## How It Works + +When you give Claude an implementation task (feature, refactor, multi-file change), ArcheFlow automatically: + +1. **Assesses the task** and picks a workflow (fast/standard/thorough) +2. **Plan** — 🔍 Explorer researches → 🏗️ Creator designs a proposal +3. **Do** — ⚒️ Maker implements in an isolated git worktree +4. **Check** — 🛡️ Guardian + 🤔 Skeptic + 📚 Sage review in parallel +5. **Act** — All approved? Merge. Issues? Cycle back with structured feedback. + +No unreviewed code reaches your main branch. Ever. ``` ╱ Act ──────────── Done ✓ @@ -26,25 +48,21 @@ Zero dependencies. No build step. Just install and go. │ Plan ← Cycle 1 ``` -Each cycle produces better results. No unreviewed code reaches your main branch. - ## The Seven Archetypes -Each archetype has a **virtue** (its unique contribution) and **shadows** (what happens when the virtue is pushed too far): +Each archetype has a **virtue** (its unique contribution) and a **shadow** (dysfunction when pushed too far). ArcheFlow detects shadows and course-corrects automatically. -| Archetype | Virtue | Shadow | -|-----------|--------|--------| -| **Explorer** | Contextual Clarity | Rabbit Hole | -| **Creator** | Decisive Framing | Over-Architect | -| **Maker** | Execution Discipline | Rogue | -| **Guardian** | Threat Intuition | Paranoid | -| **Skeptic** | Assumption Surfacing | Paralytic | -| **Trickster** | Adversarial Creativity | False Alarm | -| **Sage** | Maintainability Judgment | Bureaucrat | +| Archetype | Avatar | Virtue | Shadow | Phase | +|-----------|--------|--------|--------|-------| +| **Explorer** | 🔍 | Contextual Clarity | Rabbit Hole | Plan | +| **Creator** | 🏗️ | Decisive Framing | Over-Architect | Plan | +| **Maker** | ⚒️ | Execution Discipline | Rogue | Do | +| **Guardian** | 🛡️ | Threat Intuition | Paranoid | Check | +| **Skeptic** | 🤔 | Assumption Surfacing | Paralytic | Check | +| **Trickster** | 🃏 | Adversarial Creativity | False Alarm | Check | +| **Sage** | 📚 | Maintainability Judgment | Bureaucrat | Check | -ArcheFlow detects shadow activation and course-corrects automatically. - -## Built-in Workflows +## Workflows | Workflow | Cycles | Archetypes | Best For | |----------|:---:|------------|----------| @@ -52,74 +70,154 @@ ArcheFlow detects shadow activation and course-corrects automatically. | `standard` | 2 | Explorer + Creator → Maker → Guardian + Skeptic + Sage | Features, refactors | | `thorough` | 3 | Explorer + Creator → Maker → All 4 reviewers | Security-critical, public APIs | -## Autonomous Mode +ArcheFlow picks the workflow automatically based on task risk, or you can specify: -ArcheFlow can run fully unattended — queue your tasks, walk away, read the results in the morning: - -- **Self-organizing:** Archetypes coordinate through PDCA cycles without human input -- **Self-correcting:** Failed reviews trigger automatic revision cycles -- **Safe:** All code stays on worktree branches until all reviewers approve -- **Visible:** Full session log with every decision, finding, and merge -- **Cancellable:** Stop at any time. Incomplete work stays on branches. -- **Reversible:** Every merge is individually revertable - -## Install - -```bash -# From the plugin marketplace (when published) -claude plugin install archeflow - -# From Git -claude plugin install --url https://git.xorwell.de/c/claude-archeflow-plugin - -# Local development -claude --plugin-dir ./archeflow +``` +"Implement input validation for the API (use thorough workflow)" ``` -## What's Inside +## Usage Examples + +### Basic — just describe your task +``` +> Add user authentication with JWT tokens + +# ArcheFlow activates automatically: +# 🔍 Explorer researches auth patterns in codebase +# 🏗️ Creator designs JWT implementation +# ⚒️ Maker implements in worktree +# 🛡️ Guardian reviews for security +# 🤔 Skeptic challenges JWT assumptions +# 📚 Sage checks code quality +# → All approved → merged to main +``` + +### Force a specific workflow +``` +> Fix the off-by-one error in pagination (use fast workflow) +``` + +### Load skills manually +``` +> /archeflow:orchestration # Step-by-step execution guide +> /archeflow:shadow-detection # Shadow monitoring rules +> /archeflow:autonomous-mode # Overnight batch processing +``` + +### Autonomous mode — queue tasks and walk away +``` +> Enter autonomous mode with these tasks: +> 1. "Add input validation to all API endpoints" (thorough) +> 2. "Refactor auth middleware to use JWT" (standard) +> 3. "Fix pagination bug in search results" (fast) +``` + +ArcheFlow processes them sequentially, logs progress to `.archeflow/session-log.md`, and stops on 3 consecutive failures. + +## When ArcheFlow Activates (and When It Doesn't) + +**Activates for:** +- New features touching 2+ files +- Refactoring across modules +- Security-sensitive changes +- Bug fixes with unclear root cause +- Code review requests + +**Stays out of the way for:** +- Single-line fixes, typos +- Answering questions +- Reading/exploring code +- Single-file config changes +- Git operations + +## Key Features + +### Cross-Cycle Feedback +When a reviewer rejects, findings are structured and routed: +- Guardian/Skeptic findings → Creator (design must change) +- Sage/Trickster findings → Maker (implementation refinement) +- Resolution tracked across cycles — no regression + +### Attention Filters +Each archetype receives only relevant context. Guardian gets the git diff + risk section, not the full 2000-word research. Saves 30-50% tokens per agent. + +### Shadow Detection +Quantitative thresholds detect dysfunction: +- Explorer output >2000 words without recommendation? → Rabbit Hole +- Guardian CRITICAL:WARNING ratio >2:1? → Paranoid +- Maker has no tests in changeset? → Rogue + +First detection: correction prompt. Second: replace agent. Third: escalate to user. + +### Orchestration Metrics +Every run tracks: phases, duration, agent count, findings by severity, shadow detections. + +## Debugging + +### ArcheFlow isn't activating +1. Check the plugin is installed: `claude plugin list` +2. Verify the hook runs: `CLAUDE_PLUGIN_ROOT=./archeflow node ./archeflow/hooks/session-start` +3. Should output JSON with `additionalContext` containing "ArcheFlow — Active" +4. If empty output: check `skills/using-archeflow/SKILL.md` exists + +### Agent isn't following its archetype +- Check the agent definition in `agents/.md` +- Verify the orchestration skill passes correct context (see attention filters) +- Look for shadow activation — is the agent stuck in a loop? + +### Worktree issues +```bash +# List active worktrees +git worktree list + +# Clean up abandoned worktrees +git worktree prune +``` + +### Shadow false positives +If an agent is correctly doing intensive work but gets flagged: +- Explorer reading 20 files in a monorepo with scattered deps → not a rabbit hole +- Guardian blocking with 2 genuine CVEs → not paranoid +- Check the Shadow Immunity rules in `skills/shadow-detection/SKILL.md` + +### Checking what ArcheFlow sees at session start +```bash +CLAUDE_PLUGIN_ROOT=./archeflow node ./archeflow/hooks/session-start | python3 -m json.tool +``` + +## Plugin Structure ``` archeflow/ ├── .claude-plugin/plugin.json # Plugin manifest -├── skills/ -│ ├── using-archeflow/ # Bootstrap — loaded at session start +├── agents/ # Archetype personas (7 agents) +│ ├── explorer.md 🔍 +│ ├── creator.md 🏗️ +│ ├── maker.md ⚒️ +│ ├── guardian.md 🛡️ +│ ├── skeptic.md 🤔 +│ ├── trickster.md 🃏 +│ └── sage.md 📚 +├── skills/ # Behavioral rules (10 skills) +│ ├── using-archeflow/ # Auto-loaded at session start │ ├── orchestration/ # Step-by-step PDCA execution │ ├── plan-phase/ # Explorer + Creator protocols │ ├── do-phase/ # Maker implementation rules -│ ├── check-phase/ # Reviewer protocols (all 4) -│ ├── shadow-detection/ # Recognizing and correcting dysfunction -│ ├── attention-filters/ # What context each archetype receives +│ ├── check-phase/ # Reviewer protocols +│ ├── shadow-detection/ # Dysfunction detection + correction +│ ├── attention-filters/ # Context optimization per archetype │ ├── autonomous-mode/ # Unattended overnight sessions │ ├── custom-archetypes/ # Creating domain-specific roles │ └── workflow-design/ # Designing custom workflows -├── agents/ -│ ├── explorer.md # Research agent (Haiku) -│ ├── creator.md # Design agent (Sonnet) -│ ├── maker.md # Implementation agent (Sonnet) -│ ├── guardian.md # Security reviewer (Sonnet) -│ ├── skeptic.md # Assumption challenger (Sonnet) -│ ├── trickster.md # Adversarial tester (Haiku) -│ └── sage.md # Quality reviewer (Sonnet) -├── hooks/ -│ ├── hooks.json # SessionStart hook config -│ └── session-start # Bootstrap script -└── examples/ - ├── feature-implementation.md # Standard workflow walkthrough - ├── security-review.md # Thorough workflow walkthrough - └── custom-workflow.yaml # Custom workflow template +├── hooks/ # Auto-activation +│ ├── hooks.json # SessionStart trigger +│ └── session-start # Bootstrap script (Node.js) +├── docs/ # Plans, roadmap +│ ├── roadmap.md +│ └── plan-*.md +└── examples/ # Walkthrough examples ``` -## How It Works - -ArcheFlow is **pure skills and agents** — no runtime, no server, no dependencies. - -- **Skills** teach Claude Code *when* and *how* to orchestrate (behavioral rules) -- **Agents** define each archetype's persona and review protocol -- **Hooks** inject ArcheFlow context at session start automatically -- **Git worktrees** provide isolation — each Maker works on a separate branch - -Claude Code's native `Agent` tool spawns the archetypes. Git worktrees provide isolation. Markdown artifacts provide communication between phases. Nothing else needed. - ## Extending ArcheFlow ### Custom Archetypes @@ -130,11 +228,9 @@ Add domain-specific roles (database reviewer, compliance auditor, etc.): **ID:** db-specialist **Role:** Reviews database schemas and migration safety **Lens:** "Will this scale? Will this corrupt data?" -... ``` ### Custom Workflows -Design your own workflow: ```yaml # .archeflow/workflows/api-design.yaml pdca: