@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-prototype-lock/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: arn-spark-prototype-lock
+description: >-
+  This skill should be used when the user says "prototype lock", "lock prototype",
+  "arn prototype lock", "freeze prototype", "preserve prototype",
+  "snapshot prototype", "protect prototype", "archive prototype",
+  "save the prototype", "don't overwrite the prototype",
+  "lock the design", "freeze the design",
+  or wants to create a frozen snapshot of the validated prototype before
+  development begins, preventing production code from overwriting the
+  validated reference artifact.
+version: 1.0.0
+---
+
+# 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**, **arness.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 `arness.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:
+   - Journey screenshots from the locked version
+   - Showcase screenshots
+   - Review and judge reports for the locked version
+   - The `final-report.md` for each prototype type
+4. Copy `criteria.md`
+5. Read the lock report template:
+   > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-prototype-lock/references/lock-report-template.md`
+6. 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:
+   - Start the dev server in the background
+   - Poll for readiness (check HTTP response on the expected port)
+   - Kill the dev server after confirming it responds
+5. 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, note that no tag was created.
+
+### Step 7: Write arness.md Guardrail Rules
+
+Read the guardrail rules template:
+> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-prototype-lock/references/prototype-guardrail-rules.md`
+
+Substitute the placeholders with project-specific paths:
+- `__LOCK_DATE__` -- today's date
+- `__LOCK_TAG__` -- the git tag name from Step 6, or "none" if git is not configured
+- `__LOCKED_DIR__` -- the locked directory path
+- `__CLICKABLE_VERSION__` -- e.g., `clickable/v3/`
+- `__STATIC_VERSION__` -- e.g., `static/v4/`
+- `__PROTOTYPES_DIR__` -- base prototypes directory
+
+Add the populated `### Prototype Lock` subsection to the `## Arness` section in the project's `arness.md`.
+
+### Step 8: Optional PreToolUse Hook
+
+Ask the user:
+
+Ask the user:
+
+**"The arness.md rules instruct agents not to modify prototype files. Do you want additional enforcement?"**
+
+Options:
+1. **Rules only** (default) — arness.md instructions are usually sufficient
+2. **Rules + hook** — Adds a PreToolUse guard script for stricter enforcement
+
+**If the user chooses hook:**
+
+Read the hook template:
+> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-prototype-lock/references/pretooluse-hook-template.json`
+
+The hook is installed in the **target project** (not in the arn-spark plugin):
+
+**Other AI assistants:** The guard is installed as a PreToolUse hook.
+1. Read or create `[PLATFORM_CONFIG_DIR]/settings.json` in the target project
+2. If `[PLATFORM_CONFIG_DIR]/settings.json` already exists and has PreToolUse hooks, append the prototype guard to the existing hook list. Otherwise, create the hooks configuration using the template's `hooks_config`.
+3. Adapt the guard script from the template:
+   - Replace `__PROTECTED_PATH_1__`, `__PROTECTED_PATH_2__`, etc. with the **relative paths** of the protected directories (relative to the project root, e.g., `.arness/prototypes/locked/`). The guard script resolves them at runtime using the `cwd` field from the hook input, so no user-specific absolute paths are committed.
+4. Write the guard script to `[PLATFORM_CONFIG_DIR]/hooks/prototype-lock-guard.sh` in the target project
+5. Make the script executable: `chmod +x [PLATFORM_CONFIG_DIR]/hooks/prototype-lock-guard.sh`
+
+**OpenCode.ai:** Protection is automatic — the `arn-spark.js` plugin includes a `tool.execute.before` handler that reads the `#### Protected Paths` from `arness.md` at runtime and blocks Write/Edit calls targeting those paths. No additional configuration is needed.
+
+**Note:** The hook guards Write and Edit tool calls only. Bash commands that modify the filesystem are not intercepted -- the arness.md rules (Step 7) are the primary defense for all operations including Bash.
+
+### Step 9: Present Summary
+
+"Prototype locked.
+
+**Snapshot:** [prototypes-dir]/locked/clickable-v[N]/
+**Manifest:** [prototypes-dir]/locked/LOCKED.md
+**Independent build:** [PASS/FAIL/SKIPPED]
+**Git tag:** prototype-lock-[date] [or 'none']
+**Guardrails:** arness.md rules [+ PreToolUse hook]
+
+**Protected paths** (agents will not modify):
+- [list from guardrail rules]
+
+**arness.md updated** with `### Prototype Lock` configuration.
+
+Recommended next steps:
+1. **Set up dev environment:** Run `/arn-spark-dev-setup` to configure the development environment
+2. **Define visual testing:** Run `/arn-spark-visual-strategy` to set up visual regression testing against the prototype
+3. **Extract features:** Run `/arn-spark-feature-extract` to build the backlog
+4. **Start developing:** If you have the Arness Code plugin installed, run `/arn-planning` to begin the development pipeline. Arness auto-configures on first use."
+
+## Agent Invocation Guide
+
+| Situation | Action |
+|-----------|--------|
+| Copy and validate snapshot (Steps 3-4) | Execute directly in conversation via Bash and Write. No agent needed -- operations are deterministic. |
+| Build validation fails with path issues | Diagnose directly. If the issue requires framework-specific knowledge, invoke `arn-spark-dev-env-builder` (foreground) for diagnosis assistance. |
+| User asks about prototype quality | Reference the judge report and review reports. Do not re-run validation. |
+| User wants to re-lock after more cycles | Re-run the skill. It detects the existing lock in Step 1 and offers to replace it. |
+| User asks about visual testing | Defer: "Visual regression testing against the prototype is set up by `/arn-spark-visual-strategy`." |
+| User asks about features | Defer: "Feature extraction is done by `/arn-spark-feature-extract`." |
+
+## Error Handling
+
+- **No prototype found:** Ask user to point to the prototype source directory. Proceed without validation evidence if necessary.
+- **Prototype fails to build independently:** Preserve the files as reference. Note limitation in LOCKED.md. Guardrails still protect the files.
+- **Lock already exists:** "A prototype lock already exists from [date]. Replace it, or keep both? (Keeping both creates `locked/clickable-v[N]-[date2]/`)"
+- **Git tag already exists:** Append a sequence number: `prototype-lock-[date]-2`
+- **arness.md write fails:** Print the guardrail block for manual insertion.
+- **Hook installation fails:** Proceed with arness.md rules only. Explain that rules are usually sufficient.
+- **Large prototype (>100MB):** Warn the user about disk usage. Suggest adding the locked directory to `.gitignore` if it should not be committed.
+- **Monorepo prototype (shares dependencies with main project):** The locked copy may need its own dependency install. Note this in the LOCKED.md manifest.

