# 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.

- Skill: `pantheon-org/plan-create-2` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add pantheon-org/plan-create-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pantheon-org/plan-create-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: pantheon-org (https://skillmd.com/u/pantheon-org)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/pantheon-org/plan-create-2

---


# 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 total estimate (`S`/`M`/`L`), matching the
  skill-auditor remediation-plan convention. Use `TBD` only when sizing is
  genuinely blocked on something listed in Open Questions — don't guess a
  number to satisfy the field. Required in frontmatter for every plan this
  skill creates; it flows straight into `.context/index.yaml` so a reader can
  triage plans by effort without opening each file.
- **Value** — a `HIGH`/`MEDIUM`/`LOW` benefit-of-action grade, distinct from
  effort (cost) and severity (risk-of-inaction). Grade against
  [`.context/instructions/value-rubric.md`](../../../../instructions/value-rubric.md)
  (leverage, consumers unblocked, reversibility) — do not guess. Required in
  frontmatter for every plan this skill creates; it flows into
  `.context/index.yaml`, where the "what's next" read protocol sorts by value
  descending, then effort ascending.
- **Themes** — an ordered list of one or more areas from the controlled
  vocabulary (`EVAL` / `PR-TOOLING` / `DOCS` / `GOVERNANCE` / `SKILL-QUALITY` /
  `DISTRIBUTION`), drawn from
  [`.context/instructions/theme-vocabulary.md`](../../../../instructions/theme-vocabulary.md).
  The subject axis (what area the plan touches), orthogonal to value/effort.
  Write it **primary-first** — `themes[0]` answers "what is this mainly about?"
  and is the tie-breaker below value then effort. Required in frontmatter for
  every plan this skill creates.

### 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:

```bash
.context/plugins/pantheon-org/context-mgmt/context-index/scripts/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: ACTIVE to start implementing
```

## 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
   .context/plugins/pantheon-org/context-mgmt/context-index/scripts/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 `.context/instructions/value-rubric.md` rather than guessed.
7. **Themes tagged** — frontmatter has a non-empty `themes` list, ordered
   primary-first, with every member drawn from
   `.context/instructions/theme-vocabulary.md` (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.
- Tasks should be single-session-sized. 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.
- Default to `status: DRAFT`. Promote to `ACTIVE` only after the plan is reviewed
  and approved.
- The YAML frontmatter is not optional. A plan without frontmatter is invisible
  to `.context/index.yaml` and to every agent that reads it.

## 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` 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

- [Plan Structure Reference](references/plan-structure.md) — common plan
  sections and their purpose
- `context-file` skill — for repairing frontmatter on existing files
- `plan-review` skill — for post-creation multi-perspective audit
- `context-index` skill — for regenerating the index after creation