acostanzo/plan

/avanti:plan — Draft a new plan

You are the /avanti:plan orchestrator. When the user runs /avanti:plan <slug>, draft a new plan from templates/plan.md into project/plans/active/<slug>.md, then walk the user through an interactive authoring pass over the frontmatter and pivot paragraph. Refuse to overwrite existing files.

Read ${CLAUDE_PLUGIN_ROOT}/references/sdlc-conventions.md before proceeding if you are uncertain about any lifecycle or frontmatter rule.

Phase 0: Parse and validate

Step 1: Parse the slug

Extract the slug from $ARGUMENTS.

• If $ARGUMENTS is empty or missing → use AskUserQuestion to prompt: "What slug should the plan use? (kebab-case, e.g. phase-2-lintguini)"
• Validate the slug against ^[a-z][a-z0-9]*(-[a-z0-9]+)*$. If it fails, reject and re-prompt.

Store the validated slug as SLUG.

Step 2: Locate the repo root and the plans directory

Run git rev-parse --show-toplevel 2>/dev/null via Bash. If this fails (not a git repo), abort with a clear message — avanti expects to be run inside a repo.

Store the result as REPO_ROOT. The plans directory is PLANS_DIR = ${REPO_ROOT}/project/plans/.

Step 3: Check for collisions

Glob for project/plans/*/${SLUG}.md rooted at REPO_ROOT. If any file matches (in draft/, active/, or done/), abort:

A plan with slug "${SLUG}" already exists at <matching path>.
Refusing to overwrite. Pick a different slug or remove the existing plan.

Step 4: Ensure the plans directory exists

The destination is deterministic: ${PLANS_DIR}active/. If it is missing, create it with mkdir -p via Bash and continue. The destination is avanti's to manage and cheap to create on demand.

Phase 1: Gather authoring input

Step 1: Get today's date

Run date +%Y-%m-%d via Bash. Store as TODAY.

Step 2: Interactive authoring

Use AskUserQuestion to collect:

1. Plan title — the H1 that follows the frontmatter. Short, descriptive. Example: "Phase 2 — Lintguini linter integration."
2. Phase number — integer. The broad execution phase this plan belongs to. Default: 1 for first-phase work.
3. Pivot paragraph — one paragraph summarizing the plan's role, goal, and scope boundary. This is the paragraph a reviewer reads first; lead with the goal, close with what's out.

Store as TITLE, PHASE, PIVOT.

Phase 2: Render and write

Step 1: Read the template

Read ${CLAUDE_PLUGIN_ROOT}/templates/plan.md. Store as TEMPLATE.

Step 2: Fill placeholders

Produce RENDERED by applying these substitutions to TEMPLATE:

• phase: 0 → phase: ${PHASE}
• updated: TODO → updated: ${TODAY}
• # TODO — <plan title> → # ${TITLE}
• The "TODO: one paragraph that pivots into the work..." block under ## The role in one paragraph → ${PIVOT}

The template ships with status: active (the default landing folder), so no status substitution is needed for the default path. If a future --draft flag ships, the substitution becomes status: active → status: draft and the write target becomes plans/draft/.

Leave all other TODO/placeholder sections intact — the author will flesh them out over the course of the plan's life (model, tickets, acceptance bars, out-of-scope, DoD).

Step 3: Write

Write RENDERED to ${PLANS_DIR}active/${SLUG}.md using the Write tool.

Phase 3: Report

Tell the user:

Plan drafted: project/plans/active/${SLUG}.md

Next:
  - Fill in the model, tickets, acceptance bars, and DoD sections.
  - Commit the plan; the PR is the draft surface.
  - Mint tickets with /avanti:ticket <slug> --plan ${SLUG}
  - Promote to done/ with /avanti:promote plan:${SLUG} once every ticket is closed and A-bars pass.

Error handling

• Slug validation fails repeatedly: abort after two failed attempts with a pointer to the kebab-case rule.
• Write fails: report the underlying error; do not leave a partial file. If Write created a file before failing, delete it (rm via Bash) before re-raising.
• Repo has no project/plans/active/: auto-create it with mkdir -p and proceed. Plan-state subdirectories (active/, draft/, done/) are avanti's destination — cheap to create on demand.