Develop: Refactor Plan
Audit the current codebase against docs/PRD.md, review the differences with the user, and write a phased refactor plan to docs/REFACTOR.md. Do not write the plan until the review in step 2 is complete. If docs/PRD.md is missing, do not stop — generate the refactor-scoped PRD first (step 0 below), then continue as normal.
0. No docs/PRD.md? Generate the refactor PRD
Members refactoring an existing app don't need the full studio-develop-prd-roadmap interview — the app already answers most of its questions. Derive a refactor-scoped PRD instead:
- Read
docs/PRODUCT.md and docs/DESIGN.md in full (they're required by this phase; if either is missing, run its fast-track producer first — studio-define-from-code → studio-define-product, or studio-design-design-system-from-code).
- Explore the codebase: structure, stack, data models, screens, auth/payment integrations — what the app is today.
- Interview the user briefly, drawing on
productos/develop/guides/PRD-GENERATION.md and TECH-STACK-OPTIONS.md: the core loop, what the refactored app must do that today's doesn't, what today's does that should go, and the target stack (confirm or change).
- Write
docs/PRD.md — the target state of this product, in the standard PRD shape, opening with the note > Refactor-scoped PRD, generated by studio-develop-refactor-plan from PRODUCT.md, DESIGN.md, the existing codebase, and the member's decisions. Spec what exists-and-stays, what changes, and what's added; skip from-scratch MVP scoping that doesn't apply.
No separate docs/ROADMAP.md is needed on this path — docs/REFACTOR.md (step 3) is the executable plan, and its format below stands alone. Later feature work reads the PRD as usual.
1. Audit the codebase against the PRD
Read both spec documents in full, then explore the repository: structure, dependencies, data models, API surface, screens, and auth/payment integrations. Build a complete list of differences, classified as:
- Missing — required by the PRD but absent from the code (features, screens, entities, endpoints, states, requirements).
- Divergent — present in both but implemented differently (stack mismatches, schema differences, different auth/payment providers, structure that doesn't match the PRD's repository layout, styling that ignores
docs/DESIGN.md tokens).
- Extra — present in the code but absent from the PRD (features, dependencies, dead code, abandoned experiments).
For each difference, note the evidence: file paths, the PRD section it relates to, and a one-line impact assessment.
2. Review the differences with the user, one at a time
Present differences one at a time — never as one giant wall. For each: what was found, what the PRD says, a recommendation (keep / remove / refactor / defer), and the cost of each option. Then let the user decide. Group trivially related items where it helps, but every Extra item needs an explicit keep-or-remove decision, and every Divergent item needs a decision on which side wins — the code or the PRD. If the user keeps something the PRD doesn't cover, flag that the PRD should be updated and note it for the plan's footer. Record every decision; these define the plan's scope.
3. Write docs/REFACTOR.md
Once all decisions are made, show the user the proposed phase outline — titles, goals, rough task counts — and get approval. Then write the plan in exactly the same format as docs/ROADMAP.md (the format below stands alone when no roadmap exists):
Header: # Refactor Plan — {productName}, the note > Generated by ProductOS. Checkboxes are updated as tasks are completed. The coding agent MUST mark tasks [x] as they are finished., a **Status:** 0/{total} tasks complete line, and a **Current Phase:** line.
Refactor Philosophy: the app must remain runnable after every phase; removals before rebuilds; one concern per task; test as you go; build straight through — commit at each phase boundary, no PR required, using the coding agent's built-in review for a quality pass.
Phases sized to the actual work (typically: cleanup and removals → foundation/stack alignment → feature parity → polish and verification). Every phase has a descriptive title, a one-sentence Goal, and a Reference sections list pointing at the exact docs/PRD.md and docs/DESIGN.md headings needed.
Tasks in the exact three-line format, IDs sequential across all phases (TASK-001 through TASK-NNN):
- [ ] **TASK-001** — Description of what to do
Files: `file1.ts`, `file2.ts`
Notes: Specific implementation details, gotchas. Verify: how to confirm it works.
Every task traces to a reviewed decision or PRD requirement, is ordered for sequential execution, sized to roughly one agent session (15–45 minutes), and ends its Notes with a verification step.
Agent Session Guide: read selectively via Reference sections, never skip tasks, update the status line, commit and push at each phase boundary.
Footer: the decisions made in step 2 (kept, removed, deferred) and any PRD updates the user agreed to.
Finish by summarizing in conversation: phase count, task total, anything deferred — and point the user at studio-develop-refactor-build to execute the plan.
1---2name: studio-develop-refactor-plan3description: Use inside an **existing app codebase** when the user wants a plan to bring the code in line with their ProductOS spec documents. Triggers on phrases like "create a refactor plan", "audit my codebase against the PRD", "plan the refactor", "what's different between my app and the PRD", "make REFACTOR.md", or any request to compare an existing codebase to `docs/PRD.md` and produce an actionable migration plan. Reads `docs/PRD.md` and `docs/ROADMAP.md` when they exist; when they don't, generates its own refactor-scoped PRD from `docs/PRODUCT.md`, `docs/DESIGN.md`, the codebase, and a short interview — no need to run `studio-develop-prd-roadmap` first. Audits the codebase, classifies every difference (missing / divergent / extra), walks the user through keep-or-remove decisions one at a time, then writes `docs/REFACTOR.md` — a phased, checkbox-tracked plan in the same format as the roadmap, executable by `studio-develop-refactor-build`.4---56# Develop: Refactor Plan78Audit the current codebase against `docs/PRD.md`, review the differences with the user, and write a phased refactor plan to `docs/REFACTOR.md`. Do not write the plan until the review in step 2 is complete. If `docs/PRD.md` is missing, do not stop — generate the refactor-scoped PRD first (step 0 below), then continue as normal.910## 0. No `docs/PRD.md`? Generate the refactor PRD1112Members refactoring an existing app don't need the full `studio-develop-prd-roadmap` interview — the app already answers most of its questions. Derive a **refactor-scoped PRD** instead:13141. Read `docs/PRODUCT.md` and `docs/DESIGN.md` in full (they're required by this phase; if either is missing, run its fast-track producer first — `studio-define-from-code` → `studio-define-product`, or `studio-design-design-system-from-code`).152. Explore the codebase: structure, stack, data models, screens, auth/payment integrations — what the app *is* today.163. Interview the user briefly, drawing on `productos/develop/guides/PRD-GENERATION.md` and `TECH-STACK-OPTIONS.md`: the core loop, what the refactored app must do that today's doesn't, what today's does that should go, and the target stack (confirm or change).174. Write `docs/PRD.md` — the **target state** of this product, in the standard PRD shape, opening with the note `> Refactor-scoped PRD, generated by studio-develop-refactor-plan from PRODUCT.md, DESIGN.md, the existing codebase, and the member's decisions.` Spec what exists-and-stays, what changes, and what's added; skip from-scratch MVP scoping that doesn't apply.1819No separate `docs/ROADMAP.md` is needed on this path — `docs/REFACTOR.md` (step 3) is the executable plan, and its format below stands alone. Later feature work reads the PRD as usual.2021## 1. Audit the codebase against the PRD2223Read both spec documents in full, then explore the repository: structure, dependencies, data models, API surface, screens, and auth/payment integrations. Build a complete list of differences, classified as:2425- **Missing** — required by the PRD but absent from the code (features, screens, entities, endpoints, states, requirements).26- **Divergent** — present in both but implemented differently (stack mismatches, schema differences, different auth/payment providers, structure that doesn't match the PRD's repository layout, styling that ignores `docs/DESIGN.md` tokens).27- **Extra** — present in the code but absent from the PRD (features, dependencies, dead code, abandoned experiments).2829For each difference, note the evidence: file paths, the PRD section it relates to, and a one-line impact assessment.3031## 2. Review the differences with the user, one at a time3233Present differences one at a time — never as one giant wall. For each: what was found, what the PRD says, a recommendation (keep / remove / refactor / defer), and the cost of each option. Then let the user decide. Group trivially related items where it helps, but every **Extra** item needs an explicit keep-or-remove decision, and every **Divergent** item needs a decision on which side wins — the code or the PRD. If the user keeps something the PRD doesn't cover, flag that the PRD should be updated and note it for the plan's footer. Record every decision; these define the plan's scope.3435## 3. Write `docs/REFACTOR.md`3637Once all decisions are made, show the user the proposed phase outline — titles, goals, rough task counts — and get approval. Then write the plan in exactly the same format as `docs/ROADMAP.md` (the format below stands alone when no roadmap exists):3839- **Header:** `# Refactor Plan — {productName}`, the note `> Generated by ProductOS. Checkboxes are updated as tasks are completed. The coding agent MUST mark tasks [x] as they are finished.`, a `**Status:** 0/{total} tasks complete` line, and a `**Current Phase:**` line.40- **Refactor Philosophy:** the app must remain runnable after every phase; removals before rebuilds; one concern per task; test as you go; build straight through — commit at each phase boundary, no PR required, using the coding agent's built-in review for a quality pass.41- **Phases** sized to the actual work (typically: cleanup and removals → foundation/stack alignment → feature parity → polish and verification). Every phase has a descriptive title, a one-sentence Goal, and a Reference sections list pointing at the exact `docs/PRD.md` and `docs/DESIGN.md` headings needed.42- **Tasks** in the exact three-line format, IDs sequential across all phases (TASK-001 through TASK-NNN):4344 ```markdown45 - [ ] **TASK-001** — Description of what to do46 Files: `file1.ts`, `file2.ts`47 Notes: Specific implementation details, gotchas. Verify: how to confirm it works.48 ```4950 Every task traces to a reviewed decision or PRD requirement, is ordered for sequential execution, sized to roughly one agent session (15–45 minutes), and ends its Notes with a verification step.51- **Agent Session Guide**: read selectively via Reference sections, never skip tasks, update the status line, commit and push at each phase boundary.52- **Footer:** the decisions made in step 2 (kept, removed, deferred) and any PRD updates the user agreed to.5354Finish by summarizing in conversation: phase count, task total, anything deferred — and point the user at `studio-develop-refactor-build` to execute the plan.
buildgreatproducts