Axidify Plan-driven implementation
Source of truth: The plan markdown in docs/plans/ drives task order, acceptance criteria, and test gates. Update it on every commit, test finding, fix, or scope change — not only at phase end.
New plan skeleton: plan-template.md
When to use
| Scenario | Action |
|---|---|
| User says "implement from the plan" / "next task" | Read plan → pick next 📋 task from delivery phases → follow workflow below |
| Starting a new initiative | Copy plan-template.md → docs/plans/<name>.md → register in project doc index |
| Backend or browser test found a bug | Add row to plan Issues & fixes log immediately |
| Approach differs from plan | Add row to Plan diversions before or with the commit |
| Task complete | Update Task status tracker, Progress log, acceptance checkboxes |
Use plan for design before the living doc exists; switch here after the plan is approved and saved under docs/plans/.
Per-task workflow
Do not mark a task done until backend and browser gates pass (or defer explicitly in Issues log).
1. READ PLAN — next task, acceptance criteria, File index touch points
2. IMPLEMENT — feature branch named in plan (if any)
3. BACKEND TEST — unit/integration commands from plan or discover-project
4. BROWSER TEST — Playwright E2E and/or manual QA (see ui-browser-check)
5. DOCUMENT — update plan BEFORE or WITH commit (tracker, logs, checkboxes)
6. COMMIT — one logical task per commit; message includes task id (e.g. A.2)
7. NEXT TASK — only after plan reflects current state
Rule: If it is not in the plan document, it did not happen for the purposes of the initiative.
What to update in the plan (always)
| Event | Update |
|---|---|
| Starting a task | Progress log "started"; Task status → 🔄 In progress |
| Backend/browser failure | Issues & fixes log (even before fix) |
| Fix landed | Issues log + commit hash; acceptance checkbox |
| Deviation from plan | Plan diversions table |
| Task complete | Task status ✅; Progress log with Backend/Browser columns |
| New scope | Symptom matrix or Open questions — no silent expansion |
| Deferred work | Issues log "Deferred → task X" |
Testing
Run discover-project if test commands are not already in the plan.
| Layer | How | Pass criteria |
|---|---|---|
| Backend | Commands in plan's Backend testing table, or package.json / CI scripts |
Targeted specs green; build passes on touched packages |
| Browser | Plan's Browser testing table: Playwright E2E, Playwright MCP, manual QA | No console errors; UI matches API after settle |
Plan-specific commands belong in the plan — not duplicated here.
Commit discipline
- Message format:
type(scope): A.N short description(use plan's task ids) - After commit: Progress log row with hash + test summary
- Do not merge to default branch with stale Task status tracker or acceptance boxes
Authoring a new plan
- Copy plan-template.md to
docs/plans/<name>.md - Fill executive summary, initiatives, delivery phases, file index
- Customize Backend/Browser testing tables for the domain
- Register in the project's documentation index (if one exists)
- Link related plans at top — cross-reference, don't duplicate
Keep methodology sections from the template unless the initiative genuinely needs fewer gates (document why in Plan diversions).
Related skills
- plan — design and scope before creating the living plan doc
- discover-project — stack and test commands before authoring plan test tables
- implement — single scoped changes outside a formal plan doc
- test — run backend suites referenced in the plan
- ui-browser-check — Playwright MCP when UI behavior is unclear
- issue-tracking — product issues (GitHub, issue-log); plan Issues & fixes log for initiative findings
- review — pre-commit / pre-PR pass; log blockers in Issues log
- pr — open PR; keep Progress log in sync with review fixes
- ci — fix red checks; document in Progress log if they block a task