@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-help/references/pipeline-map.md

@@ -0,0 +1,211 @@
+# Spark Pipeline Map
+
+Reference for the `arn-spark-help` skill. Contains pipeline templates, stage detection rules, and next-step suggestions for the Spark exploration pipeline.
+
+---
+
+## Spark Pipeline Template
+
+The diagram below is the canonical Spark exploration pipeline. When rendering for the user, annotate the active stage with a `YOU ARE HERE` marker placed below the active stage name.
+
+```
+Spark Exploration Pipeline
+==========================
+
+  gf-init --> discover --> stress-test --> concept-review --> naming --> arch-vision --> use-cases --> scaffold --> spike --> visual-sketch --> style-explore --> prototypes --> lock --> feature-extract
+                          (optional)      (optional)        (optional)                                                     (optional)
+
+  Prototypes: arn-spark-static-prototype then arn-spark-clickable-prototype (in sequence)
+  Stress tests: arn-spark-stress-interview, arn-spark-stress-competitive, arn-spark-stress-premortem, arn-spark-stress-prfaq (multi-select)
+  Variants: arn-spark-use-cases-teams, arn-spark-static-prototype-teams, arn-spark-clickable-prototype-teams
+  Standalone: arn-spark-dev-setup, arn-spark-visual-readiness, arn-spark-visual-strategy
+  Guided: /arn-brainstorming -- walks through the entire pipeline with decision gates
+```
+
+---
+
+## Stage-to-Skill Mapping
+
+| Stage | Primary Skill | Notes |
+|-------|--------------|-------|
+| `gf-init` | `/arn-brainstorming` or `/arn-spark-discover` | Brainstorming is the guided wizard; discover is the direct entry |
+| `discover` | `/arn-spark-discover` | Produces product-concept.md with vision, personas, competitive landscape, pillars |
+| `stress-test` | `/arn-spark-stress-interview`, `/arn-spark-stress-competitive`, `/arn-spark-stress-premortem`, `/arn-spark-stress-prfaq` | Multi-select: user picks which tests to run. All are read-only on product-concept.md |
+| `concept-review` | `/arn-spark-concept-review` | Consolidates stress test findings. ONLY skill that modifies product-concept.md |
+| `naming` | `/arn-spark-naming` | 4-step methodology: Brand DNA, creative generation, Six Senses scoring, WHOIS/trademark due diligence |
+| `arch-vision` | `/arn-spark-arch-vision` | Technology choices, system design, packaging strategy |
+| `use-cases` | `/arn-spark-use-cases` | Cockburn fully-dressed format. Teams variant: `/arn-spark-use-cases-teams` |
+| `scaffold` | `/arn-spark-scaffold` | Creates project skeleton with chosen framework and dependencies |
+| `spike` | `/arn-spark-spike` | Optional — validate risky technical assumptions with POC code |
+| `visual-sketch` | `/arn-spark-visual-sketch` | Multiple visual direction proposals as live HTML/CSS |
+| `style-explore` | `/arn-spark-style-explore` | Define complete design system from the visual direction |
+| `prototypes` | `/arn-spark-static-prototype` then `/arn-spark-clickable-prototype` | Teams variants available for both. Includes UX judge validation |
+| `lock` | `/arn-spark-prototype-lock` | Freezes validated prototype as development reference |
+| `feature-extract` | `/arn-spark-feature-extract` | Extracts prioritized feature backlog. Optional issue tracker upload |
+
+---
+
+## Annotation Instructions
+
+1. Identify the user's current stage using the detection rules below.
+2. Place the `YOU ARE HERE` marker directly below the matching stage label.
+3. Spark is a single-track pipeline (no per-project subdirectories).
+
+**Example:**
+
+```
+Spark Exploration Pipeline
+==========================
+
+  gf-init --> discover --> stress-test --> concept-review --> naming --> arch-vision --> use-cases --> scaffold --> spike --> visual-sketch --> style-explore --> prototypes --> lock --> feature-extract
+                                                                                                                                            ^^^^^^^^^^^^^
+                                                                                                                                          YOU ARE HERE
+
+  Prototypes: arn-spark-static-prototype then arn-spark-clickable-prototype
+  Stress tests: arn-spark-stress-interview, arn-spark-stress-competitive, arn-spark-stress-premortem, arn-spark-stress-prfaq
+  Variants: arn-spark-use-cases-teams, arn-spark-static-prototype-teams, arn-spark-clickable-prototype-teams
+  Standalone: arn-spark-dev-setup, arn-spark-visual-readiness, arn-spark-visual-strategy
+  Guided: /arn-brainstorming
+```
+
+---
+
+## Stage Detection Rules
+
+Check stages from **most advanced to least advanced**. The first matching rule determines the current stage. Spark detection uses artifact existence in the configured Spark directories.
+
+**Prerequisites:** `## Arness` must contain at least one Spark field (Vision directory, Use cases directory, Prototypes directory). If none are present, Spark detection is skipped entirely.
+
+| Stage | Key | Detection Rule | Artifact |
+|-------|-----|----------------|----------|
+| Feature backlog ready | `gf-feature-extract` | Feature backlog index exists | `<vision-dir>/features/feature-backlog.md` |
+| Prototype locked | `gf-prototype-lock` | Locked prototype manifest exists | `<prototypes-dir>/locked/LOCKED.md` |
+| Clickable prototype done | `gf-clickable-proto` | Clickable prototype final report exists | `<prototypes-dir>/clickable/final-report.md` |
+| Static prototype done | `gf-static-proto` | Static prototype final report exists | `<prototypes-dir>/static/final-report.md` |
+| Style defined | `gf-style-explore` | Style brief exists | `<vision-dir>/style-brief.md` |
+| Visual direction chosen | `gf-visual-sketch` | Visual direction document exists | `<vision-dir>/visual-direction.md` |
+| Spike complete | `gf-spike` | Spike results exist | `<vision-dir>/spike-results.md` |
+| Scaffold built | `gf-scaffold` | Scaffold summary exists | `<vision-dir>/scaffold-summary.md` |
+| Use cases written | `gf-use-cases` | Use case files exist | `<use-cases-dir>/UC-*.md` (at least one) |
+| Architecture defined | `gf-arch-vision` | Architecture vision exists | `<vision-dir>/architecture-vision.md` |
+| Naming complete | `gf-naming` | Naming brief or report exists | `<vision-dir>/naming-brief.md` OR `<reports-dir>/naming-report.md` |
+| Concept reviewed | `gf-concept-review` | Concept review report exists | `<reports-dir>/stress-tests/concept-review-report.md` |
+| Stress tests run | `gf-stress-test` | Any stress test report exists | `<reports-dir>/stress-tests/interview-report.md` OR `competitive-report.md` OR `premortem-report.md` OR `prfaq-report.md` |
+| Product discovered | `gf-discover` | Product concept exists | `<vision-dir>/product-concept.md` |
+| Spark initialized | `gf-init` | Spark fields exist in `## Arness` but no artifacts found | `## Arness` has Spark fields but directories are empty |
+
+### Spark Complete Detection
+
+Spark exploration is considered **complete** when `<vision-dir>/features/feature-backlog.md` exists (the `gf-feature-extract` stage is reached). This signals the project is ready to transition from exploration to development.
+
+### Detection Notes
+
+**Stress test stage:** Four independent reports can exist in any combination. The presence of ANY stress-test report triggers the `gf-stress-test` stage. If `concept-review-report.md` also exists, it takes precedence (concept-review > stress-test in detection order).
+
+**Naming stage:** `naming-brief.md` gets written incrementally during the naming process. Any existence of naming-brief.md or naming-report.md is treated as naming complete. If naming is in-progress and the user runs `/arn-spark-naming`, it handles its own resume.
+
+**Spike stage:** Optional. If a project skips spike and goes directly from scaffold to visual-sketch, the detection works correctly — `gf-visual-sketch` is detected based on `visual-direction.md` existence.
+
+**Prototype-lock stage:** Optional. If a project skips lock and goes directly from clickable-prototype to feature-extract, the detection works correctly.
+
+---
+
+## Next Step Suggestions
+
+After detecting the current Spark stage, suggest the next command.
+
+| Current Stage | Next Command | Description |
+|---------------|-------------|-------------|
+| Spark initialized (`gf-init`) | `/arn-spark-discover` | Shape the product idea into a structured concept. Or run `/arn-brainstorming` for the guided wizard. |
+| Product discovered (`gf-discover`) | `/arn-spark-stress-interview`, etc. OR `/arn-spark-arch-vision` | Run stress tests to validate the concept (optional), or skip to architecture. |
+| Stress tests run (`gf-stress-test`) | `/arn-spark-concept-review` | Consolidate stress test findings and update the product concept. |
+| Concept reviewed (`gf-concept-review`) | `/arn-spark-naming` or `/arn-spark-arch-vision` | Name your product (optional), or skip to architecture. |
+| Naming complete (`gf-naming`) | `/arn-spark-arch-vision` | Choose technologies and design the system architecture. |
+| Architecture defined (`gf-arch-vision`) | `/arn-spark-use-cases` | Write use cases (or `/arn-spark-use-cases-teams` for expert debate). |
+| Use cases written (`gf-use-cases`) | `/arn-spark-scaffold` | Create the project skeleton with the chosen tech stack. |
+| Scaffold built (`gf-scaffold`) | `/arn-spark-spike` or `/arn-spark-visual-sketch` | Validate risky assumptions (optional), or explore visual directions. |
+| Spike complete (`gf-spike`) | `/arn-spark-visual-sketch` | Generate visual direction proposals on the dev server. |
+| Visual direction chosen (`gf-visual-sketch`) | `/arn-spark-style-explore` | Define the complete design system from the visual direction. |
+| Style defined (`gf-style-explore`) | `/arn-spark-static-prototype` | Build and validate a static HTML/CSS prototype. |
+| Static prototype done (`gf-static-proto`) | `/arn-spark-clickable-prototype` | Build and validate an interactive prototype with linked screens. |
+| Clickable prototype done (`gf-clickable-proto`) | `/arn-spark-prototype-lock` or `/arn-spark-feature-extract` | Lock the prototype (optional), or extract features directly. |
+| Prototype locked (`gf-prototype-lock`) | `/arn-spark-feature-extract` | Extract features into a prioritized backlog for development. |
+| Feature backlog ready (`gf-feature-extract`) | `/arn-planning` | Transition to development — start specifying features. Or `/arn-infra-wizard` for infrastructure. |
+
+---
+
+## Variant Commands
+
+These can be used as alternatives at specific stages:
+
+| Variant | Replaces | When to Suggest |
+|---------|----------|-----------------|
+| `/arn-spark-use-cases-teams` | `/arn-spark-use-cases` | User prefers expert debate format for use cases |
+| `/arn-spark-static-prototype-teams` | `/arn-spark-static-prototype` | User prefers expert debate for prototype validation |
+| `/arn-spark-clickable-prototype-teams` | `/arn-spark-clickable-prototype` | User prefers expert debate for prototype validation |
+
+### Standalone Commands
+
+These operate outside the main pipeline and can be suggested at any time:
+
+| Command | Purpose | Prerequisite |
+|---------|---------|--------------|
+| `/arn-spark-dev-setup` | Define or follow development environment setup | Greenfield config exists |
+| `/arn-spark-prototype-lock` | Freeze approved prototypes with guardrail hooks | Prototypes directory configured, prototype approved |
+| `/arn-spark-visual-readiness` | Check visual layer readiness before activating deferred tests | Visual strategy defined |
+| `/arn-spark-visual-strategy` | Define layered visual testing strategy | Scaffold built, at least style-explore complete |
+
+### Entry Points
+
+- `/arn-brainstorming` — Walks through the entire Spark exploration pipeline with guided decision gates. This is the recommended way to use Spark for new projects.
+- `/arn-spark-discover` — Direct entry into product discovery without the wizard.
+- `/arn-spark-init` — (Optional) Explicitly configure the greenfield environment. Not required — Arness auto-configures on first use.
+
+When suggesting next steps at an early stage (`gf-init` or `gf-discover`):
+
+```
+Tip: Run `/arn-brainstorming` for the guided pipeline, or invoke individual skills directly.
+```
+
+---
+
+## Cross-Plugin Hint Templates
+
+When Step 0 detects other plugin activity, append these hints at the bottom of the status output.
+
+**Code active:**
+```
+Development pipeline: active — run `/arn-code-help` for details.
+```
+
+**Infra active:**
+```
+Infrastructure pipeline: active — run `/arn-infra-help` for details.
+```
+
+**Code not started but configured:**
+```
+Development pipeline: configured but not started.
+```
+
+**Infra not started but configured:**
+```
+Infrastructure pipeline: configured but not started.
+```
+
+**When Spark pipeline is complete (`gf-feature-extract`):**
+```
+Spark exploration is complete. Next steps:
+- Start developing features: `/arn-planning`
+- Deploy infrastructure: `/arn-infra-wizard`
+```
+
+**When own plugin idle (`gf-init`) and other plugins have activity:**
+Show own suggestions first:
+```
+Ready to start: run `/arn-spark-discover` to shape your product idea, or `/arn-brainstorming` for the guided wizard.
+```
+Then mention others:
+```
+You also have active work in Code — run `/arn-code-help` for details.
+```

