claude-archeflow-plugin/docs/plan-core-improvements-2026-04-03.md

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