arn-spark-prototype-lock

Arness Prototype Lock

Create a frozen, independently servable snapshot of the validated prototype before development code begins to modify shared source files. The primary artifacts are a frozen prototype copy, CLAUDE.md guardrail rules that prevent agents from modifying prototype files, an optional PreToolUse hook for enforcement, and a git tag marking the prototype completion point.

This skill addresses the problem: once development starts, production code overwrites prototype components because they share the same source files. The locked copy preserves the validated design reference for visual comparison and rollback.

Prerequisites

Read the project's CLAUDE.md for a ## Arness section. If no ## Arness section exists or Arness Spark fields are missing, inform the user: "Arness Spark is not configured for this project yet. Run /arn-brainstorming to get started — it will set everything up automatically." Do not proceed without it.

Extract:

• Prototypes directory (default: .arness/prototypes)
• Vision directory (default: .arness/vision)
• Git (yes/no)
• Platform (github/bitbucket/none)

Check for prototype validation evidence:

1. Check for [prototypes-dir]/clickable/final-report.md -- if found, read it. Extract the latest version number and judge verdict.
2. Check for [prototypes-dir]/static/final-report.md -- same.
3. Check for [prototypes-dir]/criteria.md

If no prototype validation evidence found: Inform the user: "No prototype validation results found. This skill works best after /arn-spark-clickable-prototype or /arn-spark-static-prototype has validated a prototype. You can still lock any existing prototype files. What prototype source should I preserve?"

If validation found but judge verdict was FAIL: Warn the user: "The latest prototype version (v[N]) received a FAIL verdict from the judge. Are you sure you want to lock this version, or would you prefer to run more validation cycles first?"

Check for architecture vision to detect the stack:

1. Read architecture-vision.md from the Vision directory
2. Extract: UI framework (Svelte/SvelteKit, React/Next.js, Vue/Nuxt, etc.), application framework (Tauri, Electron, plain web), package manager

Workflow

Step 1: Inventory Prototype Artifacts

Scan the prototypes directory structure. Build an inventory:

"I found the following prototype artifacts:

Clickable prototype:

• Latest version: v[N] (Judge: [PASS/FAIL])
• App source: [prototypes-dir]/clickable/v[N]/app/ ([X] files, [Y] KB)
• Journey screenshots: [prototypes-dir]/clickable/v[N]/journeys/ ([Z] files)
• Showcase: [prototypes-dir]/clickable/v[N]/showcase/ ([W] files)
• Review/judge reports: [list]

Static prototype:

• Latest version: v[M] (Judge: [PASS/FAIL])
• Showcase: [prototypes-dir]/static/v[M]/showcase/ ([A] files)
• Review/judge reports: [list]

Shared:

• Criteria: [prototypes-dir]/criteria.md

Total size: [calculated total]

Which version should I lock? (Default: latest passing version)"

Wait for user to confirm or specify a different version before proceeding. Do not continue until the user responds.

Step 2: Detect Stack and Plan Copy Strategy

Read the prototype app directory and detect the framework:

• Check for package.json -- read for framework indicators (svelte, react, vue, next, nuxt, sveltekit)
• Check for Cargo.toml if Tauri
• Check for build configuration files (vite.config, next.config, svelte.config, etc.)

Determine copy strategy based on stack:

| Framework | Copy Strategy | Validation | |-----------|--------------|------------| | SvelteKit | Copy full app directory, exclude node_modules. Include package.json, lockfile, svelte.config, vite.config, tailwind.config, src/, static/ | cd [dest] && [pm] install && [pm] run build | | Next.js | Copy full app directory, exclude node_modules and .next/. Include package.json, lockfile, next.config, tsconfig, src/, public/ | cd [dest] && [pm] install && [pm] run build | | Vue/Nuxt | Copy full app directory, exclude node_modules and .nuxt/. Include package.json, lockfile, nuxt.config, src/ | cd [dest] && [pm] install && [pm] run build | | Plain HTML/CSS/JS | Copy all files directly | Open index.html in browser or serve with npx serve | | Tauri | Copy the webview source (follows its own framework row above). Copy src-tauri/ config only if relevant to the UI snapshot | Framework-specific build (webview only) |

Present the plan:

"Stack detected: [framework]

Copy plan:

• Source: [prototypes-dir]/clickable/v[N]/app/
• Destination: [prototypes-dir]/locked/clickable-v[N]/
• Strategy: [framework-specific description]
• Excludes: node_modules/, build output dirs (.svelte-kit/, .next/, dist/)
• Includes: lockfile (package-lock.json/pnpm-lock.yaml/yarn.lock/bun.lockb), all config, all source

Also copying:

• Validation evidence (review reports, judge reports, screenshots, showcase)
• Criteria document

Proceed?"

Wait for user confirmation.

Step 3: Execute Copy

1. Create destination directory: [prototypes-dir]/locked/clickable-v[N]/
2. Copy the prototype app source using cp -r with exclusion of node_modules/ and framework build output directories
3. Copy validation evidence:
4. Journey screenshots from the locked version
5. Showcase screenshots
6. Review and judge reports for the locked version
7. The final-report.md for each prototype type
8. Copy criteria.md
9. Read the lock report template:

> Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-prototype-lock/references/lock-report-template.md

1. Write a LOCKED.md manifest file at [prototypes-dir]/locked/LOCKED.md using the template. Populate all fields with the actual values from the copy operation.

If a static prototype exists and is validated, repeat the copy for the static prototype to [prototypes-dir]/locked/static-v[M]/.

Step 4: Validate the Snapshot

1. cd into the locked copy
2. Run dependency install using the detected package manager (npm/pnpm/yarn/bun)
3. Run build using the framework's build command
4. If the project has a dev server command, start it briefly and verify it responds:
5. Start the dev server in the background
6. Poll for readiness (check HTTP response on the expected port)
7. Kill the dev server after confirming it responds
8. Report validation result

If validation fails:

• Report the error
• Ask: "The locked copy does not build independently. Common causes: hard-coded paths, missing shared dependencies, monorepo imports. Should I investigate and fix, or skip validation?"
• If fixing: diagnose and fix path issues, missing deps, etc. Re-validate.
• After 3 failures: "Cannot make the locked copy build independently. The files are preserved as a reference but cannot be served standalone. Proceeding with guardrails."

Update the LOCKED.md manifest with the validation results.

Step 5: Ask User to Confirm Access

"The prototype snapshot is at [path]. Can you confirm you can access it?

If this is a web-based prototype, you can verify by running:

cd [path]
[install command]
[dev server command]

Then open [URL] in your browser.

Is the snapshot accessible and working?"

Wait for user confirmation. If the user reports issues, investigate.

Step 6: Git Tag

If Git is configured (Git: yes):

1. Check for uncommitted changes: git status --short
2. If uncommitted changes exist: "There are uncommitted changes. The git tag should mark a clean state. Should I commit current changes first, or tag despite uncommitted changes?"
3. If the tag name already exists, append a sequence number: prototype-lock-[date]-2
4. Create the tag: git tag -a prototype-lock-[date] -m "Prototype locked after validation. Clickable v[N] (Judge: [verdict]). See [prototypes-dir]/locked/LOCKED.md"
5. Report: "Git tag prototype-lock-[date] created. You can return to this exact state with git checkout prototype-lock-[date]."

If Git is not configured: skip, no