@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-arch-vision/SKILL.md

@@ -0,0 +1,226 @@
+---
+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 `.arness/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/profile.yaml]
+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 `arn-spark-tech-evaluator` with layer evaluation request |
+| User makes a technology decision | Record directly, confirm the decision and note implications |
+| User asks about code patterns or project structure | Defer: "Good question -- code patterns will be set up automatically when the project transitions to development. For now, let's focus on which technologies to use." |
+| User asks a product/scope question | Defer: "That is a product question. We can revisit the product concept if needed, but let's finish the architecture first." |
+| User seems done or conversation is circling | Proceed to readiness check |
+
+**Tracking coverage:** Track which architectural layers have been decided. A layer is "covered" when the user has agreed to a specific technology or explicitly deferred the decision.
+
+**Readiness check:** After covering the major layers (typically 4-8 rounds), check:
+
+"I think we have the architecture mapped out. Here is a summary of the stack: [brief table].
+
+**Pillar alignment:** [For each pillar, a one-line assessment of how the chosen stack serves it. Flag any pillar that is not fully supported — e.g., 'Design fidelity: Strong — Svelte + shadcn-svelte provides full component customization' or 'Zero configuration: At risk — code signing requires manual certificate setup on first build.']
+
+Ready for me to write the architecture vision document, or do you want to explore any area further?"
+
+### Step 4: Write the Architecture Vision Document
+
+When the user is ready:
+
+1. Read the template:
+   > Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-arch-vision/references/architecture-vision-template.md`
+
+2. Populate the template with all decisions from the conversation:
+   - Replace all bracketed placeholders with concrete content
+   - Build the Technology Stack table with every layer discussed
+   - Create an ASCII architecture diagram showing major components
+   - Adapt section names to match the product domain
+   - For Known Risks, include specific mitigations and fallbacks (not vague assurances)
+   - Map Future Architecture Considerations to items from the product concept's "Future Considerations"
+
+3. Write the document to the output directory as `architecture-vision.md`
+
+4. Present a summary to the user:
+   - List the document path
+   - Show the final technology stack table
+   - Highlight critical validation points that need early attention
+   - Note any decisions that were deferred or need further investigation
+
+### Step 5: Recommend Next Steps
+
+After writing the document, inform the user:
+
+"Architecture vision saved to `[path]/architecture-vision.md`.
+
+You now have both product concept and architecture vision defined. Recommended next steps:
+
+1. **Start developing:** If you have the Arness Code plugin installed, run `/arn-planning` to begin the development pipeline. Arness auto-configures code patterns based on your architecture choices.
+2. **Scaffold the project:** Set up the development environment with your chosen stack
+3. **Validate critical risks:** [list the top 1-2 validation points from the document]
+4. **Start feature specs:** Run `/arn-code-feature-spec` to spec your first feature"
+
+Adapt the next steps based on what makes sense for the project. If critical validation points were identified, emphasize those as the immediate priority.
+
+## Agent Invocation Guide
+
+| Situation | Action |
+|-----------|--------|
+| Initial technology exploration (Step 2) | Invoke `arn-spark-tech-evaluator` with full requirements |
+| "Which is better, X or Y?" | Invoke `arn-spark-tech-evaluator` with comparison request |
+| "Will X work for our use case?" | Invoke `arn-spark-tech-evaluator` with validation question |
+| "What is the current state of X?" | Invoke `arn-spark-tech-evaluator` (uses websearch) |
+| Full layer recommendation needed | Invoke `arn-spark-tech-evaluator` with layer evaluation |
+| User makes a technology decision | Record directly, no agent needed |
+| Architecture pattern question | Answer directly from conversation context |
+| Product or scope question | Defer to product concept or `/arn-spark-discover` |
+
+## Error Handling
+
+- **User cancels mid-conversation:** Confirm cancellation. If enough decisions have been made for a partial document, offer to write it. Otherwise, inform the user they can restart with `/arn-spark-arch-vision` at any time.
+- **arn-spark-tech-evaluator returns unhelpful response:** Summarize the issue briefly and continue the conversation directly. Try a more specific or narrower question on the next agent invocation.
+- **websearch unavailable (for arn-spark-tech-evaluator):** The agent will fall back to its training data. Note to the user that technology recommendations have not been verified against current release status and suggest the user manually check version currency for critical choices.
+- **Writing the document fails:** Print the full document content in the conversation so the user can copy it. Suggest checking file permissions or the output directory path.
+- **Architecture vision already exists:**
+
+  Ask the user:
+
+  > **An architecture vision already exists at `[path]`. How would you like to proceed?**
+  > 1. **Replace** — Start a fresh architecture exploration
+  > 2. **Update** — Focus on specific sections that need changes
+
+  If **Update**, read the existing document and focus the conversation on the sections that need changes.
+- **No product concept and user declines to describe product:** Cannot proceed meaningfully. Suggest: "Without understanding what we are building, technology choices would be arbitrary. Run `/arn-spark-discover` first to define the product, then come back to architecture."

