Context Files

.context/¶

Each context file in .context/ serves a specific purpose.

Files are designed to be human-readable, AI-parseable, and token-efficient.

File Overview¶

The core context files live directly under .context/. They are the substrate ctx reads in priority order when assembling the agent context packet:

Two subdirectories under .context/ are implementation details that are user-editable but not part of the priority read order:

• .context/templates/ — format templates for ctx add decision and ctx add learning. See templates below.
• .context/steering/ — behavioral rules with YAML frontmatter that get synced into each AI tool's native config. See steering below, and the full Steering files page for the design and workflow.

Outside .context/¶

Two other moving parts are often confused with context files but are not under .context/:

• Skills live in .claude/skills/ (project-local) or are provided by the installed ctx plugin. A typical project doesn't see the plugin's skills at all — they ride with the plugin and are owned by its update cycle. See ctx skill and Skills reference.
• Hooks are Claude Code PreToolUse/PostToolUse/ UserPromptSubmit entries configured in .claude/settings.json or shipped by a plugin. The ctx plugin registers its own hooks automatically; a typical project does not author hooks by hand, and any local edits to plugin-owned hook files will be overridden on the next plugin update. If you need to customize behavior, edit your own project settings, not the plugin's files. See Hook sequence diagrams.

Read Order Rationale¶

The priority order follows a logical progression for AI tools:

1. CONSTITUTION.md: Inviolable rules first. The AI tool must know what it cannot do before attempting anything.
2. TASKS.md: Current work items. What the AI tool should focus on.
3. CONVENTIONS.md: How to write code. Patterns and standards to follow when implementing tasks.
4. ARCHITECTURE.md: System structure. Understanding of components and boundaries before making changes.
5. DECISIONS.md: Historical context. Why things are the way they are, to avoid re-debating settled decisions.
6. LEARNINGS.md: Gotchas and tips. Lessons from past work that inform the current implementation.
7. GLOSSARY.md: Reference material. Domain terms and abbreviations for lookup as needed.
8. AGENT_PLAYBOOK.md: Meta instructions last. How to use this context system itself. Loaded last because the agent should understand the content (rules, tasks, patterns) before the operating manual.

CONSTITUTION.md¶

Purpose: Define hard invariants: Rules that must NEVER be violated, regardless of the task.

AI tools read this first and should refuse tasks that violate these rules.

Structure¶

# Constitution

These rules are INVIOLABLE. If a task requires violating these, the task 
is wrong.

## Security Invariants

* [ ] Never commit secrets, tokens, API keys, or credentials
* [ ] Never store customer/user data in context files
* [ ] Never disable security linters without documented exception

## Quality Invariants

* [ ] All code must pass tests before commit
* [ ] No `any` types in TypeScript without documented reason
* [ ] No TODO comments in main branch (*move to `TASKS.md`*)

## Process Invariants

* [ ] All architectural changes require a decision record
* [ ] Breaking changes require version bump
* [ ] Generated files are never committed

Guidelines¶

• Keep rules minimal and absolute
• Each rule should be enforceable (can verify compliance)
• Use checkbox format for clarity
• Never compromise on these rules

TASKS.md¶

Purpose: Track current work, planned work, and blockers.

Structure¶

Tasks are organized by Phase: logical groupings that preserve order and enable replay.

Tasks stay in their Phase permanently; status is tracked via checkboxes and inline tags.

# Tasks

## Phase 1: Initial Setup

* [x] Set up project structure
* [x] Configure linting and formatting
* [ ] Add CI/CD pipeline `#in-progress`

## Phase 2: Core Features

* [ ] Implement user authentication `#priority:high`
* [ ] Add API rate limiting `#priority:medium`
  * Blocked by: Need to finalize auth first

## Backlog

* [ ] Performance optimization `#priority:low`
* [ ] Add metrics dashboard `#priority:deferred`

Key principles:

