vc-plan-discovery

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

Invocation

Primary method — run the auto-discovery script. It applies the Scope Rules below (same-feature full depth; other features active-only; general-plans active always) and extracts ONLY the leading YAML frontmatter block of each .md file (no whole-file reads):

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

It groups output into Active Plans / Backlog / Completed / Reports / References (each line: - [name]: description (path)) and prints a trailing Found N active, N backlog, N completed, N reports, N references line. 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 the manual scan below — it is deterministic and avoids loading huge files into context.

Per task-folder artefact colocation, the script scans one level into each {slug}_{date}/ task folder and surfaces co-located _PLAN_/_REPORT_/_REF_ artefacts; the sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

The manual scan in Scope Rules below is the FALLBACK for when the script fails.

Purpose

Surface all plans relevant to the current task so agents have full plan context — what was tried, what is in progress, what is deferred, and what reports and references exist — before doing any phase work.

Scope Rules

• Same feature folder (from task context or argument): read ALL of active/, backlog/, completed/, plus any legacy sibling reports/, references/ — surface every file with frontmatter
• Other feature folders: read active/ only — surface plans whose frontmatter description or feature field matches the task domain
• general-plans/active/: always scan
• general-plans/completed/, legacy reports/, references/: scan only when same-feature folder is not identified

Per task-folder artefact colocation, expect every current artefact (plan, spec, reports, references) INSIDE its {slug}_{date}/ task folder — scan one level into each task folder. The sibling reports//references/ dirs are deprecated and only hold legacy artefacts.

Frontmatter Reading

Read frontmatter fields: name, description, type, feature, phase

Route by description field for relevance matching (same approach as vc-context-discovery).

Skip files without frontmatter or with incomplete frontmatter — log as "no frontmatter, skipped".

Output: grouped list by folder — Active Plans / Backlog / Completed / Reports / References — with name + description per file.

When To Invoke

• First action alongside vc-context-discovery at the start of every loop step (research / validate / execute / update-process)
• Any time an agent needs to know: what plans exist for this feature, what was tried before, what is deferred, what references exist

Output Format

### Active Plans
- [name]: description (path)

### Backlog
- [name]: description (path)

### Completed
- [name]: description (path)

### Reports
- [name]: description (path)

### References
- [name]: description (path)

Found N active, N backlog, N completed, N reports, N references