@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-scaffold/references/scaffold-summary-template.md

@@ -0,0 +1,74 @@
+# Scaffold Summary Template
+
+This template defines the structure for the scaffold summary document written by the `arn-spark-scaffold` skill after a successful scaffolding. The document is saved to the project's Vision directory as `scaffold-summary.md`.
+
+A scaffold summary records the full technology stack including UI toolkit decisions made during scaffolding. The architecture vision captures high-level technology choices, but CSS framework, component library, and icon library are decided during scaffolding. Downstream skills (style-explore, static-prototype, clickable-prototype, feature-extract) need this information to make informed decisions.
+
+## Instructions for arn-spark-scaffold
+
+When populating this template:
+
+- Fill in all sections from the scaffold results and UI toolkit decisions
+- Version numbers should reflect what was actually installed, not what was planned
+- Commands should be copy-pasteable — no placeholders
+- If a layer was not applicable (e.g., no icon library), omit it from the table
+- The Pillar Alignment section should only appear if product pillars exist
+
+---
+
+## Template
+
+```markdown
+# [Product Name] - Scaffold Summary
+
+## Technology Stack
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Application framework | [value] | [version] |
+| UI framework | [value] | [version] |
+| Language | [value] | [version] |
+| CSS framework | [value] | [version] |
+| Component library | [value] | [version] |
+| Icon library | [value or "none"] | [version] |
+| Build tool | [value] | [version] |
+| Package manager | [value] | [version] |
+| Test framework | [value] | [version] |
+| Linter/formatter | [value] | [version] |
+
+## Pillar Alignment
+
+[Only include if product pillars exist. Assess how the UI toolkit decisions (CSS framework, component library) serve each pillar.]
+
+| Pillar | Status | How the Toolkit Serves It |
+|--------|--------|--------------------------|
+| [Pillar name] | Supported / At Risk | [Specific explanation referencing the CSS framework, component library, or icon library choice.] |
+
+## Key Files
+
+[List the important configuration and entry point files created during scaffolding, grouped by category.]
+
+**Configuration:**
+- [file path] — [brief purpose]
+
+**Entry points:**
+- [file path] — [brief purpose]
+
+**UI toolkit:**
+- [file path] — [brief purpose, e.g., "Tailwind config with content paths"]
+
+## Commands
+
+| Action | Command |
+|--------|---------|
+| Dev server | `[command]` |
+| Build | `[command]` |
+| Test | `[command]` |
+| Lint | `[command]` |
+
+## Build Verification
+
+- **Build result:** [pass/fail]
+- **Warnings:** [any warnings, or "none"]
+- **Issues resolved during scaffolding:** [any problems encountered and how they were fixed, or "none"]
+```

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

