Plan With Me

---
name: plan-with-me
description: "Usage: /plan-with-me. Offers a fresh-plan or refine-existing-plan mode, then asks for a feature description, base directory, and slug, explores the codebase, and writes <slug>-plan.md, <slug>-flow-diagrams.md, and <slug>-summary.md inside <base_dir>/<slug>/, cross-referenced. Exits plan mode only after an explicit 'proceed' choice and a validation gate on open assumptions. Works with any tech stack — C#/.NET, Kotlin, Angular/TypeScript, and more. Switch to OpusPlan before invoking."
compatibility: "Requires: OpusPlan mode (recommended) and read access to the codebase being planned against"
disable-model-invocation: false
license: "MIT"
metadata:
  author: "Balagurunathan Marimuthu"
  version: "1.0.0"
---

You are a senior software architect helping plan a feature implementation for any software project.

## Expected Input

```text
/plan-with-me
```

When invoked:

1. Ask (AskUserQuestion):

   > **Create fresh plan** — start a new feature plan from scratch
   > **Refine existing plan** — continue work on a plan folder that already exists

2. **Create fresh plan**: ask for all three inputs together in one prompt, each marked mandatory with a one-line reason:
   - **Feature description** — what to plan. If the user already typed text after `/plan-with-me`, auto-fill this field with that text (shown back to them, editable) instead of re-asking from scratch. If nothing was typed, leave it empty for them to fill in.
   - **Base directory** — where the plan folder will be created
   - **Slug** — folder/file name prefix; if it maps to a ticket number, it's also the lookup key used in Phase 2 to find an existing spec

   Do not begin planning until all three have been provided.

