Compare commits
1 Commits
feat/bats-
...
chore/trim
| Author | SHA1 | Date | |
|---|---|---|---|
| f9afca0c58 |
@@ -1,292 +1,46 @@
|
||||
---
|
||||
name: act-phase
|
||||
description: |
|
||||
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.
|
||||
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>
|
||||
<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
|
||||
Turn Check phase findings into fixes, then decide: exit or cycle.
|
||||
|
||||
```
|
||||
Check phase output → Collect → Prioritize → Route → Fix → Verify → Exit or Cycle
|
||||
Check output → Collect → Deduplicate → Route → Fix → Exit or Cycle
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Finding Collection
|
||||
## Step 1: Collect and Consolidate Findings
|
||||
|
||||
Parse all reviewer outputs into one consolidated findings table. Use the standardized format from the `check-phase` skill.
|
||||
Parse all reviewer outputs into one table grouped by severity (CRITICAL / WARNING / INFO):
|
||||
|
||||
```markdown
|
||||
## 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
|
||||
Same file + same category + similar description = one finding. Use the higher severity, credit all sources (e.g. `guardian + skeptic`).
|
||||
|
||||
### Cross-Cycle Tracking
|
||||
### Cross-Cycle Tracking (cycle > 1)
|
||||
|
||||
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`
|
||||
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`
|
||||
|
||||
If a finding persists for 2+ consecutive cycles, flag for user escalation (see Step 5).
|
||||
Finding persisting 2+ cycles = flag for escalation (see Step 4).
|
||||
|
||||
---
|
||||
|
||||
## 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:**
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
||||
```markdown
|
||||
## 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):
|
||||
This is the **canonical routing table** (single source of truth for the whole system):
|
||||
|
||||
| Source | Category | Routes to | Reason |
|
||||
|--------|----------|-----------|--------|
|
||||
@@ -296,76 +50,91 @@ When cycling back, produce `act-feedback.md` as a structured handoff. This repla
|
||||
| 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 |
|
||||
| Trickster | reliability (test gap), testing | Maker | Needs more tests |
|
||||
|
||||
**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.
|
||||
**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 6: Incremental Runs
|
||||
## Step 3: Fix Application
|
||||
|
||||
Support starting the orchestration from any phase by reusing existing artifacts.
|
||||
Apply in severity order: CRITICAL → WARNING → INFO. Within same severity, group by file.
|
||||
|
||||
### `--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
|
||||
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>`
|
||||
|
||||
---
|
||||
|
||||
## Act Phase Checklist (Quick Reference)
|
||||
## Step 4: Exit Decision
|
||||
|
||||
```
|
||||
□ 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
|
||||
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`:
|
||||
|
||||
```markdown
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user