Your First Project

This guide walks you through a complete Contextia workflow from scratch. By the end, you will have initialized a project, written a spec, annotated your code, created and completed a task, and verified integrity with contextia check.

Prerequisites

Install Contextia via uvx or pip:

pip install contextia
# or
uvx contextia --help

You need a project directory with some source code. For this guide, we will use a small Python project.

Step 1: Initialize the project

Navigate to your project root and run:

contextia init

Contextia detects your project language, creates the .contextia/ directory, and generates a starter config.yaml and identity.md.

.contextia/
  config.yaml
  system/
    identity.md
    specs/
    norms/
    rationale/
  work/
    tasks/

Tip

Edit .contextia/system/identity.md right away. This file tells AI agents what your project is, what it does, and what matters. A good identity document saves every future session from starting cold.

Step 2: Configure your project

Open .contextia/config.yaml and review the auto-detected settings:

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

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

Adjust source_paths to match where your code lives. The comment_syntax map tells the scanner how to find annotations in each language.

Step 3: Write your first spec

Create a spec using the scaffolding command:

contextia new spec --id SPEC-001 --title "User authentication"

This creates .contextia/system/specs/SPEC-001.md with a template. Open it and fill in the behavioral contract:

---
id: SPEC-001
title: User authentication
description: Handles user login, token issuance, and session validation.
status: draft
decisions:
  - DEC-001
norms:
  - NORM-SEC-001
paths:
  - src/auth/
---

## Objective

Provide secure user authentication using JWT tokens.

## Behaviors

WHEN a user submits valid credentials
THEN the system issues a signed JWT with a 1-hour expiry.

WHEN a user submits invalid credentials
THEN the system returns a 401 status with no token.

WHEN a request includes an expired token
THEN the system returns a 401 status and the client must re-authenticate.

Note

The paths field in frontmatter creates a top-down link from the spec to your source code. The annotation in your code creates the bottom-up link. Both directions matter for traceability.

Step 4: Record a decision

Specs often depend on architectural decisions. Create one:

contextia new decision --id DEC-001 --title "JWT for session tokens"

Edit .contextia/system/rationale/DEC-001.md:

---
id: DEC-001
title: JWT for session tokens
status: accepted
date: 2026-03-02
specs:
  - SPEC-001
---

## Context

We need stateless session management for horizontal scaling.

## Decision

Use JWT (JSON Web Tokens) signed with RS256.

## Consequences

- Stateless: no session store required.
- Revocation requires a short expiry or a deny-list.

Step 5: Annotate your code

Open your source file and add annotations linking back to the spec:

src/auth/login.py

# @spec SPEC-001
# @decision DEC-001
def authenticate_user(username: str, password: str) -> Token:
    """Authenticate user and return a JWT token."""
    user = find_user(username)
    if user and verify_password(password, user.hashed_password):
        return create_jwt(user.id)
    raise AuthenticationError("Invalid credentials")

The @spec SPEC-001 annotation creates a traceable link from this function to the spec. The scanner picks these up during contextia refresh.

Step 6: Create a task

Tasks are work orders that reference specs. Create one:

contextia new task --id TASK-001 --title "Implement login endpoint" \
  --specs SPEC-001

This creates .contextia/work/tasks/TASK-001.md:

---
id: TASK-001
title: Implement login endpoint
status: open
kind: feature
priority: high
specs:
  - SPEC-001
---

## Description

Implement the `/auth/login` POST endpoint per SPEC-001.

Step 7: Activate the task and load context

When you (or an AI agent) begin working, activate the task:

contextia task activate TASK-001

This creates a working directory at .contextia/work/active/TASK-001/ with space for session logs and proposals.

Now assemble the full context for the task:

contextia context TASK-001

Contextia follows the links deterministically:

1. Reads TASK-001 and finds specs: [SPEC-001].
2. Reads SPEC-001 and finds decisions: [DEC-001], norms: [NORM-SEC-001].
3. Loads each linked artifact.
4. Assembles everything into a single context block.

── Task: TASK-001 — Implement login endpoint ──
── Spec: SPEC-001 — User authentication ──
── Decision: DEC-001 — JWT for session tokens ──
── Norm: NORM-SEC-001 — Security defaults ──

Tip

Use --depth meta to load only frontmatter (for quick navigation) or --depth summary for the first section of each artifact. The default --depth full loads everything.

Step 8: Check integrity

Run the integrity checker to verify all links resolve and annotations match:

contextia check

A clean run looks like this:

Checking .contextia/ integrity...
  Specs:      1 found, 0 issues
  Decisions:  1 found, 0 issues
  Norms:      0 found, 0 issues
  Tasks:      1 found, 0 issues
  Annotations: 2 found, 0 orphans, 0 missing
All checks passed.

If a spec references a decision that does not exist, or an annotation points to a missing spec, check reports the issue with file path and line number.

Step 9: Complete the task

After implementation is done, close the task:

contextia task complete TASK-001

This updates the task status to completed in its frontmatter and archives the working directory.

What you built

In this walkthrough you have:

• Initialized a Contextia project with contextia init
• Written a behavioral spec in WHEN/THEN format
• Recorded an architectural decision with rationale
• Annotated source code with @spec and @decision
• Created and activated a task linked to the spec
• Assembled deterministic context with contextia context
• Verified integrity with contextia check
• Completed and archived the task

Next steps

• Read Writing Effective Specs to improve your spec quality.
• See Agent Workflow to learn how AI agents use Contextia via MCP.
• Explore the Configuration Reference for all available settings.