package/plugins/arn-spark/skills/arn-spark-init/SKILL.md

@@ -0,0 +1,312 @@
+---
+name: arn-spark-init
+description: >-
+  Optional customization tool for greenfield projects. This skill should be used when the user says
+  "greenfield init", "arn spark init", "initialize greenfield", "setup greenfield",
+  "greenfield setup", "start greenfield", "configure greenfield",
+  "set up greenfield", "init greenfield", "greenfield configuration",
+  "review greenfield config", "customize greenfield config", "greenfield settings",
+  "Figma setup", "Canva setup", "add Figma", "add Canva", "design tool setup",
+  or wants to customize Arness Spark configuration, add design tool integrations
+  (Figma, Canva), or review current greenfield settings. Arness Spark auto-configures
+  with sensible defaults on first skill invocation — this init is optional.
+  Design tool integration (Figma/Canva) remains available only through this skill.
+version: 1.0.0
+---
+
+# Arness Spark Init
+
+Set up Arness for a greenfield project by configuring output directories for all greenfield artifacts and detecting the project's platform setup. This is optional — Arness Spark auto-configures with sensible defaults on first skill invocation. Use this to customize directories, add design tool integrations (Figma, Canva), or review your current settings.
+
+This skill is lightweight and focused: it configures only what greenfield skills need (artifact directories and platform integration). It does NOT set up code patterns, report templates, plans, or documentation directories — those are handled when the project transitions to the development phase. Design tool integration (Figma/Canva) is only available through this skill — ensure-config does not configure design tools.
+
+The `## Arness` section written by this skill is forward-compatible with Arness Code and Arness Infra. When either plugin's ensure-config or init runs later, it detects the existing configuration and adds the remaining fields without disrupting greenfield settings.
+
+## Workflow
+
+### Step 1: Check Existing Configuration
+
+Read the project's arness.md and look for a `## Arness` section. If no arness.md exists, create one at the project root before proceeding.
+
+**If the section does not exist:**
+- Proceed to Step 2 (fresh init)
+
+**If the section exists:**
+1. Parse all config fields from the existing `## Arness` block
+2. Read the current plugin version — use [PLATFORM_PLUGIN_METADATA] to read plugin version
+3. Show the user their current configuration
+4. Ask the user:
+   - **Review** — Show current configuration summary, no changes
+   - **Update** — Check for missing greenfield fields and fill them in
+   - **Reconfigure** — Re-run the full setup flow from scratch
+   - **Keep** — No changes
+- If **Review** → display a clean summary of all `## Arness` fields relevant to Arness Spark, then exit the skill
+- If **Keep** → done, exit the skill
+- If **Reconfigure** → continue to Step 2, pre-filling known values as defaults
+- If **Update** → check which greenfield fields are missing (Vision directory, Use cases directory, Prototypes directory, Spikes directory, Visual grounding directory, Reports directory, Git, Platform, Issue tracker, Figma, Canva) and only process those. For missing directory fields, ask the user with the existing value as the default. For missing Git/Platform/Issue tracker, re-run Step 3 detection. For missing Figma/Canva, re-run Step 3.4 design tool integration. Then proceed to Step 4 to write the updated config. Preserve all existing fields that are not managed by this skill (such as Plans directory, Specs directory, Report templates, etc.).
+
+---
+
+### Step 2: Configure Output Directories
+
+Ask the user about each output directory. All defaults are under `.arness/` to centralize Arness artifacts in one place.
+
+**2.1. Vision directory:**
+
+"Where should Arness store greenfield vision documents (product concept, architecture vision, style brief, spike results, feature backlog)?"
+
+- Default: `.arness/vision`
+- Used by: `/arn-spark-discover`, `/arn-spark-arch-vision`, `/arn-spark-spike`, `/arn-spark-style-explore`, `/arn-spark-feature-extract`, `/arn-spark-dev-setup`
+
+**2.2. Use cases directory:**
+
+"Where should Arness store use case documents?"
+
+- Default: `.arness/use-cases`
+- Used by: `/arn-spark-use-cases`, `/arn-spark-use-cases-teams`
+
+**2.3. Prototypes directory:**
+
+"Where should Arness store prototype versions and review reports?"
+
+- Default: `.arness/prototypes`
+- Used by: `/arn-spark-static-prototype`, `/arn-spark-clickable-prototype`
+
+**2.4. Spikes directory:**
+
+"Where should Arness store technical spike POC code?"
+
+- Default: `.arness/spikes`
+- Used by: `/arn-spark-spike`
+
+**2.5. Visual grounding directory:**
+
+"Where should Arness store visual grounding assets (reference images, design mockups, brand assets)?"
+
+- Default: `.arness/visual-grounding`
+- Used by: `/arn-spark-style-explore`, `/arn-spark-static-prototype`, `/arn-spark-clickable-prototype`
+
+Create three subfolders inside the visual grounding directory: `references/`, `designs/`, `brand/`.
+
+**2.6. Reports directory:**
+
+"Where should Arness store stress test reports and other analysis output?"
+
+- Default: `.arness/reports`
+- Used by: `/arn-spark-stress-interview`, `/arn-spark-stress-competitive`, `/arn-spark-stress-premortem`, `/arn-spark-stress-prfaq`, `/arn-spark-concept-review`
+
+After creating the Reports directory (`mkdir -p <chosen-path>`), also create the `stress-tests/` subdirectory: `mkdir -p <chosen-path>/stress-tests/`
+
+For each directory:
+- Accept any relative path the user provides (relative to the project root)
+- If updating an existing config (from Step 1), show the current path as the default
+- Create the directory if it does not exist: `mkdir -p <chosen-path>`
+
+---
+
+### Step 3: Detect Git, Platform, and Issue Tracker
+
+**Shared field preservation:** If `## Arness` already exists and the shared fields (Git, Platform, Issue tracker, Jira site, Jira project) are already present from a prior init (this plugin or another — e.g., arn-code-init or arn-infra-init), **skip detection and preserve the existing values** — unless the user chose **Reconfigure** in Step 1. This prevents overwriting values set by another plugin in a monorepo.
+
+Check if the project uses Git, determine the code hosting platform, and identify the issue tracker.
+
+**3.1. Git check:**
+1. Run `git rev-parse --is-inside-work-tree` to check for a git repository
+2. If Git is not detected, inform the user: "This project is not a git repository. Git-dependent skills (Arness Code: `/arn-code-ship`, `/arn-code-review-pr`, `/arn-code-create-issue`, `/arn-code-pick-issue`) will be unavailable." Record Git: no, Platform: none, Issue tracker: none and proceed to Step 4.
+
+**3.2. Remote classification:**
+1. Run `git remote -v` and classify the remote URL:
+   - Contains `github.com` → candidate: **github**
+   - Contains `bitbucket.org` → candidate: **bitbucket**
+   - Neither → Platform: none, Issue tracker: none. Inform the user: "No supported platform detected. PR and issue management skills will be unavailable."
+
+**3.3a. If candidate is github:**
+1. Run `gh auth status` to check for GitHub CLI authentication
+2. If authenticated → Platform: **github**, Issue tracker: **github**
+3. If NOT authenticated → warn the user, suggest `gh auth login`, and **STOP init** (do not continue until resolved)
+4. Create 7 Arness labels for issue management. Use `gh label create` for each label (the command is idempotent — it will skip labels that already exist):
+
+| Label | Color | Description |
+|-------|-------|-------------|
+| `arness-backlog` | `d4c5f9` | Deferred items from PRs or postponed features |
+| `arness-feature-issue` | `0e8a16` | Feature requests tracked via Arness |
+| `arness-bug-issue` | `d93f0b` | Bug reports tracked via Arness |
+| `arness-priority-high` | `b60205` | High priority |
+| `arness-priority-medium` | `fbca04` | Medium priority |
+| `arness-priority-low` | `c5def5` | Low priority |
+| `arness-rejected` | `e4e669` | Issue reviewed and rejected as invalid or out of scope |
+
+> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-init/references/platform-labels.md` for label details and which skills use each label.
+
+**3.3b. If candidate is bitbucket:**
+1. Run `bkt --version` to check if the Bitbucket CLI is installed
+   - If NOT available → read and show the setup instructions from `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-init/references/bkt-setup.md`, then **STOP init**
+2. Run `bkt auth status` to check authentication
+   - If NOT authenticated → read and show the auth instructions from `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-init/references/bkt-setup.md`, then **STOP init**
+3. Platform: **bitbucket** (confirmed)
+4. Ask the user:
+
+   > **Do you use Jira for issue tracking on this project?**
+   > 1. **Yes** — Verify Atlassian MCP server and select a Jira project
+   > 2. **No** — Skip issue tracker integration
+
+   - **Yes** → verify the Atlassian MCP server:
+     - Attempt to list Jira projects via the MCP tool
+     - If MCP NOT available → read and show the setup instructions from `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-init/references/jira-mcp-setup.md`, then **STOP init**
+     - If MCP available → list projects, present to user, user picks one
+     - Store: Issue tracker: **jira**, Jira site: (from MCP context or ask user), Jira project: (user's pick)
+     - No label creation needed (Jira labels are implicit — see `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-init/references/platform-labels.md`)
+   - **No** → Issue tracker: **none**
+     - Inform the user: "Issue management skills (Arness Code: `/arn-code-create-issue`, `/arn-code-pick-issue`) will be unavailable. PR and code workflow skills still work via bkt."
+
+**3.4. Design tool integration:**
+
+Detect design tool MCP availability, then ask the user's project-level decision.
+
+**3.4a. Detection (automatic):**
+
+1. Check if a Figma MCP server is configured:
+   - Look for `figma` in the project's `.mcp.json` or attempt to invoke a Figma MCP tool
+   - Record: Figma MCP available: yes | no
+
+2. Check if a Canva MCP server is configured:
+   - Look for `canva` in the project's `.mcp.json` or attempt to invoke a Canva MCP tool
+   - Record: Canva MCP available: yes | no
+
+**3.4b. User decision (ask):**
+
+Present the detection results, then ask the user what they want to use for THIS project.
+
+Show the detection context first:
+
+- [If Figma MCP detected:] "Figma MCP is available on this machine."
+- [If Figma MCP not detected:] "Figma MCP is not configured. ([Setup instructions](https://www.figma.com/blog/introducing-figma-mcp-server/))"
+- [If Canva MCP detected:] "Canva MCP is available on this machine."
+- [If Canva MCP not detected:] "Canva MCP is not configured. ([Setup instructions](https://www.canva.dev/docs/connect/mcp-server/))"
+
+Then ask the user (multiSelect: true):
+
+> **Which design tools do you want to use for this project?** (Even if an MCP is available, you may not need it for every project.)
+> 1. **Figma** — Pull design data and export screens during style exploration and prototype validation [only show if MCP available]
+> 2. **Canva** — Pull design assets during style exploration [only show if MCP available]
+> 3. **None** — No design tool integration for this project
+
+If the user selects a tool whose MCP is not available, inform them it requires MCP setup and suggest the setup link above.
+
+Record the user's choices:
+- **Figma:** yes | no (project-level decision, not just availability)
+- **Canva:** yes | no (project-level decision, not just availability)
+
+Downstream skills check these flags — not MCP availability — to decide whether to offer Figma/Canva integration. If the flag is `no`, the skill does not mention or attempt to use that MCP, even if it's technically available.
+
+**3.5. Record results:**
+- **Git:** yes | no
+- **Platform:** github | bitbucket | none
+- **Issue tracker:** github | jira | none
+- **Jira site:** (only if Issue tracker is jira)
+- **Jira project:** (only if Issue tracker is jira)
+- **Figma:** yes | no
+- **Canva:** yes | no
+
+---
+
+### Step 3.6: Choose Model Profile for arn-spark Agents
+
+Run the **Profile selection** procedure documented in `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-ensure-config/references/step-0-fast-path.md` under the "Model profile field" section. That procedure is the single source of truth for the prompt + write + copy + checksum flow — do NOT duplicate the question prompt or file-copy logic here.
+
+The procedure performs (in order):
+1. Cross-plugin default suggestion (read sibling plugin profile fields if present in the existing `## Arness` block — e.g., if the user previously chose `balanced` for arn-code, suggest `balanced` here too)
+2. Present the question with title "Choose model profile for arn-spark agents" and two options: `all-opus` (default unless a sibling chose `balanced`) and `balanced`
+3. Append `- **Spark agent model profile:** <choice>` to the `## Arness` block
+4. `mkdir -p .arness/agent-models/` then copy `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-init/references/agent-models-presets/<choice>.md` to `.arness/agent-models/spark.md`
+5. Compute SHA-256 and record it in `.arness/agent-models/.checksums.json` along with the profile name and version
+6. Inform the user with a one-line confirmation
+
+The field write in step 3 of the procedure is captured for the arness.md write in Step 4 of this init flow — write the chosen value to a holding variable and let Step 4 emit it inline with all other fields. The preset copy + checksum (steps 4-5 of the procedure) happen here regardless of when the arness.md write is performed.
+
+Record the chosen profile for the config write in Step 4.
+
+---
+
+### Step 4: Persist Configuration to arness.md
+
+Write (or update) the `## Arness` section in the project's arness.md:
+
+```markdown
+## Arness
+
+- **Vision directory:** [chosen-path]
+- **Use cases directory:** [chosen-path]
+- **Prototypes directory:** [chosen-path]
+- **Spikes directory:** [chosen-path]
+- **Visual grounding directory:** [chosen-path]
+- **Reports directory:** [chosen-path]
+- **Spark agent model profile:** all-opus | balanced | custom
+- **Git:** yes | no
+- **Platform:** github | bitbucket | none
+- **Issue tracker:** github | jira | none
+- **Jira site:** <site>.atlassian.net
+- **Jira project:** <KEY>
+- **Figma:** yes | no
+- **Canva:** yes | no
+```
+
+**Rules:**
+- All directory paths MUST be relative to the project root, never absolute. This ensures portability across machines.
+- The Jira site and Jira project fields are only written when Issue tracker is jira. Omit them entirely for other issue trackers.
+- The Figma and Canva fields are only written when the user explicitly chooses to use them for this project. Omit fields set to `no`.
+- Git, Platform, and Issue tracker fields are auto-detected in Step 3 and are not user-configurable. Figma and Canva are user-decided in Step 3.4.
+- If updating an existing config that has additional fields from other plugins, **preserve all fields not managed by this skill**. This includes dev fields (Plans directory, Specs directory, Report templates, Template path, Template version, Template updates, Code patterns, Docs directory, Task list ID) and infra fields (Deferred, Experience level, Project topology, Application path, Providers, Providers config, Default IaC tool, Environments, Environments config, Tooling manifest, Resource manifest, Cost threshold, Validation ceiling, Infra plans directory, Infra specs directory, Infra docs directory, Infra report templates, Infra template path, Infra template version, CI/CD platform, Reference overrides, Reference version, Reference updates). For shared fields (Git, Platform, Issue tracker, Jira site, Jira project): if already present, preserve them — do not re-detect unless the user chose Reconfigure in Step 1. Replace only the greenfield fields listed above.
+- Replace the existing `## Arness` section in place. Do not duplicate it.
+
+---
+
+### Step 5: Verify and Summarize
+
+Confirm with the user:
+
+- [ ] Vision directory configured and created: `[path]`
+- [ ] Use cases directory configured and created: `[path]`
+- [ ] Prototypes directory configured and created: `[path]`
+- [ ] Spikes directory configured and created: `[path]`
+- [ ] Visual grounding directory configured and created: `[path]`
+- [ ] Visual grounding subfolders created: `references/`, `designs/`, `brand/`
+- [ ] Reports directory configured and created: `[path]`
+- [ ] Reports subdirectory created: `stress-tests/`
+- [ ] Git detected: yes | no
+- [ ] Platform detected: github | bitbucket | none
+- [ ] Issue tracker detected: github | jira | none
+- [ ] GitHub labels created (if Platform is github)
+- [ ] Jira project selected (if Issue tracker is jira)
+- [ ] Figma integration: yes | no (user's choice for this project)
+- [ ] Canva integration: yes | no (user's choice for this project)
+- [ ] `## Arness` section written to arness.md
+
+List all created/modified files with their paths.
+
+**Next steps:**
+
+"Arness Spark is ready. Here is the recommended exploration pipeline:
+
+1. **Define the product:** Run `/arn-spark-discover` to shape your product idea into a structured concept
+2. **Stress-test the concept (optional):** Run `/arn-spark-stress-interview`, `/arn-spark-stress-competitive`, `/arn-spark-stress-premortem`, `/arn-spark-stress-prfaq` to validate the concept, then `/arn-spark-concept-review` to apply findings
+3. **Define the architecture:** Run `/arn-spark-arch-vision` to choose technologies and design the system
+4. **Write use cases:** Run `/arn-spark-use-cases` (or `/arn-spark-use-cases-teams` for expert debate) to specify system behavior
+5. **Scaffold the project:** Run `/arn-spark-scaffold` to create the project skeleton
+6. **Validate risks:** Run `/arn-spark-spike` to test critical technical assumptions
+7. **Explore visual direction:** Run `/arn-spark-visual-sketch` to generate visual direction proposals and select a direction
+8. **Define the style:** Run `/arn-spark-style-explore` to translate the visual direction into a complete design system
+9. **Prototype:** Run `/arn-spark-static-prototype` and `/arn-spark-clickable-prototype` to validate the UI
+10. **Extract features:** Run `/arn-spark-feature-extract` to build the backlog
+
+When you are ready to transition from exploration to development: if you have the Arness Code plugin installed, run `/arn-planning` to start the development pipeline. Arness auto-configures code patterns, report templates, plans, and documentation directories on first use."
+
+---
+
+## Error Handling
+
+- **User cancels at any step:** Confirm cancellation and exit gracefully. Do not leave partially written configuration. If some directories were already created, inform the user they can be removed manually.
+- **Writing to arness.md fails:** Print the full `## Arness` config block in the conversation so the user can insert it manually. Suggest checking file permissions.
+- **`gh auth login` or `bkt auth login` not resolved:** Explain the issue and stop init. The user must resolve authentication before proceeding. They can re-run `/arn-spark-init` after fixing auth.
+- **Re-running is safe:** Step 1 detects the existing config and offers Update / Reconfigure / Keep. No data is lost on re-run.
+- **Arness Init run after Spark Init:** Fully supported. Arness Init's upgrade flow detects the existing greenfield fields and adds the missing development fields (Plans, Specs, Templates, Code patterns, Docs). Greenfield fields are preserved.

package/plugins/arn-spark/skills/arn-spark-init/references/agent-models-presets/all-opus.md

@@ -0,0 +1,23 @@
+# Profile: all-opus
+# Version: 1.0.0
+
+arn-spark-brand-strategist: opus
+arn-spark-dev-env-builder: opus
+arn-spark-doctor: opus
+arn-spark-forensic-investigator: opus
+arn-spark-marketing-pm: opus
+arn-spark-market-researcher: opus
+arn-spark-persona-architect: opus
+arn-spark-persona-impersonator: opus
+arn-spark-product-strategist: opus
+arn-spark-prototype-builder: opus
+arn-spark-scaffolder: opus
+arn-spark-spike-runner: opus
+arn-spark-style-capture: opus
+arn-spark-tech-evaluator: opus
+arn-spark-ui-interactor: opus
+arn-spark-use-case-writer: opus
+arn-spark-ux-judge: opus
+arn-spark-ux-specialist: opus
+arn-spark-visual-sketcher: opus
+arn-spark-visual-test-engineer: opus

package/plugins/arn-spark/skills/arn-spark-init/references/agent-models-presets/balanced.md

@@ -0,0 +1,23 @@
+# Profile: balanced
+# Version: 1.0.0
+
+arn-spark-brand-strategist: opus
+arn-spark-dev-env-builder: sonnet
+arn-spark-doctor: sonnet
+arn-spark-forensic-investigator: opus
+arn-spark-marketing-pm: opus
+arn-spark-market-researcher: opus
+arn-spark-persona-architect: opus
+arn-spark-persona-impersonator: sonnet
+arn-spark-product-strategist: opus
+arn-spark-prototype-builder: opus
+arn-spark-scaffolder: sonnet
+arn-spark-spike-runner: sonnet
+arn-spark-style-capture: sonnet
+arn-spark-tech-evaluator: opus
+arn-spark-ui-interactor: sonnet
+arn-spark-use-case-writer: sonnet
+arn-spark-ux-judge: opus
+arn-spark-ux-specialist: sonnet
+arn-spark-visual-sketcher: sonnet
+arn-spark-visual-test-engineer: sonnet

package/plugins/arn-spark/skills/arn-spark-init/references/bkt-setup.md

@@ -0,0 +1,55 @@
+# Bitbucket CLI (bkt) Setup
+
+The `bkt` CLI provides gh-like ergonomics for Bitbucket Cloud and Data Center. Arness uses it for all Bitbucket PR operations (create, list, merge, comment).
+
+**Repository:** https://github.com/avivsinai/bitbucket-cli
+
+## Installation
+
+Install `bkt` using one of the following methods:
+
+| Method | Command |
+|--------|---------|
+| pipx (recommended) | `pipx install bitbucket-cli` |
+| npm | `npm install -g bitbucket-cli` |
+| Binary download | See [releases](https://github.com/avivsinai/bitbucket-cli/releases) |
+
+## Authentication
+
+Authenticate with Bitbucket using `bkt auth login`:
+
+```bash
+bkt auth login
+```
+
+This opens a browser for OAuth authentication. Follow the prompts to authorize the CLI.
+
+### API Token (alternative)
+
+You can also authenticate via an API token set as an environment variable:
+
+```bash
+export BKT_TOKEN="your-api-token"
+```
+
+Generate an API token from your Bitbucket account settings under **Personal settings > API tokens**.
+
+> **Note:** Bitbucket App Passwords will be deprecated in June 2026. Use API tokens instead for new integrations.
+
+## Verification
+
+After installation and authentication, verify both are working:
+
+```bash
+bkt --version       # Confirm installation
+bkt auth status     # Confirm authentication
+```
+
+Both commands must succeed before Arness can use Bitbucket integration.
+
+## Notes
+
+- `bkt` supports both Bitbucket Cloud and Bitbucket Data Center
+- Arness currently targets Bitbucket Cloud only (Data Center is out of scope)
+- `bkt` supports JSON and YAML output formats, which Arness uses for structured data parsing
+- If `bkt` is not installed or not authenticated, Arness will skip Bitbucket platform detection during `/arn-spark-init` (or `/arn-code-init`)