ouroboros-ai 0.40.2.dev20__tar.gz → 0.40.2.dev22__tar.gz

{ouroboros_ai-0.40.2.dev20 → ouroboros_ai-0.40.2.dev22}/.claude-plugin/SKILL_CAPABILITY_GUIDE.md

@@ -9,6 +9,9 @@ Use the runtime's local file search/read tools and prefer exact repository evide
 ### When a skill requires `call_mcp`
 Call available Ouroboros MCP tools through the runtime's MCP/tool surface instead of emulating MCP workflows manually.
 
+### When a skill requires `run_lateral_review`
+When an interview response marks `lateral_review_required=true`, call `ouroboros_lateral_think` with the supplied `lateral_review_tool_args` before routing the next interview turn. When directly synthesizing an answer for the user, run researcher, contrarian, and simplifier perspectives first, then collapse the result into concise choices or a recommended draft.
+
 ### When a skill requires `web_research`
 Use the runtime's web/search capability only when current external facts are required, and cite the sources used.
 

{ouroboros_ai-0.40.2.dev20 → ouroboros_ai-0.40.2.dev22/.claude-plugin}/skills/interview/SKILL.md

@@ -17,6 +17,7 @@ Socratic interview to crystallize vague requirements into clear specifications.
 - `ask_user` — ask human-judgment questions through the active runtime's user-question surface.
 - `inspect_code` — answer repo-local factual questions from exact local files before asking the user.
 - `call_mcp` — use Ouroboros MCP tools for persistent interview state and seed generation.
+- `run_lateral_review` — invoke lateral thinking subagents before milestone turns and direct-answer synthesis.
 - `web_research` — fetch current external facts only when the interview genuinely depends on them.
 - `run_shell` — run bounded local commands for version checks and repository inspection.
 - `refine_answer` — confirm structured interpretations of free-text answers before forwarding them.
