lgtm-specs 0.0.4

package/integrate/README.md

@@ -0,0 +1,459 @@
+# Integration Protocol
+
+**Spec Version**: 0.0.4
+
+This document defines how external tools (like `opencode-lgtm`) must consume this Knowledge Graph.
+
+Versioning: see `integrate/versioning.md`.
+
+## 1. Directory Structure
+
+```
+lgtm-specs/
+├── rules/
+│   ├── README.md              # Master index
+│   ├── constitution/          # CONS-XXXXX (Universal)
+│   ├── laws/                  # DOMAIN-XXXXX (Domain)
+│   │   └── go/
+│   │       └── README.md      # Domain index
+│   └── policies/              # Project policies (default.md, [project]-policy.md)
+├── agents/                    # Agent specifications
+├── models/
+│   └── registry.yaml          # Model capability mapping
+└── integrate/
+    ├── README.md              # This document
+    └── versioning.md          # Spec versioning
+```
+
+## 2. The Context Injection (Index Loading)
+
+Tools must implement the **Counsel Logic** dynamically.
+
+1.  **Detect**: Identify all relevant domains present in the project (languages + tooling).
+    - Projects may be multi-language (monorepos).
+2.  **Load**: Load the Domain Index for each detected domain (e.g., `rules/laws/go/README.md`, `rules/laws/typescript/README.md`).
+3.  **Inject**: Provide the loaded index content to the `@Counsel` agent's `{{indices}}` placeholder.
+
+Policy resolution:
+
+- If the user's repo contains `.lgtm/policies/README.md`, include it as the Primary local Policy path.
+- Otherwise include `rules/policies/default.md`.
+
+Notes:
+
+- Tools SHOULD treat `.lgtm/policies/README.md` as the local policy index/summary and avoid injecting a large number of
+  local policy note files by default.
+
+## 3. The Agent Builder (Rule Loading)
+
+Tools must parse `agents/**/*.md` and inject full rule content into the agent prompt.
+
+### Step 1: Parse Agent Spec Sections
+
+Extract sections:
+`<Meta>`, `<Role>`, `<SubAgents>`, `<InjectedSubAgents>`, `<Input>`, `<Context>`, `<Indices>`, `<InjectedRules>`,
+`<Objective>`, `<OutputFormat>`, `<Workflow>`, `<Constraints>`.
+
+- **Tag Matching**: Section tags may be indented; match opening/closing tags with optional leading whitespace.
+- **Missing Sections**: If a section tag is absent, treat it as empty.
+- **Required Placeholder**: If a tool intends to inject rules, the agent spec MUST contain a literal `{{injected_rules}}`.
+
+Prompt construction categories:
+
+- **Tool metadata (strip)**: `<Meta>`
+- **Tool schema (strip)**: `<Input>`
+- **Template containers (keep wrapper)**: `<InjectedRules>`, `<Indices>`, `<InjectedSubAgents>`
+- **LLM-facing (keep)**: all other sections
+
+`<Meta>` format:
+
+- Key lines MUST start at column 1 and match: `^[A-Za-z][A-Za-z0-9_-]*:(\s.*)?$`.
+  - Key names are single tokens (no spaces).
+- Values may be multi-line.
+  - Start a block value with `Key:` and put continuation lines on the following lines (often as markdown bullets).
+  - Block values end at the next key line (regex match) or the end of `<Meta>`.
+  - Lines inside a block may contain `:` (including trailing `:`); treat them as value lines unless they match the key
+    regex. Example: `Critical-path heuristics (informational only):` is a value line.
+- Required: `Capability: <capability-id>` for role agents.
+- Common keys (modes): `Type`, `Brain`, `Trigger`, `Team`, `SafetyProfile`.
+- Common keys (roles): `Capability`, `Trigger`, `RuleRender`, `RuleScope`.
+  - `Trigger` is informational metadata. For modes, the canonical trigger list lives in the mode spec `<Meta>`.
+- `RuleRender` values: `full` | `trimmed` | `none` | `arbitration-full`.
+- `RuleRender` semantics:
+  - `full`: inject the full rule body (including `## Examples`).
+  - `trimmed`: inject the rule body without `## Examples`.
+  - `none`: do not inject rules.
+  - `arbitration-full`: inject full rule bodies only for contested rules during arbitration.
+- `RuleScope` values: `step` | `plan`.
+- `RuleScope` semantics:
+  - `step`: inject only the rules referenced by the current plan step.
+  - `plan`: inject all selected rules for the plan/review.
+  - Default: `plan` when unspecified.
+
+Section semantics (prompt construction):
+
+| Section               | Category           | Include in LLM prompt? | Notes                                                                                           |
+| --------------------- | ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------- |
+| `<Meta>`              | Tool metadata      | No                     | Parse for orchestration/model selection, then strip.                                            |
+| `<Role>`              | LLM-facing         | Yes                    | Persona/identity/strategy (roles) or goal (modes).                                              |
+| `<SubAgents>`         | LLM-facing         | Lead only              | Agent catalog for orchestration.                                                                |
+| `<InjectedSubAgents>` | Template container | Lead only              | Replace `{{subagents}}` allowlist when provided.                                                |
+| `<Input>`             | Tool schema        | No                     | Runtime fills an Input Packet per invocation; omit `<Input>` from the system prompt by default. |
+| `<Context>`           | LLM-facing         | Optional               | Focus/boundaries/background.                                                                    |
+| `<Indices>`           | Template container | Counsel only           | Replace `{{indices}}`; keep wrapper.                                                            |
+| `<InjectedRules>`     | Template container | Yes                    | Replace `{{injected_rules}}`; keep wrapper.                                                     |
+| `<Objective>`         | LLM-facing         | Yes                    | Required for role agents; optional for mode specs.                                              |
+| `<OutputFormat>`      | LLM-facing         | Yes                    | Required for role agents; optional for mode specs.                                              |
+| `<Workflow>`          | LLM-facing         | Yes                    | Required.                                                                                       |
+| `<Constraints>`       | LLM-facing         | Optional               | Strongly recommended.                                                                           |
+
+Input Packet (invocation-time context):
+
+- Tools MUST provide the agent's actual inputs at invocation time (as a filled key/value block).
+- Tools SHOULD include the filled Input Packet and omit the agent spec `<Input>` section from the system prompt.
+- For large payloads (filtered diffs), tools SHOULD prefer providing a ready-to-run `Diff Command` over inlining.
+  - `Diff Command` MUST return a filtered diff excluding generated files.
+  - If an agent expects a diff (`Diff`/`Diff Command` inputs), tools MUST provide at least one of `Diff` or
+    `Diff Command`.
+
+### Step 2: Strip Rule Metadata
+
+When injecting a Rule (Law/Constitution), remove the Header Section.
+
+- **Algorithm**: Remove everything _before_ the first `## Definition` header. Keep everything from `## Definition` onward.
+- **Rule IDs**: Tools SHOULD prefix each injected rule with `### <RULE-ID>` for traceability.
+
+### Step 3: Render Rules
+
+Tools SHOULD support role-dependent rule rendering to reduce prompt cost:
+
+- **Full**: `## Definition` + `## Requirements` + `## Anti-Patterns` + `## Examples`
+- **Trimmed**: `## Definition` + `## Requirements` + `## Anti-Patterns` (strip `## Examples`)
+- **Algorithm**: For trimmed rendering, remove everything from the `## Examples` header onward.
+- **Default mapping**:
+  - Builder: Full.
+  - Planner: Trimmed.
+  - Reviewers: Trimmed.
+  - Lead: None during orchestration; during arbitration, Full for contested rules only.
+
+Arbitration invocations (Lead):
+
+- Tools MUST distinguish normal `@Lead` orchestration from arbitration.
+- Normal orchestration: inject no rules into `@Lead`.
+- Arbitration: when the selected mode enters an arbitration step (or `@Lead` requests arbitration), tools MUST re-invoke
+  `@Lead` with:
+  - a minimal Tier 2 diff snippet for the contested lines, and
+  - full rule bodies for the contested rule set only.
+
+Tools MAY override defaults using agent `<Meta>` keys (`RuleRender`, `RuleScope`).
+
+### Step 4: Template Placeholders
+
+Replace placeholders like `{{injected_rules}}` with the stripped/rendered content.
+
+- Tools MUST expand placeholders anywhere they appear (not just inside `<InjectedRules>`).
+
+- **Contract**: Worker agents that require rules MUST include a literal `{{injected_rules}}` placeholder in their spec.
+- **Empty Injection**: If no rules are available, replace `{{injected_rules}}` with an empty string.
+- **Empty Containers**: If a template-container section becomes empty/whitespace after replacement, tools SHOULD drop the wrapper tags.
+- **SubAgents (Optional)**: Tools MAY inject an allowlist into `{{subagents}}` for orchestration control.
+  - Semantics: After templating, if `<InjectedSubAgents>` is empty/whitespace, the Lead may use the full `<SubAgents>` catalog.
+
+Shared blocks:
+
+- Tools MUST support shared-block placeholders used by this repo's agent specs.
+  - `{{reviewer_base_constraints}}` -> `agents/roles/reviewer/BASE.md`
+  - `{{reviewer_output_format}}` -> `agents/roles/reviewer/OUTPUT_FORMAT.md`
+- Tools MAY support additional placeholders for shared prompt fragments.
+- Shared fragments are Markdown snippets (not full agent specs).
+- If a placeholder is present in a prompt, tools MUST NOT leave it unexpanded.
+
+### Step 5: Execute
+
+Send the composed system prompt to the LLM.
+
+Avoid duplicate rule context:
+
+- Tools SHOULD NOT include both:
+  1. the selected-rule list (paths/reasons), and
+  2. the hydrated rule text blocks,
+     in the same agent prompt.
+- Keep Counsel's JSON output in tool logs and inject only stripped rule bodies via `{{injected_rules}}`.
+- If the LLM must reference specific rules, include a compact list of injected rule IDs (IDs only) or prefix each injected rule body with
+  `### <RULE-ID>`; avoid full paths and rule header metadata.
+
+## 4. The Model Resolver
+
+Tools must resolve the Agent's **Capability Requirement** to a specific model ID.
+
+- **Input**: Agent Spec `<Meta>` contains `Capability: <capability-id>`.
+  - `<capability-id>` must match a key under `capabilities` in `models/registry.yaml`.
+  - Valid capability IDs: `reasoning`, `coding`, `data`, `fast`, `security`, `docs`, `general`.
+- **Lookup**: `models/registry.yaml` -> `capabilities.<name>` -> candidate list.
+- **Selection**:
+  1.  **Iterate**: Check each model in the candidate list in order.
+  2.  **Availability**: Select the first model that is available.
+      - The registry list order is the preference order.
+
+### Availability Detection
+
+Tools must define and document how availability is determined.
+
+Minimum requirement:
+
+- Treat a model as available only if the provider access is configured and the model can be invoked.
+- Availability checks should be deterministic within a single run (cache results).
+
+Tools MUST document their availability mechanism and MUST treat missing credentials/config as unavailable.
+
+Minimum mechanism (environment variable convention):
+
+1.  Derive provider from the model ID prefix before `/` (e.g., `openai/gpt-5.2` -> `openai`).
+2.  Require an API key in `${PROVIDER_UPPER}_API_KEY`.
+    - Example: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `MINIMAX_API_KEY`, `MOONSHOTAI_API_KEY`, `QWEN_API_KEY`.
+    - For `moonshotai/*`, `${PROVIDER_UPPER}` is `MOONSHOTAI`.
+3.  If the key is missing, treat the provider (and its models) as unavailable.
+
+Runtime failover:
+
+- If a model invocation fails due to authentication/permission errors, treat the provider as unavailable for the rest of the run.
+- If a model invocation fails due to transient network errors or rate limits, treat that model as unavailable for the rest of the run and try the next candidate.
+- Cache availability/failure decisions for the duration of the run.
+
+Optional preflight (non-inference):
+
+- If the provider exposes a lightweight model listing / ping endpoint, tools MAY use it to confirm credentials before first inference.
+
+Fallback:
+
+- If no model in the specific capability list is available, tools SHOULD FAIL by default.
+- Tools MAY fall back to `capabilities.general` only if they can guarantee the selected model can satisfy the required capability; tools MUST emit an explicit warning when using a fallback.
+
+Workflow invariance:
+
+- Model availability must not change workflow semantics.
+- Do not reduce the number of reviewers or gates due to model unavailability.
+
+## 5. Context Limits
+
+- **Max Rules**: Inject maximum **10** most relevant rules per agent.
+- **Counsel Output**: Counsel SHOULD target <= 10 paths and MUST cap at <= 15 paths; tools MUST down-select to <= 10 per
+  agent.
+- **Relevance**: Determined by the rule paths returned by Counsel (plus any mandatory policy rules).
+- **Truncation**: If content exceeds model context window:
+  1.  Truncate **Examples** first.
+  2.  Keep **Requirements** and **Definition** at all costs.
+
+### Non-Rule Context Budget
+
+Large artifacts (diffs, long logs) should only be sent to agents that need them.
+Avoid relaying the full diff through multiple agent contexts.
+
+Git context tiers:
+
+- **Tier 0 (Intent)**: commit subjects (and bodies when needed).
+- **Tier 1 (Scope)**: file manifest (added/modified/deleted) + size stats.
+- **Tier 2 (Review)**: filtered diff for human-authored files only.
+
+Tools SHOULD NOT make agents guess git commands.
+When an agent must fetch git context, the runtime MUST provide explicit commands in the filled Input Packet.
+
+Prompt caching (optional optimization):
+
+- If a provider supports prompt caching, tools SHOULD batch reviewers by provider and keep a shared prefix stable.
+- Put shared content first (mode + request + filtered diff + shared rules), then append reviewer-specific instructions.
+
+Recommended minimum inputs:
+
+| Agent                | Provide                                                                                                          | Avoid                             |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| Explorer             | `Query` + `Scope`; optional `Change Manifest`                                                                    | Full diff content                 |
+| Counsel              | `Task` + Context Map (Summary Map with domains/policies); optional `Change Manifest`                             | Full diff content                 |
+| Planner              | `User Request` + `Mode` + Context Map (Full Map) + injected rules; optional `Change Manifest`                    | Full diff content                 |
+| Librarian            | Research query + small relevant snippets + versions                                                              | Full diff content                 |
+| Plan-Reviewer        | `Plan` + `User Request` + optional refs + optional `Change Manifest`                                             | Full diff content                 |
+| Reviewer-Lite        | `User Request` + (`Diff` or `Diff Command`) + optional `Base Ref`/`Head Ref` + `Commit Message` + injected rules | Large non-atomic diffs            |
+| Specialist reviewers | `User Request` + (`Diff` or `Diff Command`) + optional `Base Ref`/`Head Ref` + injected rules                    | Lockfiles and generated artifacts |
+| Lead                 | `Request` + `Mode` + `Context` + optional refs + optional `Change Manifest`; structured outputs in/out           | Full diff by default              |
+
+Tier 2 delivery (preferred):
+
+- For small diffs: inline `Diff`.
+- For large diffs: provide git `Base Ref`, git `Head Ref`, and a ready-to-run `Diff Command` (already filtered).
+
+Canonical commands (examples):
+
+- Commit subjects: `git log --format=%s <base>..<head>`
+- File manifest: `git diff --name-status <base>...<head>`
+- Filtered diff: `git diff --no-color <base>...<head> -- <path1> <path2> ...`
+
+GitHub metadata (when available):
+
+- Include PR title + description for Planner/Lead and specialist reviewers (high signal, low tokens).
+- Include linked issue title + body when referenced (skip long comment threads).
+
+Explorer Context Map routing:
+
+- Explorer outputs a `Summary Map` and `Full Map`.
+- Tools SHOULD feed:
+  - `Summary Map` to Lead and Counsel by default.
+    - The `Summary Map` MUST include `Detected Domains` and `Project Policy Files` (mark one as `Primary`) when available.
+  - `Full Map` to Planner.
+
+### Generated / Auto-Generated Files
+
+Auto-generated diffs are high-token and low-signal.
+Tools SHOULD exclude them from reviewer prompts and rely on deterministic tooling for validation.
+
+Default exclude patterns (starting point):
+
+- Lockfiles: `go.sum`, `package-lock.json`, `yarn.lock`, `bun.lockb`, `pnpm-lock.yaml`, `Cargo.lock`, `Gemfile.lock`, `poetry.lock`, `composer.lock`
+- Common generated markers: files containing `Code generated by` + `DO NOT EDIT`
+- Protobuf/gRPC: `*.pb.go`, `*.pb.ts`, `*_grpc.pb.go`, `*_pb2.py`
+- Go codegen: `*_gen.go`, `*_string.go`, `wire_gen.go`, `mock_*.go`
+- Build output: `dist/`, `build/`, `vendor/` (when committed)
+
+Policy extension:
+
+- If the target repo has a generated-file policy, tools SHOULD apply it to extend/override the defaults.
+- Even when excluded from review prompts, generated files MUST still be validated by build/lint/test commands.
+
+### Three-Level Diff Loading
+
+Tools SHOULD avoid loading the unfiltered full diff upfront.
+Prefer graduated loading:
+
+1. **Commit log** (intent): subjects + bodies.
+2. **File manifest** (scope): `git diff --name-status` (or `--stat` for Planner).
+3. **Filtered diff** (review): only non-generated, human-authored files.
+
+Edge case:
+
+- If all changed files are excluded as generated, specialist reviewers should receive an empty filtered diff and output `LGTM`.
+
+### Per-Reviewer Diff Scoping (Optional)
+
+To keep specialist reviewers focused and reduce token waste, tools MAY provide different filtered diffs per reviewer.
+
+Recommended patterns:
+
+- `@Reviewer-Logic`: exclude test files and documentation-only changes; focus on runtime/production code.
+- `@Reviewer-Test`: include test file diffs; optionally include a cheap file manifest of production changes.
+- `@Reviewer-Quality`: include human-authored diffs; avoid generated artifacts; emphasize docs/maintainability.
+- `@Reviewer-Security`: include boundary-facing code (auth, input parsing, serialization, access control) and config changes.
+- `@Reviewer-Performance`: include suspected hot paths (loops, allocations, DB/query layer, critical IO paths).
+- `@Reviewer-Lite`: include the smallest atomic diff subset + commit message.
+
+If diffs are scoped per reviewer, tools SHOULD still provide a file manifest (Tier 1) so reviewers can detect missing tests
+or review gaps without reading unrelated diffs.
+
+### Per-Reviewer Rule Filtering
+
+Tools MUST NOT inject all selected rules into every reviewer.
+Inject a role-appropriate subset to preserve prompt budget.
+
+Enforcement requirements:
+
+- Tools MUST log which rule IDs were injected into each agent prompt (Planner + each reviewer) for traceability.
+- Tools MUST cap injected rules per reviewer (recommended: <= 10).
+- Tools MUST prefer:
+  1. rules explicitly selected for that reviewer (by tags), then
+  2. Constitution, then
+  3. closest-matching domain laws.
+
+If a tool cannot classify rules by tags, it MUST fall back to injecting only Constitution + the top-N domain rules rather than injecting everything.
+
+### Per-Step Rule Scoping (Builder)
+
+For execution plans, the runtime SHOULD scope Builder rule injection to the current plan step.
+
+- Planner steps SHOULD list `Requirements` as rule IDs (not rule text).
+- When invoking Builder for step N, inject only:
+  - the rules referenced by that step's rule IDs,
+  - plus any mandatory policy rules.
+
+### Counsel Output Contract (JSON)
+
+Counsel MUST return a JSON array of objects:
+
+```json
+[{ "path": "rules/constitution/CONS-00015-safety.md", "reason": "..." }]
+```
+
+Note: the code fence here is documentation-only. The `@Counsel` agent output must be raw JSON (no fences).
+
+Schema (informal):
+
+- Array length: target <= 10 items; hard cap <= 15 items.
+- `path` (string, required): repo-relative path to a rule/policy.
+- `reason` (string, required): why it was selected; may include a re-scan request when Context Map is missing domains.
+- `request` (object, optional): structured runtime request (e.g., `{ "action": "rerun_explorer", "scope": "broader" }`).
+
+JSON Schema (Draft-07 compatible):
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "array",
+  "maxItems": 15,
+  "items": {
+    "type": "object",
+    "required": ["path", "reason"],
+    "additionalProperties": false,
+    "properties": {
+      "path": { "type": "string", "minLength": 1 },
+      "reason": { "type": "string", "minLength": 1 },
+      "request": {
+        "type": "object",
+        "required": ["action"],
+        "additionalProperties": true,
+        "properties": {
+          "action": { "type": "string" },
+          "scope": { "type": "string" }
+        }
+      }
+    }
+  }
+}
+```
+
+Recommended heuristic:
+
+- `@Reviewer-Logic`: prioritize correctness/behavior rules (e.g., `#correctness`, `#behavioral`, `#runtime`).
+- `@Reviewer-Test`: prioritize testing rules (e.g., `#testing`, `#tdd`, `#mocking`, `#isolation`).
+- `@Reviewer-Security`: prioritize security rules (e.g., `#security`, `#secrets`, `#defense`, trust-boundary laws).
+- `@Reviewer-Performance`: prioritize performance rules (e.g., `#performance`, `#efficiency`, `#resources`).
+- `@Reviewer-Quality`: prioritize readability/maintainability rules (e.g., `#readability`, `#maintenance`, `#documentation`).
+
+If no specialist-relevant rules are available, inject only Constitution + the closest matching laws.
+
+Counsel error handling:
+
+- If Counsel returns invalid JSON, treat it as a hard error and fall back to Constitution + default policy.
+- If Counsel returns an empty array, fall back to Constitution + default policy.
+- If a returned `path` does not exist, skip it and log an error; if all paths are missing, fall back to Constitution + default policy.
+
+## 6. Example Flow (Loading a Go Reviewer)
+
+1.  **Detect**: Language is `Go`.
+2.  **Load Index**: Read `rules/laws/go/README.md`.
+3.  **Counsel**: Ask `@Counsel` to select rules. Returns paths.
+    ```json
+    [
+      {
+        "path": "rules/constitution/CONS-00015-safety.md",
+        "reason": "Trust boundary / safety"
+      },
+      { "path": "rules/laws/go/GO-00001-...md", "reason": "Go domain detected" }
+    ]
+    ```
+4.  **Parse Agent**: Read `agents/roles/reviewer/logic.md` and extract `<Meta>` (Capability + RuleRender).
+5.  **Load Rules**: Read the returned `path` files.
+6.  **Strip**: Remove rule headers (everything before `## Definition`).
+7.  **Render**: Apply `RuleRender: trimmed` (strip `## Examples`).
+8.  **Inject**: Replace `{{injected_rules}}` with the rendered rule bodies.
+9.  **Resolve Model**:
+    - Agent `<Meta>` contains `Capability: reasoning`.
+    - Tool loads `models/registry.yaml` and reads `capabilities.reasoning`.
+    - Tool selects the first available model from the list.
+10. **Execute**: Call API.

