How do I install the Spec Planning skill?

Run npx skillmds@latest add byerlikaya/spec-planning in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Spec Planning safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Spec Planning?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Spec Planning free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Spec Planning?

byerlikaya (@byerlikaya) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Spec Planning by byerlikaya — Agent Skill

Name: Spec Planning
Author: byerlikaya

Spec Planning

Spec-first planning: task breakdown, measurable acceptance criteria, dependency order, risk priority. planner-csk applies it; the plan goes to docs/PLAN.md. Use when the scope is unclear or the work spans more than one change.

byerlikaya Updated Sep 17, 2026

File contents

Spec-First Planning

Trigger phrases: "plan", "spec", "task breakdown", "acceptance criteria", "roadmap", "how do we split this"

Before writing code: what will be done, how it counts as "done", and in what order to proceed become clear.

Steps

Purpose & scope: the problem being solved in a single sentence; also write the out-of-scope explicitly (prevent scope creep).
Split into vertical slices: the smallest end-to-end working pieces (not horizontal layers). Each slice delivers value on its own.
A contract for every task: input · output · measurable acceptance criterion (testable) · estimated risk.
Dependency graph: which task waits on what; no cycles. Bring the riskiest/most-unknown to the front (fail-fast).
Uncertainties: assumption list + open questions; do not fill ambiguous spots with a guess, ask with explicit options.

Output (docs/PLAN.md)

# <Feature> — Plan
## Acceptance criteria
- [ ] <measurable outcome>
## Tasks (order)
1. <task> — criterion: <...> — dependency: <none/#n> — risk: <low/medium/high>
## Assumptions / Open questions
- ...

Mark what you do not know — do not fill it in

Where a requirement admits more than one reading, write the marker [NEEDS CLARIFICATION: <the question>] at that exact spot in the plan. Do not resolve it with the likeliest interpretation and move on.

This is the difference between a discipline and a hope. "Stop and ask when unsure" (§1) depends on noticing the uncertainty in the moment; a marker survives into the artifact, where the user, a reviewer and a later session can all see it. A plausible assumption silently written into a spec is indistinguishable from a decision, and that is exactly how the wrong feature gets built correctly.

Rules that keep it honest:

The marker carries the question, not the label. [NEEDS CLARIFICATION: does an expired invite count as used, or can it be re-sent?] is actionable; [NEEDS CLARIFICATION: invites] is noise.
A plan may ship with markers — that is the point. It may not ship with a marker inside an acceptance criterion: a criterion nobody can evaluate is not a criterion.
Resolve by asking, never by choosing. When the user answers, replace the marker with the answer and record which reading was rejected — the alternative is what a future reader needs.
Zero markers on a genuinely ambiguous brief is a smell, not a win.

DoD (this skill's contribution)

Every task's "done" is testable; ordering and dependencies are visible; the riskiest work has been brought to the front.
Every unresolved ambiguity carries a [NEEDS CLARIFICATION: …] marker; no acceptance criterion contains one.

---name: spec-planningdescription: Spec-first planning: task breakdown, measurable acceptance criteria, dependency order, risk priority. planner-csk applies it; the plan goes to docs/PLAN.md. Use when the scope is unclear or the work spans more than one change.---# Spec-First PlanningTrigger phrases: "plan", "spec", "task breakdown", "acceptance criteria", "roadmap", "how do we split this"Before writing code: what will be done, how it counts as "done", and in what order to proceed become clear.## Steps1. **Purpose & scope:** the problem being solved in a single sentence; also write the out-of-scope explicitly (prevent scope creep).2. **Split into vertical slices:** the smallest end-to-end working pieces (not horizontal layers). Each slice delivers value on its own.3. **A contract for every task:** input · output · **measurable acceptance criterion** (testable) · estimated risk.4. **Dependency graph:** which task waits on what; no cycles. **Bring the riskiest/most-unknown to the front** (fail-fast).5. **Uncertainties:** assumption list + open questions; do not fill ambiguous spots with a guess, ask with explicit options.## Output (docs/PLAN.md)```# <Feature> — Plan## Acceptance criteria- [ ] <measurable outcome>## Tasks (order)1. <task> — criterion: <...> — dependency: <none/#n> — risk: <low/medium/high>## Assumptions / Open questions- ...```## Mark what you do not know — do not fill it inWhere a requirement admits more than one reading, write the marker **`[NEEDS CLARIFICATION: <the question>]`** atthat exact spot in the plan. Do not resolve it with the likeliest interpretation and move on.This is the difference between a discipline and a hope. "Stop and ask when unsure" (§1) depends on noticing theuncertainty in the moment; a marker survives into the artifact, where the user, a reviewer and a later sessioncan all see it. A plausible assumption silently written into a spec is indistinguishable from a decision, andthat is exactly how the wrong feature gets built correctly.Rules that keep it honest:- The marker carries the **question**, not the label. `[NEEDS CLARIFICATION: does an expired invite count as used, or can it be re-sent?]` is actionable; `[NEEDS CLARIFICATION: invites]` is noise.- A plan may ship with markers — that is the point. It may **not** ship with a marker inside an acceptance criterion: a criterion nobody can evaluate is not a criterion.- Resolve by asking, never by choosing. When the user answers, replace the marker with the answer *and* record which reading was rejected — the alternative is what a future reader needs.- Zero markers on a genuinely ambiguous brief is a smell, not a win.## DoD (this skill's contribution)- Every task's "done" is testable; ordering and dependencies are visible; the riskiest work has been brought to the front.- Every unresolved ambiguity carries a `[NEEDS CLARIFICATION: …]` marker; no acceptance criterion contains one.

Frequently asked questions