# ArcheFlow Core Improvements Plan

## Context

ArcheFlow's archetype system and PDCA engine are feature-complete in TypeScript (`tool.archeflow/`), but the Claude Code plugin layer (`archeflow/` + `claude-archeflow-plugin/`) has gaps that reduce quality and waste tokens. Two plugin directories exist as near-duplicates. The goal: improve orchestration quality while keeping token usage low.

## Scope

**Implement (High Value):**
1. Cross-cycle feedback loop — structured issue tracking between PDCA cycles
2. Consolidate plugin directories — kill `claude-archeflow-plugin/`, keep `archeflow/`
3. Shadow detection heuristics in skill layer — concrete thresholds, not just prose
4. Attention filter enforcement — actually filter context per archetype when spawning
5. Metrics in orchestration skill — lightweight timing + token tracking
6. Autonomous mode wiring — connect skill to orchestration with progress logging

**Future Features (park for later):**
- Web dashboard UI
- A2A inter-agent negotiation protocol
- GitHub Action integration

## Implementation

### 1. Cross-Cycle Feedback Loop

**Problem:** Check phase outputs go to next Plan cycle as raw text dump. No issue tracking, no resolution status, no routing.

**Solution:** Add structured feedback format to `archeflow/skills/orchestration/SKILL.md`

**Changes:**
- `archeflow/skills/orchestration/SKILL.md` — Add "Cycle Feedback Protocol" section:
  - After Check phase, orchestrator extracts findings into structured format:
    ```
    ## Cycle N Feedback
    ### Unresolved Issues
    - [Guardian] CRITICAL: <issue> → Route to: Creator
    - [Skeptic] WARNING: <assumption> → Route to: Creator
    - [Sage] WARNING: <quality concern> → Route to: Maker
    ### Resolved (from prior cycle)
    - [Guardian] <issue> — resolved in cycle N
    ```
  - Route feedback by archetype: Guardian/Skeptic findings → Creator (design issues), Sage/Trickster findings → Maker (implementation issues)
  - Track resolution: if a finding from cycle N-1 is no longer present in cycle N review, mark resolved
- `archeflow/skills/plan-phase/SKILL.md` — Add "Prior Feedback" input section to Creator format:
  - Creator must address each unresolved issue explicitly (fix, defer with reason, or dispute)
- `archeflow/skills/check-phase/SKILL.md` — Standardize finding output format for machine parsing:
  - Each finding: `| Location | Severity | Category | Description | Fix |`
  - Categories: security, reliability, design, quality, testing

**Token impact:** Slightly more tokens in feedback artifact, but saves full cycles by giving targeted guidance instead of "here's everything, figure it out."

### 2. Consolidate Plugin Directories

**Problem:** `archeflow/` and `claude-archeflow-plugin/` are near-identical (1 commit apart), causing maintenance drift.

**Solution:** Delete `claude-archeflow-plugin/`, keep `archeflow/` (more recent, cleaner Node.js hook).

**Changes:**
- Remove `claude-archeflow-plugin/` directory
- Verify `archeflow/` is referenced in any workspace config
- Update any cross-references in docs

### 3. Shadow Detection Heuristics in Skill Layer

**Problem:** TypeScript `ShadowDetector` has concrete thresholds (e.g., >2000 words, >3 tangents), but the skill file only describes shadows in prose. The orchestrator running via Claude Code skills can't use the TypeScript runtime — it needs the heuristics inline.

**Solution:** Add quantitative detection rules to `archeflow/skills/shadow-detection/SKILL.md`

**Changes:**
- `archeflow/skills/shadow-detection/SKILL.md` — For each archetype, add a "Detection Checklist" with concrete metrics the orchestrator can evaluate:
  ```
  ### Explorer → Rabbit Hole
  **Detect:** ANY of:
  - [ ] Output >2000 words without a Recommendation section
  - [ ] >3 tangent topics not in original task
  - [ ] >15 files read
  **Correct:** "Summarize top 3 findings in 300 words. Add Recommendation."
  ```
- Keep the existing prose for understanding, add checklist for action

**Token impact:** Negligible — adds ~200 words to skill file, but prevents wasted cycles from undetected shadows.

### 4. Attention Filter Enforcement

**Problem:** The attention-filters skill describes what each archetype should/shouldn't receive, but the orchestration skill doesn't reference or enforce it when spawning agents.

**Solution:** Add concrete context-assembly instructions to `archeflow/skills/orchestration/SKILL.md`

