# PRD — CapInt v0.5: Agent Capability Activation

**Status:** Draft v2 (review incorporated)  
**Author:** CapInt route → `spec-authoring` / `prd`  
**Date:** 2026-05-30  
**Package baseline:** `@bcelep/capint@0.6.5`  
**Changelog:** v2 — dual-segment UX, explainability, skill lifecycle, CLI power-user, capint-ui prototype spec

---

## 0. Review synthesis (strengths retained)

| Strength | How we preserve it in v2 |
|----------|---------------------------|
| Deterministic skill activation | `installed` = file on disk + agent **must** read before apply; verified in tests |
| Beginner + maintainer personas | Split into **Segment A (chat-first)** vs **Segment B (CLI-first)** with shared contract |
| Workspace boundary | Cross-repo refusal + explicit override phrase |
| Measurable KPIs | Extended with explainability + recovery metrics |
| Bundle / registry / backup | Extended with disable/rollback without losing backups |

---

## 1. Executive Summary

### Problem Statement

CapInt v0.4.4 copies ~115 skills and reports `resolution_status: installed`, but IDE agents do not automatically load them. Beginners lack a **visual** onboarding path beyond chat prose. Power users lack **explainability**, **undo**, and **scriptable** orchestration. Skill count growth creates **bloat and recovery** risk when registry or matrix drifts.

### Proposed Solution

**v0.5–v0.6 “Agent Capability Activation”** in four layers:

1. **Runtime contract** — gateway + deterministic SKILL.md reads (v0.5.0)
2. **Explainability card** — why this capability, which files informed the plan (v0.5.2)
3. **Skill health** — safe disable / restore / rollback via manifest + backups (v0.5.3)
4. **Dual surface** — chat-first (GUNLUK) + optional **`capint-ui`** wizard for non-terminal users (v0.6.0)

CLI remains source of truth; UI is a thin wrapper over `route`, `doctor`, `status`.

### Success Criteria (measurable)

| KPI | Target | Segment | Measurement |
|-----|--------|---------|-------------|
| Skill read before first edit | 100% on medium+ tasks | Both | Agent audit / integration harness |
| Wrong-repo write rate | 0 without explicit override | Both | Boundary test suite |
| Beginner time-to-first-task | ≤ 5 min, **no terminal** | A | n=3 moderated test |
| Beginner completes onboarding wizard | ≥ 80% without support | A | capint-ui funnel |
| User understands *why* capability was picked | ≥ 4/5 survey after explain card | A + B | Post-task micro-survey |
| Recovery from broken registry | ≤ 2 min to green `doctor` | B | `capint recover --dry-run` drill |
| `release-check` | 28/28 pass | B | CI |
| Power user scripted route | 1-liner shell function documented | B | Docs + copy-paste test |

---

## 2. User Experience & Functionality

### 2.1 Two-segment USP (differentiation)

```
┌─────────────────────────────────────────────────────────────────┐
│                        CapInt Core                               │
│  matrix.json · registry · route engine · doctor · manifest       │
└───────────────────────────┬─────────────────────────────────────┘
                            │
           ┌────────────────┴────────────────┐
           ▼                                 ▼
   Segment A — Chat-first              Segment B — CLI-first
   (Beginner / non-terminal)           (Power user / maintainer)
   ─────────────────────────           ─────────────────────────
   · GUNLUK.md 3-step                  · capint route --json
   · IDE chat + confirm triad          · --verbose explain pack
   · capint-ui wizard (v0.6)           · shell aliases / pipelines
   · Tooltips & error plain-Turkish    · debug: manifest/gateway
   · High-contrast a11y UI             · CAPINT_* env flags
```

**Shared invariant:** Every task shows Execution Intent + (when `plan: confirm`) confirm triad. Both segments get **explainability** and **undo window** before destructive apply.

### User Personas (refined)

| ID | Persona | Primary surface | Terminal |
|----|---------|-----------------|----------|
| A1 | Beginner dev | Chat + capint-ui | Avoid |
| A2 | Product owner (non-code) | capint-ui + chat | Avoid |
| B1 | Framework maintainer | CLI + IDE | Daily |
| B2 | DevOps / release engineer | CLI scripts | Daily |

### User Stories (core — unchanged intent)

