claude-archeflow-plugin/skills/using-archeflow/SKILL.md

---
name: using-archeflow
description: Use at session start when implementing features, reviewing code, debugging, or any task that benefits from multiple perspectives. Activates ArcheFlow multi-agent orchestration.
---

# ArcheFlow -- Active

Multi-agent orchestration using archetypal roles and PDCA quality cycles.

## IMPORTANT: When to Activate

You MUST use ArcheFlow orchestration (load `archeflow:orchestration` skill and follow its steps) for any task that matches:

- **New features** -- any feature touching 2+ files
- **Refactoring** -- structural changes across modules
- **Security-sensitive changes** -- auth, encryption, input handling, API keys
- **Bug fixes with unclear root cause** -- use Explorer to investigate first
- **Code review requests** -- spawn Guardian + relevant reviewers
- **Multi-file changes** -- anything beyond a single-file edit

Choose the workflow based on risk:

| Signal | Workflow | Command |
|--------|----------|---------|
| Small fix, low risk, single concern | `fast` | Creator --> Maker --> Guardian |
| Feature, multiple files, moderate risk | `standard` | Explorer + Creator --> Maker --> Guardian + Skeptic + Sage |
| Security-sensitive, breaking changes, public API | `thorough` | Explorer + Creator --> Maker --> All 4 reviewers |

## When to Skip ArcheFlow

Do NOT use ArcheFlow for these -- just do them directly:

- Single-line fixes, typos, formatting
- Answering questions (no code changes)
- Reading/exploring code without making changes
- Config changes to a single file
- Git operations (commit, push, branch)

**Mini-Reflect fallback:** Even when skipping ArcheFlow, apply a quick reflection for non-trivial single-file changes: (1) restate what you're changing, (2) name one assumption, (3) check if it could break anything. This takes ~10 seconds and catches misunderstandings before they become commits.

## Archetypes

| 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 |

## PDCA Cycle

```
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.
```

## Progress Indicators

During orchestration, emit phase markers so the user can track progress:

```
--- ArcheFlow: <task> -------------------------
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 -----------------
```

Update each line as agents complete. This gives the user real-time visibility without interrupting the flow.

## Dry-Run Mode

When the user asks "what would ArcheFlow do?" or uses `--dry-run`, show the plan without executing:

```
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]
```

## Quick Start

When the user gives an implementation task:

1. Assess: does this need ArcheFlow? (see criteria above)
2. If yes: load `archeflow:orchestration` skill
3. Pick workflow (fast/standard/thorough)
4. Execute the PDCA steps from the orchestration skill
5. Emit progress indicators throughout (see above)

## Available Commands

| Command | What it does |
|---------|-------------|
| `archeflow:run` | Automated PDCA loop -- single command to orchestrate a full run |
| `archeflow:orchestration` | Load manual PDCA execution guide |
| `archeflow:shadow-detection` | Load shadow monitoring rules |
| `archeflow:autonomous-mode` | Load autonomous/overnight session protocol |
| `archeflow:status` | Show current orchestration state (phase, cycle, active agents) |
| `archeflow:history` | Show past orchestration summaries from `.archeflow/session-log.md` |

### `archeflow:status`
Read `.archeflow/state.json` (if exists) and report:
- Current task, phase, and cycle
- Active agents and their status
- Findings so far (by severity)
- Time elapsed

### `archeflow:history`
Read `.archeflow/session-log.md` and show the last 5 orchestration summaries in compact format.

## Skills Reference (All 24)

### Core Orchestration
- **archeflow:run** -- Automated PDCA execution loop with `--start-from` and `--dry-run`
- **archeflow:orchestration** -- Step-by-step manual execution guide
- **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
- **archeflow:shadow-detection** -- Quantitative dysfunction detection and correction
- **archeflow:attention-filters** -- Context optimization per archetype
- **archeflow:convergence** -- Detects convergence, stalling, and oscillation in multi-cycle runs
- **archeflow:artifact-routing** -- Inter-phase artifact protocol for naming, storage, and routing

### Process Intelligence
- **archeflow:process-log** -- Event-sourced JSONL logging with DAG parent relationships
- **archeflow:memory** -- Cross-run learning from recurring findings
- **archeflow:effectiveness** -- Archetype scoring on signal-to-noise, fix rate, cost efficiency
- **archeflow:progress** -- Live progress file watchable from a second terminal

### Integration
- **archeflow:colette-bridge** -- Bridges ArcheFlow with the Colette writing platform
- **archeflow:git-integration** -- Git-per-phase commits, branch-per-run, rollback
- **archeflow:multi-project** -- Cross-repo orchestration with dependency DAG and shared budget

### Configuration
- **archeflow:custom-archetypes** -- Create domain-specific roles
- **archeflow:workflow-design** -- Design custom workflows with per-phase archetype assignment
- **archeflow:domains** -- Domain adapters for writing, research, and non-code workflows
- **archeflow:cost-tracking** -- Budget enforcement and model tier recommendations
- **archeflow:templates** -- Template gallery for sharing workflows, teams, and setup bundles
- **archeflow:autonomous-mode** -- Unattended overnight sessions

### Meta
- **archeflow:using-archeflow** -- This skill: session-start activation and quick reference