Agent Workflow

Contextia’s MCP server gives AI coding agents direct access to project knowledge. Instead of relying on a human to copy-paste context, the agent calls Contextia tools to load exactly what it needs, when it needs it.

This guide describes the full agent workflow from session start to session end.

The MCP connection

The Contextia MCP server runs as a local subprocess, started by the client (Claude Code, Cursor, VS Code). It communicates over stdio using the Model Context Protocol.

AI Agent  <--stdio-->  contextia-mcp  <--filesystem-->  .contextia/

The server inherits the working directory from the client and finds the project root by walking up the directory tree looking for .contextia/config.yaml, just like git finds .git/.

Note

No per-project configuration is needed in the MCP client. The working directory determines the project. If you open your editor in the project root, Contextia finds itself automatically.

Phase 1: Session start

When an agent begins a session, it should orient itself by loading two resources that the MCP server exposes:

Identity resource

contextia://identity

This returns the contents of .contextia/system/identity.md — the project’s self-description. It tells the agent what the project is, what stack it uses, what conventions matter, and what principles guide decisions.

A well-written identity document eliminates the need for the agent to ask “what is this project?” at the start of every session.

Index resource

contextia://index

This returns a navigation map of all artifacts: specs, decisions, norms, and tasks. The agent uses this to understand the scope of the project and navigate to specific items.

specs:
  - id: SPEC-001
    title: User authentication
    status: approved
  - id: SPEC-002
    title: Rate limiting
    status: draft
decisions:
  - id: DEC-001
    title: JWT for session tokens
    status: accepted
tasks:
  - id: TASK-003
    title: Add refresh token endpoint
    status: open
    specs: [SPEC-001]

Phase 2: Task context loading

When the agent starts working on a task, it uses the load_context tool to assemble all relevant knowledge:

Tool: load_context
Arguments: { "task_id": "TASK-003", "depth": "full" }

Contextia follows links deterministically:

1. Reads the task and extracts referenced specs.
2. For each spec, loads linked decisions and norms.
3. Assembles everything into a single context block, ordered for comprehension.

The result is a complete knowledge package:

── Task: TASK-003 — Add refresh token endpoint ──
status: open | kind: feature | priority: high | specs: SPEC-001

── Spec: SPEC-001 — User authentication ──
[Full spec content with behaviors]

── Decision: DEC-001 — JWT for session tokens ──
[Decision content with rationale]

── Norm: NORM-SEC-001 — Security defaults ──
[Norm content with rules]

Depth control

The depth parameter controls how much content is loaded:

Depth	What is loaded	Use case
meta	Frontmatter only (id, title, status, links)	Quick navigation, understanding structure
summary	Frontmatter + first section of body	Deciding whether to load more
full	Entire document	Active implementation work

Tip

Agents should start with meta depth to survey the landscape, then load full for the artifacts they actually need. This keeps token usage efficient on large projects.

Finding specific artifacts

The find_specs tool searches for specs by keyword, tag, or path:

Tool: find_specs
Arguments: { "query": "authentication", "status": "approved" }

The read_spec tool loads a single artifact by ID:

Tool: read_spec
Arguments: { "id": "SPEC-001", "depth": "full" }

Phase 3: Implementation

During implementation, the agent writes code, adds annotations, and iterates. Contextia does not interfere with the coding process. The agent uses the context it loaded to guide its decisions.

When the agent encounters a question that the loaded context does not answer, it can:

1. Search for additional specs with find_specs.
2. Load additional decisions or norms by ID.
3. Check the identity document for project-wide conventions.

Adding annotations

As the agent writes code, it should add annotations linking back to specs and decisions:

# @spec SPEC-001
# @decision DEC-001
def refresh_token(token: str) -> Token:
    ...

These annotations create the bottom-up traceability link from code to knowledge.

Phase 4: Session logging

Throughout the session, the agent writes structured logs using the write_session_log tool:

Tool: write_session_log
Arguments: {
  "task_id": "TASK-003",
  "entries": [
    { "type": "progress", "message": "Implemented refresh token endpoint" },
    { "type": "decision", "message": "Used sliding expiry window instead of fixed" },
    { "type": "blocker", "message": "Need clarification on refresh token revocation strategy" }
  ]
}

Session logs are written to .contextia/work/active/TASK-003/logs/ and serve two purposes:

1. Continuity: If the session ends and a new one begins (same agent or different), the next session can read the log to understand what was done and what is pending.
2. Audit: The human developer can review what the agent did, what decisions it made, and where it got stuck.

Note

Session logs are operational artifacts. They live in work/ and are archived when the task completes. They are not permanent knowledge — that belongs in specs and decisions.

Phase 5: Proposing spec changes

Sometimes the agent discovers that a spec is incomplete, contradictory, or needs updating. Agents must never modify specs directly. Instead, they propose changes:

Tool: propose_spec_change
Arguments: {
  "task_id": "TASK-003",
  "spec_id": "SPEC-001",
  "change_type": "add_behavior",
  "description": "Add refresh token rotation behavior",
  "proposed_content": "WHEN a refresh token is used\nTHEN the old token is invalidated and a new token pair is issued."
}

Proposals are saved to .contextia/work/active/TASK-003/proposals/ as Markdown files. The human developer reviews and decides whether to promote the change to the actual spec:

contextia spec promote TASK-003 --proposal PROP-001

This staged workflow ensures that the knowledge layer remains human-reviewed while allowing agents to contribute improvements.

Phase 6: Ending the session

When work is complete (or the session is ending), the agent should use the end-session workflow:

Tool: write_session_log
Arguments: {
  "task_id": "TASK-003",
  "entries": [
    { "type": "summary", "message": "Implemented refresh token endpoint with sliding expiry. All behaviors from SPEC-001 covered. Proposed addition of refresh token rotation behavior." }
  ],
  "close": true
}

The close: true flag marks the session log as complete. If the task itself is done, the human (or a CI step) marks it complete:

contextia task complete TASK-003

Workflow prompts

Contextia provides MCP prompt templates that guide agents through standard workflows:

start_feature_task

Guides the agent through: load identity, load index, find the task, load context, begin implementation.

start_bug_fix

Similar to feature start but focuses on: load relevant specs, identify the violated behavior, find annotated code, fix while maintaining spec compliance.

end_session

Guides the agent through: write summary log, list any proposed spec changes, flag any unresolved blockers, suggest next steps.

These prompts are available in the MCP server as prompt resources. The client can present them to the agent at the appropriate time.

Example: Full session transcript

Here is a condensed view of an agent session working on TASK-003:

1. Agent reads contextia://identity        -- orients to the project
2. Agent reads contextia://index            -- surveys all artifacts
3. Agent calls load_context(TASK-003, full) -- gets task + specs + decisions + norms
4. Agent implements refresh token endpoint  -- writes code with annotations
5. Agent calls write_session_log(progress)  -- records what was done
6. Agent calls propose_spec_change(...)     -- suggests spec addition
7. Agent calls write_session_log(close)     -- ends session cleanly

Every step is deterministic. The agent knows exactly what to load and where to write. No guessing, no semantic search, no hallucinated context.

Next steps

• Set up MCP in your editor: see MCP Server documentation.
• Learn about the Configuration Reference for MCP-specific settings.
• Try the Your First Project guide to create artifacts that agents can consume.