arn-spark-dev-setup

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 different OS platforms?" | Stronger need for setup scripts and CI matrix | | "Are there backend services or databases to manage?" | Docker compose or hybrid | | "How important is onboarding speed vs. environment control?" | Dev container (fast onboard) vs. native (more control) | | "Is this a team project or solo?" | Team → stronger standardization; solo → lighter setup |

Step 4: Gather Specifics

Based on the chosen approach, explore the details conversationally:

For all approaches:

Ask (using AskUserQuestion) with multiSelect: true:

"Which platforms should the setup support? (select multiple)"

Options:

1. Linux — Linux development environment
2. macOS — macOS development environment
3. Windows — Windows development environment

Default to all platforms from the architecture vision.

Ask (using AskUserQuestion):

"Do you want CI configured?"

Options:

1. GitHub Actions — Set up GitHub Actions CI workflow
2. GitLab CI — Set up GitLab CI pipeline
3. Skip for now — No CI configuration

Also ask conversationally:

• "Should I pin toolchain versions? (Rust version, Node version, etc.)"
• "Any IDE configuration? VS Code extensions, editor settings?"

For native environments:

• "How automated should the setup be? Full automation (scripts install everything) or documented manual steps?"
• "Any specific package manager preferences per platform? (Homebrew on macOS, apt vs. snap on Linux, winget vs. chocolatey on Windows)"

For dev containers:

• "Which base image? (Language-specific like mcr.microsoft.com/devcontainers/rust or generic like ubuntu?)"
• "Any additional container features needed? (Docker-in-Docker, GPU access, specific system libs)"
• "Port forwarding for dev server?"
• "Post-create commands to run after the container starts?"

For Docker / Docker Compose:

• "Which services need containers? (database, cache, message queue, the app itself?)"
• "Volume mounts for live reload during development?"
• "Network configuration between services?"
• "Separate development and production Dockerfiles?"

For hybrid:

• "Which parts run natively? Which are containerized?"
• "How do the native and containerized parts communicate? (localhost ports, shared volumes, environment variables)"

Confirm the full specification before proceeding:

"Here is the development environment I will set up:

Type: [type] Platforms: [list] CI: [provider or none] Toolchain pins: [list] Generated files: [list of what will be created]

Ready to generate, or want to adjust anything?"

Step 5: Invoke Builder

Invoke the arn-spark-dev-env-builder agent via the Task tool, passing the model from .arness/agent-models/spark.md as the model parameter (see `plugins/arn-