Context Index

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

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.