claude-archeflow-plugin/skills/workflow-design/SKILL.md

name, description

name	description
workflow-design	Use when designing custom orchestration workflows — choosing which archetypes run in each PDCA phase, setting exit conditions, and configuring PDCA cycles.

Workflow Design — PDCA Cycles

ArcheFlow's PDCA cycles spiral upward through iterations — each cycle incorporates feedback from the previous one, producing progressively better results. Each cycle incorporates feedback from the previous one.

        ╱ Act ──────────── Done ✓
       ╱        ↑
      ╱    Check (review)
     ╱         ↑
    ╱      Do (implement)
   ╱           ↑
  ╱       Plan (design)     ← Cycle 2 (with feedback from Cycle 1)
 ╱              ↑
╱          Act ─┘ (issues found → feed back)
│              ↑
│         Check (review)
│              ↑
│          Do (implement)
│              ↑
│         Plan (design)     ← Cycle 1 (initial)

Strategy vs Workflow

A strategy defines the execution shape: PDCA is cyclic (Plan-Do-Check-Act with feedback loops), pipeline is linear (Plan-Implement-Review-Verify, no cycle-back). A workflow defines the depth: fast uses fewer agents and cycles, thorough uses more. Strategy and workflow are orthogonal — you can run a fast workflow with either strategy, though thorough always uses PDCA because linear flows cannot iterate on findings.

Built-in Workflows

fast — Single Turn

Plan:  Creator designs
Do:    Maker implements (worktree)
Check: Guardian reviews
Act:   Approve or reject (1 cycle max)

Use for: Bug fixes, small changes, low-risk tasks.

standard — Two Cycles

Plan:  Explorer researches → Creator designs
Do:    Maker implements (worktree)
Check: Guardian + Skeptic + Sage review (parallel)
Act:   Approve or cycle (2 cycles max)

Use for: Features, refactors, moderate-risk changes.

thorough — Three Cycles

Plan:  Explorer researches → Creator designs
Do:    Maker implements (worktree)
Check: Guardian + Skeptic + Sage + Trickster (parallel)
Act:   Approve or cycle (3 cycles max)

Use for: Security-critical, public APIs, infrastructure changes.

Designing Custom Workflows

Step 1: Identify the Concern

What's the primary risk?

Primary Risk	Emphasize
Security	Guardian + Trickster in Check
Correctness	Skeptic + Sage in Check
Performance	Custom perf-tester archetype
Compliance	Custom compliance-auditor archetype
Data integrity	Custom db-specialist archetype
User experience	Custom ux-reviewer archetype

Step 2: Assign Phases

Rules:

• Plan always includes Creator (someone must propose)
• Do always includes Maker (someone must build)
• Check needs at least one reviewer
• Max 3 archetypes per phase (diminishing returns beyond that)
• Explorer goes in Plan only (research before design)
• Maker goes in Do only (build from plan, not from scratch)

Step 3: Set Exit Conditions

Condition	When Cycle Ends	Best For
all_approved	Every Check reviewer says APPROVED	Consensus-driven (default)
no_critical	No CRITICAL findings in Check output	Speed with safety net
convergence	No new issues vs. previous cycle	Diminishing returns detection
always	Runs all maxCycles unconditionally	Research, exploration

Step 4: Set Max Cycles

• 1 cycle: Fast, low-risk (fast workflow)
• 2 cycles: Balanced — one shot + one fix (standard workflow)
• 3 cycles: Thorough — usually converges by cycle 3
• 4+ cycles: Rarely useful. If 3 cycles don't converge, the task needs human input.

Example Custom Workflows

Security-First

Plan:  Explorer (threat modeling) → Creator
Do:    Maker
Check: Guardian + Trickster (parallel)
Exit:  all_approved, max 3 cycles

Research-Heavy

Plan:  Explorer (deep research) → Creator
Do:    Maker
Check: Skeptic + Sage (parallel)
Exit:  all_approved, max 2 cycles

Domain-Specific (with custom archetypes)

Plan:  Explorer → Creator
Do:    Maker
Check: Guardian + db-specialist + compliance-auditor (parallel)
Exit:  all_approved, max 2 cycles

Minimal Validation

Plan:  Creator (no research)
Do:    Maker
Check: Guardian
Exit:  no_critical, max 1 cycle

Hook Points

Add project-specific validation at key moments in the PDCA cycle. Define hooks in .archeflow/hooks.yaml:

# .archeflow/hooks.yaml
pre-plan:
  - command: "npm run lint"
    description: "Ensure clean baseline before planning"
    fail_action: abort  # abort | warn | ignore

post-check:
  - command: "npm test"
    description: "Run tests after review to verify reviewer suggestions"
    fail_action: cycle_back

pre-merge:
  - command: "./scripts/check-migrations.sh"
    description: "Verify migration safety before merging"
    fail_action: abort

post-merge:
  - command: "npm run integration-test"
    description: "Full integration test after merge"
    fail_action: revert

Available hook points:

Hook	When	Typical Use
pre-plan	Before Explorer/Creator start	Lint, ensure clean baseline
post-plan	After Creator's proposal	Validate proposal against constraints
pre-do	Before Maker starts	Check worktree setup
post-do	After Maker commits	Quick smoke test
post-check	After reviewers finish	Run test suite
pre-merge	Before merging to main	Migration safety, API compatibility
post-merge	After merge completes	Integration tests, deploy checks

Workflow Template Library

Pre-built workflows for common scenarios. Use as-is or as starting points for custom workflows.

API Design

name: api-design
description: New or changed API endpoints
plan: [explorer, creator]
do: [maker]
check: [guardian, skeptic]  # Guardian for security, Skeptic for API design assumptions
exit: all_approved
max_cycles: 2
hooks:
  post-check: "npm run api-compatibility-check"

Database Migration

name: migration
description: Schema changes and data migrations
plan: [explorer, creator]
do: [maker]
check: [guardian, db-specialist]  # Requires custom db-specialist archetype
exit: all_approved
max_cycles: 2
hooks:
  pre-merge: "./scripts/check-migration-reversibility.sh"

Dependency Upgrade

name: dep-upgrade
description: Upgrading dependencies (major versions, security patches)
plan: [creator]  # No Explorer needed — changelog is the research
do: [maker]
check: [guardian]
exit: no_critical
max_cycles: 1
hooks:
  post-do: "npm audit"
  post-merge: "npm test && npm run e2e"

Documentation Rewrite

name: docs-rewrite
description: Major documentation changes
plan: [explorer, creator]
do: [maker]
check: [sage]  # Quality/consistency only — no security review needed
exit: all_approved
max_cycles: 1

Hotfix

name: hotfix
description: Emergency production fix
plan: [creator]
do: [maker]
check: [guardian]
exit: no_critical
max_cycles: 1
hooks:
  post-merge: "npm test"

Anti-Patterns

• Kitchen sink: Putting all 7 archetypes in Check. Most can't add value simultaneously.
• Runaway cycles: maxCycles > 4 burns tokens without convergence.
• Reviewerless Do: Skipping Check phase "to save time." You'll pay in bugs.
• Maker in Plan: Maker should implement from a proposal, not design on the fly.
• Solo orchestration: One archetype in every phase. That's just a single agent with extra steps.