/arn-spark-scaffold

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 `CLAUDE.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 (using `AskUserQuestion`):

**"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. Check `.claude/arness-profile.local.md` first (project override takes precedence), then `~/.arness/user-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 (using `AskUserQuestion`):

**"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) —