capiko-ai

# capiko-ai

> capiko-ai turns the GitHub Copilot CLI into a senior teammate that already knows
> your team's playbook. It installs a curated catalog of skills, a teaching-first
> persona, cross-session memory (engram), and a full Spec-Driven Development (SDD)
> workflow into `~/.copilot`. capiko **directs**; Copilot **executes** — capiko
> never calls a model itself, so everything it installs is reproducible and auditable.

It targets GitHub Copilot only and ships as a single native Go binary (a Bubbletea
TUI plus headless subcommands). Configs land in `~/.copilot/`; state, backups, and
drift tracking live in `~/.capiko/`. Module path: `github.com/martinhg/capiko-ai`.
License: MIT.

## Install

- Homebrew (macOS/Linux): `brew install martinhg/homebrew-tap/capiko-ai`
- Script (macOS/Linux): `curl -sL https://raw.githubusercontent.com/martinhg/capiko-ai/main/scripts/install.sh | bash`
- PowerShell (Windows): `irm https://raw.githubusercontent.com/martinhg/capiko-ai/main/scripts/install.ps1 | iex`
- Scoop (Windows): `scoop bucket add capiko-ai https://github.com/martinhg/scoop-bucket && scoop install capiko-ai`
- From source (Go 1.26+): `go install github.com/martinhg/capiko-ai/cmd/capiko-ai@latest`

## CLI surface

Run with no arguments to launch the interactive TUI. Headless subcommands:

- `capiko-ai install [--all] [--json]` — install skills, agents, persona, and configs non-interactively
- `capiko-ai sync [--json]` — reconcile installed configs with the catalog (auto-repair drift); warns when a managed engram binary is outdated
- `capiko-ai uninstall [--json]` — remove capiko-managed configs
- `capiko-ai doctor [--json] [--repair]` — ecosystem diagnostics (exit non-zero on failure); --repair re-applies the managed catalog when drift is found
- `capiko-ai sdd-status [--json]` — deterministic SDD workflow state for a change
- `capiko-ai sdd-continue` — advance the next dependency-ready SDD phase
- `capiko-ai skill-registry` — index installed skills by trigger and path
- `capiko-ai version` — print the version

Exit codes for headless commands: 0 success, 1 error, 2 Copilot not found.

## What capiko installs

- **Skills** (`~/.copilot/skills/<name>/SKILL.md`) — 21 embedded skills Copilot auto-discovers:
  the 10-skill SDD pipeline (explore, propose, spec, design, tasks, apply, verify, archive,
  init, onboard) plus `sdd-shared`, `skill-creator`, `skill-registry`, `codebase-docs`,
  the 4R review set (`review-risk`, `review-readability`, `review-reliability`, `review-resilience`),
  and the capiko house skills (`capiko-conventions`, `capiko-pr`, `capiko-hello`).
- **Copilot agents** (`~/.copilot/agents/<name>.agent.md`) — 8 SDD-phase agents plus a
  coordinator; the real delegation targets the SDD workflow routes to.
- **Persona** (`~/.copilot/copilot-instructions.md`) — a teaching-first (Rioplatense),
  Neutral, or None instruction block shaping how Copilot talks and reasons.
- **Scoped instructions** (`~/.copilot/instructions/*.instructions.md`) — applied per
  matching file via `applyTo` globs.
- **Engram memory** (`~/.copilot/mcp-config.json`, VS Code `mcp.json`) — wires the
  [engram](https://github.com/Gentleman-Programming/engram) MCP server for cross-session
  memory (local or `hybrid` cloud).
- **Team memory sync** (`.git/hooks/post-merge` + `.git/hooks/pre-push`, opt-in) —
  writes marker-delimited hook blocks so `post-merge` runs `engram sync --import` and
  `pre-push` runs `engram sync --project '<name>'`, sharing Engram memory across the
  team through git with no cloud required. Requires explicit ack of the scope-leak risk
  (all project memories including `scope:personal` are committed to git). Mitigations:
  wrap sensitive content in `<private>…</private>` tags, or use a separate project name
  for personal memories. If a competing hook framework (`core.hooksPath`, husky, lefthook,
  pre-commit) is detected, writes are skipped and the equivalent shell lines are shown
  for manual integration. capiko never installs the `engram` binary.
- **Copilot hooks (guardrails)** (`$COPILOT_HOME/hooks/capiko-guardrails.json`, opt-in) —
  a capiko-owned `preToolUse` hook that inspects each tool call and, per posture, asks
  (`warn`) or denies (`strict`) before four dangerous patterns: `rm -rf /`, pipe-to-shell
  (`curl | sh`), `git push --force` to main/master, and `chmod 777`. Non-matches are
  allowed silently. User-level only (repo-level `.github/hooks` is future); org policy
  hooks can override; a `timeoutSec` overrun fails open. v1 interpolates no user input,
  so the shell-injection surface is empty. Re-applied on every sync.
- **Safety net** (`~/.capiko/`) — snapshot-before-mutate backups, per-skill checksum
  state, drift detection, and self-update.

## Architecture notes

- capiko is an **install-time file writer**, not a runtime proxy or daemon. It writes
  static configs Copilot auto-discovers; it never intercepts the request path.
- It ships its own **native SDD engine** in Go (`internal/sddstatus`): `sdd-status` and
  `sdd-continue` compute workflow state deterministically rather than asking a model.
- It **configures** engram (never provisions/downloads it), the same boundary it keeps
  for any external tool.

## Docs

- [README](https://github.com/martinhg/capiko-ai/blob/main/README.md) — full overview, quickstart, menu, SDD workflow
- [Team memory sync](https://github.com/martinhg/capiko-ai/blob/main/README.md#-team-memory-sync) — git hook sharing, scope-leak warning, conflict coexistence
- [Copilot hooks (guardrails)](https://github.com/martinhg/capiko-ai/blob/main/README.md#-copilot-hooks-guardrails) — posture levels, the four patterns, scope and fail-open caveats
- [Headless CLI](https://github.com/martinhg/capiko-ai/blob/main/README.md#-headless-cli) — scripting, CI, dotfiles
- [Spec-Driven Development](https://github.com/martinhg/capiko-ai/blob/main/README.md#-spec-driven-development) — the 8-phase pipeline
- [How it works](https://github.com/martinhg/capiko-ai/blob/main/README.md#-how-it-works) — the direct/execute split
- [Releases](https://github.com/martinhg/capiko-ai/releases) — changelog and pre-built binaries