# ADR-001: Framework Evolution Roadmap — From Good Tool to Viral Framework

**Date:** 2026-03-22
**Status:** Accepted
**Deciders:** cwarner (framework author)

## Context

A comprehensive gap analysis of the harness engineering framework identified 112 gaps across 12 categories, including 34 game-changing capabilities that would push into uncharted territory for agentic engineering. The framework has strong foundations — 7 packages (~33,500 LOC), 49 skills, 12 personas, 37 MCP tools, a knowledge graph (12,915 nodes, 25,765 edges), and mechanical constraint enforcement — but lacks the synthesis layer that turns detection into understanding, and the community infrastructure that enables viral adoption.

The overarching goal is to maximize adoption and usability so the framework takes off virally. This ADR establishes the prioritized roadmap for addressing gaps, organized into three tiers executed sequentially.

## Decision

Execute a three-tier roadmap: **Tier 1 (quick wins)** ships in days, builds momentum and proves capability. **Tier 2 (monthly)** builds the features that create the "wow" factor and viral flywheel. **Tier 3 (quarterly)** delivers the deep intelligence that makes the framework irreplaceable.

### Tier 1: Build Tomorrow (1-2 weeks)

These items require minimal new code because the infrastructure already exists. They demonstrate the framework's graph intelligence and unlock immediate value.

| Priority | Item                                             | Gap ID | What to Build                                                                                                                                               | Build Time |
| -------- | ------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| 1.1      | **Graph anomaly detection**                      | C15    | Z-score outlier detection over existing complexity/coupling/fanIn/fanOut metrics + articulation point identification. New MCP tool: `detect_anomalies`.     | 1-2 days   |
| 1.2      | **Automatic task independence detection**        | F5     | Pairwise file-overlap + import-chain + call-graph reachability analysis using existing ContextQL + `get_impact()`. New MCP tool: `check_task_independence`. | 1-2 days   |
| 1.3      | **Conflict prediction before parallel dispatch** | F9     | Extension of 1.2 — returns conflict matrix with reasoning instead of pass/fail. Integrate into `harness-parallel-agents` skill.                             | 1 day      |
| 1.4      | **Natural language graph queries**               | K7     | English → ContextQL parameter translation via Claude API. New MCP tool: `ask_graph`. Enables conversational codebase exploration.                           | 2-3 days   |
| 1.5      | **Test-driven architecture enforcement**         | L3     | Assertion library wrapping existing entropy/coupling/complexity metrics. Compare against baselines. Fail CI on architectural regression.                    | 3-5 days   |
| 1.6      | **Pre-commit impact preview**                    | J6     | Formatted summary from existing `get_impact()` tool. Shows "this change affects N files, M tests, K docs" before commit.                                    | 1-2 days   |
| 1.7      | **Constraint deprecation detection**             | L2     | Query graph for rules with 0 violations over configurable window. Surface as "stale constraint" suggestions.                                                | 1 day      |

**Success criteria:** All 7 items ship as MCP tools and/or skill enhancements. Demonstrable in a 5-minute screencast.

---

### Tier 2: Build This Month (3-6 weeks per item, parallelizable)

These create the "wow" factor and viral flywheel. Prioritized by (viral impact × feasibility).

