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 for linting (install via brew install nils-cli).

Inputs:

• •User request (goal, scope, constraints, success criteria).
• •Optional: repo context (files, architecture notes, existing patterns).

Outputs:

• •A new plan file saved to docs/plans/<slug>-plan.md.
• •A short response that links the plan path and summarizes the approach.

Exit codes:

• •N/A (conversation/workflow skill)

Failure modes:

• •Request remains underspecified and the user won’t confirm assumptions.
• •Plan requires access/info the user cannot provide (credentials, private APIs, etc.).

Workflow

1. •Decide whether you must ask questions first

• •If the request is underspecified, ask 1–5 “need to know” questions before writing the plan.
• •Follow the structure from $AGENTS_HOME/skills/workflows/conversation/ask-questions-if-underspecified/SKILL.md (numbered questions, short options, explicit defaults).

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)

• •Use sprints/phases that each produce a demoable/testable increment.
• •Break work into atomic, independently testable tasks.
• •Include file paths whenever you can be specific.
• •Include a validation step per sprint (commands, checks, expected outcomes).

1. •Save the plan file

• •Path: docs/plans/<slug>-plan.md
• •Slug rules: lowercase kebab-case, 3–6 words, end with -plan.md.

1. •Lint the plan (format + executability)

• •Run: plan-tooling validate --file docs/plans/<slug>-plan.md
• •If it fails: tighten tasks (missing fields, placeholders, unclear validations) until it passes.

1. •Review “gotchas”

• •After saving, add/adjust a “Risks & gotchas” section: ambiguity, dependencies, migrations, rollout, backwards compatibility, and rollback.

Plan Template

Shared template (single source of truth):

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

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

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