@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-report/references/spark-knowledge-base.md

@@ -0,0 +1,293 @@
+# Spark Knowledge Base
+
+Reference documentation for the `arn-spark-doctor` agent. Describes the Arness Spark plugin's pipeline, configuration requirements, expected file structures, common failure modes, and inter-skill data flow.
+
+## Pipeline Map
+
+### Main Pipeline (Brainstorming Wizard)
+
+```
+discover → stress-test → concept-review → naming → arch-vision → use-cases → scaffold → spike → visual-sketch → style-explore → static-prototype → clickable-prototype → prototype-lock → feature-extract
+```
+
+The `arn-brainstorming` wizard walks through this pipeline with decision gates, detecting progress and offering to resume at the correct stage.
+
+### Stress Testing Suite
+
+Four stress test skills run after discovery and before concept review:
+
+```
+discover → stress-interview ──┐
+         → stress-competitive ─┤
+         → stress-premortem ───┤ → concept-review
+         → stress-prfaq ───────┘
+```
+
+Stress tests can run in parallel and produce independent reports. Concept review synthesizes all available stress test findings.
+
+### Teams Variants
+
+- `arn-spark-use-cases-teams` — team debate variant of use case authoring
+- `arn-spark-static-prototype-teams` — team debate variant of static prototype validation
+- `arn-spark-clickable-prototype-teams` — team debate variant of clickable prototype validation
+
+### Standalone Skills
+
+- `arn-spark-dev-setup` — development environment setup (can run independently after scaffold)
+- `arn-spark-visual-strategy` — visual testing strategy with layered validation
+- `arn-spark-visual-readiness` — visual readiness checkpoint for deferred layer activation
+
+### Entry Point
+
+- `arn-brainstorming` — guided wizard that walks through the entire greenfield pipeline with decision gates, detects resume point
+
+## Config Requirements
+
+The `## Arness` section in arness.md includes Spark-specific fields. Each skill reads specific fields:
+
+| Skill | Vision dir | Use cases dir | Prototypes dir | Spikes dir | Visual grounding dir | Reports dir |
+|-------|-----------|---------------|---------------|------------|---------------------|-------------|
+| arn-spark-ensure-config | creates | creates | creates | creates | creates | creates |
+| arn-spark-discover | writes to | - | - | - | - | - |
+| arn-spark-stress-interview | reads (vision) | - | - | - | - | writes to |
+| arn-spark-stress-competitive | reads (vision) | - | - | - | - | writes to |
+| arn-spark-stress-premortem | reads (vision) | - | - | - | - | writes to |
+| arn-spark-stress-prfaq | reads (vision) | - | - | - | - | writes to |
+| arn-spark-concept-review | reads (vision) | - | - | - | - | writes to |
+| arn-spark-naming | reads (vision) | - | - | - | - | writes to |
+| arn-spark-arch-vision | reads (vision) | - | - | - | - | - |
+| arn-spark-use-cases | reads (vision) | writes to | - | - | - | - |
+| arn-spark-use-cases-teams | reads (vision) | writes to | - | - | - | - |
+| arn-spark-scaffold | reads (vision) | - | - | - | - | - |
+| arn-spark-spike | reads (vision) | - | - | reads/writes | - | - |
+| arn-spark-visual-sketch | reads (vision) | - | - | - | writes to | - |
+| arn-spark-style-explore | reads (vision) | - | - | - | writes to | - |
+| arn-spark-static-prototype | reads (vision) | - | reads/writes | - | writes to | - |
+| arn-spark-static-prototype-teams | reads (vision) | - | reads/writes | - | writes to | - |
+| arn-spark-clickable-prototype | reads (vision) | - | reads/writes | - | writes to | - |
+| arn-spark-clickable-prototype-teams | reads (vision) | - | reads/writes | - | writes to | - |
+| arn-spark-prototype-lock | - | - | reads | - | - | - |
+| arn-spark-feature-extract | reads (vision) | reads | reads | reads | reads | writes to |
+| arn-spark-visual-strategy | - | - | - | - | reads | - |
+| arn-spark-visual-readiness | - | - | - | - | reads | - |
+| arn-spark-dev-setup | - | - | - | - | - | - |
+| arn-brainstorming | all (via ensure-config) | all | all | all | all | all |
+
+## Expected ## Arness Config Format (Spark Fields)
+
+```markdown
+## Arness
+- **Vision directory:** <path>
+- **Use cases directory:** <path>
+- **Prototypes directory:** <path>
+- **Spikes directory:** <path>
+- **Visual grounding directory:** <path>
+- **Reports directory:** <path>
+```
+
+Default values (created by arn-spark-ensure-config): Vision directory = `.arness/vision`, Use cases directory = `.arness/use-cases`, Prototypes directory = `.arness/prototypes`, Spikes directory = `.arness/spikes`, Visual grounding directory = `.arness/visual-grounding`, Reports directory = `.arness/reports`.
+
+## Expected Directory/File Structure
+
+### After arn-spark-discover
+
+```
+<vision-dir>/
+└── product-concept.md
+```
+
+### After stress tests (one or more)
+
+```
+<reports-dir>/
+├── stress-interview-report.md     (from arn-spark-stress-interview)
+├── stress-competitive-report.md   (from arn-spark-stress-competitive)
+├── stress-premortem-report.md     (from arn-spark-stress-premortem)
+└── stress-prfaq-report.md         (from arn-spark-stress-prfaq)
+```
+
+### After arn-spark-concept-review
+
+```
+<vision-dir>/
+├── product-concept.md              (updated with approved changes)
+└── product-concept-pre-review.md   (backup of pre-review version)
+<reports-dir>/
+└── concept-review-report.md
+```
+
+### After arn-spark-naming
+
+```
+<vision-dir>/
+└── naming-brief.md                 (includes Final Decision section)
+<reports-dir>/
+└── naming-report.md
+```
+
+### After arn-spark-arch-vision
+
+```
+<vision-dir>/
+└── architecture-vision.md
+```
+
+### After arn-spark-scaffold
+
+```
+<project-root>/
+├── package.json (or equivalent)
+├── node_modules/ (or equivalent)
+├── src/ (or framework-specific structure)
+└── ... (framework scaffolded files)
+```
+
+### After arn-spark-prototype-lock
+
+```
+<prototypes-dir>/
+├── locked/                         (frozen prototype copy)
+│   └── ... (snapshot of prototype files)
+└── LOCKED.md                       (lock manifest with timestamp and git tag)
+```
+
+### After arn-spark-feature-extract
+
+```
+<reports-dir>/
+└── feature-backlog.md              (prioritized feature list with Feature Tracker)
+```
+
+## Common Failure Modes
+
+| Symptom | Likely Cause | Diagnostic Check |
+|---------|-------------|------------------|
+| product-concept.md not found after discovery | arn-spark-discover did not complete, or Vision directory misconfigured | Check `<vision-dir>/product-concept.md` exists |
+| Stress test reports not in expected directory | Reports directory misconfigured, or stress test did not complete | Check `<reports-dir>/` for `stress-*-report.md` files |
+| naming-brief.md incomplete (no Final Decision section) | Naming skill did not reach Step 4 (due diligence), or user exited early | Check `<vision-dir>/naming-brief.md` for "Final Decision" heading |
+| Scaffold fails (npm/yarn install errors, framework init fails) | Missing Node.js, wrong version, network issues, or framework CLI not available | Run `node --version`, `npm --version`, check network |
+| Playwright not available for prototyping | Playwright not installed or not in PATH | Run `npx playwright --version` |
+| Visual sketch server won't start | Scaffold not completed, dev server config broken, or port conflict | Check scaffold output exists, dev server is runnable |
+| Style brief not generated from visual direction | visual-direction.md missing in Vision directory, or style-explore did not complete | Check `<vision-dir>/visual-direction.md` exists |
+| Static/clickable prototype build fails | Missing dependencies, scaffold incomplete, or style tokens not applied | Check `node_modules/` exists, scaffold files present |
+| Feature extraction finds no upstream artifacts | No product concept, no use cases, no prototype validation reports | Check Vision, Use cases, Prototypes directories for expected files |
+| Visual testing layer activation fails | Visual grounding directory missing or empty, visual strategy not run | Check `<visual-grounding-dir>/` exists and contains assets |
+| Figma/Canva MCP not available | MCP server not configured for design tool integration | Check `.mcp.json` for design tool entries |
+| Use case files not in expected format | Use cases written manually instead of via arn-spark-use-cases skill | Check `<use-cases-dir>/` for `UC-*.md` pattern |
+| Prototype lock LOCKED.md missing | arn-spark-prototype-lock did not complete or Prototypes directory misconfigured | Check `<prototypes-dir>/LOCKED.md` exists |
+| Brainstorming wizard can't detect resume point | Artifacts in unexpected locations, config directories changed after initial run | Check all configured directories match where artifacts were actually written |
+| ensure-config fails to create Spark fields | arness.md not writable, or `## Arness` section has unexpected format | Check arness.md exists and is writable, check `## Arness` section format |
+
+## Inter-Skill Data Flow
+
+```
+arn-spark-ensure-config
+  outputs: ## Arness config in arness.md (Spark fields), directories created
+  consumed by: all other Spark skills read ## Arness config
+
+arn-spark-discover
+  outputs: product-concept.md in <vision-dir>/
+  consumed by: stress tests, concept-review, naming, arch-vision, use-cases,
+               scaffold (reads product pillars), feature-extract
+
+arn-spark-stress-interview
+  outputs: stress-interview-report.md in <reports-dir>/
+  consumed by: arn-spark-concept-review
+
+arn-spark-stress-competitive
+  outputs: stress-competitive-report.md in <reports-dir>/
+  consumed by: arn-spark-concept-review
+
+arn-spark-stress-premortem
+  outputs: stress-premortem-report.md in <reports-dir>/
+  consumed by: arn-spark-concept-review
+
+arn-spark-stress-prfaq
+  outputs: stress-prfaq-report.md in <reports-dir>/
+  consumed by: arn-spark-concept-review
+
+arn-spark-concept-review
+  outputs: updated product-concept.md, concept-review-report.md in <reports-dir>/
+  consumed by: downstream skills that read product-concept.md
+
+arn-spark-naming
+  outputs: naming-brief.md in <vision-dir>/, naming-report.md in <reports-dir>/
+  consumed by: scaffold (project name), arch-vision (brand context)
+
+arn-spark-arch-vision
+  outputs: architecture-vision.md in <vision-dir>/
+  consumed by: scaffold, spike, use-cases, feature-extract
+
+arn-spark-use-cases / arn-spark-use-cases-teams
+  outputs: UC-*.md files in <use-cases-dir>/
+  consumed by: static-prototype, clickable-prototype, feature-extract
+
+arn-spark-scaffold
+  outputs: buildable project skeleton at <project-root>/
+  consumed by: spike, visual-sketch, style-explore, static-prototype,
+               clickable-prototype, dev-setup
+
+arn-spark-spike
+  outputs: spike results in <spikes-dir>/
+  consumed by: visual-sketch (optional), feature-extract
+
+arn-spark-visual-sketch
+  outputs: visual-direction.md in <vision-dir>/, screenshots in <visual-grounding-dir>/
+  consumed by: style-explore
+
+arn-spark-style-explore
+  outputs: style-brief.md in <vision-dir>/, style tokens in <visual-grounding-dir>/
+  consumed by: static-prototype, clickable-prototype
+
+arn-spark-static-prototype / arn-spark-static-prototype-teams
+  outputs: prototype files in <prototypes-dir>/, validation reports in <reports-dir>/,
+           screenshots in <visual-grounding-dir>/
+  consumed by: clickable-prototype, prototype-lock, feature-extract
+
+arn-spark-clickable-prototype / arn-spark-clickable-prototype-teams
+  outputs: interactive prototype in <prototypes-dir>/, journey screenshots in
+           <visual-grounding-dir>/, validation reports in <reports-dir>/
+  consumed by: prototype-lock, feature-extract
+
+arn-spark-prototype-lock
+  outputs: locked/ directory in <prototypes-dir>/, LOCKED.md, git tag
+  consumed by: development phase (read-only reference)
+
+arn-spark-feature-extract
+  outputs: feature-backlog.md in <reports-dir>/, optional issue tracker uploads
+  consumed by: arn-code-feature-spec (bridges into Arness Code pipeline)
+
+arn-brainstorming (entry point)
+  inputs: detects current pipeline state from artifacts on disk
+  outputs: drives discover → ... → feature-extract
+  consumed by: user (full greenfield workflow)
+```
+
+## Version History
+
+### 1.0.0
+- Initial release: 19 skills + 13 agents for the greenfield exploration pipeline
+- Includes discover, arch-vision, use-cases, scaffold, spike, visual-sketch, style-explore, static-prototype, clickable-prototype, prototype-lock, feature-extract, dev-setup, visual-strategy, visual-readiness
+- Brainstorming wizard for guided pipeline traversal
+- Renamed from nova-green-* to arn-spark-* prefix
+
+### 1.1.0
+- AI-assisted discovery enrichment: product-concept sections, market-researcher + persona-architect agents
+- Stress testing suite: stress-interview, stress-competitive, stress-premortem, stress-prfaq
+- Concept review skill for synthesizing stress test findings
+- Brand naming skill with 4-step methodology, brand-strategist agent, WHOIS scripts
+
+### 2.0.0
+- Nova to Arness rebrand: all skills/agents renamed from nova-green-*/nova-spark-* to arn-spark-*
+- Directory convention changed from .nova/ to .arness/
+- Config section changed from ## Nova to ## Arness
+
+### 2.1.0
+- Progressive zero-config init: arn-spark-ensure-config for automatic setup
+- Deferred pattern docs, welcome/profile flow
+- Teams variants for use cases, static prototype, and clickable prototype
+
+## Version Information
+
+- Plugin version — read via [PLATFORM_PLUGIN_METADATA] (field: `version`)
+- Skill versions are in each SKILL.md frontmatter (field: `version`)

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

