vc-context-discovery

vc-context-discovery

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Discover and load all relevant context for the current task. This skill lists feature group nested files with full paths and loads process/context/ files by domain routing table. It is the canonical context-loading entrypoint for every agent session.

When To Invoke

At the start of every agent session (research, innovate, plan, validate, execute, update-process, fast-mode). Also at the start of any skill that needs repo context before operating.

Frontmatter Schemas

Document the canonical schemas for three file types used across the repo. These schemas enable frontmatter-aware routing and filtering.

Context file frontmatter schema:

name: context:{slug}
description: "one-line scope — used by vc-context-discovery for routing"
keywords: comma, separated, task, vocabulary, terms   # drives grep-first keyword routing
related: [context:{other-slug}, context:{another-slug}]  # sibling/cross-group links (optional)
date: dd-mm-yy

• keywords — strongly recommended, non-empty. Comma-separated task-vocabulary terms an agent would use to describe a task this doc serves (e.g. session, token, refresh, jwt, login). This is the match surface for discover-context.mjs --match; weak/absent keywords are why a relevant doc never gets routed to. Lint WARNS when empty (so existing projects don't break on sync) — backfill at UPDATE-PROCESS.
• related — OPTIONAL list of context:{slug} values for sibling docs that are usually needed together (the markdown-native equivalent of cross-links). Every slug listed MUST resolve to a real context: doc; dangling links fail lint. Discovery follows these after the primary match so a task touching two domains loads both.

Plan file frontmatter schema:

name: plan:{slug}
description: "one-line scope and feature"
date: dd-mm-yy
feature: {feature-folder-name}
phase: "{phase-id}"  # optional, for phase program plans only

Report file frontmatter schema:

name: report:{slug}
description: "one-line scope"
date: dd-mm-yy
metadata:
  node_type: memory
  type: report
  feature: {feature-folder-name}
  phase: {phase-id}

Invocation

Primary method — run the auto-discovery script. It lists all nested files under process/context/, process/development-protocols/, process/general-plans/active/, and (with --feature) the feature folder, extracting ONLY the leading YAML frontmatter block of each .md file (no whole-file reads):

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs [--feature <name>] [--json]

The script groups output into: context files with frontmatter, protocol files, feature files by subfolder, active general plans, and files-without-frontmatter (path only). It never throws on a missing root and exits 0 unless given a bad flag. Use --json for a machine-readable object. Prefer this over manually reading each file — it is deterministic and avoids loading huge files into context.

Keyword-first routing (deterministic, not judgment). When the task vocabulary does not obviously map to a routing-table row, do not guess — let the index do the matching:

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --match "update the user ORM model"

This tokenizes the task and ranks context docs by overlap with their frontmatter keywords, then appends any related: siblings of the top hits. Read the ranked docs in order. This is the fallback that fixes "the right doc existed but the agent walked past it."

Routing-table generation (drift-proof index). The "Current Root Entry Points" and "Current Context Groups" tables in all-context.md are GENERATED from frontmatter, not hand-authored — they live between <!-- GENERATED:routing --> / <!-- /GENERATED:routing --> markers. Rebuild them after any context-org change:

node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --emit-routing   # rewrites the block
node .claude/skills/vc-context-discovery/scripts/discover-context.mjs --check-routing  # lint: block in sync?

The hand-authored Task Routing Table (task-type → file) stays editorial and is NOT generated.

Per task-folder artefact colocation, the script surfaces each task's plan, spec, reports, and references INSIDE its own {slug}_{date}/ task folder; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Workflow (manual FALLBACK)

Use these steps only if the script above fails or is unavailable.

Step 1. Run find process/context/ -type f | sort and record all available context files.

Step 2. Run find process/development-protocols/ -type f | sort and record all protocol files.

Step 3. Read process/context/all-context.md to get the routing table and current feature list.

Step 4. If a feature name was provided as the argument, run find process/features/{feature}/ -type f | sort to list ALL artifacts across all subfolders (active/, completed/, backlog/, plus any legacy reports/, references/). Surface full file paths — not just folder names. Per task-folder artefact colocation, expect each task's plan, spec, reports, and references INSIDE its own {slug}_{date}/ task folder; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Step 5. If no feature name was provided, run find process/general-plans/active/ -type f | sort to surface any active plans relevant to the current task. Note: plan files are inside {slug}_{date}/ task subfolders — look one level deep for *_PLAN_*.md files.

Step 6. From the routing table in all-context.md, identify the context group files relevant to the current task domain (e.g. tests, container, infra, skills, uxui, workflows). Do NOT read every context file — only the ones the routing table says apply to this domain. If no row obviously matches, run discover-context.mjs --match "<task>" and use its ranked keyword hits instead of guessing.

Step 7. Read the domain context file(s) identified in step 6. Each all-{group}.md is a router — after reading it, follow its routing table to load the deeper domain file(s) for the task. Then load any related: siblings of the docs you read — a task spanning two domains (e.g. auth + tests) needs both, and related is how the cross-domain link is declared.

Step 8. Frontmatter extraction: For each file in the discovered set, if the file has YAML frontmatter (a --- block at top), extract the name, description, and date fields. Surface in output as "[path] (name: X — description: Y)". Files without frontmatter: surface path only (no error, do not skip them).

Step 9. Report: full file listing for the feature folder (if applicable), active context files loaded, and any open gaps in context that would block the task.

Output Format

Context file paths with frontmatter:
  process/context/skills/skill-apps.md (context:skill-apps — Skill app runtime, vite architecture, ctx-gateway, deployment)
  process/context/tests/all-tests.md (context:all-tests — Test routing, runner split, debugging procedures)

Plan files with frontmatter:
  process/features/{feature}/completed/{slug}_{date}/{slug}_PLAN_{date}.md (plan:{plan-name} — short description...)

Files without frontmatter (path only):
  process/context/ui/design.md

Context Envelope

At session start, every inner-loop agent (research / plan / execute / update-process) emits a Context Envelope — a 10-field table capturing the orientation an agent needs to act. All 10 fields are required (use best-effort values; TBD — [reason] when not yet determinable). The fields MUST appear in the EXACT canonical C-2 order below — identical order in this SKILL and in all four inner-loop agents:

#	Field	Value
1	feature	feature folder name (or TBD)
2	phase	current RIPER phase (RESEARCH / INNOVATE / PLAN / PVL / EXECUTE / EVL / UPDATE-PROCESS)
3	session-goal	one-line goal from the /goal block
4	branch	current git branch
5	worktree	worktree path (or main)
6	context-group	relevant process/context/ group (or none)
7	blast-radius-packages	packages/paths in scope (comma-separated or TBD)
8	active-plan	selected plan file path (or none)
9	test-runner	test runner(s); multi-runner uses pipe-delimited DISPLAY format bun test | vitest
10	validate-contract	validate-contract path (or none)

Canonical order (memorize): feature → phase → session-goal → branch → worktree → context-group → blast-radius-packages → active-plan → test-runner → validate-contract.

test-runner multi-runner rule: the pipe-delimited bun test | vitest value is a DISPLAY convention only. The phase-loop workflow template (.claude/skills/vc-generate-phase-program/templates/phase-loop-workflow-template.js) expands it into SEQUENTIAL test steps (bun test THEN vitest) — a literal bun test | vitest shell pipe is NEVER emitted or run. See 03-session-start.md for the matching field table.

Frontmatter-Aware Routing

After collecting file paths, read YAML frontmatter from each file where present.

Surface the following fields alongside path: name, description, keywords, related, date, type, feature, phase.

Use the description and keywords fields for routing decisions instead of filename inference.

Group plan files by their feature field value.

Filter and sort by type field (context / plan / report / references).

Discover all nested files under feature group subdirs: active/, completed/, backlog/, reports/, references/.

Files without frontmatter: surface path only (no error), do not skip them.

Important Rules

• This skill is INDEPENDENT — it does not invoke other skills.
• Read all-context.md as a router, then load the deeper file(s). Do not treat all-context.md as sufficient on its own.
• Always produce the full find output, not a summary. The exact file paths are the output.
• Never hardcode context file paths — always discover via the find command and the routing table in all-context.md.