**Changes:**
- `archeflow/skills/orchestration/SKILL.md` — In each phase's agent-spawning step, add explicit context rules:
  ```
  ## Step 1: Plan Phase
  ### Spawn Explorer
  **Context to include:** Task description, relevant file paths
  **Context to exclude:** Prior proposals, review outputs, implementation details
  
  ### Spawn Creator  
  **Context to include:** Task description, Explorer's Research output
  **Context to exclude:** Raw file contents (Explorer already summarized), review history
  ```
- Reference the attention-filters skill but inline the actionable rules

**Token impact:** This is the biggest savings — prevents passing full codebase dumps to every agent. Each agent gets only what it needs.

### 5. Metrics in Orchestration Skill

**Problem:** No timing or cost tracking at the skill layer. The TypeScript metrics collector exists but isn't available when running via Claude Code skills.

**Solution:** Add lightweight metrics protocol to orchestration skill — track per-phase duration and agent count.

**Changes:**
- `archeflow/skills/orchestration/SKILL.md` — Add "Metrics" section:
  - After each phase, log: `Phase | Duration | Agents | Findings`
  - At orchestration end, summarize: total duration, cycles run, agents spawned, findings by severity
  - Format as compact table in orchestration output
- Keep it lightweight — no token counting (not reliable from skill layer), just timing and counts

**Token impact:** ~50 extra tokens per orchestration for the summary. Provides data for future optimization.

### 6. Autonomous Mode Wiring

**Problem:** Autonomous mode skill exists as standalone doc but isn't integrated into the orchestration skill's flow.

**Solution:** Add autonomous mode hooks to orchestration skill.

**Changes:**
- `archeflow/skills/orchestration/SKILL.md` — Add "Autonomous Mode" section:
  - When running unattended: auto-commit between cycles, log progress to `.archeflow/session-log.md`
  - Reference stop conditions from autonomous-mode skill
  - Add "between-task checkpoint" protocol: after each task completes, update session log before starting next
- `archeflow/skills/autonomous-mode/SKILL.md` — Add cross-reference to orchestration skill for execution details

**Token impact:** Minimal — only adds content to skill files loaded on-demand.

## Future Features (add to backlog)

Add to `archeflow/docs/roadmap.md`:
- **Web Dashboard**: Real-time orchestration visualization via SSE/WebSocket (`tool.archeflow/packages/web/`)
- **A2A Protocol**: Direct agent-to-agent negotiation during Check phase (schemas exist in `tool.archeflow`)
- **GitHub Action**: CI-triggered orchestrations for PR review automation

## Files to Modify

| File | Change |
|------|--------|
| `archeflow/skills/orchestration/SKILL.md` | Feedback loop, attention filters, metrics, autonomous hooks |
| `archeflow/skills/plan-phase/SKILL.md` | Prior feedback input for Creator |
| `archeflow/skills/check-phase/SKILL.md` | Standardized finding format for parsing |
| `archeflow/skills/shadow-detection/SKILL.md` | Quantitative detection checklists |
| `archeflow/skills/autonomous-mode/SKILL.md` | Cross-reference to orchestration |
| `archeflow/docs/roadmap.md` | New file — future features backlog |

| Directory | Action |
|-----------|--------|
| `claude-archeflow-plugin/` | Delete (redundant) |

## Verification

1. Load each modified skill via `Skill` tool — verify no syntax/formatting errors
2. Run a test orchestration (fast workflow) on a small task to verify:
   - Attention filters are referenced in agent spawning
   - Check phase outputs use standardized finding format
   - Feedback is structured and routed correctly
3. Verify shadow detection checklist is actionable (can an orchestrator evaluate each checkbox?)
4. Confirm `claude-archeflow-plugin/` removal doesn't break any references

## Cost-Benefit Summary

| Change | Token Cost | Quality Gain |
|--------|-----------|-------------|
| Cross-cycle feedback | +200/cycle | High — targeted revision instead of blind retry |
| Consolidate dirs | 0 | Medium — eliminates drift, single source of truth |
| Shadow heuristics | +200 skill load | Medium — catches dysfunction before it wastes cycles |
| Attention filters | **-30-50% per agent** | High — massive token savings |
| Metrics | +50/orchestration | Low-Medium — enables future optimization |
| Autonomous wiring | +100 skill load | Medium — enables unattended quality runs |

**Net effect:** Token usage goes DOWN (attention filters save more than everything else adds). Quality goes UP (structured feedback, shadow detection, metrics).