Directory Structure

The .contextia/ directory is the single source of truth for all project knowledge managed by Contextia. It lives at the project root (alongside .git/) and contains two layers: durable system knowledge and transient operational work.

Complete layout

.contextia/
├── config.yaml                         # Project configuration
├── .baseline.json                      # Known violations baseline (optional)
├── .cache/                             # Derived indexes (rebuildable, gitignored)
│   ├── index.json                      # Full artifact index
│   └── annotations.json               # Scanned annotation cache
├── system/                             # Durable knowledge layer
│   ├── identity.md                     # Project identity document
│   ├── specs/                          # Behavioral specifications
│   │   ├── SPEC-001.md
│   │   ├── SPEC-002.md
│   │   └── ...
│   ├── norms/                          # Project conventions and standards
│   │   ├── NORM-SEC-001.md
│   │   ├── NORM-API-001.md
│   │   └── ...
│   └── rationale/                      # Architectural decision records
│       ├── DEC-001.md
│       ├── DEC-002.md
│       └── ...
└── work/                               # Operational work layer
    ├── tasks/                          # All task definitions
    │   ├── TASK-001.md
    │   ├── TASK-002.md
    │   └── ...
    ├── active/                         # Working directories for active tasks
    │   └── TASK-001/
    │       ├── logs/                   # Session logs for this task
    │       │   ├── ses-20260302-1430.md
    │       │   └── ses-20260303-0900.md
    │       └── proposals/              # Spec change proposals from agents
    │           ├── PROP-001.md
    │           └── PROP-002.md
    └── archive/                        # Completed task working directories
        └── TASK-000/
            ├── logs/
            └── proposals/

Root files

config.yaml

The project configuration file. Created by contextia init and customized by the user. Controls scanning, validation, context assembly, and MCP behavior.

project:
  name: my-app
  languages: [python]
  source_paths: [src/]

annotations:
  prefix: "@"
  comment_syntax:
    python: "#"

See the Configuration Reference for the complete schema.

Note

config.yaml is the marker file that Contextia uses to find the project root. Both the CLI and MCP server walk up from the working directory until they find .contextia/config.yaml. If this file is missing, Contextia cannot operate and suggests running contextia init.

.baseline.json

Stores fingerprints of known violations for incremental adoption. Created by contextia check --create-baseline and updated by contextia check --update-baseline.

{
  "version": "1.0",
  "created_at": "2026-03-01T10:00:00Z",
  "updated_at": "2026-03-02T14:00:00Z",
  "violations": [
    {
      "fingerprint": "a1b2c3d4",
      "category": "annotation_integrity",
      "message": "File src/legacy/handler.py has @spec SPEC-003 but SPEC-003 does not list this path"
    }
  ]
}

This file should be committed to version control. It allows CI to pass despite pre-existing issues while catching new ones.

system/ — Durable knowledge

The system/ directory contains knowledge that persists across tasks. These artifacts have a lifecycle independent of any specific work item. They represent the project’s institutional memory.

system/identity.md