package/plugins/arn-spark/skills/arn-spark-prototype-lock/references/lock-report-template.md

@@ -0,0 +1,68 @@
+# Lock Report Template
+
+This template defines the structure for the `LOCKED.md` manifest file written by the `arn-spark-prototype-lock` skill. The manifest is saved to `[prototypes-dir]/locked/LOCKED.md` and documents the frozen prototype snapshot.
+
+## Template
+
+```markdown
+# Prototype Lock Manifest
+
+Locked by `/arn-spark-prototype-lock` on [date].
+
+## Locked Versions
+
+| Type | Version | Judge Verdict | Source | Locked Copy |
+|------|---------|--------------|--------|-------------|
+| [Clickable / Static] | v[N] | [PASS / FAIL / N/A] | [relative path to original] | [relative path to locked copy] |
+
+## Git Tag
+
+Tag: `[tag-name]` (or "None -- Git not configured")
+
+To return to this exact state: `git checkout [tag-name]`
+
+## Independent Build Validation
+
+| Check | Result |
+|-------|--------|
+| Dependency install | [PASS / FAIL / SKIPPED] |
+| Build | [PASS / FAIL / SKIPPED] |
+| Dev server | [PASS / FAIL / SKIPPED] |
+
+[If any checks failed: description of why and whether the snapshot is still usable as a reference]
+
+## Stack
+
+- **UI framework:** [detected framework]
+- **Package manager:** [npm / pnpm / yarn / bun]
+- **Build tool:** [vite / webpack / turbopack / etc.]
+
+## How to View
+
+```bash
+cd [locked-copy-path]
+[package-manager] install
+[package-manager] run dev
+```
+
+Then open [URL, e.g., http://localhost:5173] in your browser.
+
+## What is Locked
+
+The locked directory contains:
+- **Prototype source code** -- all components, routes, styles, and configuration
+- **Lockfile** -- exact dependency versions for reproducible builds
+- **Validation evidence** -- review reports, judge reports, journey screenshots, showcase
+- **Criteria document** -- agreed validation criteria
+
+## What is NOT Locked
+
+- `node_modules/` -- excluded from the copy (reinstall via lockfile)
+- Framework build output (`.svelte-kit/`, `.next/`, `dist/`) -- excluded (rebuild from source)
+- Runtime state, caches, and temporary files
+
+## Protected by
+
+- **arness.md rules:** `### Prototype Lock > #### Protected Paths` in the project's arness.md
+- **PreToolUse hook:** [yes / no] -- blocks Write/Edit operations targeting locked directories
+```

package/plugins/arn-spark/skills/arn-spark-prototype-lock/references/pretooluse-hook-template.json

@@ -0,0 +1,35 @@
+{
+  "description": "PreToolUse hook template for prototype lock guard. The skill reads this template, substitutes project-specific protected paths, and writes the hook configuration to the target project's [PLATFORM_CONFIG_DIR]/settings.json and the guard script to [PLATFORM_CONFIG_DIR]/hooks/prototype-lock-guard.sh.",
+
+  "hooks_config": {
+    "hooks": {
+      "PreToolUse": [
+        {
+          "matcher": "Write|Edit",
+          "hooks": [
+            {
+              "type": "command",
+              "command": "bash [PLATFORM_CONFIG_DIR]/hooks/prototype-lock-guard.sh"
+            }
+          ]
+        }
+      ]
+    }
+  },
+
+  "guard_script": "#!/usr/bin/env bash\n# prototype-lock-guard.sh\n# Blocks Write/Edit operations targeting locked prototype directories.\n# Reads tool invocation JSON from stdin; outputs decision JSON to stdout.\n# Always exits 0 (hooks must not crash).\n#\n# Installed by /arn-spark-prototype-lock. See ### Prototype Lock in arness.md.\n#\n# Protected paths are RELATIVE to the project root. The script resolves\n# them at runtime using the cwd field from the hook input, so no\n# user-specific absolute paths are committed.\n#\n# JSON parsing: tries jq -> python3 -> node (first available wins).\n# If none are found, allows the operation (fail-open -- arness.md rules\n# remain the primary defense).\n\nPROTECTED_PATHS=(\n  \"__PROTECTED_PATH_1__\"\n  \"__PROTECTED_PATH_2__\"\n  \"__PROTECTED_PATH_3__\"\n)\n\ninput=$(cat)\n\nparse_json() {\n  if command -v jq >/dev/null 2>&1; then\n    file_path=$(echo \"$input\" | jq -r '.tool_input.file_path // .tool_input.filePath // \"\"')\n    cwd=$(echo \"$input\" | jq -r '.cwd // \"\"')\n  elif command -v python3 >/dev/null 2>&1; then\n    eval \"$(echo \"$input\" | python3 -c \"\nimport sys, json\ntry:\n    d = json.load(sys.stdin)\n    ti = d.get('tool_input', {})\n    fp = ti.get('file_path', '') or ti.get('filePath', '')\n    cwd = d.get('cwd', '')\n    print(f'file_path={chr(34)}{fp}{chr(34)}')\n    print(f'cwd={chr(34)}{cwd}{chr(34)}')\nexcept:\n    print('file_path={0}{0}'.format(chr(34)))\n    print('cwd={0}{0}'.format(chr(34)))\n\" 2>/dev/null)\"\n  elif command -v node >/dev/null 2>&1; then\n    eval \"$(echo \"$input\" | node -e \"\nlet d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{\ntry{const j=JSON.parse(d);const ti=j.tool_input||{};\nconsole.log('file_path=\\\"'+(ti.file_path||ti.filePath||'')+'\\\"');\nconsole.log('cwd=\\\"'+(j.cwd||'')+'\\\"');\n}catch(e){console.log('file_path=\\\"\\\"');console.log('cwd=\\\"\\\"');}\n});\" 2>/dev/null)\"\n  else\n    file_path=\"\"\n    cwd=\"\"\n  fi\n}\n\nparse_json\n\nif [ -z \"$file_path\" ]; then\n  echo '{}'\n  exit 0\nfi\n\nfor protected in \"${PROTECTED_PATHS[@]}\"; do\n  resolved=\"${cwd}/${protected}\"\n  if [[ \"$file_path\" == \"$resolved\"* ]]; then\n    echo '{\"decision\":\"block\",\"reason\":\"This file is in the locked prototype directory. Prototype files are read-only reference artifacts. See ### Prototype Lock in arness.md.\"}'\n    exit 0\n  fi\ndone\n\necho '{}'\nexit 0",
+
+  "installation_notes": [
+    "The guard script and hook config are written to the TARGET PROJECT, not the arn-spark plugin.",
+    "Protected paths are RELATIVE to the project root (e.g., '.arness/prototypes/locked/'). The script resolves them at runtime using the cwd field from the hook input JSON, so no user-specific absolute paths are committed.",
+    "JSON parsing uses a fallback chain: jq (preferred, used in AI assistant documentation) -> python3 -> node. If none are available, the hook allows the operation (fail-open) and arness.md rules serve as the primary defense.",
+    "The script reads JSON from stdin (tool invocation), extracts file_path and cwd, resolves relative protected paths against cwd, and checks for matches.",
+    "If protected: outputs block decision with reason. If not: outputs empty JSON (allow).",
+    "Always exits 0 -- hooks must never crash or the tool call will fail.",
+    "The skill merges the hooks_config into the existing [PLATFORM_CONFIG_DIR]/settings.json (preserving other settings).",
+    "If [PLATFORM_CONFIG_DIR]/settings.json already has PreToolUse hooks, the prototype guard is appended to the existing list.",
+    "The hook guards Write and Edit tool calls only. Bash commands that modify the filesystem are not intercepted -- the arness.md rules are the primary defense for those operations.",
+    "OpenCode.ai uses a built-in `tool.execute.before` handler in the arn-spark.js plugin instead of this hook. The handler reads protected paths from arness.md's `#### Protected Paths` section at runtime, so this hook template is only relevant for hook-based AI assistants.",
+    "The `tool.execute.before` handler in arn-spark.js covers both hook-based assistants and OpenCode -- if the user runs on OpenCode, the handler activates automatically. No manual hook installation needed."
+  ]
+}

