Epic-Harness Dashboard

epic-harness
⌕

## Dashboard

4-Ring architecture status · eval scores · system health

0
Autopilot
6 hooks active
1
Commands
10 user commands
2
Auto Skills
15 context-triggered
3
Evolution
observe → evolve loop
Eval Score
0.78
composite (success 50% + quality 30% + cost 20%)
Evolved Skills
3
max 10 · stagnation limit 3
Memory Nodes
--
SQLite + FTS5 via harness-mem MCP
Sessions
--
this project
Orbit Runs
--
spec → go → check → ship
Integrations
6
Claude Code · Codex · Cursor · Gemini · Cline · Aider

### Eval Score Axes (3-Axis)

0.85
Success
0.60
Quality
0.45
Cost
composite = 0.5 × success + 0.3 × quality + 0.2 × cost = 0.78

### Pattern Detection (4 Types)

Pattern | Threshold | Status
--- | --- | ---
repeated_same_error | min 3 consecutive | clear
fix_then_break | lookahead 3, min 2 cycles | clear
long_debug_loop | min 5 same file | clear
thrashing | min 3 edits + 3 errors | clear

### Recent Activity

- Session restored via `epic-harness resume`
  session start
- Evolved skills loaded (3 active)
  $HARNESS_DIR/evolved/
- harness-mem context loaded for project
  session start
- Polish hook ran: format + typecheck
  post-edit
- Observe hook recorded tool score
  post-tool-use

## /orbit Autonomous Pipeline

spec → go → check → ship → evolve — single-command spec-to-PR execution

### Entry Mode Selection

Interactive
User runs `/discover` → `/spec` manually, then triggers orbit. Best for vague requirements.
unclear requirement
Council
4-voice parallel auto-spec (Architect + Critic + Implementor + QA). Best for complex, multi-stakeholder requirements.
complex requirement
Direct
Auto-spec and immediately start building. Best for clear, well-defined requirements.
clear requirement

### Pipeline Flow

☰
spec
REQ + AC
▶
go
plan+TDD
✓
check
review+audit
🚀
ship
PR+CI
↻
evolve
auto-analyze
check fail → auto-retry (max 3) 3 fails → pause for human state: `$HARNESS_DIR/orbit/PIPELINE-*.json`

### Pipeline State Schema

Field | Value
--- | ---
id | {timestamp}
mode | interactive | council | direct
phase | mode_select → spec → go → check → ship
status | running | completed | failed | timeout | aborted
check_fail_count | 0..3
deadline | now + 30min
worktree_name | isolated build env

### Safety Mechanisms

- Concurrent orbit guard
  Only 1 running pipeline at a time
- Deadline enforcement
  30-min hard timeout per orbit
- Crash recovery
  45-min staleness threshold, phase_history wins
- Worktree safety
  Isolated build, state survives worktree loss

## Commands Ring 1

10 user-invoked slash commands (7 manual + 1 autonomous orbit + 2 utility)

/discover
Problem discovery. Probes with 5 Whys / JTBD / Fishbone / Socratic techniques (max 3 rounds), then frames a structured problem statement.
analysispre-spec
/spec
Converts requirements into numbered Requirements + Acceptance Criteria document (SPEC-{ts}.md). Suggests /team when 3+ requirements.
planningREQ+AC
/go
Reads approved SPEC, maps Requirements to tasks, executes via TDD subagents (parallel where safe, worktree-isolated when files overlap).
buildTDD
/check
Parallel agents (reviewer + auditor + test runner) + scope-based checks (API contract, accessibility, migration safety). PASS/WARN/FAIL per dimension.
reviewaudit
/ship
Isolated integration test in fresh worktree, creates PR with spec + check report, watches CI, auto-fixes failures. Suggests /evolve on completion.
deployPR+CI
/evolve
Analyzes session observation logs to detect failure patterns and weak tools, auto-generates targeted skills. Sub-commands: status, history, cross-project, rollback, reset.
evolutionRing 3
/team
Agent team manager. Browse org libraries, hire existing teams, or design new team (3-6 agents). Patterns: Pipeline, Fan-out, Expert-Pool, Producer-Reviewer, Supervisor.
agentsteam-design
/orbit
Autonomous pipeline: spec → go → check → ship → evolve. Auto-selects mode (Interactive/Council/Direct). Auto-retries check up to 3 times. Runs /evolve on success.
autonomousend-to-end30min deadline
/status
Real-time orchestration dashboard. Active agent count, per-agent progress stage, dependency graph, elapsed time, recent event summary.
monitoring
/intervene
Intervene in active agent orchestration. Pause, cancel, or redirect running agents mid-execution.
control

