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

docs: rewrite README, add CHANGELOG, update skill index and roadmap

Browse Source 
- README: complete rewrite with all 24 skills, 8 scripts, architecture overview
- CHANGELOG: v0.1.0 → v0.2.0 → v0.3.0 with full feature history
- using-archeflow: updated skill reference to all 24 skills in 6 categories
- plugin.json: version bump to 0.3.0
- roadmap: updated with v0.3.0 features
This commit is contained in:
Christian Nennemann
2026-04-03 12:05:53 +02:00
parent 9faea1d6ea
commit 9e22ff5822
5 changed files with 452 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

438
README.md
View File

@@ -1,12 +1,20 @@
# ArcheFlow
# ArcheFlow -- Multi-Agent Orchestration for Claude Code
**Multi-agent orchestration with Jungian archetypes for Claude Code.**
**Structured quality through archetypal collaboration.** ArcheFlow coordinates multiple Claude Code agents through PDCA cycles, where each agent embodies a Jungian archetype with defined strengths and known failure modes.
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 go.
Zero dependencies. No build step. Just install and go.
## What It Does
## Install
Large coding tasks benefit from multiple perspectives, but "just spawn more agents" creates chaos. Agents duplicate work, miss each other's output, argue in circles, or go rogue. The problem is not intelligence -- it is coordination.
ArcheFlow solves this by giving each agent an *archetype*: a behavioral protocol that defines what the agent cares about, what context it receives, and how its output feeds into the next phase. Seven archetypes collaborate through **Plan-Do-Check-Act cycles**, where each iteration builds on structured feedback from the last. No unreviewed code reaches your main branch.
The key insight: archetypes are not just system prompts. Each one has a **virtue** (its unique contribution) and a **shadow** (the dysfunction it falls into when pushed too far). ArcheFlow monitors for shadow activation and course-corrects automatically -- replacing an agent that blocks everything, reining in one that researches forever, or escalating when a maker goes off-script.
## Quick Start
### 1. Install
```bash
# From Git
@@ -16,141 +24,159 @@ claude plugin install --url https://git.xorwell.de/c/claude-archeflow-plugin
claude --plugin-dir ./archeflow
```
ArcheFlow activates automatically at session start and kicks in when you give implementation tasks.
### 2. Run your first orchestration
## How It Works
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** — Reviewers assess in parallel
5. **Act** — All approved? Merge. Issues? Cycle back with structured feedback.
No unreviewed code reaches your main branch. Ever.
Just describe a task. ArcheFlow activates automatically for multi-file changes:
```
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.
> Add input validation to all API endpoints
```
Or invoke it explicitly:
```
> archeflow:run "Add JWT authentication" --workflow standard
```
### 3. What happens
ArcheFlow selects a workflow (fast, standard, or thorough) and runs a PDCA cycle:
```
Plan --> Explorer researches codebase context, Creator designs a proposal
Do --> Maker implements in an isolated git worktree
Check --> Reviewers assess in parallel (Guardian, Skeptic, Sage, Trickster)
Act --> All approved? Merge. Issues found? Cycle back with structured feedback.
Each cycle catches what the last one missed.
```
Progress is visible in real time:
```
--- ArcheFlow: Add JWT authentication ---------
Workflow: standard (2 cycles max)
🔍 [Plan] Explorer researching... done (35s)
🏗️ [Plan] Creator designing proposal... done (25s, confidence: 0.8)
⚒️ [Do] Maker implementing... done (90s, 4 files, 8 tests)
🛡️ [Check] Guardian reviewing... APPROVED
🤔 [Check] Skeptic challenging... APPROVED (1 INFO)
📚 [Check] Sage reviewing... APPROVED
[Act] All approved -- merging... merged to main
--- Complete: 3m 10s, 1 cycle -----------------
```
## 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 | Phase | Virtue | Shadow | Role |
|-----------|-------|--------|--------|------|
| 🔍 **Explorer** | Plan | Contextual Clarity | Rabbit Hole | Researches codebase, maps dependencies, synthesizes findings |
| 🏗️ **Creator** | Plan | Decisive Framing | Over-Architect | Designs solution proposals with architecture decisions and test strategy |
| ⚒️ **Maker** | Do | Execution Discipline | Rogue | Implements code in an isolated git worktree, commits per phase |
| 🛡️ **Guardian** | Check | Threat Intuition | Paranoid | Reviews for security vulnerabilities, reliability risks, breaking changes |
| 🤔 **Skeptic** | Check | Assumption Surfacing | Paralytic | Challenges assumptions, identifies untested scenarios, proposes alternatives |
| 🃏 **Trickster** | Check | Adversarial Creativity | False Alarm | Adversarial testing, boundary attacks, edge case exploitation |
| 📚 **Sage** | Check | Maintainability Judgment | Bureaucrat | Holistic quality review -- code quality, test coverage, engineering judgment |
| 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 |
Shadow detection is quantitative, not vibes. Explorer output exceeding 2000 words without a recommendation triggers Rabbit Hole. Guardian blocking three consecutive items triggers Paranoid. First detection: correction prompt. Second: replace agent. Third: escalate to user.
## Skills Reference
ArcheFlow ships with 24 skills organized by function.
### Core Orchestration
| Skill | Description |
|-------|-------------|
| `archeflow:run` | Automated PDCA execution loop -- single-command orchestration with `--start-from`, `--dry-run`, and cycle-back |
| `archeflow:orchestration` | Step-by-step PDCA execution guide for manual orchestration |
| `archeflow:plan-phase` | Explorer and Creator output formats and protocols |
| `archeflow:do-phase` | Maker implementation rules and worktree commit strategy |
| `archeflow:check-phase` | Shared reviewer protocols and output format |
| `archeflow:act-phase` | Post-Check decision logic: collect findings, route fixes, exit or cycle |
### Quality and Safety
| Skill | Description |
|-------|-------------|
| `archeflow:shadow-detection` | Quantitative dysfunction detection and automatic correction |
| `archeflow:attention-filters` | Context optimization per archetype -- each agent gets only what it needs |
| `archeflow:convergence` | Detects convergence, stalling, and oscillation in multi-cycle runs |
| `archeflow:artifact-routing` | Inter-phase artifact protocol -- naming, storage, routing, archiving |
### Process Intelligence
| Skill | Description |
|-------|-------------|
| `archeflow:process-log` | Event-sourced JSONL logging with DAG parent relationships |
| `archeflow:memory` | Cross-run memory that learns recurring findings and injects lessons |
| `archeflow:effectiveness` | Archetype scoring on signal-to-noise, fix rate, cost efficiency |
| `archeflow:progress` | Live progress file watchable from a second terminal |
### Integration
| Skill | Description |
|-------|-------------|
| `archeflow:colette-bridge` | Bridges ArcheFlow with the Colette writing platform |
| `archeflow:git-integration` | Git-per-phase commits, branch-per-run, rollback to any phase boundary |
| `archeflow:multi-project` | Cross-repo orchestration with dependency DAG and shared budget |
### Configuration
| Skill | Description |
|-------|-------------|
| `archeflow:custom-archetypes` | Create domain-specific roles (database reviewer, compliance auditor, etc.) |
| `archeflow:workflow-design` | Design custom workflows with per-phase archetype assignment and exit conditions |
| `archeflow:domains` | Domain adapters for writing, research, and other non-code workflows |
| `archeflow:cost-tracking` | Budget enforcement, per-agent cost aggregation, model tier recommendations |
| `archeflow:templates` | Template gallery for sharing workflows, teams, and setup bundles |
| `archeflow:autonomous-mode` | Unattended overnight sessions with progress logging and safe stopping |
### Meta
| Skill | Description |
|-------|-------------|
| `archeflow:using-archeflow` | Session-start skill -- activation criteria, workflow selection, quick reference |
## Library Scripts
Eight shell scripts in `lib/` power the process infrastructure.
| Script | Purpose | Usage |
|--------|---------|-------|
| `archeflow-event.sh` | Append structured JSONL events to a run log | `archeflow-event.sh <run_id> <type> <phase> <agent> '<json>'` |
| `archeflow-dag.sh` | Render ASCII DAG from JSONL events | `archeflow-dag.sh events.jsonl --color` |
| `archeflow-report.sh` | Generate Markdown process report | `archeflow-report.sh events.jsonl --output report.md --dag` |
| `archeflow-progress.sh` | Regenerate live progress file from events | `archeflow-progress.sh <run_id>` |
| `archeflow-score.sh` | Score archetype effectiveness from completed runs | `archeflow-score.sh extract events.jsonl` |
| `archeflow-memory.sh` | Cross-run memory: add, list, decay, inject lessons | `archeflow-memory.sh add "Always check for null"` |
| `archeflow-git.sh` | Per-phase commits, branch creation, merge, rollback | `archeflow-git.sh commit <run_id> <phase>` |
| `archeflow-init.sh` | Template gallery: init, save, clone, list | `archeflow-init.sh init writing-short-story` |
## Workflows
### Built-in 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 |
ArcheFlow picks the workflow automatically, or you can specify:
ArcheFlow picks the workflow automatically based on task complexity, or you can specify:
```
"Implement input validation for the API (use thorough workflow)"
> Implement input validation for the API (use thorough workflow)
```
## Usage
### 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 workflow
```
> Fix the off-by-one error in pagination (use fast workflow)
```
### 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)
```
### 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 (2+ files), refactoring, security changes, bug fixes with unclear root cause, code review requests.
**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 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 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 a recommendation? Rabbit Hole. Guardian blocking everything? Paranoid. 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.
**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.). Put them in your project's `.archeflow/archetypes/`:
```markdown
# .archeflow/archetypes/db-specialist.md
---
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?"
...
```
Workflows adapt at runtime. If Guardian finds 2+ CRITICALs in a fast workflow, it escalates to standard. If reviewers find nothing in standard, it fast-paths past the remaining cycle.
### Custom Workflows
Define your own workflows in `.archeflow/workflows/`:
```yaml
# .archeflow/workflows/api-design.yaml
name: api-design
@@ -161,67 +187,151 @@ pdca:
act: { exit_when: all_approved, max_cycles: 2 }
```
See `examples/` for complete examples including custom archetypes, team presets, and workflows.
### Example: Short Fiction Workflow
## Skills Reference
ArcheFlow is not limited to code. The included `kurzgeschichte` workflow orchestrates short story development with custom archetypes (story-explorer, story-sage), Colette voice profile integration, and scene-by-scene commits:
| 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 |
```yaml
# examples/workflows/kurzgeschichte.yaml
name: kurzgeschichte
team: story-development
phases:
plan:
archetypes: [story-explorer, creator]
do:
archetypes: [maker]
check:
archetypes: [guardian, story-sage]
act:
exit_when: all_approved
max_cycles: 2
```
## Plugin Structure
## Domain Adapters
ArcheFlow defaults to code-oriented terminology, but domain adapters remap concepts for other workflows:
| Domain | What Changes |
|--------|-------------|
| `code` | Default. Diffs, tests, security review, merge to main. |
| `writing` | Prose quality, voice consistency, dialect authenticity. Auto-activates when `colette.yaml` is detected. |
| `research` | Source quality, argument coherence, citation accuracy. |
Custom domains can be defined in `.archeflow/domains/`.
## Examples
The `examples/` directory contains complete walkthroughs:
- `feature-implementation.md` -- End-to-end feature build with standard workflow
- `security-review.md` -- Thorough review of security-sensitive code
- `custom-workflow.yaml` -- Template for defining your own workflow
- `custom-archetypes/` -- Story-explorer and story-sage for fiction writing
- `teams/` -- Team preset for story development
- `workflows/kurzgeschichte.yaml` -- Short fiction workflow with Colette integration
## Configuration
### Project Configuration
Create `.archeflow/config.yaml` in your project root:
```yaml
workflow: standard # Default workflow
budget: 50000 # Max tokens per run
git:
enabled: true # Per-phase commits
merge_strategy: squash # squash or no-ff
```
### Custom Archetypes
Add domain-specific roles in `.archeflow/archetypes/`:
```markdown
# .archeflow/archetypes/db-specialist.md
---
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?"
```
### Team Presets
Define reusable teams in `.archeflow/teams/`:
```yaml
# .archeflow/teams/backend-review.yaml
name: backend-review
archetypes: [explorer, creator, maker, guardian, db-specialist]
```
### Environment Variables
- `ARCHEFLOW_BUDGET` -- Override default token budget
- `ARCHEFLOW_WORKFLOW` -- Override default workflow selection
## Architecture
```
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
├── .claude-plugin/plugin.json # Plugin manifest (v0.3.0)
├── agents/ # 7 archetype personas (behavioral protocols)
│ ├── explorer.md # Plan: research and context mapping
│ ├── creator.md # Plan: solution design and proposals
│ ├── maker.md # Do: implementation in isolated worktree
│ ├── guardian.md # Check: security and reliability review
│ ├── skeptic.md # Check: assumption challenging
│ ├── trickster.md # Check: adversarial testing
│ └── sage.md # Check: holistic quality review
├── skills/ # 24 behavioral skills
│ ├── run/ # Automated PDCA loop
│ ├── orchestration/ # Manual PDCA execution guide
│ ├── plan-phase/ # Plan protocols
│ ├── do-phase/ # Do protocols
│ ├── check-phase/ # Check protocols
│ ├── act-phase/ # Act phase decision logic
│ ├── shadow-detection/ # Dysfunction detection
│ ├── attention-filters/ # Context optimization
│ ├── convergence/ # Cycle convergence detection
│ ├── artifact-routing/ # Inter-phase artifact protocol
│ ├── process-log/ # Event-sourced JSONL logging
│ ├── memory/ # Cross-run learning
│ ├── effectiveness/ # Archetype scoring
│ ├── progress/ # Live progress file
│ ├── colette-bridge/ # Colette writing platform bridge
│ ├── git-integration/ # Per-phase git commits
│ ├── multi-project/ # Cross-repo orchestration
│ ├── custom-archetypes/ # Domain-specific roles
│ ├── workflow-design/ # Custom workflow design
│ ├── domains/ # Domain adapters
│ ├── cost-tracking/ # Budget and cost management
│ ├── templates/ # Template gallery
│ ├── autonomous-mode/ # Unattended sessions
│ └── using-archeflow/ # Session-start activation
├── lib/ # 8 shell scripts (process infrastructure)
├── hooks/ # Auto-activation (SessionStart)
├── examples/ # Walkthroughs, templates, custom archetypes
└── docs/ # Roadmap, changelog
```
The flow: skills define behavioral rules (what agents should do), agents define personas (how they think), lib scripts handle tooling (event logging, git, reporting), and hooks wire it all together at session start. Events are emitted at every phase transition, forming a DAG that can be rendered, reported, or scored after the run.
## 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.
1. **Strength has a shadow.** Every capability becomes destructive when unchecked. The Explorer who never stops researching. The Guardian who blocks everything. The Maker who ships without review. ArcheFlow names these shadows and corrects them automatically.
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.
2. **Quality is a spiral, not a gate.** A single review pass misses things. PDCA cycles spiral upward -- each iteration catches what the previous one missed, until the reviewers have nothing left to find.
3. **Autonomy needs structure.** 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.
## Version History
See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
## License