@@ -149,18 +150,52 @@ MCP (question generator) ←→ You (answerer + router) ←→ User (human judgm
    `last_question` is required on this path so MCP can persist the real
    transcript even though the parent session generated the question.
 
-   **Milestone lateral-review advisory**:
+   **Milestone lateral-review dispatch**:
    If an MCP response includes `meta.lateral_review_recommended=true`, treat it
-   as a non-blocking cue that the interview just crossed an ambiguity milestone
-   such as `initial -> progress`, `progress -> refined`, or `refined -> ready`.
-   The MCP tool is still only a question generator; it has not run lateral
-   personas, blocked the interview, or changed requirements. Before answering
-   the returned question, the main session may run `ooo lateral` / the
-   `ouroboros_lateral_think` MCP surface to inspect hidden assumptions for the
-   named `meta.lateral_review_milestone`, then fold only concrete, user-safe
-   findings into the next answer or user question. If lateral tooling is
-   unavailable or unnecessary, continue with the returned question; do not
-   restart the interview.
+   as a required lightweight subagent review for that turn. The interview just
+   crossed an ambiguity milestone such as `initial -> progress`,
+   `progress -> refined`, or `refined -> ready`, which is exactly when hidden
+   assumptions tend to matter.
+
+   Before answering or asking the returned question:
+   - Tell the user briefly that a few perspectives are checking the question.
+   - Call `ouroboros_lateral_think` with `meta.lateral_review_tool_args` when
+     present. If only the legacy advisory fields are present, call it with
+     `personas=["researcher","contrarian","simplifier"]`, a problem context
+     containing the current interview session/milestone/question, and a current
+     approach describing the next interview-routing decision.
+   - Fold only concrete, user-safe findings into the next answer or user
+     question. Do not present every subagent note as a report.
+   - If lateral tooling is unavailable, continue the interview and say the
+     review could not be run; do not restart the interview.
+
+   The MCP interview tool is still the question generator and source of
+   persistent state. Lateral review is a main-session assist layer: it helps the
+   user feel supported, but it does not by itself change requirements or mark the
+   interview complete.
+
+   **Main-session direct-answer assistance**:
+   Use lateral review frequently when the main session would otherwise answer
+   the MCP question directly or compress the user's free-text into a decision.
+   This is the supported "deep research style" experience for interviews: the
+   user should see that multiple perspectives are helping, while the final
+   prompt stays easy to answer.
+
+   Trigger a lightweight `ouroboros_lateral_think` call before continuing when
+   any of these are true:
+   - You are about to synthesize a product/UX/architecture answer from partial
+     user input.
+   - The question asks for tradeoffs, priorities, non-goals, risk, success
+     criteria, or rollout strategy.
+   - The factual code answer is lower confidence than an exact config/manifest
+     match.
+   - The user seems busy, uncertain, terse, or likely to benefit from selectable
+     options instead of another open-ended question.
+
+   Prefer `personas=["researcher","contrarian","simplifier"]` for this
+   assist. Add `architect` when the answer changes system shape or ownership.
+   Summarize the result as 2-3 concrete options or one recommended answer draft,
+   then let the user approve, tweak, or switch to auto.
 
    **PATH 1 — Code Answer** (describe current state from codebase):
    When the question asks about existing tech stack, frameworks, dependencies,

{ouroboros_ai-0.40.2.dev20 → ouroboros_ai-0.40.2.dev22}/CONTRIBUTING.md

@@ -15,6 +15,7 @@ Thank you for your interest in contributing to Ouroboros! This guide covers ever
 - [Documentation Coverage](#documentation-coverage)
   - [CLI Commands → Doc Mapping](#cli-commands--doc-mapping)
   - [Orchestrator → Doc Mapping](#orchestrator--doc-mapping)
+  - [Capability Graph → Doc Mapping](#capability-graph--doc-mapping)
   - [Configuration → Doc Mapping](#configuration--doc-mapping)
   - [Evaluation Pipeline → Doc Mapping](#evaluation-pipeline--doc-mapping)
   - [TUI Source → Doc Mapping](#tui-source--doc-mapping)
@@ -600,7 +601,24 @@ Changes under `src/ouroboros/orchestrator/` affect runtime behavior documentatio
 | `command_dispatcher.py` | `docs/architecture.md` — command dispatch model |
 | `level_context.py` | `docs/architecture.md` — level context description |
 
-**Runtime availability rule**: If `create_agent_runtime()` raises `NotImplementedError` for a backend, that backend **must not** appear in docs as a working option. All three backends (`claude`, `codex`, `opencode`) are fully implemented and documented.
+**Runtime availability rule**: If `create_agent_runtime()` raises `NotImplementedError` for a backend, that backend **must not** appear in docs as a working option. Runtime backend availability is registry-owned; when `runtime_backend_choices()` or setup support changes, update the runtime capability matrix, setup docs, and per-runtime guide/gap documentation together.
+
+---
+
+### Capability Graph → Doc Mapping
+
+Changes that add, remove, rename, or reinterpret a skill execution capability
+must keep the capability graph and generated runtime instructions in sync.
+
+| Source path | Must update |
+|-------------|-------------|
+| `skills/*/SKILL.md` | `docs/runtime-guides/skill-capability-guides.md` if `required_capabilities` changes or the skill depends on a new abstract runtime action |
+| `src/ouroboros/backends/capabilities.py` | `docs/runtime-guides/skill-capability-guides.md`; renderer/package snapshot tests for Codex, Hermes, Claude, and setup-owned runtime artifacts |
+| `src/ouroboros/runtime_instruction_artifacts.py` | `docs/runtime-guides/skill-capability-guides.md`; `docs/cli-reference.md` setup section if install paths or managed surfaces change |
+| Packaged guide snapshots such as `.claude-plugin/SKILL_CAPABILITY_GUIDE.md` | Update when `render_backend_skill_capability_guide(<backend>)` output changes |
+
+Before submitting a capability graph PR, run the checklist in
+[`docs/runtime-guides/skill-capability-guides.md`](./docs/runtime-guides/skill-capability-guides.md#contributor-checklist-for-capability-changes).
 
 ---
 
@@ -668,7 +686,7 @@ Changes under `skills/` (YAML skill definitions used by Claude and Codex) or `sr
 | Source path | Must update |
 |-------------|-------------|
 | `skills/codex.md` | `docs/runtime-guides/codex.md` — if skill instructions change |
-| `skills/*.yaml` or `src/ouroboros/agents/*.md` | `docs/` guide that describes the affected skill/agent behaviour |
+| `skills/*.yaml`, `skills/*/SKILL.md`, or `src/ouroboros/agents/*.md` | `docs/` guide that describes the affected skill/agent behaviour; `docs/runtime-guides/skill-capability-guides.md` if required capabilities change |
 | `src/ouroboros/plugin/skills/executor.py` | `docs/architecture.md` — skill execution model |
 | `src/ouroboros/plugin/agents/registry.py` | `docs/architecture.md` — agent registry; `docs/runtime-capability-matrix.md` if supported agents change per runtime |
 

{ouroboros_ai-0.40.2.dev20 → ouroboros_ai-0.40.2.dev22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ouroboros-ai
-Version: 0.40.2.dev20
+Version: 0.40.2.dev22
 Summary: Specification-first workflow engine for AI coding agents. Works with Claude Code and Codex CLI.
 Author-email: Q00 <jqyu.lee@gmail.com>
 License-File: LICENSE

{ouroboros_ai-0.40.2.dev20 → ouroboros_ai-0.40.2.dev22}/docs/cli-reference.md

@@ -268,7 +268,7 @@ ouroboros setup --non-interactive
 
 **What setup does:**
 
-- Scans PATH for `claude`, `codex`, `opencode`, `hermes`, `gemini`, and `kiro-cli` CLI binaries
+- Scans PATH for `claude`, `codex`, `opencode`, `hermes`, `gemini`, `kiro-cli`, `copilot`, and `goose` CLI binaries
 - Prompts you to select a runtime if multiple are found (or auto-selects if only one)
 - Writes `orchestrator.runtime_backend` to `~/.ouroboros/config.yaml`
 - For Claude Code: registers the MCP server in `~/.claude/mcp.json`
@@ -279,7 +279,11 @@ ouroboros setup --non-interactive
 - For Codex CLI: installs managed `~/.codex/ouroboros-*.config.toml` profile-v2 anchors on current Codex releases, or legacy `[profiles.ouroboros-*]` anchors when the detected CLI still requires them
 - For OpenCode: registers the Ouroboros MCP server in OpenCode's configuration
 - For OpenCode (plugin mode): installs the bridge plugin into `<opencode_config_dir>/plugins/ouroboros-bridge/`
+- For OpenCode: installs the runtime skill capability guide into global `AGENTS.md` in the active OpenCode config directory
+- For Gemini CLI: installs the runtime skill capability guide into `~/.gemini/GEMINI.md`
 - For Kiro CLI: sets `orchestrator.kiro_cli_path` and `llm.backend: kiro` in `~/.ouroboros/config.yaml`, and registers the Ouroboros MCP server in `~/.kiro/settings/mcp.json` with `OUROBOROS_RUNTIME=kiro` / `OUROBOROS_LLM_BACKEND=kiro` baked into the entry's `env` so `ooo <skill>` shortcuts route to the Kiro adapter on the very next `kiro-cli chat`. The detector prefers the resolved `ouroboros` binary over `uvx` to stay within Kiro's MCP init timeout
+- For Kiro CLI: installs the runtime skill capability guide into `~/.kiro/steering/ouroboros-skill-capability-guide.md`
+- For Copilot CLI: installs the runtime skill capability guide into `~/.copilot/ouroboros-instructions/AGENTS.md` and configures Ouroboros-launched Copilot child sessions to read it via `COPILOT_CUSTOM_INSTRUCTIONS_DIRS`
 
 > **Codex config split:** put persistent Ouroboros per-role model overrides in `~/.ouroboros/config.yaml` (`clarification.default_model`, `llm.qa_model`, `evaluation.semantic_model`, `consensus.models`, `consensus.advocate_model`, `consensus.devil_model`, `consensus.judge_model`). `~/.codex/config.toml` is only the Codex MCP/env hookup file used by setup on current Codex releases; profile anchors live in `~/.codex/<profile>.config.toml`. If you run a long-lived URL-based Ouroboros MCP server, setup preserves that user-managed entry in the default `--mcp-mode auto`; use `--mcp-mode stdio` only when you intentionally want setup to replace it.
 

{ouroboros_ai-0.40.2.dev20 → ouroboros_ai-0.40.2.dev22}/docs/contributing/key-patterns.md

@@ -223,6 +223,30 @@ seed.goal = "Different goal"  # ValidationError: frozen
 - The ontology can evolve with consensus, but direction fields cannot
 - Use `seed.to_dict()` / `Seed.from_dict()` for serialization
 
+## 8. Capability Graph for Skill Execution
+
+Skills declare abstract runtime needs; runtime adapters translate those needs
+through the capability graph.
+
+**Location**: `src/ouroboros/backends/capabilities.py`
+
+```python
+SkillExecutionCapability(
+    name="run_lateral_review",
+    guidance=(
+        "When an interview response marks `lateral_review_required=true`, "
+        "call `ouroboros_lateral_think` with the supplied tool args before "
+        "routing the next interview turn."
+    ),
+)
+```
+
+**Rules**:
+- Keep `SKILL.md` capability names runtime-neutral
+- Put runtime-specific tool names and prompt wording inside `SkillExecutionCapability.guidance`
+- Regenerate or update setup-owned instruction artifacts when rendered guide output changes
+- Follow `docs/runtime-guides/skill-capability-guides.md` before merging capability changes
+
 ## Summary Table
 
 | Pattern | When to Use | Key File |
@@ -234,3 +258,4 @@ seed.goal = "Different goal"  # ValidationError: frozen
 | Three-stage eval | Artifact verification | `evaluation/pipeline.py` |
 | TUI SSOT | UI state management | `tui/app.py`, `tui/events.py` |
 | Seed immutability | Workflow specification | `core/seed.py` |
+| Capability graph | Runtime-specific skill execution | `backends/capabilities.py` |

{ouroboros_ai-0.40.2.dev20 → ouroboros_ai-0.40.2.dev22}/docs/runtime-guides/copilot.md

@@ -45,6 +45,7 @@ ouroboros setup --runtime copilot
 #   - calls https://api.githubcopilot.com/models with your gh token
 #   - prints the live model list and lets you pick a default
 #   - writes ~/.ouroboros/config.yaml + ~/.copilot/mcp-config.json
+#   - installs ~/.copilot/ouroboros-instructions/AGENTS.md for Ouroboros runs
 
 # 4. Restart your Copilot session, then use ooo skills
 copilot
@@ -64,6 +65,11 @@ This means non-PATH installs (for example, a winget or scoop install on
 Windows that lands the binary outside `$PATH`) work without modifying
 shell init.
 
+Ouroboros-launched Copilot child sessions append the setup-owned
+`~/.copilot/ouroboros-instructions` directory to
+`COPILOT_CUSTOM_INSTRUCTIONS_DIRS` using Copilot CLI's comma-separated list
+format. Existing custom instruction directories are preserved.
+
 ## Live model discovery
 
 `ouroboros setup --runtime copilot` always queries the live model catalog

ouroboros_ai-0.40.2.dev22/docs/runtime-guides/skill-capability-guides.md

@@ -0,0 +1,111 @@
+# Runtime Skill Capability Guides
+
+Issue #1008 moves runtime-specific skill execution guidance out of individual
+`SKILL.md` files and into the backend capability registry. Runtime adapters then
+consume the rendered guide through the instruction surface they actually own.
+
+## Capability graph contract
+
+The capability graph is the source of truth that maps abstract skill needs to
+runtime-specific tool names, prompt instructions, and unsupported behavior.
+
+```
+SKILL.md required capabilities
+    -> src/ouroboros/backends/capabilities.py
+    -> render_backend_skill_capability_guide(<backend>)
+    -> runtime-owned instruction artifact
+    -> runtime session behavior
+```
+
+`SKILL.md` files should describe what a skill needs in runtime-neutral terms
+such as `run_lateral_review`. They should not name a specific runtime's prompt
+file, CLI flag, or tool spelling unless the skill is explicitly runtime-scoped.
+Backend-specific wording belongs in `SkillExecutionCapability` entries in
+`src/ouroboros/backends/capabilities.py`.
+
+When the graph changes, contributors must update every generated or
+setup-owned surface that exposes the graph. A capability added only to a
+`SKILL.md` is not shipped until a maintained runtime can discover it through
+its rendered guide or a documented fallback.
+
+## Current coverage
+
+| Runtime | Generated artifact surface | Status |
+| --- | --- | --- |
+| Codex | Managed rule under `~/.codex/rules/ouroboros.md` | Installed during Codex setup/update via the generated guide renderer. |
+| Hermes | `~/.hermes/skills/autonomous-ai-agents/ouroboros/SKILL_CAPABILITY_GUIDE.md` | Installed with the Hermes skill bundle. |
+| Claude | `.claude-plugin/SKILL_CAPABILITY_GUIDE.md` | Shipped with the Claude plugin package and checked against the renderer. |
+| OpenCode | Global `AGENTS.md` in the active OpenCode config directory | Installed by OpenCode setup for plugin and subprocess modes. |
+| Gemini | `~/.gemini/GEMINI.md` | Installed by Gemini setup as a managed section in the global Gemini memory file. |
+| Kiro | `~/.kiro/steering/ouroboros-skill-capability-guide.md` | Installed by Kiro setup as a global steering file. |
+| Copilot | `~/.copilot/ouroboros-instructions/AGENTS.md` | Installed by Copilot setup; Ouroboros Copilot runtime also injects that directory through `COPILOT_CUSTOM_INSTRUCTIONS_DIRS`. |
+| Goose | No setup-owned capability artifact yet | Known gap: setup can select Goose as a runtime, but no durable Goose instruction surface or Goose-specific `SkillExecutionCapability` entries are registered yet. Keep skill requirements runtime-neutral and rely on runtime-local operator guidance until a Goose artifact installer exists. |
+| Pi | No setup-owned capability artifact yet | Known gap: Pi has generic rendered capability guidance in the registry, but setup does not yet install it into a durable Pi-owned instruction artifact. Use `render_backend_skill_capability_guide("pi")` when building Pi prompts until a stable artifact surface exists. |
+
+## Seed generation client-gate enforcement
+
+`ouroboros_generate_seed` always reports `required_client_gates`,
+`accepted_client_gates`, and `missing_client_gates` metadata so runtimes can
+confirm that the Seed-ready Acceptance Guard and Restate gate ran before seed
+generation. By default, missing gates remain warnings for compatibility with
+existing clients. Set `OUROBOROS_REQUIRE_CLIENT_GATES=1` to promote missing
+gates to a hard MCP precondition while migrating maintained clients to pass the
+`client_gates` acknowledgements.
+
+## Fallback behavior for new runtimes without generated artifacts
+
+When adding a new runtime that does not yet have a durable instruction surface
+owned by `ouroboros setup`, clients should render
+`render_backend_skill_capability_guide(<backend>)` when building prompts or
+user-facing setup guidance, but must not copy long adapter sections into
+individual `SKILL.md` files.
+
+The fallback for new runtimes should stay conservative:
+
+1. Keep `SKILL.md` files runtime-neutral.
+2. Keep backend-specific execution wording in `src/ouroboros/backends/capabilities.py`.
+3. Add an installer only when the runtime has a stable, documented artifact
+   surface that setup can refresh idempotently.
+4. If no such surface exists, document the gap here and rely on the generic
+   backend guide until the runtime integration grows one.
+
+## Contributor checklist for capability changes
+
+Use this checklist when a PR adds, removes, renames, or materially changes an
+abstract capability used by any skill.
+
+1. Update the relevant `SKILL.md` `required_capabilities` or instructions using
+   runtime-neutral capability names.
+2. Update `src/ouroboros/backends/capabilities.py` with the matching
+   `SkillExecutionCapability` entries for every maintained backend.
+3. Update any setup-owned or packaged instruction artifacts that are checked in,
+   such as `.claude-plugin/SKILL_CAPABILITY_GUIDE.md`, when renderer output
+   changes.
+4. Update this document when a runtime's generated artifact surface changes or a
+   backend has a known gap.
+5. Add or update tests that prove the rendered guide and installed artifacts
+   contain the capability.
+
+Recommended targeted checks:
+
+```bash
+uv run pytest -q \
+  tests/unit/backends/test_capabilities.py \
+  tests/unit/test_runtime_skill_capability_docs.py \
+  tests/unit/test_runtime_instruction_artifacts.py \
+  tests/unit/test_claude_plugin_skill_guide.py \
+  tests/unit/test_codex_artifacts.py::TestInstallCodexRules::test_packaged_rules_include_rendered_skill_capability_guide \
+  tests/unit/hermes/test_artifacts.py
+```
+
+## Adding a new runtime artifact
+
+When a runtime gains a stable rule/skill/plugin instruction surface:
+
+1. Add or refine its `SkillExecutionCapability` entries in
+   `backends.capabilities`.
+2. Consume `render_backend_skill_capability_guide("<backend>")` from the
+   runtime installer or package artifact.
+3. Add an artifact test that proves setup/package output contains the rendered
+   guide and does not duplicate generated sections on refresh.
+4. Update the coverage table above.