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

docs: comprehensive README with install, usage, debugging, and examples

Browse Source
This commit is contained in:
Christian Nennemann
2026-04-03 06:03:37 +02:00
parent d08dc657d1
commit df0c81ae89
1 changed files with 168 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

240
README.md
View File

@@ -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. 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 ✓ ╱ Act ──────────── Done ✓
@@ -26,25 +48,21 @@ Zero dependencies. No build step. Just install and go.
│ Plan ← Cycle 1 │ Plan ← Cycle 1
``` ```
Each cycle produces better results. No unreviewed code reaches your main branch.
## The Seven Archetypes ## 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 | | Archetype | Avatar | Virtue | Shadow | Phase |
|-----------|--------|--------| |-----------|--------|--------|--------|-------|
| **Explorer** | Contextual Clarity | Rabbit Hole | | **Explorer** | 🔍 | Contextual Clarity | Rabbit Hole | Plan |
| **Creator** | Decisive Framing | Over-Architect | | **Creator** | 🏗️ | Decisive Framing | Over-Architect | Plan |
| **Maker** | Execution Discipline | Rogue | | **Maker** | ⚒️ | Execution Discipline | Rogue | Do |
| **Guardian** | Threat Intuition | Paranoid | | **Guardian** | 🛡️ | Threat Intuition | Paranoid | Check |
| **Skeptic** | Assumption Surfacing | Paralytic | | **Skeptic** | 🤔 | Assumption Surfacing | Paralytic | Check |
| **Trickster** | Adversarial Creativity | False Alarm | | **Trickster** | 🃏 | Adversarial Creativity | False Alarm | Check |
| **Sage** | Maintainability Judgment | Bureaucrat | | **Sage** | 📚 | Maintainability Judgment | Bureaucrat | Check |
ArcheFlow detects shadow activation and course-corrects automatically. ## Workflows
## Built-in Workflows
| Workflow | Cycles | Archetypes | Best For | | 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 | | `standard` | 2 | Explorer + Creator → Maker → Guardian + Skeptic + Sage | Features, refactors |
| `thorough` | 3 | Explorer + Creator → Maker → All 4 reviewers | Security-critical, public APIs | | `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: ```
"Implement input validation for the API (use thorough workflow)"
- **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
``` ```
## 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/<archetype>.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/ archeflow/
├── .claude-plugin/plugin.json # Plugin manifest ├── .claude-plugin/plugin.json # Plugin manifest
├── skills/ ├── agents/ # Archetype personas (7 agents)
│ ├── using-archeflow/ # Bootstrap — loaded at session start │ ├── 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 │ ├── orchestration/ # Step-by-step PDCA execution
│ ├── plan-phase/ # Explorer + Creator protocols │ ├── plan-phase/ # Explorer + Creator protocols
│ ├── do-phase/ # Maker implementation rules │ ├── do-phase/ # Maker implementation rules
│ ├── check-phase/ # Reviewer protocols (all 4) │ ├── check-phase/ # Reviewer protocols
│ ├── shadow-detection/ # Recognizing and correcting dysfunction │ ├── shadow-detection/ # Dysfunction detection + correction
│ ├── attention-filters/ # What context each archetype receives │ ├── attention-filters/ # Context optimization per archetype
│ ├── autonomous-mode/ # Unattended overnight sessions │ ├── autonomous-mode/ # Unattended overnight sessions
│ ├── custom-archetypes/ # Creating domain-specific roles │ ├── custom-archetypes/ # Creating domain-specific roles
│ └── workflow-design/ # Designing custom workflows │ └── workflow-design/ # Designing custom workflows
├── agents/ ├── hooks/ # Auto-activation
│ ├── explorer.md # Research agent (Haiku) │ ├── hooks.json # SessionStart trigger
│ ├── creator.md # Design agent (Sonnet) │ └── session-start # Bootstrap script (Node.js)
│ ├── maker.md # Implementation agent (Sonnet) ├── docs/ # Plans, roadmap
│ ├── guardian.md # Security reviewer (Sonnet) │ ├── roadmap.md
│ ├── skeptic.md # Assumption challenger (Sonnet) │ └── plan-*.md
│ ├── trickster.md # Adversarial tester (Haiku) └── examples/ # Walkthrough examples
│ └── 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
``` ```
## 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 ## Extending ArcheFlow
### Custom Archetypes ### Custom Archetypes
@@ -130,11 +228,9 @@ Add domain-specific roles (database reviewer, compliance auditor, etc.):
**ID:** db-specialist **ID:** db-specialist
**Role:** Reviews database schemas and migration safety **Role:** Reviews database schemas and migration safety
**Lens:** "Will this scale? Will this corrupt data?" **Lens:** "Will this scale? Will this corrupt data?"
...
``` ```
### Custom Workflows ### Custom Workflows
Design your own workflow:
```yaml ```yaml
# .archeflow/workflows/api-design.yaml # .archeflow/workflows/api-design.yaml
pdca: pdca: