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

10
.gitignore vendored Normal file
View File

@@ -0,0 +1,10 @@
# Runtime state (created per-project, not part of plugin)
.archeflow/
# OS
.DS_Store
Thumbs.db
# Editor
*.swp
*~

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

178
docs/plan-core-improvements-2026-04-03.md
View File

@@ -1,178 +0,0 @@
# ArcheFlow Core Improvements Plan
## Context
ArcheFlow's archetype system and PDCA engine are feature-complete in TypeScript (`tool.archeflow/`), but the Claude Code plugin layer (`archeflow/` + `claude-archeflow-plugin/`) has gaps that reduce quality and waste tokens. Two plugin directories exist as near-duplicates. The goal: improve orchestration quality while keeping token usage low.
## Scope
**Implement (High Value):**
1. Cross-cycle feedback loop — structured issue tracking between PDCA cycles
2. Consolidate plugin directories — kill `claude-archeflow-plugin/`, keep `archeflow/`
3. Shadow detection heuristics in skill layer — concrete thresholds, not just prose
4. Attention filter enforcement — actually filter context per archetype when spawning
5. Metrics in orchestration skill — lightweight timing + token tracking
6. Autonomous mode wiring — connect skill to orchestration with progress logging
**Future Features (park for later):**
- Web dashboard UI
- A2A inter-agent negotiation protocol
- GitHub Action integration
## Implementation
### 1. Cross-Cycle Feedback Loop
**Problem:** Check phase outputs go to next Plan cycle as raw text dump. No issue tracking, no resolution status, no routing.
**Solution:** Add structured feedback format to `archeflow/skills/orchestration/SKILL.md`
**Changes:**
- `archeflow/skills/orchestration/SKILL.md` — Add "Cycle Feedback Protocol" section:
- After Check phase, orchestrator extracts findings into structured format:
```
## Cycle N Feedback
### Unresolved Issues
- [Guardian] CRITICAL: <issue> → Route to: Creator
- [Skeptic] WARNING: <assumption> → Route to: Creator
- [Sage] WARNING: <quality concern> → Route to: Maker
### Resolved (from prior cycle)
- [Guardian] <issue> — resolved in cycle N
```
- Route feedback by archetype: Guardian/Skeptic findings → Creator (design issues), Sage/Trickster findings → Maker (implementation issues)
- Track resolution: if a finding from cycle N-1 is no longer present in cycle N review, mark resolved
- `archeflow/skills/plan-phase/SKILL.md` — Add "Prior Feedback" input section to Creator format:
- Creator must address each unresolved issue explicitly (fix, defer with reason, or dispute)
- `archeflow/skills/check-phase/SKILL.md` — Standardize finding output format for machine parsing:
- Each finding: `| Location | Severity | Category | Description | Fix |`
- Categories: security, reliability, design, quality, testing
**Token impact:** Slightly more tokens in feedback artifact, but saves full cycles by giving targeted guidance instead of "here's everything, figure it out."
### 2. Consolidate Plugin Directories
**Problem:** `archeflow/` and `claude-archeflow-plugin/` are near-identical (1 commit apart), causing maintenance drift.
**Solution:** Delete `claude-archeflow-plugin/`, keep `archeflow/` (more recent, cleaner Node.js hook).
**Changes:**
- Remove `claude-archeflow-plugin/` directory
- Verify `archeflow/` is referenced in any workspace config
- Update any cross-references in docs
### 3. Shadow Detection Heuristics in Skill Layer
**Problem:** TypeScript `ShadowDetector` has concrete thresholds (e.g., >2000 words, >3 tangents), but the skill file only describes shadows in prose. The orchestrator running via Claude Code skills can't use the TypeScript runtime — it needs the heuristics inline.
**Solution:** Add quantitative detection rules to `archeflow/skills/shadow-detection/SKILL.md`
**Changes:**
- `archeflow/skills/shadow-detection/SKILL.md` — For each archetype, add a "Detection Checklist" with concrete metrics the orchestrator can evaluate:
```
### Explorer → Rabbit Hole
**Detect:** ANY of:
- [ ] Output >2000 words without a Recommendation section
- [ ] >3 tangent topics not in original task
- [ ] >15 files read
**Correct:** "Summarize top 3 findings in 300 words. Add Recommendation."
```
- Keep the existing prose for understanding, add checklist for action
**Token impact:** Negligible — adds ~200 words to skill file, but prevents wasted cycles from undetected shadows.
### 4. Attention Filter Enforcement
**Problem:** The attention-filters skill describes what each archetype should/shouldn't receive, but the orchestration skill doesn't reference or enforce it when spawning agents.
**Solution:** Add concrete context-assembly instructions to `archeflow/skills/orchestration/SKILL.md`
**Changes:**
- `archeflow/skills/orchestration/SKILL.md` — In each phase's agent-spawning step, add explicit context rules:
```
## Step 1: Plan Phase
### Spawn Explorer
**Context to include:** Task description, relevant file paths
**Context to exclude:** Prior proposals, review outputs, implementation details
### Spawn Creator
**Context to include:** Task description, Explorer's Research output
**Context to exclude:** Raw file contents (Explorer already summarized), review history
```
- Reference the attention-filters skill but inline the actionable rules
**Token impact:** This is the biggest savings — prevents passing full codebase dumps to every agent. Each agent gets only what it needs.
### 5. Metrics in Orchestration Skill
**Problem:** No timing or cost tracking at the skill layer. The TypeScript metrics collector exists but isn't available when running via Claude Code skills.
**Solution:** Add lightweight metrics protocol to orchestration skill — track per-phase duration and agent count.
**Changes:**
- `archeflow/skills/orchestration/SKILL.md` — Add "Metrics" section:
- After each phase, log: `Phase | Duration | Agents | Findings`
- At orchestration end, summarize: total duration, cycles run, agents spawned, findings by severity
- Format as compact table in orchestration output
- Keep it lightweight — no token counting (not reliable from skill layer), just timing and counts
**Token impact:** ~50 extra tokens per orchestration for the summary. Provides data for future optimization.
### 6. Autonomous Mode Wiring
**Problem:** Autonomous mode skill exists as standalone doc but isn't integrated into the orchestration skill's flow.
**Solution:** Add autonomous mode hooks to orchestration skill.
**Changes:**
- `archeflow/skills/orchestration/SKILL.md` — Add "Autonomous Mode" section:
- When running unattended: auto-commit between cycles, log progress to `.archeflow/session-log.md`
- Reference stop conditions from autonomous-mode skill
- Add "between-task checkpoint" protocol: after each task completes, update session log before starting next
- `archeflow/skills/autonomous-mode/SKILL.md` — Add cross-reference to orchestration skill for execution details
**Token impact:** Minimal — only adds content to skill files loaded on-demand.
## Future Features (add to backlog)
Add to `archeflow/docs/roadmap.md`:
- **Web Dashboard**: Real-time orchestration visualization via SSE/WebSocket (`tool.archeflow/packages/web/`)
- **A2A Protocol**: Direct agent-to-agent negotiation during Check phase (schemas exist in `tool.archeflow`)
- **GitHub Action**: CI-triggered orchestrations for PR review automation
## Files to Modify
| File | Change |
|------|--------|
| `archeflow/skills/orchestration/SKILL.md` | Feedback loop, attention filters, metrics, autonomous hooks |
| `archeflow/skills/plan-phase/SKILL.md` | Prior feedback input for Creator |
| `archeflow/skills/check-phase/SKILL.md` | Standardized finding format for parsing |
| `archeflow/skills/shadow-detection/SKILL.md` | Quantitative detection checklists |
| `archeflow/skills/autonomous-mode/SKILL.md` | Cross-reference to orchestration |
| `archeflow/docs/roadmap.md` | New file — future features backlog |
| Directory | Action |
|-----------|--------|
| `claude-archeflow-plugin/` | Delete (redundant) |
## Verification
1. Load each modified skill via `Skill` tool — verify no syntax/formatting errors
2. Run a test orchestration (fast workflow) on a small task to verify:
- Attention filters are referenced in agent spawning
- Check phase outputs use standardized finding format
- Feedback is structured and routed correctly
3. Verify shadow detection checklist is actionable (can an orchestrator evaluate each checkbox?)
4. Confirm `claude-archeflow-plugin/` removal doesn't break any references
## Cost-Benefit Summary
| Change | Token Cost | Quality Gain |
|--------|-----------|-------------|
| Cross-cycle feedback | +200/cycle | High — targeted revision instead of blind retry |
| Consolidate dirs | 0 | Medium — eliminates drift, single source of truth |
| Shadow heuristics | +200 skill load | Medium — catches dysfunction before it wastes cycles |
| Attention filters | **-30-50% per agent** | High — massive token savings |
| Metrics | +50/orchestration | Low-Medium — enables future optimization |
| Autonomous wiring | +100 skill load | Medium — enables unattended quality runs |
**Net effect:** Token usage goes DOWN (attention filters save more than everything else adds). Quality goes UP (structured feedback, shadow detection, metrics).

36
docs/roadmap.md
View File

@@ -10,33 +10,23 @@
- [x] Orchestration metrics (timing, agent count, findings)
- [x] Autonomous mode integrated into orchestration flow
- [x] Plugin consolidation (single `archeflow/` directory)
- [x] Workflow intelligence (conditional escalation, fast-path, confidence triggers)
- [x] Quality loop (self-review, convergence detection, dedup, completion promises)
- [x] Parallel teams, auto-resume, budget scheduling
- [x] Extensibility (archetype composition, team presets, hook points, workflow templates)
- [x] Mini-reflect for non-ArcheFlow changes
## Future Features
## Future
### Web Dashboard
Real-time orchestration visualization via SSE/WebSocket. Infrastructure exists in `tool.archeflow/packages/web/` (routes, SSE, WebSocket, conflict resolution UI). Needs frontend implementation and connection to event store.
**Value:** Visual monitoring of long/overnight orchestrations, conflict resolution UI.
**Cost:** Medium — frontend work, hosting. Low incremental token cost.
### A2A Protocol (Agent-to-Agent)
Direct inter-agent negotiation during Check phase. Schemas defined in `tool.archeflow/packages/core/`. Currently agents communicate only through artifacts (files) — A2A would allow real-time back-and-forth (e.g., Guardian asking Maker to clarify a code choice before issuing verdict).
**Value:** Fewer full cycles needed — issues resolved within a phase.
**Cost:** High complexity. Risk of increased token usage if negotiations run long. Needs strict turn limits.
### GitHub Action Integration
CI-triggered orchestrations for automated PR review. Package exists at `tool.archeflow/packages/action/` with minimal implementation.
**Value:** Automated quality gates on every PR without manual orchestration.
**Cost:** Low implementation effort, but ongoing CI minutes cost. Best for high-value repos.
| Feature | Value | Effort | Notes |
|---------|-------|--------|-------|
| A2A Protocol | Fewer cycles via in-phase negotiation | High | Needs strict turn limits |
| GitHub Action | Automated PR review via CI | Low | CI minutes cost |
| Web Dashboard | Real-time orchestration visualization | Medium | SSE/WebSocket frontend |
## Version History
Maintainers should update this table when significant features ship or major improvements are completed. Reverse chronological order (latest first).
| Date | Changes |
|------|---------|
| 2026-04-03 | 25-feature release — workflow intelligence (conditional escalation, fast-path, confidence triggers), quality loop (self-review, convergence detection, dedup, completion promises, post-merge verification), parallel teams, auto-resume, budget scheduling, DX (progress indicators, dry-run, status/history commands, onboarding), extensibility (archetype composition, team presets, hook points, workflow templates, reviewer profiles, explorer cache, learning from history), Ralph Loop integration (mini-reflect, alternatives, structured confidence) |
| 2026-04-03 | Core improvements — cross-cycle feedback loop, attention filter enforcement, shadow detection heuristics, orchestration metrics, autonomous mode wiring, plugin consolidation, emoji avatars for archetypes |
| 2026-04-03 | Initial roadmap created with completed features and future backlog |
| 2026-04-03 | v0.2 — Plugin consolidation, shareable structure, examples |
| 2026-04-03 | v0.1 — Full feature set: 7 archetypes, 10 skills, PDCA workflows, shadow detection, autonomous mode, extensibility |

56
examples/custom-archetypes/story-explorer.md Normal file
View File

@@ -0,0 +1,56 @@
---
name: story-explorer
description: |
Researches story foundations — setting, character dynamics, thematic possibilities, plot seeds.
Use in Plan phase for creative writing tasks.
model: haiku
---
You are the **Story Explorer** archetype. You research the foundations a story needs before anyone writes a word.
## Your Virtue: Thematic Clarity
You see the emotional core before anyone acts. You map character dynamics, spot narrative patterns, and surface the story's central question. Without you, the Creator outlines blind and the Maker writes without direction.
## Your Lens
"What is this story really about? What makes it matter? What's the emotional engine?"
## Process
1. Read the story brief / premise carefully
2. Read character files if they exist
3. Read the voice profile and persona rules
4. Identify the emotional core (what universal truth does this explore?)
5. Map character dynamics (who wants what, who's in the way?)
6. Sketch the setting's role (is it backdrop or character?)
7. Identify 2-3 possible plot directions
8. Recommend the strongest one
## Output Format
```markdown
## Story Research: <premise>
### Emotional Core
One sentence: what this story is really about.
### Characters in Play
- Character — role, want, obstacle
### Setting as Character
How the location shapes the story.
### Plot Seeds
1. Direction A — brief pitch + why it works
2. Direction B — brief pitch + why it works
3. Direction C — brief pitch + why it works
### Recommendation
<one paragraph: which direction + rationale>
```
## Rules
- Lead with emotion, not plot mechanics. Plot serves theme.
- Keep it under 800 words. The Creator needs direction, not a novel.
- Every recommendation must be writable in the story's target word count.
- Reference the voice profile constraints — don't suggest things the voice forbids.
## Shadow: Endless Research
You keep exploring "one more angle" without landing on a direction. If you have 4+ plot directions or your output exceeds 1000 words — STOP. Pick the strongest direction and commit. A good-enough recommendation now beats a perfect one never.

59
examples/custom-archetypes/story-sage.md Normal file
View File

@@ -0,0 +1,59 @@
---
name: story-sage
description: |
Reviews prose quality, voice consistency, dialect authenticity, and narrative craft.
Use in Check phase for creative writing tasks.
model: sonnet
---
You are the **Story Sage** archetype. You evaluate whether the prose is good enough to publish.
## Your Virtue: Craft Judgment
You hear the voice. You feel the rhythm. You know when a sentence sings and when it clunks. Without you, technically correct prose goes out without soul.
## Your Lens
"Does this sound like the author it's supposed to be? Would a reader savor this or skim it?"
## Process
1. Read the voice profile (dimensions, verboten, erlaubt, vorbilder)
2. Read the prose
3. Check voice consistency — does it match the profile throughout?
4. Check prose quality — rhythm, imagery, dialogue, pacing
5. Check dialect usage — too much? Too little? Authentic?
6. Check for forbidden patterns (from voice profile)
7. Deliver verdict with specific line-level feedback
## Output Format
```markdown
## Prose Review: <story title>
### Voice Consistency: PASS / DRIFT
- Where does the voice hold? Where does it slip?
- Specific examples with line references.
### Prose Quality
- **Rhythm**: Does sentence length vary? Do paragraphs breathe?
- **Imagery**: Vivid and sensory, or generic?
- **Dialogue**: Natural speech or book-speech?
- **Pacing**: Does tension build? Are quiet moments earned?
### Dialect Check
- Frequency: too much / just right / too little
- Authenticity: do the Einsprengsel feel natural?
- Examples of what works, what doesn't.
### Forbidden Pattern Violations
- List any violations of the voice profile's verboten section.
### Verdict: APPROVED / REVISE
Top 3-5 specific fixes (with line references where possible).
```
## Rules
- Max 5 fixes per review. Quality over quantity.
- Every fix must include a concrete rewrite suggestion, not just "improve this."
- Read the voice profile FIRST. Your standard is the profile, not your taste.
- Dialect judgment: if it reads natural to a Münchner, it's fine.
## Shadow: Literary Perfectionist
Your prose sensitivity becomes endless revision requests. Review longer than the story? More than 5 fixes? Suggesting rewrites for lines that already work? STOP. The goal is publishable, not Pulitzer. Max 5 actionable fixes. Move on.

17
examples/teams/story-development.yaml Normal file
View File

@@ -0,0 +1,17 @@
# Team: Story Development
# For short fiction (Giesing Gschichten and similar)
name: story-development
description: "Kurzgeschichten-Entwicklung: Recherche, Outline, Draft, Review"
plan: [story-explorer, creator]
do: [maker]
check: [guardian, story-sage]
exit: all_approved
max_cycles: 2
# Context: story-explorer and story-sage are custom archetypes in .archeflow/archetypes/
# Guardian checks plot coherence and character consistency (standard archetype)
# Creator designs the outline (standard archetype, adapted by context)
# Maker drafts the prose (standard archetype, adapted by context)

54
examples/workflows/kurzgeschichte.yaml Normal file
View File

@@ -0,0 +1,54 @@
# Workflow: Kurzgeschichte
# For writing short fiction (5-8k words) with the story-development team
name: kurzgeschichte
description: "Short story development — from premise to polished draft"
team: story-development
phases:
plan:
archetypes: [story-explorer, creator]
parallel: false
description: |
1. story-explorer: Research premise, identify emotional core, recommend plot direction
2. creator: Design scene outline, character beats, tension arc
inputs:
- "Story premise / brief"
- "Character files (characters/*.yaml)"
- "Voice profile (vp-giesing-gschichten-v1)"
- "Persona rules (giesinger.yaml)"
do:
archetypes: [maker]
parallel: false
description: |
Draft the story following the outline.
Write in scenes, not chapters.
Commit after each scene.
inputs:
- "Scene outline from creator"
- "Voice profile for style reference"
- "Character files for consistency"
check:
archetypes: [guardian, story-sage]
parallel: true
description: |
guardian: Plot coherence, character consistency, continuity
story-sage: Prose quality, voice consistency, dialect authenticity
inputs:
- "Draft from maker"
- "Outline from creator (for guardian)"
- "Voice profile (for story-sage)"
act:
exit_when: all_approved
max_cycles: 2
on_reject: |
Route guardian findings back to creator (outline fix).
Route story-sage findings back to maker (prose fix).
hooks:
pre_plan: []
post_check: []
post_act: []

5
hooks/hooks.json
View File

@@ -2,12 +2,11 @@
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume|clear|compact",
"matcher": "",
"hooks": [
{
"type": "command",
"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start\"",
"async": false
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start\""
}
]
}

46
skills/onboarding/SKILL.md
View File

@@ -1,46 +0,0 @@
---
name: onboarding
description: Use when a user is new to ArcheFlow or asks "what is this?" / "how does this work?". Explains the plugin in 60 seconds.
---
# Welcome to ArcheFlow
ArcheFlow is a Claude Code plugin that automatically coordinates multiple AI agents when you give implementation tasks. Instead of one agent doing everything, specialized agents with different perspectives collaborate through quality cycles.
## What Just Happened
When you installed ArcheFlow, it activated automatically. From now on:
- **Give an implementation task** (feature, refactor, bug fix) → ArcheFlow kicks in
- **Give a quick task** (typo fix, question, config edit) → Claude handles it normally
You don't need to do anything different. Just describe your task.
## The 30-Second Version
```
You: "Add user authentication with JWT"
ArcheFlow:
🔍 Explorer researches your codebase (what files, what patterns, what tests)
<20><>️ Creator designs a proposal (architecture, file changes, test strategy)
⚒️ Maker implements it in a safe branch (isolated, nothing breaks)
🛡️ Guardian reviews for security (injection, auth bypass, data exposure)
🤔 Skeptic challenges assumptions (what if JWT isn't the right choice?)
📚 Sage checks quality (readable? tested? consistent with codebase?)
✅ All approve → merged. Issues? → automatic revision cycle.
```
## Key Concepts
- **Archetypes:** 7 specialized agent roles, each with a unique perspective
- **PDCA Cycles:** Plan → Do → Check → Act. If reviewers reject, it cycles back and improves
- **Worktrees:** Code changes happen on isolated branches. Nothing touches main until approved.
- **Shadow Detection:** If an agent gets stuck or dysfunctional, ArcheFlow detects and corrects it
- **Workflows:** `fast` (1 cycle, quick fixes), `standard` (2 cycles, features), `thorough` (3 cycles, security)
## Want to Learn More?
- `/archeflow:orchestration` — See the full step-by-step execution guide
- `/archeflow:shadow-detection` — How dysfunction is detected and corrected
- `/archeflow:autonomous-mode` — Run tasks overnight unattended