@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-feature-extract/references/feature-backlog-template.md

@@ -0,0 +1,176 @@
+# Feature Backlog Index Template
+
+This template defines the structure for the feature backlog index document written by the `arn-spark-feature-extract` skill. The index is saved to `features/feature-backlog.md` under the project's Vision directory. Individual feature entries are saved as separate files (`F-NNN-kebab-name.md`) in the same `features/` directory.
+
+The index is a lightweight navigation and tracking document. It contains the Feature Tracker table (local source of truth for dependency resolution and status tracking), a Feature Index with links to individual feature files, journey mappings, and implementation ordering. The detailed feature content lives in the individual files.
+
+## Instructions for arn-spark-feature-extract
+
+When populating this template:
+
+- Generate the Feature Tracker table after finalizing all features -- it is the local source of truth for dependency resolution and issue tracking
+- The Feature Index table provides one row per feature with a relative link to the individual feature file
+- Group features by functional area in the Feature Index (matching the functional area grouping in individual files)
+- Include the journey-to-feature mapping table to ensure complete coverage
+- The Issue Body Template at the bottom defines the format for uploading features to GitHub/Jira
+- Individual feature files are written using the feature entry template (`feature-entry-template.md`) -- see that template for field-level guidance
+
+---
+
+## Template
+
+```markdown
+# [Product Name] - Feature Backlog
+
+Generated by `/arn-spark-feature-extract` on [date].
+
+## Summary
+
+| Priority | Count |
+|----------|-------|
+| Must-have | [N] |
+| Should-have | [N] |
+| Nice-to-have | [N] |
+| **Total** | **[N]** |
+
+**Journey coverage:** [N] of [M] user journeys fully mapped to features.
+**Feature files:** [N] individual feature files in this directory.
+
+## Feature Tracker
+
+[Local source of truth for dependency resolution and issue tracking. This table enables `/arn-code-pick-issue` to find unblocked features without network calls, and `/arn-code-ship` to update status after PRs are created.]
+
+| ID | Feature | Priority | Deps | Phase | Issue | Status |
+|----|---------|----------|------|-------|-------|--------|
+| F-001 | [Feature Name] | Must-have | None | Foundation | -- | pending |
+| F-002 | [Feature Name] | Must-have | F-001 | Foundation | -- | pending |
+| F-003 | [Feature Name] | Should-have | F-001, F-002 | Core | -- | pending |
+| ... | ... | ... | ... | ... | ... | ... |
+
+**Column definitions:**
+- **ID:** Feature identifier (F-NNN), matches the individual feature file
+- **Priority:** Must-have / Should-have / Nice-to-have
+- **Deps:** Comma-separated feature IDs that must be `done` before this feature can start, or `None`
+- **Phase:** Implementation phase from the Implementation Order Suggestion: Foundation, Core, Enhancement, or Polish
+- **Issue:** Issue tracker reference: GitHub issue number (`#42`), Jira key (`PROJ-42`), or `--` if not uploaded
+- **Status:** `pending` (not started), `in-progress` (being worked on), `done` (shipped), `decomposed` (XL feature split into sub-features by `arn-code-feature-spec` -- not directly pickable; parent is marked `done` when all sub-features are `done`)
+
+**Sub-feature rows (added by `arn-code-feature-spec` when decomposing XL features):**
+
+When `arn-code-feature-spec` decomposes an XL feature, it adds sub-feature rows to the Feature Tracker and sets the parent's status to `decomposed`. Sub-features use dot notation (`F-NNN.N`):
+
+| ID | Feature | Priority | Deps | Phase | Issue | Status |
+|----|---------|----------|------|-------|-------|--------|
+| F-005 | Ambient Portal Communication | Must-have | F-001, F-002 | Core | #42 | decomposed |
+| F-005.1 | Audio Pipeline | Must-have | F-001 | Core | #43 | pending |
+| F-005.2 | Signaling | Must-have | F-002 | Core | #44 | pending |
+| F-005.3 | Portal UI Integration | Must-have | F-005.1, F-005.2 | Core | #45 | pending |
+
+- Sub-feature IDs use the parent's ID with a dot suffix: `F-NNN.N`
+- Sub-feature priority inherits from the parent unless overridden during spec
+- Sub-feature deps can reference sibling sub-features (for ordering) or external features
+- The parent row's status is `decomposed` and its Issue column keeps the original parent issue reference
+- `/arn-code-pick-issue` skips `decomposed` rows and shows sub-features as pickable items
+- `/arn-code-ship` marks individual sub-features as `done`; when ALL sub-features of a parent are `done`, the parent is also marked `done`
+
+## Feature Index
+
+### [Functional Area 1]
+
+| ID | Feature | Priority | Complexity | File |
+|----|---------|----------|------------|------|
+| F-001 | [Feature Name] | Must-have | M | [F-001-feature-name.md](./F-001-feature-name.md) |
+| F-002 | [Feature Name] | Must-have | L | [F-002-feature-name.md](./F-002-feature-name.md) |
+
+### [Functional Area 2]
+
+| ID | Feature | Priority | Complexity | File |
+|----|---------|----------|------------|------|
+| F-003 | [Feature Name] | Should-have | M | [F-003-feature-name.md](./F-003-feature-name.md) |
+| ... | ... | ... | ... | ... |
+
+[Repeat for each functional area. For decomposed XL features, list the parent in its functional area, then sub-features grouped below:]
+
+| ID | Feature | Priority | Complexity | File |
+|----|---------|----------|------------|------|
+| F-005 | Ambient Portal Communication | Must-have | XL | [F-005-ambient-portal.md](./F-005-ambient-portal.md) |
+| F-005.1 | -- Audio Pipeline | Must-have | M | (spec: `FEATURE_F-005.1_audio-pipeline.md`) |
+| F-005.2 | -- Signaling | Must-have | M | (spec: `FEATURE_F-005.2_signaling.md`) |
+| F-005.3 | -- Portal UI Integration | Must-have | L | (spec: `FEATURE_F-005.3_portal-ui.md`) |
+
+## Journey-to-Feature Mapping
+
+[Maps each user journey to the features that implement it. Ensures no journey is left without implementing features and no feature is orphaned from a journey.]
+
+| Journey | Steps | Features |
+|---------|-------|----------|
+| [Journey name] | [total steps] | F-001, F-003, F-007 |
+| [Journey name] | [total steps] | F-002, F-004 |
+| ... | ... | ... |
+
+**Unmapped journeys:** [Any journeys not fully covered by features -- these represent gaps]
+**Orphaned features:** [Any features not referenced by any journey -- these may be infrastructure or may indicate missing journeys]
+
+## Implementation Order Suggestion
+
+[A suggested sequence for implementing features, considering dependencies, priorities, and journey completeness. This is a recommendation, not a mandate. The Phase column in the Feature Tracker is derived from this section.]
+
+1. **Foundation:** [Features that establish core infrastructure, typically must-haves with no dependencies. These enable other features but may not complete any journey on their own.]
+2. **Core experience:** [Features that deliver the primary user value. Completing this phase should make at least the main user journey functional end-to-end.]
+3. **Enhancement:** [Should-have features that round out the experience. Additional journeys become functional.]
+4. **Polish:** [Nice-to-have features that add refinement.]
+
+## Deferred Items
+
+[Items that came up during extraction but were explicitly excluded from the backlog. These are not features for v1 -- they are noted here for future reference.]
+
+| Item | Reason for Deferral | Revisit When |
+|------|-------------------|--------------|
+| [Item] | [Why it is not in v1] | [Condition that would trigger reconsideration] |
+```
+
+---
+
+## Issue Body Template
+
+When uploading features as issues to GitHub/Jira (Step 7 of `arn-spark-feature-extract`), use this lean template for the issue body. Include repo links so the full detail is always accessible from the issue. The issue body matches the lean F-NNN file -- it does not expand UC content inline.
+
+Read the content from the individual feature file. Construct repo links using the platform and repo URL from the `## Arness` config in arness.md.
+
+```markdown
+### F-[NNN]: [Feature Name]
+
+**Priority:** [Must-have / Should-have / Nice-to-have]
+**Complexity:** [S / M / L / XL]
+**Phase:** [Foundation / Core / Enhancement / Polish]
+**Dependencies:** [F-NNN: Name (ISSUE-KEY), ... / None]
+
+#### Description
+[Full description from feature file]
+
+#### Journey Summary
+[Brief journey summary from feature file -- 2-3 sentences, not full steps]
+
+#### Acceptance Criteria
+[Full acceptance criteria from feature file]
+
+#### Components
+[Library and product-specific components with references]
+
+#### Technical Notes
+[Technical notes from feature file]
+
+---
+
+**Full detail:** [Feature file](REPO-BROWSE-URL/[vision-dir]/features/F-NNN-name.md)
+**Use cases:** [UC-NNN: Title](REPO-BROWSE-URL/[use-cases-dir]/UC-NNN-name.md), [UC-NNN: Title](REPO-BROWSE-URL/[use-cases-dir]/UC-NNN-name.md)
+
+*Generated by `/arn-spark-feature-extract` from the feature backlog.*
+```
+
+**Repo link construction:**
+- Read Platform from `## Arness` config: `github`, `bitbucket`, or `none`
+- For GitHub: `https://github.com/<owner>/<repo>/blob/main/`
+- For Bitbucket: `https://bitbucket.org/<workspace>/<repo>/src/main/`
+- Append the relative path to the feature file or UC file
+- If platform is `none` or URL cannot be determined: omit repo links, add "See local files for full detail." instead