The project identity document. This is the single most important file in Contextia. It is loaded as an MCP resource (contextia://identity) at the start of every agent session.

---
project: my-app
version: "1.0"
---

## What is this

My App is a B2B platform for inventory management.

## Architecture

Monolithic FastAPI backend with React frontend.

## Conventions

- API responses use the { data, error, meta } envelope.
- All database access through the repository pattern.

The identity document is not a spec or a norm. It is a narrative overview that orients AI agents and human newcomers. Keep it current and concise.

Tip

A good identity document is 50-150 lines. If it grows beyond that, extract specific topics into norms or specs. The identity doc should be a map, not an encyclopedia.

system/specs/

Behavioral specifications. Each file is a Markdown document with SpecMeta frontmatter. Specs describe what parts of the system do in WHEN/THEN format.

system/specs/
├── SPEC-001.md    # User authentication
├── SPEC-002.md    # Rate limiting
├── SPEC-003.md    # Order processing
└── SPEC-004.md    # Notification delivery

File naming convention: {ID}.md where the ID matches the id field in frontmatter (e.g., SPEC-001.md). This is not strictly enforced but is strongly recommended for navigation.

See Frontmatter Schemas for the SpecMeta schema and Writing Effective Specs for authoring guidelines.

system/norms/

Project conventions, standards, and rules. Each file is a Markdown document with NormMeta frontmatter. Norms describe how code should be written, not what it should do.

system/norms/
├── NORM-SEC-001.md    # Security: password handling
├── NORM-SEC-002.md    # Security: input validation
├── NORM-API-001.md    # API: response format
├── NORM-API-002.md    # API: error codes
└── NORM-UI-001.md     # UI: component patterns

Norms support path scoping via the paths frontmatter field. A norm with paths: [src/api/**] applies only to files in the API directory. A norm with empty paths applies project-wide.

system/rationale/

Architectural decision records (ADRs). Each file is a Markdown document with DecisionMeta frontmatter. Decisions explain why certain architectural choices were made.

system/rationale/
├── DEC-001.md    # JWT over session cookies
├── DEC-002.md    # PostgreSQL over MongoDB
├── DEC-003.md    # Monorepo over polyrepo
└── DEC-004.md    # Zustand over Redux

Decisions have a lifecycle: proposed -> accepted -> superseded or deprecated. When a decision is superseded, the superseded_by field links to the replacement.

work/ — Operational state

The work/ directory contains transient artifacts tied to specific work items. These have a lifecycle: they are created when work begins and archived when work completes.

work/tasks/

Task definitions (work orders). Each file is a Markdown document with TaskMeta frontmatter. Tasks reference specs and are the primary entry point for context assembly.

work/tasks/
├── TASK-001.md    # Implement login endpoint
├── TASK-002.md    # Fix rate limiter bypass
├── TASK-003.md    # Add refresh token support
└── TASK-004.md    # Refactor order validation

Task status lives in YAML frontmatter (open, active, blocked, completed, cancelled). Tasks are never moved between directories to represent status changes.

Note

Task files remain in work/tasks/ throughout their lifecycle. Only the working directory (logs, proposals) moves from active/ to archive/ on completion.

work/active/

Working directories for currently active tasks. Created by contextia task activate {id} and removed (moved to archive) by contextia task complete {id}.

work/active/
└── TASK-003/
    ├── logs/
    │   ├── ses-20260302-1430.md
    │   └── ses-20260303-0900.md
    └── proposals/
        └── PROP-001.md

logs/

Session logs written by AI agents during work sessions. Each log file covers one session and contains timestamped entries recording progress, decisions, blockers, and summaries.

Session logs enable continuity: if an agent session ends and a new one begins, the new agent reads previous logs to understand what was done and what remains.

proposals/

Spec change proposals written by AI agents. When an agent discovers that a spec needs updating, it writes a proposal here instead of modifying the spec directly.

Proposals are reviewed by humans and promoted to actual spec changes with contextia spec promote.

work/archive/

Archived working directories from completed tasks. The structure mirrors active/:

work/archive/
└── TASK-000/
    ├── logs/
    │   └── ses-20260228-1000.md
    └── proposals/

Archived data is retained for historical reference but is not included in indexes or context assembly.

.cache/ — Derived data

The .cache/ directory contains derived artifacts that can be rebuilt from source at any time. It should be added to .gitignore.

.cache/
├── index.json          # Full artifact index (specs, decisions, norms, tasks)
└── annotations.json    # Scanned annotation results

index.json

A JSON index of all artifacts with their frontmatter metadata. Used by the MCP server for the contextia://index resource and by the CLI for contextia find.

Rebuilt by contextia refresh or automatically when stale.

annotations.json

A JSON cache of all annotation scan results. Contains file paths, line numbers, annotation types, IDs, and context information.

Rebuilt by contextia refresh or when source files are modified.

Note

Never commit .cache/ to version control. Add .contextia/.cache/ to your .gitignore. The cache is always rebuildable from the source artifacts and code.

.gitignore recommendations

Add the following to your project’s .gitignore:

# Contextia cache (rebuildable)
.contextia/.cache/

Everything else in .contextia/ should be committed to version control: config, identity, specs, decisions, norms, tasks, logs, proposals, and baseline.

Creating the structure

With contextia init

contextia init

Creates the minimal structure: config.yaml, system/identity.md, and empty directories for specs, norms, rationale, and tasks.

Manually

If you prefer to create the structure by hand:

mkdir -p .contextia/system/{specs,norms,rationale}
mkdir -p .contextia/work/{tasks,active,archive}
touch .contextia/config.yaml
touch .contextia/system/identity.md

Then populate config.yaml and identity.md with content.

Next steps

• See the Configuration Reference for config.yaml details.
• Read Frontmatter Schemas for artifact metadata schemas.
• Follow Your First Project to populate the structure with real content.