| Priority | Item                                                | Gap ID | What to Build                                                                                                                                                                                                                                                                                                             | Build Time     |
| -------- | --------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| 2.1      | **Skill marketplace + `harness install`**           | H1     | `@harness-skills/*` npm namespace. Skill packaging (skill.yaml + SKILL.md as npm packages). `harness install <skill>` command with dependency resolution. Search/browse via `harness skills search`. Leverage existing npm infrastructure, semver enforcement, and changesets.                                            | 4-6 weeks      |
| 2.2      | **Constraint sharing (`harness share`)**            | H3     | Export constraint subsets from harness.config.json as shareable bundles. `harness share my-api-rules` publishes to npm. `harness install-constraints @harness-constraints/strict-api`. Merge logic for combining constraint sets.                                                                                         | 2-3 weeks      |
| 2.3      | **Architecture decay timeline**                     | J1     | Scheduled snapshot capture (CI job) of constraint violations, complexity hotspots, dead code, coupling density, test coverage. Time-series nodes in graph. Trend visualization. "Your architecture stability: 95% → 78% over 6 months."                                                                                   | 3-4 weeks      |
| 2.4      | **Predictive architecture failure**                 | J2     | Extension of 2.3. Extrapolate decay trends + planned roadmap features → project which constraints will break and when. "If you ship these 3 features without restructuring services/, you'll have circular deps by Sprint 14."                                                                                            | +1 week on 2.3 |
| 2.5      | **Spec-to-implementation traceability**             | E2     | Enhance phase gates with content validation. Build requirement→test→assertion mapping. Add graph edge types: `requires`, `verified_by`, `tested_by`. Coverage matrix showing which spec requirements have code + tests. 80% of infrastructure exists (EARS patterns, phase gates, cross-checks, planning task→file maps). | 3-4 weeks      |
| 2.6      | **Skill recommendation engine**                     | D11    | Map codebase characteristics → optimal skill sequences. "Based on your coupling (high), coverage (62%), and recent violations (3 circular imports), run: dependency-health → enforce-architecture → tdd." Decision tree scoring.                                                                                          | 3-4 weeks      |
| 2.7      | **Intelligent skill dispatch**                      | L4     | Change-triggered skill selection. Auto-compose workflows from persona stack. Hotspot-aware skill pre-loading. Builds on 2.6.                                                                                                                                                                                              | 3-4 weeks      |
| 2.8      | **Constraint emergence from patterns**              | L1     | Cluster violations by pattern. When N similar violations appear in M weeks, suggest a new rule. "These 7 violations follow the same pattern. Create rule: 'services/ must not import from ui/'?"                                                                                                                          | 3-4 weeks      |
| 2.9      | **Cascading failure simulation**                    | C9     | Probabilistic BFS traversal with failure probability annotations (synthesized from change frequency). New tool: `compute_blast_radius(nodeId)`. Shows transitive impact with confidence scores.                                                                                                                           | 2-3 weeks      |
| 2.10     | **Community detection (module boundary discovery)** | C6     | Label propagation over import/call graph. Auto-suggest module boundaries. "Your codebase has 4 natural clusters. Here's where the boundaries should be."                                                                                                                                                                  | 2-3 weeks      |

**Success criteria:** Marketplace has 10+ installable skills. Architecture timeline shows 3+ months of history. Skill dispatch auto-recommends on 80%+ of tasks. At least one constraint set published by a non-author user.

---

### Tier 3: Build This Quarter (6-12 weeks per item)

Deep intelligence that makes the framework irreplaceable. These are the capabilities no competitor has.

