/arn-code-save-plan

name: arn-code-save-plan
description: >-
  This skill should be used when the user says "save plan", "save the plan",
  "arness code save plan", "structure this plan", "create project from plan",
  "export plan", "export project plan", "organize this plan",
  "set up project structure", "turn this into a project",
  "generate project structure", "finalize the plan", or wants to convert a
  planning
  conversation into an actionable phased project structure with implementation
  and testing plans.
version: 2.0.0
argument-hint: "[project-name]"

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

3. If **Yes, migrate**:

• Rename the section to `## Arness`
• Add the **Code patterns** field with a default value of `.arness/`
• Update the section in CLAUDE.md in place

4. 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 Se