package/integrate/versioning.md

@@ -0,0 +1,41 @@
+# Versioning
+
+This repository is consumed as a specification database by tools via `integrate/README.md`.
+
+## Current Version
+
+- Repo version: `0.0.4` (see `VERSION`).
+- Integration spec version: `0.0.4` (see `integrate/README.md`).
+
+## How Consumers Pin a Version
+
+Recommended: Git tags + GitHub releases.
+
+```bash
+git tag v0.0.4
+git push origin v0.0.4
+```
+
+Consumers can fetch a tag tarball:
+
+```bash
+curl -L "https://github.com/<owner>/lgtm-specs/archive/refs/tags/v0.0.4.tar.gz" | tar -xz
+
+For this repository, `<owner>` is `yyforyongyu`.
+```
+
+Alternative: git submodule.
+
+```bash
+git submodule add https://github.com/<org>/lgtm-specs.git .lgtm/specs
+git submodule update --init --recursive
+```
+
+## SemVer Policy
+
+This repo is pre-1.0.0; breaking changes are possible in any version bump.
+We still try to follow these targets:
+
+- Patch: doc fixes, indexing fixes, typo fixes.
+- Minor: new rules/agents/models that are additive.
+- Major: breaking changes to `integrate/README.md` contracts.

package/models/README.md

