cvm-plan-create

name

cvm-plan-create

description

Author a valid CVM Plan Protocol (CVM-PP) plan that CVM can execute. Use this skill whenever you need to write, draft, or structure a CVM plan — a mission plus ordered TDDAB/step blocks — so an AI agent can be driven through the work one task at a time by the CVM planexecutor. Triggers: create a CVM plan, write a plan.md for CVM, turn this feature into a CVM-PP plan, prepare work for autonomous execution.

cvm-plan-create — Author a CVM-PP Plan

Purpose

CVM (Cognitive Virtual Machine) drives an AI agent through a piece of work one task at a time by reading a structured Markdown plan written in the CVM Plan Protocol (CVM-PP). This skill guides you to author such a plan so that parsePlan accepts it and the planexecutor can run it — no bespoke agent setup required. Your deliverable is a single plan.md (or an index + sub-files for large plans) that validates cleanly.

Step 1 — Read the format spec (source of truth)

READ docs/PLAN_FORMAT.md first. It is the authoritative CVM-PP grammar: tags, plan shapes, type detection, compiled output, validation rules. Do not rely on memory or reproduce the grammar from this skill — the spec is the contract and may have evolved. This skill is a workflow guide; docs/PLAN_FORMAT.md is the law.

Step 2 — Authoring checklist

Write the plan against the spec, ensuring:

• Mission is self-sufficient. Exactly one <mission> (in the single file, or in the index of a multi-file plan). It becomes PROJECT CONTEXT: for every block, so it must carry the tech stack, build/test commands, conventions, and file layout — enough that any single block can be executed on a clean context with no other knowledge.
• Block ids are NN-kebab-case and globally unique. Two digits, a hyphen, kebab slug (e.g. 01-parser, 02-task-store). Unique across all sub-files too.
• Decompose bottom-up, atomic blocks. One responsibility/layer per block; each block independently verifiable and rollback-able. Never one monolithic block per feature.
• <red> lines are strictly - test: .... Each item is one unit-level failing test (contract, not E2E). Any annotation goes after the colon: - test: register happy path @local-only — needs a live DB.
• <actions> blocks for non-testable work (docs, config, release steps). Each line is strictly - action: .... A pure step plan needs all blocks to be <actions>.
• <success> is a checklist of objectively checkable items (- [ ]), each provable against real code/tests with file:line evidence.
• Put rich detail in the block body (### Implementation prose/code) — it is not parsed but stays reachable via planRef.
• End with an Execution Order section listing blocks and their dependencies.
• Multi-file mode for large plans: an index file with <mission> + a <files> list (one - filename per line, file order = execution order); each sub-file holds only blocks. See the multi-file rules in the spec.

Step 3 — Common mistakes to avoid

• Tag before the colon (issue #10 trap). - test @local-only: register happy does not match - test: — it is now a hard validation error, and before CVM-PP v1.1 was silently dropped while the plan still looked valid:true. Always put tags/annotations after the colon.
• Prose or code inside <red> / <actions>. These sections are a strict contract: every non-empty line must be a valid - test: / - action: item (blank lines are OK). Move explanations into the block body.
• Options / TODOs / "investigate" in a block. A plan is a recipe, not a discussion — resolve every decision before writing it.
• Vague <success> items. If the agent cannot point at code to prove it, the VERIFY loop stalls.
• Raw TDDAB tag names with angle brackets inside tag content — the parser cannot tell them from real tag boundaries.

Step 4 — Validate before delivering

Run the parsePlan MCP tool on your plan file. It returns valid:true with the block count/ids, or a list of line N: message errors. Fix every reported error and re-run until it is clean. Do not deliver a plan that parsePlan rejects.