arn-spark-arch-vision

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_aware: true and the user lists relevant technologies, add "Team has strong [X] experience" as an IMPORTANT (not CRITICAL) criterion in the comparison matrix. If development_experience: learning, add explanatory notes for complex technologies and flag steep learning curves. If development_experience: non-technical, favor the most mainstream, well-documented options. Apply the advisory pattern: present the technically optimal recommendation first, then a preference-aligned alternative with pros/cons if they differ.

The agent returns:

• A requirements summary table (with pillar-derived criteria marked)
• Candidate technologies per architectural layer with comparison matrices
• Pillar alignment assessment per recommendation
• Validation points and risk assessment
• An initial stack recommendation with rationale

Present the findings to the user as a conversation starter. Highlight:

• The recommended stack and why
• How the stack serves (or challenges) each product pillar
• Key trade-offs and alternatives considered
• Critical validation points that need early testing

Frame it as: "Here is my initial technology assessment. Let's discuss each layer and make sure we are aligned."

Step 3: Architecture Exploration (Iterative)

Enter a conversation loop. Cover these architectural categories (not necessarily in order -- follow the user's interests):

1. Application Framework -- Desktop, web, mobile, cross-platform runtime
2. UI Framework -- Rendering approach, component library, animation capability
3. Network & Communication -- Protocols for discovery, signaling, data transport
4. Security & Identity -- Cryptographic identity, trust establishment, encryption
5. Data Storage & Persistence -- Config storage, state persistence, caching
6. Platform Integration -- OS-specific features, permissions, system tray, device management
7. Packaging & Distribution -- Installers, code signing, auto-updates, firewall rules
8. Known Risks -- Technical risks with specific mitigations and fallbacks

Within each round of conversation, decide how to respond:

| Situation | Action | |-----------|--------| | User asks "which is better, X or Y?" | Load ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-arch-vision/references/technology-evaluation-guide.md if not already loaded, then invoke arn-spark-tech-evaluator with head-to-head comparison request | | User asks "will X work for our use case?" | Invoke arn-spark-tech-evaluator with validation question | | User asks about a technology's current status | Invoke arn-spark-tech-evaluator (uses WebSearch to verify) | | User wants a full recommendation for a layer | Invoke `ar