arn-code-plan

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 Task tool, passing the model from .arness/agent-models/code.md as the model parameter (see plugins/arn-code/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 on a tool failure.

Step 4: Invoke the Planner Agent

Derive the spec name from the spec filename (strip prefix and extension):

• FEATURE_websocket-notifications.md → websocket-notifications
• BUGFIX_checkout-500.md → checkout-500
• FEATURE_F-001.1_user-auth.md → F-001.1_user-auth

The output file path is: <plans-dir>/PLAN_PREVIEW_<spec-name>.md

Check for existing PLAN_PREVIEW: If a PLAN_PREVIEW file already exists at that path, inform the user: "A plan preview already exists for this spec: <path>. Would you like to regenerate it from scratch, or review the existing plan?" If review → skip to Step 5. If regenerate → proceed.

Spawn the arn-code-feature-planner agent via the Task tool, passing the model from .arness/agent-models/code.md as the model parameter (see plugins/arn-code/skills/arn-code-ensure-config/references/ensure-config.md "Dispatch convention" for fallback). Context:

You are generating an implementation plan for the following specification.

**Specification:** <spec-name>
**Spec file:** <specs-dir>/<spec-filename>

--- SPECIFICATION CONTENT ---
[full spec file content]
--- END SPECIFICATION ---

--- DRIFT REPORT ---
[full drift report from Step 3.5, if severity was minor/moderate/major and the user chose to proceed; omit this section entirely if severity was none]
--- END DRIFT REPORT ---

--- CODEBASE PATTERNS ---
[code-patterns.md content]
[testing-patterns.md content]
[architecture.md content]
[ui-patterns.md content, if it exists]
[security-patterns.md content, if it exists]
--- END CODEBASE PATTERNS ---

**Output file:** <plans-dir>/PLAN_PREVIEW_<spec-name>.md

Generate a structured implementation plan and write it to the output file.
Include `Spec: <specs-dir>/<spec-filename>` near the top for arn-code-save-plan linkage.

Record the agent ID returned by the Task tool (needed for resume in Step 5b).

Step 5: Present Plan and Feedback Loop

After the planner agent completes:

1. Read the generated plan from <plans-dir>/PLAN_PREVIEW_<spec-name>.md
2. Parse each phase's Complexity: and Complexity rationale: fields (added by the planner per ${CLAUDE_PLUGIN_ROOT}/agents/arn-code-feature-planner.md's Complexity Assessment section). If a phase is missing these fields (older plans), treat its complexity as unknown and skip the upgrade gate for it.
3. Present a structured summary to the user:
4. Spec: the linked specification name
5. Phases: list each phase with a 1-line description, key deliverables, and complexity rating (e.g., Phase 3: Dispatch Site Edits — 7 deliverables — complexity: complex). Always show the rating, regard