Docs: Updated ADRs and referenced them from the specification

docs/adr/ADR-012-skill-system.md

@@ -0,0 +1,113 @@
+# ADR-012: Skill System
+
+**Status:** Accepted
+**Date:** 2026-02-16
+**Supersedes:** None
+**Related ADRs:** ADR-002, ADR-010, ADR-011, ADR-013
+
+## Context
+
+Actors need curated sets of tools to perform their roles — a code execution actor needs file operations, git tools, and test runners; a DevOps actor needs infrastructure provisioning and deployment tools. Assigning tools individually to each actor would be repetitive, error-prone, and difficult to maintain. The system needs an organizational unit that groups related tools into reusable, composable collections.
+
+## Decision
+
+A **skill** is a namespaced, reusable collection of tools that serves as the organizational layer between individual tools and actors. Skills are defined in YAML, support hierarchical composition through skill-includes, and are flattened into a unified tool set when referenced by an actor.
+
+## Design
+
+### Skill Definition
+
+Skills are defined in YAML configuration files and managed via `agents skill` CLI commands. A skill configuration includes:
+
+- **`name`**: Namespaced identifier (e.g., `local/devops-toolkit`).
+- **`tools`**: Named tool references (by namespace/name from the Tool Registry), with optional metadata overrides.
+- **`includes`**: References to other skills, with optional per-tool overrides.
+- **`mcp_servers`**: MCP server configurations, with optional per-tool overrides.
+- **`agent_skills`**: Agent Skills (SKILL.md) references.
+- **`builtins`**: Built-in tool group references (e.g., `file_operations`, `git_operations`).
+- **`anonymous_tools`**: Inline tool definitions scoped to this skill only.
+
+### Skill / Tool Distinction
+
+**Tools** are independently registered atomic operations with their own name, YAML, source, capability metadata, and lifecycle.
+
+**Skills** are organizational units. They group named tool references, anonymous inline tools, child skill includes, and source-specific tool collections (MCP, Agent Skills, builtins). A skill has no execution logic of its own — it is purely a composition mechanism.
+
+When an actor references a skill, it gains the **flattened set** of all tools from that skill and its transitive includes.
+
+### Hierarchical Composition
+
+Skills can include other skills, forming a hierarchy:
+
+```
+local/full-stack-dev
+  ├── local/file-ops (builtins: file_operations, directory_operations)
+  ├── local/code-analysis (MCP: semgrep-server, custom: local/ast-parser)
+  ├── local/testing (custom: local/run-pytest, local/coverage-check)
+  └── local/devops-toolkit
+      ├── local/docker-tools (MCP: docker-server)
+      └── local/deploy (custom: local/helm-deploy)
+```
+
+The flattened tool set is the union of all tools across the entire hierarchy.
+
+### Name Conflict Resolution
+
+When the same tool name appears in multiple included skills, conflicts are resolved by qualification: `<skill_name>.<tool_name>`. This ensures unambiguous tool references even in complex composition hierarchies.
+
+### Metadata Overrides at Inclusion
+
+When a skill includes another skill or references a named tool, it can override `capability` and `description` metadata at the point of inclusion. Overrides are shallow-merged, never persist back to the source, and cannot override schema or built-in metadata.
+
+### Tool Source Integration
+
+Skills integrate tools from all four sources:
+
+- **Named tools**: Reference registered tools by name from the Tool Registry.
+- **MCP servers**: Declare MCP server configurations; all tools exposed by the server are included.
+- **Agent Skills**: Reference SKILL.md files; tools described in frontmatter are included.
+- **Built-ins**: Reference built-in tool groups by name (e.g., `file_operations`).
+- **Anonymous tools**: Define inline tools scoped to this skill only.
+
+### Skill Access Policy
+
+Actors specify a `skill_access_policy` that controls which skills they can use. This enables restricting an actor to a specific set of capabilities (e.g., a read-only review actor should not have access to write-capable skills).
+
+## Constraints
+
+- Circular skill includes are forbidden. The include graph must be a DAG.
+- Tool name conflicts across included skills must be resolved by qualification.
+- Skills do not have execution logic — they are purely organizational.
+- Anonymous tools defined in a skill are scoped to that skill only and are not registered in the Tool Registry.
+- Skill names follow the namespace system (`[[server:]namespace/]name`).
+
+## Consequences
+
+### Positive
+- Reusable skill definitions eliminate repetitive tool assignment across actors.
+- Hierarchical composition enables building complex capability sets from simple, focused skills.
+- The flattening model ensures actors always see a flat tool set, regardless of how deeply the skill hierarchy is nested.
+- MCP, Agent Skill, built-in, and custom tools are composed uniformly through the skill layer.
+
+### Negative
+- Deep skill hierarchies can make it difficult to determine which tools an actor actually has access to without inspecting the full transitive closure.
+- Metadata overrides at multiple inclusion points can create confusion about the effective metadata for a tool.
+- The qualification mechanism for name conflicts (`<skill_name>.<tool_name>`) produces verbose tool names.
+
+### Risks
+- Large flattened tool sets may exceed LLM context window limits, degrading tool-calling accuracy.
+- Skill hierarchy changes (adding or removing tools from a shared skill) have cascading effects on all actors that reference it.
+
+## Alternatives Considered
+
+**Direct tool assignment to actors (no skill layer)** — Simpler but does not scale. Actors performing similar roles would have redundant tool lists, and changes to tool sets would require updating every affected actor individually.
+
+**Dynamic tool selection (LLM chooses tools from the full registry)** — Removes the curation benefit. Without curated skill sets, the LLM must choose from the entire tool registry, which is both a security risk (access to tools it should not have) and a quality risk (too many irrelevant tools in the prompt).
+
+## Compliance
+
+- **Cycle detection**: Skill registration validates that includes do not introduce cycles.
+- **Flattening tests**: Unit tests verify that hierarchically composed skills produce the correct flattened tool set, including conflict resolution.
+- **Override tests**: Tests verify that metadata overrides at inclusion points are applied correctly and do not persist back to the source.
+- **Access policy tests**: Tests verify that actor skill access policies correctly restrict the available tool set.
+- **BDD scenarios**: Behave features exercise actors using hierarchically composed skills across all tool sources.