diff --git a/skills/check-phase/SKILL.md b/skills/check-phase/SKILL.md index fc9212f..40170ab 100644 --- a/skills/check-phase/SKILL.md +++ b/skills/check-phase/SKILL.md @@ -76,6 +76,107 @@ Use the higher severity. Don't double-count in the verdict. → Build cycle feedback (see orchestration skill) and feed to Plan phase ``` +## Reviewer Spawning Protocol + +This section defines the exact sequence for spawning reviewers in the Check phase. + +### Step 1: Guardian First (mandatory) + +Guardian always runs first, before any other reviewer. It receives the Maker's git diff and the proposal's risk section only. + +**Context for Guardian:** +- `git diff main...` (the actual code changes) +- Risk section from `plan-creator.md` (if present) +- Do NOT include: Explorer research, full proposal, other reviewer outputs + +``` +Agent( + description: "Guardian: security and risk review for ", + prompt: "You are the GUARDIAN archetype. + Review the diff: + Proposal risks: + Assess: security vulnerabilities, reliability risks, breaking changes, dependency risks. + Output: APPROVED or REJECTED with findings in the standardized format. + Each finding: | Location | Severity | Category | Description | Fix |", + model: +) +``` + +Save output to `.archeflow/artifacts/${RUN_ID}/check-guardian.md`. + +### Step 2: A2 Fast-Path Evaluation + +After Guardian completes, parse its output before spawning other reviewers: + +```bash +CRITICAL_COUNT=$(grep -ci "CRITICAL" ".archeflow/artifacts/${RUN_ID}/check-guardian.md" || echo 0) +WARNING_COUNT=$(grep -ci "WARNING" ".archeflow/artifacts/${RUN_ID}/check-guardian.md" || echo 0) + +if [[ "$CRITICAL_COUNT" -eq 0 && "$WARNING_COUNT" -eq 0 && "$ESCALATED" != "true" ]]; then + # A2 fast-path: skip remaining reviewers + echo "Guardian fast-path: 0 CRITICAL, 0 WARNING — skipping remaining reviewers." + # Proceed directly to Act phase +fi +``` + +**Exception:** First cycle of `thorough` workflows always spawns all reviewers, even if Guardian is clean. + +### Step 3: Parallel Reviewer Spawning + +If A2 does not trigger, spawn remaining reviewers in parallel based on workflow: + +| Workflow | Reviewers (after Guardian) | +|----------|--------------------------| +| `fast` | None (Guardian only) | +| `fast` (escalated via A1) | Skeptic + Sage | +| `standard` | Skeptic + Sage | +| `thorough` | Skeptic + Sage + Trickster | + +Spawn all applicable reviewers in a single message with multiple Agent calls: + +``` +# Standard workflow example — spawn Skeptic and Sage in parallel: +Agent( + description: "Skeptic: challenge assumptions for ", + prompt: "", + model: +) + +Agent( + description: "Sage: holistic quality review for ", + prompt: "", + model: +) +``` + +Each reviewer gets context per the attention filters defined in `archeflow:orchestration`: +- **Skeptic:** Creator's proposal (assumptions section focus) +- **Sage:** Creator's proposal + Maker's diff + implementation summary +- **Trickster:** Maker's diff only + +### Step 4: Collect Results + +Wait for all spawned reviewers to return. For each: +1. Save output to `.archeflow/artifacts/${RUN_ID}/check-.md` +2. Emit `review.verdict` event with findings +3. Record sequence number for DAG parent tracking + +### Timeout Handling + +Each reviewer has a **5-minute timeout**. If a reviewer does not return within 5 minutes: +1. Emit `agent.complete` with `"error": true, "reason": "timeout"` +2. Log a WARNING — do not block the run +3. Treat the timed-out reviewer as having delivered no findings (neither approved nor rejected) +4. Proceed with available verdicts + +If Guardian times out, this is a blocking failure — abort the Check phase and report to the user. + +### Re-Check Protocol (Act Phase Fixes) + +When the Act phase routes findings back to the Maker and the Maker applies fixes in a subsequent cycle, the Check phase re-runs with the updated diff. Reviewers who previously rejected should focus on whether their specific findings were addressed. The structured feedback from `act-feedback.md` provides the mapping of which findings were routed where. + +--- + ## Why Structured Findings Matter The standardized format enables: diff --git a/skills/orchestration/SKILL.md b/skills/orchestration/SKILL.md index cf0f829..335e3d6 100644 --- a/skills/orchestration/SKILL.md +++ b/skills/orchestration/SKILL.md @@ -194,6 +194,8 @@ Agent( Spawn Guardian **first**. After Guardian completes, check adaptation rule A2 (fast-path). If A2 triggers (0 CRITICAL, 0 WARNING, non-escalated workflow), skip remaining reviewers and proceed to Act. Otherwise, spawn remaining reviewers **in parallel**. +**Reviewer spawning protocol:** The canonical sequence (Guardian first, A2 evaluation, parallel spawning, timeout handling) is defined in `archeflow:check-phase` under "Reviewer Spawning Protocol". Follow that protocol for the exact spawning order, context per reviewer, and timeout rules. + ### Guardian (always runs first) **Context to include:** Maker's git diff, proposal risk section only.