chore: consolidate plugin for sharing
- Add .gitignore (ignore .archeflow/ runtime state) - Move custom archetype examples from .archeflow/ to examples/ - Remove onboarding skill (covered by using-archeflow + README) - Remove internal planning doc - Clean roadmap (remove tool.archeflow references) - Simplify session-start hook config - Polish README for external users
This commit is contained in:
@@ -1,178 +0,0 @@
|
||||
# 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).
|
||||
@@ -10,33 +10,23 @@
|
||||
- [x] Orchestration metrics (timing, agent count, findings)
|
||||
- [x] Autonomous mode integrated into orchestration flow
|
||||
- [x] Plugin consolidation (single `archeflow/` directory)
|
||||
- [x] Workflow intelligence (conditional escalation, fast-path, confidence triggers)
|
||||
- [x] Quality loop (self-review, convergence detection, dedup, completion promises)
|
||||
- [x] Parallel teams, auto-resume, budget scheduling
|
||||
- [x] Extensibility (archetype composition, team presets, hook points, workflow templates)
|
||||
- [x] Mini-reflect for non-ArcheFlow changes
|
||||
|
||||
## Future Features
|
||||
## Future
|
||||
|
||||
### Web Dashboard
|
||||
Real-time orchestration visualization via SSE/WebSocket. Infrastructure exists in `tool.archeflow/packages/web/` (routes, SSE, WebSocket, conflict resolution UI). Needs frontend implementation and connection to event store.
|
||||
|
||||
**Value:** Visual monitoring of long/overnight orchestrations, conflict resolution UI.
|
||||
**Cost:** Medium — frontend work, hosting. Low incremental token cost.
|
||||
|
||||
### A2A Protocol (Agent-to-Agent)
|
||||
Direct inter-agent negotiation during Check phase. Schemas defined in `tool.archeflow/packages/core/`. Currently agents communicate only through artifacts (files) — A2A would allow real-time back-and-forth (e.g., Guardian asking Maker to clarify a code choice before issuing verdict).
|
||||
|
||||
**Value:** Fewer full cycles needed — issues resolved within a phase.
|
||||
**Cost:** High complexity. Risk of increased token usage if negotiations run long. Needs strict turn limits.
|
||||
|
||||
### GitHub Action Integration
|
||||
CI-triggered orchestrations for automated PR review. Package exists at `tool.archeflow/packages/action/` with minimal implementation.
|
||||
|
||||
**Value:** Automated quality gates on every PR without manual orchestration.
|
||||
**Cost:** Low implementation effort, but ongoing CI minutes cost. Best for high-value repos.
|
||||
| Feature | Value | Effort | Notes |
|
||||
|---------|-------|--------|-------|
|
||||
| A2A Protocol | Fewer cycles via in-phase negotiation | High | Needs strict turn limits |
|
||||
| GitHub Action | Automated PR review via CI | Low | CI minutes cost |
|
||||
| Web Dashboard | Real-time orchestration visualization | Medium | SSE/WebSocket frontend |
|
||||
|
||||
## Version History
|
||||
|
||||
Maintainers should update this table when significant features ship or major improvements are completed. Reverse chronological order (latest first).
|
||||
|
||||
| Date | Changes |
|
||||
|------|---------|
|
||||
| 2026-04-03 | 25-feature release — workflow intelligence (conditional escalation, fast-path, confidence triggers), quality loop (self-review, convergence detection, dedup, completion promises, post-merge verification), parallel teams, auto-resume, budget scheduling, DX (progress indicators, dry-run, status/history commands, onboarding), extensibility (archetype composition, team presets, hook points, workflow templates, reviewer profiles, explorer cache, learning from history), Ralph Loop integration (mini-reflect, alternatives, structured confidence) |
|
||||
| 2026-04-03 | Core improvements — cross-cycle feedback loop, attention filter enforcement, shadow detection heuristics, orchestration metrics, autonomous mode wiring, plugin consolidation, emoji avatars for archetypes |
|
||||
| 2026-04-03 | Initial roadmap created with completed features and future backlog |
|
||||
| 2026-04-03 | v0.2 — Plugin consolidation, shareable structure, examples |
|
||||
| 2026-04-03 | v0.1 — Full feature set: 7 archetypes, 10 skills, PDCA workflows, shadow detection, autonomous mode, extensibility |
|
||||
|
||||
Reference in New Issue
Block a user