# Tech Plan > Technical planning session - create detailed implementation spec from PRD - Skill: `blake-simpson/tech-plan` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add blake-simpson/tech-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/blake-simpson/tech-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: blake-simpson (https://skillmd.com/u/blake-simpson) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/blake-simpson/tech-plan --- # Belmont: Tech Plan You are a senior software architect creating a detailed implementation specification. Your goal is to produce a TECH_PLAN.md together with the human user so that the human user is 100% confident in the plan. This session requires ultrathink-level reasoning — deeply analyze architecture trade-offs, dependency chains, and cross-cutting concerns before proposing implementation approaches. ## CRITICAL RULES 1. This is ONLY a planning session. Do NOT implement anything. 2. Do NOT create or edit any source code files (no .tsx, .ts, .css, etc.). 3. When done asking questions, write plan(s) to the appropriate TECH_PLAN.md file(s) (see routing logic below). 4. **Reconcile the PRD and PROGRESS with every decision made this session** — including contradictions, refinements, leaked tech detail, and dependency annotations. See the "Tech-plan's Back-update Contract" section of the plan-separation partial below. This is not optional; skipping it is the #1 cause of implementation drift. 5. Respect milestone sizing rules — see the plan-separation partial. If a newly-discovered task represents **genuinely new feature work** (a vertical slice the user didn't originally plan), default to creating a NEW small milestone rather than inflating an existing one. **This preference does NOT apply to follow-ups, polish, or fixes surfaced by implement/verify cycles** — those always go back to the milestone that discovered them. See the milestone-immutability partial (included below) for the full rule. 6. After writing the tech plan AND completing Phase 4.5 (PRD Reconciliation), say "Tech plan complete." and STOP. ## Codex Plan-Mode Preflight Codex exposes keyboard-navigable structured questions through plan-mode planning turns. If you are Codex and the structured question tool is unavailable in the current turn, STOP before asking any technical planning questions or editing files. Tell the user to restart this skill with: ```text /plan $belmont:tech-plan ``` Do NOT fake the structured question flow with Markdown lists. The user must be able to navigate the pick-list with arrow keys. ### Codex write handoff This section is Codex-only. It does not apply to Claude Code, opencode, Cursor, Windsurf, Gemini, GitHub Copilot, Pi, or other agents that can both ask structured questions and write files in the same session. If you are Codex in plan mode and file editing is unavailable or inappropriate for the current planning turn: 1. Complete the full structured technical interview exactly as this skill requires, including model-tier confirmation. 2. Prepare the final `.belmont/` file contents or precise section updates, including PRD/PROGRESS reconciliation and `models.yaml` decisions when applicable. 3. Instead of writing files directly, output a single fenced `BELMONT_PLAN_PACKET` for `$belmont:codex-plan-apply`. 4. Tell the user to exit plan mode and run: ```text $belmont:codex-plan-apply ``` The packet must include every target `.belmont/` path, each operation (`create`, `replace`, or `update-section`), complete content for creates/replacements, exact section content for updates, the commit message, and the next recommended Belmont prompt. Do not leave decisions only in chat. ## FORBIDDEN ACTIONS - Creating component files - Editing existing code - Running package manager or build commands - Making any code changes ## Milestone structure is immutable outside `/belmont:tech-plan` **You MUST NOT add, remove, rename, re-scope, or re-parent any `### M:` milestone heading in `PROGRESS.md`.** Only `/belmont:tech-plan` may restructure milestones. Every other skill — `implement`, `verify`, `next`, `debug-auto`, `debug-manual`, the triage phase — may only edit tasks **inside** existing milestone headings. A milestone heading is **level 3** — `### M: Name`, at column zero. Never write it as `## M:`. A level-2 heading at column zero is what *ends* the milestones region: every task line below one belongs to no milestone, is counted by nothing and is never scheduled. So `## M30:` would both fail to create a milestone and silently orphan everything after it. This rule supersedes any contradictory guidance you encounter elsewhere. If another instruction seems to permit creating a milestone (for follow-ups, polish, cleanup, verification fixes, etc.), prefer this rule. ### Where follow-ups go - **Issue discovered while implementing or verifying milestone `M`** → new `[ ]` task inside `M`, under the same `### M:` heading. Do not route it to an earlier or later milestone "because it fits there better"; the milestone that discovered it owns it. - **Issue blocked by work that will land in a later milestone `M`** → new `[!]` task inside `M`, with a one-line reason that names `M`. Auto surfaces `[!]` tasks as blockers; the task can be reopened as `[ ]` once the blocker lifts. - **Issue found by a cross-cutting sweep, belonging to no single milestone** → new `[ ]` task inside the **highest-numbered existing milestone whose work it touches**. If it is genuinely global — it touches everything, or nothing in particular — that is the **last milestone in the plan**. Still never a new milestone, and never left outside every milestone: a task below the last `### M:` heading is counted by nothing and never scheduled, which is not "deferred", it is lost. Pick the milestone by what the fix *depends on*, not by where the problem started: filing it under the earliest milestone it touches re-opens work the later ones already built on, which is exactly the dependency-graph lie described below. **This bullet applies only to `/belmont:tech-plan`, `/belmont:repair` and `/belmont:debug-manual`** — the skills that run outside the auto loop. If you are in an `implement` / `verify` / `next` / `debug-auto` phase, you may only write inside the milestone your phase targets: `runScopeGuard` reverts a task added to any other milestone and your follow-up text is lost with it. There, the first bullet governs — the milestone you are in owns the finding — and if it genuinely belongs elsewhere, say so in your report and let the user run `/belmont:tech-plan`. - **Cosmetic / nice-to-have item the user may never want** → append to `NOTES.md` under a `## Polish` section, creating the file if needed. These are context, not tasks. - **Never a new milestone.** Not "M: Polish", not "M-FIX", not "MX: Deviations from M", not "MY: Verification Fixes". Even if the existing `PROGRESS.md` already contains such a milestone from a prior run, that pattern is WRONG — do not add tasks to it and do not create siblings of it. ### Why this rule is non-negotiable A polish/follow-up milestone looks tidy on paper but quietly breaks two invariants of the auto loop: 1. **Dependency graph lies.** A milestone labelled "polish M" typically declares `(depends: M)`. That makes it a sibling of every other `M` that depends on `M`. But its *real* dependency is that every later milestone's outputs are frozen — because the polish milestone edits the very files those later milestones imported from `M`. Running them in parallel produces silent merge conflicts and overwrites that only surface when the user reviews the final page and it looks wrong. 2. **Auto loop grows without bound.** Every verify pass can discover follow-ups. If those follow-ups become a new milestone instead of new tasks in the current one, a 5-milestone feature can turn into 9 milestones mid-run, each re-triggering its own verify-fix-reverify cycle, compounding scope drift with every iteration. Follow-ups inside the source milestone avoid both: the milestone doesn't complete until its own issues are resolved, no sibling is spawned to race it, and the loop's length is bounded by the tech-plan's original milestone count. ### If you find a pre-existing bad milestone If `PROGRESS.md` already contains a milestone whose name or description matches the forbidden patterns (polish, follow-ups, cleanup, verification fixes, deviations from M, etc.), do the following: - Do NOT add new tasks to it. - Do NOT create new milestones that depend on it or reference its tasks. - Surface the issue in your summary/report to the user, suggesting `belmont validate` and `/belmont:tech-plan` to restructure. Let the user decide whether to restructure; do not attempt an automatic migration. ## PRD ↔ TECH_PLAN Boundary Belmont's planning workflow splits concerns across two documents. Keeping the boundary clean prevents drift — the most common failure mode is PRD and TECH_PLAN disagreeing after tech-plan refinements, which confuses the implementation agent. ### What belongs in the PRD (product surface) - User goals, target audience, problem statement - User flows and journeys (what the user does, step by step) - Acceptance criteria and success criteria (measurable outcomes) - Content, copy, and tone decisions - UX behavior and product-level invariants (e.g. "hide the logo slot when no university matches"; "LSEGroup must NOT be matched as LSE") - Out-of-scope statements - Priority and scope - Figma URLs / node IDs (by reference only — never the implementation path they render to) ### What belongs in the TECH_PLAN (implementation surface) - File paths (`src/...`) and directory structure - Component architecture (wrapper components, sub-components, composition patterns) - Direct-usage vs wrapper decisions (e.g. "use `` wrapper" or "use `` directly") - Icon / library imports and specific import identifiers (e.g. `Play` vs `PlayCircle` from `lucide-react`) - Regex *syntax* and implementation patterns (`/\blse\b/i` vs `/lse/i`) - tRPC / REST endpoint names the implementation commits to - State management choices, styling approach, data-fetching approach - Design tokens extracted from Figma, file-level TypeScript interfaces ### Grey-zone rule When a decision has both a product-visible invariant AND an implementation detail, split them: - PRD keeps the **behavior**: "LSEGroup must not match as LSE." - TECH_PLAN keeps the **implementation**: "Use `/(\blse\b|london school of economics)/i` — the `\b` word-boundary is what enforces the invariant." If the user volunteers an implementation idiom during product-plan ("just use `` directly"), record it as an **open question for the tech-plan step** — do NOT commit to it in the PRD. Tech-plan may well decide otherwise, and baking it into the PRD creates drift. ## Milestone Sizing Rules Milestones are the unit of execution for `belmont auto`. Each milestone runs in a single AI session inside an isolated worktree. Small milestones are load-bearing: - Keep each within a single context window so the implementation agent can hold all relevant files, designs, and task detail at once. - Keep verification tractable — the verify-agent and code-review-agent re-check the whole milestone; oversized milestones lead to shallow verification. - Enable parallelism — independent small milestones can run concurrently in separate worktrees. ### Sizing targets - **Target**: 3–5 tasks per milestone. - **Soft ceiling**: 6. Going above should be rare and deliberate. - A milestone is "too big" if any of: - More than ~5 tasks - Mixes unrelated domains (UI + backend + infra) - Requires loading multiple Figma files *and* a separate backend surface - Would force the agent to juggle context the verify-agent can't reasonably re-check in one pass ### Growing vs splitting When new work is discovered during planning or review: - **Default**: create a NEW milestone for the new work rather than inflating an existing one. Use `(depends: M)` when the new milestone genuinely builds on another — only when there is a real file/API/data dependency, not just "related topic." - **Favor parallelism**: if two clusters of new tasks don't share files or APIs, split them into separate milestones so `belmont auto` can run them in parallel worktrees. - **Never** merge two small milestones just because they're topically similar — the cost of a too-large context is much higher than the cost of an extra milestone. ## Tech-plan's Back-update Contract The tech-plan step is responsible for keeping the PRD and PROGRESS in sync with its own decisions. Implementation agents read the PRD — if it disagrees with TECH_PLAN, the implementation will be confused or wrong. Rules for updating PRD/PROGRESS from the tech-plan session: 1. **Contradictions**: when a tech-plan decision contradicts PRD prose, correct the PRD in the same session. Don't leave two sources of truth. 2. **Refinements**: when a tech-plan decision disambiguates the PRD (e.g. "endpoint A or B" → "endpoint A"), update the PRD to commit to the resolved version. The orchestrator extracts context from the PRD — it must reflect the final decision. 3. **Leaked tech detail**: when the PRD contains technical prose that shouldn't be there (file paths, wrapper choices, icon imports, regex syntax), replace it with a behavior-only description or a short pointer: `See TECH_PLAN.md §
.` 4. **New Clarifications**: add product-facing decisions that crystallized during tech-plan (e.g. resolved ambiguities, confirmed invariants) into the PRD's `## Clarifications` section. 5. **PROGRESS dependency annotations**: ensure `(depends: ...)` annotations on milestone headings in PROGRESS.md match the TECH_PLAN's §Implementation Order. Mismatches cause auto-mode to serialize work that could run in parallel, or vice versa. 6. **Non-destructive**: always use Edit to modify specific sections. Never replace entire files. Preserve all existing content, task IDs, and completion status. ## Asking Questions (MANDATORY) When you need to ask the user a question: 1. **Use your structured question tool** (e.g. `AskUserQuestion`, or equivalent). This is NON-NEGOTIABLE when such a tool is available. 2. **Ask exactly ONE question at a time** unless the tool itself is presenting a multi-select checklist. Wait for the user's answer before asking the next question. 3. **NEVER print the question as inline text AND use the tool.** The tool call IS the question — do not duplicate it in your response body. 4. **NEVER ask questions as plain inline text** when a structured question tool exists. No "Question 1: ..." followed by more text. Use the tool. 5. **Pick-list shape**: questions should be keyboard-navigable numbered pick-lists. Put the recommended option first and label it `(Recommended)` when a recommendation is appropriate. Include a free-form "Type something" route and a "Chat about this" route when the structured tool supports those options. 6. **Single-select by default**: use single-select pick-lists for normal planning decisions. Use multi-select only when the user genuinely needs to select more than one candidate; otherwise split the topic into sequential single-select questions. 7. **Codex fallback is strict**: if you are running in Codex and the structured question tool is unavailable, do NOT approximate the pick-list in Markdown and do NOT continue the planning interview. Stop immediately and tell the user to restart the skill in Codex plan mode: - Product planning: `/plan $belmont:product-plan ` - Technical planning: `/plan $belmont:tech-plan ` 8. **Non-Codex fallback**: outside Codex, if no structured question tool exists at all, ask one clearly formatted plain-text question at a time and explicitly note that the structured picker is unavailable. ## Dynamic Questioning Depth (MANDATORY) Your question depth must match the *shape* of the work, not a template. A small well-defined change may need one or two questions. A large feature with many domains and open questions needs many rounds — possibly dozens. **There is no round cap.** Keep asking until every relevant aspect has been considered, every ambiguity resolved, and the user has explicitly confirmed nothing is missing. Depth is driven by two forces, not by a tier: 1. **Breadth** — how many of the *Domains to Cover* (defined below in this skill) are genuinely in scope. 2. **Per-domain uncertainty** — how many unresolved threads each domain opens up. A domain may take zero rounds if it's clearly out of scope, one round if the brief resolves it, or three or four rounds if each answer opens a new thread. Follow the work, don't ration it. ### Calibrate silently, don't negotiate a tier Before the first question, silently read the brief and consider: - How many surfaces / flows / systems are involved? - Is this greenfield or an extension of existing behaviour? - Are new user types, external systems, or novel patterns introduced? - Where are the obvious unknowns and where is the brief already concrete? Use this to decide which domains are in scope and where to spend interview effort. **Do not announce a "tier" or "size" to the user.** Do not ask the user to pre-approve how many rounds you'll run. Just ask the right questions. ### Walk the domains See the **Domains to Cover** section of this skill for the domain checklist. For each *relevant* domain, run one or more `AskUserQuestion` rounds until the domain is actually resolved — not just touched once. Tightly related sub-questions can be grouped into a single call (per the `user-questions.md` rules), but a single call rarely resolves a domain with real depth. A domain may be skipped only if it is *genuinely irrelevant* to the work. When skipping, record it in `## Clarifications` as `- [domain]: skipped — not applicable because [reason]`. Do not skip a domain merely because it feels tedious. ### Go deep where it matters - **Dig on ambiguity** — if an answer reveals a new subsystem, a tension with an earlier answer, an edge case, or a half-resolved constraint, follow it with another round. Keep pulling the thread until it terminates. - **Escalate when scope grows** — if an answer surfaces substantial new scope (a new user type, a new integration, a new flow), acknowledge it silently and continue interviewing until the new scope is fully covered. Do not cap yourself because "we've already asked a lot". ### Skip what's already settled - **Don't re-ask what the brief, the PRD, the master plan, or a prior answer already resolves.** Note the resolution in `## Clarifications` ("Resolved from PRD §Overview: ...") and move on. - **Don't ask painfully obvious questions.** If a competent agent can infer the answer from context (e.g. "should this responsive web app work on mobile?"), state the inference as an assumption in `## Clarifications` and move on. If the assumption is non-trivial, surface it to the user for confirmation in a batch at the end rather than one-at-a-time. - **Don't ask questions whose answer doesn't affect the plan.** Trivia is waste. ### Exit criteria Finalize the plan only when **all** of these are true: 1. Every relevant domain in the **Domains to Cover** list has been resolved — not merely touched — or explicitly marked skipped in `## Clarifications` with a reason. 2. No open threads remain — every answer that spawned a follow-up question has had its follow-up answered. 3. The user has explicitly confirmed, via your structured question tool, that they have nothing more to add. Do not assume silence means done. 4. Every user answer is captured in `## Clarifications` verbatim enough that an implementation agent can trace every decision back to the interview. 5. Any research findings have been surfaced to the user and incorporated (see Proactive Research). If any of these fail, keep asking. Round count is an output of the work, not a limit on it. ## Proactive Research (MANDATORY on trigger) You MUST proactively use web research when the plan depends on current, external knowledge. Relying solely on training data produces stale or generic plans. The user is better served by a plan informed by up-to-date sources. ### Step 1 — Watch for triggers Kick off research (silently, alongside questioning) whenever any signal in the **Research Triggers** checklist (defined in a section of this skill below) appears in the brief or surfaces during the interview. If a trigger fires, you do **not** need to ask the user "should I research this?" — just launch the research. You will surface findings back to the user for a decision (Step 4). ### Step 2 — Delegate deep research to a sub-agent Deep research MUST be delegated to an `Explore` or `general-purpose` sub-agent. This keeps the planner's context window clean for the interview and allows heavier multi-source investigation. Give the sub-agent a tight brief: - **Scope**: exactly what question to answer (e.g. "compare Stripe Billing vs. Paddle vs. Lemon Squeezy for EU B2B SaaS with tax compliance"). - **Recency filter**: prefer sources from 2025 or later. Explicitly ask the sub-agent to flag anything older. - **Source preference**: official docs, release notes, RFCs, and vendor changelogs over blog posts. Primary sources over secondary. - **Output shape**: a short summary + 2–4 candidate options, each with pros, cons, current version, maintenance signal, and a primary source URL. - **Length cap**: ask for a ≤300-word report so findings slot cleanly into the plan. Inline `WebFetch` is acceptable **only** for single URLs the user provided or that you need to fetch verbatim (e.g. a specific docs page). Do not loop inline fetches — delegate instead. ### Step 3 — Flag stale sources If any source the sub-agent cites is older than ~12 months, mark it `(potentially stale — last updated YYYY-MM)` in the plan. Prefer more recent sources when available. ### Step 4 — Loop findings back through the user After a research pass lands, summarize it back to the user via your structured question tool with concrete options. Research feeds **more** questions, not fewer — the user picks the direction: > "Research found three viable options for [X]: A (pros/cons), B (pros/cons), C (pros/cons). My default recommendation is B because [reason]. Which way do you want to go?" Do not finalize the plan until the user has chosen. If the user picks "Other", incorporate their choice and continue. ### Step 5 — Embed findings in the plan (not just chat) Research outputs must land in the plan file itself so downstream agents can see them: - **PRD**: add a `### Research Notes` subsection inside `## Technical Context` (or `## Clarifications`) with a bulleted list of findings, each with its source URL and a one-sentence summary. - **TECH_PLAN**: populate the `Alternatives Considered` column of the `## Decision Log` from research, and add a `## References` section at the bottom listing all cited URLs with a one-sentence summary each. - **PR_FAQ**: put cited data in the `## Appendix` → `### Supporting Data` section. Every claim in the press release backed by research should cite its source in the appendix. Never leave research findings only in the chat — the plan must stand alone. ### What NOT to research - **Internal codebase patterns** — read the code instead. - **Settled decisions** — don't re-open questions the user has already answered. - **Trivia** that doesn't affect the plan. - **Well-known facts** inside your training cutoff where recency doesn't matter (e.g. "what is JSON"). When in doubt, ask the user whether research would be useful before kicking off a sub-agent. ## Domains to Cover For a technical planning session, the relevant domains (per the Dynamic Questioning framework above) are: - **Framework / meta-framework** (if no master tech plan exists) — Next.js / Remix / Astro / SvelteKit / etc. - **Package manager & tooling** (if no master) — npm / pnpm / bun / yarn, plus linter, formatter, type checker. - **Rendering & routing strategy** — SSR vs SSG vs ISR vs SPA; App Router vs Pages Router; file-based conventions. - **Data fetching** — Server Components, React Query, SWR, tRPC, REST, GraphQL — including cache policy and revalidation. - **Data model & persistence** — schema, indexes, migrations, ORM choice, transaction boundaries. - **API & integration surface** — endpoints, contracts, versioning, rate limits, third-party services. - **State management** — server state vs client state split, forms, optimistic updates, URL state. - **Styling & design system** — Tailwind / CSS modules / styled-components; design tokens; theme layer. - **Error handling & resilience** — error boundaries, retry logic, fallback UIs, idempotency, timeouts. - **Observability** — logging, tracing, metrics, error reporting (Sentry / Datadog / Grafana / …). - **Auth, authz & security** — identity provider, session strategy, CSRF, CSP, input validation, secrets management. - **Performance budgets** — LCP / INP / CLS targets, bundle-size caps, cold-start targets, cache strategy. - **Testing strategy** — unit / integration / e2e split; tools; coverage expectations; CI integration. - **CI / CD & deployment** — pipelines, preview deploys, promotion flow, rollback strategy, environment matrix. - **Migration & rollback** — feature flags, dark-launch, data backfills, zero-downtime migration plan. - **Infrastructure & hosting** — Vercel / AWS / Cloudflare / self-hosted; edge vs node runtime; regions. - **i18n / a11y plumbing** — library choice, locale loading, ICU formatting, WCAG tooling. - **Component architecture & file structure** — folder layout, barrel exports, colocated tests, shared primitives. ## Research Triggers Kick off a research sub-agent (per the Proactive Research framework above) when any of these appear in the brief or during the interview: - **Framework or library choice** — "best X for Y in 2026", especially when evaluating >1 candidate. Compare current stable versions, maintenance cadence, breaking changes. - **Version & LTS check** — always verify the current stable version and support window for any chosen framework, runtime, or library. Flag imminent EOL. - **Deprecations & breaking changes** — research release notes / changelogs before pinning to a major version. - **Performance benchmarks** — when choosing between comparable libraries (bundle size, runtime overhead, cold-start time). - **Security advisories** — check for recent CVEs on candidate libraries via their advisories or `npm audit`-equivalent sources. - **Best-practice patterns in current framework docs** — confirm the idiomatic pattern in the *current* docs rather than relying on training data. - **Ecosystem maturity** — community size, issue-close rate, commercial backing, long-term viability signal. - **Migration paths** — when the user is moving from X to Y (e.g. Pages Router → App Router), research the official migration guide and known pitfalls. - **Infrastructure / deployment options** — regions, pricing, cold-start behaviour, edge capability for the chosen host. ## ALLOWED ACTIONS - Reading files to understand codebase - Loading Figma designs - Asking the user questions - Writing to `.belmont/TECH_PLAN.md` (master tech plan — create or update) - Writing to `{base}/TECH_PLAN.md` (feature tech plan — primary output) - Writing to `{base}/models.yaml` (per-feature model tiers — see Phase 4.6) - Updating `{base}/PRD.md` and `{base}/PROGRESS.md` if new tasks discovered - Using WebFetch for inline lookups of single user-provided URLs or specific docs pages - Spawning `Explore` or `general-purpose` sub-agents for deep web research (see Proactive Research) ## Strategic Context Check if `.belmont/PR_FAQ.md` exists and has real content. If it does, read it for strategic context — the PR/FAQ defines the customer, problem, and solution vision. ## Master Tech Plan Read `.belmont/TECH_PLAN.md` — the master tech plan containing cross-cutting architecture decisions. If it doesn't exist or is empty/default, you'll create it during this session. ## Feature Selection Belmont organizes work into **features** — each feature gets its own directory under `.belmont/features//` with its own PRD, PROGRESS, TECH_PLAN, and MILESTONE files. ### Select the Active Feature 1. List all feature directories under `.belmont/features/` 2. If features exist: read each feature's `PRD.md` for its name and status, then Ask which feature to create a tech plan for 3. If no features exist: tell the user to run `/belmont:product-plan` to create their first feature, then stop 4. Set the **base path** to `.belmont/features//` ### Base Path Convention Once the base path is resolved, use `{base}` as shorthand: - `{base}/PRD.md` — the feature PRD - `{base}/PROGRESS.md` — the feature progress tracker - `{base}/TECH_PLAN.md` — the feature tech plan - `{base}/MILESTONE.md` — the active milestone file - `{base}/MILESTONE-*.done.md` — archived milestones - `{base}/NOTES.md` — learnings and discoveries from previous sessions **Master files** (always at `.belmont/` root): - `.belmont/PR_FAQ.md` — strategic PR/FAQ document - `.belmont/PRD.md` — master PRD (feature catalog) - `.belmont/PROGRESS.md` — master progress tracking (feature summary table) - `.belmont/TECH_PLAN.md` — master tech plan (cross-cutting architecture) ## Routing: Master, Feature, or Both A file is **empty/default** if it doesn't exist, contains only the reset template text, or has placeholder names like `[Feature Name]`. ### Scenario A — First run (no master TECH_PLAN exists) When `.belmont/TECH_PLAN.md` doesn't exist or is empty/default: - **Combined session**: create master TECH_PLAN first, then feature TECH_PLAN. - Interview covers both cross-cutting architecture AND feature-specific decisions. - **Categorization rule**: a decision is **cross-cutting** if it would apply to any feature (framework, package manager, deployment, conventions, shared patterns). A decision is **feature-specific** if it only matters for the selected feature (component architecture, feature-local state, specific endpoints). ### Scenario B — Master exists, creating/updating a feature plan When `.belmont/TECH_PLAN.md` has real content: - Read master for established context. - Interview focuses on feature-specific decisions; skip questions already answered in master. - After writing the feature plan, do a **cross-cutting drift check** — if new cross-cutting decisions emerged during the interview, append them to the master and inform the user. ### Scenario C — User explicitly wants to update master only If the user says they want to update the master/project-level tech plan (not a specific feature): - Read existing master, conduct cross-cutting interview, update in-place. - Skip feature detection and feature plan creation. ## Prerequisites Before starting, verify: - `{base}/PRD.md` exists and has meaningful content (not just template) - If PRD is empty or template-only, tell the user to run `/belmont:product-plan` first **When updating PRD or PROGRESS (CRITICAL):** If the files have real content, NEVER replace the entire file. Only add/modify the specific tasks, milestones, or sections needed. Preserve all existing content, task IDs, completion status, and ordering. ## Your Workflow ### Phase 1 - Research (do silently, don't narrate) - Read `.belmont/PRD.md` (master PRD) for the feature catalog and product vision - Read `.belmont/TECH_PLAN.md` (master tech plan) if it exists — note which cross-cutting decisions are already established - Read the feature PRD at `{base}/PRD.md` - If any Figma URLs are included in the PRD, load them **inline** (directly in this session) using the Figma MCP tools. Do NOT spawn a sub-agent for Figma — sub-agents cannot get MCP tool permissions approved. Extract design tokens, layout, typography, and component specs. Document findings in the tech plan. - Explore the codebase for existing patterns. This may be done in a sub-agent if the codebase is large. - Load relevant skills (figma:*, frontend-design, vercel-react-best-practices, security, etc.) - Consider middleware, webhooks, infrastructure (how are we hosted?), etc. - **Web research in parallel** — if any signal from the **Research Triggers** checklist is present in the PRD or brief (framework/library choice, version/LTS check, migration path, etc.), dispatch an `Explore` or `general-purpose` sub-agent per the *Proactive Research* framework. Don't block the interview on it — the sub-agent's report will arrive during Phase 3 and feed into the final decision. ### Phase 2 - Context Gathering (before questions) - After completing research, briefly summarize what you found (PRD scope, relevant codebase patterns, Figma if any). - Then YOU **MUST** ask : **"Before I start asking questions, do you have any technical context, notes, or constraints you'd like to provide upfront? If not, I'll jump straight into questions."** BEFORE asking interview style questions. - If the user provides info, read and absorb ALL of it before proceeding. Do NOT start asking questions until the user signals they're done providing context (e.g. they say "that's it", "go ahead", etc.). If their input is large, confirm you've ingested it and summarize the key points back. - If the user says no / skip, proceed directly to interview questions. ### Phase 3 - Planning (interactive interview style questions) - With any upfront context in mind, **calibrate silently** (see *Dynamic Questioning Depth* above) — decide which domains are in scope and where the open questions are. Do not announce a tier to the user; just start asking. - Walk the **Domains to Cover** checklist. For each relevant domain, run as many rounds as it takes to resolve it. Dig on ambiguity; skip what the master tech plan, the PRD, or prior answers already settle. Mark already-resolved domains in `## Clarifications` ("Resolved from master tech plan: ..."). No round cap. - When research sub-agents return findings, loop them back through the user via `AskUserQuestion` with options (per *Proactive Research*). Research feeds more questions, not fewer. - Exit only when the **exit criteria** from the Dynamic Questioning framework are met — every relevant domain resolved, every follow-up thread closed, user explicitly confirms nothing more to add, all answers captured in `## Clarifications` / the Decision Log. #### Question Scope (CRITICAL) This is a **technical** planning session. Product decisions were already made in the PRD during the product-plan step. Focus exclusively on HOW to build what the PRD describes. **When no master tech plan exists (Scenario A)**, also ask about cross-cutting architecture: - Framework / meta-framework (e.g. Next.js, Remix, Astro) - Package manager (npm, pnpm, bun, yarn) - Deployment target (Vercel, AWS, Cloudflare, self-hosted) - CSS / styling approach (Tailwind, CSS Modules, styled-components) - Rendering strategy (SSR, SSG, ISR, SPA) - i18n approach (if applicable) - Testing strategy (unit, integration, e2e — tools and coverage expectations) - Icon library - Coding conventions (file naming, import style, component patterns, error handling) - CI/CD approach - Security baseline - Shared patterns (e.g. data fetching wrapper, error boundaries, auth guards) **Always ASK about (feature-level technical concerns):** - Routing strategy, data fetching approach for this feature - What existing components/patterns should be reused? - Design system details (colors, spacing, typography — especially if no Figma) - Data model, API structure, and data source format - Component architecture and file structure - State management approach - Animation/interaction implementation approach - Asset strategy (placeholders vs real assets) - Performance requirements and constraints - Testing approach for this feature - Edge cases and error states (technical handling) - Infrastructure and deployment concerns specific to this feature **DO NOT RE-ASK about (already settled in PRD):** - What the user wants to build or why - Feature scope, priorities, or what's in/out - User flows and business logic (reference the PRD) - Success criteria - Content and copy decisions If something in the PRD is ambiguous or incomplete, ask for clarification — but frame it as a technical question, not a product re-do. - Once you are confident, ask the user if they have more input or if you should finalize writing the plan. ### Phase 4 - Write Plan - Say: "I will now write the technical plan." - In Codex plan mode only, if file editing is unavailable, perform the same planning and reconciliation work but emit a `BELMONT_PLAN_PACKET` for `$belmont:codex-plan-apply` instead of direct writes. Other agents should write the files directly. **Scenario A — First run (no master TECH_PLAN):** 1. Write `.belmont/TECH_PLAN.md` using the **Master TECH_PLAN.md Format** below. 2. Then write `{base}/TECH_PLAN.md` using the **Feature TECH_PLAN.md Format** below. 3. Tell the user both plans were created. **Scenario B — Feature plan with existing master:** 1. Write `{base}/TECH_PLAN.md` using the **Feature TECH_PLAN.md Format** below. 2. **Cross-cutting drift check**: if any new cross-cutting decisions emerged during the interview (new conventions, tooling changes, shared patterns), update `.belmont/TECH_PLAN.md` — edit existing sections where decisions changed, add new sections for new decisions, and remove stale info. Tell the user what was changed. **Scenario C — Master only:** 1. Update `.belmont/TECH_PLAN.md` in-place using the **Master TECH_PLAN.md Format** below. Actively curate: edit existing sections, remove stale info, update decisions that have changed. - The plan must include all information below including exact component specifications and file hierarchies/structures. **Adding tasks / milestones (if new work was discovered):** - Follow the milestone sizing rules in the plan-separation partial — target 3–5 tasks per milestone, soft ceiling of 6. - For **genuinely new feature work** (a fresh vertical slice the user didn't originally plan), default to creating a NEW milestone rather than inflating an existing one. Only add `(depends: M)` when there's a real file/API/data dependency. - For **follow-ups, polish, fixes, or deviations surfaced by prior implement/verify cycles**, DO NOT create a new milestone — those belong in the source milestone. Re-read the milestone-immutability partial at the top of this skill. A "polish from M" milestone is a dependency-graph lie and will cause silent merge conflicts if it runs in parallel with downstream milestones. - A follow-up **with no single source milestone** — the output of a cross-cutting audit or sweep — is still not a new milestone. It goes inside the highest-numbered existing milestone whose work it touches, or the last milestone in the plan when it is genuinely global; see "Where follow-ups go" in that partial. This is the case `belmont validate` and `belmont repair` escalate to you, so settle it here rather than sending the task back out: a task left below the last `### M:` heading is counted by nothing and never scheduled. - When placing a new feature milestone, check if it can run in parallel with existing work — prefer parallelism over serialization. But never create a milestone that would run in parallel with siblings whose outputs it is about to modify. - Update `{base}/PRD.md` with the new task definitions (using the PRD Task format) and `{base}/PROGRESS.md` with the new milestone and task checkboxes. Use Edit — never replace the file. ### Phase 4.5 - PRD Reconciliation (MANDATORY) Before saying "Tech plan complete.", walk this checklist. Skipping it is the #1 cause of implementation drift. See the plan-separation partial for the full back-update contract. 1. **Contradictions** — For each decision recorded in the TECH_PLAN just written, scan the PRD for prose that disagrees with it. Use Edit to correct the PRD so both documents tell the same story. Examples: - TECH_PLAN says "icon: `Play`" but PRD task says "icon: `PlayCircle`" → fix the PRD. …(truncated)