package/plugins/arn-spark/skills/arn-spark-prototype-lock/references/prototype-guardrail-rules.md

@@ -0,0 +1,38 @@
+# Prototype Guardrail Rules Template
+
+This template defines the `### Prototype Lock` subsection written to the target project's `arness.md` by the `arn-spark-prototype-lock` skill. The skill substitutes project-specific paths into the placeholders before writing.
+
+## Placeholders
+
+- `__LOCK_DATE__` -- date the lock was created
+- `__LOCK_TAG__` -- git tag name (or "none")
+- `__LOCKED_DIR__` -- path to the locked directory (e.g., `.arness/prototypes/locked/`)
+- `__CLICKABLE_VERSION__` -- e.g., `clickable/v3/`
+- `__STATIC_VERSION__` -- e.g., `static/v4/`
+- `__PROTOTYPES_DIR__` -- base prototypes directory (e.g., `.arness/prototypes`)
+
+## Template
+
+```markdown
+### Prototype Lock
+- **Locked:** yes
+- **Lock date:** __LOCK_DATE__
+- **Lock tag:** __LOCK_TAG__
+- **Locked directory:** __LOCKED_DIR__
+
+#### Protected Paths
+DO NOT modify, delete, or overwrite any files under these paths. They contain the validated prototype reference artifact:
+- `__LOCKED_DIR__` -- frozen prototype snapshots (independently buildable)
+- `__PROTOTYPES_DIR__/__CLICKABLE_VERSION__` -- original validated clickable prototype
+- `__PROTOTYPES_DIR__/__STATIC_VERSION__` -- original validated static prototype
+- `__PROTOTYPES_DIR__/criteria.md` -- agreed validation criteria
+- `__PROTOTYPES_DIR__/*/final-report.md` -- complete validation history
+- `__PROTOTYPES_DIR__/*/v*/review-report.md` -- version review reports
+- `__PROTOTYPES_DIR__/*/v*/judge-report.md` -- judge verdicts
+- `__PROTOTYPES_DIR__/*/v*/showcase/` -- visual showcase assets
+- `__PROTOTYPES_DIR__/*/v*/journeys/` -- journey test screenshots
+
+Any agent or skill that attempts to modify these files is operating incorrectly. The prototype is a reference artifact, not a working codebase. When implementing features, build in the project's source directories -- never in the prototype directories.
+
+To view the locked prototype: see `__LOCKED_DIR__/LOCKED.md` for build and serve instructions.
+```