@@ -0,0 +1,239 @@
+---
+name: arn-spark-scaffold
+description: >-
+  This skill should be used when the user says "scaffold", "arn scaffold",
+  "set up the project", "create project", "initialize project",
+  "bootstrap project", "create the skeleton",
+  "install dependencies", "configure the project", or wants to create a working
+  project skeleton from architecture decisions with installed dependencies,
+  configured build tools, and a UI toolkit ready for development.
+version: 1.0.0
+---
+
+# Arness Scaffold
+
+Set up a working project skeleton from architecture vision decisions through guided conversation, aided by the `arn-spark-scaffolder` agent for project creation and optionally the `arn-spark-tech-evaluator` agent for UI toolkit comparisons. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifact is a **buildable project** with all dependencies installed and configured.
+
+This skill covers the initial project setup: framework scaffolding, dependency installation, build configuration, linting, and UI toolkit setup. It does not implement features, create screens, or write application logic -- those are handled by subsequent skills (`/arn-spark-spike`, `/arn-spark-style-explore`, `/arn-spark-static-prototype`, `/arn-spark-clickable-prototype`).
+
+## Prerequisites
+
+An architecture vision document must 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 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.
+3. If `## Arness` exists but no architecture vision found, check `.arness/vision/architecture-vision.md` at the project root
+
+**If an architecture vision is found:** Read it and proceed to Step 1.
+
+**If no architecture vision is found:** Inform the user:
+
+"No architecture vision document found. I recommend running `/arn-spark-arch-vision` first to define your technology stack. The scaffold needs to know which frameworks, build tools, and libraries to set up."
+
+Do not proceed without an architecture vision or explicit technology stack from the user.
+
+Determine the project root:
+1. The project root is the working directory unless the user specifies otherwise
+2. If the project root already contains a `package.json`, `Cargo.toml`, or similar, warn the user: "This directory already has a project manifest. Do you want to extend the existing project or start fresh in a subdirectory?"
+
+## Workflow
+
+### Step 1: Load Architecture Vision, Product Pillars, and Extract Stack Decisions
+
+Read the architecture vision document. Extract technology decisions for each layer:
+
+- **Application framework:** e.g., Tauri, Electron, plain web
+- **UI framework:** e.g., Svelte, React, Vue
+- **Language:** e.g., TypeScript, JavaScript
+- **Build tool:** e.g., Vite, webpack
+- **Package manager:** e.g., npm, pnpm, yarn, bun
+- **Test framework:** e.g., Vitest, Jest, Playwright
+- **Linter/formatter:** e.g., ESLint + Prettier, Biome
+
+Also load the product concept document (same Vision directory) and extract the **Product Pillars** section if it exists. Pillars guide UI toolkit decisions in Step 2 — for example, a "design fidelity" pillar means the component library must allow full visual customization, while a "simplicity" pillar favors pre-styled components with minimal configuration.
+
+Present the extracted stack and relevant pillars to the user:
+
+"Based on your architecture vision, here is the stack I will scaffold:
+
+| Layer | Technology |
+|-------|-----------|
+| Framework | [value] |
+| UI | [value] |
+| Build | [value] |
+| ... | ... |
+
+[If pillars found:] Your product pillars that will guide UI toolkit choices:
+- **[Pillar]:** [what it implies for CSS/component library decisions]
+- ...
+
+Ask the user:
+
+**"Does this stack look right?"**
+
+Options:
+1. **Yes, proceed** — Set up the project with this stack
+2. **Adjust** — I want to change something before proceeding"
+
+### Step 2: UI Toolkit Decisions
+
+The architecture vision defines the high-level UI framework (e.g., Svelte) but typically does not specify the CSS approach and component library. These decisions happen now because they affect the scaffold setup and all subsequent work (style exploration, prototyping, production code).
+
+When product pillars are available, annotate each option with how it serves or challenges the pillars. This helps the user make an informed choice aligned with their product's non-negotiable qualities.
+
+**Profile-aware recommendations:** Read user profile from `.arness/profile.yaml`. Also check `.arness/preferences.yaml` for project-level team preferences. If the user lists specific frameworks (e.g., "React"), suggest compatible component libraries the user likely knows. If `development_experience: learning`, favor pre-styled libraries (DaisyUI, Chakra) over headless ones (shadcn, Radix) -- pre-styled libraries have less configuration overhead and visible results faster. If `development_experience: non-technical`, favor the most mainstream option with the largest community and most tutorials. Apply the advisory pattern for all toolkit recommendations: present the technically optimal recommendation first, then a preference-aligned alternative with pros/cons if they differ.
+
+Ask the user about each:
+
+**CSS approach:**
+
+Ask the user:
+
+**"Which CSS framework should we use?"**
+
+Offer common options for the chosen UI framework, noting pillar alignment where relevant. For example, for Svelte with a "design fidelity" pillar:
+
+Options:
+1. **Tailwind CSS** (most popular, utility-first) — Supports design fidelity: fine-grained control over every visual detail
+2. **UnoCSS** (similar to Tailwind, faster build) — Same control as Tailwind, lighter toolchain
+3. **CSS Modules** (scoped styles, no utility framework) — Maximum control but more manual effort
+4. **Vanilla CSS** (no framework, component-scoped styles) — Full freedom but no utility shortcuts
+
+**Component library:**
+
+Ask the user:
+
+**"Which component library should we use?"**
+
+Offer common options for the chosen UI framework + CSS approach, noting pillar alignment. For example, for Svelte + Tailwind with a "design fidelity" pillar:
+
+Options:
+1. **shadcn-svelte** (headless components, fully customizable) — Strong pillar fit: unstyled primitives give complete visual control
+2. **Skeleton UI** (Svelte-native, Tailwind-based) — Moderate: customizable but has opinionated defaults
+3. **DaisyUI** (Tailwind plugin, pre-styled) — Pillar risk: pre-styled components may conflict with custom design direction
+4. **None** (build custom components) — Maximum control, highest effort
+
+Note: Limit to 4 options. If more options exist, group or prioritize based on the chosen framework.
+
+**Icon library (optional):**
+
+Ask the user:
+
+**"Do you want an icon library?"**
+
+Options:
+1. **Lucide** — Clean, consistent, popular
+2. **Heroicons** — From the Tailwind team
+3. **None** — Add later if needed
+
+If the user is unsure about CSS or component library choices, invoke the `arn-spark-tech-evaluator` agent with a head-to-head comparison request for the specific options — include the product pillars so the evaluator can assess pillar alignment. Present the comparison and let the user decide.
+
+Record all UI toolkit decisions for the scaffolder.
+
+### Step 3: Invoke Scaffolder
+
+Invoke the `arn-spark-scaffolder` 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:
+
+- All stack decisions from Step 1 (framework, UI, build, package manager, test, linter)
+- All UI toolkit decisions from Step 2 (CSS framework, component library, icon library)
+- Project root path
+- Any configuration preferences the user mentioned
+
+The agent creates the project structure, installs dependencies, configures build tools, sets up the UI toolkit, creates a minimal entry point, and runs the build to verify.
+
+**Staging behavior:** When using official project creation tools (npm create, etc.), the scaffolder uses a `_scaffold-staging/` subdirectory to avoid overwriting existing project content (`.arness/`, `arness.md`, `.git/`, and any other files already present). Generated files are merged into the project root after creation, skipping any that already exist. The staging directory is removed after a successful merge. On failure, the staging directory is left in place so the user can inspect it.
+
+### Step 4: Verify the Scaffold
+
+After the scaffolder reports completion, verify using the scaffold checklist:
+
+> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-scaffold/references/scaffold-checklist.md`
+
+Walk through all checklist categories:
+
+1. **Project structure:** Key directories exist (src/, tests/, config files)
+2. **Dependency management:** Package manifest exists, dependencies installed without errors, lock file present
+3. **Build configuration:** Build tool configured, compiles or bundles without errors
+4. **Linting and formatting:** Linter and formatter configured, run without errors on the minimal code
+5. **Testing framework:** Test runner configured and executes (even with zero tests)
+6. **UI toolkit:** CSS framework configured, component library initialized, a component renders
+7. **Git configuration:** .gitignore is appropriate for the stack
+8. **Minimal entry point:** App starts and renders something visible
+9. **Run instructions:** Dev server, build, test, and lint commands documented
+
+For any failed checks:
+- Critical failures (build broken, dependencies not installed): Ask the scaffolder to fix
+- Non-critical gaps (missing .gitignore entry): Note for the user
+
+### Step 5: Write Scaffold Summary
+
+Write a scaffold summary document so downstream skills have a record of the full technology stack including UI toolkit decisions made during scaffolding.
+
+1. Read the template:
+   > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-scaffold/references/scaffold-summary-template.md`
+
+2. Populate the template with the scaffolding results:
+   - Technology stack with actual installed versions (from the scaffolder's report)
+   - UI toolkit decisions from Step 2 (CSS framework, component library, icon library)
+   - Pillar alignment assessment (if product pillars exist)
+   - Key files created
+   - Commands
+   - Build verification result
+
+3. Determine the output directory:
+   - Read the project's `arness.md` for the configured Vision directory
+   - If not found, use `.arness/vision` at the project root
+   - Create the directory if it does not exist
+
+4. Write the document to the Vision directory as `scaffold-summary.md`
+
+### Step 6: Present Results and Recommend Next Steps
+
+Present what was created:
+
+"Project scaffolded successfully. Here is what was set up:
+
+**Stack:**
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| ... | ... | ... |
+
+**Key files created:**
+- [list of important configuration and entry point files]
+
+**Commands:**
+- Dev server: `[command]`
+- Build: `[command]`
+- Test: `[command]`
+- Lint: `[command]`
+
+**Build result:** [pass/fail]
+
+Scaffold summary saved to `[path]/scaffold-summary.md`.
+
+Recommended next steps:
+1. **Set up development environment:** Run `/arn-spark-dev-setup` to configure setup scripts, CI, dev containers, and developer onboarding
+2. **Validate critical risks:** Run `/arn-spark-spike` to test technical risks from your architecture vision
+3. **Explore visual style:** Run `/arn-spark-style-explore` to define the look and feel"
+
+Adapt next steps based on context. If the architecture vision identified critical risks, emphasize spiking first. If the user is eager to see UI, suggest style exploration.
+
+## Agent Invocation Guide
+
+| Situation | Action |
+|-----------|--------|
+| Initial scaffold (Step 3) | Invoke `arn-spark-scaffolder` with full stack + UI toolkit decisions |
+| User unsure about CSS framework | Invoke `arn-spark-tech-evaluator` with comparison request |
+| User unsure about component library | Invoke `arn-spark-tech-evaluator` with comparison request |
+| User asks about code patterns | Defer: "Code patterns will be established when features are built. The scaffold just sets up the foundation." |
+| User asks about features or screens | Defer: "Features come after the scaffold. Next steps are `/arn-spark-spike` or `/arn-spark-style-explore`." |
+| Build fails after scaffold | Ask `arn-spark-scaffolder` to diagnose and fix |
+
+## Error Handling
+
+- **Architecture vision not found:** Cannot proceed. Suggest `/arn-spark-arch-vision` first.
+- **Project directory already has code:** Warn the user. Offer to extend the existing project or scaffold in a subdirectory.
+- **Scaffold build fails:** Report the error. Invoke scaffolder to fix. If it fails after 3 attempts, present the error and suggest the user investigate manually.
+- **Dependency installation fails:** Check network connectivity. Report the specific package that failed. Suggest the user try installing it manually.
+- **UI toolkit comparison requested but arn-spark-tech-evaluator unavailable:** Provide a brief comparison from general knowledge and note that it was not verified via web search.
+- **User cancels mid-scaffold:** Note what was completed. The user can re-run `/arn-spark-scaffold` to continue or start fresh.

package/plugins/arn-spark/skills/arn-spark-scaffold/references/scaffold-checklist.md

@@ -0,0 +1,79 @@
+# Scaffold Checklist
+
+This checklist defines what a properly scaffolded project should have. The `arn-spark-scaffold` skill uses it to verify completeness after the `arn-spark-scaffolder` agent finishes. Items are framework-agnostic -- adapt specifics to the chosen stack.
+
+## Verification Categories
+
+### 1. Project Structure
+
+- [ ] Root directory exists with the project name or at the specified path
+- [ ] `src/` directory (or framework equivalent) exists for application source code
+- [ ] Entry point file exists (e.g., `src/main.ts`, `src/App.svelte`, `src/index.tsx`)
+- [ ] Static assets directory exists if applicable (e.g., `public/`, `static/`)
+- [ ] Test directory exists (e.g., `tests/`, `test/`, `__tests__/`)
+
+### 2. Dependency Management
+
+- [ ] Package manifest exists (e.g., `package.json`, `Cargo.toml`)
+- [ ] Lock file exists (e.g., `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`)
+- [ ] Core framework dependencies are installed (not just listed)
+- [ ] Development dependencies are installed (linter, formatter, test framework)
+- [ ] No missing peer dependencies (check install output for warnings)
+
+### 3. Build Configuration
+
+- [ ] Build tool configuration exists (e.g., `vite.config.ts`, `webpack.config.js`, `tauri.conf.json`)
+- [ ] TypeScript configuration exists if using TypeScript (`tsconfig.json`)
+- [ ] Build command runs without errors
+- [ ] Development server starts without errors (if applicable)
+
+### 4. Linting and Formatting
+
+- [ ] Linter configuration exists (e.g., `eslint.config.js`, `.eslintrc`, `biome.json`)
+- [ ] Formatter configuration exists (e.g., `.prettierrc`, integrated in biome/eslint)
+- [ ] Linter runs on the minimal source code without errors
+- [ ] Formatter runs without errors
+
+### 5. Testing Framework
+
+- [ ] Test framework is installed and configured
+- [ ] Test command is defined in package scripts or is runnable
+- [ ] A sample or smoke test can be executed (even if there are no real tests yet)
+- [ ] Test configuration exists if needed (e.g., `vitest.config.ts`, `jest.config.js`)
+
+### 6. UI Toolkit (if applicable)
+
+- [ ] CSS framework is installed and configured (e.g., Tailwind CSS with `tailwind.config.js`)
+- [ ] CSS framework directives are included in the global stylesheet (e.g., `@tailwind base;`)
+- [ ] PostCSS is configured if required by the CSS framework
+- [ ] Component library is installed and initialized (e.g., shadcn-svelte, Skeleton UI)
+- [ ] Component library theme or base configuration is in place
+- [ ] A component library component renders correctly in the minimal entry point
+
+### 7. Git Configuration
+
+- [ ] `.gitignore` exists with appropriate entries for the stack (node_modules, dist, build artifacts, OS files)
+- [ ] No sensitive files or large binaries are unignored
+
+### 8. Minimal Entry Point
+
+- [ ] Application renders something visible (text, a component, a styled element)
+- [ ] Entry point uses the UI framework (not just raw HTML)
+- [ ] If a component library is installed, at least one component is used to verify integration
+- [ ] The entry point is intentionally minimal -- no features beyond proving the stack works
+
+### 9. Run Instructions
+
+- [ ] Development server command is clear (e.g., `npm run dev`, `cargo tauri dev`)
+- [ ] Build command is clear (e.g., `npm run build`, `cargo tauri build`)
+- [ ] Test command is clear (e.g., `npm test`, `npx vitest`)
+
+## How to Use This Checklist
+
+The `arn-spark-scaffold` skill should:
+
+1. After the `arn-spark-scaffolder` agent reports completion, walk through each applicable category
+2. Skip categories that do not apply to the chosen stack (e.g., skip "UI Toolkit" for a CLI project)
+3. For each failed check, note it as an issue in the scaffold summary
+4. Critical failures (build does not pass, dependencies not installed) should be addressed before proceeding
+5. Non-critical gaps (missing .gitignore entry, no sample test) can be noted for the user to address later