**US-1 — Invisible routing** · **US-2 — Installed means usable** · **US-3 — Workspace boundary** · **US-4 — Full bundle** · **US-5 — Upgrade path**  
*(Acceptance criteria unchanged from v1; see git history / Appendix A.)*

### User Stories (v2 additions)

**US-6 — Explainability card**

As a product owner, I want a short explanation of why the agent chose a capability so that I can trust automation.

**Acceptance criteria:**

- Before `apply_now`, agent shows **Explanation Card** (max 8 lines):
  - Matched keywords / task_type id
  - Primary skill + workflow (if any)
  - Files consulted (gateway, SKILL.md, HANDOFF snippet count)
  - Confidence source (`route_explain` or `--verbose` equivalent)
- `capint route --verbose` emits same structure as JSON field `explanation` (v0.5.2)

---

**US-7 — Undo / manual gate**

As a user, I want to reject or revise a plan before files change so that wrong skills do not corrupt my repo.

**Acceptance criteria:**

- Confirm options remain: `apply_now | plan_first | analyze_only`
- On `plan_first`, no file writes until second explicit “go” message
- Agent summarizes **files it intends to touch** (paths list) before apply
- v0.6: capint-ui “Cancel / Edit task” returns to wizard step 2 without side effects

---

**US-8 — Skill disable & restore**

As a maintainer, I want to disable a skill without deleting files so that routing stops recommending broken bundles.

**Acceptance criteria:**

- `capint skill disable <name>` → updates `.capint/disabled-skills.json` (append-only log + set)
- Route treats disabled skill as `not_installed` with hint: `capint skill enable <name>`
- `capint doctor` warns on disabled core skills
- Does not delete `skills/<name>/`

---

**US-9 — Self-healing recovery**

As a power user, I want to rollback matrix/registry from backup when config is corrupt.

**Acceptance criteria:**

- `capint recover --list` shows `.capint/backups/*` timestamps
- `capint recover --apply --latest` restores matrix + registry from latest backup; dry-run by default
- `capint doctor` exit code 1 includes **actionable** next command (never silent fail)
- Init manifest v2 tracks bundle files for audit (existing)

---

**US-10 — CLI pipeline / macro**

As a power user, I want to chain route → confirm → log in shell scripts.

**Acceptance criteria:**

- Documented pattern: `capint route --json "$1" | jq ...`
- Env: `CAPINT_DEFAULT_CONFIRM=plan_first` for CI advisory mode
- Example `scripts/capint-task.sh` in package docs (bash + PowerShell)
- Optional v0.6: `capint run "<task>" --confirm apply_now` (single entry — **non-goal for v0.5** if scope creep)

### Non-Goals (updated)

- Full autonomous agent army / vector DB / MCP flood (unchanged)
- Registering 115 skills in Cursor global picker (unchanged)
- **v0.5:** Production-grade hosted SaaS dashboard (capint-ui is **local-first** static or Tauri/Electron prototype)
- **v0.5:** Git-level undo (user uses IDE/git; CapInt only gates *agent* apply window)
- Replacing PrismX entirely

---

## 2.2 Segment A — capint-ui prototype (v0.6)

### Purpose

Ultra-simple **wizard** for users who will not run terminal commands. Wraps existing CLI via child_process or precomputed JSON artifacts after `capint init`.

### Wireframe (text)

```
┌─ CapInt ────────────────────────────────────────┐
│ Step 1/4  ●○○○   Proje hazır mı?                │
│  [✓] skills/ (115)  [✓] matrix  [⚠] doctor     │
│  [ Doktoru çalıştır ]  → plain Turkish result   │
├─────────────────────────────────────────────────┤
│ Step 2/4  ●●○○   Görevini yaz                   │
│  ┌─────────────────────────────────────────┐   │
│  │ Lang dosyaları uyumsuz, düzelt          │   │
│  └─────────────────────────────────────────┘   │
│  [ Route et ]                                   │
├─────────────────────────────────────────────────┤
│ Step 3/4  ●●●○   Plan özeti (Explanation Card)  │
│  Capability: localization-hub                   │
│  Çünkü: "lang", "çeviri" eşleşti (i18n)         │
│  Okunacak: skills/localization-hub/SKILL.md     │
│  ○ apply_now  ● plan_first  ○ analyze_only      │
├─────────────────────────────────────────────────┤
│ Step 4/4  ●●●●   Sonuç                          │
│  Chat’e yapıştır: [ Kopyala ]                   │
│  Sorun mu?  [ Neden bu skill? ]  [ Skill sağlığı ]│
└─────────────────────────────────────────────────┘
```

