/arn-spark-dev-setup

name: arn-spark-dev-setup
description: >-
  This skill should be used when the user says "dev setup", "arn spark dev setup",
  "development environment", "configure dev environment", "dev container",
  "configure CI", "set up CI", "onboard developer", "developer setup",
  "set up docker", "configure development", "how do I set up this project",
  "development setup", "onboard me", "get this project running", "set up my
  machine", "new developer setup", "how do I get started", "developer
  onboarding", or wants to define a standardized development environment for
  their project (producing dev environment infrastructure files and a dev-setup
  document) or follow an existing environment standard to get onboarded as a
  new developer.
version: 1.0.0

Arness Dev Setup

Define or follow a standardized development environment through guided conversation, aided by the `arn-spark-dev-env-builder` agent for file generation and optionally the `arn-spark-tech-evaluator` agent for environment comparisons. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifacts are **development environment infrastructure files** (setup scripts, container configs, CI workflows, toolchain pins) and a **dev-setup document**.

This skill covers the development environment: how developers get the project running on their machines, how CI builds and tests, and how toolchain versions are pinned for reproducibility. It does not create project source code (that is `/arn-spark-scaffold`) or validate technical risks (that is `/arn-spark-spike`).

This skill operates in two modes:

• **Define mode:** An architect or project lead defines the standard development environment. The skill asks questions, generates infrastructure files, writes a dev-setup document, and stores configuration in CLAUDE.md.
• **Onboard mode:** A developer joining the project follows the existing standard. The skill reads the configuration from CLAUDE.md, presents the setup steps, and guides the developer through the process.

Prerequisites

The following artifacts inform the development environment. Check in order:

**Architecture vision (recommended):** 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 found, check `.arness/vision/architecture-vision.md` at the project root

**If an architecture vision is found:** Read it for stack decisions (framework, languages, platform targets, system dependencies).

**If no architecture vision is found:** Ask the user to describe their stack: "No architecture vision found. Describe your technology stack and target platforms so I can configure the development environment."

**Scaffolded project (recommended):** Check for `package.json`, `Cargo.toml`, or similar at the project root to detect what dependencies and tooling are already configured.

**If the project is scaffolded:** Use existing manifests and configs for context.

**If the project is not scaffolded:** Warn the user: "The project does not appear to be scaffolded yet. I can define the development environment conceptually, but setup scripts will be more useful after running `/arn-spark-scaffold`." Proceed with the conversation.

Workflow

Step 1: Detect Mode

Read CLAUDE.md and check for a `## Arness` section with a `### Dev Environment` subsection.

**If `### Dev Environment` exists:**

"A development environment is already configured for this project:

**Type:** [type from CLAUDE.md] **Platforms:** [platforms from CLAUDE.md]

Ask (using `AskUserQuestion`):

**"A development environment is already configured. What would you like to do?"**

Options: 1. **Follow the existing setup** — I will guide you through setting up your development environment 2. **Reconfigure** — I will walk through the environment decisions again and update the configuration"

• If the user chooses to follow → proceed to **Onboard Mode (Step O1)**
• If the user chooses to reconfigure → proceed to **Define Mode (Step 2)**

**If no `### Dev Environment` exists:**

Proceed to Define Mode (Step 2).

---

Define Mode

Step 2: Load Context

Read available artifacts:

• **Architecture vision:** Framework, languages, platform targets, known risks, system-level requirements
• **Scaffold results:** package.json (scripts, engines, dependencies), Cargo.toml (edition, targets), build configuration files
• **Existing dev files:** Check for .devcontainer/, Dockerfile, docker-compose.yml, .github/workflows/, scripts/ -- note what already exists

Identify platform-specific requirements from the stack. For example:

• Tauri requires WebKit2GTK on Linux, WebView2 on Windows, and Xcode command-line tools on macOS
• Rust requires the Rust toolchain (rustup + cargo)
• Node.js projects need a specific Node version

Step 3: Explore Environment Approach

Present the environment options, informed by the project context:

"Your project uses **[stack summary]**, targeting **[platforms]**. Based on your stack, I would suggest **[recommendation with brief rationale]**."

Ask (using `AskUserQuestion`):

**"Which development environment approach fits your project?"**

Options: 1. **Native** — Developers install tools directly on their OS. Best for GUI applications, hardware access, and fast iteration 2. **Dev container** — Reproducible containerized environment via VS Code Dev Containers. Best for web services, team consistency, and easy onboarding 3. **Docker / Docker Compose** — Containerized services. Best for backend services, databases, and microservices 4. **Hybrid** — Native for some parts (GUI, hardware), containerized for others (backend services, databases)

If the user is unsure, ask probing questions:

| Question | Guides Toward | |----------|--------------| | "Does the project need native windowing or hardware access?" | Native or hybrid (containers cannot easily access GUI/hardware) | | "Will developers be on