context-index

name

context-index

description

Regenerate .context/index.yaml from all .context/**/*.md frontmatter, and validate all files carry standard YAML frontmatter. Use when the index is stale, files were added or removed, or the pre-commit hook blocks on missing frontmatter. DO NOT use to create new context files (use context-file skill instead), to edit index.yaml by hand, or as a substitute for fixing frontmatter issues at the source. Triggers: 'update context index', 'regenerate index', 'context index stale', 'sync context', 'what context files exist', 'frontmatter missing', 'index .context'.

Context Index

Scan, validate, and index all .context/ files.

Prerequisites

• One or more .context/ files with valid or fixable YAML frontmatter
• The context-file skill to add or repair frontmatter on files that lack it
• Shell access to run the skill's scripts

Quick Start

# Regenerate the index
scripts/regenerate-context-index.sh

# Check staged files for missing frontmatter
scripts/check-context-frontmatter.sh .context/**/*.md

What It Does

1. Scans all .context/**/*.md files
2. Reads YAML frontmatter (title, type, status, date, related) from each
3. Writes .context/index.yaml — one entry per file, sorted by path
4. Prints any files missing required frontmatter to stderr (excluded from the index)

The generated index.yaml looks like:

plans:
  - path: ".context/plans/example-plan.md"
    title: "Example Plan"
    status: ACTIVE
    date: 2026-07-01
findings:
  - path: ".context/findings/topic-2026-07-01.md"
    title: "Finding: Topic"
    status: ACTIVE
    date: 2026-07-01

When to Use

• After creating, renaming, or deleting a .context/ file
• When the pre-commit hook blocks with "Missing YAML frontmatter"
• When asked "what plans / findings / analyses exist?"
• After bulk imports or retroactive frontmatter migration

When Not to Use

• Do not run this as a substitute for creating a missing file — create the file first using the context-file skill
• Do not edit .context/index.yaml by hand — it is fully generated and will be overwritten

Workflow

1. Run the check frontmatter script to list files missing frontmatter
2. For each file missing frontmatter: add it using the schema from the context-file skill
3. Run the regenerate index script to rebuild the index
4. If committing context files, also stage the index

# Full session example
./scripts/check-context-frontmatter.sh .context/**/*.md
./scripts/regenerate-context-index.sh
git add .context/index.yaml

Frontmatter Schema

Every .context/*.md file requires this frontmatter block (template at assets/templates/context-index-template.yaml):

---
title: "Human-readable title"
type: PLAN | finding | analysis
status: DRAFT | active | done | superseded
date: YYYY-MM-DD
related:
  - ../plans/related-plan.md   # omit entirely if no related files
---

Mindset

• The index is a cache — the source of truth is always the frontmatter in each .md file
• Regeneration is idempotent; when in doubt, regenerate
• Files with missing or malformed frontmatter are listed on stderr and excluded from the index — fix them first
• Optionally run the check script before regenerating to surface issues early
• Balance prescriptive rules (NEVER, ALWAYS) with permissive guidance: consider, optionally, may
• Use production-grade terminology: pitfall, gotcha, ALWAYS, NEVER, anti-pattern

Troubleshooting

• Index shows stale or missing entries: Re-run regenerate-context-index.sh — the index is a generated cache, not the source of truth
• Pre-commit hook blocks after creating a file: Run check-context-frontmatter.sh to identify files without frontmatter, add the block, then regenerate
• Script warnings on stderr: Files with warnings are excluded from the index — fix the frontmatter issues first, then regenerate

# Check for frontmatter issues before regenerating
./scripts/check-context-frontmatter.sh .context/**/*.md
# Fix any files reported, then regenerate
./scripts/regenerate-context-index.sh

Anti-Patterns

NEVER edit .context/index.yaml by hand. WHY: It is fully regenerated by regenerate-context-index.sh; manual edits will be overwritten on the next run. BAD: Adding or editing entries directly in index.yaml. GOOD: Update the source .md file frontmatter, then re-run regenerate-context-index.sh.

NEVER ignore stderr warnings from regenerate-context-index.sh. WHY: Files excluded from the index are invisible to agents reading it — they will miss active plans or findings. BAD: Running regenerate-context-index.sh with warnings and treating the output as the complete index. GOOD: Fix all warnings first, then regenerate.

NEVER rely on the index as the sole source of context file inventory. WHY: Files with missing or malformed frontmatter are silently excluded — the index is only complete when all files have valid frontmatter. BAD: Using the index output to determine what context files exist without first checking for warnings. GOOD: Run check-context-frontmatter.sh first, fix issues, then regenerate for a reliable inventory.

References

Topic	Reference	When to Use
Technical details, exit codes, and best practices for index regeneration	Regeneration Reference	Debugging index regeneration issues or setting up CI checks

Example Output

When all frontmatter is valid, regeneration produces output like:

Scanned: 12 files
Indexed: 12 entries
Errors:  0
Warnings: 0

On errors, the script lists problematic files on stderr — fix those and re-run.