# Work Plan: Sprint 5a — MCP Prompt for AI Agent Guidance

Created Date: 2026-03-05
Type: feature
Estimated Duration: 1 day
Estimated Impact: 3 files (2 new, 1 modified)
Related Issue/PR: N/A

## Related Documents
- Design Doc: Inline spec (see sprint description)
- ADR: N/A (no architecture decisions — text file + 10-line registration)
- PRD: N/A

## Objective
Create an MCP prompt that teaches AI agents how to use GodotIQ's 27 tools effectively. The prompt is injected into the agent's context when it connects via `@mcp.prompt()`. Zero changes to existing tool files.

## Background
GodotIQ now has 27 MCP tools across 6 categories (memory, code, spatial, assets, animation, bridge) with 622 passing tests. AI agents connecting to GodotIQ lack structured guidance on which tools to call, in what order, and how to recover from errors. An MCP prompt solves this by providing agent-facing documentation at connection time.

## Phase Structure Diagram

```mermaid
graph TD
    P0[Phase 0: Confirm skill constraints] --> P1[Phase 1: Create prompt package and content]
    P1 --> P2[Phase 2: Register prompt in server]
    P2 --> P3[Phase 3: Quality Assurance]
    P3 --> P4[Phase 4: Verify skill fidelity]
```

## Task Dependency Diagram

```mermaid
graph LR
    T1[Create prompts/__init__.py] --> T3[Register prompt in server.py]
    T2[Create godot_development.md] --> T3
    T3 --> T4[Smoke test import]
    T4 --> T5[Full regression pytest]
    T5 --> T6[Verify skill fidelity]
```

## Risks and Countermeasures

### Technical Risks
- **Risk**: FastMCP `@mcp.prompt()` decorator API mismatch (wrong signature or return type)
  - **Impact**: Low — prompt registration fails at import time
  - **Countermeasure**: Already confirmed via runtime inspection. If it fails, fall back to `mcp.add_prompt()` method or raw prompt registration.

### Schedule Risks
- **Risk**: None significant — this is a 3-file, ~10-line-of-code change
  - **Impact**: Negligible
  - **Countermeasure**: N/A

## Implementation Phases

### Phase 0: Confirm Skill Constraints (Estimated commits: 0)
**Purpose**: Verify this plan complies with all skill constraints before implementation begins.

#### Tasks
- [x] Confirm no changes to existing Python tool files
- [x] Confirm no changes to GDScript files
- [x] Confirm no new test files needed (text file + registration only)
- [x] Confirm prompt content target under 3000 words
- [x] Confirm Strategy B (Implementation-First) is appropriate — no test design information provided

#### Phase Completion Criteria
- [x] All constraints acknowledged and verified

### Phase 1: Create Prompt Package and Content File (Estimated commits: 1)
**Purpose**: Create the `src/godotiq/prompts/` package and the markdown prompt content file.

#### Tasks
- [ ] Create `src/godotiq/prompts/__init__.py` with docstring `"""GodotIQ MCP prompts."""`
- [ ] Create `src/godotiq/prompts/godot_development.md` with full prompt content covering:
  - Quick Start (first 3 calls an agent should make)
  - Tool Categories:
    - UNDERSTAND (13 tools): `godotiq_ping`, `godotiq_project_summary`, `godotiq_file_context`, `godotiq_dependency_graph`, `godotiq_signal_map`, `godotiq_impact_check`, `godotiq_validate`, `godotiq_scene_map`, `godotiq_spatial_audit`, `godotiq_asset_registry`, `godotiq_suggest_scale`, `godotiq_animation_info`, `godotiq_animation_audit`
    - EDIT (6 tools): `godotiq_node_ops`, `godotiq_script_ops`, `godotiq_file_ops`, `godotiq_editor_context`, `godotiq_scene_tree`, `godotiq_undo_history`
    - PLAY & DEBUG (8 tools): `godotiq_run`, `godotiq_screenshot`, `godotiq_perf_snapshot`, `godotiq_input`, `godotiq_exec`, `godotiq_state_inspect`, `godotiq_nav_query`, `godotiq_watch`
  - 4 Workflows: Moving/Placing Objects, Editing Scripts Safely, Debugging Runtime Issues, Testing Game Interaction
  - GDScript Conventions (naming, structure, best practices, signal patterns)
  - Node Path Convention
  - Token Efficiency tips
  - Error Recovery guide
- [ ] Verify prompt is under 3000 words