package/plugins/arn-spark/skills/arn-spark-arch-vision/references/architecture-vision-template.md

@@ -0,0 +1,153 @@
+# Architecture Vision Template
+
+This template defines the structure for architecture vision documents written by the `arn-spark-arch-vision` skill. The document is saved to the project's vision directory as `architecture-vision.md`.
+
+An architecture vision captures the HOW at a high level: technology stack, system design, protocols, platform integration, packaging, and known risks. It does not contain implementation details like code structure, file organization, or specific APIs -- that is the plan's job.
+
+## Instructions for arn-spark-arch-vision
+
+When populating this template:
+
+- Every section below MUST appear in the output, even if the content is brief
+- Replace all bracketed placeholders with concrete content from the architecture exploration conversation
+- The Technology Stack table should include every architectural layer discussed, with rationale for each choice
+- The High-Level Architecture diagram should be ASCII art showing major components and their relationships
+- Adapt section names to match the product domain (e.g., "Network Protocols" for a P2P app, "API Design" for a web service)
+- Pillar Alignment must reference the product concept's Product Pillars section. If no pillars exist, omit this section. Every pillar must be assessed — do not skip pillars that are hard to evaluate
+- Known Risks must include specific mitigations, not just "we'll figure it out"
+- Future Architecture Considerations should map to the product concept's "Future Considerations" and explain what would change architecturally
+
+---
+
+## Template
+
+```markdown
+# [Product Name] - Architecture Vision
+
+## Technology Stack
+
+| Layer | Technology | Rationale |
+|-------|-----------|-----------|
+| [layer name] | **[technology]** | [Why this was chosen over alternatives. Reference specific project requirements.] |
+
+## Business Constraints & Trade-offs
+
+[How the technology stack addresses identified business constraints. Cost implications at stated scale, compliance alignment, tenancy support, vendor dependencies, and licensing. Omit this section if no business constraints were captured in the product concept.]
+
+| Constraint | How Stack Addresses It | Risk or Trade-off |
+|-----------|----------------------|-------------------|
+| [e.g., Multi-tenant, 500 clients] | [e.g., PostgreSQL with schema-per-tenant via pg_schema; PgBouncer for connection pooling] | [e.g., Operational complexity increases with tenant count; schema migrations must be tenant-aware] |
+| [e.g., HIPAA compliance] | [e.g., AWS with BAA, RDS encryption at rest, CloudTrail audit logging] | [e.g., Limits provider choices to AWS/GCP/Azure with BAA] |
+| [e.g., Budget: $500/mo] | [e.g., Self-hosted on single VPS with tenant density optimization] | [e.g., Scaling beyond 200 tenants requires infrastructure upgrade] |
+
+[Remove example rows. Only include constraints from the product concept's Business Constraints section.]
+
+## Pillar Alignment
+
+[For each product pillar from the product concept, assess how the chosen technology stack serves it. This section ensures that non-negotiable product qualities were not compromised by technology decisions.]
+
+| Pillar | Status | How the Stack Serves It |
+|--------|--------|------------------------|
+| [Pillar name] | Supported / At Risk / Mitigated | [Specific explanation: which technologies serve this pillar and how. If at risk, explain why and what mitigation exists.] |
+
+[If any pillar is "At Risk," elaborate on the specific concern and what can be done — e.g., a spike to validate, a configuration change, or an alternative technology to evaluate. A technology stack that conflicts with a product pillar should be reconsidered unless the conflict is acknowledged and accepted by the user.]
+
+## High-Level Architecture
+
+[ASCII component diagram showing major components, their groupings, and relationships. Use box drawing characters for clarity. Show the boundary between backend/native and frontend/UI layers if applicable.]
+
+### [Backend / Native Layer Name]
+
+[What runs at the native/system level. List responsibilities as bullets. Describe each major component briefly.]
+
+### [Frontend / UI Layer Name]
+
+[What the user sees and interacts with. List responsibilities as bullets. Describe each major component briefly.]
+
+### Communication Between Layers
+
+[How the backend and frontend communicate. IPC mechanism, event system, API pattern. Brief description of data flow direction.]
+
+## [Protocols / Communication Design]
+
+[For each protocol or communication mechanism used by the product:]
+
+### [Protocol / Mechanism Name]
+
+[Service definition, message types, data format. How devices/users discover each other, how connections are established, what data flows over each channel. Include protocol-specific details like ports, service types, message schemas.]
+
+[Repeat for each protocol]
+
+## [Identity / Security Architecture]
+
+### Identity
+
+[How entities (users, devices) are identified. What cryptographic primitives are used. Where identity information is stored.]
+
+### [Trust Establishment]
+
+[How trust is established between entities. The pairing/authentication flow at a technical level.]
+
+### [Entity] States
+
+[State machine for the primary entity. List states and what each means for the system's behavior.]
+
+## [Platform Integration / Device Management]
+
+### [Capability] Selection & Persistence
+
+[How platform resources (audio devices, cameras, etc.) are enumerated, selected, and remembered across sessions.]
+
+### Hot-Plug Handling
+
+[How the system handles devices being connected/disconnected during operation. Fallback behavior, notification strategy, auto-recovery.]
+
+## Packaging & Distribution
+
+### [Platform 1]
+
+[Installer type, signing requirements, platform-specific setup (firewall rules, permissions), build environment requirements.]
+
+### [Platform 2]
+
+[Same structure for each target platform.]
+
+### Storage Locations
+
+[Where application data is stored on each platform. Config files, cached data, logs.]
+
+## Known Risks & Mitigations
+
+[For each identified risk:]
+
+### [Risk Name]
+
+[Description of the risk. What could go wrong and what impact it would have.]
+
+**Mitigation:** [Specific strategy to address or reduce the risk.]
+
+**Fallback:** [What to do if the mitigation is insufficient. Alternative approach.]
+
+## Future Architecture Considerations
+
+[For each item in the product concept's "Future Considerations," briefly describe what architectural changes would be needed. This ensures v1's architecture does not accidentally block future work.]
+
+- **[Future feature]:** [What would change architecturally. What v1 decisions accommodate or constrain this.]
+```
+
+---
+
+## Section Guidance
+
+| Section | Source | Depth |
+|---------|--------|-------|
+| Technology Stack | arn-spark-tech-evaluator recommendations + user decisions | Table covering every layer, 1-sentence rationale each |
+| Business Constraints & Trade-offs | Business Constraints section of product concept | Table mapping each constraint to stack support + risk. Concrete numbers (cost at scale, connection limits, tenant capacity). Omit if no business constraints captured. |
+| Pillar Alignment | Product concept pillars + stack decisions | Table with one row per pillar, status + explanation |
+| High-Level Architecture | Conversation synthesis | ASCII diagram + 2-3 subsections with bullet lists |
+| Protocols / Communication | arn-spark-tech-evaluator analysis + conversation | 1 subsection per protocol, technical but not implementation-level |
+| Identity / Security | Conversation exploration of trust model | Identity primitives, trust flow, state machine |
+| Platform Integration | Conversation exploration of platform concerns | Device management, hot-plug, OS-specific behavior |
+| Packaging & Distribution | arn-spark-tech-evaluator research + conversation | 1 subsection per platform, installer + signing + permissions |
+| Known Risks & Mitigations | arn-spark-tech-evaluator validation points + conversation | Each risk: description + mitigation + fallback |
+| Future Architecture Considerations | Product concept's "Future Considerations" | Bullet list mapping each future item to architectural impact |

