adol1111/doc-driven-spec-workflow58 installs
milestone-planning
Decomposes confirmed docs-driven direction into milestones, optional modules, and roadmap-level tasks. Use when roadmap boundaries, delivery order, or task breakdown are unclear.
How do I install this agent skill?
npx skills add https://github.com/adol1111/doc-driven-spec-workflow --skill milestone-planningIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides a structured framework for milestone and roadmap planning. It defines governance rules for task decomposition and document management without introducing security risks.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Milestone Planning
Purpose
Turn a clear direction into roadmap structure. This skill owns docs governance, not task-local design.
Use when
- planning direction is clear enough to decompose
- milestone boundaries, module grouping, or task breakdown still need decisions
- the user needs roadmap-level tasks before task-local
spec.mdwork can begin
Do not use when
- goals, constraints, or now-vs-later boundaries are still genuinely unclear
- the current task is already selected from confirmed roadmap state
- the work now is task-local spec, plan, implementation, or branch closing
Read first
docs/tasks/index.mddocs/tasks/planning-inbox.mddocs/tasks/backlog.md- relevant milestone, module, and task docs under
docs/tasks/ - the current user prompt
Owns
- milestone boundaries
- optional module boundaries
- roadmap-level task decomposition
Roadmap confirmedstate and its consequencesplanning-inbox,backlog, andHandoff Notesgovernance- planning review pause and planning handoff context
Must not own
- task-local
spec.md - task-local
plan.md - execution isolation or implementation
- readiness checks, verification flow, or branch closing
- implementation-level sequencing disguised as roadmap structure
Entry checks
- If planning direction is still unresolved, route back to
planning-clarification. - If
Open Milestonesis empty, checkplanning-inbox.md,backlog.md, and prompt evidence before decomposing. - If no evidence identifies either a concrete short-term target or roadmap misalignment, ask the planning mode question.
- If the user asks to start work inside
Roadmap confirmed: no, keep decomposition provisional until milestone structure is explicitly confirmed. - If the user is moving into a later milestone, resolve previous milestone closure first.
- When confirming a milestone or changing
Roadmap confirmed: notoyes, inspectbacklog.mdfor deferred tasks that fit the milestone goal.
Default flow
- Confirm whether the current problem is roadmap structure rather than planning ambiguity.
- Choose milestone boundaries from delivery goals, phase boundaries, or exit criteria, not feature count.
- Add modules only when there are multiple durable capability areas with distinct ownership, risk, dependency, release, or acceptance boundaries.
- Split roadmap tasks by coherent capability outcome. Each task should be independently reviewable, independently handoffable, and independently completable.
- When a milestone is confirmed, promote matching
backlog.mdtasks into the milestone or explicitly leave them deferred. - Record rationale for milestone, module, and task boundaries in roadmap docs.
- Stop at a planning review pause after creating or reshaping roadmap docs.
Boundary rules
- Milestone boundaries are about release or phase meaning, not about keeping milestone size visually balanced.
- Do not keep one giant milestone open just because the original request was broad. Split when there are real phase, exit, or release boundaries.
- Modules are optional. Do not create a single catch-all module for one capability area.
- Do not use tiny one-off modules as buckets for isolated tasks.
- Task boundaries must stay above implementation design. A roadmap task says what capability lands, not how code changes are sequenced.
- Do not hide multiple selectable capabilities inside vague task names such as
core,foundation,mvp, orpolish. - Do not name roadmap tasks after files, endpoints, tests, migrations, or refactor slices.
- Do not split implementation, tests, docs, verification, or review follow-up into separate roadmap tasks unless that governance work is itself the user-visible delivery outcome.
- Task order belongs in the relevant ordered list, not in numeric directory prefixes.
- Newly discovered future work during an active milestone should go to that milestone's
Handoff Notesfirst by default, not into task-localplan.md. planning-inbox.mdstores goals and candidate milestone direction, not concrete tasks.backlog.mdstores concrete deferred tasks, not broad goals.
Goal definition
- A goal is a desired future state, product outcome, opportunity, or phase direction. It explains what should become true and why it matters, before deciding the roadmap shape.
- A goal should usually be broader than one implementation task, but it does not need to be huge. It may later become one milestone, several milestones, or be discarded after clarification.
- A goal is not a code change, endpoint, migration, test suite, refactor slice, or already selectable implementation outcome.
- Treat an item as task-shaped when it can already be given a concrete
task.mdwith outcome, rough scope, acceptance checklist, and success signals without first deciding phase direction. - If promoting a planning inbox item would naturally create a milestone and a single same-named task with no additional boundary decision, reclassify the item as a backlog task or current milestone task unless the item is itself a real release, migration, or phase boundary.
- Name goals by the outcome or phase, not by the likely implementation mechanism.
Examples:
- Good planning-inbox goal:
API contract stabilitywith goal text such as "make backend responses predictable enough that frontend and external clients can handle success, validation failure, and business failure consistently." - Task-shaped, not a goal:
Unify API business error model and response envelope. This already names the concrete implementation outcome and can likely become onetask.md. - Better classification for that task-shaped item: put
Unify API business error model and response envelopeinbacklog.mdor the current milestone, and optionally fit it under a goal such asAPI contract stability. - Good milestone from that goal:
API Contract Stabilization, with exit criteria around documented response semantics, client-safe compatibility, and contract tests. - Good tasks under that milestone:
Define response envelope and business error semantics,Adapt callers to the unified response contract, andAdd API contract coverage and migration notes. - Bad promotion shape: planning inbox goal
Unify API business error model and response envelope-> milestoneUnify API business error model and response envelope-> one taskUnify API business error model and response envelope. This duplicates labels across layers instead of making a roadmap decision.
Handoff Notes routing
- Record
Handoff Notesin the current milestoneindex.md, not in task-localplan.md. - Keep an item in the current milestone only when it must be completed to satisfy the current milestone's exit criteria.
- Move an item to a later milestone when it is clearly milestone-shaped future work, but not required to close the current milestone.
- Move an item to
docs/tasks/backlog.mdwhen it is a concrete task-shaped follow-up that is not assigned to a milestone. - Move an item to
docs/tasks/planning-inbox.mdwhen it is a goal, phase, opportunity, or direction that is not yet ready to become a milestone. - Remove an item only when it is explicitly discarded or no longer worth tracking.
- If the user explicitly decides the item is high priority enough to interrupt the current path, replan it instead of leaving it as handoff-only follow-up.
Task status lifecycle
- New roadmap tasks start as
planned. - Keep a task at
plannedwhile it is only decomposed, ordered, or selected as a future candidate. - Move a task to
in_progressonly when active task-local preparation or implementation work actually begins. - Use
blockedonly when the selected task cannot currently move forward because of an external dependency, unresolved decision, failed prerequisite, or explicit stop condition. - Do not mark a task
completedfrom roadmap planning alone; completion belongs to execution after implementation, verification, required docs/status updates, and closing outcome are resolved. - Keep task
Statussingle-choice at all times.
Planning inbox
planning-inbox.mdis the goal layer. It stores future product goals, opportunities, candidate phases, and long-range roadmap direction.- Planning inbox goals should describe the future state or phase to plan, not the exact task that will implement it.
- Do not store concrete task-shaped work in
planning-inbox.md; move that work tobacklog.mdunless it belongs in an open milestone. - Pull an item out of
planning-inbox.mdwhen the goal is ready to become an open milestone or needs planning clarification. - When a planning inbox goal becomes a milestone, check
backlog.mdfor deferred tasks that match that goal.
Backlog
backlog.mdis the task layer. It stores concrete deferred tasks that are worth keeping but are not assigned to an open milestone.- A backlog item should be task-shaped: it has an outcome, rough scope, source, and a plausible goal or milestone fit.
- Pull an item out of
backlog.mdwhen milestone planning, milestone confirmation, orRoadmap confirmed: notoyespromotes it into active milestone consideration. - Remove a backlog item after it is promoted into a milestone task, explicitly discarded, or superseded by a different task.
If blocked
- Ask the planning mode question when no evidence identifies a concrete short-term target or misalignment:
Do you already have a concrete short-term target for this iteration, or do we need to realign the next stage of the roadmap first?
- Route back to
planning-clarificationwhen roadmap structure still depends on unresolved goal or boundary ambiguity. - Stop and ask directly when an unresolved item blocks milestone confirmation, milestone closure, or cross-milestone movement.
Review and follow-up
- Stop at a planning review pause after roadmap docs change.
- Treat clear forward-motion language after that review pause as permission for routine follow-up.
- Default routine follow-up after review is:
- commit reviewed planning docs
- unless the user explicitly asks to leave them uncommitted
- then report handoff context and move toward the next applicable stage
- Do not treat planning review approval as permission to skip unresolved hard gates.
Hard gates
- Do not move into a later milestone while an earlier milestone still appears open and unresolved.
- Do not treat
continueas milestone confirmation when the roadmap structure is still explicitly unconfirmed. - Do not close a milestone while any
Handoff Notesitem remains unresolved. - Do not add follow-up work to a completed milestone. Create a new open milestone, backlog task, or planning inbox goal instead.
Output
- recommended milestone structure
- why it is one milestone or several
- whether modules are needed
- task list per milestone or module
- delivery order when not obvious
- assumptions or open questions
Stop point
- planning review pause
- or a direct blocking question about roadmap ambiguity, confirmation, or closure
Handoff
DecidedUndecidedNext skillStop point
References
- Use
references/roadmap-template.mdfor roadmap document shape.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/adol1111/doc-driven-spec-workflow/milestone-planning">View milestone-planning on skillZs</a>