## Auto Skills Ring 2

15 context-triggered skills + _dispatch core router · static skills always take priority over evolved

### _dispatch — Core Router

Always active. Auto-invokes matching skill before every response. Runs confusion protocol on high-risk ambiguity. Calls `mem_recall` with current task context before invoking any skill. Past decisions (importance=0.9) surface first.
dispatch log: `$HARNESS_DIR/dispatch/dispatch_YYYYMMDD.jsonl`
tdd
trigger: new feature or bug fix
Enforces Red → Green → Refactor. No prod code without failing test first.
debug
trigger: test failure, runtime error, unexpected behavior
Systematic root-cause isolation. Never retry without diagnosis.
verify
trigger: before marking done or /ship
Build + test + lint must all pass. No exceptions.
secure
trigger: auth, DB, API, infra, or secrets code touched
Security checklist for SQL, endpoints, env vars, infra config.
perf
trigger: loops, DB queries, rendering, batch ops
Catches N+1, missing indexes, unnecessary re-renders.
simplify
trigger: file >200 lines, high complexity, duplication
Deep nesting, copy-paste, god functions. Extract and reduce.
commit
trigger: commit/save
CC 1.0.0 commit generator. Stages relevant files, infers type(scope): desc.
context
trigger: context >70% or large new task
Snapshots state, compacts, resumes via hook.
discover
trigger: vague/unfocused request
Reframes goal before acting. Prevents solution-without-problem.
council
trigger: architecture/design decisions with trade-offs
Multi-voice analysis for decisions with no clear answer.
document
trigger: public API/module added or changed
Auto-generates documentation for new exports and signature changes.
reflect
trigger: /reflect or AI usage review
Scores 5 dims: amplification, improvement, metacognition, prompts, efficiency.
orchestrate
trigger: active multi-agent run
Handles inbox reading, dep resolution, message formatting, handoffs.
agent-introspection
trigger: 3+ consecutive failures, circular retries
Breaks loops. Detects overwhelming context and circular patterns.

## Internal Agents

4 built-in agents used by /go and /check phases · extendable via /team

Builder
epic:builder
Implements a single task using TDD. Writes test first, then code, then verifies. Used by /go to execute individual requirement tasks.
TDD/go
Reviewer
epic:reviewer
Reviews code for quality, correctness, style, and test coverage. Launched by /check in parallel with auditor and test runner.
review/check
Auditor
epic:auditor
Audits code for security vulnerabilities and performance issues. Parallel execution with reviewer during /check phase.
security/check
Planner
epic:planner
Breaks down a goal into ordered, parallelizable tasks with dependencies. Used by /go to create the execution plan from approved spec.
planning/go

### /team Orchestration Patterns

Pattern | Agents | Best For
--- | --- | ---
Pipeline | 3-6 | Sequential handoffs, build → test → review
Fan-out | 3-6 | Parallel independent tasks, then merge
Expert-Pool | 3-6 | Route to specialist per task type
Producer-Reviewer | 2-3 | One builds, one reviews, iterate
Supervisor | 3-6 | Central coordinator dispatches to workers

## Eval & Evolve Ring 3

Observe → Analyze → Evolve → Gate → Reload self-improvement loop

### Evolution Loop

👁
Observe
post-tool-use
📈
Analyze
session end
🛠
Evolve
gen skills
✓
Gate
validate
↻
Reload
next session

### Skill Seeding Thresholds

Type | Condition | Min Observations
--- | --- | ---
Weak tool | success rate < 0.6 | 5
Weak file type | success rate < 0.5 | 3
High-frequency error | 5+ occurrences | 5

### Stagnation & Gating

- Stagnation limit: 3 sessions
  No improvement → auto-rollback to best checkpoint
- Improvement threshold: 5%
  Trend: improving / stable / declining
- Max evolved skills: 10
  Static skills always take priority
- Validation: frontmatter + body ≥20 chars
  Invalid skills silently removed

### Skill Attribution (A/B Tracking)

metrics.json tracks per-evolved-skill: avg_score_with vs avg_score_without · positive delta = effective
data: `$HARNESS_DIR/metrics.json` history: `$HARNESS_DIR/evolution.jsonl` backup: `$HARNESS_DIR/evolved_backup/`

## Hooks Ring 0

6 Claude Code hooks providing autopilot automation · Rust single binary

### Hook Registry

