feat(agents): knowledge router + org-guidance & practice-knowledge skills (#38)

## What

Extends the knowledge system beyond Project Index (the only covered
class, ~30% of the Slack KG questions) to the top two uncovered classes
from the [Slack KG Question
Analysis](https://docs.google.com/document/d/1UDuazl1APUQedT2AcIUtGX47qIA3dd8gk5pxiRR8u9I/edit):
**Sage/org guidance** (149 q) and **Practice knowledge** (93 q).

The single `LIK Query: Project Index` agent is replaced by a **Knowledge
Search Agent** — a router that classifies a question and dispatches to
the matching query skill.

## Skills

- **`query-project-index`** (existing) — projects.
- **`query-org-guidance`** (new) — org standards, process, templates,
tool/license access. Confluence spaces `NH, BB, PD, ENG`; follows hub
pages to Drive templates; answers "does Nava have license X" by evidence
only (no central inventory exists).
- **`query-practice-knowledge`** (new) — discipline craft how-to.
Practice spaces `DOH, PL, ENG, PM1, NL, TSS` + community-of-practice
Slack channels; labels *documented practice* vs *peer discussion*.

Space assignments were derived by reading each Confluence space's home
page. `ENG` intentionally serves both topics. The empty `IT` space was
dropped. Both new skills reuse the project-index marker recipe,
integrity guard, and confirmation-weighted ranking/feedback.

Error handling across all skills + the router switched from
**stop-on-failure** to **report-and-continue**.

## Rename: drop the `lik-` prefix

The Claude workspace is single-tenant for this app, so no namespacing is
needed. Renamed all skill directories/frontmatter and agent file stems,
and updated every in-repo reference, deploy-workflow option, CLAUDE.md
rule, and doc. Historical `docs/plans` / `docs/brainstorms` left
untouched.

## Notes / follow-ups

- The old **"LIK Query: Project Index"** platform agent is not pruned by
deploy (glob + create/update, no delete) — left live intentionally.
- `deploy-skills.yml` retained for standalone skill updates;
`deploy_agents.py` still deploys each agent's referenced skills.
- New skills use **live source search** (no Catalog rows yet) — a later
pass could catalog org-guidance for confirmation-weighted ranking.

## Test

`deploy` + `lik-ui` agent/skill/init suites pass (SDK faked, no
network).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: yoomlam

.github/workflows/deploy-agents.yml

@@ -21,9 +21,9 @@ on:
         type: choice
         options:
           - all
-          - lik-query-project-index
-          - lik-cross-source-reference
-          - lik-catalog-registration
+          - knowledge-search
+          - cross-source-reference
+          - catalog-registration
         default: all
 
 permissions:

.github/workflows/deploy-skills.yml

@@ -19,8 +19,10 @@ on:
         type: choice
         options:
           - all
-          - lik-query-project-index
-          - lik-sync-catalog-from-project-indexes
+          - query-project-index
+          - query-org-guidance
+          - query-practice-knowledge
+          - sync-catalog-from-project-indexes
         default: all
 
 permissions:

CLAUDE.md

@@ -8,8 +8,8 @@
 
 * **Never commit or push to `main` without asking first.** All changes go through a branch and PR. Before every commit or push, check the current branch (`git branch --show-current`) — if it's `main`, stop and ask. This applies even for one-line follow-up fixes; a merged PR often leaves the checkout back on `main`.
 * **Re-check the current branch right before any git write (commit, push, branch, checkout), not once at the start.** The user switches branches while Claude is working, so the branch you saw earlier may be stale by the time you act. Never assume the checkout is still on the branch you created or expected — run `git branch --show-current` immediately before the write and confirm it's the intended one.
-* Prefix all skill names with `lik-` (e.g. `lik-query-project-index`). Applies to the skill directory under `claude_platform/skills/` and its `name:` frontmatter.
-* Managed Agents resources are GitHub-sourced under `claude_platform/`: `skills/` (skill dirs), `agents/` and `environments/` (the platform's raw export YAML). Agents reference skills, and lik-ui references agents/environments, **by name** — no platform ids in the repo. Deploy skills via `deploy-skills.yml` and agents+environments via `deploy-agents.yml` (both manual dispatch); see `scripts/README.md`.
+* Skill and agent names carry **no** `lik-` prefix (e.g. skill dir `query-project-index`, agent file `knowledge-search.yaml`). The Claude workspace is single-tenant for this app, so no namespacing is needed. Applies to skill directories + their `name:` frontmatter and agent file stems.
+* Managed Agents resources are GitHub-sourced under `claude_platform/`: `skills/` (skill dirs), `agents/` and `environments/` (the platform's raw export YAML). Agents reference skills, and lik-ui references agents/environments, **by name** — no platform ids in the repo. Deploy a skill on its own via `deploy-skills.yml`; deploy agents+environments (with each agent's referenced skills) via `deploy-agents.yml` (both manual dispatch); see `scripts/README.md`.
 * Wrap `SKILL.md` prose at a 120-character line limit. Exceptions that stay on one line: YAML frontmatter values (e.g. the `description`), table rows, and fenced code.
 * The software is being implemented based on the docs in the `v0.5` folder.
     - As code is being written ensure it aligns with the goals and intent of those docs.

…orm/agents/lik-catalog-registration.yaml …latform/agents/catalog-registration.yamlclaude_platform/agents/lik-catalog-registration.yaml renamed to claude_platform/agents/catalog-registration.yaml claude_platform/agents/lik-catalog-registration.yaml renamed to claude_platform/agents/catalog-registration.yaml

@@ -14,15 +14,15 @@ model:
 description: >
   Registers entries into the Discovery Layer Catalog (the lik-mcp service) from their source of
   truth. Today it can catalog Project Indexes — crawling the project-index pages in Confluence and
-  upserting one Catalog row per page — via the lik-sync-catalog-from-project-indexes skill. More
+  upserting one Catalog row per page — via the sync-catalog-from-project-indexes skill. More
   cataloging skills, for other topics, will be added over time.
 system: >
   You are the Catalog Registration Agent for Nava. Your job is to register entries into the
   Discovery Layer Catalog (the lik-mcp service) from their authoritative source, using whichever
   cataloging skill matches what the user asked to catalog.
 
   Available cataloging skills:
-  - lik-sync-catalog-from-project-indexes — catalog Project Indexes. Use it whenever the user asks
+  - sync-catalog-from-project-indexes — catalog Project Indexes. Use it whenever the user asks
     to catalog, sync, or (re)build the project indexes / the project-index catalog. It crawls the
     Confluence pages tagged `project-index` and upserts one Catalog row per page. It writes only to
     the Catalog, never back to Confluence.
@@ -66,5 +66,5 @@ tools:
 # Divergence from the raw export: skills are referenced by NAME (the skill's directory under
 # claude_platform/skills/), not skill_id. deploy_agents.py resolves name -> skill_id at deploy.
 skills:
-  - name: lik-sync-catalog-from-project-indexes
+  - name: sync-catalog-from-project-indexes
 metadata: {}

…m/agents/lik-cross-source-reference.yaml …tform/agents/cross-source-reference.yamlclaude_platform/agents/lik-cross-source-reference.yaml renamed to claude_platform/agents/cross-source-reference.yaml claude_platform/agents/lik-cross-source-reference.yaml renamed to claude_platform/agents/cross-source-reference.yaml

@@ -0,0 +1,125 @@
+# Managed Agent spec — deployed to the Claude platform by scripts/deploy_agents.py.
+#
+# This is the platform's raw agent export/import YAML (the shape beta.agents.create/update
+# consumes), with ONE divergence: `skills` entries reference a skill by *name*, not skill_id.
+# The deploy resolves each name to its platform skill_id (created by deploy_skills.py) and pins
+# `version: "latest"` before the SDK call — so no skill_ids live in the repo. The `name:` field
+# below is the platform identity the deploy and lik-ui match on (create-if-absent, else update).
+name: "Knowledge Search Agent"
+model:
+  effort:
+    type: high
+  id: claude-sonnet-5
+  speed: standard
+description: >
+  Answers a Nava delivery-knowledge question by routing it to the right specialized query skill —
+  project history, organizational guidance (standards, process, templates, tool/license access), or
+  practice craft how-to. Classifies the question first, then runs the matching skill and returns its
+  cited, confirmation-weighted answer. Names what it can't yet cover and points elsewhere.
+system: >
+  You are the Knowledge Search Agent for Nava. A person brings you a delivery-knowledge question;
+  your job is to classify it and route it to the ONE query skill built for that kind of question,
+  then let that skill do the work. You are a router, not an answerer — the skills own the retrieval,
+  citation, ranking, and feedback; you pick the right one and hand off.
+
+  Available query skills, and the questions each owns:
+  - query-project-index — Nava's PROJECTS: what a team has done, scope, impact, client, CPARS,
+    workstreams, capabilities, tech stack, artifacts, research, case studies, BD assets. Use for
+    "has anyone done X?", "which projects involve Y?", "what tech did project Z use?", "who worked
+    on it?".
+  - query-org-guidance — ORGANIZATIONAL guidance that applies across projects: standards,
+    processes, approval paths, templates and kickoff artifacts, and tool/license/vendor access.
+    Use for "what is Nava's policy on X?", "is there a process for Y?", "does Nava have a license
+    for Z / how do I get access?", "where's the template for W?". Its sources today are Nava's
+    Confluence guidance spaces (the Sage handbook and the org handbooks), but treat those as its
+    sources, not the question's subject.
+  - query-practice-knowledge — CRAFT how-to by discipline (design, engineering, research,
+    accessibility, content, AI technique): "how do you approach X?", "what's the best practice for
+    Y?", "what tool do people recommend for Z?". This is peer craft knowledge, distinct from a named
+    project's work.
+
+  How to route:
+  1. Classify the question into exactly one of the three domains above. If it clearly spans two
+     (e.g. "what tech stack do teams use AND what's the recommended practice"), pick the primary
+     domain, run that skill, then offer to run the second.
+  2. If the domain is ambiguous, ask ONE short single-letter / numbered question to disambiguate
+     rather than guessing.
+  3. Run the matching skill and follow it EXACTLY — its staged escalation, its Response integrity
+     guard and content-state marker recipe, its citation and confirmation-weighted ranking, and its
+     feedback step. Return its answer as-is; do not add an uncited summary on top.
+
+  Questions you cannot yet cover — name the gap plainly, don't improvise:
+  - Government/domain context ("how does the VA Contention Classifier work?"), finding a PERSON or
+    certification, and reporting broken content have NO dedicated skill yet. Say so, and suggest the
+    Cross-Source Referencing Agent as a general fallback.
+  - HR / operations / benefits questions (timesheets, expense codes, PD budgets, perks) are out of
+    scope for delivery knowledge; say so and point to People Ops rather than searching.
+
+  If a tool call fails or a required source is unavailable, do not stop — report the error, its
+  likely cause, and the remedy, and continue with whatever the chosen skill can still do. Do not
+  silently switch to a different skill to paper over a failure; surface the gap and provide options to the user.
+mcp_servers:
+  - name: lik-mcp
+    type: url
+    url: https://mcp.lik.navapbc.com/mcp
+  - name: atlassian
+    type: url
+    url: https://mcp.atlassian.com/v1/mcp
+  - name: google-drive-drivemcp
+    type: url
+    url: https://drivemcp.googleapis.com/mcp/v1
+  - name: slack
+    type: url
+    url: https://mcp.slack.com/mcp
+  - name: github
+    type: url
+    url: https://api.githubcopilot.com/mcp
+tools:
+  - configs: []
+    default_config:
+      enabled: true
+      permission_policy:
+        type: always_allow
+    type: agent_toolset_20260401
+  - configs: []
+    default_config:
+      enabled: true
+      permission_policy:
+        type: always_allow
+    mcp_server_name: lik-mcp
+    type: mcp_toolset
+  - configs: []
+    default_config:
+      enabled: true
+      permission_policy:
+        type: always_allow
+    mcp_server_name: atlassian
+    type: mcp_toolset
+  - configs: []
+    default_config:
+      enabled: true
+      permission_policy:
+        type: always_allow
+    mcp_server_name: google-drive-drivemcp
+    type: mcp_toolset
+  - configs: []
+    default_config:
+      enabled: true
+      permission_policy:
+        type: always_allow
+    mcp_server_name: slack
+    type: mcp_toolset
+  - configs: []
+    default_config:
+      enabled: true
+      permission_policy:
+        type: always_allow
+    mcp_server_name: github
+    type: mcp_toolset
+# Divergence from the raw export: skills are referenced by NAME (the skill's directory under
+# claude_platform/skills/), not skill_id. deploy_agents.py resolves name -> skill_id at deploy.
+skills:
+  - name: query-project-index
+  - name: query-org-guidance
+  - name: query-practice-knowledge
+metadata: {}