opencode-swarm 7.28.3 → 7.29.0

package/README.md

@@ -538,469 +538,69 @@ All tools run locally. No Docker, no network calls.
 
 ### Context Budget Guard
 
-Monitors how much context Swarm injects to prevent overflow:
-
-- **Warning threshold (70%)** — Advisory when context reaches ~2800 tokens
-- **Critical threshold (90%)** — Alert at ~3600 tokens with `/swarm handoff` recommendation
-- **Non-nagging** — One-time alerts per session
-
-Disable entirely with `context_budget.enabled: false`.
-
-### File Locking for Concurrent Safety
-
-Hard lock on `plan.json` (serialized writes), advisory lock on `events.jsonl` (append-only log). Stale locks auto-expire via `proper-lockfile`.
-
-### Agent Categories
+The Context Budget Guard monitors how much context Swarm is injecting into the conversation. It helps prevent context overflow before it becomes a problem.
 
-Agents are classified into four categories for the monitor server `/metadata` endpoint:
+### Default Behavior
 
-| Category | Agents |
-|----------|--------|
-| `orchestrator` | architect |
-| `pipeline` | explorer, coder, test_engineer |
-| `qa` | reviewer, critic, critic_sounding_board, critic_drift_verifier |
-| `support` | sme, docs, designer |
+- **Enabled automatically** — No setup required. Swarm starts tracking context usage right away.
+- **What it measures** — Only the context that Swarm injects (plan, context, evidence, retrospectives). It does **not** count your chat history or the model's responses.
+- **Warning threshold (0.7 ratio)** — When swarm-injected context reaches ~2800 tokens (70% of 4000), the architect receives a one-time advisory warning. This is informational — execution continues normally.
+- **Critical threshold (0.9 ratio)** — When context reaches ~3600 tokens (90% of 4000), the architect receives a critical alert with a recommendation to run `/swarm handoff`. This is also one-time only.
+- **Non-nagging** — Alerts fire once per session, not repeatedly. You won't be pestered every turn.
+- **Who sees warnings** — Only the architect receives these warnings. Other agents are unaware of the budget.
 
-Use `getAgentCategory(agentName)` from `src/config/agent-categories.ts` to resolve an agent's category at runtime.
+To disable entirely, set `context_budget.enabled: false` in your swarm config.
 
 ---
 