Session start
`epic-harness resume`
Restore session + load evolved skills
active
Pre tool use
`epic-harness guard`
Block dangerous shell patterns
active
Post tool use
`epic-harness observe`
Record tool scores (3-axis eval, async)
active
Post edit
`epic-harness polish`
Auto-format + typecheck (feeds into observe)
active
Pre compact
`epic-harness snapshot`
Save session state before compaction
active
Session end
`epic-harness reflect`
Evolve skills + save metrics + merge session obs
active

### Guard Rule Extension

# .harness/guard-rules.yaml
blocked:
- pattern: kubectl\s+delete
msg: kubectl delete blocked
warned:
- pattern: docker\s+system\s+prune
msg: Docker prune — check first

## harness-mem WIP

Unified knowledge graph · SQLite + FTS5 · MCP server registered as `harness-mem`

### MCP Tools (6)

Tool | Purpose
--- | ---
mem_recall | Smart contextual recall · hint + project + graph neighbors
mem_add | Add node with auto-importance by type
mem_search | FTS5 keyword search, ranked by importance
mem_query | Filter by tag/type/project
mem_context | Project-scoped smart recall (session start)
mem_related | BFS graph traversal from node ID

### Scoring Formula

recency(25%) + importance(35%) + access_freq(15%) + FTS_match(25%)
recency: exponential decay, 30-day half-life
importance: type-based (0.0-1.0)
access_freq: saturates at 20 accesses
FTS_match: 1.0 bonus via FTS5

### Node Types & Default Importance

decision (0.9) resolution (0.8) concept (0.7) project (0.7) pattern (0.5) error (0.4) session (0.2)
lifecycle: access tracking → 30d decay (-10%/cycle) → 180d stale → `pinned` tag prevents decay

### Storage

Database | ~/.harness/memory.db (SQLite + FTS5)
MCP Server | harness-mem (registered in Claude Code)
Integration | _dispatch calls mem_recall before invoking any skill
Status | WIP — under active development

## Integrations

6 AI coding tool integrations · configs in `integrations/`

⚡
Claude Code
Primary integration. Hooks + skills + commands + MCP server.
hooks skills (15) commands (10) agents (4)
💻
Codex (OpenAI)
OpenAI Codex CLI integration.
hooks.json config.toml prompts (8) skills (7)
➤
Cursor
Cursor IDE agent integration.
hooks.json commands (8) agents (4)
✨
Gemini CLI
Google Gemini CLI integration.
settings.json GEMINI.md commands (8) skills (7)
⚖
Cline
Cline autonomous coding agent.
hooks (5 scripts) rules/epic-harness.md
🌐
Aider
Aider AI pair programming integration.
.aider.conf.yml CONVENTIONS.md

### Shared Resources

Resource | Count | Location
--- | --- | ---
Commands | 10 | registry/commands/*.md
Auto Skills | 15 + _dispatch | registry/skills/*/SKILL.md
Agents | 4 | registry/agents/*.md
Presets | 4 stacks | registry/presets/{go,node,python,rust}
Hooks Binary | 1 | hooks/bin/epic-harness (Rust)

## Settings

Review and edit epic-harness configurations

### Eval Score Weights

Success Weight
tool_success axis weight (0/1)
Quality Weight
output_quality axis weight (0.0-1.0)
Cost Weight
execution_cost axis weight (0.0-1.0)

### Evolution Tuning

Stagnation Limit
Sessions without improvement before rollback
Improvement Threshold
Minimum score improvement to count as progress
%
Max Evolved Skills
Upper limit for auto-generated skills
Cross-Project Learning
Share patterns across projects (opt-in)

### Pattern Detection Thresholds

Repeated Error Min
Consecutive same error + same hash threshold
Debug Loop Min
Same file in consecutive operations threshold
Thrashing Min Edits
Edit↔Error alternating minimum edit count

### System Info

Version | 0.4.0
Runtime | Rust (edition 2024)
Binary | hooks/bin/epic-harness
Memory DB | SQLite + FTS5
Dashboard | Tauri (src-tauri/)
License | Apache-2.0
CI | check + clippy + fmt + test
Release | cargo-dist

### Project Data Paths

HARNESS_DIR | ~/.harness/projects/{slug}/
Observations | obs/ (JSONL, 3-axis scores)
Evolved Skills | evolved/ (auto-generated)
Evolution Backup | evolved_backup/ (best state)
Sessions | sessions/*.json
Metrics | metrics.json
Orbit State | orbit/PIPELINE-*.json
Dispatch Log | dispatch/dispatch_*.jsonl
Memory | memory/ (project patterns)

### Cold-Start Presets

Rust Node.js Python Go
Auto-apply on first session with no evolved skills for detected stacks.