plan-create
/plan-create
Create `.context/plans/*.md` files with standard YAML frontmatter, phases/tasks/waves decomposition, and post-creation validation. Infers section conventions from existing plans in `.context/plans/` to match the local style. Integrates with plan-review for a create → review → iterate loop. Triggers: 'create a plan', 'new plan', 'draft a plan', 'plan scaffold', 'write a plan'. Do NOT use for plans outside `.context/plans/`, ephemeral notes, or the main project SKILL.md.
- Author
- pantheon-org ↗
- Repository
- tekhne ↗
- Licence
- MIT
- Last repository change
- 21.10.2026
Assessment and security
- Files in this package
- 23
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 21.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/validate-plan-scaffold.sh
What it does and when to use it
Create `.context/plans/*.md` files with standard YAML frontmatter, phases/tasks/waves decomposition, and post-creation validation. Infers section conventions from existing plans in `.context/plans/` to match the local style. Integrates with plan-review for a create → review → iterate loop. Triggers: 'create a plan', 'new plan', 'draft a plan', 'plan scaffold', 'write a plan'. Do NOT use for plans outside `.context/plans/`, ephemeral notes, or the main project SKILL.md.
Triggers from the description
Original author description
Create `.context/plans/*.md` files with standard YAML frontmatter, phases/tasks/waves decomposition, and post-creation validation. Infers section conventions from existing plans in `.context/plans/` to match the local style. Integrates with plan-review for a create → review → iterate loop. Triggers: 'create a plan', 'new plan', 'draft a plan', 'plan scaffold', 'write a plan'. Do NOT use for plans outside `.context/plans/`, ephemeral notes, or the main project SKILL.md.
How it works
- Prerequisites
- When to Use
- When NOT to Use
- Workflow
- Verification
- Mindset
- Anti-Patterns
- References
SKILL.md preview
---
name: plan-create
description: >
Create `.context/plans/*.md` files with standard YAML frontmatter,
phases/tasks/waves decomposition, and post-creation validation.
Infers section conventions from existing plans in `.context/plans/`
to match the local style. Integrates with plan-review for a
create → review → iterate loop. Triggers: 'create a plan',
'new plan', 'draft a plan', 'plan scaffold', 'write a plan'.
Do NOT use for plans outside `.context/plans/`, ephemeral notes,
or the main project SKILL.md.
---
# Plan Create -- Structured Plan Scaffolding
Create `.context/plans/` files that pass structural validation and match
local conventions. The workflow ensures every plan has valid frontmatter,
clear phases and tasks, and can be immediately reviewed by the
`plan-review` skill.
## Prerequisites
- A clear idea of the work to be planned (goal, scope, implementation steps)
- The `context-file` skill available if frontmatter repair is needed
- The `plan-review` skill available for post-creation validation (optional)
- Shell access to run validation scripts
## When to Use
- Drafting a new implementation plan with multiple phases
- Scoping work that needs review before implementation begins
- Creating a plan that will later be audited by `plan-review`
## When NOT to Use
- For the main project SKILL.md or agent skills -- use the skill template instead
- For one-off notes or scratch files -- use inline notes
- When the work is trivially small (1 step, no phases) -- just write a finding
## Workflow
### 1. Gather the plan specification
Ask the user about the plan. Collect at minimum:
- **Goal** -- what does success look like? What problem is being solved?
- **Scope** -- what's in and what's out? Are there known constraints?
- **Phases** -- what are the sequential stages? Each phase should:
- Have a clear deliverable or exit criterion
- Be independently shippable (could stop after this phase)
- Be 2–5 tasks, not 20+
- **Tasks per phase** -- for each phase, list concrete work units:
- Each task should be completable in a single session (hours, not weeks)
- Use actionable language ("Add --format flag", not "Improve output")
- Flag which tasks can run in parallel (waves)
- **Dependencies** -- does this plan depend on other plans, PRs, or external work?
- **Risks** -- what could go wrong? What's the biggest unknown?
- **Timeline** -- optional, if the user has a deadline or priority
- **Effort** -- a T-shirt-sized estimate. **Value** -- a benefit-of-action grade.
**Themes** -- an ordered subject-area tag list. All three are required
frontmatter fields; see
[Grading Effort, Value, and Themes](references/grading-effort-value-themes.md)
for the full rubric, allowed values, and worked examples. TYPICALLY these
three fields are the ones a first-time plan author gets wrong -- read the
reference before guessing.
### 2. Infer local conventions
Scan existing plans to understand what sections this repo uses:
```bash
grep -r '^## ' .context/plans/*.md | sed 's/.*## //' | sort | uniq -c | sort -rn
```
From the frequency table, identify:
- **Core sections** (present in >= 40% of plans): always include
- **Common sections** (present in 20-39%): include unless the plan is small
- **Rare sections** (< 20%): include only if relevant
Also check the naming convention: timestamped (`topic-YYYY-MM-DD.md`) or
topic-only (`short-description.md`). Follow whatever the majority of plans use.
### 3. Draft the plan
Construct the plan file following the structure in
[assets/templates/plan-scaffold.yaml](assets/templates/plan-scaffold.yaml).
The template is validated against
[assets/schemas/plan-scaffold.schema.json](assets/schemas/plan-scaffold.schema.json).
The plan always includes:
- YAML frontmatter with `title`, `type: PLAN`, `status: DRAFT`, `date` (today),
`effort` (`S`/`M`/`L`/`TBD`), `value` (`HIGH`/`MEDIUM`/`LOW`), `themes` (ordered
list from the theme vocabulary, primary-first)
- `## Goal` section -- one paragraph describing the desired end state
- `## Phases` section -- numbered phases with tasks and wave annotations
- `## Open Questions` section -- unresolved items for the reviewer
Additional sections based on what the user provided and what the local
conventions suggest (from step 2): `## Scope`, `## Risks`, `## Verification`.
### 4. Validate the plan
Run the frontmatter validation script (see the `context-index` skill's
`scripts/validate-context-frontmatter.sh`):
```bash
validate-context-frontmatter.sh .context/plans/<plan-file>.md
```
If validation fails, fix the frontmatter and re-run. Do not proceed until
validation passes -- a plan with invalid frontmatter is invisible to the index.
### 5. Review the plan (optional)
Offer to run the `plan-review` skill on the newly created plan:
> "I created the plan at `.context/plans/<file>`. Would you like me to run
> the `plan-review` skill on it now to catch any issues?"
If the user accepts, load the `plan-review` skill and follow its workflow.
This completes the create → review → iterate loop.
### 6. Confirm and conclude
Confirm the file was created with its path and a summary:
```
Created: .context/plans/<file>.md
Title: <title>
Status: draft
Phases: <N> phases, <M> tasks total
Next: Run plan-review on it, or mark status: READY once reviewed and approved
(status becomes ACTIVE on its own once a worktree/branch for it exists)
```
## Verification
After creating the plan, run these checks:
1. **Frontmatter validation** -- run `validate-context-frontmatter.sh` on the
file. If it fails, fix the frontmatter before presenting the result.
```bash
validate-context-frontmatter.sh <file>
```
2. **Structure check** -- verify the plan has at minimum `## Goal` and
`## Phases` sections. If the local convention requires others (from step 2),
add those too.
3. **Phase completeness** -- verify each phase has 2-5 concrete tasks and
an exit criterion. Phases with more than 8 tasks should be split.
4. **Wave annotation** -- verify tasks that can run in parallel are marked
(e.g., "Wave A: frontend, Wave B: backend -- can run concurrently").
5. **Effort declared** -- frontmatter has `effort` set to `S`/`M`/`L`/`TBD`.
If `TBD`, confirm the corresponding Open Question actually explains what's
blocking the estimate.
6. **Value graded** -- frontmatter has `value` set to `HIGH`/`MEDIUM`/`LOW`,
graded against the value rubric (see
[Grading Effort, Value, and Themes](references/grading-effort-value-themes.md))
rather than guessed.
7. **Themes tagged** -- frontmatter has a non-empty `themes` list, ordered
primary-first, with every member drawn from the controlled theme vocabulary
(same reference) -- no invented themes.
## Mindset
- A plan is a communication tool first, a todo list second. Write for the next
person who reads this cold.
- Phases are about sequencing, not grouping. Phase 1 must finish before Phase 2
starts. If two groups don't depend on each other, they're waves within a phase,
not separate phases. PREFER an explicit wave label over leaving parallelism
implicit.
- Tasks should be single-session-sized. TYPICALLY a phase holds 2-5 tasks. If a
task takes "a few days", it's too large -- break it down. If it takes
"5 minutes", it's too small -- combine it.
- BY DEFAULT a new plan is `status: DRAFT`. Promote to `READY` only after the
plan is reviewed and approved -- AVOID skipping straight to `READY` UNLESS the
work is genuinely trivial enough to skip review entirely (see When NOT to Use).
`ACTIVE` is not a manual promotion at all -- it's entered automatically once a
worktree/branch referencing the plan exists (see `planning-flow.md`).
- The YAML frontmatter is not optional. A plan without frontmatter is invisible
to `.context/index.yaml` and to every agent that reads it.
- Sizing `effort` and grading `value` is RECOMMENDED to happen against the
rubric in [Grading Effort, Value, and Themes](references/grading-effort-value-themes.md),
not from gut feel -- a guessed grade misleads the reader more than a stated
`TBD` with an Open Question.
## Anti-Patterns
**NEVER** -- Create a plan without YAML frontmatter
**SYMPTOM:** The file renders fine in markdown but never appears in the context
index. Future agents never discover the plan.
**CONSEQUENCE:** Effort goes into a plan no one reads. The plan is orphaned
until someone manually finds it and adds frontmatter.
**WHY:** The context index and pre-commit hooks both require frontmatter. A plan
without it is invisible machinery.
**BAD:** Starting the file with `# Plan: My Title` directly.
**GOOD:** Always open with `---\ntitle: "Plan: My Title"\ntype: PLAN\nstatus: DRAFT\ndate: YYYY-MM-DD\n---`.
**NEVER** -- Skip the convention inference step
**SYMPTOM:** The created plan uses a structure that doesn't match any other plan
in the repo -- no `## Open Questions`, no `## Scope`. It feels out of place.
**CONSEQUENCE:** Agents that parse plans expecting `## Steps` instead of
`## Phases` may skip sections. The plan is technically valid but practically
misaligned.
**WHY:** The local convention reflects what agents in this repo expect. A plan
that doesn't follow it is harder to review, harder to index, and harder to
discover.
**BAD:** Hardcoding "Goal → Steps → Open Questions" without scanning first.
**GOOD:** Running `grep -r '^## ' .context/plans/*.md` and using the actual
frequencies.
**NEVER** -- Create a phase with more than 8 tasks
**SYMPTOM:** "Phase 1: Everything" with 15 tasks and no sub-structure.
The phase cannot be shipped independently -- it's the whole plan.
**CONSEQUENCE:** No meaningful checkpoint exists. If the plan runs out of time,
there's no partial delivery. The cost of splitting later is higher than splitting
now.
**WHY:** A phase should be small enough to review, implement, and ship in a
sprint (1-2 weeks). 8+ tasks means the phase is underspecified.
**BAD:** A flat list of 15 tasks with no phase grouping.
**GOOD:** 3 phases, each with 3-5 tasks and an exit criterion.
**NEVER** -- Omit or guess the `effort` field
**SYMPTOM:** The plan has no `effort` in frontmatter, or has one picked
arbitrarily to satisfy validation rather than reflecting an actual estimate.
**CONSEQUENCE:** A reader scanning `.context/index.yaml` for quick wins vs.
big lifts can't distinguish them without opening every plan file. A fake
number is worse than a missing one -- it looks authoritative but isn't.
**WHY:** `effort` exists so plans are triageable at a glance, the same way
`status` lets a reader triage by lifecycle stage. `validate-context-frontmatter.sh`
requires it for any `type: PLAN` with `status: DRAFT`, `READY`, or `ACTIVE`.
**BAD:** Setting `effort: S` on a plan nobody has actually sized, just to pass
validation.
**GOOD:** `effort: TBD` with an Open Question stating exactly what decision
blocks sizing (see `migrate-off-tessl-eval-2026-06-29.md` for a real example).
## References
| Topic | Reference | When to Use |
| --- | --- | --- |
| Common plan sections, their purpose, and file-naming conventions | [Plan Structure Reference](references/plan-structure.md) | Step 2, inferring which sections to include and how to name the file |
| Effort/value/themes rubric, allowed values, worked example | [Grading Effort, Value, and Themes](references/grading-effort-value-themes.md) | Step 1, whenever effort, value, or themes need grading rather than guessing |
| Repairing frontmatter on an existing file | `context-file` skill | When a plan's frontmatter is invalid and needs fixing, not creating from scratch |
| Post-creation multi-perspective audit | `plan-review` skill | Step 5, after a plan is drafted and ready for review |
| Regenerating the index after creation | `context-index` skill | After a plan is created or its frontmatter changes, to keep `.context/index.yaml` in sync |
Files in this package (23)
- SKILL.md 12 KB
- .audits/2026-10-02/Analysis.md 1 KB
- .audits/2026-10-02/Remediation.md 1 KB
- .audits/2026-10-02/audit.json 1 KB
- assets/schemas/plan-scaffold.schema.json 4 KB
- assets/templates/plan-scaffold.yaml 2 KB
- evals/instructions.json 3 KB
- evals/summary.json 1 KB
- evals/scenario-01/capability.txt 1 KB
- evals/scenario-01/criteria.json 2 KB
- evals/scenario-01/task.md 2 KB
- evals/scenario-02/capability.txt 1 KB
- evals/scenario-02/criteria.json 2 KB
- evals/scenario-02/task.md 2 KB
- evals/scenario-03/capability.txt 1 KB
- evals/scenario-03/criteria.json 2 KB
- evals/scenario-03/task.md 2 KB
- evals/scenario-04/capability.txt 1 KB
- evals/scenario-04/criteria.json 2 KB
- evals/scenario-04/task.md 2 KB
- references/grading-effort-value-themes.md 3 KB
- references/plan-structure.md 2 KB
- scripts/validate-plan-scaffold.sh 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · pantheon-org/tekhne | 100 | MIT |
| markshust/hcf | 100 | MIT |
| allemaar/open-skills | 100 | Apache-2.0 |
| serbanghita/plan-critique-skills | 92 | MIT |
Database snapshot: 13.11.2026 · package version 9aba5129dab7 (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
- 100plans
Read and write numbered plan files in repos that use a plans/ directory with an index. Use when asked to find, list, read, or search plans; when creating a plan or changing one's status; and in place of superpowers writing-plans where the repo declares `superpowers: override`.… - 90writing-plans
Plan, implement, or review writing plans work in an existing codebase with compatibility, security, and verification controls. Use when the user explicitly requests writing plans work. - 100plan-editing-conventions
Conventions for editing plan.json implementation plans including task format, structured arrays, and plan structure rules. Use when creating or modifying plan.json files. - 100iterate-plan
Update existing implementation plans through user feedback with thorough research and validation. Also migrates old checkbox-based plans to the new Task tools system. This skill should be used when iterating on implementation plans, updating plans based on new requirements,… - 96planner
Use when the user asks to create, write, or review a docs/plans plan. - 82plan-objective
Create a detailed execution plan for an objective, breaking it into concrete tasks with success criteria. Use when the user wants to plan an objective, create execution plans, or prepare for building. Triggers on: "plan objective", "create plans", "plan the next objective",…