| Priority | Item                                               | Gap ID | What to Build                                                                                                                                                                                                                                                                            | Build Time |
| -------- | -------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| 3.1      | **Self-improving agent skills**                    | D4, D5 | Outcome attribution: map review findings → actual bugs via issue tracker integration. Skill effectiveness baselines (like perf baselines). Dynamic prompt injection into preamble builder based on historical outcomes. Skills that measurably improve over time.                        | 6-8 weeks  |
| 3.2      | **Cross-project knowledge federation**             | D2     | Project registry (`~/.harness/projects/`). Node ID scoping (projectId in metadata). Graph merger via ProjectConnector (follows existing connector pattern). Federation-aware FusionLayer for cross-project semantic search. "Last time you used this pattern in Project A, it caused X." | 8-10 weeks |
| 3.3      | **Spec-to-code semantic verification**             | E1     | Extension of 2.5. EARS grammar parser for machine-verifiable requirements. Test assertion semantic analysis. Requirement→behavior matching via Claude API. "This spec says 'return 404 when not found.' Test file X asserts status 200 only. Gap detected."                              | 6-8 weeks  |
| 3.4      | **Trust scoring for agent output**                 | E6     | Explicit confidence model: validation method (mechanical > graph > heuristic) × evidence quality × cross-agent agreement × historical accuracy. Every finding gets a visible confidence percentage.                                                                                      | 4-6 weeks  |
| 3.5      | **Skill effectiveness tracking + feedback loops**  | D3, D9 | Link review findings to actual bugs via git history + issue tracker. Build effectiveness baselines per skill. Feed back into prompt selection. "TDD skill has 92% accuracy on refactors, 64% on new features."                                                                           | 6-8 weeks  |
| 3.6      | **Anti-pattern inference from failure clustering** | D7     | Failure feature extraction, clustering algorithm, rule synthesis from clusters. "When files matching pattern X are changed without updating Y, failures occur 80% of the time." Learned constraints from project history.                                                                | 4-6 weeks  |
| 3.7      | **Architectural debt quantification**              | J4     | Cost model: developer-hours per violation type (from historical fix times). Compound interest calculation. ROI scoring for refactorings. "This forbidden import costs $2K/month. Fixing it takes 3 days. ROI: payback in 2 hours."                                                       | 4-5 weeks  |
| 3.8      | **Developer velocity analysis**                    | K1     | Git history temporal analysis, PR/review time integration, friction zone identification. "Feature development touching auth/ takes 40% longer due to high coupling."                                                                                                                     | 5-6 weeks  |
| 3.9      | **Multi-language support**                         | B1, B6 | Tree-sitter integration for Python/Go/Rust/Java parsing. Language-agnostic constraint enforcement. Cross-language dependency tracking in knowledge graph.                                                                                                                                | 6-8 weeks  |
| 3.10     | **Persistent agent specialization**                | F10    | Agent memory system, task-type performance tracking, specialization scoring, dynamic persona weighting. Agents that develop expertise in your specific codebase.                                                                                                                         | 6-8 weeks  |
| 3.11     | **Security posture timeline**                      | L6     | Security metric snapshots over time, supply chain monitoring, vulnerability time-to-fix analysis. "Your security posture: 90/100 → 62/100 in 3 months. Primary driver: cryptography module."                                                                                             | 4-5 weeks  |
| 3.12     | **Agent effectiveness introspection**              | L7     | Domain-specific accuracy tracking, blind spot detection, persona switching triggers. "This agent misses security issues in crypto 85% of the time. Use security-specialist persona instead."                                                                                             | 4-5 weeks  |

**Success criteria:** Skills demonstrate measurable improvement over 30-day period. Cross-project federation works across 3+ projects. Trust scores visible on all review findings. At least one anti-pattern auto-discovered and validated.

---

### Supporting Work (Continuous)

These items don't fit neatly into tiers but run in parallel throughout:

| Item                         | Gap IDs   | What to Build                                                                                                               |
| ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------- |
| **Onboarding funnel**        | A1-A14    | 5-minute quickstart, interactive init prompts, shell completion, `harness doctor`, troubleshooting guide, starter templates |
| **Community infrastructure** | H2, H4-H8 | Discord community, showcase gallery, social media, educational content, sponsorship, gamification                           |
| **Testing gaps**             | E9, E10   | Unit tests for 8+ security rules, enforce coverage thresholds in CI                                                         |
| **Missing skill domains**    | G1-G16    | Deployment, database, API design, monitoring, auth, etc. — driven by community demand once marketplace exists               |
| **Platform expansion**       | B3, B7-B9 | VS Code extension, multi-CI support, monorepo per-package config, config inheritance                                        |

## Alternatives Considered

### Alternative 1: Feature-First (Option B from initial proposal)

Fill all missing skill domains and platform gaps before building community infrastructure.

**Why not chosen:** Missing skills (deployment, database, API design) are incremental improvements that don't create viral dynamics. Community marketplace (H1) lets the community build these skills faster than one team can. Network effects > feature completeness.

### Alternative 2: Community-First (Option C from initial proposal)

Build Discord, marketplace, and sharing before any new technical capabilities.

**Why not chosen:** Community needs something to be excited about. The Tier 1 quick wins (graph anomaly detection, natural language queries, architecture assertions) provide the "wow" content that seeds community engagement. Build the "wow," then build the community around it.

