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

name, description

name	description
artifact-routing	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
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+):

## 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-explorer.md, reviewer outputs, raw task description
Maker (cycle 2+)	plan-creator.md, Maker-routed findings from act-feedback.md	Explorer research, Guardian/Skeptic findings (those went to Creator)

Maker context injection template (cycle 2+):

## 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:

## 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:

## Proposal to Challenge
<contents of plan-creator.md>

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

Sage context injection template:

## 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:

## 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

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

Ambiguous cases: If a Trickster finding could be either a design flaw or a test gap, check: does the fix require changing the proposal's architecture/approach, or just adding a test/validation? Architecture change → Creator. Additional test → Maker.

Feedback File Format

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

# 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):

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)
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:

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.