@@ -0,0 +1,68 @@
+# The Intelligence Layer
+
+This directory defines the **Compute Intelligence** strategy for LGTM (2026 Standard).
+
+## The Capability System
+
+Agents request **Capabilities**. This allows for specialization (e.g., using a high-context model for retrieval vs. a reasoning model for planning).
+
+The order of models within each capability list in `models/registry.yaml` is the preference order.
+
+Preference notes:
+
+- Models earlier in each capability list are the preferred defaults (first available wins).
+- Lists are grouped by provider preference order (OpenAI -> Anthropic -> Google -> MiniMax -> MoonshotAI -> Qwen).
+- This ordering encodes org preference and operational experience; it is not a claim of global benchmark rank.
+
+Capability IDs are lowercase keys under `capabilities` (e.g., `reasoning`, `coding`).
+
+### **Reasoning**
+
+- **Role**: Planning, Architecture, Deep Logic, Complex Review.
+- **Capabilities**: Chain-of-thought, multi-step reasoning, low hallucination.
+
+### **Coding**
+
+- **Role**: Implementation, Refactoring, Syntax Correction.
+- **Capabilities**: Strong syntax knowledge, code generation, refactoring patterns.
+
+### **Data**
+
+- **Role**: Retrieval, Context Mapping, Summarization.
+- **Capabilities**: Massive context window (1M+), recall accuracy.
+
+### **Security**
+
+- **Role**: Threat Modeling, Vulnerability Scanning.
+- **Capabilities**: Defensive reasoning, high safety bounds.
+
+### **Docs**
+
+- **Role**: Technical Writing, Release Notes, Stakeholder Comms.
+- **Capabilities**: Structured writing, tone adaptation, empathy.
+
+### **Fast**
+
+- **Role**: Tool Routing, Quick Checks, Formatting.
+- **Capabilities**: Low latency, high throughput, low cost.
+
+### **General**
+
+- **Role**: Fallback when no specialist capability model is available.
+- **Capabilities**: Balanced; must be "good enough" across reasoning + coding + retrieval.
+
+## Usage
+
+Agents specify a **Capability Requirement**. The runtime resolves this to a specific model from `registry.yaml`.
+
+Resolution Rules:
+
+1.  **Check Capability List**: Iterate through the models listed for the requested capability.
+2.  **Availability**: Pick the first model the user has access to (keys configured).
+3.  **Fallback**: If no specialist model is available, fail by default.
+    - Tools MAY fall back to `general` only if they can guarantee the selected model can satisfy the required capability.
+    - Tools MUST emit an explicit warning when using a fallback.
+
+## Contributing
+
+To update the registry, read `contribute/update-models.md`.