package/plugins/arn-spark/skills/arn-spark-feature-extract/references/feature-entry-template.md

@@ -0,0 +1,209 @@
+# Feature Entry Template
+
+This template defines the structure for individual feature files written by the `arn-spark-feature-extract` skill. Each feature is saved as a separate file (`F-NNN-kebab-name.md`) in the `features/` directory under the project's Vision directory.
+
+A feature entry captures lean context -- description, journey summary, UI behavior unique to the feature, validated components, use case references, debate insights, technical notes, and acceptance criteria -- with references to upstream UC documents. `arn-code-feature-spec` expands these references at spec time by reading the referenced UC documents directly, so feature files avoid duplicating UC content.
+
+## Instructions for arn-spark-feature-extract
+
+When populating this template for each feature:
+
+- Extract the feature from ALL available artifacts: product concept, architecture vision, style brief, spike results, static prototype results (including showcase), clickable prototype results (including showcase and screen manifest), use cases (including postconditions and business rules), user journey definitions, debate reports (from teams variants), and visual grounding assets
+- Each feature should be a user-facing capability, not a technical task (e.g., "Voice communication between paired devices" not "Implement WebRTC peer connection")
+- **Journey summary, UI behavior, and components are mandatory fields** -- journey summary captures the user flow briefly with UC references; UI behavior describes only interactions unique to this feature (not already described in the UC); components list the validated building blocks
+- Priority must be justified -- not every feature is must-have
+- Complexity estimates are relative within the project (S/M/L/XL) and based on the architecture vision's stack
+- The "Source" field tracks where the feature was identified, for traceability
+- Features marked "Ready for spec: Yes" must have description, journey summary (with UC references), UI behavior, and components filled in with enough detail for `arn-code-feature-spec` to start (it will read the referenced UC documents for full behavioral detail)
+- XL features should be flagged for decomposition -- either split into separate backlog features, or if the UX specialist determines it is one coherent user-facing capability, kept whole with a `## Decomposition Hints` section providing suggested sub-feature boundaries for `arn-code-feature-spec` to decompose at spec time
+- When use cases exist, reference them with step ranges and BR identifiers -- do not inline postconditions or business rules verbatim (arn-code-feature-spec reads the UC documents directly at spec time)
+
+---
+
+## Template
+
+```markdown
+# F-[NNN]: [Feature Name]
+
+**Priority:** [Must-have / Should-have / Nice-to-have]
+**Complexity:** [S / M / L / XL]
+**Phase:** [Foundation / Core / Enhancement / Polish]
+**Dependencies:** [F-NNN, F-NNN / None]
+**Status:** pending
+
+## Description
+
+[2-4 sentences describing what the feature does from the user's perspective. What can the user do that they could not do before? What problem does it solve?]
+
+## Journey Steps
+
+[Brief summary of the user journey this feature covers (2-3 sentences), with references to UC documents for full step-by-step detail:]
+
+**Journey: [Journey Name]**
+[2-3 sentence summary of what happens in this journey segment. E.g., "User discovers peers via mDNS, selects one, sends a pairing request, and upon acceptance exchanges Ed25519 identities to establish a permanent pairing."]
+**UC references:** UC-NNN steps N-M, UC-NNN
+
+[If the feature spans multiple journeys, list each with a brief summary and UC references. If no UC exists for this feature, provide 3-5 inline step descriptions instead.]
+
+## UI Behavior
+
+[Describe only the UI interactions and visual details that are unique to this feature and NOT already described in the referenced UC documents. Focus on:]
+
+- [Prototype-specific details: animations, transitions, visual effects not in the UC]
+- [Component-level interactions: how specific UI components behave (hover states, expand/collapse, etc.)]
+- [Feedback mechanisms: sounds, haptic, toast notifications, loading states]
+- [Edge case UI states: empty states, error states, disabled states]
+- [Layout and positioning details from the prototype that the UC does not specify]
+
+[If the UC's Main Success Scenario already describes the core flow, do not rewrite it here. Reference it: "Core flow follows UC-NNN steps N-M. Additional UI details:"]
+
+## Components
+
+[Validated UI components this feature uses, split by tier:]
+
+- **Library:** [Component name] ([variants]) -- [static showcase reference]. E.g., "Button (primary, secondary) -- static showcase v3 section 3"
+- **Library:** [Component name] ([variants]) -- [static showcase reference]
+- **Product-specific:** [Component name] -- [clickable screen reference]. E.g., "DeviceListItem -- clickable v2 screen 04-main-dashboard"
+
+[If no prototypes exist: "None -- no validated components available"]
+
+## Animation
+
+[Animation behaviors for this feature, described in platform-agnostic intent language. Reference the style brief's Animation and Motion section for the motion design system.]
+
+- [e.g., "Scroll-triggered card stagger entrance, 0.15s delay between cards — validated in clickable v2 screen 03"]
+- [e.g., "State transition: status change fades between states over 200ms ease-in-out"]
+- [Or "None — this feature has no animation requirements"]
+
+**Core or decorative:** [Is animation core to this feature's UX (removing it degrades the experience) or purely decorative (removing it has no functional impact)?]
+
+[If no style brief Animation section exists: omit this section entirely.]
+
+## Priority Rationale
+
+[Why this priority. Must-haves: core experience collapses without it. Should-haves: significantly improves the experience. Nice-to-haves: polish or convenience.]
+
+## Complexity Notes
+
+[Brief explanation of what drives the complexity. E.g., "M -- straightforward UI but requires mDNS integration" or "L -- multiple screens with real-time state updates across peers"]
+
+## Technical Notes
+
+[Relevant technical context from architecture vision and spike results. E.g., "WebRTC getUserMedia validated in spike-001. Uses mDNS for discovery (validated). Requires Ed25519 keypair for identity." Or "Spike-003 showed WKWebView has limited Notification API -- use Tauri notification plugin instead."]
+
+## Source
+
+[Which artifact(s) this was extracted from: product-concept, architecture-vision, spike-results, prototype screen name, journey name, use-case UC-NNN, user input]
+
+## References
+
+**Prototype:** [Which prototype screens show this feature. E.g., "Clickable prototype v3: screens /pairing, /pairing/confirm. Journey screenshots: prototypes/clickable/v3/journeys/device-pairing/"]
+**Showcase:** [Which showcase sections show this feature's screens/components. E.g., "Static showcase v3: sections 3 (Buttons), 5 (Inputs). Clickable showcase v2: screens 01-hub, 04-main-dashboard." Or "None"]
+**Visual target:** [Implementation precision for this feature's visual appearance:]
+- `Design assets` -- design mockups exist in visual grounding `designs/` matching this feature's screens. Implementation should aim for pixel-level fidelity.
+- `Reference alignment` -- reference images exist in visual grounding `references/` setting the direction. Implementation should match the feel, not pixel-perfect.
+- `Style brief only` -- no visual grounding assets for this feature. Implementation follows style brief text specifications.
+
+## Debate Insights
+
+[Key expert findings from debate reports (static-prototype-teams, clickable-prototype-teams, use-cases-teams) relevant to this feature. E.g., "UX specialist noted pairing flow needs inline error messages (round-2 cross-review). Business reviewer agreed and added: must show device name in error context." Or "None"]
+
+## Use Case Context
+
+**References:** [UC-IDs this feature implements, with relationship and step ranges. E.g., "Implements UC-001 Device Pairing (steps 1-6). Includes UC-005 Device Discovery." Or "None"]
+**Postconditions:** See UC-NNN Postconditions [or "None" if no use cases exist]
+**Business rules:** See UC-NNN Business Rules (BR-1 through BR-N) [or "None" if no use cases exist]
+
+[If the feature adds business rules BEYOND what the UC defines, inline only those additional rules here:]
+- [BR-N+1: Additional rule not in the UC. E.g., "Portal materialization animation must complete before audio pipeline starts."]
+
+## Acceptance Criteria
+
+[3-5 testable conditions that define when this feature is complete. Derived from journey steps, prototype behavior, and use case postconditions.]
+
+- [ ] [Criterion 1 -- e.g., "User can see available devices within 3 seconds of opening the pairing screen"]
+- [ ] [Criterion 2 -- e.g., "Selected device shows confirmation dialog before connecting"]
+- [ ] [Criterion 3 -- e.g., "Connected device appears in the main device list with status indicator"]
+
+## Decomposition Hints
+
+[Only for XL features kept whole in the backlog. Omit this section entirely for S/M/L features.]
+
+[When the UX specialist or user decides an XL feature should stay as one coherent user-facing capability (not split into separate backlog features), provide decomposition hints so `arn-code-feature-spec` can split it into implementation sub-features at spec time.]
+
+**Suggested sub-features:**
+
+1. **[Sub-feature name]** -- [1 sentence describing the implementation slice]
+   - Journey segment: [which UC steps this covers]
+   - Key components: [which components from the Components section apply]
+
+2. **[Sub-feature name]** -- [1 sentence]
+   - Journey segment: [steps]
+   - Key components: [components]
+
+3. **[Sub-feature name]** -- [1 sentence]
+   - Journey segment: [steps]
+   - Key components: [components]
+
+**Split rationale:** [Why this decomposition. E.g., "Each sub-feature targets a distinct technical domain (audio, signaling, UI) while the user experience is one coherent capability."]
+
+**Dependencies between sub-features:** [E.g., "Sub-feature 1 (audio pipeline) must complete before sub-feature 3 (UI integration) can start. Sub-feature 2 (signaling) is independent."]
+
+## Spec Readiness
+
+**Ready for spec:** [Yes / No]
+
+[If No, note what is missing.]
+```
+
+---
+
+## Priority Definitions
+
+| Priority | Definition | Test |
+|----------|-----------|------|
+| Must-have | The core experience cannot function without this feature | If removed, does the product still deliver its primary value? If not, it is must-have. |
+| Should-have | The experience is significantly degraded without this feature | Users would notice and be frustrated by its absence, but the product still works. |
+| Nice-to-have | Adds polish, convenience, or secondary value | The product is complete without it; this makes it better. |
+
+## Complexity Definitions
+
+| Size | Scope | Typical characteristics |
+|------|-------|----------------------|
+| S | Single component or minor change | One file or a few lines in 2-3 files. Clear implementation path. No new dependencies. Consider merging into a parent feature if too thin. |
+| M | Feature within a single domain | Multiple files in one area. May require a new dependency or integration point. Maps to 1-2 journey segments. |
+| L | Feature spanning multiple domains | Touches multiple parts of the stack (UI + backend, or multiple services). Requires design decisions. Maps to a full journey. |
+| XL | Major feature or infrastructure | New subsystem, complex protocol implementation, or architectural change. **Should be decomposed** into smaller features before speccing, OR kept whole with `## Decomposition Hints` if the UX specialist determines it is one coherent user-facing capability -- `arn-code-feature-spec` decomposes at spec time. Maps to multiple journeys. |
+
+## Spec Readiness Criteria
+
+A feature is **ready for spec** when ALL of the following are true:
+
+1. **Description** is 2-4 sentences covering what the user can do
+2. **Journey steps** include at least one journey with actual step descriptions
+3. **UI behavior** describes the key interactions with transition details and feedback
+4. **Components** lists the validated library and product-specific components used
+5. **Technical notes** capture any relevant spike results, validated capabilities, or known limitations
+6. **Acceptance criteria** list 3-5 testable conditions
+7. **Use case references** are listed with step ranges if use cases exist (arn-code-feature-spec reads UC documents at spec time)
+8. **Complexity** is not XL, OR if XL, a `## Decomposition Hints` section is present with at least 2 suggested sub-features (`arn-code-feature-spec` decomposes at spec time)
+9. **Animation** (if style brief has Animation and Motion section) describes the feature's animation behaviors in platform-agnostic intent language, with core/decorative classification
+
+If any of these are missing, mark "Ready for spec: No" and note what is needed.
+
+## UI Behavior Writing Guide
+
+The UI behavior field should describe only the interactions and visual details that are **unique to this feature** and not already covered by the referenced UC documents. The UC's Main Success Scenario and Extensions describe the core user flow -- do not rewrite them here.
+
+Focus on:
+
+- **Prototype-specific details:** Animations, transitions, visual effects that the UC text does not describe
+- **Component interactions:** How specific UI components behave (hover states, expand/collapse, inline editing)
+- **Feedback mechanisms:** Sounds, haptic, toast notifications, loading indicators
+- **Edge case UI states:** Empty states, disabled states, error display styles
+- **Layout and positioning:** Where elements appear on screen, how they stack or overlay
+
+If the UC already describes the core flow well, reference it and add only the unique UI layer:
+
+Example:
+> Core flow follows UC-002 steps 1-10. Additional UI details: Scanning indicator animates while mDNS discovery runs. Discovered devices appear in real-time as PairingCard entries. Portal materialization: fade-in with frosted-glass appearance, brief pulse, settles into ambient state.

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