### UI requirements

| Requirement | Detail |
|-------------|--------|
| Accessibility | WCAG 2.1 AA contrast; keyboard nav; TR + EN labels |
| Error UX | “Skill eksik” → `capint init` / `upgrade --apply` CTA, not stack trace |
| Tooltips | `installed` vs “Cursor listesinde yok” FAQ link |
| Offline | Works on local project folder; no account required |
| Stack options | v0.6 PoC: Vite static page reading `.capint/ui-state.json` **or** Tauri shell |

### KPI (Segment A)

- Wizard completion without opening terminal: ≥ 80%
- Time step 1→3: ≤ 3 min

---

## 2.3 Segment B — CLI power user

### Commands (roadmap)

| Command | Version | Behavior |
|---------|---------|----------|
| `capint route --verbose` | 0.5.1 | Human + JSON `explanation` block |
| `capint skill disable\|enable\|list` | 0.5.3 | Non-destructive skill gating |
| `capint recover --list\|--apply` | 0.5.3 | Backup restore |
| `capint pipeline` | 0.6 | **Optional** — run route + doctor + ide check |

### Scripting example (docs contract)

```bash
# bash — advisory route in CI
intent=$(capint route --json "$TASK" | jq -r '.execution_intent')
echo "$intent" | jq '{capability, resolution_status, plan}'
```

```powershell
# PowerShell
capint route --json "prd hazırla" | ConvertFrom-Json | Select-Object -ExpandProperty execution_intent
```

### Debug mode

`CAPINT_DEBUG=1 capint route "..."` prints: matrix task_type id, provider winner, disabled-skills filter, manifest schema version.

---

## 3. AI System Requirements

### Tool Requirements (extended)

| Tool | Role |
|------|------|
| `capint route --json` | Deterministic resolution |
| `route_explain` / `--verbose` | Explainability card source |
| `capint doctor` / `status` | Health + actionable hints |
| `capint skill disable\|enable` | Skill gating |
| `capint recover` | Rollback |
| `skills/<name>/SKILL.md` | Runtime activation |
| `.capint/disabled-skills.json` | Soft-off registry overlay |

### Explanation Card schema (v0.5.2)

```json
{
  "explanation": {
    "task_type_id": "write_prd",
    "matched_keywords": ["prd", "hazırla"],
    "winner": { "type": "skill", "resource": "prd" },
    "files_to_read": [
      "skills/prismx-skill-gateway/SKILL.md",
      "skills/prd/SKILL.md"
    ],
    "reason_summary": "Keyword match write_prd; prd skill installed on disk.",
    "alternatives_considered": [
      { "resource": "genesis", "type": "workflow", "confidence": 0.83 }
    ]
  }
}
```

### Evaluation Strategy (extended)

| Test | Pass |
|------|------|
| Explain JSON schema | Valid against `.capint/schemas/explanation.v1.json` |
| Disable skill → route not_installed | Automated |
| recover --dry-run | No mutation; lists backup |
| capint-ui smoke | Playwright: 4-step wizard happy path |
| Beginner no-terminal | n=3 via UI only |

---

## 4. Technical Specifications

### Architecture (v2)

```
                    ┌──────────────┐
  Segment A ───────►│  capint-ui   │──┐
  (wizard)          └──────────────┘  │
                                      ▼
  Segment B ───────► capint CLI ◄── route engine
  (terminal)              │              │
                          │         disabled-skills overlay
                          ▼              │
                     doctor / recover    │
                          │              │
                          ▼              ▼
                     .capint/backups   skills/*.md
                          │
                     IDE session rules → Agent Explanation Card → apply/undo gate
```

### Skill proliferation & bloat control

| Mechanism | Description |
|-----------|-------------|
| Registry tiers | core (3) / recommended (matrix) / optional (~100+) |
| `capint skill disable` | Operational off without delete |
| `init --bundle minimal` | **Open:** 5-skill CI stub vs full bundle |
| Matrix ownership | Package wins on upgrade; custom task_types preserved |
| Catalog docs | `skills/prismx-skills-catalog` browse-only; not all loaded into context |
| Doctor warnings | Orphan skills, missing core, duplicate task_type ids |

