---
id: withkynam/vibecode-pro-max-kit/vc-context-discovery
version: "9564d67b"
license: MIT
install: manual
updated: 2026-06-21
---

# vc-context-discovery — vc-context-discovery is the canonical context-loading entry point for every agent session. It discovers and surfaces all nested files under process folders, extracts frontmatter metadata, and routes context by domain using keyword matching. Use the auto-discovery script or keyword-first routing to load exactly the docs your task needs.

Publisher: withkynam · Stars: 1058 · Updated: 2026-06-21

Install (manual): `git clone https://github.com/withkynam/vibecode-pro-max-kit`

## SKILL.md

# 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:**
```yaml
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:**
```yaml
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:**
```yaml
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):

```bash
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:

```bash
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:

```bash
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`.


[View on SkillFed](https://skillfed.io/withkynam/vibecode-pro-max-kit/vc-context-discovery) · [View on GitHub](https://github.com/withkynam/vibecode-pro-max-kit)