code-ai-installer 3.0.0 → 4.0.1-a

package/domains/development/locales/en/.agents/skills/mcp-integration/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: mcp-integration
+description: "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents."
+type: mandatory
+domain: development
+owners:
+  - architect
+  - conductor
+  - devops
+  - product_manager
+  - reviewer
+  - senior_full_stack
+  - tester
+  - ux_ui_designer
+gates:
+  - PM
+  - UX
+  - ARCH
+  - DEV
+  - REV
+  - OPS
+  - TEST
+  - RG
+tech:
+  - mcp
+topic:
+  - general
+triggers:
+  - record_decision
+  - request_decision
+  - classify_gate
+  - advance_gate
+  - submit_artifact
+  - list_skills
+  - get_skill
+  - load_role
+  - MCP
+  - code-ai MCP
+  - gate flow
+related:
+  - karpathy-guidelines
+  - code-review-checklist
+  - adr-log
+budget_lines: 250
+schema_version: 1
+license: MIT
+---
+
+
+# MCP Integration
+
+Rules for working with the code-ai MCP server for all development agents. Which tool to call when, in what order, what to record, what mistakes to avoid.
+
+> If the MCP server is not registered in `.mcp.json` — fall back to file reads with a `report_exception` note. Do not stay silent.
+
+---
+
+## 1. When to apply
+
+**Triggers:** any task in the development domain that passes through gates (PM/UX/ARCH/DEV/REV/OPS/TEST/RG). Which is — almost any task.
+
+**Output:** the tool was invoked correctly, its result was used in the current phase, and recorded via `record_decision` or `submit_artifact` when needed.
+
+---
+
+## 2. What is code-ai MCP
+
+A local MCP server (stdio transport) with 26 tools. State lives in `.code-ai/state/` (JsonlStore — append-only, files `decisions.jsonl`, `exceptions.jsonl`, `artifacts/<task>.jsonl`). MempalaceStore is an optional mirror, not the source of truth.
+
+The server is registered by the installer (`.mcp.json` is written automatically on `--target=claude`). If the installer did not run — records can be made manually in `.code-ai/state/`, but the MCP tools are preferred: they validate input via zod.
+
+---
+
+## 3. Group 1 — Navigation (4 tools)
+
+**`list_skills`** — get the full list of domain skills with frontmatter. Call at task start to understand what you have. The parser is permissive — it skips skills with broken frontmatter (see `run_drift_audit` if something was expected but did not appear).
+
+**`get_skill`** — get a SKILL.md by name. Use instead of manual file reading — get_skill returns frontmatter already parsed and the markdown body separately.
+
+**`load_role`** — get an agent profile (prompt + list of skills the agent may call). Call first when a task lands on your role.
+
+**`regenerate_manifest`** — rebuild `manifest.json` after skill edits. Call when you added/removed/renamed a skill.
+
+**Order at task start:** `load_role` → `list_skills` → pick the ones you need → `get_skill` for each.
+
+---
+
+## 4. Group 2 — Gate flow (5 tools)
+
+This is the gate-passage ritual. **Every gate** must follow these steps in order.
+
+**`classify_gate`** — classify the task before starting work on a gate. Returns `auto_resolve` (green path, artifact still required for audit), `fork` (needs a DEN decision — request it via `request_decision`) or `exception` (an automated check failed — write a breakdown to exceptions).
+
+**`request_decision`** — request a decision from DEN. Creates an ADR-PENDING-* entry in decisions.jsonl. Must be called **before** `record_decision` if the decision requires DEN approval. Do not stay silent and do not choose on your own — that violates `karpathy-guidelines §1`.
+
+**`current_gate`** — where the task currently is. Useful when context was lost or you switched between tasks.
+
+**`advance_gate`** — push the task into the next gate. **Only after** all artifacts of the current gate are submitted and sign_off is in place.
+
+**`sign_off`** — sign the current gate. Sign_off without a prior `submit_artifact` is an anti-pattern (see §8). Result first, signature second.
+
+**Canonical gate ritual:** `current_gate` (understand where you are) → `classify_gate` → if fork: `request_decision` → wait → `record_decision` → continue → `submit_artifact` → `verify_claim` (where applicable) → `sign_off` → `advance_gate`.
+
+---
+
+## 5. Group 3 — Actions (15 tools)
+
+Tools that **do** something in the project. Each answers one DoD question.
+
+**`run_tests`** — a vitest/jest/pytest wrapper. Call when the DoD says "tests are green". Returns `numPassedTests`, `numFailedTests`, `failureMessages`. Used by `verify_claim` for `claim_type=tests_pass`.
+
+**`check_lint`** — linter check. Returns `clean: true/false` plus a list of lint failures. DoD claim_type `lint_clean`.
+
+**`build`** — `tsc` or equivalent. Parses `TSxxxx` errors. DoD claim_type `build_succeeds`.
+
+**`apply_diff`** — apply a git diff from stdin. Cleaner than manual edits across many Edit/Write calls — especially for multi-file patches.
+
+**`git_commit`** — commit (with paths or `-a`). Uses a tempfile for the message — heredoc with quotes is unreliable on Windows.
+
+**`run_drift_audit`** — find divergence between skills on disk and AGENTS.yaml/manifest.json. The parser is permissive — it sees broken skills (unlike `list_skills` which skips them).
+
+**`e2e_playwright`** — Playwright runner. Browsers are not downloaded by default (`.npmrc` skip flag) — install manually if needed.
+
+**`docker_compose`** — wrapper over `docker compose` (up/down/ps/logs). Skipped if the Docker daemon is not running.
+
+**`dependency_supply_chain`** — `npm audit --json` parser. Returns vulnerabilities with severity. DoD claim_type `no_critical_vulns`.
+
+**`verify_claim`** — meta-tool. Takes a `claim_type` (`tests_pass` / `lint_clean` / `build_succeeds` / `no_critical_vulns` / `e2e_passes` / `docker_runs` / `custom`), calls the right action tool, returns a structured verdict. `custom` is still a stub — for it, human verification (see DEV-103).
+
+**`audit_budget_compliance`** — file budget compliance check: declared_budget > schema_max (catches schema rejection latent bugs — DEV-107 RoleFrontmatter case) and actual_lines > declared_budget. Across all agent.md + SKILL.md in the given domain (RU + EN). Call periodically or before substantial edits to agent.md / SKILL.md.
+
+**`audit_bilocale_parity`** — RU/EN locale parity check: pairs each agent.md / SKILL.md with its sibling in the other locale and reports declared_mismatch (differing budget_lines), actual_mismatch (differing line counts — the design-intake drift in DEV-114), and orphan (file present in one locale only). Read-only. Call before/after edits that touch a single locale.
+
+**`aggregate_run_metrics`** — the Auditor's data foundation. Computes deterministic per-agent (gate→role via pipeline.yaml) and per-workflow (mode) statistics from the completed-run ledger (`.code-ai/state/audit/runs.jsonl`): first-try rate, reworks, rollbacks, circuit-breaker trips, exceptions, classification breakdown. `min_runs` (default 3) guards small samples. Read-only, numbers only — judgment belongs to the Auditor agent.
+
+**`propose_change`** — record an Auditor proposal (a draft change to an agent/skill) as a pending entry in the local store (`.code-ai/state/audit/proposals.jsonl`). Carries change_kind (edit_minor/add_asset/destructive → risk tier), rationale, evidence, threshold_met, and the inline draft. Pure surfacing — touches no asset; inert until approved/applied (item 4b).
+
+**`list_proposals`** — list Auditor proposals (newest first), filters status/risk/domain. Read-only.
+
+**`review_proposal`** — authorize a proposal status transition (approve/reject a pending one; mark an approved one applied) plus a mandatory report. Applies the autonomy matrix + the `.code-ai/config.json` toggle: `decided_by='auditor_auto'` may approve only low/additive AND only when the gate is OFF; destructive (high) and gate-ON always require den. Auto-adding a new skill also runs an additive-dedup guard — on overlap with an existing skill it routes to den instead of auto-adding. Authorization only — the byte write into the asset is a separate submit_artifact/edit step (see next_step).
+
+---
+
+## 6. Group 4 — Recording decisions (6 tools + 1 utility)
+
+**`record_decision`** — write an ADR decision to `decisions.jsonl`. **Only after** `request_decision` if the decision needs DEN. If the decision is mechanical (signer=mcp) — direct is fine, but set `signer: "mcp"` explicitly.
+
+**`recent_decisions`** — last N decisions (filters by domain/signer/since). Use to understand the current task context.
+
+**`audit_trail`** — the full audit trail of a task: all decisions + artifacts + exceptions in chronological order. Call before `sign_off` to make sure nothing was forgotten.
+
+**`submit_artifact`** — submit an artifact of the current gate (e.g. spec.md, ADR draft, design doc). Without it you cannot `sign_off`.
+
+**`list_artifacts`** / **`get_artifact`** — see what was already submitted in the task. Use to avoid duplicates.
+
+**`report_exception`** — record an exception (gate-check failed). Do not use instead of an honest fix — exception means "I tried, didn't work, reason X, need a fork", not "workaround".
+
+**Storage lives in JsonlStore** (append-only). No "overwrite" — only a new entry with `invalidates: <prev_id>` via `kg_invalidate` if a fact is outdated.
+
+---
+
+## 7. Canonical rituals
+
+### Ritual A — "Got a task"
+```
+1. load_role          (understand what I can do)
+2. list_skills        (what exists in the domain)
+3. current_gate       (where the task is)
+4. get_skill <name>   (for each relevant skill)
+5. classify_gate      (start gate ritual)
+```
+
+### Ritual B — "Closing a gate"
+```
+1. verify_claim       (for each DoD claim_type with an automated check)
+2. submit_artifact    (artifacts of the gate)
+3. audit_trail        (last check — is everything in place)
+4. sign_off           (signature)
+5. advance_gate       (transition)
+```
+
+### Ritual C — "Architectural decision"
+```
+1. request_decision   (creates ADR-PENDING-*)
+2. (wait for DEN approve)
+3. record_decision    (finalizes the ADR with signer=den)
+4. apply_diff         (apply the changes as one patch if possible)
+5. git_commit         (commit with adr_id in the message)
+```
+
+---
+
+## 8. Anti-patterns
+
+1. **`record_decision` without `request_decision`** for decisions that need DEN approve — breaks governance, breaks the audit trail.
+2. **`advance_gate` without `sign_off`** — the gate stays "unsigned", the next agent does not understand what is ready.
+3. **`apply_diff` without `git_commit`** — changes sit in the working tree, the next session loses them or claims them as its own.
+4. **Manual SKILL.md parsing** instead of `get_skill` — you skip frontmatter validation and catch a latent bug (see the DEV-103 list_skills lesson).
+5. **`report_exception` instead of an honest fix** — exception is for "DEN decides next", not for "I worked around it".
+6. **Calling MCP when the server is not registered** without a graceful fallback — silent failure is worse than an honest "MCP unavailable, fell back to file read".
+
+---
+
+## 9. DoD
+
+- [ ] gate ritual fully completed (classify → action → submit → sign_off → advance)
+- [ ] all artifacts submitted via `submit_artifact`
+- [ ] all decisions recorded via `record_decision` (with `request_decision` where DEN approve is required)
+- [ ] exceptions recorded honestly via `report_exception` (if any)
+- [ ] `verify_claim` called for every DoD claim with an automated check
+- [ ] commits with MCP-coupled changes are made in a single batch (apply_diff → git_commit)

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/claude.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-integration",
+  "display_name": "MCP Integration",
+  "description": "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents.",
+  "default_prompt": "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate.",
+  "triggers": [
+    "mcp-integration",
+    "MCP",
+    "code-ai MCP",
+    "gate flow",
+    "record_decision",
+    "request_decision",
+    "classify_gate"
+  ],
+  "capabilities": [
+    "mcp",
+    "gate-flow",
+    "integration"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/copilot.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-integration",
+  "display_name": "MCP Integration",
+  "description": "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents.",
+  "default_prompt": "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate.",
+  "triggers": [
+    "mcp-integration",
+    "MCP",
+    "code-ai MCP",
+    "gate flow",
+    "record_decision",
+    "request_decision",
+    "classify_gate"
+  ],
+  "capabilities": [
+    "mcp",
+    "gate-flow",
+    "integration"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/gemini.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-integration",
+  "display_name": "MCP Integration",
+  "description": "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents.",
+  "default_prompt": "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate.",
+  "triggers": [
+    "mcp-integration",
+    "MCP",
+    "code-ai MCP",
+    "gate flow",
+    "record_decision",
+    "request_decision",
+    "classify_gate"
+  ],
+  "capabilities": [
+    "mcp",
+    "gate-flow",
+    "integration"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/kimi.yaml

@@ -0,0 +1,18 @@
+name: "mcp-integration"
+display_name: "MCP Integration"
+description: "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents."
+default_prompt: "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate."
+triggers:
+  - "mcp-integration"
+  - "MCP"
+  - "code-ai MCP"
+  - "gate flow"
+  - "record_decision"
+  - "request_decision"
+  - "classify_gate"
+capabilities:
+  - "mcp"
+  - "gate-flow"
+  - "integration"
+tools: []
+implicit_invocation: true

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "MCP Integration"
+  short_description: "Rules for working with the code-ai MCP server for all development agents — gate ritual, recording discipline, action tools."
+  default_prompt: "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate."
+dependencies:
+  tools: []
+policy:
+  allow_implicit_invocation: true

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/qwen.json

@@ -0,0 +1,22 @@
+{
+  "name": "mcp-integration",
+  "display_name": "MCP Integration",
+  "description": "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents.",
+  "default_prompt": "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate.",
+  "triggers": [
+    "mcp-integration",
+    "MCP",
+    "code-ai MCP",
+    "gate flow",
+    "record_decision",
+    "request_decision",
+    "classify_gate"
+  ],
+  "capabilities": [
+    "mcp",
+    "gate-flow",
+    "integration"
+  ],
+  "tools": [],
+  "implicit_invocation": true
+}

package/domains/development/locales/en/.agents/skills/mcp-integration/agents/skill.yaml

@@ -0,0 +1,26 @@
+version: 1
+name: "mcp-integration"
+display_name: "MCP Integration"
+description: "Which MCP tool to call and in what order — gate ritual, recording discipline, action tools for all development agents."
+default_prompt: "Use $mcp-integration when a task goes through the code-ai MCP gate flow: classify_gate, record_decision, submit_artifact, sign_off, advance_gate."
+triggers:
+  - "mcp-integration"
+  - "MCP"
+  - "code-ai MCP"
+  - "gate flow"
+  - "record_decision"
+  - "request_decision"
+  - "classify_gate"
+capabilities:
+  - "mcp"
+  - "gate-flow"
+  - "integration"
+tools: []
+invocation:
+  explicit: true
+  implicit: true
+localization:
+  default_locale: "en"
+  available_locales:
+    - "ru"
+    - "en"

package/domains/development/locales/en/.agents/skills/memory/SKILL.md

@@ -1,8 +1,39 @@
 ---
 name: memory
-description: Project context management — what to store, how to retrieve it, how to avoid decision conflicts and context loss between sessions.
+description: "Project context management — what to store, how to retrieve it, how to avoid decision conflicts and context loss between sessions."
+type: mandatory
+domain: development
+owners:
+  - conductor
+gates:
+  - PM
+  - UX
+  - ARCH
+  - DEV
+  - REV
+  - OPS
+  - TEST
+  - RG
+tech: []
+topic:
+  - orchestration
+triggers:
+  - save context
+  - what to remember
+  - session context
+  - avoid decision conflict
+  - memory across sessions
+  - extract context
+related:
+  - handoff
+  - board
+  - adr-log
+  - gates
+budget_lines: 290
+schema_version: 1
 ---
 
+
 # Skill: Memory (context between sessions)
 
 Do not lose context: decisions, contracts, requirements, results.
@@ -21,7 +52,7 @@ Do not lose context: decisions, contracts, requirements, results.
 
 ```
 1. During work:
-   ├── Save decisions as they happen (ADR, assumptions)
+   ├── Save decisions as they happen (ADR file)
    ├── Save deliverables (PRD, specs, contracts)
    └── Save issues/findings (bugs, review findings)
 
@@ -52,6 +83,7 @@ Do not lose context: decisions, contracts, requirements, results.
 | 🟠 **Important** | Test results | Test report artifacts | After each test run |
 | 🟠 **Important** | Backlog + Board | `docs/backlog.md`, board in messages | After each gate |
 | 🟡 **Useful** | Design decisions | Design intake report | When design changes |
+| 🟡 **Useful** | Cross-session knowledge graph | `docs/sessions/*.md` | After significant decisions/events |
 | 🟡 **Useful** | Session summaries | Session handoff docs | End of each session |
 
 ---

package/domains/development/locales/en/.agents/skills/memory/agents/kimi.yaml

@@ -1,12 +1,12 @@
-name: "memory"
-display_name: "Memory (context between sessions)"
-description: "Project context management — what to store, how to retrieve it, how to avoid decision conflicts and context loss between sessions."
-default_prompt: "Use $memory when the task matches the \"Memory (context between sessions)\" skill."
-triggers:
-  - "memory"
-  - "Memory (context between sessions)"
-  - "Project context management — what to store, how to retrieve it, how to avoid decision conflicts and context loss between sessions"
-capabilities:
-  - "memory"
-tools: []
-implicit_invocation: true
+name: "memory"
+display_name: "Memory (context between sessions)"
+description: "Project context management — what to store, how to retrieve it, how to avoid decision conflicts and context loss between sessions."
+default_prompt: "Use $memory when the task matches the \"Memory (context between sessions)\" skill."
+triggers:
+  - "memory"
+  - "Memory (context between sessions)"
+  - "Project context management — what to store, how to retrieve it, how to avoid decision conflicts and context loss between sessions"
+capabilities:
+  - "memory"
+tools: []
+implicit_invocation: true