claude-archeflow-plugin/skills/artifact-routing/SKILL.md

---
name: artifact-routing
description: |
  Inter-phase artifact protocol for ArcheFlow runs. Defines how artifacts are named, stored,
  routed between agents, and archived across PDCA cycles. Ensures each agent receives exactly
  the context it needs — no more, no less.
  <example>Automatically loaded by archeflow:run</example>
  <example>User: "What does the Maker receive as context?"</example>
---

# Artifact Routing — Inter-Phase Context Protocol

Every ArcheFlow run produces artifacts — research notes, proposals, diffs, reviews, feedback. This skill defines how those artifacts are named, where they live, what each agent receives, and how they are preserved across cycles.

## Artifact Directory Structure

```
.archeflow/artifacts/<run_id>/
├── plan-explorer.md          # Explorer research output
├── plan-creator.md           # Creator proposal/outline
├── do-maker.md               # Maker implementation summary
├── do-maker-files.txt        # List of files created/modified (one path per line)
├── check-guardian.md          # Guardian review verdict + findings
├── check-sage.md             # Sage review (if present)
├── check-skeptic.md          # Skeptic review (if present)
├── check-trickster.md        # Trickster review (if present)
├── act-feedback.md           # Structured feedback for next cycle (Cycle Feedback Protocol)
├── act-fixes.jsonl           # Applied fixes log (one JSON line per fix)
├── cycle-1/                  # Archived artifacts from cycle 1
│   ├── plan-explorer.md
│   ├── plan-creator.md
│   ├── do-maker.md
│   ├── do-maker-files.txt
│   ├── check-guardian.md
│   ├── check-sage.md
│   └── act-feedback.md
└── cycle-2/                  # Archived artifacts from cycle 2 (if cycle 3 starts)
    └── ...
```

## Naming Convention

Artifacts follow the pattern: `<phase>-<agent>.<ext>`

| Phase | Agent | Filename | Format |
|-------|-------|----------|--------|
| plan | explorer | `plan-explorer.md` | Markdown research report |
| plan | creator | `plan-creator.md` | Markdown proposal with confidence scores |
| plan | mini-explorer | `plan-mini-explorer.md` | Focused risk research (only if confidence gate triggers) |
| do | maker | `do-maker.md` | Markdown implementation summary |
| do | maker | `do-maker-files.txt` | Plain text, one file path per line |
| check | guardian | `check-guardian.md` | Markdown verdict + findings table |
| check | sage | `check-sage.md` | Markdown verdict + findings table |
| check | skeptic | `check-skeptic.md` | Markdown verdict + findings table |
| check | trickster | `check-trickster.md` | Markdown verdict + findings table |
| act | (orchestrator) | `act-feedback.md` | Structured feedback (see Cycle Feedback Protocol) |
| act | (orchestrator) | `act-fixes.jsonl` | JSONL fix log |

**Rule:** Never invent new artifact names during a run. If a reviewer is skipped (A2 fast-path, reviewer profile), its artifact simply does not exist. Downstream phases check for file existence before reading.

---

## Context Injection Rules

Each agent receives a filtered subset of artifacts. This is the **attention filter** — it controls what context is injected into the agent's prompt.

### Plan Phase

| Agent | Receives | Does NOT receive |
|-------|----------|-----------------|
| **Explorer** | Task description, relevant file paths, codebase access | Prior proposals, review outputs, implementation details |
| **Creator** (cycle 1) | Task description, `plan-explorer.md` (if exists) | Raw file contents (Explorer summarized them), git diffs |
| **Creator** (cycle 2+) | Task description, `plan-explorer.md`, `act-feedback.md` (Creator-routed findings only) | Raw reviewer outputs, Maker-routed findings |

**Creator context injection template (cycle 2+):**
```markdown
## Task
<task description>

## Research (from Explorer)
<contents of plan-explorer.md>

## Feedback from Prior Cycle
<Creator-routed section of act-feedback.md only>

Note: Address each unresolved issue listed above. Explain how your revised proposal resolves it.
```