• Tasks never move between sections: mark as [x] or [-] in place
• Use #in-progress inline tag to indicate current work
• Phase headers provide structure and replay order
• Backlog section for unscheduled work

Tags¶

Use inline backtick-wrapped tags for metadata:

Lifecycle tags (for session correlation):

These timestamps help correlate tasks with session files and track which session started vs completed work.

Status Markers¶

Guidelines¶

• Never delete tasks; mark as [x] completed or [-] skipped
• Never move tasks between sections; use inline tags for status
• Use ctx task archive periodically to move completed tasks to archive
• Mark current work with #in-progress inline tag

DECISIONS.md¶

Purpose: Record architectural decisions with rationale so they don't get re-debated.

Structure¶

# Decisions

## [YYYY-MM-DD] Decision Title

**Status**: Accepted | Superseded | Deprecated

**Context**: What situation prompted this decision?

**Decision**: What was decided?

**Rationale**: Why was this the right choice?

**Consequence**: What are the implications?

**Alternatives Considered**:
* Alternative A: Why rejected
* Alternative B: Why rejected

Example¶

## [2025-01-15] Use TypeScript Strict Mode

**Status**: Accepted

**Context**: Starting a new project, need to choose the type-checking level.

**Decision**: Enable TypeScript strict mode with all strict flags.

**Rationale**: Catches more bugs at compile time. Team has experience
with strict mode. Upfront cost pays off in reduced runtime errors.

**Consequence**: More verbose type annotations required. Some
third-party libraries need type assertions.

**Alternatives Considered**:
- Basic TypeScript: Rejected because it misses null checks
- JavaScript with JSDoc: Rejected because tooling support is weaker

Status Values¶

LEARNINGS.md¶

Purpose: Capture lessons learned, gotchas, and tips that shouldn't be forgotten.

Structure¶

# Learnings

## Category Name

### Learning Title

**Discovered**: YYYY-MM-DD

**Context**: When/how was this learned?

**Lesson**: What's the takeaway?

**Application**: How should this inform future work?

Example¶

## Testing

### Vitest Mocks Must Be Hoisted

**Discovered**: 2025-01-15

**Context**: Tests were failing intermittently when mocking fs module.

**Lesson**: Vitest requires `vi.mock()` calls to be hoisted to the
top of the file. Dynamic mocks need `vi.doMock()` instead.

**Application**: Always use `vi.mock()` at file top. Use `vi.doMock()`
only when mock needs runtime values.

Categories¶

Organize learnings by topic:

• Testing
• Build & Deploy
• Performance
• Security
• Third-Party Libraries
• Git and Workflow

CONVENTIONS.md¶

Purpose: Document project patterns, naming conventions, and standards.

Structure¶

# Conventions

## Naming

* **Files**: kebab-case for all source files
* **Components**: PascalCase for React components
* **Functions**: camelCase, verb-first (getUser, parseConfig)
* **Constants**: SCREAMING_SNAKE_CASE

## Patterns

### Pattern Name

**When to use**: Situation description

**Implementation**:
// in triple backticks
// Example code

**Why**: Rationale for this pattern

Guidelines¶

• Include concrete examples
• Explain the "why" not just the "what"
• Keep patterns minimal: Only document what's non-obvious

ARCHITECTURE.md¶

Purpose: Provide system overview and component relationships.

Structure¶

# Architecture

## Overview

Brief description of what the system does and how it's organized.

## Components

### Component Name

**Responsibility**: What this component does

**Dependencies**: What it depends on

**Dependents**: What depends on it

**Key Files**:
* path/to/file.ts: Description

## Data Flow

Description or diagram of how data moves through the system.

## Boundaries

What's in scope vs out of scope for this codebase.

Guidelines¶

• Keep diagrams simple (Mermaid works well)
• Focus on boundaries and interfaces
• Update when major structural changes occur

GLOSSARY.md¶

Purpose: Define domain terms, abbreviations, and project vocabulary.

Structure¶

# Glossary

## Domain Terms

### Term Name

**Definition**: What it means in this project's context

