Configuration Reference

The .contextia/config.yaml file controls how Contextia scans, validates, and assembles context for your project. It is created by contextia init with sensible defaults and can be customized as needed.

Full schema overview

project:
  name: string
  languages: list[string]
  source_paths: list[string]

check:
  strict_bidirectional: boolean
  ignore_patterns: list[string]
  required_fields:
    spec: list[string]
    decision: list[string]
    norm: list[string]
    task: list[string]

approval:
  require_review: boolean
  reviewers: list[string]

context:
  max_tokens: integer
  default_depth: string
  include_norms: boolean
  include_decisions: boolean

annotations:
  prefix: string
  comment_syntax: map[string, string]
  parser: string

mcp:
  enabled: boolean
  expose_resources: list[string]
  expose_prompts: list[string]

commits:
  require_task_id: boolean
  task_id_pattern: string

baseline:
  path: string

Section: project

Project-level metadata and scanning configuration.

Field	Type	Default	Description
name	string	(required)	Project name. Used in identity resource and index.
languages	list[string]	[]	Programming languages present in the project. Determines comment syntax defaults. Supported: python, typescript, javascript, rust, go, java, kotlin, swift, ruby, c, cpp, csharp.
source_paths	list[string]	["src/"]	Directories containing source code to scan for annotations. Paths are relative to project root. Supports glob patterns.

project:
  name: my-app
  languages:
    - python
    - typescript
  source_paths:
    - backend/src/
    - frontend/src/
    - packages/shared/src/

Note

The languages field is informational and used for auto-detecting comment syntax. It does not restrict which files are scanned. File scanning is controlled by source_paths.

Section: check

Controls the behavior of contextia check and CI validation.

Field	Type	Default	Description
strict_bidirectional	boolean	false	When true, bidirectional consistency warnings (spec lists a path but file has no matching annotation) become errors that cause non-zero exit.
ignore_patterns	list[string]	[]	Glob patterns for files and directories to skip during annotation scanning. Relative to project root.
required_fields	map	(see below)	Extra frontmatter fields that must be present per artifact type, beyond the always-required id and title.

required_fields defaults

By default, only id and title are required for all artifact types. You can add additional required fields:

check:
  strict_bidirectional: true
  ignore_patterns:
    - "tests/**"
    - "scripts/**"
    - "vendor/**"
    - "**/*.generated.*"
  required_fields:
    spec:
      - description
      - status
      - paths
    decision:
      - date
      - status
    norm:
      - status
    task:
      - status
      - kind

Section: approval

Controls the spec change proposal and review workflow.

Field	Type	Default	Description
require_review	boolean	false	When true, contextia spec promote requires at least one reviewer approval before merging a proposal into the spec.
reviewers	list[string]	[]	List of GitHub usernames or team handles authorized to approve spec changes. Only used when require_review is true.

approval:
  require_review: true
  reviewers:
    - "@platform-team"
    - "alice"
    - "bob"

Tip

The approval workflow is designed for teams where specs are contracts. For solo developers or early-stage projects, leave require_review: false and promote proposals directly.

Section: context

Controls how contextia context and the MCP load_context tool assemble context.

Field	Type	Default	Description
max_tokens	integer	12000	Approximate maximum token count for assembled context. Context assembly stops adding artifacts when this budget would be exceeded. Uses a simple word-count heuristic (1 token ~ 0.75 words).
default_depth	string	"full"	Default depth level when no --depth flag is provided. Options: meta, summary, full.
include_norms	boolean	true	Whether to include linked norms in assembled context. Set to false to reduce context size if norms are well-known to the team.
include_decisions	boolean	true	Whether to include linked decisions in assembled context. Set to false if decision rationale is not needed during implementation.

context:
  max_tokens: 8000
  default_depth: full
  include_norms: true
  include_decisions: true

Depth levels explained

