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

refactor: trim 11 secondary ArcheFlow skills from 3340 to 952 lines

Browse Source 
Remove verbose YAML examples, bash pseudo-code, tutorial prose, and
motivational content from configuration/integration skills while
preserving all operational protocols, reference tables, and rules.

Skills trimmed: domains, colette-bridge, multi-project, cost-tracking,
git-integration, custom-archetypes, workflow-design, templates,
autonomous-mode, progress, presence.
This commit is contained in:
Christian Nennemann
2026-04-06 20:48:50 +02:00
parent c8bd55d97c
commit d94688ca1b
11 changed files with 485 additions and 2868 deletions
Download Patch File Download Diff File Expand all files Collapse all files

268
skills/workflow-design/SKILL.md
View File

@@ -1,248 +1,70 @@
---
name: workflow-design
description: Use when designing custom orchestration workflows — choosing which archetypes run in each PDCA phase, setting exit conditions, and configuring PDCA cycles.
description: 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
# 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.
PDCA cycles spiral upward: each cycle incorporates feedback from the previous one.
## 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.
| Workflow | Plan | Do | Check | Exit | Max Cycles |
|----------|------|----|-------|------|------------|
| `fast` | Creator | Maker | Guardian | approve/reject | 1 |
| `standard` | Explorer + Creator | Maker | Guardian + Skeptic + Sage | all_approved | 2 |
| `thorough` | Explorer + Creator | Maker | Guardian + Skeptic + Sage + Trickster | all_approved | 3 |
## Designing Custom Workflows
### Step 1: Identify the Concern
**Step 1: Identify the concern**
What's the primary risk?
| Risk | Emphasize in Check |
|------|-------------------|
| Security | Guardian + Trickster |
| Correctness | Skeptic + Sage |
| Performance | Custom `perf-tester` |
| Compliance | Custom `compliance-auditor` |
| Data integrity | Custom `db-specialist` |
| 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: Phase assignment rules**
- Plan always includes Creator
- Do always includes Maker
- Check needs at least one reviewer
- Max 3 archetypes per phase
- Explorer goes in Plan only; Maker goes in Do only
### Step 2: Assign Phases
**Step 3: Exit conditions**
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)
| Condition | Cycle ends when |
|-----------|----------------|
| `all_approved` | Every reviewer says APPROVED |
| `no_critical` | No CRITICAL findings |
| `convergence` | No new issues vs previous cycle |
| `always` | Runs all maxCycles unconditionally |
### 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
```
**Step 4: Max cycles** -- 1 (fast), 2 (balanced), 3 (thorough). 4+ rarely useful.
## Hook Points
Add project-specific validation at key moments in the PDCA cycle. Define hooks in `.archeflow/hooks.yaml`:
Define in `.archeflow/hooks.yaml`:
```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 |
| 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 |
| `pre-plan` | Before Explorer/Creator | Lint, clean baseline |
| `post-plan` | After Creator's proposal | Validate constraints |
| `pre-do` | Before Maker | Check worktree |
| `post-do` | After Maker commits | Smoke test |
| `post-check` | After reviewers | Run test suite |
| `pre-merge` | Before merge | Migration safety |
| `post-merge` | After merge | Integration tests |
## Workflow Template Library
Pre-built workflows for common scenarios. Use as-is or as starting points for custom workflows.
### API Design
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
name: hotfix
description: Emergency production fix
plan: [creator]
do: [maker]
check: [guardian]
exit: no_critical
max_cycles: 1
hooks:
post-merge: "npm test"
```
Each hook has `command`, `description`, and `fail_action` (abort / warn / ignore / cycle_back / revert).
## 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.
- All 7 archetypes in Check (diminishing returns)
- maxCycles > 4 (burns tokens without convergence)
- Skipping Check phase
- Maker in Plan phase
- One archetype in every phase (just a single agent with overhead)