package/plugins/arn-spark/skills/arn-spark-report/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: arn-spark-report
+description: >-
+  This skill should be used when the user says "spark report", "report spark issue",
+  "spark broke", "arn-spark-report", "greenfield issue", "report greenfield problem",
+  "report spark problem", "diagnose spark", "spark doctor",
+  "spark bug", "spark not working",
+  or wants to report a problem with an Arness Spark workflow skill.
+  Invokes the arn-spark-doctor agent to diagnose the issue, then files a GitHub
+  issue on the Arness plugin repository. Do NOT use this for filing issues on the
+  user's own project — use /arn-code-create-issue for that.
+version: 1.0.0
+---
+
+# Arness Spark Report
+
+Report an Arness Spark workflow issue by running a diagnostic and filing a GitHub issue on the Arness plugin repository. The arn-spark-doctor agent analyzes Spark configuration and behavior — it never reads project source code or business logic.
+
+## Workflow
+
+### Step 0: Smart Routing
+
+Before proceeding, check whether the user's issue actually belongs to a different Arness plugin:
+
+1. Read the `## Arness` section from the project's arness.md (if it exists).
+2. Check the user's description for keyword signals:
+   - **Code keywords:** "plan", "spec", "execute", "taskify", "swift", "standard", "batch", "ship", "PR", "review-pr", "assess", "catch-up", "document-project", "save-plan"
+   - **Infra keywords:** "deploy", "Dockerfile", "container", "IaC", "terraform", "pipeline", "CI/CD", "environment", "secrets", "monitor", "infrastructure"
+3. If Code signals detected: "This sounds like an Arness Code issue. Run `/arn-code-report` instead."
+4. If Infra signals detected: "This sounds like an Arness Infra issue. Run `/arn-infra-report` instead."
+5. If the user confirms it is actually a Spark issue, proceed.
+
+---
+
+### Step 1: Explain the Process
+
+Inform the user:
+
+"I'll help you report an Arness Spark workflow issue. Here's how this works:
+1. You describe what happened — which skill you used and what went wrong
+2. I'll run a diagnostic that checks Spark's configuration and expected behavior (I won't read your project code)
+3. You'll review the issue report before it's submitted
+4. The issue gets filed on the Arness plugin repository for the maintainers
+
+Your project code and business logic are never included in the report."
+
+---
+
+### Step 2: Gather User Description
+
+Ask the user to describe the issue (free-form text, not a multi-choice question — this is open-ended):
+
+"What happened? Which Arness Spark skill were you using and what went wrong?"
+
+Let the user type a free-form description. This becomes the `user_description` for the diagnostic.
+
+---
+
+### Step 3: Check Prerequisites
+
+1. Detect the plugin's GitHub repository:
+   - Read the `repository` field from [PLATFORM_PLUGIN_METADATA]. Parse `owner/repo` from the URL.
+   - Fallback: `git -C ${CLAUDE_PLUGIN_ROOT} remote get-url origin`. Extract `owner/repo` from the URL (strip `.git` suffix and `https://github.com/` or `git@github.com:` prefix).
+
+2. Check `gh auth status` — user must be authenticated to file issues.
+
+3. Read plugin version — use [PLATFORM_PLUGIN_METADATA] to read plugin version.
+
+4. Read `## Arness` config from the project's arness.md (if it exists).
+
+If GitHub access is not available, offer an alternative: generate the diagnostic report as a local file (`arness-spark-report-<YYYY-MM-DD>.md` in the project root) the user can manually submit.
+
+---
+
+### Step 4: Invoke arn-spark-doctor
+
+Spawn the `arn-spark-doctor` agent via the Task tool, passing the model from `.arness/agent-models/spark.md` as the `model` parameter (see `plugins/arn-spark/skills/arn-spark-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:
+- The user's description of the issue
+- Project root path
+- `## Arness` config content (or "not configured")
+- Plugin version
+- Instruction to read the knowledge base at `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-report/references/spark-knowledge-base.md`
+
+Wait for the agent to complete and collect the diagnostic report.
+
+---
+
+### Step 5: Compose and Review Issue
+
+Assemble the GitHub issue using the template from `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-report/references/issue-template.md`:
+- Include the user's original description in the "User Report" section
+- Include the doctor's diagnostic findings (ISSUE items only, not OK items)
+- Include the doctor's assessment
+- Include plugin version and relevant config state
+- Include environment info (OS, Git, GitHub, gh CLI, Node.js, Playwright status)
+- Exclude any project code or business logic
+
+Present the complete draft to the user, then request explicit consent.
+
+Ask the user:
+
+> **This report will be filed as a public GitHub issue on the Arness repository.** It contains only Arness configuration state and diagnostic findings — no project source code or business logic. Please review the report above carefully.
+>
+> 1. Submit — I've reviewed it and consent to filing this publicly
+> 2. Save locally — save as a file instead of submitting
+> 3. Edit first — let me modify the report before deciding
+
+- If **Submit**: proceed to Step 6.
+- If **Save locally**: save as `arness-spark-report-<YYYY-MM-DD>.md` in the project root. Inform the user. Do not submit.
+- If **Edit first**: let the user modify the draft, then ask again.
+
+---
+
+### Step 6: Submit Issue
+
+The `arn-spark-report` label must already exist on the plugin repository (maintained by the plugin maintainers, not created by this skill).
+
+1. Create the issue with the `arn-spark-report` label:
+   ```bash
+   gh issue create --repo <owner/repo> --title "<title>" --body "<body>" --label "arn-spark-report"
+   ```
+
+2. If the command fails because the label does not exist, retry without `--label` and inform the user that the issue was filed without a label.
+
+3. Report the issue URL to the user.
+
+If submission fails for other reasons (permissions, network), save the report as `arness-spark-report-<YYYY-MM-DD>.md` in the project root and inform the user with instructions to submit manually.
+
+## Error Handling
+
+- **Plugin not installed from GitHub** — no git remote found in plugin root and no `repository` field in plugin.json. Generate report as `arness-spark-report-<YYYY-MM-DD>.md` in the project root instead.
+- **`gh` not authenticated** — suggest `gh auth login`, offer local file fallback (`arness-spark-report-<YYYY-MM-DD>.md`).
+- **User lacks permission to file issues on plugin repo** — save report as `arness-spark-report-<YYYY-MM-DD>.md` in the project root, suggest opening manually.
+- **arn-spark-doctor agent fails** — report the failure, offer to file a minimal issue with just the user's description.
+- **`## Arness` config missing** — proceed anyway, note "not configured" in the report.
+- **`arn-spark-report` label missing from plugin repo** — retry without `--label`, note this in the output.
+
+## Constraints
+
+- **Allowed tools:** Read, Glob, Grep, Bash, Agent (for arn-spark-doctor)
+- **NEVER** include project source code, business logic, or sensitive data in the report
+- **NEVER** file issues on the user's own project repository — this skill only files on the Arness plugin repository
+- **ALWAYS** present the full report draft and obtain explicit user consent before submitting
+- **ALWAYS** offer a local-file alternative — the user must never be forced to submit publicly

package/plugins/arn-spark/skills/arn-spark-report/references/issue-template.md

@@ -0,0 +1,81 @@
+# Issue Report Template
+
+Template for GitHub issues created by `/arn-spark-report`. The skill assembles this template with data from the user's description and the arn-spark-doctor agent's diagnostic findings.
+
+## Template Format
+
+The issue body follows this structure:
+
+```markdown
+## Arness Spark Report
+
+**Plugin version:** <version from plugin.json>
+**Skill(s) involved:** <skill names identified by the arn-spark-doctor diagnostic>
+
+### User Report
+
+> <user's original description of the issue, quoted verbatim>
+
+### Diagnostic Findings
+
+<arn-spark-doctor's findings — only ISSUE items, not OK items>
+
+### Assessment
+
+<arn-spark-doctor's root cause assessment — 1-3 sentences>
+
+### Config State
+
+\```
+<relevant ## Arness Spark fields from the project's arness.md, or "Arness Spark not configured">
+\```
+
+### Environment
+
+- **OS:** <detected via uname or "unknown">
+- **Git:** <yes/no>
+- **GitHub:** <yes/no>
+- **gh CLI:** <authenticated/not authenticated/not installed>
+- **Node.js:** <version or not installed>
+- **Playwright:** <available/not available>
+
+---
+*Filed via `/arn-spark-report` — Arness Spark v<version>*
+```
+
+## Issue Title Format
+
+Use a concise title derived from the doctor's assessment:
+
+`[arn-spark-report] <skill name>: <brief issue summary>`
+
+Examples:
+- `[arn-spark-report] arn-spark-discover: product concept not saved after discovery`
+- `[arn-spark-report] arn-spark-naming: WHOIS check fails with timeout`
+- `[arn-spark-report] arn-spark-clickable-prototype: Playwright journey test crashes`
+
+## Privacy Guidelines
+
+The issue MUST NOT include:
+- Project source code or file contents
+- Business logic or domain-specific data
+- File paths outside of Arness configuration directories
+- User credentials, tokens, or authentication details
+- Any information that could identify the user's project
+
+The issue SHOULD include:
+- Arness Spark configuration state (## Arness fields)
+- Directory existence checks (exists/missing, not contents)
+- Skill names and pipeline stage where the issue occurred
+- Error messages related to Arness Spark workflow behavior
+- Plugin version and environment information
+
+## Labels
+
+The `arn-spark-report` label is applied automatically. This label must be pre-created on the plugin repository by maintainers — the skill does not create it.
+
+## Notes
+
+- The user ALWAYS reviews and approves the issue before submission
+- If the user edits the draft, use their edited version
+- If submission fails, save the report as a local markdown file