Skip to content

PLAN.md

Latest commit

 

History

History
123 lines (86 loc) · 3.49 KB

PLAN.md

File metadata and controls

123 lines (86 loc) · 3.49 KB

PLAN.md

This file is the delivery roadmap for this specific project. It is maintained by Bob throughout the project lifecycle. Claude Code reads this at the start of every session to understand current state.

How to Write and Maintain This File

When to create it

Write PLAN.md during Phase 0, after PROJECT_UNDERSTANDING.md is complete. You cannot plan delivery without understanding what you are building.

How to structure phases

  • Phase 0 is always Foundation — project compiles, auth works, deployment pipeline exists
  • Phase 1+ are feature phases — each phase delivers a working, demonstrable product increment
  • Never plan more than 2 phases ahead in detail — the domain always changes
  • Each phase should end with something you can demo or deploy

The starter ships with Phase 0 already complete. Start your PLAN.md at Phase 1.

How to write sprints

Each sprint must have:

  • A name (e.g. "Sprint 1.2 — Work Order CRUD")
  • A one-sentence goal
  • A checklist of concrete tasks — backend and frontend separated
  • A definition of done — what must be true for this sprint to be complete

Sprint tasks must be concrete enough that Claude Code can execute them without asking a follow-up question.

Bad: "Build the items module"

Good: "Items CRUD — POST /items, GET /items (paginated + filterable), GET /items/:id, PATCH /items/:id, DELETE /items/:id, frontend list page + create/edit dialog, follow Users module pattern exactly"

How to update it

  • When a sprint is complete: mark all tasks ✅, update the status line, move to next sprint
  • When a sprint is blocked: mark it 🚫, add the blocker to TASKS.md
  • When scope changes: add a dated note in the sprint explaining what changed and why
  • Never delete completed sprints — they are the project history

Status markers

  • ✅ Complete
  • 🔄 In progress
  • ⬜ Not started
  • 🚫 Blocked — see TASKS.md for details

Template

Copy everything below this line into your project's PLAN.md and fill it in.

# PLAN.md — [Project Name]

> Last updated: [date]
> Current phase: Phase [N]
> Current sprint: [N.N — Name]
> Status: [In progress / Blocked / Ready for next sprint]

---

## Phase 0 — Foundation ✅
Goal: Project compiles, auth works, deployment pipeline exists.
Status: Complete — provided by starter.

Included in starter:
- [x] Repo initialized and compiling (backend + frontend)
- [x] Environment variables validated on startup (Zod)
- [x] Database connected and migrations running
- [x] JWT auth with httpOnly cookies and refresh rotation
- [x] RBAC — roles, permissions, role-permission assignment
- [x] Users CRUD with avatar upload and soft delete
- [x] Settings module with Redis cache flush
- [x] In-app notifications (DB + email + Socket.IO)
- [x] BullMQ background job queue with status polling
- [x] GitHub deploy hook endpoint
- [x] Swagger docs (dev/staging only)
- [x] Health + status endpoints
- [x] Docker Compose for local MySQL + Redis

---

## Phase 1 — [Module Name]
Goal: [One sentence — what this delivers and why it matters to the client]

### Sprint 1.1 — [Name] ⬜
Goal: [one sentence]

Backend:
- [ ] task
- [ ] task

Frontend:
- [ ] task
- [ ] task

Definition of done: [what must be true]

---

## Deferred / Backlog
- [ ] [Feature] — reason: [why deferred]

---

## Deployment Checklist
- [ ] .env production values set
- [ ] prisma migrate deploy run
- [ ] PM2 process started
- [ ] Nginx config deployed
- [ ] SSL active
- [ ] Smoke test: login, core flow, logout