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

name, description

name	description
using-archeflow	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.

Session Start

On activation, print ONE line:

archeflow v0.3.0 · 25 skills · <domain> domain

Where <domain> is auto-detected: writing if colette.yaml exists, research if paper/thesis files exist, code otherwise. Then proceed silently — no further announcement unless archeflow:run is invoked.

During runs, follow the archeflow:presence skill for output format: show outcomes not mechanics, one line per phase, value at the end.

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