arn-code-save-plan

Arness Save Plan

Convert a planning conversation into a structured, executable project with phased implementation plans, testing plans, task lists, and progress tracking.

This skill requires Arness to be configured in the target project. If Arness configuration is not found in the project's CLAUDE.md, the user should run /arn-planning to get started.

Workflow

Step 1: Check Arness Configuration

Read the project's CLAUDE.md and look for a ## Arness section. Also check for a legacy ## Arness Save Plan section (from earlier versions of this skill).

If ## Arness is found, extract:

• Plans directory -- base path where project plans are saved
• Specs directory -- path to the directory containing specification files
• Report templates -- default or custom
• Template path -- path to the report template set (JSON templates)
• Template version -- plugin version the templates were copied from (if present)
• Template updates -- user preference: ask, auto, or manual (if present)
• Code patterns -- path to the directory containing stored pattern documentation

Validate that all paths exist on disk. If any path is missing, warn the user before proceeding.

Template Version Check

If the ## Arness section contains Template version and Template updates fields, compare the project's template version against the plugin version. If they differ, check for user modifications via checksums and either auto-update, prompt the user, or skip based on the configured preference. If ## Arness does NOT contain these fields, treat as legacy and skip.

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-save-plan/references/template-versioning.md for the full template version check procedure.

If legacy ## Arness Save Plan is found but no ## Arness, offer to migrate:

1. Inform the user: "I found a legacy ## Arness Save Plan section. Arness now uses a unified ## Arness configuration section."
2. Ask (using AskUserQuestion):

"Should I migrate this to the new format?"

Options:

1. Yes, migrate -- Rename the section and add new fields
2. No, keep legacy -- Proceed using legacy values

1. If Yes, migrate:
2. Rename the section to ## Arness
3. Add the Code patterns field with a default value of .arness/
4. Update the section in CLAUDE.md in place
5. If No, keep legacy: proceed using the legacy values, treating the missing Code patterns path as .arness/

If NEITHER section is found, Arness has not been configured:

1. 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.

Step 2: Initialize Project Structure

Ask the user for PROJECT_NAME if not already provided in the conversation.

Resolve the Plan File

Look for a PLAN_PREVIEW file in the plans directory:

1. Search for files matching PLAN_PREVIEW_*.md in <plans-dir>/
2. If exactly one PLAN_PREVIEW file exists: use it automatically. If PROJECT_NAME was not provided, derive it from the preview filename (e.g., PLAN_PREVIEW_websocket-notifications.md → websocket-notifications).
3. If multiple PLAN_PREVIEW files exist: list them and ask the user to choose.
4. If no PLAN_PREVIEW files exist: check ~/.claude/plans/ as a legacy fallback. If plans are found there, show the most recent and ask the user to confirm. If nothing is found anywhere, inform the user: "No plan found. Run /arn-code-plan to create one first."

Create Project Structure

Run the setup script with the resolved plan file path:

bash ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-save-plan/scripts/save_plan.sh <PROJECT_NAME> <OUTPUT_DIR> <resolved-plan-file-path>

This creates:

<OUTPUT_DIR>/<PROJECT_NAME>/
├── SOURCE_PLAN.md
├── plans/
└── reports/

If the script fails (non-zero exit code), report the error output to the user. Common causes: output directory does not exist, disk permissions, or PROJECT_NAME contains invalid characters. Do not proceed to Step 3 until the project structure is successfully created.

Step 3: Write INTRODUCTION.md

Create <OUTPUT_DIR>/<PROJECT_NAME>/INTRODUCTION.md using the template from ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-save-plan/references/templates.md.

Source Material

The INTRODUCTION.md draws from up to THREE sources:

1. SOURCE_PLAN.md — the plan (execution structure, phases/steps)
2. Specification file (optional) — for architectural context and decisions
3. Stored pattern documentation — for codebase patterns and references

Finding the specification:

• Search SOURCE_PLAN.md for a line matching Spec: <path> — if found, read that file
• If not found, search the specs directory (from ## Arness config) for files whose name matches the PROJECT_NAME pattern (e.g., project websocket-notifications matches spec FEATURE_websocket-notifications.md or BUGFIX_websocket-notifications.md)
• If multiple matches, ask the user which spec applies
• If no spec is found, proceed using only SOURCE_PLAN.md and pattern docs

Populating Sections

Use Claude's intelligence to interpret the source material and populate each INTRODUCTION.md section. Do NOT rely on exact section name matching — extract the relevant information regardless of how the source material is structured.

| INTRODUCTION.md Section | Primary Source | Fallback | |------------------------|---------------|----------| | Project Overview | Spec (Problem Statement / Bug Report) | Plan (any overview/summary content) | | Architectural Definition | Spec (Architectural Assessment) | Plan (any architecture/design content) | | Codebase Patterns | Stored pattern docs (code-patterns.md, testing-patterns.md, ui-patterns.md if present) | Stored pattern docs (code-patterns.md, testing-patterns.md) | | Codebase References | Stored pattern docs (architecture.md) | Stored pattern docs (architecture.md) | | Sketch Artifacts (conditional) | Spec (Sketch Reference section) | Scan arness-sketches/ for matching manifests | | Scope & Boundaries | Spec (Scope & Boundaries) | Plan (any scope content) | | Dependencies | Spec or Plan | Infer from components mentioned | | Phase Overview | Plan (logical phases/steps) | Single phase if plan has no explicit phases |

Phase identification from SOURCE_PLAN.md: Plans may use any structure. Identify logical phases by looking for:

• Explicit phase/step headers (any naming convention)
• Numbered task groups
• Sections that describe sequential work with dependencies
• If the plan is a flat task list, group related tasks into logical phases
• If no phases are identifiable, treat the entire plan as a single phase

Finding sketch artifacts: Check whether the specification file (if found) contains a ## Sketch Reference section. If it does, extract the sketch directory path, manifest path, blueprint path, and component mapping table from that section and populate the ### Sketch Artifacts subsection in the Codebase References section of INTRODUCTION.md. If no spec is found or the spec has no Sketch Reference section, fall back to scanning the project root for a arness-sketches/ directory. If a arness-sketches/ directory exists, look for a subdirectory whose name matches the PROJECT_NAME (by name or keyword overlap). If a matching sketch directory is found with a sketch-manifest.json containing componentMapping and composition fields, populate the Sketch Artifacts subsection from the manifest data. If no sketch is found through either method, omit the Sketch Artifacts subsection entirely.

Every pattern in INTRODUCTION.md MUST reference real files and real code from the codebase. Do not use placeholder content — the INTRODUCTION.md is the ground truth that all phase plans reference.

Step 4: Create Phase Plans

For each phase identified in Step 3's Phase Overview, create `<OUTPUT_DIR>/<PROJECT_NAME>