@@ -0,0 +1,209 @@
+---
+name: arn-spark-spike
+description: >-
+  This skill should be used when the user says "spike", "arn spike",
+  "validate risks", "technical validation", "proof of concept",
+  "validate architecture", "risk spike", "test this risk", "will this work",
+  "technical spike", "validate the stack", or wants to validate critical
+  technical risks from the architecture vision by creating minimal
+  proof-of-concept code and testing whether the chosen technologies work as
+  expected.
+version: 1.0.0
+---
+
+# Arness Spike
+
+Validate critical technical risks from the architecture vision through minimal proof-of-concept implementations, aided by the `arn-spark-spike-runner` agent for POC creation and execution. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifacts are **spike POC code** in isolated directories and a **spike results document**.
+
+This skill addresses the question: "Will the chosen technologies actually work for our use case?" It does not implement features or build the application -- it runs targeted experiments to validate or invalidate specific technical assumptions before committing to them.
+
+## Prerequisites
+
+An architecture vision document should exist. Check in order:
+
+1. Read the project's `arness.md` for a `## Arness` section. If found, check the configured Vision directory for `architecture-vision.md`
+2. If no `## Arness` section found, check `.arness/vision/architecture-vision.md` at the project root
+
+**If an architecture vision is found:** Read it and extract the "Known Risks & Mitigations" section.
+
+**If no architecture vision is found:** Inform the user:
+
+"No architecture vision document found. I can still run spikes if you describe the specific technical risks to validate. For a comprehensive risk assessment, run `/arn-spark-arch-vision` first."
+
+If the user provides risks directly, proceed with those.
+
+The project should ideally be scaffolded (via `/arn-spark-scaffold`) so the spike runner can leverage the existing project setup. If not scaffolded, spikes will need to set up their own dependencies, which the spike runner handles.
+
+Determine the spike workspace:
+1. Read the project's `arness.md` and check for a `## Arness` section
+2. If found, extract the configured Spikes directory path — this is the source of truth
+3. 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.
+4. If the directory does not exist, create it
+
+## Workflow
+
+### Step 1: Identify Risks
+
+Load the architecture vision and extract all risks from the "Known Risks & Mitigations" section. Parse each risk to identify:
+
+- **Risk title:** Brief name
+- **Description:** What could go wrong
+- **Validation priority:** Critical (must validate before any code), Important (validate in first sprint), Monitor (keep an eye on)
+- **Suggested mitigation:** What the architecture vision proposes as a fallback
+
+If additional validation points were noted in the tech evaluator's recommendations during the architecture vision phase, include those as well.
+
+Present the risk list to the user:
+
+"I found [N] risks in your architecture vision. Here they are by priority:
+
+**Critical:**
+1. [Risk title] -- [brief description]
+2. [Risk title] -- [brief description]
+
+**Important:**
+3. [Risk title] -- [brief description]
+
+**Monitor:**
+4. [Risk title] -- [brief description]
+
+Ask the user with `multiSelect: true`:
+
+**"Which risks would you like to spike? (select multiple)"**
+
+Options:
+[List each risk as a numbered option with its title and brief description, e.g.:]
+1. **[Risk 1 title]** — [brief description]
+2. **[Risk 2 title]** — [brief description]
+3. **[Risk 3 title]** — [brief description]
+
+If the user adds custom risks not from the architecture vision, include those.
+
+### Step 2: Define Validation Criteria (Per Risk)
+
+For each selected risk, propose a minimal POC approach and clear validation criteria:
+
+"For **[Risk Title]**:
+
+**POC approach:** [What we will build to test this. 1-2 sentences describing the minimal experiment.]
+
+**Validation criteria:**
+- [Specific, measurable criterion 1]
+- [Specific, measurable criterion 2]
+
+**Spike directory:** `<configured Spikes directory>/spike-[NNN]-[descriptive-name]/`
+
+Does this approach look right, or would you test it differently?"
+
+Wait for user approval or adjustments before running each spike. The user may want to modify the approach, change criteria, or skip the risk.
+
+### Step 3: Execute Spikes
+
+**IMPORTANT: Run spikes sequentially, one at a time.** Do NOT launch multiple spike-runner agents in parallel or in the background. The spike-runner agent needs Bash and Write tool access, which requires user permission approval. Parallel or background agents cannot surface permission prompts to the user, causing all tool calls to be denied. Wait for each spike to fully complete before starting the next one.
+
+For each approved spike, in order:
+
+1. Invoke the `arn-spark-spike-runner` agent via the Task tool (foreground, not background), 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:
+   - Risk description and context
+   - Validation criteria
+   - Project context (stack, existing scaffold location)
+   - Spike workspace path (e.g., `<Spikes directory>/spike-001-webrtc-wkwebview/`)
+
+2. Wait for the agent to complete fully before proceeding.
+
+3. Present the spike runner's results to the user:
+   - **Validated:** "Risk validated. [Brief evidence summary]. No architecture changes needed."
+   - **Partially Validated:** "Risk partially validated. [Caveats]. We should discuss whether these limitations are acceptable."
+   - **Failed:** "Risk failed validation. [Evidence]. Here are the alternatives the spike runner identified: [list]. How would you like to proceed?"
+   - **Deferred:** "Could not test this in the current environment. [What is needed]. The spike files and manual execution instructions are saved at `[spike directory]` -- you can run this spike manually on the required platform. This should be validated when [condition]."
+
+4. **If a spike failed:**
+
+   Ask the user:
+
+   **"Risk [Risk Title] failed validation. How would you like to proceed?"**
+
+   Options:
+   1. **Accept the risk** — Proceed anyway with the current approach
+   2. **Choose an alternative** — Discuss trade-offs and pick a different approach
+   3. **Update architecture vision** — Revise the architecture to address the failure
+
+5. Proceed to the next spike only after presenting results and resolving any failures.
+
+### Step 4: Write Spike Results Document
+
+After all spikes have been run:
+
+1. Read the spike report template:
+   > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-spike/references/spike-report-template.md`
+
+2. Populate the template with all spike results
+
+3. Determine the output directory:
+   - Read the project's `arness.md` and check for a `## Arness` section
+   - If found, extract the configured Vision directory path — this is the source of truth
+   - 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.
+
+4. Write the document as `spike-results.md`
+
+5. Present a summary:
+
+"Spike results saved to `[path]/spike-results.md`.
+
+**Summary:**
+| Risk | Result |
+|------|--------|
+| [Risk 1] | Validated |
+| [Risk 2] | Failed -- chose Alternative A |
+| [Risk 3] | Deferred -- needs macOS |
+
+[N] of [M] risks validated. [Note any architecture changes decided.]"
+
+### Step 5: Update Architecture Vision (If Needed)
+
+If any spikes failed and the user chose an alternative approach:
+
+"Based on the spike results, the following sections of `architecture-vision.md` should be updated:
+
+1. [Section]: [What to change and why]
+2. [Section]: [What to change and why]
+
+Ask the user:
+
+> **Should I update the architecture vision now?**
+> 1. **Yes** — Update the affected sections
+> 2. **No** — Skip for now, I will update manually later"
+
+If the user chooses **Yes**, make the targeted updates to the architecture vision document. Only change the specific sections affected by failed spikes -- do not rewrite the entire document.
+
+### Step 6: Recommend Next Steps
+
+"All spikes complete. Recommended next steps:
+
+1. **Explore visual style:** Run `/arn-spark-style-explore` to define the look and feel
+2. **Build static prototype:** Run `/arn-spark-static-prototype` to validate visual fidelity
+3. **Address deferred risks:** [List any deferred risks and when they should be revisited]"
+
+Adapt based on results. If critical risks failed and alternatives were chosen, emphasize the architecture changes. If risks were deferred, note when they should be revisited.
+
+## Agent Invocation Guide
+
+| Situation | Action |
+|-----------|--------|
+| Run an approved spike (Step 3) | Invoke `arn-spark-spike-runner` sequentially (foreground, not background) with risk details, criteria, and workspace path. Wait for completion before starting the next spike. |
+| Spike runner agent denied permissions | The agent likely failed because it ran in the background or in parallel. Re-run it in the foreground sequentially. If permissions are still denied, run the spike directly in the main conversation instead of delegating to the agent. |
+| User asks about technology alternatives | Answer from the architecture vision context or invoke `arn-spark-tech-evaluator` if deep comparison needed |
+| User wants to add a custom risk | Record it and proceed to Step 2 for that risk |
+| User asks about features or screens | Defer: "Feature work comes after risk validation. Next step after spikes is `/arn-spark-style-explore` or `/arn-spark-static-prototype`." |
+| Spike runner reports environment limitation | Record as deferred, continue to next spike |
+
+## Error Handling
+
+- **No risks found in architecture vision:** Ask the user if they have specific technical concerns to validate. If none, inform them: "No critical risks identified. You can proceed to `/arn-spark-style-explore` or `/arn-spark-static-prototype`."
+- **Spike cannot run in current environment:** The spike runner still creates all POC files and a README with manual execution instructions on disk. Mark as deferred with specific environment requirements. The user can run the spike manually on the required platform later. Continue to the next spike.
+- **Spike runner agent denied permissions (Bash/Write):** This happens when agents are launched in parallel or in the background -- permission prompts cannot reach the user. Re-run the spike in the foreground sequentially. If permissions are still denied, fall back to running the spike directly in the main conversation context (write POC files and run build/execute commands yourself rather than delegating to the agent).
+- **Spike fails repeatedly (3 times):** The spike runner will halt. Present the failure state to the user and ask how to proceed (skip, try different approach, or investigate manually).
+- **User disagrees with spike result:** Re-examine the evidence. If the user provides additional context, consider re-running with adjusted criteria.
+- **Writing the results document fails:** Print the full content in the conversation so the user can copy it. Suggest checking file permissions.
+- **Architecture vision update conflicts:** If the architecture vision was modified since it was read, re-read it before making changes. Present the diff to the user for confirmation.
+- **No project scaffold exists:** Spikes can still run -- the spike runner creates self-contained workspaces. Note that some spikes may need to install their own dependencies.

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