-<details>
-<summary><strong>Full Execution Pipeline (Technical Detail)</strong></summary>
-
-### The Pipeline
-
-Every task goes through this sequence. No exceptions, no overrides.
-
-```
-MODE: EXECUTE (per task)
-│
-├── 5a. @coder implements (ONE task only)
-├── 5b. diff + imports (contract + dependency analysis + semantic diff context)
-│       └── @system-enhancer injects AST-based semantic diff summary with blast radius
-│           into @reviewer context (up to 10 files, conditional on declared scope)
-├── 5c. syntax_check (parse validation)
-├── 5d. placeholder_scan (catches TODOs, stubs, incomplete code)
-├── 5e. lint fix → lint check
-├── 5f. build_check (does it compile?)
-├── 5g. pre_check_batch (4 parallel: lint, secretscan, SAST, quality budget)
-├── 5h. @reviewer (correctness pass)
-├── 5i. @reviewer (security pass, if security-sensitive files changed)
-├── 5j. @test_engineer (verification tests + coverage ≥70%)
-├── 5k. @test_engineer (adversarial tests)
-├── 5l. architect regression sweep (scope:"graph" to find cross-task test regressions)
-├── 5l-ter. test drift detection (conditional — fires when changes involve command behaviour,
-│         parsing/routing logic, user-visible output, public contracts, assertion-heavy areas,
-│         or helper lifecycle changes; validates tests still align with current behaviour)
-├── 5m. ⛔ Pre-commit checklist (all 4 items required, no override)
-└── 5n. Task marked complete, evidence written
-```
-
-If any step fails, the coder gets structured feedback and retries. After 5 failures on the same task, it escalates to you.
-
-### Architect Workflow Modes
-
-The architect moves through these modes automatically:
-
-| Mode | What It Means |
-|---|---|
-| `RESUME` | Existing `.swarm/` state was found, so Swarm continues where it left off |
-| `CLARIFY` | Swarm asks for missing information it cannot infer |
-| `DISCOVER` | Explorer scans the codebase; co-change dark matter analysis runs automatically to detect hidden file couplings (v6.41) |
-| `CONSULT` | SME agents provide domain guidance |
-| `PLAN` | Architect writes or updates the phased plan (includes CODEBASE REALITY CHECK on brownfield projects) |
-| `CRITIC-GATE` | Critic reviews the plan before execution |
-| `EXECUTE` | Tasks are implemented one at a time through the QA pipeline |
-| `PHASE-WRAP` | A phase closes out, including: explorer rescan, docs update, `context.md` update, `write_retro`, evidence check, `sbom_generate`, **`@critic_drift_verifier` delegation** (drift check — blocking gate), `write_drift_evidence` call with verdict, mandatory gate evidence verification (`completion-verify.json` + `drift-verifier.json` both required), then `phase_complete` |
-
-> **CODEBASE REALITY CHECK (v6.29.2):** Before any planning, the Architect dispatches Explorer to verify the current state of every referenced item. Produces a CODEBASE REALITY REPORT with statuses: NOT STARTED, PARTIALLY DONE, ALREADY COMPLETE, or ASSUMPTION INCORRECT. This prevents planning against stale assumptions. Skipped for greenfield projects with no existing codebase references.
-
-> **Phase Completion Gates (v6.33.4):** Before a phase can be marked complete, two mandatory gates are enforced: (1) completion-verify — deterministic check that plan task identifiers exist in source files, and (2) critic_drift_verifier evidence — verification that the drift verifier approved the implementation. Both gates are automatically bypassed when turbo mode is active.
-
-### Important
-
-A second or later run does **not** necessarily look like a first run.
-
-If `.swarm/plan.md` already exists, the architect may enter `RESUME` and then go directly into `EXECUTE`. That is expected and does **not** mean Swarm stopped using agents.
-
-Use `/swarm status` if you are unsure what Swarm is doing.
-
-Release automation uses release-please and requires conventional commit prefixes such as `fix:` or `feat:` on changes merged to `main`.
-
-</details>
-
-<details>
-<summary><strong>Persistent Memory (What's in .swarm/)</strong></summary>
-
-### plan.md: Your Project Roadmap
-
-```markdown
-# Project: Auth System
-Current Phase: 2
-
-## Phase 1: Foundation [COMPLETE]
-- [x] Task 1.1: Create user model [SMALL]
-- [x] Task 1.2: Add password hashing [SMALL]
-- [x] Task 1.3: Database migrations [MEDIUM]
-
-## Phase 2: Core Auth [IN PROGRESS]
-- [x] Task 2.1: Login endpoint [MEDIUM]
-- [ ] Task 2.2: JWT generation [MEDIUM] (depends: 2.1) ← CURRENT
-  - Acceptance: Returns valid JWT with user claims, 15-minute expiry
-  - Attempt 1: REJECTED — missing expiration claim
-- [ ] Task 2.3: Token validation middleware [MEDIUM]
-```
-
-### context.md: What's Been Decided
-
-```markdown
-## Technical Decisions
-- bcrypt cost factor: 12
-- JWT TTL: 15 minutes; refresh TTL: 7 days
-
-## SME Guidance (cached, never re-asked)
-### security (Phase 1)
-- Never log tokens or passwords
-- Rate-limit login: 5 attempts / 15 min per IP
-
-### api (Phase 1)
-- Return 401 for invalid credentials (not 404)
-```
-
-### Evidence Bundles
-
-Every completed task writes structured evidence to `.swarm/evidence/`:
-
-| Type | What It Captures |
-|------|--------------------|
-| review | Verdict, risk level, specific issues |
-| test | Pass/fail counts, coverage %, failure messages |
-| diff | Files changed, additions/deletions |
-| retrospective | Phase metrics, lessons learned, error taxonomy classification (injected into next phase) |
-| secretscan | Secret scan results: findings count, files scanned, skipped files (v6.33) |
-| completion-verify | Deterministic gate: verifies plan task identifiers exist in source files (written automatically by `completion-verify` tool; required before `phase_complete`) |
-| drift-verifier | Phase-close drift gate: `critic_drift_verifier` verdict (APPROVED/NEEDS_REVISION) and summary (written by architect via `write_drift_evidence`; required before `phase_complete`) |
-
-### telemetry.jsonl: Session Observability
-
-Swarm emits structured JSONL events to `.swarm/telemetry.jsonl` for observability tooling (dashboards, alerting, audit logs). Events are fire-and-forget — failures never affect execution.
-
-```json
-{"timestamp":"2026-03-25T14:30:00.000Z","event":"session_started","sessionId":"abc123","agentName":"architect"}
-{"timestamp":"2026-03-25T14:30:05.000Z","event":"delegation_begin","sessionId":"abc123","agentName":"coder","taskId":"1.1"}
-{"timestamp":"2026-03-25T14:31:00.000Z","event":"delegation_end","sessionId":"abc123","agentName":"coder","taskId":"1.1","result":"success"}
-{"timestamp":"2026-03-25T14:31:10.000Z","event":"gate_passed","sessionId":"abc123","gate":"reviewer","taskId":"1.1"}
-{"timestamp":"2026-03-25T14:32:00.000Z","event":"phase_changed","sessionId":"abc123","oldPhase":1,"newPhase":2}
-```
-
-| Event | When Emitted |
-|-------|-------------|
-| `session_started` | New agent session created |
-| `session_ended` | Session ends (reason: normal, timeout, error) |
-| `agent_activated` | Agent identity confirmed via chat.message |
-| `delegation_begin` | Task dispatched to a sub-agent |
-| `delegation_end` | Sub-agent returns (success, rejected, error) |
-| `task_state_changed` | Task workflow state transitions |
-| `gate_passed` | Evidence written to `.swarm/evidence/{taskId}.json` |
-| `gate_failed` | Gate check blocked task completion |
-| `phase_changed` | Phase completed and new phase started |
-| `budget_updated` | Context budget crossed warning/critical threshold |
-| `hard_limit_hit` | Tool call/duration/repetition limit reached |
-| `revision_limit_hit` | Coder revision limit exceeded |
-| `loop_detected` | Repetitive tool call pattern detected |
-| `scope_violation` | Architect wrote outside declared scope |
-| `qa_skip_violation` | QA gate skipped without valid reason |
-| `model_fallback` | Transient error triggered model fallback |
-| `heartbeat` | 30-second throttled keep-alive signal |
-
-File rotates automatically at 10MB to `.swarm/telemetry.jsonl.1`.
-
-</details>
-
-<details>
-<summary><strong>Working Directory Requirement: No process.cwd() Fallback</strong></summary>
-
-All Swarm tools that accept a `working_directory` parameter **require an explicit path**. They do **not** fall back to `process.cwd()`. This prevents `.swarm` state from being created in project subdirectories when the host process's working directory differs from the actual project root (issue [#922](https://github.com/zaxbysauce/opencode-swarm/issues/922)).
-
-### Defense-in-Depth
-
-This safety guarantee is implemented in two layers:
-
-1. **Fast-path filter** (`resolveWorkingDirectory` in `src/tools/resolve-working-directory.ts`) — validates all incoming `working_directory` values for null-byte injection, path traversal, Windows device paths, and subdirectory containment before any file system access
-2. **Canonical write-time guard** (`validateProjectRoot` in `src/evidence/manager.ts`) — uses `realpathSync` to canonicalize paths at evidence-write time, catching any symlink-based subdirectory bypasses that slip past the fast-path filter
-
-### Tools That Require Explicit working_directory
-
-The following tools require an explicit `working_directory` and reject subdirectory paths:
-
-- `save_plan`
-- `update_task_status`
-- `declare_scope`
-- `pre_check_batch`
-- `test_impact`
-- `mutation_test`
-- `diff_summary`
-
-### Failure Conditions
-
-| Condition | Behavior |
-|-----------|----------|
-| Missing (`undefined` / `null`) | Fails with: "Target workspace is required" |
-| Empty or whitespace-only | Fails with: "Target workspace cannot be empty or whitespace" |
-| Path traversal (`..`) | Fails with: "Target workspace cannot contain path traversal" |
-| Subdirectory of project root | Fails with: "...is a subdirectory of fallback..." |
-| Windows device path | Fails with: "Windows device paths are not allowed" |
-
-### Usage Contract
-
-When using any affected tool, always pass a valid `working_directory`:
-
-```typescript
-// save_plan example
-save_plan({
-  title: "My Project",
-  swarm_id: "mega",
-  phases: [{ id: 1, name: "Setup", tasks: [{ id: "1.1", description: "Initialize project" }] }],
-  working_directory: "/path/to/project"  // Required - no process.cwd() fallback
-})
-
-// update_task_status example
-update_task_status({
-  task_id: "1.1",
-  status: "completed",
-  working_directory: "/path/to/project"  // Required - no fallback
-})
-```
-
-### Stray .swarm Detection
-
-`/swarm doctor` now detects and reports stray `.swarm` directories found in project subdirectories (created by older versions or misconfigured tools). It offers cleanup guidance to prevent state pollution.
-
-</details>
-
-<details>
-<summary><strong>Guardrails and Circuit Breakers</strong></summary>
-
-Every agent runs inside a circuit breaker that kills runaway behavior before it burns your credits.
-
-| Signal | Default Limit | What Happens |
-|--------|:---:|-------------|
-| Tool calls | 200 | Agent is stopped |
-| Duration | 30 min | Agent is stopped |
-| Same tool repeated | 10x | Agent is warned, then stopped |
-| Consecutive errors | 5 | Agent is stopped |
-
-Limits reset per task. A coder working on Task 2.3 is not penalized for tool calls made during Task 2.2.
-
-#### Architect Self-Coding Block
-
-If the architect writes files directly instead of delegating to the coder, a hard block fires:
-
-| Write count | Behavior |
-|:-----------:|----------|
-| 1–2 | Warning injected into next architect message |
-| ≥ 3 | `Error` thrown with `SELF_CODING_BLOCK` — identifies file paths written and count |
-
-The counter resets only when a coder delegation is dispatched. This is a hard enforcement — not advisory.
-
-Per-agent overrides:
-
-```json
-{
-  "guardrails": {
-    "profiles": {
-      "coder": { "max_tool_calls": 500, "max_duration_minutes": 60 },
-      "explorer": { "max_tool_calls": 50 }
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary><strong>File Authority (Per-Agent Write Permissions)</strong></summary>
-
-Swarm enforces per-agent file write authority — each agent can only write to specific paths. By default, these rules are hardcoded, but you can override them via config.
-
-### Default Rules
-
-| Agent | Can Write | Blocked | Zones |
-|-------|-----------|---------|-------|
-| `architect` | Everything (except plan files) | `.swarm/plan.md`, `.swarm/plan.json` | `generated` |
-| `coder` | `src/`, `tests/`, `docs/`, `scripts/` | `.swarm/` (entire directory) | `generated`, `config` |
-| `reviewer` | `.swarm/evidence/`, `.swarm/outputs/` | `src/`, `.swarm/plan.md`, `.swarm/plan.json` | `generated` |
-| `test_engineer` | `tests/`, `.swarm/evidence/` | `src/`, `.swarm/plan.md`, `.swarm/plan.json` | `generated` |
-| `explorer` | Read-only | Everything | — |
-| `sme` | Read-only | Everything | — |
-| `docs` | `docs/`, `.swarm/outputs/` | — | `generated` |
-| `designer` | `docs/`, `.swarm/outputs/` | — | `generated` |
-| `critic` | `.swarm/evidence/` | — | `generated` |
-
-### Prefixed Agents
-
-Prefixed agents (e.g., `paid_coder`, `mega_reviewer`, `local_architect`) inherit defaults from their canonical base agent via `stripKnownSwarmPrefix`. The lookup order is:
-
-1. Exact match for the prefixed name (if explicitly defined in user config)
-2. Fall back to the canonical agent's defaults (e.g., `paid_coder` → `coder`)
-
-```json
-{
-  "authority": {
-    "rules": {
-      "coder": { "allowedPrefix": ["src/", "lib/"] },
-      "paid_coder": { "allowedPrefix": ["vendor/", "plugins/"] }
-    }
-  }
-}
-```
-
-In this example, `paid_coder` gets its own explicit rule, while other prefixed coders (e.g., `mega_coder`) fall back to `coder`.
+### Skill Propagation
 
-#### Selecting the primary agent in multi-swarm configs (`default_agent`)
+Swarm includes an intelligent skill propagation system that tracks, validates, and scores skill usage across agent delegations. When the architect delegates to subagents (coder, reviewer, test_engineer, etc.), the system:
 
-The top-level `default_agent` field controls which generated agents OpenCode treats as primary. **It is optional.** Behavior:
+- **Logs skill usage** to `.swarm/skill-usage.jsonl` with session-scoped entries (agent, task ID, skill paths, timestamp)
+- **Scores skill relevance** based on frequency, compliance, recency, task ID diversity, and context matching
+- **Provides recommendations** — when delegating without a `SKILLS:` field, the system suggests relevant skills with relevance scores
+- **Enforces compliance** — optional enforcement mode can block delegations missing the `SKILLS:` field
+- **Auto-populates skill index** — maintains a `## Available Skills` section in `.swarm/context.md` with usage counts and compliance rates
+- **Supports explicit routing** — `.opencode/skill-routing.yaml` maps agent types to specific skill paths with optional keyword descriptions
 
-- **Omitted** — every architect-role agent is primary. In a multi-swarm config that means each swarm exposes its own architect (`local_architect`, `mega_architect`, `paid_architect`, `modelrelay_architect`, …) as a selectable session default. This is the v7.0.0-compatible behavior and the recommended setup.
-- **Base role** (e.g. `"coder"`) — every generated agent whose canonical base role matches becomes primary (`local_coder`, `mega_coder`, …).
-- **Exact generated name** (e.g. `"local_architect"`) — only that agent is primary.
-- **Unknown / invalid value** — a one-time warning is logged and the resolver falls back to architect-role primaries (or the first generated agent if architects are disabled). The plugin never produces zero primaries when at least one agent exists.
+**Guardrails:**
+- Relevance scoring threshold: 0.5 (skills below this are not recommended)
+- Maximum recommendations per delegation: 5
+- Scoring budget safeguard: Skipped when session exceeds 500 skill-usage entries to prevent unbounded file reads
+- Graceful degradation: Zero installed skills = zero friction — no warnings, no blocks, no auto-population
 
-See [`docs/configuration.md`](docs/configuration.md) for the full table.
-
-### Runtime Enforcement
-
-Architect direct writes are enforced at runtime via `toolBefore` hook. This tracks writes to source code paths outside `.swarm/` and protects `.swarm/plan.md` and `.swarm/plan.json` from direct modification.
-
-### Configuration
-
-Override default rules in `.opencode/opencode-swarm.json`:
+**Configuration:**
 
 ```json
 {
-  "authority": {
+  "skill_propagation": {
     "enabled": true,
-    "rules": {
-      "coder": {
-        "allowedPrefix": ["src/", "lib/", "scripts/"],
-        "blockedPrefix": [".swarm/"],
-        "blockedZones": ["generated"]
-      },
-      "explorer": {
-        "readOnly": false,
-        "allowedPrefix": ["notes/", "scratch/"]
-      }
-    }
-  }
-}
-```
-
-### Rule Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `readOnly` | boolean | If `true`, agent cannot write anywhere |
-| `blockedExact` | string[] | Exact file paths that are blocked |
-| `allowedExact` | string[] | Exact file paths that are allowed (overrides prefix/glob restrictions) |
-| `blockedPrefix` | string[] | Path prefixes that are blocked (e.g., `.swarm/`) |
-| `allowedPrefix` | string[] | Only these path prefixes are allowed. Omit to remove restriction; set `[]` to deny all |
-| `blockedGlobs` | string[] | Glob patterns that are blocked (uses picomatch: `**`, `*`, `?`) |
-| `allowedGlobs` | string[] | Glob patterns that are allowed (uses picomatch: `**`, `*`, `?`) |
-| `blockedZones` | string[] | File zones to block: `production`, `test`, `config`, `generated`, `docs`, `build` |
-
-### Merge Behavior
-
-- User rules **override** hardcoded defaults for the specified agent
-- Scalar fields (`readOnly`) — user value replaces default
-- Array fields (`blockedPrefix`, `allowedPrefix`, etc.) — user array **replaces** entirely (not merged)
-- If a field is omitted in the user rule for a **known agent** (one with hardcoded defaults), the default value for that field is preserved
-- If a field is omitted in the user rule for a **custom agent** (not in the defaults list), that field is `undefined` — there are no defaults to inherit
-- `allowedPrefix: []` explicitly denies all writes; omitting `allowedPrefix` entirely means no allowlist restriction is applied (all paths are evaluated against blocklist rules only)
-- Setting `enabled: false` ignores all custom rules and uses hardcoded defaults
-
-### Custom Agents
-
-Custom agents (not in the defaults list) start with no rules. Their write authority depends entirely on what you configure:
-
-- **Not in config at all** — agent is denied with `Unknown agent` (no rule exists; this is not the same as "blocked from all writes")
-- **In config without `allowedPrefix`** — no allowlist restriction applies; only any `blockedPrefix`, `blockedZones`, or `readOnly` rules you explicitly set will enforce limits
-- **In config with `allowedPrefix: []`** — all writes are denied
-
-To safely restrict a custom agent, always set `allowedPrefix` explicitly:
-
-```json
-{
-  "authority": {
-    "rules": {
-      "my_custom_agent": {
-        "allowedPrefix": ["plugins/", "extensions/"],
-        "blockedZones": ["generated"]
-      }
+    "enforce": false,
+    "scoring": {
+      "threshold": 0.5,
+      "max_recommendations": 5
     }
   }
 }
 ```
 
-### Advanced Examples
-
-#### Glob Pattern Support
-
-Use glob patterns for complex path matching:
-
-```json
-{
-  "authority": {
-    "rules": {
-      "coder": {
-        "allowedGlobs": ["src/**/*.ts", "tests/**/*.test.ts"],
-        "blockedGlobs": ["src/**/*.generated.ts", "**/*.d.ts"],
-        "allowedExact": ["src/index.ts", "package.json"]
-      },
-      "docs_agent": {
-        "allowedGlobs": ["docs/**/*.md", "*.md"],
-        "blockedExact": [".swarm/plan.md"]
-      }
-    }
-  }
-}
+**Skill routing file format** (`.opencode/skill-routing.yaml`):
+
+```yaml
+version: 1
+routing:
+  coder:
+    - path: .claude/skills/writing-tests/SKILL.md
+      keywords: ["test", "testing", "writing tests"]
+    - path: .claude/skills/engineering-conventions/SKILL.md
+      keywords: ["engineering", "conventions", "invariants"]
+  reviewer:
+    - path: .claude/skills/swarm-pr-review/SKILL.md
+      keywords: ["review", "security", "audit"]
 ```
 
-**Glob Pattern Features:**
-- `**` — Match any number of directories: `src/**/*.ts` matches all TypeScript files in src/ and subdirectories
-- `*` — Match any characters except path separators: `*.md` matches all Markdown files in current directory
-- `?` — Match single character: `test?.js` matches `test1.js`, `testa.js`
-- Uses [picomatch](https://github.com/micromatch/picomatch) for cross-platform compatibility
-
-**Path Normalization and Symlinks:**
-Paths are resolved via `realpathSync` before matching, which resolves symlinks and prevents path-traversal escapes. However, if a symlink's target does not exist, `realpathSync` throws and the fallback returns the symlink's own path (unresolved). A dangling symlink inside an `allowedPrefix` directory will therefore pass prefix-based checks even if its intended target is outside the project. Use `blockedExact` or `blockedGlobs` to deny known dangling-symlink paths explicitly.
-
-**Evaluation Order:**
-1. `readOnly` check (if true, deny all writes)
-2. `blockedExact` (exact path matches, highest priority)
-3. `blockedGlobs` (glob pattern matches)
-4. `allowedExact` (exact path matches, overrides prefix/glob restrictions)
-5. `allowedGlobs` (glob pattern matches)
-6. `blockedPrefix` (prefix matches)
-7. `allowedPrefix` (prefix matches)
-8. `blockedZones` (zone classification)
-
-</details>
-
-<details>
-<summary><strong>Context Budget Guard</strong></summary>
-
-The Context Budget Guard monitors how much context Swarm is injecting into the conversation. It helps prevent context overflow before it becomes a problem.
-
-### Default Behavior
-
-- **Enabled automatically** — No setup required. Swarm starts tracking context usage right away.
-- **What it measures** — Only the context that Swarm injects (plan, context, evidence, retrospectives). It does **not** count your chat history or the model's responses.
-- **Warning threshold (0.7 ratio)** — When swarm-injected context reaches ~2800 tokens (70% of 4000), the architect receives a one-time advisory warning. This is informational — execution continues normally.
-- **Critical threshold (0.9 ratio)** — When context reaches ~3600 tokens (90% of 4000), the architect receives a critical alert with a recommendation to run `/swarm handoff`. This is also one-time only.
-- **Non-nagging** — Alerts fire once per session, not repeatedly. You won't be pestered every turn.
-- **Who sees warnings** — Only the architect receives these warnings. Other agents are unaware of the budget.
-
-To disable entirely, set `context_budget.enabled: false` in your swarm config.
+Routing skills are merged with scored recommendations, with explicitly routed skills receiving a boosted score (0.9) to prioritize them.
 
 ### Configuration Reference
 

package/dist/cli/index.js

@@ -34,7 +34,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.28.3",
+    version: "7.29.0",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",

package/dist/hooks/knowledge-application.d.ts

@@ -90,6 +90,18 @@ export declare function gateKnowledgeApplication(args: {
     recentArchitectText: string;
     config: KnowledgeApplicationConfig;
 }): GateResult;
+/**
+ * Filter knowledge entries by minimum confidence threshold.
+ * Used by the knowledge reinjection hook to surface high-confidence
+ * knowledge after context compression events.
+ *
+ * @param entries - Array of knowledge entries (swarm or hive)
+ * @param threshold - Minimum confidence score (default 0.8)
+ * @returns Filtered entries with confidence >= threshold
+ */
+export declare function filterHighConfidenceKnowledge<T extends {
+    confidence: number;
+}>(entries: T[], threshold?: number): T[];
 export declare const _internals: {
     parseAcknowledgments: typeof parseAcknowledgments;
     recordKnowledgeShown: typeof recordKnowledgeShown;

package/dist/hooks/skill-propagation-gate.d.ts

@@ -20,6 +20,12 @@ import * as fs from 'node:fs';
 import type { MessageWithParts } from './knowledge-types.js';
 import { computeSkillRelevanceScore, formatSkillIndexWithContext } from './skill-scoring.js';
 import { appendSkillUsageEntry, readSkillUsageEntries, readSkillUsageEntriesTail } from './skill-usage-log.js';
+/**
+ * Load routing skills from .opencode/skill-routing.yaml for a target agent.
+ * Returns array of skill paths that are explicitly routed for the agent.
+ * Best-effort: returns empty array on any error or if file doesn't exist.
+ */
+export declare function loadRoutingSkills(directory: string, targetAgent: string): string[];
 /** Agents that should receive skill context in delegations. */
 export declare const SKILL_CAPABLE_AGENTS: Set<string>;
 /**
@@ -58,11 +64,12 @@ export declare const _internals: {
     appendSkillUsageEntry: typeof appendSkillUsageEntry;
     readSkillUsageEntries: typeof readSkillUsageEntries;
     readSkillUsageEntriesTail: typeof readSkillUsageEntriesTail;
-    extractSkillsFieldFromPrompt: typeof extractSkillsFieldFromPrompt;
     parseSkillPaths: typeof parseSkillPaths;
     extractTaskIdFromPrompt: typeof extractTaskIdFromPrompt;
+    extractSkillsFieldFromPrompt: typeof extractSkillsFieldFromPrompt;
     computeSkillRelevanceScore: typeof computeSkillRelevanceScore;
     formatSkillIndexWithContext: typeof formatSkillIndexWithContext;
+    loadRoutingSkills: typeof loadRoutingSkills;
 };
 /**
  * Scans project for available skill SKILL.md files.
@@ -117,13 +124,18 @@ export declare function extractTaskIdFromPrompt(prompt: string): string;
  * the architect delegates to a skill-capable agent with a non-empty, non-"none"
  * SKILLS field.
  *
- * @returns { blocked: false, reason: null } when no action needed.
- *          { blocked: false, reason: "warning message" } when warning only (enforce=false).
- *          { blocked: true, reason: "blocked: ..." } when blocking (enforce=true).
+ * @returns { blocked: boolean; reason: string | null; recommendedSkills?: Array<{ skillPath: string; score: number; usageCount: number }> }
+ *          When scoring has computed results, includes `recommendedSkills` with ranked skill recommendations.
+ *          When scoring was skipped or errored, `recommendedSkills` is undefined.
  */
 export declare function skillPropagationGateBefore(directory: string, input: SkillGateInput, config: SkillPropagationConfig): Promise<{
     blocked: boolean;
     reason: string | null;
+    recommendedSkills?: Array<{
+        skillPath: string;
+        score: number;
+        usageCount: number;
+    }>;
 }>;
 /**
  * Chat messages transform hook. Scans reviewer output for SKILL_COMPLIANCE

package/dist/index.js

@@ -48,7 +48,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "opencode-swarm",
-    version: "7.28.3",
+    version: "7.29.0",
     description: "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
     main: "dist/index.js",
     types: "dist/index.d.ts",
@@ -75944,58 +75944,31 @@ SECURITY_KEYWORDS: password, secret, token, credential, auth, login, encryption,
 
 ## SKILLS PROPAGATION
 
-Subagents run in isolated contexts. Project-specific skills loaded in your session are NOT automatically visible to them. Prefer repo-relative \`file:\` references; inline bodies bloat context and are fallback only.
+Subagents run in isolated contexts. Any project-specific skill constraints loaded into your session (e.g. \`writing-tests\`, \`engineering-conventions\`, coding standards, security guidelines) are NOT automatically visible to them. The hook system auto-injects relevant skills into delegation prompts.
 
-### Step 1 — Discover available skills (once per session)
+### Step 1 — Skills are auto-discovered and scored
 
-At session start, before your first delegation:
-1. Read contract files first: \`AGENTS.md\`, \`CLAUDE.md\`, \`CONTRIBUTING.md\`, \`TESTING.md\` when present. Extract task-relevant MUST/NEVER rules and pass them in INPUT/CONSTRAINT.
-2. Reuse \`<skill-context>\` skills when present.
-3. Otherwise use \`search\` with \`include\` patterns like \`.opencode/skills/*/SKILL.md,.claude/skills/*/SKILL.md\` and frontmatter queries \`^name:\` / \`^description:\`.
-4. Cache a short \`.swarm/context.md\` \`## Available Skills\` index. Include the repo-relative \`file:\` path and description so subagents can load on demand:
-   - writing-tests: Guidelines for writing tests (used: 12, compliance: 95%) → test_engineer, coder
-   - engineering-conventions: Engineering invariants (used: 8, compliance: 100%) → coder, reviewer, test_engineer
-   - [name]: [description] (used: N, compliance: N%) → [applicable agents]
+The hook system discovers available skills and scores them by relevance to the task. The hook auto-injects them into the delegation prompt.
 
-   Use \`.swarm/skill-usage.jsonl\` when present; otherwise weight skills equally.
+### Step 2 — SKILLS: field is auto-populated
 
-   If skill-usage.jsonl does not exist, proceed with equal weighting — no enrichment needed.
+The hook auto-populates the \`SKILLS:\` field with top recommended skills (max 5, threshold 0.5). Explicit \`SKILLS: none\` is preserved.
 
+### Step 3 — Skill references with context descriptions
 
-### Step 2 — Route skills to agents
+When passing skill references, you may add brief context descriptions. The hook injects \`file:path (-- description)\` format.
 
-Include a skill when its name/description matches:
+### Step 4 — Forward SKILLS_USED_BY_CODER to reviewer
 
-| Skill description / name contains…               | Pass to agents…                       |
-Route tests to test_engineer/coder; conventions to coder/reviewer/test_engineer; implementation to coder/reviewer; review/security to reviewer; docs to docs; architecture/ui/domain topics to designer or sme.
+When delegating to the reviewer after a coder task, include a \`SKILLS_USED_BY_CODER: [comma-separated list of skill paths from the coder delegation]\` field. The reviewer must receive the same skill context the coder received so it can verify skill compliance.
 
-When uncertain, pass the skill. Missing applicable skills cause convention drift.
+Example: If the coder received \`SKILLS: file:.claude/skills/writing-tests/SKILL.md\`, the reviewer delegation must include \`SKILLS_USED_BY_CODER: file:.claude/skills/writing-tests/SKILL.md\` in addition to the reviewer's own \`SKILLS:\` field.
 
-### Step 3 — Include skill references in delegations
+**Skill-to-agent routing:** Managed via \`.opencode/skill-routing.yaml\`. The hook reads this file at delegation time.
 
-Add \`SKILLS:\` to every coder, reviewer, test_engineer, sme, docs, and designer delegation:
-
-- \`SKILLS: none\` — only when no project-specific skill applies to that delegation
-- \`SKILLS: file:.claude/skills/writing-tests/SKILL.md\` — preferred for skills that exist on disk; use repo-relative \`file:\` references, comma-separated when multiple skills apply
-- Descriptive multi-line catalog:
-  SKILLS:
-  - file:.claude/skills/writing-tests/SKILL.md - Guidelines for writing tests
-  - file:.claude/skills/engineering-conventions/SKILL.md - Engineering invariants for safe changes
-- Inline fallback:
-  SKILLS:
-  --- [skill-name] ---
-  [full SKILL.md body content pasted here]
-
-Default to repo-relative \`file:\` references. Use inline skill bodies only when no stable repo path exists or a prior agent reported \`SKILL_LOAD_FAILED\`.
-
-**SKILL_LOAD_FAILED recovery:** do NOT retry with the same reference. Re-delegate with the full skill body inline, or \`SKILLS: none\` if no applicable content exists.
-
-**Mandatory for coding tasks:** provide \`writing-tests\` to test_engineer and \`engineering-conventions\` to coder + reviewer when present.
-
-### Step 4 — Forward skills to reviewer
-
-When delegating to reviewer after coder, include \`SKILLS_USED_BY_CODER: [comma-separated skill paths from coder]\` plus reviewer \`SKILLS:\` so compliance can be checked.
+**SKILL_LOAD_FAILED recovery:** If a subagent reports SKILL_LOAD_FAILED for a \`file:\` reference, do NOT retry with the same reference. Instead, re-delegate with either: (a) the full skill body pasted inline, or (b) \`SKILLS: none\` if no applicable skill content is available. Never re-use a file: reference that has already failed.
 
+**Mandatory for coding tasks:** Always provide \`writing-tests\` to test_engineer and \`engineering-conventions\` to coder + reviewer when those skills are present in the project. Prefer \`file:\` references when the files exist.
 
 ## SWARM KNOWLEDGE DIRECTIVES (v2 acknowledgment contract)
 
@@ -76018,14 +75991,28 @@ You may also call the \`knowledge_ack\` tool to record an outcome explicitly whe
 
 ## SKILL IMPROVER (low-frequency, expensive-model adviser)
 
-Use \`skill_improver\` / \`skill_improve\` rarely for repeated review failures, ignored knowledge clusters, stale skills, or fresh spec drift. It is quota-bounded and proposal-only.
+The \`skill_improver\` agent and the \`skill_improve\` tool exist for rare, deep
+review of accumulated knowledge / skills / spec / architect prompt. They are
+quota-bounded (default 10 calls/day) and disabled by default. Suggest running
+\`skill_improve\` only after one of:
+- repeated reviewer rejections in a row,
+- many \`KNOWLEDGE_IGNORED\` outcomes for the same cluster,
+- stale skills (no updates while their target area changed),
+- a fresh spec mismatch with shipped behaviour.
 
 When \`skill_improver.require_user_approval\` is true (default), ASK the user
 before running. Default outputs are proposals only — they never modify source.
 
 ## SPEC WRITER
 
-For substantial spec authoring/revision, prefer \`spec_writer\`; it writes only via \`spec_write\`. Use it for new/major specs, non-trivial requirements decomposition, or when you would otherwise inline-author \`.swarm/spec.md\`. Handle small typos/cross-references inline.
+For substantial spec authoring or revision, prefer delegating to the
+\`spec_writer\` agent (independent model from architect). It writes only via
+the safe \`spec_write\` tool. Use it when:
+- the user requests a new spec or major spec revision,
+- requirements decomposition is non-trivial,
+- you would otherwise inline-author \`.swarm/spec.md\` yourself.
+
+Continue handling small touch-ups (typos, cross-references) inline.
 
 ### ANTI-RATIONALIZATION
 - ✗ "The coder already knows these conventions" → Skills contain project-specific rules the model cannot know from training. Always pass.
@@ -76038,7 +76025,7 @@ For substantial spec authoring/revision, prefer \`spec_writer\`; it writes only
 ## SLASH COMMANDS
 {{SLASH_COMMANDS}}
 Commands above are documented with args and behavioral details. Run commands via /swarm <command> [args].
-Outside OpenCode, use \`bunx opencode-swarm run <command> [args]\`; never use \`bun -e\` or internal \`src/commands/\` paths. Human-only commands (\`acknowledge-spec-drift\`, \`reset\`, \`reset-session\`, \`rollback\`, \`checkpoint\`, safety-gate release, plan-state destruction) MUST be presented to the user to run. Never invoke them via Bash, swarm_command, or chat fallback; if blocked as human-only, present it to the user.
+Outside OpenCode, invoke any plugin command via: \`bunx opencode-swarm run <command> [args]\` (e.g. \`bunx opencode-swarm run knowledge migrate\`). Do not use \`bun -e\` or look for \`src/commands/\` — those paths are internal to the plugin source and do not exist in user project directories. EXCEPTION — human-only commands (including but not limited to \`acknowledge-spec-drift\`, \`reset\`, \`reset-session\`, \`rollback\`, \`checkpoint\`, and any command that releases a runtime safety gate or destroys plan state): you MUST present these to the user and ask them to run the command themselves. Never invoke a human-only command via Bash, swarm_command, or chat fallback. The runtime guardrail will block such attempts; if a Bash call returns \`BLOCKED\` with a "human-only" message, do not retry under a different shell form — present the situation to the user instead.
 
 SMEs advise only. Reviewer and critic review only. None of them write code.
 
@@ -76046,15 +76033,15 @@ Available Tools: {{AVAILABLE_TOOLS}}
 
 ## DELEGATION FORMAT
 
-Delegations happen ONLY through the **Task** tool; chat text is not delivered to agents. Examples below are Task content.
+Delegations are performed ONLY by calling the **Task** tool. Writing delegation text into the chat does nothing — the agent will not receive it. Every delegation below is the content you pass to the Task tool, not text you output to the conversation.
 
-follow the receiving agent's INPUT FORMAT exactly; do NOT invent/omit fields. Begin with agent name, \`TASK:\`, and \`SKILLS:\` when supported.
+All delegations MUST follow the receiving agent's INPUT FORMAT exactly. Do NOT invent fields, omit required fields, or force one agent's schema onto another. Every delegation MUST begin with the agent name, include \`TASK:\`, and include \`SKILLS:\` when that agent prompt supports skills.
 Do NOT add conversational preamble before the agent prefix. Begin directly with the agent name.
 
 {{AGENT_PREFIX}}[agent]
 TASK: [single objective]
 [agent-specific fields required by that agent's INPUT FORMAT]
-SKILLS: [either "none", repo-relative file references with descriptions, or inline skill bodies — see SKILLS PROPAGATION; use "none" only when no project-specific skill applies]
+SKILLS: [either "none", repo-relative file: references, or inline skill bodies — see SKILLS PROPAGATION; use "none" only when no project-specific skill applies]
 
 Examples:
 
@@ -76087,22 +76074,22 @@ FILE: src/auth/login.ts
 INPUT: Validate email format, password >= 8 chars
 OUTPUT: Modified file
 CONSTRAINT: Do not modify other functions
-SKILLS: file:.claude/skills/engineering-conventions/SKILL.md - safe code changes
+SKILLS: file:.claude/skills/engineering-conventions/SKILL.md
 
 {{AGENT_PREFIX}}reviewer
 TASK: Review login validation
 FILE: src/auth/login.ts
 CHECK: [security, correctness, edge-cases]
 GATES: lint=PASS, sast_scan=PASS, secretscan=PASS
-SKILLS_USED_BY_CODER: file:.claude/skills/engineering-conventions/SKILL.md - safe code changes
+SKILLS_USED_BY_CODER: file:.claude/skills/engineering-conventions/SKILL.md
 OUTPUT: VERDICT + RISK + ISSUES
-SKILLS: file:.claude/skills/engineering-conventions/SKILL.md - safe code changes
+SKILLS: file:.claude/skills/engineering-conventions/SKILL.md
 
 {{AGENT_PREFIX}}test_engineer
 TASK: Generate and run login validation tests
 FILE: src/auth/login.ts
 OUTPUT: Test file at src/auth/login.test.ts + VERDICT: PASS/FAIL with failure details
-SKILLS: file:.claude/skills/writing-tests/SKILL.md - tests
+SKILLS: file:.claude/skills/writing-tests/SKILL.md
 
 {{AGENT_PREFIX}}critic
 TASK: Review plan for user authentication feature
@@ -76117,14 +76104,14 @@ FILE: src/auth/login.ts
 CHECK: [security-only] — evaluate against OWASP Top 10, scan for hardcoded secrets, injection vectors, insecure crypto, missing input validation
 GATES: lint=PASS, sast_scan=PASS, secretscan=PASS
 OUTPUT: VERDICT + RISK + SECURITY ISSUES ONLY
-SKILLS: file:.claude/skills/engineering-conventions/SKILL.md - safe code changes
+SKILLS: file:.claude/skills/engineering-conventions/SKILL.md
 
 {{AGENT_PREFIX}}test_engineer
 TASK: Adversarial security testing
 FILE: src/auth/login.ts
 CONSTRAINT: ONLY attack vectors — malformed inputs, oversized payloads, injection attempts, auth bypass, boundary violations
 OUTPUT: Test file + VERDICT: PASS/FAIL
-SKILLS: file:.claude/skills/writing-tests/SKILL.md - tests
+SKILLS: file:.claude/skills/writing-tests/SKILL.md
 
 {{AGENT_PREFIX}}explorer
 TASK: Integration impact analysis
@@ -95117,6 +95104,9 @@ function utcDayKey(d = new Date) {
 function buildAckDedupKey(sessionId, id, result, now = new Date) {
   return `${sessionId}|${id}|${result}|${utcDayKey(now)}`;
 }
+function filterHighConfidenceKnowledge(entries, threshold = 0.8) {
+  return entries.filter((entry) => entry.confidence >= threshold);
+}
 
 // src/hooks/knowledge-application-gate.ts
 var HIGH_RISK_TOOLS = new Set([
@@ -95569,7 +95559,8 @@ function createKnowledgeInjectorHook(directory, config3) {
       currentPhase: phaseDescription
     };
     const entries = await readContextualKnowledge(directory, config3, retrievalCtx);
-    cachedShownIds = entries.map((e) => e.id);
+    const filteredEntries = filterHighConfidenceKnowledge(entries);
+    cachedShownIds = filteredEntries.map((e) => e.id);
     let freshPreamble = null;
     try {
       const driftReports = await readPriorDriftReports(directory);
@@ -95590,7 +95581,7 @@ function createKnowledgeInjectorHook(directory, config3) {
 ${freshPreamble}` : `<curator_briefing>${truncatedBriefing}</curator_briefing>`;
       }
     } catch {}
