# Context Index

> 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'.

- Skill: `pantheon-org/context-index-2` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add pantheon-org/context-index-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pantheon-org/context-index-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pantheon-org (https://skillmd.com/u/pantheon-org)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/pantheon-org/context-index-2

---


# 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

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

```yaml
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

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

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

```bash
# 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](references/regeneration-reference.md) | Debugging index regeneration issues or setting up CI checks |

## Example Output

When all frontmatter is valid, regeneration produces output like:

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

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