create-plan

name	create-plan
description	Create a standard execution-ready implementation plan under docs/plans/<slug>/ with phases/sprints, atomic tasks, dependencies, validation, and Read First source context. Use when the user asks to plan implementation or split work. For required complexity scoring, sprint scorecards, PR grouping, or subagent-reviewed execution modeling, use create-dispatch-plan.

Create Plan

Create detailed, phased implementation plans (sprints + atomic tasks) for bugs, features, or refactors. This skill produces a plan document only; it does not implement.

Contract

Prereqs:

• User is asking for an implementation plan (not asking you to build it yet).
• You can read enough repo context to plan safely (or the user provides constraints).
• plan-tooling available on PATH from nils-cli >= 0.8.7 for scaffold/lint/parse/split flows (scaffold, validate, to-json, batches, split-prs; install via brew install nils-cli).

Inputs:

• User request (goal, scope, constraints, success criteria).
• Primary source artifact or source material to convert into one.
• Optional: repo context (files, architecture notes, existing patterns).

Outputs:

• A new plan file saved to docs/plans/<slug>/<slug>-plan.md.
• A Read First section that links the primary source artifact or records an explicit plan-only waiver.
• Optional tracking issue handoff when the user explicitly asks for provider issue tracking; use plan-tracking-issue after plan validation instead of making issue creation a default create-plan side effect.
• A short response that links the plan path and summarizes the approach.
• If the request is not actually an implementation plan, a short recommendation for a better durable artifact instead of forcing docs/plans/.

Exit codes:

• N/A (conversation/workflow skill)

Failure modes:

• Request remains underspecified and the user won't confirm assumptions.
• No usable source artifact exists and the user does not approve a plan-only waiver.
• Plan requires access/info the user cannot provide (credentials, private APIs, etc.).

Entrypoint

• None. This is a workflow-only skill with no scripts/ entrypoint.

Workflow

1. Decide whether you must ask questions first

• If the request is underspecified enough to block a useful plan, ask 1-5 "need to know" questions before writing the plan.
• Follow the blocking-question structure from $AGENT_HOME/skills/workflows/conversation/requirements-gap-scan/SKILL.md (numbered questions, short options, explicit defaults).

1. Confirm that a plan is the right artifact

• Use this skill when the user needs implementation sequencing: phases, sprints, atomic tasks, validation gates, ownership boundaries, or PR/issue splitting.
• Do not force docs/plans/ when the request is mainly to preserve review findings, risks, lessons learned, improvement backlog, or "what to fix later" guidance. Use review-to-improvement-doc for a project-local durable doc/runbook/backlog entry, or recommend one if the user did not ask you to write it.
• Do not force docs/plans/ when the request is mainly to preserve converged requirements, design, feasibility, product, or customer-facing discussion. Use discussion-to-implementation-doc for the implementation-readiness source artifact.
• If the user needs both a durable review/improvement record and an execution plan, keep them distinct: preserve the stable findings in the project doc first, then write the plan under its own docs/plans/<slug>/ folder and link that doc under the plan's context/read-first section.
• If a durable project doc, issue, or tracker already exists, reference it rather than duplicating the full backlog inside the plan.
• If the user wants to execute or resume an existing plan or implementation-ready document, use execute-from-plan instead of creating another plan.

1. Establish the plan source artifact

• Every plan must have exactly one primary source artifact unless the user explicitly asks for a plan-only waiver.
• For converged requirements, design, feasibility, product, architecture, or customer-facing discussion, first use discussion-to-implementation-doc or reference an equivalent existing doc/spec. When creating it for this plan, save it as docs/plans/<slug>/<slug>-discussion-source.md.
• For review findings, risks, lessons learned, or fix-later backlog, first use review-to-improvement-doc or reference an equivalent existing issue/doc. When creating it for this plan, save it as docs/plans/<slug>/<slug>-review-source.md.
• For plan-created source docs, keep the sibling bundle machine-checkable: source docs should include stable labels Recommended plan and Recommended execution state using docs/plans/<slug>/<slug>-plan.md and docs/plans/<slug>/<slug>-execution-state.md, and this plan's Read First Primary source should point back to the sibling source doc.
• For unresolved HEURISTIC_SYSTEM workflow gaps that must survive cleanup before a fix exists, create or reference heuristic-system/error-inbox/<slug>.md and link it as the primary source or a Read First record.
• Existing issues, tickets, specs, or project docs can be the primary source when they already separate facts, scope, decisions, acceptance criteria, and open questions well enough for execution.
• Link the primary source under Read First; do not duplicate the full requirements, findings, or rationale in the plan.
• Treat plan-created source docs as coordination artifacts that are eligible for cleanup after execution unless they are explicitly promoted.

1. Research the repo just enough to plan well

• Identify existing patterns, modules, and similar implementations.
• Note constraints (runtime, tooling, deployment, CI, test strategy).

1. Write the plan (do not implement)

• Follow the shared baseline in skills/workflows/plan/_shared/references/PLAN_AUTHORING_BASELINE.md.
• For browser-facing acceptance, name browser-qa evidence when UI, layout, JavaScript, DOM interaction, authenticated browser state, console output, network behavior, screenshots, or deploy-preview inspection matters. Keep browser QA conditional, not mandatory for every task.
• Fill Complexity when it materially affects batching/splitting or when a task looks oversized.
• You may omit sprint scorecards unless the user explicitly wants deeper sizing analysis or execution modeling.

1. Save the plan file

• Use the shared save rules from skills/workflows/plan/_shared/references/PLAN_AUTHORING_BASELINE.md.

1. Lint the plan (format + executability)

• Use the shared lint flow from skills/workflows/plan/_shared/references/PLAN_AUTHORING_BASELINE.md.

1. Run an executability + grouping pass (mandatory)

• Use the shared executability + grouping workflow in skills/workflows/plan/_shared/references/PLAN_AUTHORING_BASELINE.md.
• Add sprint metadata only when the plan needs explicit grouping/parallelism metadata or the user asks for that level of execution detail.

1. Optionally create a tracking issue

• Only do this when the user explicitly asks to open a provider issue, requests issue tracking for this plan, or a repo-local policy clearly opts into issue tracking.
• Use plan-tracking-issue after the plan and primary source are saved and linted.
• The tracking issue is a follow-up/discovery surface; the primary source and plan bundle remain the source of truth.
• Prefer --dry-run first when the provider, repository, labels, milestone, or assignee are uncertain.
• Do not use this optional handoff as a substitute for deliver-dispatch-plan; that workflow remains the heavyweight GitHub execution path when the issue itself drives sprint/subagent close gates.

1. Review "gotchas"

• Use the shared Risks & gotchas guidance from skills/workflows/plan/_shared/references/PLAN_AUTHORING_BASELINE.md.

Plan Template

Shared markdown scaffold:

• skills/workflows/plan/_shared/assets/plan-template.md

Canonical shared authoring and validation rules:

• skills/workflows/plan/_shared/references/PLAN_AUTHORING_BASELINE.md

Optional scaffold helper (creates a placeholder plan; fill it before linting):

• plan-tooling scaffold --slug <slug> --title "<task name>"