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

chore: consolidate plugin for sharing

Browse Source 
- Add .gitignore (ignore .archeflow/ runtime state)
- Move custom archetype examples from .archeflow/ to examples/
- Remove onboarding skill (covered by using-archeflow + README)
- Remove internal planning doc
- Clean roadmap (remove tool.archeflow references)
- Simplify session-start hook config
- Polish README for external users
This commit is contained in:
Christian Nennemann
2026-04-03 07:29:53 +02:00
parent 5eefa309cb
commit 8dec44d199
10 changed files with 337 additions and 403 deletions
Download Patch File Download Diff File Expand all files Collapse all files

279
README.md
View File

@@ -4,7 +4,7 @@
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. Install and it activates automatically.
Zero dependencies. No build step. Just install and go.
## Install
@@ -16,95 +16,82 @@ claude plugin install --url https://git.xorwell.de/c/claude-archeflow-plugin
claude --plugin-dir ./archeflow
```
That's it. No config needed. ArcheFlow activates automatically at session start and kicks in when you give implementation tasks.
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:
When you give Claude an implementation task, 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
2. **Plan** — Explorer researches, Creator designs a proposal
3. **Do** — Maker implements in an isolated git worktree
4. **Check** — Reviewers assess in parallel
5. **Act** — All approved? Merge. Issues? Cycle back with structured feedback.
No unreviewed code reaches your main branch. Ever.
```
╱ Act ──────────── Done ✓
╱ ↑
╱ Check (Guardian + Skeptic + Sage review in parallel)
╱ ↑
╱ Do (Maker implements in isolated worktree)
╱ ↑
╱ Plan (Explorer researches → Creator designs) ← Cycle 2
╱ ↑
╱ Act ─┘ (issues found → feed back)
│ ↑
│ Check
│ ↑
│ Do
│ ↑
│ Plan ← Cycle 1
Plan → Explorer researches, Creator proposes
Do → Maker implements in isolated worktree
Check → Reviewers assess in parallel (approve/reject)
Act → All approved? Merge. Issues? Cycle back to Plan.
Each cycle catches what the last one missed.
```
## The Seven Archetypes
Each archetype has a **virtue** (its unique contribution) and a **shadow** (dysfunction when pushed too far). ArcheFlow detects shadows and course-corrects automatically.
| 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 |
| Archetype | 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 |
## Workflows
| Workflow | Cycles | Archetypes | Best For |
|----------|:---:|------------|----------|
| `fast` | 1 | Creator → Maker → Guardian | Bug fixes, small changes |
| `standard` | 2 | Explorer + Creator → Maker → Guardian + Skeptic + Sage | Features, refactors |
| `thorough` | 3 | Explorer + Creator → Maker → All 4 reviewers | Security-critical, public APIs |
| `fast` | 1 | Creator, Maker, Guardian | Bug fixes, small changes |
| `standard` | 2 | Explorer + Creator, Maker, Guardian + Skeptic + Sage | Features, refactors |
| `thorough` | 3 | Explorer + Creator, Maker, All 4 reviewers | Security-critical, public APIs |
ArcheFlow picks the workflow automatically based on task risk, or you can specify:
ArcheFlow picks the workflow automatically, or you can specify:
```
"Implement input validation for the API (use thorough workflow)"
```
## Usage Examples
## Usage
### Just describe your task
### 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
# 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
### Force a 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)
@@ -112,127 +99,61 @@ ArcheFlow picks the workflow automatically based on task risk, or you can specif
> 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.
### Dry run
```
> What would ArcheFlow do for "Add JWT authentication"?
Dry run for: "Add JWT authentication"
Workflow: standard (2 cycles)
Agents: Explorer → Creator → Maker → Guardian + Skeptic + Sage
Est. agents: 6 per cycle, 12 max
Worktree: yes (isolated branch)
Proceed? [y/n]
```
## 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
**Activates for:** New features (2+ files), refactoring, security 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
**Stays out of the way for:** Single-line fixes, answering questions, exploring code, single-file configs, 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
**Cross-Cycle Feedback** — When a reviewer rejects, findings are structured and routed to the right agent. Guardian findings go to Creator (design must change). Sage findings go to Maker (implementation refinement). Resolution is tracked across cycles.
### 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.
**Attention Filters** — Each archetype receives only relevant context. Guardian gets the diff + risk section, not the full research report. 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
**Shadow Detection** — Quantitative thresholds detect dysfunction. Explorer output >2000 words without a recommendation? Rabbit Hole. Guardian blocking everything? Paranoid. First detection: correction prompt. Second: replace agent. Third: escalate to user.
First detection: correction prompt. Second: replace agent. Third: escalate to user.
**Workflow Adaptation** — Workflows adjust at runtime. If Guardian finds 2+ CRITICALs in a fast workflow, it escalates to standard. If Guardian finds nothing in standard, it fast-paths past the remaining reviewers.
### 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/
├── .claude-plugin/plugin.json # Plugin manifest
├── 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
│ ├── 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
├── hooks/ # Auto-activation
│ ├── hooks.json # SessionStart trigger
│ └── session-start # Bootstrap script (Node.js)
├── docs/ # Plans, roadmap
│ ├── roadmap.md
│ └── plan-*.md
└── examples/ # Walkthrough examples
```
**Parallel Teams** — Run up to 3 independent tasks through their own PDCA cycles simultaneously. Each team gets its own worktree. First-finished-first-merged.
## Extending ArcheFlow
### Custom Archetypes
Add domain-specific roles (database reviewer, compliance auditor, etc.):
Add domain-specific roles (database reviewer, compliance auditor, etc.). Put them in your project's `.archeflow/archetypes/`:
```markdown
# .archeflow/archetypes/db-specialist.md
## Identity
**ID:** db-specialist
**Role:** Reviews database schemas and migration safety
**Lens:** "Will this scale? Will this corrupt data?"
---
name: db-specialist
description: Reviews database schemas and migration safety
model: sonnet
---
You are the **Database Specialist**.
Your lens: "Will this scale? Will this corrupt data?"
...
```
### Custom Workflows
```yaml
# .archeflow/workflows/api-design.yaml
name: api-design
pdca:
plan: { archetypes: [explorer, creator] }
do: { archetypes: [maker] }
@@ -240,15 +161,67 @@ pdca:
act: { exit_when: all_approved, max_cycles: 2 }
```
## Philosophy
See `examples/` for complete examples including custom archetypes, team presets, and workflows.
ArcheFlow is built on three beliefs:
## Skills Reference
| Skill | What it does |
|-------|-------------|
| `archeflow:orchestration` | Step-by-step PDCA execution guide |
| `archeflow:shadow-detection` | Dysfunction detection and correction |
| `archeflow:autonomous-mode` | Unattended overnight sessions |
| `archeflow:plan-phase` | Explorer + Creator output formats |
| `archeflow:do-phase` | Maker implementation rules |
| `archeflow:check-phase` | Shared reviewer protocols |
| `archeflow:attention-filters` | Context optimization per archetype |
| `archeflow:custom-archetypes` | Creating domain-specific roles |
| `archeflow:workflow-design` | Designing custom workflows |
## Plugin Structure
```
archeflow/
├── .claude-plugin/plugin.json # Plugin manifest
├── agents/ # 7 archetype personas
│ ├── explorer.md
│ ├── creator.md
│ ├── maker.md
│ ├── guardian.md
│ ├── skeptic.md
│ ├── trickster.md
│ └── sage.md
├── skills/ # 10 behavioral skills
│ ├── using-archeflow/ # Auto-loaded at session start
│ ├── orchestration/ # PDCA execution guide
│ ├── plan-phase/ # Plan phase protocols
│ ├── do-phase/ # Do phase protocols
│ ├── check-phase/ # Check phase protocols
│ ├── shadow-detection/ # Dysfunction detection
│ ├── attention-filters/ # Context optimization
│ ├── autonomous-mode/ # Unattended sessions
│ ├── custom-archetypes/ # Creating new roles
│ └── workflow-design/ # Custom workflows
├── hooks/ # Auto-activation
│ ├── hooks.json
│ └── session-start
├── examples/ # Walkthroughs + templates
│ ├── feature-implementation.md
│ ├── security-review.md
│ ├── custom-workflow.yaml
│ ├── custom-archetypes/
│ ├── teams/
│ └── workflows/
└── docs/
└── roadmap.md
```
## Philosophy
1. **Strength has a shadow.** Every capability becomes destructive when unchecked. The Explorer who won't stop researching. The Guardian who blocks everything. The Maker who ships without review. ArcheFlow names these shadows and corrects them.
2. **Quality is a spiral, not a gate.** A single review pass misses things. PDCA cycles spiral upward — each cycle catches what the previous one missed, until the reviewers have nothing left to find.
3. **Autonomy needs structure.** Agents left to their own devices produce mediocre results. Agents given clear roles, typed communication, and quality gates produce exceptional work — even overnight, even unattended.
3. **Autonomy needs structure.** Agents given clear roles, typed communication, and quality gates produce exceptional work — even overnight, even unattended.
## License