# CapInt Architecture Decisions

## Positioning

CapInt is a **capability-first runtime router** for IDE agents — not a skill catalog, not a multi-agent factory, not a memory engine.

| Layer | CapInt | Neighbor repos |
|-------|--------|----------------|
| Routing | Yes (core) | skill-gateway, agent-skills |
| Team generation | No | revfactory/harness, agency-agents |
| Memory/graph engine | No (adapters only) | mempalace, agentmemory, graphify |
| Cross-harness standardization | Partial (project scaffold) | affaan-m/ECC |
| Verification discipline | Yes (policy gates) | obra/superpowers |

## Adopted patterns

- **Invisible gateway** (skill-gateway): route without ceremony; user sees Execution Intent, not skill names.
- **Confirm triad** (PrismX lesson): `apply_now | plan_first | analyze_only` on medium+.
- **Operational hygiene** (ECC): `consult`, `status`, `doctor` — read-only / dry-run, no auto-fix.
- **Verification gate** (superpowers): medium/heavy requires evidence before "done".
- **Hybrid scaffold**: minimal first, `prismx-compatible` only on explicit opt-in.

## Explicitly avoided

- Bundling memory/graph runtimes in core (Docker, vector DB, MCP tool floods).
- Self-mutating skills / instinct evolution.
- Full autonomous PM→Architect→Dev→QA pipelines.
- Markdown-only routing tables as source of truth (matrix JSON is SoT).
- Blind overwrite of existing project docs.

## Provider activation policy

Default: **off** for memory and graph providers.

Activation requires (any):

1. Capability `requires_memory: required`, or
2. High-risk capability (memory-retrieval, incident-response, threat-modeling), or
3. Explicit env flag (`CAPINT_MEMORY=1`, `CAPINT_GRAPH=1`)

Blocked when:

- `light` weight and capability does not require memory
- `doctor` has not passed (unless feature flag set)

Fallback: always `local` (HANDOFF, AGENT.md, design.md, project files).

## Event log (optional)

Route events append to `.capint/logs/route-events.ndjson` only when:

- `CAPINT_EVENT_LOG=1`, or
- `.capint/context.json` has `"event_log": true`

Default: off. Does not block route hot-path when disabled.

## Schema versioning

| Change | Version bump |
|--------|----------------|
| `execution_intent` breaking field change | package major |
| matrix field addition | matrix minor (e.g. 1.0 → 1.1) |
| matrix field removal or semantic break | matrix major |

## Scaffold conflict policy

- Missing file → create
- File with `<!-- capint:managed:start/end -->` → merge inner block only
- File without managed markers → write `*.capint.new.md`, never overwrite
- `--force` opt-in only

## Operational command contracts

| Command | Side effects | Auto-fix |
|---------|--------------|----------|
| `consult` | None | No |
| `status` | None | No |
| `doctor` | None | No |
| `audit` | None | No |
| `init` / `scaffold` | Creates/merges files | No (safe-merge only) |
| `route` | None | No |

## Inspiration map (repos reviewed)

| Repo | Take | Skip |
|------|------|------|
| addyosmani/agent-skills | lifecycle phases, verification | mandatory 15-step for all tasks |
| buraksu42/skill-gateway | invisible router, quality tiers | web search on miss, install links in chat |
| multica-ai/andrej-karpathy-skills | constitutional layer | CLAUDE.md-only routing |
| affaan-m/ECC | doctor/status/install state | 249 skills default, daemon/TUI |
| obra/superpowers | evidence-before-claims | full subagent army on light tasks |
| msitarzewski/agency-agents | convert/install UX | 144 persona default bundle |
| MemPalace / agentmemory / graphify | adapter contracts | core embedding, hooks, MCP surfaces |
| giancarloerra/SocratiCode | provider boundary | AGPL docker stack in core |
| revfactory/harness | orchestration patterns reference | team factory in router core |
