4.4 KiB
Development Plan
SOP Governance Tool — Stage 1
Assumption: solo beginner + Claude Code, 10–15 focused hrs/week ⇒ ~15–17 weeks. Each milestone ends with a demo you can show on your own phone/laptop and a short acceptance checklist. Do not start a milestone until the previous checklist passes.
Golden rules:
- One milestone at a time. Resist building ahead.
- Never paste code you can't explain. Ask Claude Code to explain until you can.
- Commit after every working step with a plain-English message.
- Deploy to Vercel from Week 1 — always have a live URL.
M0 · Setup (Week 1)
Scaffold Next.js + TypeScript + Tailwind + shadcn/ui; create Supabase project (Singapore); run db/schema.sql; connect; deploy "hello world" to Vercel; put this /docs pack + CLAUDE.md in the repo.
✅ Live URL loads · schema visible in Supabase table editor · repo pushed.
M1 · Auth & Users (Weeks 2–3) — FR-1.x
Login/logout; profiles; role-based redirect; Users & Departments admin pages; JWT claims hook; role guard middleware. ✅ Staff login lands on /my-sops and CANNOT open /users (test it) · admin can invite a user and change a role · deactivated user blocked.
M2 · SOP Repository & Editor (Weeks 4–6) — FR-2.x
SOP list with filters/search; create SOP; structured editor with steps + photo upload; autosave. ✅ Create WH-PICK-001, add 5 steps with 2 photos, refresh mid-edit and lose ≤10s · duplicate code rejected politely.
M3 · Governance (Weeks 7–8) — FR-3.x
lib/workflow.ts state machine; submit / decide / publish routes; version snapshotting; approvals queue; version history tab; audit log writes + audit page.
✅ Full loop: draft → submit → approve → publish v1.0 → edit → publish v1.1 → open v1.0 frozen content · reject requires a comment · every action appears in audit log · illegal transitions blocked at API (curl test).
M4 · Distribution & Acknowledgement (Weeks 9–10) — FR-4.x
Assign departments; staff My SOPs + mobile viewer; acknowledge flow with typed-name signature; share link; re-ack on new version. ✅ On YOUR OWN PHONE: staff account sees assigned SOP in BM… acknowledges… it moves to "Acknowledged" · same user cannot ack twice · publishing v1.2 moves it back to "Needs acknowledgement".
M5 · Dashboard & Reports (Week 11) — FR-5.x
Stat cards; per-SOP % table; department table; overdue-review flag; CSV export. ✅ Numbers match a hand-count of seeded data · CSV opens in Excel with outstanding names listed.
M6 · AI (Weeks 12–13) — FR-6.x
/api/ai/draft + editor modal; /api/ai/translate + translations tab + reviewed flag; ai_log; rate limit.
✅ Describe a process in 3 sentences → usable structured draft in the editor · translate v1.x to BM + ZH, mark BM reviewed, staff viewer shows BM (safety in English until reviewed) · 21st call today politely refused · Anthropic key absent from client bundle.
M6.5 · Incident Log (Week 14) — FR-7.x
Incidents table + RLS; staff report flow (viewer link + My SOPs button, photo, severity); admin incident list + review/close with resolution note; SOP detail Incidents tab; dashboard open-incidents card. ✅ Staff reports a problem with photo from the viewer in <60s · approver closes it with a note and jumps to the SOP editor · closed incident is read-only · all transitions in audit log.
M7 · Hardening & Go-Live (Weeks 15–16)
Security checklist from 03-architecture §6 (all boxes); Supabase backups on + one restore test; seed real company data; onboard real staff via WhatsApp-shared link; fix top frictions for one week. ✅ 20+ real SOPs published · ≥80% acknowledgement · founder does ZERO manual screenshot/Sheet work for a full week.
Scope-cut order (if behind schedule)
Cut from the end of the week's scope, never extend weeks: 1) ZH translation (keep BM) · 2) CSV exports (screen only) · 3) incident photo + per-SOP tab (keep report + list) · 4) audit log UI (data still recorded) · 5) photo upload in steps (text only). NEVER cut: RLS, the state machine, acknowledgement immutability, the basic incident report+list.
Weekly rhythm (fits around warehouse + trading)
- 2 × 2-hr build sessions with Claude Code (follow CLAUDE.md session plan)
- 1 × 1-hr review: read the week's code, run the checklist, commit, deploy
- 10 min: write next session's goal at the top of CLAUDE.md scratch section