### Do Phase

| Agent | Receives | Does NOT receive |
|-------|----------|-----------------|
| **Maker** (cycle 1) | `plan-creator.md` (the proposal), `plan-mini-explorer.md` (if exists) | `plan-explorer.md`, reviewer outputs, raw task description |
| **Maker** (cycle 2+) | `plan-creator.md`, `plan-mini-explorer.md` (if exists), Maker-routed findings from `act-feedback.md` | Explorer research, Guardian/Skeptic findings (those went to Creator) |

**Maker context injection template (cycle 2+):**
```markdown
## Proposal
<contents of plan-creator.md>

## Implementation Feedback from Prior Cycle
<Maker-routed section of act-feedback.md only>

Note: The proposal has been revised to address design-level issues. Focus on the implementation
feedback items above (code quality, test gaps, consistency).
```

**Why Maker doesn't get Explorer output:** The Creator already distilled Explorer's research into a concrete proposal. Giving Maker raw research causes scope creep and "Rogue" shadow activation.

### Check Phase

| Agent | Receives | Does NOT receive |
|-------|----------|-----------------|
| **Guardian** | Maker's git diff, risk section from `plan-creator.md` | Full proposal, Explorer research, other reviewer outputs |
| **Skeptic** | `plan-creator.md` (assumptions focus) | Git diff details, Explorer research, other reviewer outputs |
| **Sage** | `plan-creator.md`, Maker's git diff, `do-maker.md` | Explorer research, other reviewer outputs |
| **Trickster** | Maker's git diff only | Everything else |

**Guardian context injection template:**
```markdown
## Changes to Review
<git diff from Maker's branch>

## Risk Assessment (from proposal)
<risks section extracted from plan-creator.md>

Review these changes for security, reliability, breaking changes, and dependency risks.
```

**Skeptic context injection template:**
```markdown
## Proposal to Challenge
<contents of plan-creator.md>

Focus on assumptions, alternatives not considered, edge cases, and scalability.
```

**Sage context injection template:**
```markdown
## Proposal
<contents of plan-creator.md>

## Implementation Summary
<contents of do-maker.md>

## Changes
<git diff from Maker's branch>

Evaluate code quality, test coverage, documentation, and codebase consistency.
```

**Trickster context injection template:**
```markdown
## Changes to Attack
<git diff from Maker's branch>

Try to break this. Malformed input, boundaries, concurrency, error paths, dependency failures.
```

### Act Phase

No agents are spawned in Act. The orchestrator reads all `check-*.md` artifacts directly.

---

## Feedback Routing

> **This is the canonical routing table.** Other skills (orchestration, act-phase) must match this table exactly. When updating routing rules, update this table first, then sync the others.

When building `act-feedback.md` after the Check phase, route each finding to the right agent for the next cycle:

| Finding Source | Finding Category | Routes To | Rationale |
|---------------|-----------------|-----------|-----------|
| 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.

### Feedback File Format

`act-feedback.md` is split into two sections so each agent can be given only its portion:

```markdown
# Cycle <N> Feedback

## Creator-Routed Issues
| # | Source | Severity | Category | Issue | Suggested Fix |
|---|--------|----------|----------|-------|---------------|
| 1 | Guardian | CRITICAL | security | SQL injection in user input | Add parameterized queries |
| 2 | Skeptic | WARNING | design | Assumes single-tenant only | Add tenant isolation |

## Maker-Routed Issues
| # | Source | Severity | Category | Issue | Suggested Fix |
|---|--------|----------|----------|-------|---------------|
| 3 | Sage | WARNING | quality | Test names don't describe behavior | Rename to describe expected outcome |
| 4 | Sage | INFO | consistency | Import order doesn't match codebase style | Re-order imports |

## Resolved (from prior cycles)
| # | Source | Issue | Resolution | Resolved In |
|---|--------|-------|------------|-------------|
| 1 | Guardian | Missing rate limit | Added rate limiter middleware | Cycle 1 |

## Convergence Warnings
<any finding that appeared unresolved in 2+ consecutive cycles — requires user input>
```

