Context Compilation is the process of generating precise, structured startup context for AI agents from your codebase. Instead of an agent starting every session with no knowledge of your project, ChooChoo compiles a context document (AGENTS.md) it reads at startup.

choochoo context generate

This scans your repository and produces AGENTS.md — a document that tells your agent what's in scope, what's off-limits, what schemas apply, and what decisions have been made before.

Why Context Quality Matters

Agents fail in predictable ways when their startup context is poor:

• Missing rules — The agent doesn't know the conventions it's supposed to follow, so it invents plausible-sounding ones. Schema changes break downstream consumers. Auth logic lands without the required review.
• Missing background — The agent lacks the history needed to make correct decisions. It refactors code it shouldn't touch, re-implements things that already exist, and repeats mistakes from last week.
• Context drift — As the codebase evolves, a stale AGENTS.md becomes misleading. Agents operating on outdated context make systematically wrong assumptions.

High-quality compiled context reduces all three. Agents working from choochoo context generate output produce fewer boundary violations and fewer specification errors than agents working from manually written or absent AGENTS.md files.

Tools

Context compilation uses two internal tools:

Tool	Purpose
qmd	Semantic indexing over your codebase and trace history. Powers vsearch (vector semantic search).
colgrep	Combined semantic + regex search for precise code location.

You don't call these directly — choochoo context generate orchestrates them.

System Card Schema

Every agent gets a System Card — a machine-readable identity document stored in system-cards/*.yaml. The System Card declares the agent's capabilities, limitations, and compliance alignment, and is injected into AGENTS.md so the agent is aware of its own boundaries at startup.

systemCardSpecification: "1.0.0"
info:
  id: claude-code
  name: Claude Code
  version: "1.x"
  owner: [email protected]
  description: AI coding agent

intendedUse:
  - Code generation and refactoring
  - Test writing
  - Documentation updates

limitations:
  - No access to production environments
  - Cannot modify financial data without approval

compliance:
  frameworks: ["EU AI Act"]
  dataResidency: ["us-east-1"]

The limitations field documents known failure modes. These are injected into AGENTS.md so the agent is aware of its own constraints.

Context Regeneration

Context goes stale as your codebase evolves. ChooChoo can regenerate AGENTS.md automatically after every commit:

# Add to your post-commit hook
choochoo context generate --quiet

Or configure automatic regeneration in choochoo.toml:

[context]
auto_regenerate = true

Skills (SKILL.md)

Alongside AGENTS.md, ChooChoo supports Skill files — modular, importable knowledge units that agents can load on demand. Where AGENTS.md describes the whole project, a Skill describes how to do one specific task correctly in this codebase.

Examples:

• skills/db-migration.md — "How to write and run a database migration in this app"
• skills/api-contract-change.md — "How to update an OpenAPI spec without breaking downstream consumers"
• skills/pr-workflow.md — "The branching and review conventions for this team"

Skills are declared in choochoo.toml and injected into agent context selectively:

[context.skills]
sources = ["skills/**/*.md"]

When an agent is assigned a task, ChooChoo uses qmd vsearch to surface the most relevant skill files and inject only those — keeping the context window focused.

Example skill file

skills/db-migration.md:

---
title: "Database Migrations"
tags: ["database", "migrations", "postgres", "alembic"]
applies_to: ["alembic/**", "app/models/**"]
---

How to write and run a database migration using Alembic in this app.

## Context

This app uses PostgreSQL with Alembic for schema migrations. All migrations
live under `alembic/versions/`. The Alembic config is in `alembic.ini`.
Never edit migration files after they have been merged to main.

## Steps

1. Generate the migration file:
   alembic revision --autogenerate -m "describe_your_change"
   Review the generated file in `alembic/versions/` before proceeding.

2. Edit the generated file if autogenerate missed anything (e.g. index
   additions, custom types). Check both `upgrade()` and `downgrade()`.

3. Apply locally:
   alembic upgrade head

4. Run the test suite to confirm nothing is broken:
   mise run test

5. Commit the migration file together with any model changes in the same
   commit. Never commit them separately.

## Pitfalls

- Do not use --autogenerate alone for column renames. Alembic treats a
  rename as drop + add, which destroys data. Write the migration by hand.
- Check for circular imports. Alembic imports your models at migration
  time; circular imports cause sqlalchemy.exc.InvalidRequestError.
- Do not backfill large tables in the migration. Write a separate backfill
  script and run it asynchronously after the migration.

See Skill Files for full documentation on skill file format, naming conventions, and how qmd vsearch selects skills at task time.

Just-in-Time Context

For large codebases, injecting the full AGENTS.md into every session is wasteful. ChooChoo supports Just-in-Time (JIT) context injection: when an agent is working on a specific feature or schema change, ChooChoo injects only the relevant specs (ODCS, OpenAPI, etc.) and skill files for that task — preventing context window overflow and reducing hallucinations from irrelevant context.

JIT context is powered by qmd vsearch — the same semantic indexer that builds AGENTS.md, now used at task time to surface the right context for the right job. This is planned as part of the Phase 2 roadmap; see the Roadmap for status.

Related

• Agents — How agents use the compiled context document.
• Agent Trace — How trace history feeds context compilation.
• Skill Files — Full documentation on skill file format and selection.
• CLI Reference — Full documentation for choochoo context commands.