#### Phase Completion Criteria
- [ ] `src/godotiq/prompts/__init__.py` exists with correct docstring
- [ ] `src/godotiq/prompts/godot_development.md` exists and is under 3000 words
- [ ] All 27 tools are mentioned in the prompt content
- [ ] 4 workflows are documented

#### Operational Verification Procedures
1. Run: `python -c "from pathlib import Path; p = Path('src/godotiq/prompts/godot_development.md'); content = p.read_text(); words = len(content.split()); print(f'Prompt: {len(content)} chars, {words} words')"`
2. Verify word count is under 3000
3. Verify all 27 tool names appear in the file

### Phase 2: Register Prompt in Server (Estimated commits: 1)
**Purpose**: Wire the prompt into the FastMCP server so it is available to connecting agents.

#### Tasks
- [ ] Add `from pathlib import Path` import to `src/godotiq/server.py` (top of file, with other imports)
- [ ] Add `PROMPT_DIR` constant: `PROMPT_DIR = Path(__file__).resolve().parent / "prompts"`
- [ ] Add `@mcp.prompt("godot-development")` decorated async function that reads and returns the markdown content
- [ ] Place prompt registration AFTER `mcp = FastMCP(...)` line but BEFORE tool imports

#### Phase Completion Criteria
- [ ] `src/godotiq/server.py` contains the prompt registration
- [ ] Import smoke test passes: `python -c "from godotiq.server import mcp; print('OK')"`
- [ ] No existing tool registrations are affected

#### Operational Verification Procedures
1. Run: `python -c "from godotiq.server import mcp; print('OK')"`
2. Verify output is `OK` (no import errors)
3. Verify no changes to any tool file (only `server.py` modified)

### Phase 3: Quality Assurance (Required) (Estimated commits: 0)
**Purpose**: Full regression to confirm nothing broke.

#### Tasks
- [ ] Run full test suite: `pytest tests/ -v`
- [ ] Verify all 622+ tests pass
- [ ] Verify no test failures or errors
- [ ] Verify prompt file is readable and well-formed

#### Phase Completion Criteria
- [ ] All existing tests pass (622+ tests, 0 failures)
- [ ] Import smoke test passes
- [ ] Prompt file exists and contains expected content

#### Operational Verification Procedures
1. Run: `pytest tests/ -v`
2. Verify output shows 0 failures, 0 errors
3. Run: `python -c "from godotiq.server import mcp; print('OK')"`
4. Run: `python -c "from pathlib import Path; p = Path('src/godotiq/prompts/godot_development.md'); print(f'Prompt: {len(p.read_text())} chars')"`

### Phase 4: Verify Skill Fidelity (Estimated commits: 0)
**Purpose**: Final check that all constraints and acceptance criteria are met.

#### Tasks
- [ ] Confirm only 3 files were touched (2 created, 1 modified)
- [ ] Confirm no existing tool Python files were changed
- [ ] Confirm no GDScript files were changed
- [ ] Confirm prompt is under 3000 words
- [ ] Confirm all 27 tools are covered in the prompt

#### Phase Completion Criteria
- [ ] All acceptance criteria from the sprint spec are satisfied
- [ ] No unintended side effects

## Completion Criteria
- [ ] All phases completed
- [ ] Each phase's operational verification procedures executed
- [ ] 27 tools documented in prompt content
- [ ] 4 workflows documented in prompt content
- [ ] Prompt under 3000 words
- [ ] All 622+ existing tests still pass
- [ ] Only files created/modified: `src/godotiq/prompts/__init__.py` (new), `src/godotiq/prompts/godot_development.md` (new), `src/godotiq/server.py` (modified)

## Progress Tracking
### Phase 0
- Start: 2026-03-05
- Complete: 2026-03-05
- Notes: Constraints confirmed

### Phase 1
- Start:
- Complete:
- Notes:

### Phase 2
- Start:
- Complete:
- Notes:

### Phase 3
- Start:
- Complete:
- Notes:

### Phase 4
- Start:
- Complete:
- Notes:

## Notes
- This is a LOW risk sprint. Only 2 new files and ~10 lines added to server.py.
- No new tests are needed — this is a text content file and minimal registration code.
- The 27 tools break down as: 1 ping + 2 memory + 4 code + 2 spatial + 2 assets + 2 animation + 14 bridge = 27.
- FastMCP prompt API was confirmed working via runtime inspection before this sprint.
- Implementation strategy: Strategy B (Implementation-First) — no test design information provided, and the scope is too small for TDD overhead.
