| name | plan-management |
| description | Update, archive, and track implementation plans and the roadmap. Use when the user asks to update a plan, check plan progress, archive a completed plan, or sync the roadmap with shipped/planned work. |
Plan Management
This skill covers the end-to-end workflow for managing implementation plans in the Piwi Dashboard project. Plans live in plans/; the roadmap (plans/roadmap.md) is the single source of truth for product direction and status.
When to Use
- User asks to "update the X plan" or "check progress on X plan"
- User asks to "archive" or "mark as shipped" a plan
- User asks to update the roadmap
- User asks to add/remove items from a plan's checklist
- After implementing features from a plan — sync its status
Workflow
1. Read the plan and assess its state
Read the plan file from plans/<name>.md. If the plan has a "File-by-file checklist" or numbered checklist sections, those are the items to check.
For each checklist item, search the codebase to determine whether it's been implemented:
Test-Path "<path>"
rg "<symbol>" --include "*.ts" --include "*.vue" application/ reporter/
Do NOT use Get-ChildItem for file existence — use Test-Path or glob/grep tools.
2. Determine plan status
A plan is fully shipped when ALL checklist items are confirmed implemented in the codebase. A plan is partially shipped when some sections are done and others remain.
3. If fully shipped — archive it
Move the plan to plans/archive/:
Move-Item -LiteralPath "plans\<name>.md" -Destination "plans\archive\<name>.md"
Then update plans/roadmap.md in TWO places:
A) "Shipped — archived plans" table (near the top): Add a new row with a brief description and the archive link.
B) "Detailed plans" table (near the bottom): Add a row or update existing row with ✅ Shipped (YYYY-MM-DD).
Format:
| Brief feature description | [`<name>.md`](archive/<name>.md) |
4. If partially shipped — update the plan in place
- Mark completed items as
[x] (or ✅) in the plan's checklist.
- Add completion dates if the plan convention uses them (e.g.,
✅ shipped 2026-07-01).
- If the unshipped remainder should be deferred/split into a new plan, note it.
- Update the roadmap's "Detailed plans" table to reflect partial status (e.g.,
🟢 Track A shipped; Track B open).
5. Roadmap conventions
The roadmap has these sections:
- "Shipped — archived plans" table: brief description + archive link for each fully-shipped plan.
- "Detailed plans" table: every plan (active, partially shipped, shipped) with status and link.
- Thematic sections (§4–§14): cross-reference shipped plans by marking them as done (e.g., "✅ shipped").
When adding a shipped plan, update ALL relevant sections:
- Shipped table → new row
- Detailed plans table →
✅ Shipped row
- Relevant thematic section → mark item as
✅
6. Capture findings
If the assessment reveals bugs, inconsistencies, or technical debt, append them to plans/exploration-findings.md:
## [Date] — Plan audit: <plan-name>
### Finding: <title>
- **File/Component**: <location>
- **Issue**: <description>
- **Impact**: Low / Medium / High
- **Suggested fix**: <recommendation>
7. No commit needed
Plans are gitignored (plans/ is in .gitignore) — they're local working documents. Do not commit plan changes or the archive move.
Plan Structure Conventions
Plans in this project follow this structure:
- Goal at the top (one-line summary)
- Current state (findings/audit of what exists)
- Decisions (D1, D2, … table of architectural choices)
- Workstreams (numbered, each with sub-items like A1, A2, B1, B2, …)
- File-by-file checklist at the end (checkboxes grouped by workstream)
- Verification steps (numbered task list for manual QA)
- Risks & notes
Key Code Locations to Check
| Area | Where to look |
|---|
| DB schema | application/server/database/schema.sqlite.ts, schema.pg.ts |
| API endpoints | application/server/api/ |
| Shared types | application/shared/types.ts |
| Shared handlers | application/shared/handlers/ |
| Frontend types | application/types/api.ts |
| Frontend pages | application/app/pages/ |
| Frontend components | application/app/components/ (organized by domain subfolder) |
| Frontend composables | application/app/composables/ |
| Settings metadata | application/app/utils/settings-metadata.ts |
| Help content | application/app/utils/help-content.ts |
| Layout (sidebar, footer) | application/app/layouts/default.vue |
| Env var registry | application/shared/piwi-env-vars.ts |
| Reporter source | reporter/src/ |
| Reporter tests | reporter/tests/ |
| Demo API mirror | application/app/demo/api/ |
| Demo simulator | application/app/demo/simulator.ts |
| Demo seed script | application/scripts/generate-demo-seed.mjs |
| Unit tests | application/tests/unit/ |
| E2E tests | application/tests/ |
| CI workflows | .github/workflows/ |
| Docs | docs/ |
| MCP tools | application/server/utils/mcp/tools.ts |
| MCP tool defs | application/shared/mcp-tools.ts |
