Skip to content
Skills Library
Programming · Planning

plan

/plan

Use when a spec is approved and implementation has not started: turns it into a task-by-task plan with exact paths and checkable verification. No code here.

Repository
vibekit ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when a spec is approved and implementation has not started: turns it into a task-by-task plan with exact paths and checkable verification. No code here.

Original author description

Use when a spec is approved and implementation has not started: turns it into a task-by-task plan with exact paths and checkable verification. No code here.

How it works

  1. HARD-GATE
  2. The spec is settled
  3. Refusals
  4. Plan document
  5. Task shape
  6. You may not write a value you have not observed
  7. No placeholders
  8. Self-review
  9. User review gate
  10. Handoff
Original SKILL.md headings · 105 lines, 974 words
SKILL.md preview
---
name: plan
description: "Use when a spec is approved and implementation has not started: turns it into a task-by-task plan with exact paths and checkable verification. No code here."
trigger: Spec approved, implementation not yet started
gate: hard
---

# plan

Turn an approved spec into an implementation plan. No code is written here.

## HARD-GATE

Do NOT implement anything until a plan file exists and the user has approved it.

The gate has one precondition, and it is checkable rather than asserted: a spec file exists carrying `status: approved` in its frontmatter. If there is none, stop and invoke `brainstorm`. A plan built on a draft is a plan built on something the user may still change.

## The spec is settled

Read it, do not re-litigate it. Questions it already answered are not asked again. A defect found in it goes back to the user as a question: never a silent edit, because the approved artefact is what the user signed.

## Refusals

- **Spec spans independent subsystems.** Say so before writing any task. One plan per subsystem, each producing working software on its own.
- **A requirement has no possible verify clause.** Not a licence to write a weak one. Either the task boundary is wrong and splits, or the requirement is unobservable and goes back to the user as a question.

## Plan document

Write to `docs/plans/YYYY-MM-DD-<topic>.md`, then commit: that file alone.

```
# <topic>: Implementation Plan

**Spec:** docs/specs/<file>.md
**Goal:** one sentence
**Architecture:** two or three sentences

## Global constraints
- <one line each, values copied verbatim from the spec>
```

Global constraints are the spec's project-wide requirements: version floors, dependency limits, naming rules. Stated once, they are implicitly part of every task, so no task restates them and no task author has to remember them.

## Task shape

```
### Task N: <name> → verify: <predicate>

**Files:**
- Create: `exact/path`
- Modify: `exact/path:12-40`

- [ ] Step 1: <one action>
- [ ] Step 2: Run `<command>`
- [ ] Step N: Commit

```

A task is the smallest unit worth a fresh reviewer's gate. Fold setup, config and documentation into the task whose deliverable needs them. Split only where a reviewer could reject one task while approving its neighbour. Each task ends with an independently testable deliverable and one commit.

Steps that change code carry the actual code. A step that runs a command names the command and stops there.

## You may not write a value you have not observed

Every value this plan states, a number, a path, a count, a cross-reference, must be one you observed. You read it, you ran it, or you chose it as a threshold. A value you recalled is a guess, and a guess in a plan is a defect a fresh implementer pays for: they follow the plan exactly, hit a contradiction, and stop.

Two ways to satisfy it. Derive the value before writing it, usually one command and a few seconds. Or state the property instead of the value: "every new case passes" rather than "three cases pass".

**A clause is the strictest case.** A `→ verify:` clause states a predicate: something checkable by a reader of the plan, before anything runs. Not a transcript.

**Predicates:** exit status, pass or fail, a file exists, a match count at or above a threshold, an HTTP status.

**Not predicates:** a quoted message, a specific count, a diff, a sample of output. Each is a claim about a future you have not seen. When one is wrong, the executing agent cannot tell whether the code failed or the plan lied, and it will assume the code.

A number is not itself the tell. Three forms carry one legitimately: an exit status, an HTTP status, and a threshold in either direction (at least 1 match, under 120 lines). Any other number in a clause is a predicted value. A threshold is derivable because you chose it. A predicted value is not, because the runtime chooses it.

Spelling a number out does not launder it. "The four cases pass" is a count, and the first plan written under this rule got that count wrong.

Naming your command in a code span is not quoting. Backticks delimit what to run. Straight quotes are how a predicted transcript gets in.

If a specific value is genuinely load-bearing, the task's first step **observes it**, and the clause refers to the observation instead of a guess.

A clause must be satisfiable by the task it belongs to. If you cannot say what would make it true, the task boundary is wrong, not the clause.

**Outside a clause the rule still holds, and there is no allowlist.** A line count in a task title, a path in a Files block, a version in Global constraints, a reference to another task by number: each is a value, so each was read, run, or chosen. None may be recalled.

## No placeholders

`TBD`, `TODO`, "add error handling", "similar to Task N", and any reference to a function no task defines are plan failures, not shorthand. Repeat the code: tasks get read out of order.

## Self-review

1. **Spec coverage.** Every requirement maps to a task. Add any that is missing.
2. **Placeholders.** Scan for the patterns above. Fix them.
3. **Clauses.** Scan every `→ verify:` for a quoted string, or a number outside the three permitted forms. Both are predicted output. Fix them.
4. **Provenance.** For every number, path, count and cross-reference in the plan, name where it came from. "I ran it" and "I read it" pass. "I knew it" is a guess: derive it, or state a property instead.

Fix inline. No re-review.

## User review gate

Send exactly this, verbatim:

> Plan written and committed to `<path>`. Please review it and let me know if you want to make any changes before we start implementing.

Wait. On requested changes, make them and re-run self-review.

## Handoff

The only next skill is `exec`, once the user has approved the plan. Never invoke an implementation skill from here.

Versions

RepositoryScoreLicence
This page · rizukirr/vibekit100MIT
mlophez/polix-ai100Apache-2.0
jeremylongshore/tons-of-skills-marketplace100MIT
duronext/jig100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
rjmurillo/ai-agents100MIT
xoai/sage100MIT
JoDi-27/JoDi-SDD100MIT

Database snapshot: 13.11.2026 · package version 518dd1afac0c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100writing-plans
    Use when you have a spec or requirements for a multi-step task, before touching code. Triggers on: "create a plan", "write implementation steps", "break down the task", any planning request. Creates comprehensive implementation plans with bite-sized tasks and exact file paths.
  • 100plan-work
    Turn an approved spec or brief into a plan grounded in the real code, with the design, state machines, and verifiable slices, slice 1 in the real environment. Writes no code. Use when asked to plan the work in a spec or brief, plan a feature, or prepare an implementation plan.
  • 100write-plan
    Use when you have a finalized brainstorm-beagle spec at `.beagle/concepts/<slug>/spec.md` and need a bite-sized, TDD-driven implementation plan before any code is written. Triggers on: \"write a plan\", \"plan this spec\", \"turn the spec into a plan\", \"now plan the…
  • 84writing-plans
    Use when you have a spec or requirements for a multi-step task. Creates comprehensive implementation plans with bite-sized tasks, exact file paths, and complete code examples.
  • 100writing-plans
    Use when you have a spec or requirements for a multi-step task. Creates comprehensive implementation plans with bite-sized tasks, exact file paths, and complete code examples.
  • 100blueprinting
    Break a chosen approach into a detailed implementation blueprint with bite-sized tasks, exact paths, and verification steps. Use when approach is chosen and you need a plan before coding

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.