package/models/registry.yaml

@@ -0,0 +1,55 @@
+# Updated: 2026-02-08
+# Ordering: earlier models are preferred defaults. Lists are grouped by provider
+# preference order: openai -> anthropic -> google -> minimax -> moonshotai -> qwen.
+
+capabilities:
+  reasoning:
+    - openai/gpt-5.2
+    - anthropic/claude-opus-4.6
+    - anthropic/claude-opus-4.5
+    - google/gemini-3-pro-preview
+    - minimax/minimax-m2.1
+    - moonshotai/kimi-k2.5
+
+  coding:
+    - openai/gpt-5.2-codex
+    - openai/gpt-5.2
+    - anthropic/claude-sonnet-4.5
+    - google/gemini-3-flash-preview
+    - minimax/minimax-m2.1
+    - qwen/qwen3-coder
+
+  data:
+    - openai/gpt-5.2
+    - anthropic/claude-opus-4.6
+    - anthropic/claude-opus-4.5
+    - google/gemini-3-pro-preview
+    - minimax/minimax-m2.1
+    - moonshotai/kimi-k2.5
+
+  security:
+    - openai/gpt-5.2
+    - anthropic/claude-opus-4.6
+    - anthropic/claude-opus-4.5
+    - google/gemini-3-pro-preview
+    - minimax/minimax-m2.1
+
+  docs:
+    - openai/gpt-5.2
+    - anthropic/claude-sonnet-4.5
+    - anthropic/claude-opus-4.5
+    - google/gemini-3-pro-preview
+    - minimax/minimax-m2.1
+
+  fast:
+    - openai/gpt-4o-mini
+    - anthropic/claude-haiku-4.5
+    - google/gemini-3-flash-preview
+    - google/gemini-2.5-flash
+    - minimax/minimax-m2.1
+
+  general:
+    - openai/gpt-5.2
+    - anthropic/claude-sonnet-4.5
+    - google/gemini-3-pro-preview
+    - minimax/minimax-m2.1

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "lgtm-specs",
+  "version": "0.0.4",
+  "description": "Validation and formatting commands for LGTM specs.",
+  "scripts": {
+    "validate": "python3 scripts/validate_specs.py",
+    "format": "bunx prettier --write .",
+    "format:check": "bunx prettier --check .",
+    "check": "bun run validate && bun run format:check"
+  }
+}