MCP Prompts

MCP prompts are workflow templates that an AI agent can instantiate to follow a structured process. Unlike tools (which perform a single operation) or resources (which provide static data), prompts generate a sequence of instructions that guide the agent through a multi-step workflow.

Contextia exposes three prompts:

Prompt	Purpose
start_feature_task	Begin work on a feature task with full context
start_bug_fix	Begin work on a bug fix with diagnostic focus
end_session	Close out a work session with proper logging

How prompts work

When an agent activates a prompt, the MCP server returns a structured message that the agent incorporates into its reasoning. The message typically includes:

1. Instructions — step-by-step guidance for the workflow.
2. Tool calls to make — specific Contextia tools the agent should invoke, in order.
3. Context to load — resources or artifacts the agent needs before starting.
4. Checkpoints — points where the agent should verify its understanding or ask the user for confirmation.

Prompts do not execute tools automatically. They provide a plan that the agent follows, making tool calls as instructed. This keeps the agent in control while ensuring it follows the recommended workflow.

start_feature_task

Purpose: Initialize a work session for a feature task. Load all relevant context, understand the requirements, and prepare to write code.

Parameters:

Parameter	Type	Required	Description
task_id	string	yes	The task to work on (e.g., TASK-042)

Generated workflow:

When the agent activates start_feature_task(task_id="TASK-042"), the server returns instructions equivalent to:

## Feature Task Workflow: TASK-042

### Step 1: Load project identity
Read the contextia://identity resource to understand the project's
tech stack, conventions, and architecture.

### Step 2: Load task context
Call mcp_context(task_id="TASK-042", depth="summary", budget=6000)
to get the task, linked specs, decisions, and norms in one bundle.

### Step 3: Read prior session logs
Call mcp_read_log(task_id="TASK-042", latest=false, n=3)
to understand what was done in previous sessions.

### Step 4: Review linked specs in full
For each spec linked in the task, call mcp_show(artifact_id=<spec_id>, format="full")
to read the complete behavioral contract.

### Step 5: Confirm understanding
Before writing any code, summarize your understanding of:
- What the task requires
- Which specs define the expected behavior
- What decisions constrain the implementation
- What norms apply to the code you will write
Ask the user to confirm or correct your understanding.

### Step 6: Begin implementation
Write code that satisfies the spec. Reference spec IDs in code
annotations (@spec SPEC-012) for traceability.

### Step 7: Log progress
Call mcp_write_log(task_id="TASK-042") periodically to record
decisions made, files changed, and open questions.

Tip

The start_feature_task prompt is the recommended way to begin any non-trivial coding session. It ensures the agent loads all relevant context before writing code, reducing hallucinated requirements and missed constraints.

What makes this different from just calling mcp_context

mcp_context assembles a context bundle — it is a single data-retrieval operation. The start_feature_task prompt wraps that call in a complete workflow: load identity first, then context, then logs, then read linked specs in full, then confirm understanding with the user. It encodes the best-practice sequence, not just the data.

start_bug_fix

Purpose: Initialize a work session for a bug fix. The workflow emphasizes understanding the current behavior, tracing the code path, and identifying the discrepancy with the spec.

Parameters:

Parameter	Type	Required	Description
task_id	string	yes	The bug fix task (e.g., TASK-045)

Generated workflow:

## Bug Fix Workflow: TASK-045

### Step 1: Load project identity
Read contextia://identity for project conventions and architecture.

### Step 2: Load task context
Call mcp_context(task_id="TASK-045", depth="full", budget=8000).
Bug fixes need full spec detail to understand expected vs actual behavior.

### Step 3: Identify affected files
Call mcp_find_by_path(file_path=<paths from linked specs>)
to find all artifacts and code related to the buggy area.

### Step 4: Trace the code path
Call mcp_trace(path=<primary file>) for each file in the affected area.
Understand which specs govern this code and what annotations exist.

### Step 5: Read prior session logs
Call mcp_read_log(task_id="TASK-045", latest=false, n=3).
Check if previous sessions identified root causes or partial fixes.

### Step 6: Diagnose
Before writing any fix, articulate:
- What the spec says should happen (expected behavior)
- What actually happens (observed behavior)
- Where the discrepancy originates (root cause hypothesis)
Present this to the user for confirmation.

### Step 7: Implement the fix
Write the fix. Ensure it addresses the root cause, not just symptoms.
Add or update annotations linking to the relevant spec.

### Step 8: Verify against spec
Re-read the linked spec and confirm each acceptance criterion is met.

### Step 9: Log the session
Call mcp_write_log(task_id="TASK-045") with:
- Root cause description
- Fix description
- Files changed
- Any spec clarifications needed

Key differences from start_feature_task

The bug fix workflow differs in several ways:

• Full depth by default. Bug fixes need the complete spec to understand expected behavior precisely. Features can often work from summaries.
• Trace step. The workflow includes mcp_trace to understand the existing code-to-spec relationships, helping the agent find where the bug originates.
• Diagnosis before coding. The workflow explicitly requires the agent to articulate the discrepancy between spec and reality before writing any code.
• Spec verification after coding. The agent re-reads the spec after implementing the fix to verify all acceptance criteria are met.

end_session

Purpose: Properly close out a work session, ensuring all progress is logged and the session state is clean for the next agent (or the next session with the same agent).

Parameters:

Parameter	Type	Required	Description
task_id	string	yes	The task being worked on

Generated workflow:

## End Session Workflow

### Step 1: Summarize work done
Review the changes made during this session and write a summary
covering:
- What was accomplished
- What decisions were made and why
- What files were created or modified
- What remains to be done

### Step 2: Record open questions
List any unresolved questions, ambiguities in specs, or decisions
that need human input before the next session.

### Step 3: Write final log entry
Call mcp_write_log(task_id=<task_id>) with:
- Session summary
- Decisions made
- Files changed
- Open questions
- Suggested next steps

### Step 4: Close the session log
Call mcp_close_log(task_id=<task_id>) to finalize the session record.

### Step 5: Run checks
Call mcp_check(baseline="all") to verify the project is in a
consistent state. Report any new issues introduced during this session.

### Step 6: Report to user
Present a brief summary to the user:
- Work completed
- Open questions requiring their input
- Check results (pass/fail)
- Recommended next steps

Caution

Always run the end_session prompt (or at minimum call mcp_close_log) before ending a conversation. Unclosed session logs can confuse the next agent that picks up the task, since it may not be clear where the previous session ended.

Why session closure matters

AI agent sessions are ephemeral. When the conversation ends, the agent’s in-memory understanding of the project disappears. The session log is the only persistent record of what happened.

A properly closed session log enables:

• Continuity. The next agent (or the same agent in a new session) can read the log and pick up where the previous session left off.
• Accountability. The human developer can review what the agent did, what decisions it made, and why.
• Debugging. If the agent introduced a bug, the session log helps trace which change caused it and what reasoning led to that change.

Using prompts in practice

Prompts are activated differently depending on the MCP client:

• Claude Code: The agent can reference prompts directly. You can also trigger them by describing the workflow (e.g., “Start working on TASK-042 as a feature task”).
• Cursor / VS Code: Prompt support varies by client. Some clients expose prompts as slash commands or suggestions; others require the agent to invoke them programmatically.

If your client does not support MCP prompts natively, you can achieve the same effect by instructing the agent to follow the workflow manually:

“Before working on TASK-042, load the project identity, then call mcp_context for the task, read the prior session logs, read all linked specs in full, and confirm your understanding with me before writing any code.”

This is exactly what the start_feature_task prompt encodes — the prompt just makes it automatic.