### Security & Privacy (unchanged +)

- Explanation card must not embed secrets from `.env`
- Recover only touches CapInt-managed JSON under project root
- Disabled skills list is user-visible audit trail

### File conventions (resolved partial)

| Artifact | Canonical path |
|----------|----------------|
| PRD | `docs/PRD-*.md` (CapInt projects); PrismX may use `.prismx/arch/v{N}/PRD.md` |
| Disabled skills | `.capint/disabled-skills.json` |
| UI state (optional) | `.capint/ui-state.json` (generated, gitignored) |

---

## 5. Risks & Roadmap

### Phased Rollout (revised)

**v0.5.0 — Runtime contract** (@ 0.6.5)  
- [x] Full bundle init  
- [x] PRD route, upgrade sync  
- [x] FAQ: installed ≠ Cursor picker  
- [x] AGENT.md activation model  
- [x] session-start: mandatory gateway read  

**v0.5.1 — Explainability (CLI)**  
- [x] `explanation` block in `--verbose` / `--json`  
- [x] Agent session template: Explanation Card before apply  
- [x] Boundary task_type `workspace_scope` (matrix id)  

**v0.5.2 — Trust & gate**  
- [x] Intended file list in `plan_first` output (`files_intended`)  
- [x] Docs: undo = stay on `plan_first` + git  
- [x] Integration tests for explanation schema (AJV)  

**v0.5.3 — Skill health & recovery**  
- [x] `capint skill disable|enable|list`  
- [x] `capint recover --list|--apply`  
- [x] doctor actionable recovery hints  

**v0.6.0 — capint-ui (Segment A)**  
- [x] 4-step wizard PoC (local static)  
- [~] Tooltips + TR error messages (partial — FAQ link backlog)  
- [x] Copy-to-chat Execution Intent  
- [x] Optional `capint skill pin`  

**v0.6.1 — Power pipelines (Segment B)**  
- [x] Documented bash/ps1 macros  
- [x] `CAPINT_DEBUG`, `CAPINT_DEFAULT_CONFIRM`  
- [x] Optional `capint pipeline` smoke command  

**v0.6.5 — Quality gate (post-audit)**  
- [x] Workspace boundary confirm blocked mode  
- [x] Playwright wizard E2E smoke  
- [x] Registry validator + consult/status smokes  
- [ ] Beginner moderated test (n=3) — manual KPI backlog  

### Technical Risks (extended)

| Risk | Mitigation |
|------|------------|
| UI duplicates CLI logic | UI only calls CLI; no second router |
| Explainability token bloat | Cap explanation at 8 lines / structured JSON |
| disable/enable desync from registry | Overlay file; doctor reconciles |
| Skill bloat over 150+ | minimal bundle flag; tier docs |
| False trust in “undo” | Clear copy: CapInt gates agent; git is real undo |

---

## Appendix A — Traceability to v0.4.4

| Requirement | Implementation |
|-------------|----------------|
| Full bundle | `presets.js` → `copyBundleTree` |
| Registry v1.1 | `deriveRegistryFromMatrix` |
| PRD routing | `write_prd` task type |
| Gateway IDE | `ide-sync.js`, `session-start.md` |

## Appendix B — Open questions (updated)

| # | Question | Recommendation |
|---|----------|----------------|
| 1 | Spec path | `docs/PRD-*.md` for CapInt; PrismX keeps arch versioning |
| 2 | minimal bundle flag | Yes — `capint init --bundle minimal` for CI; default full |
| 3 | PrismX vs CapInt | Parallel; CapInt is installable slice; PrismX meta-repo may consume capint as npm |
| 4 | capint-ui stack | Start Vite static + CLI spawn; Tauri if desktop packaging needed |
| 5 | Hosted UI | Non-goal v0.6; revisit only with auth story |

## Appendix C — Review feedback mapping

| Feedback theme | PRD section |
|----------------|-------------|
| Non-tech UI / wizard | §2.2 capint-ui |
| Explainability | §US-6, §3 Explanation Card |
| Undo / manual gate | §US-7 |
| Skill bloat / self-healing | §US-8, §US-9, Skill proliferation table |
| CLI automation | §2.3 Segment B |
| Two-sided USP | §2.1 diagram |

---

*v2 incorporates external review. Next lock: pick v0.5.1 vs v0.5.3 implementation order.*