-    if (entries.length === 0) {
+    if (filteredEntries.length === 0) {
       if (freshPreamble === null)
         return;
       cachedInjectionText = freshPreamble;
@@ -95601,9 +95592,9 @@ ${freshPreamble}` : `<curator_briefing>${truncatedBriefing}</curator_briefing>`;
     const isFullBudget = effectiveBudget === maxInjectChars;
     const directiveBudget = Math.floor(effectiveBudget * 0.45);
     const lessonBudget = Math.floor(effectiveBudget * 0.3);
-    const directiveEntries = entries.filter((e) => e.triggers && e.triggers.length > 0 || e.required_actions && e.required_actions.length > 0 || e.forbidden_actions && e.forbidden_actions.length > 0 || e.directive_priority === "critical" || e.directive_priority === "high" || e.generated_skill_path);
+    const directiveEntries = filteredEntries.filter((e) => e.triggers && e.triggers.length > 0 || e.required_actions && e.required_actions.length > 0 || e.forbidden_actions && e.forbidden_actions.length > 0 || e.directive_priority === "critical" || e.directive_priority === "high" || e.generated_skill_path);
     const directiveBlock = buildDirectiveBlock(directiveEntries, directiveBudget, config3);
-    const lessonBlock = buildKnowledgeBlock(entries, lessonBudget, config3, projectName);
+    const lessonBlock = buildKnowledgeBlock(filteredEntries, lessonBudget, config3, projectName);
     const parts2 = [];
     let remaining = effectiveBudget;
     if (directiveBlock) {
@@ -95645,7 +95636,7 @@ ${freshPreamble}` : `<curator_briefing>${truncatedBriefing}</curator_briefing>`;
     injectKnowledgeMessage(output, cachedInjectionText);
     const sessionID = systemMsg?.info?.sessionID;
     if (sessionID) {
-      const criticalIds = entries.filter((e) => e.directive_priority === "critical" && e.status !== "archived").map((e) => e.id);
+      const criticalIds = filteredEntries.filter((e) => e.directive_priority === "critical" && e.status !== "archived").map((e) => e.id);
       if (criticalIds.length > 0) {
         setCriticalShownIds(sessionID, {
           ids: criticalIds,
@@ -96179,8 +96170,12 @@ function getSkillStats(skillPath, directory) {
   };
 }
 function formatSkillIndexWithContext(skills, directory) {
-  const allEntries = readSkillUsageEntries(directory);
-  const hasHistory = allEntries.length > 0;
+  const usageLogPath = path89.join(directory, ".swarm", "skill-usage.jsonl");
+  let hasHistory = false;
+  try {
+    const stat7 = fs62.statSync(usageLogPath);
+    hasHistory = stat7.size > 0;
+  } catch {}
   if (!hasHistory) {
     return skills.map((sp) => {
       const meta3 = _internals42.readSkillMetadata(sp, directory);
@@ -96210,6 +96205,121 @@ _internals42.computeRecencyScore = computeRecencyScore;
 _internals42.computeContextMatchScore = computeContextMatchScore;
 
 // src/hooks/skill-propagation-gate.ts
+function parseSimpleYaml(content) {
+  const lines = content.split(`
+`);
+  const result = {};
+  let _currentSection = null;
+  let currentSubSection = null;
+  let currentList = [];
+  let currentListItem = null;
+  for (const line of lines) {
+    if (!line.trim() || line.trim().startsWith("#"))
+      continue;
+    const indent = line.search(/\S/);
+    const trimmed = line.trim();
+    if (indent === 0 && trimmed.endsWith(":")) {
+      if (_currentSection && currentSubSection && currentList.length > 0) {
+        if (!result[_currentSection]) {
+          result[_currentSection] = {};
+        }
+        result[_currentSection][currentSubSection] = currentList;
+      } else if (currentSubSection && currentList.length > 0) {
+        result[currentSubSection] = currentList;
+      }
+      _currentSection = trimmed.slice(0, -1);
+      currentSubSection = null;
+      currentList = [];
+      currentListItem = null;
+      continue;
+    }
+    if (indent === 2 && trimmed.endsWith(":")) {
+      if (_currentSection && currentSubSection && currentList.length > 0) {
+        if (!result[_currentSection]) {
+          result[_currentSection] = {};
+        }
+        result[_currentSection][currentSubSection] = currentList;
+      } else if (currentSubSection && currentList.length > 0) {
+        result[currentSubSection] = currentList;
+      }
+      currentSubSection = trimmed.slice(0, -1);
+      currentList = [];
+      currentListItem = null;
+      continue;
+    }
+    if (trimmed.startsWith("- ")) {
+      currentListItem = null;
+      const rest = trimmed.slice(2);
+      if (rest.includes(":")) {
+        const colonIndex = rest.indexOf(":");
+        const key = rest.slice(0, colonIndex).trim();
+        const value = rest.slice(colonIndex + 1).trim();
+        currentListItem = { [key]: parseYamlValue(value) };
+      } else {
+        currentListItem = { path: trimmed.slice(2) };
+      }
+      currentList.push(currentListItem);
+      continue;
+    }
+    if (indent >= 4 && currentListItem) {
+      if (trimmed.includes(":")) {
+        const colonIndex = trimmed.indexOf(":");
+        const key = trimmed.slice(0, colonIndex).trim();
+        const value = trimmed.slice(colonIndex + 1).trim();
+        currentListItem[key] = parseYamlValue(value);
+      }
+    }
+  }
+  if (currentSubSection && currentList.length > 0) {
+    if (_currentSection) {
+      if (!result[_currentSection]) {
+        result[_currentSection] = {};
+      }
+      result[_currentSection][currentSubSection] = currentList;
+    } else {
+      result[currentSubSection] = currentList;
+    }
+  }
+  return result;
+}
+function parseYamlValue(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+    const inner = trimmed.slice(1, -1);
+    if (!inner.trim())
+      return [];
+    return inner.split(",").map((s) => s.trim().replace(/^["']|["']$/g, ""));
+  }
+  if (trimmed.toLowerCase() === "true")
+    return true;
+  if (trimmed.toLowerCase() === "false")
+    return false;
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+    return trimmed.includes(".") ? parseFloat(trimmed) : parseInt(trimmed, 10);
+  }
+  return trimmed;
+}
+function loadRoutingSkills(directory, targetAgent) {
+  const routingPath = path90.join(directory, ".opencode", "skill-routing.yaml");
+  if (!_internals43.existsSync(routingPath))
+    return [];
+  try {
+    const content = _internals43.readFileSync(routingPath, "utf-8");
+    const config3 = parseSimpleYaml(content);
+    if (!config3?.routing)
+      return [];
+    const routing = config3.routing;
+    const routingEntries = routing[targetAgent];
+    if (!routingEntries || routingEntries.length === 0)
+      return [];
+    return routingEntries.map((entry) => entry.path);
+  } catch {
+    return [];
+  }
+}
 var SKILL_CAPABLE_AGENTS = new Set([
   "coder",
   "reviewer",
@@ -96242,11 +96352,12 @@ var _internals43 = {
   appendSkillUsageEntry,
   readSkillUsageEntries,
   readSkillUsageEntriesTail,
-  extractSkillsFieldFromPrompt: null,
   parseSkillPaths: null,
   extractTaskIdFromPrompt: null,
+  extractSkillsFieldFromPrompt: null,
   computeSkillRelevanceScore,
-  formatSkillIndexWithContext
+  formatSkillIndexWithContext,
+  loadRoutingSkills: null
 };
 function discoverAvailableSkills(directory) {
   const results = [];
@@ -96354,22 +96465,21 @@ function parseSkillPaths(fieldValue) {
   const trimmed = fieldValue.trim();
   if (trimmed.toLowerCase() === "none" || trimmed === "")
     return [];
-  const lines = trimmed.split(/\r?\n/);
-  const hasCatalogLines = lines.some((line) => /^(?:-|\*|\d+\.)\s+/.test(line.trim()));
-  const parts2 = hasCatalogLines ? lines : trimmed.split(",");
-  const paths = [];
-  for (const rawPart of parts2) {
-    const part = rawPart.trim().replace(/^(?:-|\*|\d+\.)\s+/, "").trim();
-    if (!part || part.toLowerCase() === "none")
-      continue;
-    const fileRef = part.match(/\bfile:[^\s,;)\]]+/);
-    if (fileRef) {
-      paths.push(fileRef[0].replace(/\\/g, "/"));
-      continue;
-    }
-    paths.push(part);
-  }
-  return [...new Set(paths)];
+  const commaParts = trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  if (commaParts.length === 1 && commaParts[0].startsWith("- ")) {
+    const newlineParts = trimmed.split(`
+`).map((s) => s.trim()).filter((s) => s.startsWith("- ")).map((s) => s.slice(2).trim());
+    return newlineParts.map((s) => {
+      const parenIndex = s.indexOf("(--");
+      const pathOnly = parenIndex !== -1 ? s.slice(0, parenIndex).trim() : s;
+      const dashIndex = pathOnly.search(/\s+[-–—]\s+/);
+      return dashIndex !== -1 ? pathOnly.slice(0, dashIndex).trim() : pathOnly;
+    }).filter((s) => s.length > 0);
+  }
+  return commaParts.map((s) => {
+    const parenIndex = s.indexOf("(--");
+    return parenIndex !== -1 ? s.slice(0, parenIndex).trim() : s;
+  }).filter((s) => s.length > 0);
 }
 function extractTaskIdFromPrompt(prompt) {
   if (!prompt || typeof prompt !== "string")
@@ -96384,22 +96494,22 @@ function extractTaskIdFromPrompt(prompt) {
 }
 async function skillPropagationGateBefore(directory, input, config3) {
   if (!config3.enabled)
-    return { blocked: false, reason: null };
+    return { blocked: false, reason: null, recommendedSkills: undefined };
   const toolName = typeof input.tool === "string" ? input.tool : "";
   if (toolName !== "task" && toolName !== "Task")
-    return { blocked: false, reason: null };
+    return { blocked: false, reason: null, recommendedSkills: undefined };
   const agentRaw = typeof input.agent === "string" ? input.agent : "";
   if (!agentRaw)
-    return { blocked: false, reason: null };
+    return { blocked: false, reason: null, recommendedSkills: undefined };
   const baseAgent = stripKnownSwarmPrefix(agentRaw);
   if (baseAgent !== "architect")
-    return { blocked: false, reason: null };
+    return { blocked: false, reason: null, recommendedSkills: undefined };
   const parsed = _internals43.parseDelegationArgs(input.args);
   if (!parsed)
-    return { blocked: false, reason: null };
+    return { blocked: false, reason: null, recommendedSkills: undefined };
   const targetBase = stripKnownSwarmPrefix(parsed.targetAgent);
   if (!_internals43.SKILL_CAPABLE_AGENTS.has(targetBase))
-    return { blocked: false, reason: null };
+    return { blocked: false, reason: null, recommendedSkills: undefined };
   const sessionID = typeof input.sessionID === "string" ? input.sessionID : "unknown";
   const availableSkills = _internals43.discoverAvailableSkills(directory);
   const skillsValue = parsed.skillsField.trim();
@@ -96462,6 +96572,23 @@ async function skillPropagationGateBefore(directory, input, config3) {
       warn(`[skill-propagation-gate] skill scoring failed (non-blocking): ${err2 instanceof Error ? err2.message : String(err2)}`);
     }
   }
+  try {
+    const routingPaths = _internals43.loadRoutingSkills(directory, targetBase);
+    if (routingPaths.length > 0) {
+      const existingPaths = new Set(scored.map((s) => s.skillPath));
+      for (const routingPath of routingPaths) {
+        if (!existingPaths.has(routingPath)) {
+          scored.push({
+            skillPath: routingPath,
+            score: 0.9,
+            usageCount: 0
+          });
+          existingPaths.add(routingPath);
+        }
+      }
+      scored.sort((a, b) => b.score - a.score || b.usageCount - a.usageCount);
+    }
+  } catch {}
   if (availableSkills.length > 0) {
     try {
       let skillsForIndex = availableSkills;
@@ -96520,14 +96647,14 @@ ${newSection}`;
     const coderHadSkills = skillsValue.length > 0 && skillsValue.toLowerCase() !== "none";
     if (!hasSkillsUsedByCoder && coderHadSkills) {
       const message = `SKILLS_USED_BY_CODER warning: Delegating to reviewer without SKILLS_USED_BY_CODER field. ` + `Add SKILLS_USED_BY_CODER with the skills the coder received for this task.`;
-      return { blocked: false, reason: message };
+      return { blocked: false, reason: message, recommendedSkills: undefined };
     }
   }
   if (availableSkills.length === 0)
-    return { blocked: false, reason: null };
+    return { blocked: false, reason: null, recommendedSkills: undefined };
   const skillsLower = skillsValue.toLowerCase();
   if (skillsValue && skillsLower !== "none")
-    return { blocked: false, reason: null };
+    return { blocked: false, reason: null, recommendedSkills: scored };
   const skillNames = availableSkills.map((p) => {
     const parts2 = p.split("/");
     return parts2[parts2.length - 2] ?? p;
@@ -96547,9 +96674,9 @@ ${newSection}`;
   } catch {}
   if (config3.enforce) {
     const blockedMsg = `Blocked by skill propagation gate: Delegating to ${targetBase} without SKILLS field. ` + `Available skills: ${skillNames.join(", ")}. ` + `Add a SKILLS: field or set enforce: false in config.`;
-    return { blocked: true, reason: blockedMsg };
+    return { blocked: true, reason: blockedMsg, recommendedSkills: undefined };
   }
-  return { blocked: false, reason: warningMsg };
+  return { blocked: false, reason: warningMsg, recommendedSkills: undefined };
 }
 var COMPLIANCE_PATTERN = /SKILL_COMPLIANCE\s*:\s*(COMPLIANT|PARTIAL|VIOLATED)(?:\s*(?:—|-)\s*(.*))?\s*$/i;
 var CODER_SKILLS_PATTERN = /SKILLS_USED_BY_CODER\s*:\s*(.+)/i;
@@ -96658,10 +96785,8 @@ async function skillPropagationTransformScan(directory, output, sessionID) {
       continue;
     let currentTargetAgent = "";
     let skillsField = "";
-    const textLines = text.split(`
-`);
-    for (let lineIndex = 0;lineIndex < textLines.length; lineIndex++) {
-      const line = textLines[lineIndex] ?? "";
+    for (const line of text.split(`
+`)) {
       const trimmed = line.trim();
       if (trimmed.match(/TO\s+(coder|reviewer|test_engineer|sme|docs|designer)/i)) {
         const agentMatch = trimmed.match(/TO\s+(coder|reviewer|test_engineer|sme|docs|designer)/i);
@@ -96669,8 +96794,7 @@ async function skillPropagationTransformScan(directory, output, sessionID) {
           currentTargetAgent = agentMatch[1].toLowerCase();
       }
       if (trimmed.startsWith("SKILLS:")) {
-        skillsField = _internals43.extractSkillsFieldFromPrompt(textLines.slice(lineIndex).join(`
-`));
+        skillsField = trimmed.slice("SKILLS:".length).trim();
       }
       if (currentTargetAgent && skillsField && skillsField.toLowerCase() !== "none") {
         const skillPaths = _internals43.parseSkillPaths(skillsField);
@@ -96706,10 +96830,11 @@ _internals43.skillPropagationTransformScan = skillPropagationTransformScan;
 _internals43.writeWarnEvent = writeWarnEvent2;
 _internals43.discoverAvailableSkills = discoverAvailableSkills;
 _internals43.parseDelegationArgs = parseDelegationArgs;
-_internals43.extractSkillsFieldFromPrompt = extractSkillsFieldFromPrompt;
 _internals43.parseSkillPaths = parseSkillPaths;
 _internals43.extractTaskIdFromPrompt = extractTaskIdFromPrompt;
+_internals43.extractSkillsFieldFromPrompt = extractSkillsFieldFromPrompt;
 _internals43.formatSkillIndexWithContext = formatSkillIndexWithContext;
+_internals43.loadRoutingSkills = loadRoutingSkills;
 
 // src/hooks/slop-detector.ts
 import * as fs64 from "node:fs";
@@ -99991,7 +100116,7 @@ import {
   readFileSync as readFileSync44,
   writeFileSync as writeFileSync17
 } from "node:fs";
-import { join as join83 } from "node:path";
+import { join as join84 } from "node:path";
 var EVIDENCE_DIR2 = ".swarm/evidence";
 var VALID_TASK_ID = /^\d+\.\d+(\.\d+)*$/;
 var COUNCIL_GATE_NAME = "council";
@@ -100025,9 +100150,9 @@ function writeCouncilEvidence(workingDir, synthesis) {
   if (!VALID_TASK_ID.test(synthesis.taskId)) {
     throw new Error(`writeCouncilEvidence: invalid taskId "${synthesis.taskId}" — must match N.M or N.M.P format`);
   }
-  const dir = join83(workingDir, EVIDENCE_DIR2);
+  const dir = join84(workingDir, EVIDENCE_DIR2);
   mkdirSync25(dir, { recursive: true });
-  const filePath = join83(dir, `${synthesis.taskId}.json`);
+  const filePath = join84(dir, `${synthesis.taskId}.json`);
   const existingRoot = Object.create(null);
   if (existsSync53(filePath)) {
     try {
@@ -100061,7 +100186,7 @@ function writeCouncilEvidence(workingDir, synthesis) {
     updated.required_gates = [];
   writeFileSync17(filePath, JSON.stringify(updated, null, 2));
   try {
-    const councilDir = join83(workingDir, ".swarm", "council");
+    const councilDir = join84(workingDir, ".swarm", "council");
     mkdirSync25(councilDir, { recursive: true });
     const auditLine = JSON.stringify({
       round: synthesis.roundNumber,
@@ -100069,7 +100194,7 @@ function writeCouncilEvidence(workingDir, synthesis) {
       timestamp: synthesis.timestamp,
       vetoedBy: synthesis.vetoedBy
     });
-    appendFileSync12(join83(councilDir, `${synthesis.taskId}.rounds.jsonl`), `${auditLine}
+    appendFileSync12(join84(councilDir, `${synthesis.taskId}.rounds.jsonl`), `${auditLine}
 `);
   } catch (auditError) {
     console.warn(`writeCouncilEvidence: failed to append round-history audit log: ${auditError instanceof Error ? auditError.message : String(auditError)}`);
@@ -100392,20 +100517,20 @@ function buildFinalCouncilFeedback(projectSummary, verdict, vetoedBy, requiredFi
 
 // src/council/criteria-store.ts
 import { existsSync as existsSync54, mkdirSync as mkdirSync26, readFileSync as readFileSync45, writeFileSync as writeFileSync18 } from "node:fs";
-import { join as join84 } from "node:path";
+import { join as join85 } from "node:path";
 var COUNCIL_DIR = ".swarm/council";
 function writeCriteria(workingDir, taskId, criteria) {
-  const dir = join84(workingDir, COUNCIL_DIR);
+  const dir = join85(workingDir, COUNCIL_DIR);
   mkdirSync26(dir, { recursive: true });
   const payload = {
     taskId,
     criteria,
     declaredAt: new Date().toISOString()
   };
-  writeFileSync18(join84(dir, `${safeId(taskId)}.json`), JSON.stringify(payload, null, 2));
+  writeFileSync18(join85(dir, `${safeId(taskId)}.json`), JSON.stringify(payload, null, 2));
 }
 function readCriteria(workingDir, taskId) {
-  const filePath = join84(workingDir, COUNCIL_DIR, `${safeId(taskId)}.json`);
+  const filePath = join85(workingDir, COUNCIL_DIR, `${safeId(taskId)}.json`);
   if (!existsSync54(filePath))
     return null;
   try {
@@ -118927,6 +119052,73 @@ async function initializeOpenCodeSwarm(ctx) {
         skillSession.pendingAdvisoryMessages ??= [];
         skillSession.pendingAdvisoryMessages.push(skillResult.reason);
       }
+      if (skillResult.recommendedSkills && skillResult.recommendedSkills.length > 0) {
+        const argsRecord = input.args;
+        const promptRaw = argsRecord.prompt;
+        if (typeof promptRaw === "string") {
+          const parsedDelegation = parseDelegationArgs(input.args);
+          if (parsedDelegation) {
+            const existingSkills = parsedDelegation.skillsField.trim();
+            if (!existingSkills) {
+              const qualified = skillResult.recommendedSkills.filter((s) => s.score >= 0.5);
+              if (qualified.length === 0) {
+                argsRecord.prompt = `SKILLS: none
+
+${promptRaw}`;
+                console.warn("[skill-propagation-gate] No skills above threshold 0.5 — injected SKILLS: none");
+              } else {
+                const topSkills = qualified.slice(0, 5);
+                const SKILL_DESCRIPTIONS = {
+                  "writing-tests": "Guidelines for writing tests",
+                  "engineering-conventions": "Engineering invariants and conventions",
+                  "running-tests": "Safe test execution patterns",
+                  "commit-pr": "Commit and PR workflow",
+                  "swarm-implement": "Swarm implementation workflow",
+                  "issue-tracer": "Issue investigation workflow",
+                  "qa-sweep": "QA sweep workflow",
+                  "research-first": "Research-driven approach",
+                  "swarm-pr-review": "PR review workflow",
+                  "tech-debt-ci-review": "Tech debt and CI review",
+                  browse: "Fast web browsing",
+                  code: "Expert coding workflow",
+                  review: "Pre-landing PR review",
+                  "ci-failure-resolver": "CI/CD failure resolution"
+                };
+                const skillPaths = topSkills.map((s) => {
+                  const dirName = path144.basename(path144.dirname(s.skillPath));
+                  const desc = SKILL_DESCRIPTIONS[dirName] ?? dirName;
+                  return `file:${s.skillPath} (-- ${desc})`;
+                }).join(", ");
+                const skillsLine = `SKILLS: ${skillPaths}`;
+                const newPrompt = `${skillsLine}
+
+${promptRaw}`;
+                argsRecord.prompt = newPrompt;
+                const skillNames = topSkills.map((s) => `${path144.basename(s.skillPath)} (score: ${s.score.toFixed(2)})`).join(", ");
+                console.warn(`[skill-propagation-gate] Injected skills: ${skillNames}`);
+                for (const skill of topSkills) {
+                  try {
+                    appendSkillUsageEntry(ctx.directory, {
+                      skillPath: skill.skillPath,
+                      agentName: String(input.agent),
+                      taskID: "injection",
+                      timestamp: new Date().toISOString(),
+                      complianceVerdict: "not_checked",
+                      sessionID: input.sessionID
+                    });
+                  } catch {}
+                }
+                const targetAgent = parsedDelegation.targetAgent.toLowerCase();
+                if (targetAgent.includes("reviewer")) {
+                  const usedByCoderLine = `SKILLS_USED_BY_CODER: ${topSkills.map((s) => `file:${s.skillPath}`).join(", ")}`;
+                  argsRecord.prompt = `${newPrompt}
+${usedByCoderLine}`;
+                }
+              }
+            }
+          }
+        }
+      }
       if (swarmState.lastBudgetPct >= 50) {
         const pressureSession = ensureAgentSession(input.sessionID, swarmState.activeAgent.get(input.sessionID) ?? ORCHESTRATOR_NAME);
         if (!pressureSession.contextPressureWarningSent) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "opencode-swarm",
-	"version": "7.28.3",
+	"version": "7.29.0",
 	"description": "Architect-centric agentic swarm plugin for OpenCode - hub-and-spoke orchestration with SME consultation, code generation, and QA review",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",