# ADR-001: Force-Multiplier Integration Architecture

- **Status:** Proposed
- **Date:** 2026-03-21
- **Decision Makers:** @cwarner
- **Context:** [discovery.md](./discovery.md), [analysis.md](./analysis.md)

## Decision

Adopt **Option C: Bidirectional Knowledge Bridge** as the integration architecture. Build a
multi-tier integration system where external tools feed into the harness knowledge graph
(inbound), harness artifacts push back to external tools (outbound), and MCP peer connections
enable real-time agent interaction with external services.

## Context

Harness operates as a closed loop — agents work within the codebase but lack access to the
broader knowledge ecosystem where developers think, research, and collaborate. Research across
35+ tools, 12,230+ MCP servers, and current March 2026 ecosystem trends identified significant
gaps in agent context richness that external integrations can fill.

## Architecture

```
                         ┌──────────────────────────┐
                         │     Harness Knowledge     │
                         │         Graph             │
                         │   (single source of       │
                         │    truth for agents)       │
                         └────────────┬───────────────┘
                                      │
              ┌───────────────────────┼───────────────────────┐
              │                       │                       │
     ┌────────┴────────┐    ┌────────┴────────┐    ┌────────┴────────┐
     │  INBOUND LAYER  │    │  OUTBOUND LAYER │    │   MCP PEER      │
     │  (Connectors)   │    │  (Exporters)    │    │   LAYER         │
     └────────┬────────┘    └────────┬────────┘    └────────┬────────┘
              │                       │                       │
   ┌──────────┼──────────┐  ┌────────┼────────┐    ┌────────┼────────┐
   │          │          │  │        │        │    │        │        │
Obsidian  Linear  Research  Obsidian Linear  Mermaid  Perplexity  Context7
 Vault    Issues  Cache     Notes   Issues  Diagrams  Search     Docs
                                                    │        │
                                              Sequential  E2B
                                              Thinking    Sandbox
                                                    │        │
                                              Sentry    Augment
                                              Errors    Code
```

## Integration Tiers

### Tier 0: Zero-Config MCP Peers (Day 1)

Add to `.mcp.json` — no harness code changes, immediate value.

| Integration             | What                                          | Impact                                     | Cost                             |
| ----------------------- | --------------------------------------------- | ------------------------------------------ | -------------------------------- |
| **Context7**            | Live version-pinned docs for 9,000+ libraries | Eliminates API hallucination               | Free, one-liner                  |
| **Sequential Thinking** | Structured multi-step reasoning               | Better architecture decisions, debugging   | Free, Anthropic reference server |
| **Playwright MCP**      | Browser automation for agents                 | E2E testing, web scraping, UI verification | Free, Microsoft-maintained       |

### Tier 1: High-Value MCP Peers (Week 1-2)

Add to `.mcp.json` with API key configuration.

| Integration      | What                                  | Impact                                                 | Cost                |
| ---------------- | ------------------------------------- | ------------------------------------------------------ | ------------------- |
| **Perplexity**   | Real-time web search + deep research  | Biggest capability gap — agents get live web knowledge | ~$1-3/M tokens      |
| **Augment Code** | Semantic code search across codebase  | **70% agent accuracy improvement** in benchmarks       | Free local mode     |
| **E2B**          | Cloud sandbox for safe code execution | Agents can test generated code before committing       | Usage-based pricing |
| **Sentry**       | Production error data via remote MCP  | Agents see what's breaking in production               | Free tier available |

### Tier 2: Graph Connectors — Inbound (Month 1)

New `GraphConnector` implementations following the existing pattern
(`JiraConnector`, `SlackConnector`, etc.).

| Connector              | Source                  | Graph Nodes Created                   | Edges                                              |
| ---------------------- | ----------------------- | ------------------------------------- | -------------------------------------------------- |
| **ObsidianConnector**  | Local vault markdown    | `knowledge` (notes), `concept` (tags) | `references` (wikilinks), `documents` (code links) |
| **LinearConnector**    | Linear GraphQL API      | `issue`, `project`, `cycle`           | `applies_to` (code), `blocks`, `relates_to`        |
| **ResearchConnector**  | Perplexity result cache | `research` (queries + results)        | `informs` (features), `cites` (sources)            |
| **UnblockedConnector** | Organizational context  | `decision`, `conversation`            | `decided_by`, `references`                         |

