Christian Nennemann
d08dc657d1
- Cross-cycle feedback protocol with structured finding format, routing, and resolution tracking - Attention filter enforcement: explicit context include/exclude per archetype - Shadow detection: quantitative checklists with concrete thresholds - Orchestration metrics: per-phase timing, agent count, findings summary - Autonomous mode wiring: checkpoint protocol, session log, stop conditions - Auto-activation: SessionStart hook fires ArcheFlow for implementation tasks without user config - Emoji avatars for all 7 archetypes - Standardized finding format across all reviewers for cross-cycle tracking - Persisted implementation plan in docs/
179 lines
8.9 KiB
Markdown
179 lines
8.9 KiB
Markdown
# 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).
|