### Alternative 3: Everything in Parallel

Attempt all 112 gaps simultaneously.

**Why not chosen:** Spreads effort too thin. The tiered approach ensures each layer compounds: Tier 1 proves capability → Tier 2 creates viral flywheel → Tier 3 makes the framework irreplaceable. Each tier builds on the infrastructure of the previous one.

## Consequences

### Positive

- Tier 1 ships in 1-2 weeks, demonstrating the framework's graph intelligence capability to the community immediately
- Marketplace (Tier 2) creates network effects — each community skill makes the framework more valuable for everyone
- Game-changing capabilities (self-improving skills, spec-to-code verification, cross-project federation) move into territory no competitor occupies
- Architecture decay timeline and debt quantification convert abstract "code quality" into business-language ROI
- Natural language graph queries make the knowledge graph accessible to non-expert users
- Tiered execution means early tiers fund later tiers with adoption and feedback

### Negative

- Tier 3 items are 6-12 weeks each — long development cycles with risk of scope creep — **mitigation:** strict phase gating, ship MVPs, iterate based on usage data
- Self-improving skills (D4/D5) require outcome data that takes weeks to accumulate — **mitigation:** synthetic benchmarks initially, real data over time
- Cross-project federation (D2) adds architectural complexity (graph merging, ID scoping) — **mitigation:** opt-in, start with learnings federation only
- Multi-language support (B1) is a large surface area — **mitigation:** start with Python (largest non-JS audience), add languages driven by demand
- Marketplace requires critical mass to be useful — **mitigation:** seed with 20+ first-party skills, incentivize community contributions

### Neutral

- Some Tier 2/3 items may be reordered based on community demand signals from marketplace and Discord
- Supporting work (onboarding, testing, platform) runs continuously and may absorb sprint capacity
- The framework's competitive moat shifts from "mechanical enforcement" (defensible but niche) to "intelligence synthesis" (broader but requires sustained investment)

## Action Items

- [ ] **Tier 1.1-1.7**: Implement 7 quick-win MCP tools and skill enhancements — owner: cwarner — by: 2026-04-05
- [ ] **Supporting: Discord**: Stand up Discord community server — owner: cwarner — by: 2026-04-01
- [ ] **Supporting: Onboarding**: Ship 5-minute quickstart + interactive init + `harness doctor` — owner: cwarner — by: 2026-04-12
- [ ] **Tier 2.1**: Skill marketplace MVP (`harness install`, `@harness-skills/*` namespace) — owner: cwarner — by: 2026-04-30
- [ ] **Tier 2.2**: `harness share` constraint sharing — owner: cwarner — by: 2026-05-07
- [ ] **Tier 2.3-2.4**: Architecture decay timeline + predictive failure — owner: cwarner — by: 2026-05-21
- [ ] **Tier 2.5**: Spec-to-implementation traceability — owner: cwarner — by: 2026-05-28
- [ ] **Tier 2.6-2.7**: Skill recommendation + intelligent dispatch — owner: cwarner — by: 2026-06-11
- [ ] **Tier 2.8-2.10**: Constraint emergence + cascading failure + community detection — owner: cwarner — by: 2026-06-25
- [ ] **Tier 3.1-3.3**: Self-improving skills + federation + semantic verification — owner: cwarner — by: 2026-08-31
- [ ] **Tier 3.4-3.12**: Remaining Tier 3 items — owner: cwarner — by: 2026-10-31

## Reference

- Discovery notes: `docs/architecture/framework-gaps-assessment/discovery.md`
- Codebase analysis: `docs/architecture/framework-gaps-assessment/analysis.md`
- Full proposal: `docs/architecture/framework-gaps-assessment/proposal.md`
- Competitor research: `docs/research/framework-research-round-2.md`, `docs/research/framework-research-round-3.md`
- Existing ADRs: `docs/architecture/codebase-hardening/ADR-001.md`, `docs/architecture/graph-context-system/ADR-001.md`, `docs/architecture/force-multiplier-integrations/ADR-001.md`
