diff --git a/.archeflow/config.yaml b/.archeflow/config.yaml index ff79540..1152d1e 100644 --- a/.archeflow/config.yaml +++ b/.archeflow/config.yaml @@ -3,6 +3,9 @@ version: "0.6.0" +# Strategy — execution shape: pdca (cyclic), pipeline (linear), auto (task-based selection) +strategy: auto + # Budget costs: budget_usd: 10.00 diff --git a/skills/orchestration/SKILL.md b/skills/orchestration/SKILL.md index 335e3d6..68846c2 100644 --- a/skills/orchestration/SKILL.md +++ b/skills/orchestration/SKILL.md @@ -7,6 +7,58 @@ description: Use when executing a multi-agent orchestration — spawning archety This skill guides you through running a full ArcheFlow orchestration using Claude Code's native Agent tool and git worktrees. +## Strategy Selection + +A **strategy** defines the shape of an orchestration run — which phases execute, in what order, and when to iterate. A **workflow** (fast/standard/thorough) controls the depth within a strategy. + +### Available Strategies + +| Strategy | Flow | When to Use | +|----------|------|-------------| +| `pdca` | Plan -> Do -> Check -> Act (cyclic) | Refactors, thorough reviews, multi-concern tasks | +| `pipeline` | Plan -> Implement -> Spec-Review -> Quality-Review -> Verify (linear) | Bug fixes, fast patches, single-concern tasks | +| `auto` | Selected by task analysis | Default — let ArcheFlow decide | + +### Strategy Interface + +Every strategy defines: + +- **Phases** — ordered list of execution stages +- **Agent mapping** — which archetypes run in each phase +- **Transition rules** — conditions for moving between phases +- **Iteration model** — cyclic (PDCA) or linear (pipeline) +- **Exit conditions** — when the run terminates + +### PDCA Strategy + +The existing orchestration flow (Steps 0-4 below). Cyclic — the Act phase can feed back to Plan for another iteration. Best for tasks requiring multiple review perspectives and iterative refinement. + +### Pipeline Strategy + +Linear flow with no cycle-back. Faster for well-understood tasks where one pass is sufficient. + +| Phase | Agent | Purpose | +|-------|-------|---------| +| Plan | Creator | Design proposal | +| Implement | Maker | Build in worktree | +| Spec-Review | Guardian, then Skeptic | Security + assumption check (sequential) | +| Quality-Review | Sage | Code quality review | +| Verify | (automated) | Run tests, apply targeted fix if CRITICAL | + +No cycle-back — WARNINGs are logged but do not block. CRITICALs in Verify trigger a single targeted fix attempt by the Maker, not a full cycle. + +### Auto-Selection Rules + +When `strategy: auto` (default): + +- Task contains "fix", "bug", "patch", "hotfix" → `pipeline` +- Task contains "refactor", "redesign", "review" → `pdca` +- Workflow is `thorough` → `pdca` (always) +- Workflow is `fast` with single file → `pipeline` +- Otherwise → `pdca` + +--- + ## Step 0: Choose a Workflow If `.archeflow/teams/.yaml` exists, the user can reference a team preset: `"Use the backend team"`. Load the preset's phase config instead of built-in defaults. See `archeflow:custom-archetypes` skill for preset format. diff --git a/skills/run/SKILL.md b/skills/run/SKILL.md index bcb7124..3bb724a 100644 --- a/skills/run/SKILL.md +++ b/skills/run/SKILL.md @@ -63,7 +63,38 @@ After emitting `run.start`, record `SEQ_RUN_START=1`. If `--start-from` is specified, verify that the required prior artifacts exist in `.archeflow/artifacts/${RUN_ID}/` before skipping phases. If missing, abort with an error. -#### 0a. Lib Script Validation +#### 0a. Strategy Resolution + +Determine the execution strategy before proceeding. Strategy controls the overall flow shape (cyclic vs linear). + +```bash +# Read strategy from config or CLI flag +STRATEGY=$(grep '^strategy:' "$CONFIG" 2>/dev/null | sed 's/strategy:\s*//' | tr -d '"' | head -1) +STRATEGY="${STRATEGY:-auto}" + +# CLI override: --strategy pdca|pipeline +# (parsed from invocation args, overrides config) + +# Auto-select logic +if [[ "$STRATEGY" == "auto" ]]; then + TASK_LOWER=$(echo "$TASK" | tr '[:upper:]' '[:lower:]') + if echo "$TASK_LOWER" | grep -qE '(fix|bug|patch|hotfix)'; then + STRATEGY="pipeline" + elif echo "$TASK_LOWER" | grep -qE '(refactor|redesign|review)'; then + STRATEGY="pdca" + elif [[ "$WORKFLOW" == "thorough" ]]; then + STRATEGY="pdca" + else + STRATEGY="pdca" + fi +fi + +echo "Strategy: $STRATEGY" +``` + +**Strategy dispatch:** If `STRATEGY=pdca`, execute Steps 1-5 below (existing PDCA flow). If `STRATEGY=pipeline`, skip to the "Pipeline Strategy Execution" section at the end of this skill. + +#### 0b. Lib Script Validation Verify that all required library scripts exist and are executable before proceeding. Fail fast if any dependency is missing. @@ -102,7 +133,7 @@ if ! command -v jq &>/dev/null; then fi ``` -#### 0b. Memory Injection +#### 0c. Memory Injection Load cross-run memory lessons and inject into agent prompts. Use `--audit` to track which lessons were injected for this run: @@ -121,7 +152,7 @@ ${MEMORY_LESSONS}" fi ``` -#### 0c. Model Configuration +#### 0d. Model Configuration Read model assignment from `.archeflow/config.yaml` and resolve the model for each archetype based on the current workflow. Per-workflow overrides take precedence over per-archetype overrides, which take precedence over the default. @@ -740,3 +771,74 @@ Run ID: | Workflow: | Cycle: 1/ Artifacts: .archeflow/artifacts// Report: .archeflow/events/.jsonl ``` + +--- + +## Pipeline Strategy Execution + +When `STRATEGY=pipeline`, execute this linear flow instead of the PDCA cycle above. + +### Pipeline Phases + +``` +Plan -> Implement -> Spec-Review -> Quality-Review -> Verify +``` + +No cycle-back. Each phase runs once. + +### 1. Plan + +Spawn Creator only (no Explorer). Use fast-workflow Creator prompt with Mini-Reflect. + +Save output to `.archeflow/artifacts/${RUN_ID}/plan-creator.md`. + +### 2. Implement + +Spawn Maker in isolated worktree with Creator's proposal. + +Save output to `.archeflow/artifacts/${RUN_ID}/do-maker.md`. + +### 3. Spec-Review + +Run Guardian and Skeptic **sequentially** (Guardian first, then Skeptic only if Guardian has findings). + +- Guardian receives: Maker's git diff + proposal risk section +- Skeptic receives: Creator's proposal (assumptions focus) + +Save to `check-guardian.md` and `check-skeptic.md`. + +### 4. Quality-Review + +Spawn Sage with proposal + diff + implementation summary. + +Save to `check-sage.md`. + +### 5. Verify + +Run the project's test suite. If tests pass and no CRITICAL findings exist: + +1. Merge the Maker's branch +2. Emit `run.complete` + +If CRITICAL findings exist: + +1. Spawn Maker for a **single targeted fix** — provide only the CRITICAL findings as context +2. Re-run tests +3. If still failing, report to user (do not cycle back) + +WARNINGs are logged in the run event but do not block the merge. + +### Pipeline Progress Display + +``` +━━━ ArcheFlow Pipeline: ━━━━━━━━━━━━━━━━ +Run ID: | Strategy: pipeline + +[Plan] Creator designing... -> done (20s) +[Implement] Maker building... -> done (60s, 3 files) +[Spec] Guardian reviewing... -> APPROVED +[Quality] Sage reviewing... -> APPROVED (1 WARNING) +[Verify] Tests passing... -> merged to main + +━━━ Complete: 2m 15s ━━━━━━━━━━━━━━━━━━━━━━━━━━ +``` diff --git a/skills/workflow-design/SKILL.md b/skills/workflow-design/SKILL.md index 0ad148b..9cd2992 100644 --- a/skills/workflow-design/SKILL.md +++ b/skills/workflow-design/SKILL.md @@ -25,6 +25,10 @@ ArcheFlow's PDCA cycles spiral upward through iterations — each cycle incorpor │ 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