claude-archeflow-plugin/skills/act-phase/SKILL.md

name, description

name	description
act-phase	Use after the Check phase completes. Collects reviewer findings, routes fixes, applies them, decides whether to exit or cycle. <example>Automatically loaded during orchestration after Check phase</example>

Act Phase

Turn Check phase findings into fixes, then decide: exit or cycle.

Check output → Collect → Deduplicate → Route → Fix → Exit or Cycle

---

Step 1: Collect and Consolidate Findings

Parse all reviewer outputs into one table grouped by severity (CRITICAL / WARNING / INFO):

#	Source	Location	Category	Description	Suggested Fix
1	guardian	src/auth/handler.ts:48	security	Empty string bypasses validation	Add length check

Deduplication

Same file + same category + similar description = one finding. Use the higher severity, credit all sources (e.g. guardian + skeptic).

Cross-Cycle Tracking (cycle > 1)

Compare against prior cycle findings:

• Resolved — no longer present, mark resolved, do not re-raise
• Persisting — same location + category, increment cycle_count
• New — first appearance, cycle_count: 1

Finding persisting 2+ cycles = flag for escalation (see Step 4).

---

Step 2: Fix Routing

This is the canonical routing table (single source of truth for the whole system):

Source	Category	Routes to	Reason
Guardian	security, breaking-change	Creator	Design must change
Guardian	reliability, dependency	Creator	Architectural decision needed
Skeptic	design, scalability	Creator	Assumptions need revision
Sage	quality, consistency	Maker	Implementation refinement
Sage	testing	Maker	Test gap, not design flaw
Trickster	reliability (design flaw)	Creator	Needs redesign
Trickster	reliability (test gap), testing	Maker	Needs more tests

Disambiguation: If the fix requires changing the approach → Creator. If it requires changing code within the existing approach → Maker.

Direct Fix (no agent)

Apply with Edit tool when all are true:

• Mechanical (typo, naming, formatting, import order)
• No behavioral change
• No test update needed
• Single file

Maker Fix (spawn agent)

Spawn a targeted Maker when the fix involves code logic, tests, multiple files, or behavioral changes. Batch findings in the same file area into one Maker spawn.

Agent(
  description: "Fix: <description>",
  prompt: "You are the MAKER archetype.
    Branch: <maker's branch>
    Findings:
    1. [CRITICAL] file:line — issue → suggested fix
    2. [WARNING] file:line — issue → suggested fix
    Rules: fix ONLY these issues, add/update tests if behavior changes,
    run tests, commit each fix separately as 'fix: <description>'.
    Do NOT refactor surrounding code.",
  isolation: "worktree",
  mode: "bypassPermissions"
)

Design Fix (route to Creator)

Design findings are NOT fixed in Act. Collect them into act-feedback.md for the Creator in the next cycle (see Step 5).

---

Step 3: Fix Application

Apply in severity order: CRITICAL → WARNING → INFO. Within same severity, group by file.

For each fix:

1. Apply the change (direct edit or via Maker agent)
2. Emit fix.applied event with source, finding, file, severity, before/after
3. For non-trivial fixes: re-run only the originating reviewer scoped to changed files. New findings from re-check get added with source re-check:<reviewer>

---

Step 4: Exit Decision

CRITICAL = 0 AND criteria met        → EXIT: proceed to merge
CRITICAL = 0 AND criteria NOT met    → CYCLE: feedback to Creator
CRITICAL > 0 AND cycles remaining    → CYCLE: build feedback, go to Plan
CRITICAL > 0 AND no cycles left      → STOP: report unresolved to user
Same CRITICAL persists 2+ cycles     → ESCALATE: ask user for guidance

Emit cycle.boundary event with: cycle number, max_cycles, critical/warning/info remaining, fixes applied, next action.

---

Step 5: Cycle Feedback

When cycling back, produce act-feedback.md:

## Cycle N → Cycle N+1

### For Creator (design changes needed)
| # | Source | Severity | Category | Issue | Cycles Open |
|---|--------|----------|----------|-------|-------------|

### For Maker (implementation fixes needed)
| # | Source | Severity | Category | Issue | Cycles Open |
|---|--------|----------|----------|-------|-------------|

### Resolved This Cycle
| # | Source | Issue | How Resolved |
|---|--------|-------|--------------|

### Persisting Issues (escalation candidates)
| # | Source | Issue | Cycles Open | Action |
|---|--------|-------|-------------|--------|

Route findings into Creator vs Maker sections using the routing table in Step 2.