@@ -0,0 +1,123 @@
+# Spike Report Template
+
+This template defines the structure for spike result documents written by the `arn-spark-spike` skill. Individual spike results are collected and written to the project's vision directory as `spike-results.md`.
+
+A spike report captures the outcome of technical risk validation: what was tested, how it was tested, whether it passed, and what impact the result has on the architecture.
+
+## Instructions for arn-spark-spike
+
+When populating this template:
+
+- Create one report section per spike run
+- Replace all bracketed placeholders with concrete content from the spike execution
+- Evidence must be concrete: output logs, error messages, measurements, exit codes. "It worked" is not evidence.
+- If a spike was deferred (could not run in current environment), document what would need to be tested and the required environment
+- Impact assessment should reference specific sections of the architecture vision that are affected
+- Suggested alternatives are only needed for Failed or Partially Validated results
+
+---
+
+## Template
+
+```markdown
+# Spike Results
+
+Generated by `/arn-spark-spike` on [date].
+
+## Summary
+
+| # | Risk | Result | Priority | Impact |
+|---|------|--------|----------|--------|
+| [N] | [Brief risk description] | Validated / Partially Validated / Failed / Deferred | Critical / Important / Monitor | [One-line impact summary] |
+
+---
+
+## Spike [N]: [Risk Title]
+
+### Risk Description
+
+[What technical assumption was being validated. Be specific about the capability and the environment constraint.]
+
+### Priority
+
+[Critical / Important / Monitor] -- [Brief rationale for this priority level]
+
+### Validation Criteria
+
+[What would prove it works. Specific, measurable conditions that were agreed before the spike ran.]
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+
+### POC Approach
+
+[What was built to test this. Brief description of the proof-of-concept code, key files, and how it tests the risk.]
+
+**Spike directory:** `[path to spike workspace, e.g., spikes/spike-001-webrtc-wkwebview/]`
+
+### Result: [Validated / Partially Validated / Failed / Deferred]
+
+[1-3 sentence summary of the outcome.]
+
+### Evidence
+
+[Concrete evidence supporting the result. Include relevant output:]
+
+```
+[Terminal output, log excerpts, error messages, or measurements]
+```
+
+[If measurements were taken, present them in a table:]
+
+| Metric | Expected | Actual |
+|--------|----------|--------|
+| [metric] | [target] | [measured] |
+
+### Caveats
+
+[Any limitations, conditions, or assumptions in the validation. E.g., "Tested on Linux; macOS WKWebView behavior may differ." or "Tested with 2 peers; behavior at 5+ peers not validated."]
+
+### Impact on Architecture
+
+[How this result affects the architecture vision. Reference specific sections or decisions.]
+
+- **If Validated:** [Any implications discovered, or "No architecture changes needed."]
+- **If Partially Validated:** [What limitations must be accommodated. What section of the architecture vision should be updated.]
+- **If Failed:** [What needs to change in the architecture. Which decisions are affected.]
+
+### Suggested Alternatives
+
+[Only for Failed or Partially Validated results. 1-3 alternative approaches:]
+
+1. **[Alternative A]:** [Description. What changes in the architecture. What new risks it introduces.]
+2. **[Alternative B]:** [Description. Trade-offs compared to Alternative A.]
+
+---
+
+[Repeat for each spike]
+
+## Architecture Vision Updates
+
+[Summary of any changes needed to the architecture vision based on spike results. If no changes needed, state "No updates required -- all critical risks validated."]
+
+- [ ] [Specific update 1: section, what to change, why]
+- [ ] [Specific update 2: section, what to change, why]
+```
+
+---
+
+## Section Guidance
+
+| Section | Source | Depth |
+|---------|--------|-------|
+| Summary | Aggregated from all spikes | One row per spike, overview only |
+| Risk Description | Architecture vision "Known Risks" section + user input | 1-2 sentences, specific |
+| Validation Criteria | Agreed with user before spike runs | Checklist format, measurable |
+| POC Approach | arn-spark-spike-runner's report | 1 paragraph + file reference |
+| Result | arn-spark-spike-runner's assessment | One of four status values + summary |
+| Evidence | arn-spark-spike-runner's captured output | Code blocks with actual output |
+| Caveats | arn-spark-spike-runner's observations | Bullet list of limitations |
+| Impact on Architecture | Skill assessment after spike | Reference specific arch-vision sections |
+| Suggested Alternatives | arn-spark-spike-runner (if failed) + skill assessment | Numbered list with trade-offs |
+| Architecture Vision Updates | Aggregated from all spike impacts | Checklist of specific updates |