ADK Plan / Roadmap

Standalone task skill under the adk-plan category router. Produces an ordered, file-aware implementation plan that an engineer (or adk-build-feature) can execute slice by slice.

When to use

• The goal and approach are settled; only the order and scoping are open.
• The work is too large for a single sitting and must be broken into slices.
• Multiple contributors or sessions will pick up the work and need shared milestones.
• The deliverable is a plan markdown that drives subsequent build skills.

When NOT to use

• Direction or design is still open -> adk-plan-brainstorm / adk-plan-design
• The change is one file and trivial -> just do it with adk-build-feature directly
• The plan exists already and reviewers want a critique -> use adk-review-local against the plan

Inputs

Input	Required	Notes
<goal>	yes	What the plan delivers when fully executed
<scope>	optional	Path or system surface
<output path>	optional	Defaults to .temp/plans/<slug>.md
<deadline>	optional	Used to pace milestones
--auto	optional	Skip approval gate

Workflow

1. Confirm intent - restate goal, scope, deadline, and constraints. Approval gate unless --auto.
2. Map - enumerate the surface: which files, modules, services, configs, tests will change. Read code first; do not guess.
3. Slice - cut the work into vertical slices that each leave the codebase buildable, testable, and (ideally) committable.
4. Order - sequence slices by dependency; mark parallel-safe groups.
5. Gate - for each slice define the validation that proves it is done (test command, lint, type-check, manual check).
6. Risk pass - mark slices that touch risky areas, third parties, or migrations.
7. Report - return the plan path, slice count, parallel groups, and the first slice with its files.

Plan template

# Plan: <goal>

## TL;DR
<3 bullets>

## Scope
- In: <bullets>
- Out: <bullets>

## Slices
### Slice 1: <name>
- Goal: <one sentence>
- Files: `<path>`, `<path>`
- Steps:
  1. <action>
  2. <action>
- Validation: `<command>` should <expected>
- Risk: <none | low | medium | high>
- Depends on: <none | Slice X>

### Slice 2: <name>
...

## Parallel Groups
- Group A: Slice 2, Slice 4 (no shared files)
- Group B: Slice 5, Slice 6 (after Slice 3)

## Open Questions
- <question>

## Done When
- <criteria 1>
- <criteria 2>

Slicing rules

• Each slice changes < ~200 lines and < ~5 files when possible.
• Each slice has its own validation step. No "we'll test at the end".
• Each slice is committable on its own; if not, document why.
• Mark a slice "spike" only when its outcome is information, not code.
• Never put a destructive irreversible step into the same slice as exploratory work.

Output format

## Plan ready
- File: <path>
- Slices: <count>
- Parallel groups: <count>
- First slice: <name>
  - Files: <list>
  - Validation: <command>

Ready to hand off to `adk-build-feature`?

Anti-patterns

• One giant "implement everything" slice. Cut harder.
• Slices that share the same file with circular dependencies between them.
• Validation steps like "looks right" or "no obvious errors". Be concrete.
• Hiding scope creep inside slice 9. Out-of-scope work goes to a follow-up plan.
• Authoring code in the plan. The plan describes; build executes.

Examples

User says	Plan shape
"Add SSO to the admin panel"	Slices: discover identity provider, add config, wire login flow, gate routes, tests, rollout flag.
"Migrate from Express 4 to 5"	Slices: pin Express 5, fix breaking middlewares per file group, regenerate types, run integration suite, remove shims. Mark middlewares group as parallel-safe.

Clarifying questions (default-ask)

When running without --auto, the skill asks these questions in order, one at a time. Under --auto, the skill picks the safest option for each (see references/clarifying-questions.md) and reports the choices.

1. What is the source spec or design we are planning from? — How to pick: Pass a path to the spec/design markdown. If none, ask the user to run adk-plan-spec or adk-plan-design first.
2. What is the slice size you want: thin vertical slices (one user-visible behavior at a time) or layered (model → API → UI)? — How to pick: Vertical = ship value continuously, simpler review, harder coordination. Layered = easier per-team handoff, slower user value, riskier integration. Default = vertical for ≤5 engineers.
3. Are there hard deadlines or external dependencies to respect? — How to pick: List them. Steps that depend on external parties get marked with a blocker tag and a fallback path.

Default report: Ordered step list (id, summary, files, validation, dependencies, effort).

Detailed report (on request or --verbose): Add: per-step risks, rollback strategy per step, parallelization graph (which steps can run concurrently), test-coverage delta per step.

Artifact: implementation-roadmap — Markdown roadmap. Sections: Source (spec/design link), Goals, Steps (numbered table: id/summary/files/validation/dependencies/effort), Parallelization, Open Risks, Rollback Strategy.

Artifact path: .temp/plans/roadmap-<slug>.md

Clarifying questions (default-ask)

When running without --auto, the skill asks these questions in order, one at a time. Under --auto, the skill picks the safest option for each (see references/clarifying-questions.md) and reports the choices.

1. What is the source spec or design we are planning from? — How to pick: Pass a path to the spec/design markdown. If none, ask the user to run adk-plan-spec or adk-plan-design first.
2. What is the slice size you want: thin vertical slices (one user-visible behavior at a time) or layered (model → API → UI)? — How to pick: Vertical = ship value continuously, simpler review, harder coordination. Layered = easier per-team handoff, slower user value, riskier integration. Default = vertical for ≤5 engineers.
3. Are there hard deadlines or external dependencies to respect? — How to pick: List them. Steps that depend on external parties get marked with a blocker tag and a fallback path.

Default vs detailed output

Default report: Ordered step list (id, summary, files, validation, dependencies, effort).

Detailed report (on request or --verbose): Add: per-step risks, rollback strategy per step, parallelization graph (which steps can run concurrently), test-coverage delta per step.

Artifact: implementation-roadmap — Markdown roadmap. Sections: Source (spec/design link), Goals, Steps (numbered table: id/summary/files/validation/dependencies/effort), Parallelization, Open Risks, Rollback Strategy.

Artifact path: .temp/plans/roadmap-<slug>.md

<!-- adk:references:start -->

References shipped with this skill

These files live in references/ next to this SKILL.md. Read them when the skill activates; they are inlined here so the skill is fully self-contained (no cross-skill or shared sources).

File	Purpose
references/anti-patterns.md	Things to avoid when running this skill.
references/artifact-format.md	The deliverable's format and where it lives (.temp/ contract).
references/clarifying-questions.md	The default-ask questions for this skill, with how-to-pick rubrics.
references/constitution.md	Non-negotiable rules and working/communication discipline.
references/examples.md	Example trigger phrases, invocation, and report shape.
references/interaction-contract.md	Default-ask, explained-options, --auto contract every skill must follow.
references/output-format.md	Default vs detailed report shapes; severity labels; verbosity rules.
references/persona.md	The agent persona that drives this skill.
references/research-protocol.md	Source ordering, stop conditions, evidence buckets, citation discipline.
references/working-artifacts.md	Legacy: superseded by artifact-format.md; kept for back-compat.

<!-- adk:references:end -->