---

name: code-planning description: Plan implementation changes before coding. Use when the user requests a new feature, modification, or asks for a plan. Ensures full understanding, discovers existing code, creates detailed file/folder structure with contracts and tests, and gets user approval before implementation.

Implementation Planning

Plan BEFORE writing code. Complete each phase before proceeding to the next.

Plan output must be TERSE. No prose. Use tables, one-liners, and compact notation.

---

Phase 1: Understand Request

Achieve full understanding before any discovery or planning.

1. Restate the request in one sentence
2. Identify ambiguities - list anything unclear or with multiple interpretations
3. Ask clarifying questions using AskUserQuestion:
   • Expected input/output types
   • Which package should contain this
   • Edge cases to handle
   • Error handling expectations
   • Performance requirements (if applicable)

Do NOT proceed until you have clear answers to all ambiguities.

---

Phase 2: Load Architecture

Load the codebase rules that govern file placement and imports.

Copymcp__dungeonmaster__get-architecture()

Internalize before proceeding:

• Folder types and when to use each (decision tree)
• Import hierarchy (what can import what)
• Forbidden folders and their replacements
• Entry file naming conventions
• Layer file rules

---

Phase 3: Discovery

Find existing code related to this request. Extend existing functionality rather than duplicating.

Search strategies:

Copymcp__dungeonmaster__discover({ type: "files", search: "[keyword]" })
mcp__dungeonmaster__discover({ type: "files", fileType: "broker", search: "[domain]" })
mcp__dungeonmaster__discover({ type: "files", path: "packages/[pkg]/src/[folder]" })

Questions to answer:

• Does similar functionality exist? (If yes, extend it with options)
• What existing contracts define related types?
• What adapters wrap the npm packages we'll use?
• What brokers handle related business logic?
• What patterns do similar features follow?

Only use Read tool when: MCP discover returns a file but doesn't provide enough implementation detail to understand how to extend or integrate with it.

---

Phase 4: Get Folder Details

For each folder type you'll create/modify files in, load the specific rules.

Copymcp__dungeonmaster__get-folder-detail({ folderType: "brokers" })
mcp__dungeonmaster__get-folder-detail({ folderType: "contracts" })
mcp__dungeonmaster__get-folder-detail({ folderType: "adapters" })

Each call provides:

• Naming conventions for that folder
• Import restrictions
• Proxy file requirements
• Test patterns
• Code structure examples

Call for EVERY folder type in your plan before creating the plan.

---

Phase 5: Create Plan

Produce a terse implementation plan. Use tables exclusively. No prose paragraphs.

Files

Actions: NEW, MODIFY, DELETE

Contracts

Use branded types. Show nested objects inline.

Signatures

All parameters use object destructuring.

Dependencies

Tests

One line per test case. Format: condition -> expected result

Manual Testing (E2E BDD)

These are real E2E flows Claude will execute after implementation to verify the feature works. Not unit tests - actual user-like verification.

---

Phase 6: Review Manual Testing for Claude Execution

After writing BDD scenarios, determine HOW Claude will execute each.

By feature type:

For each scenario, specify the exact commands/steps:

If Claude cannot execute (rare):

• Mark as USER MANUAL TEST with clear instructions
• Example: "Verify push notification appears on physical device"

If tooling needed:

1. Check if adapter exists: discover({ type: "files", fileType: "adapter", search: "playwright" })
2. If not, add adapter to plan Files table
3. Include adapter setup in plan Dependencies

Update Files and Dependencies tables if new tooling required.

---

Phase 7: Verify Standards

Before presenting, verify plan against architecture rules:

• No forbidden folders (utils, helpers, lib, common, shared)
• All contracts use branded Zod types (no raw string/number)
• All functions use object destructuring for parameters
• All functions have explicit return types
• Entry files follow naming: [folder-path]-[suffix].ts
• Layer files only in allowed folders (widgets, brokers, responders)
• Import hierarchy respected (check get-architecture output)
• Each file has one primary export
• Test + proxy files included for all implementations
• File names are kebab-case

Fix any violations before presenting the plan.

---

Phase 8: Get Approval

Present the complete plan tables to the user.

Ask: "Does this plan look correct? Any modifications needed?"

If user requests changes:

1. Update the plan tables
2. Re-verify against standards (Phase 6)
3. Present updated plan
4. Repeat until approved

Only after explicit user approval: Proceed to implementation.