/arn-code-plan

name: arn-code-plan
description: >-
  This skill should be used when the user says "arness code plan", "arn-code-plan",
  "write a plan", "create plan", "implementation plan", "plan feature",
  "plan the spec", "plan from spec", "generate plan", "arness code plan FEATURE_X",
  "plan the bugfix", "plan bugfix", "make a plan",
  or wants to generate an implementation plan from a Arness specification.
  The skill invokes the arn-code-feature-planner agent to generate the plan,
  presents it for review, and iterates on user feedback until approved.
  Produces a PLAN_PREVIEW file that feeds into /arn-code-save-plan.
version: 1.1.0
argument-hint: "[spec-name]"

Arness Plan

Generate an implementation plan from a Arness specification by invoking the `arn-code-feature-planner` agent. The plan is written to disk as a PLAN_PREVIEW file, presented to the user for review, and iteratively refined based on feedback until approved. The approved plan then feeds into `/arn-code-save-plan` for structuring into phases, tasks, and reports.

Pipeline position:

arn-code-init -> arn-code-feature-spec / arn-code-bug-spec -> **arn-code-plan** -> arn-code-save-plan -> arn-code-review-plan -> arn-code-taskify -> arn-code-execute-plan

Prerequisites

If no `## Arness` section exists in the project's CLAUDE.md, inform the user: "Arness is not configured for this project yet. Run `/arn-planning` to get started — it will set everything up automatically." Do not proceed without it.

Workflow

Step 1: Load Configuration

Read the project's CLAUDE.md and extract the `## Arness` section to find:

• **Plans directory** — base path where project plans and PLAN_PREVIEW files are stored
• **Specs directory** — path to the directory containing specification files
• **Code patterns** — path to the directory containing stored pattern documentation

If `## Arness` is not found, inform the user: "Arness is not configured for this project yet. Run `/arn-planning` to get started — it will set everything up automatically." Do not proceed.

---

Step 2: Find the Specification

The user may provide a spec name as an argument (e.g., "arness plan FEATURE_websocket-notifications" or "plan the spec websocket-notifications").

**If an argument was provided:**

• Look for `<specs-dir>/<argument>.md` (exact match)
• If not found, try `<specs-dir>/FEATURE_<argument>.md` and `<specs-dir>/BUGFIX_<argument>.md`
• If not found, try matching files in `<specs-dir>/` that contain the argument text in their filename
• If still not found, list available specs and ask the user to choose

**If no argument was provided:**

• List all `.md` files in `<specs-dir>/`
• If only one exists, use it automatically
• If multiple exist, show the list sorted by modification date (most recent first) and ask the user to choose
• If none exist, inform the user: "No specifications found in `<specs-dir>/`. Run `/arn-code-feature-spec` or `/arn-code-bug-spec` to create one first."

---

Step 3: Load Context

Read these files (skip any that don't exist): 1. The selected specification file 2. `<code-patterns-dir>/code-patterns.md` 3. `<code-patterns-dir>/testing-patterns.md` 4. `<code-patterns-dir>/architecture.md` 5. `<code-patterns-dir>/ui-patterns.md` (if it exists) 6. `<code-patterns-dir>/security-patterns.md` (if it exists)

**If pattern documentation files are missing** (no `code-patterns.md`, `testing-patterns.md`, or `architecture.md` in the Code patterns directory):

Inform the user: "This is the first time pattern documentation is being generated for this project. Analyzing your codebase to understand its patterns, conventions, and architecture. This is a one-time operation — future invocations will use the cached results."

Then invoke `arn-code-codebase-analyzer` (existing codebase) or `arn-code-pattern-architect` (greenfield) to generate fresh analysis. Write the results to the Code patterns directory.

---

Step 3.5: Verify Spec Alignment with Current Codebase

Specs may have been written days or weeks before being planned. The codebase moves in the meantime — files get renamed, modules refactored, frameworks swapped. Before invoking the planner, verify the spec's concrete references still hold against HEAD.

Spawn the `arn-code-drift-detector` agent via the Agent tool, passing the model from `.arness/agent-models/code.md` as the `model` parameter (see `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:

Verify whether the following specification still aligns with the current codebase.

**Spec file:** <specs-dir>/<spec-filename>
**Source root:** <repo root>

Return a structured drift report with severity classified as none, minor, moderate, or major.

Capture the agent's drift report and branch on severity:

• **`none`** — proceed silently to Step 4.
• **`minor`** — display the report's `Summary` line to the user (one sentence). Carry the full drift report forward as an annotation to the planner agent's context (see Step 4 input block below). Proceed to Step 4.
• **`moderate` or `major`** — display the full drift report. Then ask the user how to proceed using `AskUserQuestion`:

**The spec has drifted from the current codebase. How would you like to proceed?** 1. **Refresh the spec** — route to `/arn-code-feature-spec` (or `/arn-code-bug-spec` for a bug spec) with the drift report as input so the spec can be updated against current reality. 2. **Proceed with annotations** — pass the drift report to the planner so it accounts for the divergence while building the plan. 3. **Abort** — exit the skill; no plan generated.

Honor the user's choice. On (1), exit this skill and route to the spec skill. On (3), exit cleanly. On (2), continue to Step 4 with the drift report attached.

If the drift detector itself fails (e.g., spec file unreadable, git unavailable), inform the user and ask whether to proceed without a drift check. Do not block