c/claude-archeflow-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add automated PDCA loop, domain adapters, cost tracking, DAG renderer

Browse Source 
- skills/run: automated PDCA execution loop with --start-from, --dry-run
- skills/artifact-routing: inter-phase artifact protocol with context injection
- skills/act-phase: structured review→fix pipeline with cycle feedback
- skills/domains: domain adapter system (writing, code, research)
- skills/cost-tracking: per-agent cost estimation, budget enforcement
- lib/archeflow-dag.sh: ASCII DAG renderer from JSONL events
- lib/archeflow-report.sh: updated with DAG section, cycle diff, --dag/--summary flags
This commit is contained in:
Christian Nennemann
2026-04-03 11:20:14 +02:00
parent 1753e69a9f
commit b6df3d19fd
7 changed files with 2259 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

285
skills/artifact-routing/SKILL.md Normal file
View File

@@ -0,0 +1,285 @@
---
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 |
| 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-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+):**
```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
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:
```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) |
| `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.