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

name, description

name	description
act-phase	Use after the Check phase completes. Collects reviewer findings, prioritizes them, routes fixes to the right agent or tool, applies fixes systematically, and decides whether to exit or cycle. <example>Automatically loaded during orchestration after Check phase</example> <example>User: "Run just the act phase on existing findings"</example>

Act Phase

After all reviewers complete, the Act phase turns findings into fixes and decides whether the cycle is done. This is the bridge between "what's wrong" and "what we do about it."

Overview

Check phase output → Collect → Prioritize → Route → Fix → Verify → Exit or Cycle

---

Step 1: Finding Collection

Parse all reviewer outputs into one consolidated findings table. Use the standardized format from the check-phase skill.

## Findings Summary — Cycle N

### CRITICAL (must fix before next cycle)
| # | Source | Location | Category | Description | Suggested Fix |
|---|--------|----------|----------|-------------|---------------|
| 1 | guardian | src/auth/handler.ts:48 | security | Empty string bypasses validation | Add length check |
| 2 | trickster | src/api/parse.ts:92 | reliability | Null input causes crash | Guard with null check |

### WARNING (should fix)
| # | Source | Location | Category | Description | Suggested Fix |
|---|--------|----------|----------|-------------|---------------|
| 3 | sage | tests/auth.test.ts:15 | testing | Test names don't describe behavior | Rename to "should reject expired tokens" |
| 4 | guardian | src/auth/handler.ts:52 | security | Missing rate limit | Add rate limiter middleware |

### INFO (nice to have)
| # | Source | Location | Category | Description | Suggested Fix |
|---|--------|----------|----------|-------------|---------------|
| 5 | skeptic | src/auth/handler.ts:30 | design | Consider caching validated tokens | Add TTL cache |

Deduplication

Before listing findings, deduplicate across reviewers (same rule as check-phase):

• Same file + same category + similar description = one finding
• Use the higher severity
• Credit all sources: guardian + skeptic
• Don't double-count in severity tallies

Cross-Cycle Tracking

Compare against prior cycle findings (if cycle > 1):

• Resolved: Finding from cycle N-1 no longer present → mark resolved, do not re-raise
• Persisting: Same location + category still present → increment cycle_count
• New: Finding not seen before → add with cycle_count: 1

If a finding persists for 2+ consecutive cycles, flag for user escalation (see Step 5).

---

Step 2: Fix Routing

Not all findings are fixed the same way. Route each finding based on its nature:

Category	Fix Route	Rationale
security	Spawn Maker with targeted instructions	Security fixes need tested code changes
reliability	Spawn Maker with targeted instructions	Same — code-level fix with test
breaking-change	Route to Creator in next cycle	Design decision needed
design	Route to Creator in next cycle	Architecture change, not a patch
dependency	Spawn Maker with targeted instructions	Package update or removal
quality	Spawn Maker or apply directly	Depends on scope (see below)
testing	Spawn Maker with targeted instructions	Tests need to be written and run
consistency	Apply directly or spawn Maker	Naming/style → direct. Pattern change → Maker

Direct Fix (no agent)

Apply directly with Edit tool when all of these are true:

• The fix is mechanical (typo, naming, formatting, import order)
• No behavioral change
• No test update needed
• Exactly one file affected

Examples: rename a variable, fix a typo in a string, reorder imports, fix indentation.

Maker Fix (spawn agent)

Spawn a targeted Maker when the fix involves:

• Code logic changes
• New or modified tests
• Multiple files
• Any behavioral change

Provide the Maker with:

1. The specific finding(s) to address (not all findings — just the routed ones)
2. The file and line location
3. The suggested fix from the reviewer
4. The Maker's original branch (to apply fixes on top)