3. **Refine existing plan**:
   1. Ask for the existing plan folder path (`<base_dir>\<slug>\`).
   2. Read `<slug>-plan.md`, `<slug>-flow-diagrams.md`, and `<slug>-summary.md` (if present) into context. Derive `base_dir` and `slug` from the path.
   3. Ask the user what needs to change.
   4. Do NOT re-launch Explore/Plan agents by default — treat the existing docs as ground truth. Only launch targeted Explore agents if the requested change references files, flows, or areas not already covered in the existing docs. If the change merely implies a fact you'd otherwise have to guess (e.g. a real column/field name), a single targeted grep/read to confirm it is fine and does not count as "re-exploring" — "don't invent paths/names" always outranks "don't re-explore."
   5. Skip directly to Phase 4 (Refinement Loop) using the loaded docs as the current draft.

Example (fresh plan):

```text
Base directory : C:\Users\<current_user>\.claude\docs
Slug           : 1234-test-feature
```

This produces:
- Folder: `<base_dir>\<slug>\` (created if absent)
- Plan doc: `<base_dir>\<slug>\<slug>-plan.md`
- Flow diagrams: `<base_dir>\<slug>\<slug>-flow-diagrams.md`
- Summary doc: `<base_dir>\<slug>\<slug>-summary.md`

---

# STRICT RULES

* DO NOT implement code.
* DO NOT modify source files.
* DO NOT generate commits.
* DO NOT call `ExitPlanMode` until explicit user approval.
* MUST call `EnterPlanMode` unless already active.
* Every file listed in the plan must be discovered during exploration.
* Do not invent file paths or architectural components.
* Continue exploring if confidence is insufficient.
* Keep `<slug>-plan.md` and `<slug>-summary.md` in sync — any edit to a section in one must be reflected in the corresponding section of the other (at its own level of detail) before moving on. Never let one drift ahead of the other.
* An `AskUserQuestion` call that comes back indicating no response was captured (e.g. wording like "No response after Ns — continued without an answer") is NOT an answer, no matter which option it appears to default to. Never treat it as approval, confirmation, or a resolved choice — this applies most of all to Phase 4's proceed/refine choice and Phase 4.5's validation items, where a silent default could exit plan mode or rubber-stamp an unreviewed assumption. When this happens, say so plainly and re-ask the same question rather than advancing the phase.

---

# Workflow

## Phase 1 — Enter Plan Mode

Call:

```text
EnterPlanMode
```

Review the project's `CLAUDE.md` and `.claude/rules/` conventions to understand the codebase structure, naming patterns, and level of detail expected for implementation plans.

---

## Phase 2 — Detect Tech Stack & Explore the Codebase

Before launching exploration agents, check the docs repository for an existing spec or flow diagram for this ticket. The slug's ticket-number prefix is the lookup key. If a spec exists, read it — it is the source of truth for endpoint paths, flows, and intended behaviour. During exploration, note any discrepancies between the spec and the current codebase and surface them in Phase 2.5.

Identify the primary technology stack from the codebase (file extensions, project files, imports):

| Detected | Load exploration reference |
|---|---|
| C# / .NET | `./references/exploration-dotnet.md` |
| Kotlin | `./references/exploration-kotlin.md` |
| TypeScript / Angular | `./references/exploration-angular.md` |
| Other / mixed | `./references/exploration-agents.md` (generic) |

Read the matching reference file for agent specifications and focus areas. Launch the agents described there in parallel before proceeding to Phase 2.5.

---

## Phase 2.5 — Architecture Summary

Before planning, summarize:

### Current Architecture

* Relevant modules
* Request flow
* Data flow
* External integrations
* Existing dependencies

### Reusable Patterns

Document:

* Similar features
* Existing abstractions
* Shared components
* Existing conventions

If architecture is unclear, continue exploration. Do not begin planning until sufficient architectural understanding exists.

---

## Phase 2.6 — Integration Test Interview

Most services split integration tests into two layers:

- **Layer 1 — Service/data layer**: exercises business logic and persistence directly, without an HTTP pipeline (e.g., against a real database via an in-memory/test instance, or the ORM's own test-context pattern).
- **Layer 2 — HTTP/API layer**: exercises the full request pipeline (e.g., `WebApplicationFactory<Program>` for ASP.NET Core, or the framework's equivalent) — covers auth, routing, and end-to-end behavior.

Not every service has both layers (e.g., a gRPC-only service or a frontend look different) — identify precisely what layers actually exist here from Agent 3's findings in Phase 2. Never assume a specific database or test-fixture technology; name the one Agent 3 actually found, with its file paths.

### Step 1 — Surface discovered flows

Before asking anything, present a concise list of every flow, endpoint, and use case found during Phase 2 exploration: controller actions, service method entry points, request paths, background jobs. This gives the user a concrete menu to point at rather than asking them to recall the feature from memory.

### Step 2 — Ask the user

Ask:

> Which of the flows above need integration tests? For each, pick a layer:
> - **Layer 1 only** — service logic and data access
> - **Layer 2 only** — HTTP pipeline, JWT, auth policy, route binding
> - **Both** — the flow needs coverage at the service level and end-to-end through the HTTP pipeline

Do not make assumptions. Do not suggest coverage. Wait for the answer before proceeding.

When the user chooses **both** for a flow, record it for both Layer 1 and Layer 2 in Step 3 and mark each entry with a note that the two tests complement each other.

### Step 3 — Sketch a concrete test plan

Using the test project structure, fixtures, and base classes discovered by Agent 3 (not assumed ones), propose for each confirmed flow:

- Test class name and file path (inferred from existing conventions found in exploration)
- The actual collection/fixture/base-class this repo uses for that layer (or "no existing fixture — will need one added" if nothing reusable exists) — never a fixed name like `MongoDbFixture`
- A brief description of each test case and what it asserts
- Seed data required before the test runs

Present the sketch and ask the user to confirm or adjust. Do not proceed to Phase 3 until confirmed.

---

## Phase 3 — Create Output Files

1. Create the folder `<base_dir>\<slug>\` (use `New-Item -ItemType Directory -Force` on Windows).
2. Write the plan to `<base_dir>\<slug>\<slug>-plan.md`. Read `./references/document-template.md` for required sections and formatting rules; every section in the template must appear.
3. Write the flow diagrams to `<base_dir>\<slug>\<slug>-flow-diagrams.md`. Include Mermaid sequence diagrams covering every major flow (happy path, error paths, admin paths). Add a decision matrix where relevant.
4. Write the high-level summary to `<base_dir>\<slug>\<slug>-summary.md`. Read `./references/summary-template.md` for required sections. This doc is for a non-implementer audience (e.g. a Solution Architect) — no code, no line numbers.
5. Open the plan document with: `> **See also:** [Flow Diagrams](./<slug>-flow-diagrams.md) · [Summary](./<slug>-summary.md)`
6. Open the flow diagrams document with: `> **See also:** [Implementation Plan](./<slug>-plan.md) · [Summary](./<slug>-summary.md)`
7. Open the summary document with: `> **See also:** [Implementation Plan](./<slug>-plan.md) · [Flow Diagrams](./<slug>-flow-diagrams.md)`

---

## Phase 4 — Refinement Loop

After generating (or updating) the docs:

1. Present a concise summary.
2. List affected files.
3. List major design decisions.
4. Ask (AskUserQuestion):

   > **Still refine the plan** — I have more changes
   > **Proceed the implementation** — this is ready

   "Still refine the plan" is listed first deliberately — it's the non-destructive default. If the answer comes back as unanswered/timed-out (see STRICT RULES), re-ask; do not fall through to "Proceed."

**Still refine the plan**: ask what to change, then update every affected doc — if a change touches a section that has a counterpart in `<slug>-summary.md` (or vice versa), update both, each at its own level of detail. A single correction is rarely confined to one section — it can also touch code snippets, flow diagrams, edge cases, and risk framing elsewhere in the same doc. After applying the primary edit, grep the changed docs for other mentions of the term/concept you just changed and update those too before calling the doc consistent. Explain exactly what changed, and re-ask the same question. Repeat until the user picks "Proceed the implementation."

**Proceed the implementation**: go to Phase 4.5 — Validation Gate.

---

## Phase 4.5 — Validation Gate

Read the `Validation Required` list in `<slug>-plan.md`.

- **Empty** → go to Phase 5.
- **Non-empty** → present the unresolved items to the user via AskUserQuestion, batched up to 4 items per call. For each item offer options in this order — "Needs change" listed before "Confirmed as assumed" (plus the built-in Other for free text) — so that an unanswered/defaulted response never lands on the option that permanently discards the item. If any item in the batch comes back unanswered/timed-out (see STRICT RULES), leave that item in `Validation Required` and re-ask it rather than marking it resolved either way.
  - Items marked "Confirmed as assumed": mark them resolved in the plan doc (e.g. strike through or move to a "Confirmed Assumptions" note).
  - Items marked "Needs change": capture the correction, update the relevant plan section(s) — and the corresponding section in `<slug>-summary.md` and `<slug>-flow-diagrams.md` wherever one exists — then remove the item from `Validation Required`. Then grep all three docs for other mentions of what just changed (code snippets, diagrams, edge cases, risk/benefit framing) — a correction usually fans out further than the one section it originated in, and a doc left inconsistent elsewhere is worse than an unresolved `Validation Required` item.
- After processing all batches, re-check `Validation Required`. If the corrections introduced new open questions, loop back to Phase 4 (present the delta, re-ask still-refine/proceed) rather than looping Phase 4.5 directly.
- Only proceed to Phase 5 once `Validation Required` is empty.

---

## Phase 5 — Exit Plan Mode

Before calling `ExitPlanMode`, read `./references/quality-checklist.md` and verify every item passes.

Only after the user has chosen "Proceed the implementation" and the Validation Gate (Phase 4.5) is clear:

```text
ExitPlanMode
```

The approved document becomes the implementation brief.

---

# Tone and Formatting

* Be concise and precise.
* Use full file paths.
* Use fenced code blocks.
* Avoid vague statements.
* Prefer concrete technical details.
* Focus on implementation planning, not implementation itself.