**Implementation pattern** (follows existing connector interface):

```typescript
interface GraphConnector {
  readonly name: string;
  readonly source: string;
  ingest(store: GraphStore, config: ConnectorConfig): Promise<IngestResult>;
}
```

### Tier 3: Graph Connectors — Enhanced Context (Month 2)

| Connector             | Source                     | Graph Nodes Created           | Edges                                  |
| --------------------- | -------------------------- | ----------------------------- | -------------------------------------- |
| **GraptileConnector** | Greptile code intelligence | `pattern`, `dependency_chain` | `uses_pattern`, `depends_on`           |
| **PiecesConnector**   | Developer activity memory  | `activity`, `snippet`         | `worked_on`, `captured_from`           |
| **SentryConnector**   | Production error tracking  | `error`, `incident`           | `caused_by` (commit), `affects` (file) |
| **GraphitiConnector** | Temporal knowledge graph   | `temporal_fact`               | `valid_from`, `superseded_by`          |

### Tier 4: Outbound Exporters (Month 2-3)

Push harness artifacts back to external tools.

| Exporter               | Target               | What Gets Pushed                                                                                     |
| ---------------------- | -------------------- | ---------------------------------------------------------------------------------------------------- |
| **ObsidianExporter**   | Vault markdown files | ADRs → `adr/` folder, learnings → `learnings/`, roadmap → `roadmap.md`, all with wikilinks           |
| **LinearExporter**     | Linear API           | Roadmap features → Linear issues, milestone → project, status syncs back                             |
| **MermaidExporter**    | `docs/diagrams/`     | Architecture diagram, dependency graph, component relationships — auto-generated from graph topology |
| **NanobananaExporter** | Generated images     | Polished architecture visuals, infographics from graph data for documentation                        |

### Tier 5: Bidirectional Bridges (Month 3-4)

Full two-way sync with conflict resolution.

| Bridge       | Inbound                       | Outbound                               | Conflict Strategy                                                                       |
| ------------ | ----------------------------- | -------------------------------------- | --------------------------------------------------------------------------------------- |
| **Obsidian** | Vault notes → graph nodes     | ADRs, learnings, roadmap → vault notes | Last-write-wins with `.harness/sync-metadata.json` timestamps                           |
| **Linear**   | Issue status → roadmap status | Roadmap features → issues              | Linear is source of truth for status; harness is source of truth for feature definition |

### Tier 6: Distribution Surfaces (Month 4+)

| Surface               | What                                     | How                                                                   |
| --------------------- | ---------------------------------------- | --------------------------------------------------------------------- |
| **Raycast Extension** | macOS launcher for harness commands      | React/TS extension calling harness MCP tools                          |
| **Composio Gateway**  | 850+ integrations via single MCP gateway | Replace individual connectors with managed gateway                    |
| **Figma MCP**         | Design-to-code pipeline                  | Agents read design tokens, generate components matching design system |

## Evaluate Later

These are promising but depend on team context:

| Tool                 | When Valuable                         | Integration Path                                     |
| -------------------- | ------------------------------------- | ---------------------------------------------------- |
| **Sourcegraph Cody** | Multi-repo codebases                  | MCP peer (competes with Augment Code)                |
| **Graphite**         | Stacked PR workflow adoption          | MCP peer for auto-stacking agent PRs                 |
| **SonarQube**        | Enterprise code quality requirements  | MCP peer supplementing harness security scan         |
| **Grafana/Datadog**  | Self-hosted monitoring stack          | MCP peer + potential graph connector                 |
| **Neo4j**            | Graph needs to scale beyond LokiJS    | Migration path for GraphStore backend                |
| **Qdrant**           | Semantic/vector search over knowledge | Embedding pipeline + MCP peer for similarity search  |
| **Tana**             | Structured knowledge management       | MCP peer (competes with Obsidian for knowledge slot) |
| **Warp**             | AI terminal users on the team         | MCP client consuming harness tools                   |
| **Windsurf/Zed**     | Additional IDE platform targets       | MCP client consuming harness tools                   |

