/arn-spark-arch-vision

name: arn-spark-arch-vision
description: >-
  This skill should be used when the user says "arch vision", "architecture
  vision", "arn arch vision", "define the architecture", "tech stack",
  "what technology should I use", "design the system", "system architecture",
  "how should I build this", "technology choices", "choose technologies",
  "pick a tech stack", or wants to explore
  technology options and define the high-level architecture for a greenfield
  project. Takes a product concept as input and produces an
  architecture-vision.md document capturing the technology stack, system
  design, protocols, packaging strategy, and known risks.
version: 1.0.0

Arness Arch Vision

Explore technology options and define the system architecture for a greenfield project through iterative conversation, aided by technology research from the `arn-spark-tech-evaluator` agent. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifact is an **architecture vision document**.

This skill covers the HOW at a high level: what technologies to use and how the system is structured. It does not cover implementation details like file structure, specific APIs, or code patterns -- that is the plan's job (via `/arn-code-plan`).

Step 0: Ensure Configuration

Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-ensure-config/references/step-0-fast-path.md` and follow its instructions. This guarantees a user profile exists and `## Arness` is configured with Arness Spark fields before proceeding.

After Step 0 completes, extract from `## Arness`:

• Vision directory, Use cases directory, Prototypes directory, Spikes directory, Visual grounding directory, Reports directory

Prerequisites

A product concept document should exist. Check in order:

1. Check the configured Vision directory for `product-concept.md` 2. If not found, check `.arness/vision/product-concept.md` at the project root

**If a product concept is found:** Read it and proceed to Step 1.

**If no product concept is found:** Inform the user:

"No product concept document found. I recommend running `/arn-spark-discover` first to define what you are building. Alternatively, you can describe your product briefly and I will work with that."

If the user provides an inline description, proceed with that as the product context. Do not hard-block.

Determine the output directory: 1. Use the Vision directory path from `## Arness` — this is the source of truth 2. If the output directory does not exist, create it

Workflow

Step 1: Load Product Concept and Extract Requirements

Read the product concept document (or use the inline description). Extract two things:

**Product Pillars:** If the product concept contains a Product Pillars section, extract all pillars. These are non-negotiable qualities that every technology choice must serve or, at minimum, not compromise. Examples: "design fidelity" means the UI framework must support high polish; "zero configuration" means the packaging and distribution must be frictionless; "privacy-first" means the network layer must support end-to-end encryption natively.

**Technical requirements by category:**

• **Target platforms:** Operating systems, versions, deployment targets
• **Real-time requirements:** Latency needs, streaming, P2P, bidirectional communication
• **Security requirements:** Trust model, encryption, authentication mechanism
• **Scale requirements:** Number of participants, topology, data volume
• **UI requirements:** Complexity, animations, native feel, accessibility
• **Distribution requirements:** Installer type, app store, auto-updates
• **Business & operational constraints:** Business model (B2B/B2C/SaaS), multi-tenancy requirements (tenant count, isolation level), regulatory compliance (GDPR/HIPAA/SOC2), cost/budget limits, vendor constraints, licensing requirements, team experience, timeline pressures

Present both to the user:

"Based on your product concept, here are the **product pillars** that will guide technology decisions:

• **[Pillar]:** [what it means for architecture choices]
• ...

And the key **technical requirements:** [bullet list].

Does this capture everything correctly, or should I adjust anything before we explore technology options?"

If no pillars were found in the product concept (e.g., it was written before the pillars feature, or the user provided an inline description), ask: "I did not find product pillars in your concept. Are there non-negotiable qualities -- like performance, polish, simplicity, privacy -- that should influence technology choices?"

Wait for user confirmation or corrections before proceeding.

Step 2: Initial Technology Exploration

Read the user profile for expertise context. 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.

Invoke the `arn-spark-tech-evaluator` 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:

• The product concept (or extracted requirements)
• The full set of technical requirements from Step 1
• The product pillars from Step 1
• Any technology preferences or constraints the user has mentioned
• User expertise context (structured blocks below)

Include in the agent invocation context:

--- BEGIN USER EXPERTISE ---
[Read from ~/.arness/user-profile.yaml or .claude/arness-profile.local.md (project override takes precedence)]
Role: [role]
Experience: [development_experience]
Technology preferences: [technology_preferences]
Expertise-aware: [expertise_aware]
--- END USER EXPERTISE ---

--- BEGIN PROJECT PREFERENCES ---
[Read from .arness/preferences.yaml if it exists, otherwise omit this section]
--- END PROJECT PREFERENCES ---

If `expertise_awa