Project Index

Generate project context and codebase documentation for AI agents.

Workflow

initialize --> overview + summary

Each command can be used independently or chained via initialize.

Context Loading Strategy

Load only the reference matching the current trigger. Never load multiple references simultaneously.

Triggers

Trigger Pattern	Reference
Initialize project, setup project, index project	initialize.md
Overview, project context	overview.md
Summary, map codebase, analyze codebase	summary.md

Cross-References

initialize.md ----> overview.md
initialize.md ----> summary.md (if brownfield)
overview.md ------> root-agents.md (auto-update AGENTS.md)
summary.md -------> root-agents.md (auto-update AGENTS.md)

Output Structure

.agents/
├── project.md              # Project context (overview)
└── codebase/               # Codebase analysis (summary)
    ├── stack.md
    ├── architecture.md
    ├── conventions.md
    ├── testing.md
    ├── integrations.md
    ├── commands.md
    ├── checklist.md
    ├── workflows.md
    └── concerns.md          # Optional: tech debt, risks (only when issues detected)

AGENTS.md                   # Root file (auto-generated)

Templates

Document	Template
Project overview	project.md
Stack	stack.md
Architecture	architecture.md
Conventions	conventions.md
Testing	testing.md
Integrations	integrations.md
Commands	commands.md
Checklist	checklist.md
Workflows	workflows.md
Concerns	concerns.md

Output Size Budget

Keep generated docs concise. Agents load these into context -- every line costs tokens.

Document	Target	Max
project.md	~30 lines	50
stack.md	~20 lines	40
architecture.md	~50 lines	80
conventions.md	~30 lines	50
testing.md	~30 lines	50
integrations.md	~15 lines	30
commands.md	~20 lines	30
checklist.md	~15 lines	20
workflows.md	~30 lines	50
concerns.md	~15 lines	30
AGENTS.md	~60 lines	100

Total target: ~300 lines / ~12k tokens. Tables max 10 rows, lists max 7 items.

Integration with Other Skills

docs-writer (.artifacts/docs/) --> project-index (overview) consumes as context source
spec-driven (plan phase)       --> may add discoveries to .agents/codebase/
project-index (summary)        --> preserves spec-driven additions when re-running

• docs-writer: Overview checks .artifacts/docs/ for existing briefs, PRDs, design docs, pitches, and scopes. When found, uses them as primary context for generating project.md.
• spec-driven: Summary preserves discoveries added during planning. More specific context (from feature planning) takes precedence over general analysis.

Guidelines

DO:

• Read actual code files to extract patterns, not just list them
• Keep all outputs concise and scannable
• Document conventions as observed, not as prescribed
• Update existing docs when re-running (merge, never overwrite)

DON'T:

• Generate exhaustive catalogs of every component/file
• Include implementation details that change frequently
• Duplicate information across output files
• Create outputs without reading representative source files

Error Handling

• No source code found: Inform this is for existing projects
• Empty project: Skip summary, generate overview only
• .agents/ already exists: Ask if refresh needed