**Not to be confused with**: Similar terms that mean different things

**Example**: How it's used

## Abbreviations

| Abbrev | Expansion                     | Context                |
|--------|-------------------------------|------------------------|
| ADR    | Architectural Decision Record | Decision documentation |
| SUT    | System Under Test             | Testing                |

Guidelines¶

• Define project-specific meanings
• Clarify potentially ambiguous terms
• Include abbreviations used in code or docs

AGENT_PLAYBOOK.md¶

Purpose: Explicit instructions for how AI tools should read, apply, and update context.

Key Sections¶

Read Order: Priority order for loading context files

When to Update: Events that trigger context updates

How to Avoid Hallucinating Memory: Critical rules:

1. Never assume: If not in files, you don't know it
2. Never invent history: Don't claim "we discussed" without evidence
3. Verify before referencing: Search files before citing
4. When uncertain, say so
5. Trust files over intuition

Context Update Commands: Format for automated updates via ctx watch:

<context-update type="task">Implement rate limiting</context-update>
<context-update type="complete">user auth</context-update>
<context-update type="learning"
  context="Debugging hooks"
  lesson="Hooks receive JSON via stdin"
  application="Parse JSON stdin with the host language"
>Hook Input Format</context-update>
<context-update type="decision"
  context="Need a caching layer"
  rationale="Redis is fast and team has experience"
  consequence="Must provision Redis infrastructure"
>Use Redis for caching</context-update>

See Integrations for full documentation.

templates/¶

Location: .context/templates/. Status: implementation detail, user-editable.

Purpose: Format templates for ctx add decision and ctx add learning. These control the structure of new entries appended to DECISIONS.md and LEARNINGS.md.

ctx init deploys two starter templates:

• decision.md — sections: Context, Rationale, Consequence
• learning.md — sections: Context, Lesson, Application

Customizing¶

Edit the templates directly. Changes take effect immediately on the next ctx add command. For example, to add a "References" section to all new decisions, edit .context/templates/decision.md.

Templates are committed to git, so customizations are shared with the team.

steering/¶

Location: .context/steering/. Status: implementation detail, user-editable.

Purpose: Behavioral rules with YAML frontmatter that tell an AI assistant how to behave when a specific kind of prompt arrives. Unlike the core context files (which describe what the project is), steering files describe what to do and ride alongside the prompt through the AI tool's native rule pipeline (Claude Code, Cursor, Kiro, Cline). ctx matches steering files to prompts and syncs them out to each tool's config.

ctx init scaffolds four foundation files:

• product.md — who this project serves and why
• tech.md — the technology stack and its constraints
• structure.md — how the code is organized
• workflow.md — how work moves through the system

Each file carries YAML frontmatter describing when it applies (always, matching prompts, or manually referenced) and what tool scope it covers. The foundation files use inclusion: always by default so every session picks them up.

Customizing¶

Edit the files directly. Add your own steering files with ctx steering add, preview the match set with ctx steering preview, and run ctx steering sync to push them into each AI tool's config after changes. Steering files are committed to git, so they're shared with the team.

For the design rationale, the full inclusion/priority model, and the end-to-end sync workflow, see the dedicated Steering files page.

Parsing Rules¶

All context files follow these conventions:

1. Headers define structure: # for title, ## for sections, ### for items
2. Bold keys for fields: **Key**: followed by value
3. Code blocks are literal: Never parse code block content as structure
4. Lists are ordered: Items appear in priority/chronological order
5. Tags are inline: Backtick-wrapped tags like #priority:high

Further Reading¶

• Refactoring with Intent: how persistent context prevents drift during refactoring sessions

Token Efficiency¶

Keep context files concise:

• Use abbreviations in tags, not prose;
• Omit obvious words ("The," "This");
• Prefer bullet points over paragraphs;
• Keep examples minimal but illustrative;
• Archive old completed items periodically.

Next Up: Prompting Guide →: effective prompts for AI sessions with ctx