context-index

Context Index

Scan, validate, and index every context file the project has captured.

Mindset

The index is a cache, never a ledger. The source of truth for what exists is always the YAML frontmatter inside each context file; the generated index is a derived summary that lets an agent answer "what plans/findings/decisions exist?" without reading every file. Because it is derived, regeneration is idempotent and safe to run whenever there is doubt about freshness — there is no state to corrupt, only a file to rewrite from scratch.

A file with missing or malformed frontmatter is not a formatting nitpick: it is invisible to every tool and agent that reads the index instead of the raw directory tree. Treat exclusion-from-index as the real failure mode, not the warning text that reports it. Balance that with proportionate language — flag the gap clearly (ALWAYS regenerate after a change, NEVER hand-edit the index) without turning every missing tag into a blocking emergency.

Prerequisites

• One or more context files, each with frontmatter that is valid or fixable.
• The create-context-file skill (companion to this one) to add or repair frontmatter on files that lack it, using its typology set and templates.
• Shell access (bash, python3, git) to run this skill's scripts.

When to Use

• After creating, renaming, or deleting a context file.
• When a pre-commit or CI gate blocks with a message like "missing YAML frontmatter" or "index is stale."
• When asked "what plans / findings / decisions / follow-ups exist?" — read the index rather than walking the directory tree by hand.
• After a bulk import, migration, or retroactive frontmatter cleanup touching many context files at once.

When Not to Use

• Do not run this as a substitute for creating a missing file — create it first with the create-context-file skill, which owns the filename and frontmatter shape.
• Do not edit the generated index by hand — it is fully regenerated and any manual edit is silently overwritten on the next run.
• Do not treat a clean regeneration as proof every context file is meaningful or current — it only proves the frontmatter parses; stale content still needs a human to retire it.