Migration Guide

Adding Contextia to a project that already has code, decisions, and institutional knowledge requires a different approach than starting from scratch. This guide walks through a practical migration strategy that avoids disrupting ongoing work.

Overview

Migration happens in four phases:

1. Initialize — Set up .contextia/ and capture project identity.
2. Baseline — Run check, accept existing state, prevent new drift.
3. Document incrementally — Add specs and annotations as you touch code.
4. Enforce — Remove baseline entries, enable CI gates.

The key principle: you do not need to document everything before Contextia becomes useful. Even a single spec with annotations improves an AI agent’s context for that area of the codebase.

Phase 1: Initialize

Run contextia init in your project root:

contextia init

Contextia auto-detects your languages and source paths from the project structure. Review and adjust .contextia/config.yaml:

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

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

Write the identity document

.contextia/system/identity.md is the single most important file. It is loaded at the start of every AI agent session. Write it as if you are onboarding a new team member who is about to write code.

Cover:

• What the project does and who it serves.
• The tech stack and why those choices were made.
• Key architectural patterns (monolith, microservices, event-driven).
• Non-obvious conventions the team follows.
• What areas are stable vs. under active development.

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

## What is this

My Existing App is a B2B SaaS platform for inventory management.
Backend is Python (FastAPI), frontend is React + TypeScript.
Data layer is PostgreSQL with SQLAlchemy ORM.

## Architecture

Monolithic backend with domain-driven module boundaries.
Modules: auth, inventory, orders, reporting, integrations.
Each module has its own router, service layer, and repository.

## Conventions

- All API endpoints return JSON with envelope: { data, error, meta }.
- Database migrations use Alembic. Never modify models without a migration.
- Frontend state management uses Zustand. No Redux.
- Tests are required for all service-layer functions.

Tip

The identity document does not need to be perfect on day one. Write what you know, commit it, and refine it as you learn what agents need. If an agent keeps asking about something that is not in the identity doc, add it.

Phase 2: Create a baseline

Before adding any specs or annotations, run the integrity check:

contextia check --create-baseline

With no specs or annotations yet, the baseline will be mostly empty. The point is to establish the starting state. As you add artifacts, new inconsistencies (like a spec referencing a file that does not exist) will be caught immediately.

Commit the baseline file:

git add .contextia/.baseline.json
git commit -m "Add Contextia baseline"

Note

The baseline is a snapshot of known violations. It does not suppress future issues — only the exact violations present when the baseline was created. New violations always surface.

Phase 3: Document incrementally

Do not try to write specs for the entire codebase at once. Instead, adopt a “document as you go” strategy:

Strategy: Spec on touch

Whenever you or an agent work on a part of the codebase, create a spec for it before starting the work:

contextia new spec --id SPEC-015 --title "Order processing pipeline"

Write the behavioral contract, then annotate the relevant code:

# @spec SPEC-015
class OrderProcessor:
    def process(self, order: Order) -> ProcessingResult:
        ...

Over time, the most-touched areas of the codebase accumulate specs naturally. Areas that are stable and rarely changed can remain undocumented until they need attention.

Strategy: Decision archaeology

Your codebase already contains architectural decisions. They are just not recorded. When you encounter code and think “why was it done this way?”, that is a decision worth capturing:

contextia new decision --id DEC-020 --title "PostgreSQL over MongoDB for order data"

Even a brief decision record is valuable:

---
id: DEC-020
title: PostgreSQL over MongoDB for order data
status: accepted
date: 2024-06-15
specs:
  - SPEC-015
---

## Context

Order data has complex relationships (order -> items -> inventory -> suppliers).

## Decision

Use PostgreSQL with SQLAlchemy for relational integrity and join performance.

## Consequences

- Migrations required for schema changes (managed by Alembic).
- No flexible-schema documents for order metadata -- use JSONB columns where needed.

Strategy: Norm extraction

If your team has conventions documented in a wiki, README, or team knowledge base, migrate the actionable ones to norms:

contextia new norm --id NORM-API-001 --title "API response envelope"

---
id: NORM-API-001
title: API response envelope
status: active
paths:
  - backend/src/api/**
---

## Rule

All API endpoints must return responses in the standard envelope format:

```json
{
  "data": {},
  "error": null,
  "meta": { "request_id": "...", "timestamp": "..." }
}

No endpoint may return a bare object or array as the top-level response.

### Prioritizing what to document first

Focus your initial documentation effort on:

1. **Areas where agents will work first** -- if you are about to use AI for a feature in the auth module, spec the auth module.
2. **Areas with the most institutional knowledge** -- the parts where only one person knows why things are the way they are.
3. **Cross-cutting concerns** -- norms that apply everywhere (error handling, logging, security).
4. **Recent decisions** -- decisions made in the last 6 months are still fresh and easy to record.

## Phase 4: Enable CI enforcement

Once you have a meaningful set of specs and annotations, add `contextia check` to CI:

```yaml
- name: Knowledge integrity
  run: contextia check --ci

The baseline ensures that pre-existing gaps do not block PRs. Only new violations cause failure.

Reducing the baseline over time

Track baseline reduction as a team metric:

# See how many baseline violations remain
contextia check --format json | jq '.summary.baselined'

# Update baseline after fixing some violations
contextia check --update-baseline

Set a cadence: review and reduce the baseline once per sprint. When the baseline reaches zero, you have full integrity checking.

Handling large codebases

For projects with hundreds of source files:

Scope annotations to hot paths

You do not need annotations in every file. Start with:

• Entry points (API routes, CLI commands, event handlers).
• Service-layer functions that implement business logic.
• Configuration files that specs reference.

Utility functions, helpers, and internal plumbing can be annotated later if needed.

Use path patterns in specs

Instead of listing every file:

paths:
  - backend/src/orders/**/*.py

This captures the entire module without maintaining a file list.

Ignore vendor and generated code

Configure check to skip irrelevant paths:

check:
  ignore_patterns:
    - "node_modules/**"
    - "**/*.generated.ts"
    - "backend/src/migrations/**"
    - "vendor/**"

Team onboarding

When introducing Contextia to a team:

1. Start with one advocate. One person sets up the initial .contextia/ directory, writes the identity document, and creates a few example specs.
2. Present the value to the team. Show a before/after of an AI agent session: without Contextia (agent asks basic questions, makes wrong assumptions) vs. with Contextia (agent loads context, implements correctly).
3. Make it part of the PR process. “If you touched code covered by a spec, update the spec. If you made a decision, record it.”
4. Use CI as a safety net. The check command catches drift automatically. No one has to remember to update docs.

Tip

The biggest risk in migration is trying to do too much at once. Start small, show value quickly, and let the documentation grow with the codebase. A project with 5 good specs is more useful than one with 50 stale ones.

Next steps

• Follow Your First Project to practice the full workflow.
• See CI/CD Integration for detailed pipeline setup.
• Read Writing Effective Specs to ensure your specs are high quality from the start.