skill-system-router

What this skill does

# Skill System Router

Deprecated compatibility surface. `skill-system-cli` now owns the router runtime module used by `sk`, while this skill remains available so existing router docs, policy references, and legacy entrypoints do not break during the transition.

You are the Router. This skill teaches you how to orchestrate other skills.

Router is an internal orchestration layer. The public user-facing entrypoint remains `sk` from `skill-system-cli`.

## How It Works

```
User goal → Read skills-index.json → Match capabilities → Read skill manifest
→ (Complex goal: plan with workflow) → Check policy → Execute entrypoints → Parse JSON output → Decide next step → Log
```

## Step 0: Installer Bootstrap Check (First Run Only)

Check if the project's AGENTS.md contains `## Skill System`.

- If found: skip to Step 1 (already bootstrapped).
- If not found: use `skill-system-installer` bootstrap to scaffold and embed the skill system into the project.

Bootstrap ownership lives in `skill-system-installer`. After bootstrap, every future session reads AGENTS.md and knows about the skill system automatically.

## Step 1: Discover Skills

Read `skills-index.json` (in the skills root directory, sibling to skill folders) to see available capabilities.

The index maps capabilities → skills and lists each skill's operations with descriptions and input params. Match the user's goal to capabilities. If no match, check if the goal can be decomposed into sub-capabilities.

If the goal is multi-step, ambiguous, or likely to involve 3+ operations, route through workflow planning first via `plan-with-workflow`.

If `skills-index.json` is missing or stale, regenerate it:

```bash
bash "<this-skill-dir>/scripts/build-index.sh"
```

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "<this-skill-dir>\scripts\build-index.ps1"
```

## Session Guard

**MANDATORY ROUTER-FIRST STARTUP**: This skill MUST be loaded before any non-router skill at session start. This is a fail-closed guard:

1. Load `skill-system-router` first.
2. Run the `guard-check` operation.
3. If guard-check has NOT succeeded: **block all non-router skill loads** and emit the failure message:
   > `Router guard failed: load skill-system-router and complete router discovery before using non-router skills.`
4. Only after guard-check succeeds: proceed with non-router skills.

This enforcement is non-negotiable. If a user requests a non-router skill directly, you MUST load router first and complete the guard before proceeding.

Guard failure semantics:
- If `router_checked` flag is missing: block non-router skills, show message, run discovery.
- If `skills-index.json` is missing or stale: rebuild it before marking guard complete.
- Memory-backed flag preferred: `router_checked=true` with `session_id`.

- Procedure: `scripts/session-guard-check.md`

## Step 2: Read Skill Manifest

Open the target skill's `SKILL.md` and find the `` `skill-manifest` `` fenced block. This gives you:

- **operations**: what the skill can do, with input/output schemas
- **effects**: side effects (used for policy check)
- **entrypoints**: OS-specific commands to run

Full manifest spec: `references/manifest-spec.md`

## Configuration

Runtime settings are in `config/router.yaml`. Config is the single source of truth.

See: `../../config/router.yaml`

## Step 3: Check Policy

Before executing, verify the skill's declared `effects` against the active policy profile:

```sql
SELECT allowed_effects FROM skill_system.policy_profiles WHERE name = 'dev';
```

- ALL effects in `allowed_effects` → proceed
- ANY effect NOT in `allowed_effects` → **ask the user** before proceeding
- No policy profile exists → ask the user

`report-improvement-issue` policy notes:
- Always requires: `proc.exec`, `net.fetch`
- Also requires `git.read` when `repo` is omitted and inferred from git remote

Standard effects: `db.read`, `db.write`, `proc.exec`, `fs.read`, `fs.write`, `net.fetch`, `git.read`, `git.write`

The internal policy helper `scripts/router.py check-policy` returns a structured
`policy_decisions` list so callers can surface the exact allow/deny reasoning.
If `skill_system.policy_profiles` is unavailable, the helper falls back to
`config/router.yaml` `policy.default_allowed_effects` and reports that fallback
explicitly in the output.

## Step 4: Execute

1. Determine OS: `OS` env = `Windows_NT` → use `windows` entrypoint, otherwise `unix`
2. Read the operation's `entrypoints` for your OS
3. Substitute `{param}` placeholders with actual values
4. Set cwd to the skill's directory
5. Run the command
6. Parse the **last line of stdout** as JSON — this is the result

Exit code ≠ 0 or last line not JSON → operation failed.

## Step 5: Chain Operations

When a goal requires multiple skills/operations:

1. Execute first operation → parse JSON output
2. Use output values as input to the next operation (you decide the mapping)
3. Repeat until goal is met

You are intelligent — adapt based on intermediate results. This is better than a fixed pipeline because you can handle errors, skip unnecessary steps, and make contextual decisions.

## Step 5.5: Orchestration Call Chain (Router → TKT → Workflow)

For complex goals that need multi-agent coordination, the router orchestrates three layers:

```
1. Router identifies TKT-worthy goal
2. TKT.create-bundle → decomposes into tickets (000 + workers + audit)
3. Workflow.plan → orders tickets into a DAG with dependency waves
4. Router dispatches each ticket's skill execution by wave order
5. TKT.update / TKT.close → tracks results and triggers review
```

**Decision matrix:**

| Goal Type | Route |
|-----------|-------|
| Single-skill, simple | Direct execute (Step 4) |
| Multi-step, single session | Workflow.plan → execute by wave |
| Multi-agent, cross-session | TKT.create-bundle → Workflow.plan → execute → TKT.close |

For workflow-only planning (no TKT), use `scripts/plan-with-workflow.md`.
For TKT-integrated planning, use the call chain above.

## Step 6: Log (Observability)

After non-trivial workflows, log for observability:

```sql
INSERT INTO skill_system.runs(task_spec_id, status, started_at, effective_policy)
VALUES (NULL, 'running', NOW(), '{}'::jsonb) RETURNING id;

INSERT INTO skill_system.run_events(run_id, level, event_type, payload)
VALUES (<run_id>, 'info', 'step_completed',
  jsonb_build_object('skill', '<id>', 'operation', '<op>', 'status', '<ok|error>', 'duration_ms', <ms>));

UPDATE skill_system.runs SET status='succeeded', ended_at=NOW(),
  metrics=jsonb_build_object('steps', <n>, 'duration_ms', <ms>) WHERE id=<run_id>;
```

Skip logging for simple single-operation calls.

## Step 7: Report Improvement Issue

When an agent notices reusable gaps, friction points, or unclear behavior in a skill/system flow, create a GitHub issue so the improvement is trackable.

Use `scripts/report-improvement-issue.md`.

When to report:
- Missing guardrails or policy checks discovered during execution
- Repeated user friction caused by unclear docs/entrypoints
- Reliability gaps (drift-prone steps, weak validation, poor observability)

Before creating a new issue, check for duplicates in open issues.

If a similar issue already exists, link that issue instead of creating a new one.

## Experiment Gate Delegation

For experiment validation and registry safety operations, delegate to `skill-system-gate`:

| Operation | Delegate to |
|---|---|
| Validate experiment code/logs against gate rules | `skill-system-gate` → `validate-experiment` |
| Check registry state safety before reset/rerun | `skill-system-gate` → `verify-registry` |
| Show experiment queue status and health | `skill-system-gate` → `status` |

## GitHub Operations Delegation

For general GitHub PM operations beyond improvement reporting, delegate to `skill-system-github`:

| Operation | Delegate to |
|---|---|
| Report improvement issue (during routing) | **This skill** — `report-improvement-issue` |
| Create/list/comment/close/reo