Depth	Content loaded	Approximate size
meta	YAML frontmatter only (id, title, status, links)	~50 tokens per artifact
summary	Frontmatter + first section of the Markdown body	~200 tokens per artifact
full	Entire Markdown document	Varies, typically 200-800 tokens

Section: annotations

Controls how Contextia scans source code for @spec, @decision, and @test annotations.

Field	Type	Default	Description
prefix	string	"@"	The prefix used before annotation types. With prefix @, annotations look like @spec SPEC-001. With prefix @ctx:, they look like @ctx:spec SPEC-001.
comment_syntax	map[string, string]	(auto-detected)	Maps language names to their single-line comment character(s). Used by the scanner to find annotations inside comments.
parser	string	"regex"	Parsing strategy for annotations. Options: regex (default, fast, no dependencies) or tree-sitter (precise AST-aware parsing, requires optional dependency).

Comment syntax defaults

When comment_syntax is not specified, defaults are derived from project.languages:

Language	Default comment syntax
python	#
typescript	//
javascript	//
rust	//
go	//
java	//
kotlin	//
swift	//
ruby	#
c	//
cpp	//
csharp	//

You can override defaults or add unlisted languages:

annotations:
  prefix: "@ctx:"
  comment_syntax:
    python: "#"
    typescript: "//"
    sql: "--"
    lua: "--"
    haskell: "--"
  parser: regex

Note

The tree-sitter parser provides AST-aware context (function name, class name) for each annotation. The regex parser uses best-effort heuristics for context detection. Both produce the same annotation results; the difference is in the richness of the context field in AnnotationResult.

Section: mcp

Controls the MCP server behavior.

Field	Type	Default	Description
enabled	boolean	true	Whether the MCP server exposes tools for this project. Set to false to disable MCP without removing the server configuration.
expose_resources	list[string]	["identity", "index"]	Which MCP resources to expose. Options: identity (project identity document), index (navigation map of all artifacts).
expose_prompts	list[string]	["start_feature_task", "start_bug_fix", "end_session"]	Which workflow prompt templates to expose via MCP.

mcp:
  enabled: true
  expose_resources:
    - identity
    - index
  expose_prompts:
    - start_feature_task
    - start_bug_fix
    - end_session

Section: commits

Controls integration with version control workflows.

Field	Type	Default	Description
require_task_id	boolean	false	When true, commit messages must reference a task ID. Enforced by contextia check --commits.
task_id_pattern	string	"TASK-\\d+"	Regex pattern for task IDs in commit messages. Used when require_task_id is true.

commits:
  require_task_id: true
  task_id_pattern: "TASK-\\d+"

Section: baseline

Controls the baseline file location.

Field	Type	Default	Description
path	string	".contextia/.baseline.json"	Path to the baseline file, relative to project root. The baseline stores fingerprints of known violations to support incremental adoption.

baseline:
  path: ".contextia/.baseline.json"

Complete example

project:
  name: platform
  languages:
    - python
    - typescript
  source_paths:
    - packages/api/src/
    - packages/web/src/
    - packages/shared/src/

check:
  strict_bidirectional: false
  ignore_patterns:
    - "tests/**"
    - "**/node_modules/**"
    - "**/*.generated.*"
  required_fields:
    spec:
      - description
      - paths

approval:
  require_review: false

context:
  max_tokens: 10000
  default_depth: full
  include_norms: true
  include_decisions: true

annotations:
  prefix: "@"
  comment_syntax:
    python: "#"
    typescript: "//"
  parser: regex

mcp:
  enabled: true
  expose_resources:
    - identity
    - index
  expose_prompts:
    - start_feature_task
    - start_bug_fix
    - end_session

commits:
  require_task_id: false

baseline:
  path: ".contextia/.baseline.json"

Next steps

• See the Directory Structure reference for the full .contextia/ layout.
• Read Frontmatter Schemas for artifact metadata schemas.
• Check CI/CD Integration for using config with automated checks.