create-plan
Turn what is known about a task into one plan file that a person can review line by line. The plan
lives in the task directory, and comments are written into the file, so the review history stays
with the plan and survives a new session.
The layout (path, file name, front matter, comment block, the "done" signal) is fixed in
references/artifact-layout.md. Only scripts/artifact.mjs writes
the front matter.
Steps
Find the task directory. Ask for the task name if it was not given (kebab-case, one per
branch, issue or lane). List what is already there:
node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" status --task-dir .ork/tasks/<task>
Read every artifact in it in full, in NN order: research, earlier plans, and their comment
blocks. Open comments on an earlier artifact are requirements unless they were resolved.
Read the code the research points at. Every file the plan changes must be opened, so file
paths and code in the plan are real.
Write the body to a scratch file, using
references/plan-template.md. Each phase is testable on its own,
names the files it changes, and ends with runnable automated checks.
Create the artifact through the script (never write the file directly):
node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" create \
--task <task> --kind plan --slug <slug> --title "<title>" --author <your seat> --body /tmp/plan-body.md
# prints .ork/tasks/<task>/NN-plan-<slug>.md
Reply with the path and stop. Ask the reviewer to comment in the file (or run
/ork:review-artifact-comments after they do). Do not start implementing.
Rules
- When documents disagree, the newest wins: plan over research over the original ask.
- Out of scope is a section, not an afterthought: list what the plan will not do.
- Manual checks only where a person really has to look; do not pad phases with them.
- A second plan for the same task is a new artifact (new NN), not an edit of the old one. Revising
the same plan is
iterate-plan.
Related
/ork:iterate-plan: revise this plan from review comments, keeping every comment.
/ork:create-research: the research artifact this plan should read first.
/ork:review-artifact-comments: read, answer and resolve comments on any artifact.
1---2name: create-plan3description: "Writes an implementation plan file (.ork/tasks/TASK/NN-plan-SLUG.md) with phases, file changes and runnable success criteria. Use when research is done and a reviewable plan is needed before code."4argument-hint: "<task> [slug]"5user-invocable: true6allowed-tools: "Bash Read Write Grep Glob"7compatibility: "Claude Code 2.1.277+. Node 22+."8metadata:9 source: https://skillmd.com/skills/yonatangross/create-plan10 version: "1.0.0"11 author: "OrchestKit"12 complexity: "medium"13 tags: "planning, artifacts, review, task-directory, workflow"14---1516# create-plan1718Turn what is known about a task into one plan file that a person can review line by line. The plan19lives in the task directory, and comments are written into the file, so the review history stays20with the plan and survives a new session.2122The layout (path, file name, front matter, comment block, the "done" signal) is fixed in23[references/artifact-layout.md](references/artifact-layout.md). Only `scripts/artifact.mjs` writes24the front matter.2526## Steps27281. **Find the task directory.** Ask for the task name if it was not given (kebab-case, one per29 branch, issue or lane). List what is already there:3031 ```bash32 node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" status --task-dir .ork/tasks/<task>33 ```34352. **Read every artifact in it in full**, in NN order: research, earlier plans, and their comment36 blocks. Open comments on an earlier artifact are requirements unless they were resolved.373. **Read the code the research points at.** Every file the plan changes must be opened, so file38 paths and code in the plan are real.394. **Write the body** to a scratch file, using40 [references/plan-template.md](references/plan-template.md). Each phase is testable on its own,41 names the files it changes, and ends with runnable automated checks.425. **Create the artifact** through the script (never write the file directly):4344 ```bash45 node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" create \46 --task <task> --kind plan --slug <slug> --title "<title>" --author <your seat> --body /tmp/plan-body.md47 # prints .ork/tasks/<task>/NN-plan-<slug>.md48 ```49506. **Reply with the path and stop.** Ask the reviewer to comment in the file (or run51 `/ork:review-artifact-comments` after they do). Do not start implementing.5253## Rules5455- When documents disagree, the newest wins: plan over research over the original ask.56- Out of scope is a section, not an afterthought: list what the plan will not do.57- Manual checks only where a person really has to look; do not pad phases with them.58- A second plan for the same task is a new artifact (new NN), not an edit of the old one. Revising59 the same plan is `iterate-plan`.6061## Related6263- `/ork:iterate-plan`: revise this plan from review comments, keeping every comment.64- `/ork:create-research`: the research artifact this plan should read first.65- `/ork:review-artifact-comments`: read, answer and resolve comments on any artifact.