## Not Recommended

| Tool           | Reason                                                                  |
| -------------- | ----------------------------------------------------------------------- |
| **NotebookLM** | No stable API; community MCP relies on undocumented APIs; 50-source cap |
| **Heptabase**  | No public API; MCP is write-only                                        |
| **Reflect**    | E2E encryption limits programmatic access                               |
| **Elicit**     | Internal-use-only license                                               |
| **Consensus**  | Application-only API                                                    |

## Implementation Principles

1. **MCP-first:** Every integration should work via MCP (peer or consumed by harness MCP server).
2. **Graph-enriched:** Data that persists should flow into the knowledge graph, not stay siloed.
3. **Privacy-first:** User controls what leaves the machine. Local tools (Obsidian, Pieces) preferred over cloud-only.
4. **Connector contract:** All inbound integrations implement `GraphConnector` interface.
5. **Incremental adoption:** Each tier is independently valuable. No tier depends on a later tier.
6. **Composable:** Integrations feed each other (Perplexity → ResearchConnector → Graph → ObsidianExporter → Vault).

## Knowledge Flywheel

The compounding effect across tiers:

```
Developer researches topic (Perplexity) →
  Results cached (ResearchConnector → Graph) →
    Agent uses research in planning (graph context) →
      Agent produces ADR + implementation (harness skills) →
        ADR exported to Obsidian vault (ObsidianExporter) →
          Learnings feed future agent context (ObsidianConnector → Graph) →
            Architecture diagram auto-generated (MermaidExporter) →
              Roadmap feature synced to Linear (LinearExporter) →
                Team tracks progress (Linear) →
                  Status syncs back to roadmap (LinearConnector) →
                    Next research cycle begins...
```

## Success Metrics

| Metric                         | Baseline (Today)                       | Target (6 months)                                                    |
| ------------------------------ | -------------------------------------- | -------------------------------------------------------------------- |
| Graph node count               | Code + Git + Jira + Slack + Confluence | +Research, Knowledge, Issues, Activities, Errors                     |
| Agent context sources          | 4 (code, git, docs, graph)             | 10+ (add research, vault, issues, errors, docs, activities)          |
| Outbound artifact destinations | 1 (`.harness/` directory)              | 4+ (Obsidian, Linear, diagrams, visuals)                             |
| MCP peer connections           | 1 (harness server)                     | 6+ (Context7, Perplexity, Augment, E2B, Sentry, Sequential Thinking) |
| Knowledge feedback loops       | 0 (one-directional)                    | 3+ (Obsidian, Linear, Research cache)                                |

## Risks and Mitigations

| Risk                                               | Impact                              | Mitigation                                                             |
| -------------------------------------------------- | ----------------------------------- | ---------------------------------------------------------------------- |
| MCP tool description bloat (40-50% context window) | Agents lose context for actual work | Tool description optimization; selective tool loading per skill        |
| Bidirectional sync conflicts                       | Data corruption                     | Last-write-wins with timestamps; source-of-truth designation per field |
| API rate limiting on cloud services                | Degraded experience                 | Configurable sync schedules; cache-first pattern                       |
| Community MCP server fragility                     | Integration breaks                  | Prefer official MCP servers; pin versions; fallback to direct API      |
| Over-integration complexity                        | Maintenance burden                  | Each tier independently valuable; prune unused integrations            |

## Alternatives Considered

- **Option A (MCP Peers Only):** Too shallow — agents have enough tools, they need better context. Doesn't solve the core problem.
- **Option B (Graph-First, No Outbound):** Good ROI but misses the flywheel effect. Knowledge flows in but harness artifacts stay trapped.
- **Individual tool integrations without architecture:** Ad hoc integrations become unmaintainable. The tiered approach ensures coherent evolution.
