Context Keeper

Maintains project context through layered documentation and enforced synchronization.

Overview

Context Keeper implements a three-level documentation system that ensures AI agents always have accurate, up-to-date context about the codebase:

1. USERAGENTS.md - Project-level: structure, conventions, and directory index
2. TECH_INFO.md - Directory-level: file descriptions, dependencies, and changes
3. File headers - File-level: function descriptions, parameters, and modification dates

When to Use This Skill

• Project initialization: Run scan_project.py to generate initial documentation
• Before modifying code: Read the relevant TECH_INFO.md first
• After completing changes: Update TECH_INFO.md and file headers
• When project structure changes: Update USERAGENTS.md

Key Design Decisions

• On-demand TECH_INFO.md generation: Documentation is only created for directories where the AI actually works, avoiding unnecessary files
• Event-driven maintenance: Hooks track file modifications and automatically prompt AI to update documentation at session end
• No git commits: TECH_INFO.md files are excluded from version control (local context only)
• Full directory depth: No artificial depth limitation - documentation scales with the project
• Language: All generated content is in English for international teams

Workflow

Phase 1: Initialize Project Context

Run the scanner to generate initial documentation:

python scripts/scan_project.py <project-path>

The script will:

1. Detect tech stack (TypeScript, React, Go, Python, etc.)
2. Infer coding conventions based on tech stack
3. Generate USERAGENTS.md with project structure
4. Note: TECH_INFO.md files are NOT pre-generated - they are created on-demand when you work in a directory
5. Update AGENTS.md/CLAUDE.md with enforcement instructions
6. (Optional) Install hooks to automatically track changes and enforce documentation updates

Use --dry-run to preview changes without modifying files.

Phase 2: On-Demand TECH_INFO.md Creation

When you start working in a directory that doesn't have TECH_INFO.md:

1. Check if the directory has a TECH_INFO.md file
2. If not, create it using the template format
3. Fill in the descriptions based on your analysis of the code in that directory

The template structure:

# [Directory Name] - Technical Documentation

> **Directory purpose**: [Your analysis based on file contents]
> **Last updated**: YYYY-MM-DD

---

## 📁 File Inventory

| Filename | Description | Input | Output | Dependencies |
|----------|-------------|-------|--------|--------------|
| file1.ts | [Accurate description] | Type | Type | ./other-file |

---

## 🔄 Change Log

| Date | Change | Operator |
|------|--------|----------|
| YYYY-MM-DD | [What you changed] | context-keeper |

Phase 3: Before Any Code Modification

Before modifying any file, follow this checklist:

Pre-modification checklist:
- [ ] Read USERAGENTS.md to understand project conventions
- [ ] Read target directory's TECH_INFO.md
- [ ] Understand file dependencies from TECH_INFO.md
- [ ] Review file header comments for context

Phase 4: After Code Modification

After completing changes, update documentation:

Post-modification checklist:
- [ ] Update file header (@description, @lastModified)
- [ ] Update TECH_INFO.md file table if file added/changed
- [ ] Add change record to TECH_INFO.md
- [ ] Update USERAGENTS.md if directory structure changed

Phase 5: Automatic Enforcement (via Hooks)

When the session ends, the stop.sh hook will:

1. Check which files were modified during the session
2. Group them by directory
3. Display a mandatory action list requiring you to update documentation
4. Block session completion (in --strict mode) until documentation is updated

This ensures documentation is never forgotten, even when using multiple skills.

Installation & Setup

1. Install Dependencies

# No external dependencies required - uses Python standard library only
python3 --version  # Requires Python 3.7+

2. Initialize Documentation

# Generate initial USERAGENTS.md
python scripts/scan_project.py /path/to/your/project

# Preview without changes
python scripts/scan_project.py /path/to/your/project --dry-run

3. (Optional) Install Hooks

Configure hooks in your Claude Code settings:

{
  "hooks": {
    "PostToolUse": "/absolute/path/to/context-keeper/hooks/post_tool_use.sh",
    "Stop": "/absolute/path/to/context-keeper/hooks/stop.sh --strict"
  }
}

What the hooks do:

• PostToolUse: Tracks file modifications (edit_file, write, create, delete)
• Stop: Displays mandatory documentation tasks before session end
• --strict flag (optional): Blocks session completion until docs are updated

Dependencies & Runtime

• Python 3.7+ required: scripts/scan_project.py uses only the Python standard library
• No external packages: Safe to run in restricted environments
• Git required: For .gitignore parsing and tracking changes

Documentation Templates

TECH_INFO.md Template

See references/tech_info_template.md for the standard template.

File Header Template

/**
 * @file filename.ts
 * @description Function description
 * @module ModuleName
 * @dependencies ./dependency1, ./dependency2
 * @lastModified YYYY-MM-DD
 */

USERAGENTS.md Sections

See references/useragents_template.md for the standard structure.

Coding Conventions by Tech Stack

The scanner automatically infers conventions based on detected tech stack. Common rules include:

TypeScript/JavaScript:

• Do not use any type - use unknown for unknown types
• All functions must have explicit return type declarations
• Use interface for objects, type for unions and complex types
• Enable all strict mode checks

React:

• Use function components and Hooks only
• PascalCase for component files
• Use React.memo() for optimization
• Use useMemo/useCallback to avoid unnecessary re-renders

Go:

• Follow Go official coding standards (Effective Go)
• Always handle errors explicitly
• Use gofmt for formatting

Python:

• Follow PEP 8 coding standards
• Use type hints
• Use f-strings and pathlib

Common (all projects):

• Do not use native fetch directly - use wrapped HTTP utility
• Do not hardcode sensitive information
• All async operations must have proper error handling

Enforcement Mechanism

The skill adds mandatory instructions to AGENTS.md/CLAUDE.md:

1. Pre-read requirement: Agent must read USERAGENTS.md and relevant TECH_INFO.md before any modification
2. Post-update requirement: Agent must update documentation after any modification
3. Structure sync: Agent must check if USERAGENTS.md needs updating after task completion
4. Hook enforcement: Stop hook displays mandatory action list when files were modified

File Structure

project/
├── AGENTS.md          # Contains enforcement instructions
├── USERAGENTS.md      # Project-level context (auto-generated)
├── .context-keeper/
│   └── pending.txt    # Tracks modified files (created by hooks)
├── src/
│   ├── TECH_INFO.md   # Directory-level documentation (created on-demand)
│   ├── components/
│   │   ├── TECH_INFO.md
│   │   └── Button.tsx # With file header comments
│   └── utils/
│       ├── TECH_INFO.md
│       └── http.ts
└── .gitignore         # Contains TECH_INFO.md and .context-keeper/

Notes

• TECH_INFO.md files are added to .gitignore by default (local context only)
• USERAGENTS.md can be committed if desired for team sharing
• The scanner can be re-run to refresh documentation
• On-demand generation means only directories you actually work in will have documentation
• Hooks ensure documentation is updated even when using multiple skills