contextia context

contextia context is the core command of Contextia. Given a task ID, it assembles a complete context bundle by following explicit links: task references specs, specs reference decisions and norms, and all linked documents are collected into a single output. No semantic search, no guessing — just deterministic link traversal.

Synopsis

contextia context <task-id> [OPTIONS]

Arguments

Argument	Description
task-id	Task identifier (e.g., TASK-007)

Options

Option	Short	Description
--depth <level>	-d	Detail level: meta, summary, full (default: full)
--budget <tokens>	-b	Approximate token budget for the output
--include-identity		Prepend identity.md to the context (default: true)
--no-identity		Exclude identity.md from the context
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json
--help	-h	Show help and exit

Link traversal

The context assembly follows a deterministic chain:

TASK-007
  └── specs: [SPEC-AUTH-001]
        ├── links: [DEC-002, NORM-SEC-001]
        │     ├── DEC-002 (decision)
        │     └── NORM-SEC-001 (norm)
        └── paths: [src/auth/**]
              └── (file listing, not content)

The output is ordered: identity (if included), then the task, then specs, then decisions, then norms. Each section is clearly delimited.

Depth and budget

The --depth and --budget options control how much content is included:

• --depth meta: Only frontmatter for all linked artifacts. Minimal token usage.
• --depth summary: Frontmatter plus the first section of each artifact.
• --depth full: Complete content of all linked artifacts.
• --budget N: Automatically adjusts depth per-artifact to fit within approximately N tokens. Prioritizes task and specs over decisions and norms.

Examples

Assemble full context for a task:

$ contextia context TASK-007
═══ Context for TASK-007: Implement OAuth login ═══

── identity ──
my-api: A REST API for the billing platform...

── task ──
TASK-007: Implement OAuth login (feature, active)
  specs: SPEC-AUTH-001

  ## Objective
  Implement OAuth 2.0 with PKCE for user authentication...

── spec ──
SPEC-AUTH-001: Authentication Flow (approved)
  paths: src/auth/**, src/middleware/auth.py
  links: DEC-002, NORM-SEC-001

  ## Overview
  Users authenticate via OAuth 2.0 with PKCE...

── decision ──
DEC-002: OAuth 2.0 with PKCE over API keys (accepted)

  ## Context
  We need an authentication mechanism...

── norm ──
NORM-SEC-001: No secrets in source code (active)
  scope: **/*

  ## Rule
  All secrets must be loaded from environment variables...

═══ 4 artifacts, ~1,240 tokens ═══

Context with a token budget:

$ contextia context TASK-007 --budget 500
═══ Context for TASK-007: Implement OAuth login ═══

── identity ──
my-api: A REST API for the billing platform.

── task ──
TASK-007: Implement OAuth login (feature, active)
  specs: SPEC-AUTH-001

── spec ──
SPEC-AUTH-001: Authentication Flow (approved)
  Users authenticate via OAuth 2.0 with PKCE...

── decision ──
DEC-002: OAuth 2.0 with PKCE over API keys (accepted)

── norm ──
NORM-SEC-001: No secrets in source code (active)

═══ 4 artifacts, ~480 tokens (budget: 500) ═══

Meta-only context for quick orientation:

$ contextia context TASK-007 --depth meta
═══ Context for TASK-007 (meta) ═══
task:     TASK-007 Implement OAuth login (feature, active)
spec:     SPEC-AUTH-001 Authentication Flow (approved)
decision: DEC-002 OAuth 2.0 with PKCE (accepted)
norm:     NORM-SEC-001 No secrets in source code (active)
═══ 4 artifacts ═══

JSON output:

$ contextia context TASK-007 --json
{
  "task": { "id": "TASK-007", "title": "Implement OAuth login", "status": "active" },
  "specs": [
    { "id": "SPEC-AUTH-001", "title": "Authentication Flow", "status": "approved" }
  ],
  "decisions": [
    { "id": "DEC-002", "title": "OAuth 2.0 with PKCE over API keys", "status": "accepted" }
  ],
  "norms": [
    { "id": "NORM-SEC-001", "title": "No secrets in source code", "status": "active" }
  ],
  "token_estimate": 1240
}

Behavior

• If a linked artifact does not exist (broken reference), a warning is printed to stderr and the missing artifact is noted in the output.
• Identity is included by default. Use --no-identity to exclude it when the agent already has it loaded as an MCP resource.
• Token estimates are approximate, based on a simple character-to-token ratio (roughly 4 characters per token).
• The command exits with code 0 even if some links are broken, but prints warnings to stderr.