# Plan Driven Implementation

> Executes features from a living docs/plans/*.md file: per-task implement, backend test, browser test, update plan (progress, issues, diversions), commit. Use when implementing from an implementation plan, updating plan progress, authoring docs/plans/, or when the user asks to follow the plan document or keep the plan updated. After plan approval, use instead of ad-hoc implement for multi-phase initiatives.

- Skill: `axidify/plan-driven-implementation` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add axidify/plan-driven-implementation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/axidify/plan-driven-implementation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Axidify (https://skillmd.com/u/axidify)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/axidify/plan-driven-implementation

---


# 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](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](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

1. Copy [plan-template.md](plan-template.md) to `docs/plans/<name>.md`
2. Fill executive summary, initiatives, delivery phases, file index
3. Customize Backend/Browser testing tables for the domain
4. Register in the project's documentation index (if one exists)
5. 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