When injecting feedback into Creator's prompt, include **only** the "Creator-Routed Issues" section.
When injecting feedback into Maker's prompt, include **only** the "Maker-Routed Issues" section.

---

## Cycle Archiving

When a PDCA cycle completes and a new cycle begins, archive the current artifacts so they are preserved and the working directory is clean for the next iteration.

### Archive Procedure

At the end of each cycle (before starting the next):

```bash
RUN_DIR=".archeflow/artifacts/${RUN_ID}"
ARCHIVE_DIR="${RUN_DIR}/cycle-${CYCLE}"

mkdir -p "$ARCHIVE_DIR"

# Copy all phase artifacts to archive
cp "${RUN_DIR}"/plan-*.md   "$ARCHIVE_DIR/" 2>/dev/null || true
cp "${RUN_DIR}"/do-*.md     "$ARCHIVE_DIR/" 2>/dev/null || true
cp "${RUN_DIR}"/do-*.txt    "$ARCHIVE_DIR/" 2>/dev/null || true
cp "${RUN_DIR}"/check-*.md  "$ARCHIVE_DIR/" 2>/dev/null || true
cp "${RUN_DIR}"/act-feedback.md "$ARCHIVE_DIR/" 2>/dev/null || true
```

**Do NOT delete** the working-level artifacts after archiving. The next cycle's agents need `act-feedback.md` and `plan-explorer.md` (Explorer cache may reuse prior research). Old artifacts in the working directory get overwritten when the new cycle's agents produce their outputs.

### Archive Access

Archived artifacts are read-only references. Use them for:
- **Resolution tracking:** Compare `cycle-1/check-guardian.md` findings against `cycle-2/check-guardian.md` to detect resolved/persisting issues
- **Convergence detection:** Same finding in `cycle-N/act-feedback.md` and `cycle-N+1/act-feedback.md` → escalate to user
- **Post-hoc analysis:** Understanding how a solution evolved across cycles

---

## Artifact Existence Checks

Before injecting an artifact into an agent's context, always check if the file exists. Missing artifacts are expected in certain workflows:

| Artifact | Missing when |
|----------|-------------|
| `plan-explorer.md` | Fast workflow (no Explorer) |
| `plan-mini-explorer.md` | Confidence gate did not trigger for risk coverage |
| `check-skeptic.md` | Fast workflow, or A2 fast-path taken |
| `check-sage.md` | Fast workflow, or A2 fast-path taken |
| `check-trickster.md` | Non-thorough workflow, or A2 fast-path taken |
| `act-feedback.md` | Cycle 1 (no prior feedback exists) |
| `act-fixes.jsonl` | Cycle 1, or no fixes applied |

**Rule:** Never fail because an optional artifact is missing. Check existence, skip injection if absent, and note what was skipped in the event data.

---

## Git Diff as Artifact

The Maker's git diff is not saved as a file — it is generated on-the-fly from the Maker's worktree branch:

```bash
git diff main...<maker-branch>
```

This ensures reviewers always see the actual current diff, not a stale snapshot. The diff is injected directly into reviewer prompts, not saved to disk.

Exception: `do-maker-files.txt` IS saved to disk (just the file list, not the full diff) for quick reference by the orchestrator and for archiving purposes.

---

## Design Principles

1. **Minimal context per agent.** Each agent gets only what it needs. Over-injection causes distraction, shadow activation, and wasted tokens.
2. **Artifacts are the handoff mechanism.** Agents never communicate directly. All inter-agent data flows through saved artifacts.
3. **Files over memory.** Everything is on disk. If a session crashes, artifacts survive. A `--start-from` resume reads artifacts, not session state.
4. **Overwrite, don't accumulate.** Working-level artifacts get overwritten each cycle. Archives preserve history. This keeps the working directory simple.
5. **Check before inject.** Always verify artifact existence. Gracefully handle missing optional artifacts.