package/plugins/arn-spark/skills/arn-spark-arch-vision/references/technology-evaluation-guide.md

@@ -0,0 +1,86 @@
+# Technology Evaluation Guide
+
+Framework for evaluating technology choices in greenfield projects. Used by the `arn-spark-arch-vision` skill and `arn-spark-tech-evaluator` agent to ensure consistent, requirements-driven evaluation.
+
+## Evaluation Criteria Categories
+
+When evaluating technologies, draw criteria from these categories. Not all categories apply to every evaluation -- select those relevant to the project's requirements.
+
+### Core Criteria (almost always relevant)
+
+- **Platform support:** Does it run on all target platforms? Native support or workarounds needed?
+- **Maturity:** How long has it been production-ready? Stable API? Predictable release cadence?
+- **Maintenance:** Active development? Responsive to issues? Backed by a company or strong community?
+- **Documentation:** Quality of official docs? Tutorials, examples, migration guides available?
+- **Community:** Size and activity of the community? Stack Overflow presence? Discord/forum activity?
+
+### Project-Specific Criteria (select based on requirements)
+
+- **Real-time capability:** Latency characteristics, streaming support, P2P capability
+- **Performance:** Startup time, memory usage, CPU overhead, bundle/install size
+- **Security:** Built-in security features, encryption support, vulnerability track record
+- **Cross-platform consistency:** Same behavior across platforms? Platform-specific quirks?
+- **Integration:** How well does it work with other chosen technologies? Known compatibility issues?
+- **Learning curve:** Complexity for the team? Familiarity with the paradigm?
+- **Licensing:** Open source? Permissive or copyleft? Commercial use restrictions?
+- **Extensibility:** Plugin ecosystem? Easy to customize or extend?
+
+## Comparison Matrix Format
+
+For each decision point, build a comparison table:
+
+```
+| Criteria | [Tech A] | [Tech B] | [Tech C] |
+|----------|----------|----------|----------|
+| [Requirement 1] * | Strong | Adequate | Weak |
+| [Requirement 2] | Adequate | Strong | Strong |
+| [Requirement 3] * | Strong | Strong | Weak |
+
+* = Critical requirement (Weak rating here is a deal-breaker)
+```
+
+### Rating Definitions
+
+- **Strong:** Fully meets the requirement with minimal effort. Well-documented, battle-tested for this use case.
+- **Adequate:** Meets the requirement but with caveats. May need extra configuration, workarounds, or has minor limitations.
+- **Weak:** Does not meet the requirement, or meeting it requires significant effort, workarounds, or unproven approaches.
+- **N/A:** Criteria does not apply to this technology.
+
+### Guidelines
+
+- Derive criteria rows from the project's actual requirements, not generic benchmarks
+- Mark critical requirements with an asterisk -- a "Weak" on a critical requirement is a deal-breaker
+- Include evidence for each rating (1-2 sentences). Avoid bare ratings without explanation.
+- If a rating is uncertain, note it: "Adequate (needs validation)" or "Strong (based on docs, not verified)"
+
+## Validation Point Categories
+
+After recommending technologies, categorize what must be validated:
+
+### Critical (validate before writing any production code)
+
+Items where failure would require changing the technology choice entirely. Examples:
+- "WebRTC getUserMedia works in Tauri's macOS WKWebView"
+- "mDNS multicast is not blocked by default Windows Firewall"
+
+### Important (validate in the first sprint)
+
+Items where failure would require workarounds but not a technology change. Examples:
+- "Svelte transitions perform smoothly on older hardware"
+- "WebSocket reconnection handles network flapping gracefully"
+
+### Monitor (keep an eye on during development)
+
+Items that are low-risk but worth tracking. Examples:
+- "Bundle size stays under target as dependencies are added"
+- "Build times remain reasonable as codebase grows"
+
+## Stack Cohesion Assessment
+
+When recommending a full stack, assess how well the technologies work together:
+
+- **Integration patterns:** Are there established patterns for combining these technologies? (e.g., "Tauri + Svelte has official template support")
+- **Community examples:** Are there real projects using this combination? Can we reference them?
+- **Build tooling:** Do the build tools play well together? Any conflicting requirements?
+- **Dependency overlap:** Do the technologies share dependencies that could cause version conflicts?
+- **Knowledge transfer:** If a developer knows one part of the stack, does that help with other parts?