@@ -0,0 +1,149 @@
+---
+name: arn-spark-help
+description: >-
+  This skill should be used when the user says "spark help", "arn spark help",
+  "greenfield status", "greenfield help", "where am I in spark", "what's next for spark",
+  "spark pipeline", "spark status", "arn-spark-help", "show spark pipeline",
+  "what step am I on for spark", "spark workflow", "exploration status",
+  "show exploration pipeline", "how does spark work", "explain spark pipeline",
+  or wants to see their current position in the
+  Arness Spark exploration pipeline and get guidance on the next step.
+version: 1.0.0
+---
+
+# Arness Spark Help
+
+Detect the user's current position in the Arness Spark exploration pipeline, render a diagram with the active stage marked, and suggest the next command to run. Supports cross-plugin awareness — detects activity in Arness Code and Arness Infra and provides hints at the bottom of the output. This skill is strictly read-only — it never modifies files or project state.
+
+**Allowed tools:** Read, Glob, Grep only. This skill MUST NOT use Write, Edit, Bash, or Task tools. This skill MUST NOT invoke any agents.
+
+## Workflow
+
+### Step 0: Multi-Plugin Awareness
+
+1. Read the project's `arness.md` file.
+2. Extract the `## Arness` section.
+3. Detect other plugin field groups:
+   - **code_fields_present**: true if `Plans directory` OR `Specs directory` present in `## Arness`
+   - **infra_fields_present**: true if `Infra plans directory` OR `Infra specs directory` present in `## Arness`
+4. For each detected plugin, do a quick existence check (max 2 files):
+   - **Code**: Check if `<Specs directory>` contains any `FEATURE_*.md` or `BUGFIX_*.md`, OR `<Plans directory>` has any subdirectories
+   - **Infra**: Check if `<Infra plans directory>` has any subdirectories, OR if `Dockerfile` or `docker-compose.yml` exists in the project root
+5. Record `{ plugin_name, has_activity: bool }` for each detected plugin.
+6. Proceed to Step 1. The cross-plugin hints are appended AFTER own status is rendered in Step 3.
+
+---
+
+### Step 1: Load Configuration
+
+1. From the `## Arness` section, extract **Spark fields**:
+   - **Vision directory** (e.g., `.arness/vision/`)
+   - **Use cases directory** (e.g., `.arness/use-cases/`)
+   - **Prototypes directory** (e.g., `.arness/prototypes/`)
+   - **Spikes directory** (e.g., `.arness/spikes/`)
+   - **Visual grounding directory** (e.g., `.arness/visual-grounding/`)
+   - **Reports directory** (e.g., `.arness/reports/`)
+
+**If `## Arness` is missing or no Spark fields present:** Show the Spark pipeline diagram with all stages unmarked. Suggest `/arn-brainstorming` to start a new greenfield project. Do not attempt detection.
+
+---
+
+### Step 2: Detect Pipeline Position
+
+Read the pipeline reference file at `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-help/references/pipeline-map.md` to load detection rules, rendering templates, and next-step tables.
+
+Check from most advanced to least advanced — first match wins:
+
+1. **Feature backlog ready** (`gf-feature-extract`): `<vision-dir>/features/feature-backlog.md` exists
+2. **Prototype locked** (`gf-prototype-lock`): `<prototypes-dir>/locked/LOCKED.md` exists
+3. **Clickable prototype done** (`gf-clickable-proto`): `<prototypes-dir>/clickable/final-report.md` exists
+4. **Static prototype done** (`gf-static-proto`): `<prototypes-dir>/static/final-report.md` exists
+5. **Style defined** (`gf-style-explore`): `<vision-dir>/style-brief.md` exists
+6. **Visual direction chosen** (`gf-visual-sketch`): `<vision-dir>/visual-direction.md` exists
+7. **Spike complete** (`gf-spike`): `<vision-dir>/spike-results.md` exists
+8. **Scaffold built** (`gf-scaffold`): `<vision-dir>/scaffold-summary.md` exists
+9. **Use cases written** (`gf-use-cases`): At least one `UC-*.md` file exists in `<use-cases-dir>/`
+10. **Architecture defined** (`gf-arch-vision`): `<vision-dir>/architecture-vision.md` exists
+11. **Naming complete** (`gf-naming`): `<vision-dir>/naming-brief.md` exists OR `<reports-dir>/naming-report.md` exists
+12. **Concept reviewed** (`gf-concept-review`): `<reports-dir>/stress-tests/concept-review-report.md` exists
+13. **Stress tests run** (`gf-stress-test`): Any of `interview-report.md`, `competitive-report.md`, `premortem-report.md`, `prfaq-report.md` exists in `<reports-dir>/stress-tests/`
+14. **Product discovered** (`gf-discover`): `<vision-dir>/product-concept.md` exists
+15. **Spark initialized** (`gf-init`): Spark fields exist in `## Arness` but none of the above artifacts found
+
+**Spark complete:** If the detected stage is `gf-feature-extract`, Spark exploration is considered complete.
+
+---
+
+### Step 3: Render Pipeline Diagram
+
+Read the pipeline templates from `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-help/references/pipeline-map.md`.
+
+1. Place the `YOU ARE HERE` marker below the detected stage.
+2. Display the next-step suggestion from the next-step table.
+3. Spark is a single-track pipeline (no per-project subdirectories).
+
+**Own-plugin suggestions always come first.** After the pipeline diagram and next-step suggestion, append cross-plugin hints from Step 0:
+
+- If own plugin has activity: show own status first. If other plugins have activity, append 1-2 lines at the bottom:
+  ```
+  Other pipelines: Development (active) — `/arn-code-help` | Infrastructure (not started)
+  ```
+
+- If own plugin is idle (`gf-init`) but other plugins have activity: show own-plugin "ready to start" 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.
+  ```
+
+- When Spark pipeline is complete (`gf-feature-extract`): suggest transition:
+  ```
+  Spark exploration is complete. Next steps:
+  - Start developing features: `/arn-planning`
+  - Deploy infrastructure: `/arn-infra-wizard`
+  ```
+
+Keep output concise — the user wants a quick status check, not a wall of text.
+
+---
+
+### Step 4: Answer Follow-up Questions
+
+After presenting the pipeline status:
+
+1. Remain available for follow-up questions about the Spark pipeline, skill purposes, or workflow decisions.
+2. Reference `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-help/references/pipeline-map.md` for answers — do not re-scan the filesystem unless the user explicitly asks to refresh the detection.
+3. Keep answers brief and direct.
+
+Common questions the user might ask:
+- "What is Spark?" — Spark is the exploration phase for new projects. It takes a raw idea through structured discovery, validation, prototyping, and feature extraction before development begins.
+- "How do I run the full Spark pipeline?" — Run `/arn-brainstorming`, which walks through the entire exploration pipeline with guided decision gates.
+- "What are stress tests?" — Four adversarial lenses that test your product concept: synthetic user interviews, competitive gap analysis, pre-mortem failure analysis, and PR/FAQ stress testing.
+- "What is naming?" — A structured 4-step brand naming methodology: strategic foundation, creative generation, qualitative scoring, and due diligence with WHOIS domain checking.
+- "Can I skip stress tests?" — Yes, all stages are optional. The brainstorming wizard presents skip options at each gate.
+- "How do I transition to development?" — After feature extraction, run `/arn-planning` in the project. Arness Code sets up automatically on first use.
+- "Where is the development pipeline status?" — Run `/arn-code-help` for the Arness Code development pipeline.
+- "Where is infrastructure status?" — Run `/arn-infra-help` for the Arness Infra infrastructure pipeline.
+- "What are the entry points?" — `/arn-brainstorming` is the main Spark entry point. For development: `/arn-planning`. For infrastructure: `/arn-infra-wizard`.
+- "What is dev-setup?" — `/arn-spark-dev-setup` is a standalone skill for defining or onboarding to a development environment (dev containers, Docker, CI workflows). It can be run at any time after greenfield config exists.
+- "What is visual-strategy?" — `/arn-spark-visual-strategy` sets up layered visual regression testing infrastructure (capture scripts, baselines, comparison pipelines). Requires scaffold and at least style-explore to be complete.
+- "What is visual-readiness?" — `/arn-spark-visual-readiness` validates and activates deferred visual testing layers after project milestones. Requires a visual strategy to be defined first.
+
+---
+
+## Error Handling
+
+- **`## Arness` section not found in arness.md** — Show the Spark pipeline diagram with no stage marked. Suggest running `/arn-brainstorming` to start a new greenfield project.
+- **arness.md does not exist** — Same as `## Arness` not found.
+- **Spark fields present but directories don't exist** — Treat as `gf-init` stage. The directories may not have been created yet.
+- **Pipeline reference file not found** — Inform the user that the pipeline-map.md reference is missing and suggest reinstalling or updating the Arness Spark plugin.
+- **Reports directory not configured** — Skip stress-test, concept-review, and naming detection (these stages require the Reports directory). Proceed with detection from `gf-arch-vision` downward.
+
+## Constraints
+
+- This skill MUST NOT write or modify any files.
+- This skill MUST NOT invoke any agents.
+- All tools used must be read-only: Read, Glob, Grep.
+- All command suggestions must use bare skill names (e.g., `/arn-spark-discover`, `/arn-code-help`). Do not use the fully qualified `plugin:skill` format in user-facing text.