Agent(
  description: "Fix: <finding description>",
  prompt: "You are the MAKER archetype.
    Apply this fix on branch: <maker's branch>
    
    Finding: <source> | <severity> | <category>
    Location: <file:line>
    Issue: <description>
    Suggested fix: <fix>
    
    Rules:
    1. Fix ONLY this issue — no other changes
    2. Add/update tests if the fix changes behavior
    3. Run existing tests — nothing may break
    4. Commit with message: 'fix: <description>'
    Do NOT refactor surrounding code.",
  isolation: "worktree",
  mode: "bypassPermissions"
)

Writing/Prose Fix (domain-specific)

For writing projects (books, stories), voice or prose findings need special context:

Agent(
  description: "Fix: voice drift in <file>",
  prompt: "You are the MAKER archetype.
    Apply this prose fix on branch: <maker's branch>
    
    Finding: <source> | <severity> | <category>
    Location: <file:line>
    Issue: <description>
    
    Voice profile to match: <load from .archeflow/config.yaml or project voice profile>
    
    Rules:
    1. Fix the flagged passage to match the voice profile
    2. Do not rewrite surrounding paragraphs
    3. Preserve the narrative intent — only change voice/style
    4. Commit with message: 'fix: <description>'",
  isolation: "worktree",
  mode: "bypassPermissions"
)

Design Fix (route to next cycle)

Findings that require design changes are NOT fixed in the Act phase. They become structured feedback for the Creator in the next PDCA cycle. Collect them into act-feedback.md (see Step 5).

---

Step 3: Fix Application Protocol

Apply fixes in severity order: CRITICAL first, then WARNING, then INFO. Within the same severity, fix in file order (reduces context switching).

For each fix:

1. Apply the change (direct edit or via Maker agent)
2. Emit fix.applied event:

   {
     "type": "fix.applied",
     "phase": "act",
     "agent": "maker",
     "data": {
       "source": "guardian",
       "finding": "Empty string bypasses validation",
       "file": "src/auth/handler.ts",
       "line": 48,
       "severity": "CRITICAL",
       "before": "<old code>",
       "after": "<new code>"
     },
     "parent": [<seq of the review.verdict that found it>]
   }
   

3. Targeted re-check (if the fix is non-trivial):
   • Re-run only the reviewer that raised the finding
   • Scope the re-check to just the changed file(s)
   • If the re-check raises new findings → add them to the findings list with source re-check:<reviewer>

Batching Maker Fixes

If multiple findings route to the same Maker and affect the same file or tightly coupled files, batch them into a single Maker spawn:

Agent(
  description: "Fix: 3 findings in src/auth/",
  prompt: "You are the MAKER archetype.
    Apply these fixes on branch: <maker's branch>
    
    1. [CRITICAL] src/auth/handler.ts:48 — Empty string bypass → Add length check
    2. [WARNING] src/auth/handler.ts:52 — Missing rate limit → Add middleware
    3. [WARNING] tests/auth.test.ts:15 — Bad test names → Rename to behavior descriptions
    
    Fix all three. Commit each as a separate commit.
    Run tests after all fixes."
)

Batch only within the same functional area. Don't batch unrelated fixes — the Maker loses focus.

---

Step 4: Exit Decision

After all fixes are applied, evaluate exit conditions:

Decision Tree

┌─ Count remaining CRITICAL findings (including from re-checks)
│
├─ CRITICAL = 0 AND completion criteria met (if defined)
│  └─ EXIT: Proceed to merge
│
├─ CRITICAL = 0 AND completion criteria NOT met
│  └─ CYCLE: Feed back "completion criteria failing" to Creator
│
├─ CRITICAL > 0 AND cycles_remaining > 0
│  └─ CYCLE: Build feedback, go to Plan phase
│
├─ CRITICAL > 0 AND cycles_remaining = 0
│  └─ STOP: Report to user with unresolved findings
│
└─ Same CRITICAL finding persisted 2+ cycles
   └─ ESCALATE: Stop and ask user for guidance

Emit cycle.boundary event:

{
  "type": "cycle.boundary",
  "phase": "act",
  "data": {
    "cycle": 1,
    "max_cycles": 2,
    "exit_condition": "all_approved",
    "met": false,
    "critical_remaining": 1,
    "warning_remaining": 2,
    "info_remaining": 1,
    "fixes_applied": 3,
    "design_issues_forwarded": 1,
    "next_action": "cycle"
  }
}

---

Step 5: Cycle Feedback Protocol

When cycling back, produce act-feedback.md as a structured handoff. This replaces dumping raw findings.

## Cycle N Feedback → Cycle N+1

### For Creator (design changes needed)
| # | Source | Severity | Category | Issue | Cycles Open |
|---|--------|----------|----------|-------|-------------|
| 1 | guardian | CRITICAL | security | SQL injection in user input | 1 |
| 2 | skeptic | WARNING | design | Assumes single-tenant only | 1 |

### For Maker (implementation fixes needed)
| # | Source | Severity | Category | Issue | Cycles Open |
|---|--------|----------|----------|-------|-------------|
| 3 | sage | WARNING | testing | Test assertions too weak | 1 |
| 4 | trickster | WARNING | reliability | Error path not tested | 1 |

### Resolved in This Cycle
| # | Source | Issue | How Resolved |
|---|--------|-------|--------------|
| 5 | guardian | Missing rate limit | Added rate limiter middleware (commit abc123) |
| 6 | sage | Test names unclear | Renamed to behavior descriptions (commit def456) |

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

Routing rules (canonical table — matches orchestration and artifact-routing skills):

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)	Maker	Needs more tests
Trickster	testing	Maker	Edge case not covered

Disambiguation rule: When in doubt: if the fix requires changing the approach, route to Creator. If it requires changing the code within the existing approach, route to Maker.

---

Step 6: Incremental Runs

Support starting the orchestration from any phase by reusing existing artifacts.

--start-from check

Re-run Check + Act on existing Do artifacts:

1. Read .archeflow/artifacts/<run_id>/ for Maker branch and implementation summary
2. Verify the Maker branch still exists (git branch --list)
3. Spawn reviewers against the existing branch
4. Proceed through Act phase normally

--start-from act

Re-run Act with existing Check findings:

1. Read .archeflow/artifacts/<run_id>/ for Check phase consolidated output
2. Parse findings from the stored reviewer outputs
3. Skip finding collection (already done) — proceed from Step 2 (Fix Routing)

--start-from do

Re-run Do + Check + Act with existing Plan:

1. Read .archeflow/artifacts/<run_id>/ for Creator's proposal
2. Verify proposal exists and is parseable
3. Spawn Maker with the existing proposal
4. Proceed through Check and Act normally

Artifact Verification

Before starting from a mid-point, verify required artifacts exist:

--start-from do    → needs: proposal (Creator output)
--start-from check → needs: proposal + implementation (Maker branch + summary)
--start-from act   → needs: proposal + implementation + review outputs

If artifacts are missing, report which ones and abort. Don't guess or generate placeholders.

Event Continuity

For incremental runs, emit events with parent pointing to the existing artifacts' events:

1. Read the existing <run_id>.jsonl to find the last seq number
2. Continue sequence numbering from there
3. Set parent on the first new event to point to the last event of the prior phase

---

Act Phase Checklist (Quick Reference)

□ Parse all reviewer outputs into consolidated findings table
□ Deduplicate across reviewers
□ Compare against prior cycle findings (if cycle > 1)
□ Route each finding: direct fix / Maker / Creator feedback
□ Apply direct fixes first (fastest)
□ Spawn Maker(s) for code fixes (batch by file area)
□ Emit fix.applied event for each fix
□ Re-check non-trivial fixes with the originating reviewer
□ Count remaining CRITICALs after all fixes
□ Check completion criteria (if defined)
□ Decide: exit / cycle / escalate
□ If cycling: produce act-feedback.md with routed findings
□ If exiting: proceed to merge (see orchestration skill Step 4)
□ Emit cycle.boundary event