@fredcallagan/arn-spark 5.1.0

package/plugins/arn-spark/skills/arn-spark-use-cases/references/use-case-index-template.md

@@ -0,0 +1,108 @@
+# Use Case Index Template
+
+This template defines the structure for the `use-cases/README.md` file written by the `arn-spark-use-case-writer` agent. This file serves as the entry point for the use case directory, providing an overview of the application's behavior, a complete actor catalog, a use case index with links, and a relationship diagram.
+
+## Instructions for arn-spark-use-case-writer
+
+When populating this template:
+
+- The introduction should summarize what the application does in 2-3 paragraphs, derived from the product concept but focused on system behavior (what it does), not identity (what it is)
+- The actor catalog must include every actor referenced in any use case file
+- The use case index must link to every UC file in the directory using relative paths
+- The use case diagram should show all actors and use cases with their relationships as a Mermaid `graph TB` diagram, with `click` directives linking to UC files. Keep the text relationship summary below for accessibility.
+- Coverage notes should honestly assess completeness -- note known gaps
+- Update this file whenever use cases are added, removed, or restructured
+
+---
+
+## Template
+
+```markdown
+# [Product Name] -- Use Cases
+
+## Introduction
+
+[2-3 paragraphs summarizing the application's behavioral scope. Describe what the system does from the actors' perspectives. Readers should understand the full range of behaviors the application supports from this introduction alone.
+
+Focus on behavior, not identity. Instead of "Talkie is a walkie-talkie app", write "The system enables real-time voice communication between devices on a local network. Users discover nearby devices, pair with them, and initiate voice calls with a single action. Optional video and text capabilities extend the core voice experience."]
+
+## Actor Catalog
+
+| Actor | Type | Description |
+|-------|------|-------------|
+| [Name] | Primary | [What this actor is, what they want from the system, and how they interact with it] |
+| [Name] | Secondary | [What this actor is and how it participates in interactions initiated by primary actors] |
+| [Name] | Supporting | [What this external system or service provides to the system] |
+
+**Actor types:**
+- **Primary:** Initiates interactions with the system to achieve a goal
+- **Secondary:** Participates in interactions initiated by primary actors (e.g., a paired device, another user)
+- **Supporting:** External systems or services that the system depends on (e.g., operating system, network)
+
+## Use Case Index
+
+| UC-ID | Title | Primary Actor | Level | Priority | File |
+|-------|-------|---------------|-------|----------|------|
+| UC-001 | [Title] | [Actor] | User Goal | Must-have | [UC-001-title.md](./UC-001-title.md) |
+| UC-002 | [Title] | [Actor] | User Goal | Must-have | [UC-002-title.md](./UC-002-title.md) |
+| UC-003 | [Title] | [Actor] | Subfunction | Should-have | [UC-003-title.md](./UC-003-title.md) |
+| ... | ... | ... | ... | ... | ... |
+
+## Use Case Diagram
+
+\`\`\`mermaid
+graph TB
+    %% Actors
+    Actor1((Actor Name))
+    Actor2((Actor Name))
+
+    %% Use Cases
+    UC001[UC-001: Title]
+    UC002[UC-002: Title]
+    UC003[UC-003: Title]
+    UC004[UC-004: Title]
+
+    %% Actor-UseCase connections
+    Actor1 --> UC001
+    Actor1 --> UC002
+    Actor2 -.participates.-> UC002
+
+    %% Relationships
+    UC001 -.includes.-> UC003
+    UC004 -.extends.-> UC001
+    UC001 -- follows --> UC002
+
+    %% Click links (relative paths to UC files)
+    click UC001 "./UC-001-title.md" "Open use case"
+    click UC002 "./UC-002-title.md" "Open use case"
+    click UC003 "./UC-003-title.md" "Open use case"
+    click UC004 "./UC-004-title.md" "Open use case"
+\`\`\`
+
+[Show ALL actors and ALL use cases with their relationships. Use `graph TB` (top-to-bottom) for the system-level overview. Include:
+- All actors as `((Actor Name))` circle nodes
+- All use cases as `[UC-NNN: Title]` rectangle nodes
+- Solid arrows `-->` for actor-to-use-case connections (primary actors)
+- Dotted arrows `-.participates.->` for secondary actor connections
+- Dotted arrows `-.includes.->` for includes relationships
+- Dotted arrows `-.extends.->` for extends relationships
+- Solid arrows `-- follows -->` for temporal ordering
+- `click` directives with relative file paths for every use case node
+- Remove any example nodes/lines that do not apply — only show actual actors, use cases, and relationships from the catalog]
+
+## Use Case Relationships
+
+[Text summary of relationships for accessibility and searchability. One line per use case with relationships:]
+
+- **UC-001 [Title]:** includes UC-003, extended by UC-004, follows → UC-002
+- **UC-002 [Title]:** includes UC-005, extended by UC-006
+- **UC-003 [Title]** (subfunction): included by UC-001, UC-002
+
+## Coverage Notes
+
+**Actors fully covered:** [List actors whose goals are all captured in use cases above]
+
+**Actors partially covered:** [List actors with known goals not yet captured, and what is missing]
+
+**Known gaps:** [Behaviors mentioned in the product concept or discussed with the user that are not yet written as use cases. Note why -- deferred, out of scope, or pending clarification.]
+```

package/plugins/arn-spark/skills/arn-spark-use-cases/references/use-case-template.md

@@ -0,0 +1,125 @@
+# Use Case Template
+
+This template defines the structure for individual use case documents written by the `arn-spark-use-case-writer` agent. Each use case is saved as a separate file in the `use-cases/` directory as `UC-NNN-kebab-case-title.md`.
+
+A use case describes a single, coherent interaction between an actor and the system to achieve a specific goal. It uses Cockburn's fully-dressed format for completeness while remaining technology-agnostic.
+
+## Instructions for arn-spark-use-case-writer
+
+When populating this template:
+
+- Every field below MUST appear in the output, even if the value is brief or "None"
+- Use cases are technology-agnostic: describe behavior ("The system displays"), not implementation ("The mDNS service queries")
+- Main success scenario steps follow actor-system alternation where natural: odd steps are actor actions, even steps are system responses (guideline, not rigid)
+- Extensions branch from a specific main scenario step and either rejoin the main flow or terminate
+- Preconditions must be verifiable states, not assumptions
+- Postconditions describe system state, not actor satisfaction
+- Business rules are constraints that govern the behavior within this use case
+- Screen references are optional -- include only when prototype screens exist and clearly correspond to a step
+- Priority and complexity should match the use case catalog agreed with the user
+- Related use cases should use the UC-ID format and note the relationship type (includes, extended by, follows, precedes, included by)
+
+---
+
+## Template
+
+```markdown
+# UC-[NNN]: [Title]
+
+**Primary Actor:** [The entity that initiates or primarily benefits from this use case]
+**Goal:** [What the primary actor wants to accomplish -- one sentence, verb-noun form]
+**Scope:** [The system boundary -- what system is being described]
+**Level:** [User Goal / Subfunction / Summary]
+
+## Use Case Diagram
+
+\`\`\`mermaid
+graph LR
+    Actor1((Primary Actor)) --> ThisUC[UC-NNN: Title]
+    Actor2((Secondary Actor)) -.participates.-> ThisUC
+    ThisUC -.includes.-> IncludedUC[UC-NNN: Included Title]
+    ExtendingUC[UC-NNN: Extending Title] -.extends.-> ThisUC
+    ThisUC -- follows --> NextUC[UC-NNN: Next Title]
+    click IncludedUC "./UC-NNN-included-title.md" "Open use case"
+    click ExtendingUC "./UC-NNN-extending-title.md" "Open use case"
+    click NextUC "./UC-NNN-next-title.md" "Open use case"
+\`\`\`
+
+[Show the primary actor, this use case, any secondary/supporting actors that participate, and all related use cases (includes, extended by, follows, precedes) as connected nodes. Include `click` directives with relative file paths for each related use case node. Remove any relationship lines that do not apply — only show relationships that exist in the Related Use Cases section. If this use case has no relationships, show only the primary actor connected to the use case node.]
+
+## Preconditions
+
+- [Verifiable state that must be true before this use case can begin]
+- [Each precondition on its own line]
+
+## Trigger
+
+[What event or actor action starts this use case]
+
+## Main Success Scenario
+
+1. [Actor action or system response]
+2. [Next step]
+3. [Continue with actor-system alternation where natural]
+4. [...]
+N. [Final step that achieves the goal]
+
+## Extensions
+
+**[Step]a. [Condition]:**
+1. [What happens when the condition is true]
+2. [Additional steps if needed]
+3. [Rejoin step N of main scenario / Use case ends in failure / Use case ends with partial success]
+
+**[Step]b. [Another condition at the same step]:**
+1. [What happens]
+2. [Rejoin step N / Use case ends]
+
+[Repeat for each extension point. Extensions are numbered from the main scenario step they branch from.]
+
+## Postconditions
+
+**Success guarantee:** [System state when the main success scenario completes successfully]
+**Minimal guarantee:** [System state preserved regardless of outcome -- what is always true after the use case ends, even on failure. Resources released, partial state cleaned up, etc.]
+
+## Business Rules
+
+- [BR-1: Constraint that governs behavior within this use case]
+- [BR-2: Another constraint]
+- [If none apply, write "None"]
+
+## Related Use Cases
+
+- **Includes:** [UC-NNN Title] -- [why this is included as a substep]
+- **Extended by:** [UC-NNN Title] -- [what optional behavior it adds]
+- **Follows:** [UC-NNN Title] -- [what typically happens after this use case]
+- **Precedes:** [UC-NNN Title] -- [what typically happens before this use case]
+- **Included by:** [UC-NNN Title] -- [which use case contains this one as a substep]
+- [If no relationships, write "None"]
+
+## Metadata
+
+- **Priority:** [Must-have / Should-have / Nice-to-have]
+- **Complexity:** [S / M / L / XL]
+- **Screen References:** [Summary list of prototype screen paths referenced in this use case, e.g., "setup/welcome, setup/pairing". Individual steps may also have inline screen annotations (e.g., "Screen: setup/welcome") where the system presents information. This field summarizes all referenced screens. "None" if no prototype screens exist.]
+```
+
+---
+
+## Section Guidance
+
+| Section | Guidance | Common Mistakes |
+|---------|----------|-----------------|
+| Use Case Diagram | Mermaid `graph LR` showing this UC's actor(s) and related UCs as linked nodes. Include `click` directives with relative `.md` file paths. Only show relationships that exist. | Including UCs that are not in the Related Use Cases section. Forgetting `click` directives. Using `graph TB`/`graph TD` for per-UC diagrams (use `graph LR` for horizontal layout; `TB` is reserved for the system-level index diagram). |
+| Primary Actor | The entity initiating the interaction. Always external to the system boundary. | Naming the system as actor. The system responds, it does not initiate use cases. |
+| Goal | One sentence, verb-noun form ("Pair with a new device", "Initiate a voice call") | Too vague ("Use the app") or too implementation-specific ("Send mDNS query") |
+| Scope | The system being described. Usually the application name. | Listing subsystems instead of the whole system boundary |
+| Level | User Goal = what a user sits down to do; Subfunction = a step reused by multiple user goals; Summary = spans multiple user goals | Defaulting everything to User Goal. If a use case is always invoked within another, it is likely a Subfunction. |
+| Preconditions | States that must be true BEFORE the trigger. Must be verifiable. | Including things that happen AS PART of the use case. "App is running" is a precondition. "User has opened settings" is a precondition only if the use case does not start by opening settings. |
+| Trigger | The specific event that starts the flow. One sentence. | Confusing the trigger with the first step of the main scenario. The trigger is what initiates; step 1 is the first action. |
+| Main Success Scenario | Happy path only, typically 4-12 steps. Actor-system alternation. | Including error handling (belongs in extensions). Steps that are too granular ("User moves cursor to button") or too vague ("System handles the request"). |
+| Extensions | Branch from a specific step number. Specify rejoin or termination. | Vague branching ("at any point") -- be specific about which step. Forgetting to specify where the extension rejoins or terminates. |
+| Postconditions | Observable system state after the use case ends. | Describing actor emotions ("User is satisfied") or vague outcomes ("Everything works"). State what is TRUE about the system. |
+| Business Rules | Constraints governing THIS use case specifically. | Generic rules not specific to this use case ("The system must be secure"). Business rules are concrete: "Maximum 8 participants per call", "Pairing requires physical proximity". |
+| Related Use Cases | Explicit relationship type with UC-ID. Bidirectional. | Listing related use cases without the relationship type. If UC-001 includes UC-005, then UC-005 must list "Included by UC-001". |
+| Screen References | Optional. Only when prototype screens exist. Relative paths. | Inventing screen references when no prototype exists. Screen references are enrichment, not required. |

package/plugins/arn-spark/skills/arn-spark-use-cases-teams/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: arn-spark-use-cases-teams
+description: >-
+  This skill should be used when the user says "use cases teams",
+  "arn use cases teams", "team use cases", "debate use cases",
+  "collaborative use cases", "use cases with debate",
+  "team-based use case review", "use case debate", "review use cases as a team",
+  or wants to create structured use case documents through expert debate
+  where product strategist and UX specialist review and discuss each other's
+  findings before revising, producing a use-cases/ directory with individual
+  Cockburn fully-dressed use case files and a README index.
+version: 1.0.0
+---
+
+# Arness Use Cases Teams
+
+Create structured use case documents in Cockburn fully-dressed format through a team debate process. The `arn-spark-use-case-writer` agent drafts, then `arn-spark-product-strategist` and `arn-spark-ux-specialist` (greenfield agents in this plugin) engage in a structured debate -- reviewing each other's findings, agreeing, disagreeing, and surfacing insights neither would find alone. Supports Agent Teams for parallel debate or sequential simulation as fallback. If `arn-spark-ux-specialist` is unavailable, the skill falls back to single-reviewer mode with product strategist only. This is a conversational skill that runs in normal conversation (NOT plan mode).
+
+This is an alternative to `arn-spark-use-cases` (independent sequential review). Use this when the project has enough complexity that expert debate adds value -- multiple actors, many use cases, or business rules that benefit from cross-disciplinary scrutiny. For simpler projects or lower token budgets, use `/arn-spark-use-cases` instead.
+
+The primary artifacts are a **use-cases/ directory** at the project root containing individual use case files (`UC-NNN-title.md`) and a **README.md** index -- the same output format as `/arn-spark-use-cases`. Additionally, mandatory **per-round debate reports** are saved to `use-cases/reviews/`.
+
+## Prerequisites
+
+Same prerequisites as `/arn-spark-use-cases`. Check in order:
+
+Determine the use cases output directory:
+1. Read the project's `arness.md` and check for a `## Arness` section
+2. If found, extract the configured Use cases directory path — this is the source of truth
+3. If no `## Arness` section exists or Arness Spark fields are missing, inform the user: "Arness Spark is not configured for this project yet. Run `/arn-brainstorming` to get started — it will set everything up automatically." Do not proceed without it.
+4. If the directory does not exist, create it
+
+> All references to `use-cases/` in this skill refer to the configured use cases directory determined above.
+
+**Product concept (strongly recommended):**
+1. Read the project's `arness.md` for a `## Arness` section. If found, look for a `Vision Directory` field and check that directory for `product-concept.md`
+2. If no `## Arness` section found, check `.arness/vision/product-concept.md` at the project root
+
+**If a product concept is found:** Use it as the primary source for actors, goals, and use case derivation.
+
+**If no product concept is found:** Ask the user: "No product concept found. I recommend running `/arn-spark-discover` first to define your product. Alternatively, describe your application's purpose, users, and main capabilities and I will work from that."
+
+**Architecture vision (optional):**
+1. Check the same Vision directory for `architecture-vision.md`
+2. If no `## Arness` section found, check `.arness/vision/architecture-vision.md` at the project root
+
+If found: use for understanding system capabilities, constraints, and platform scope.
+
+**Existing prototype screens (optional):**
+1. Read the configured Prototypes directory from the `## Arness` section (default: `.arness/prototypes`)
+2. Check for `[prototypes-dir]/clickable/` directories
+3. Check for `[prototypes-dir]/static/` directories
+
+If found: screen references can enrich use case steps with concrete screen paths.
+
+**Style brief is NOT needed.** Use cases describe behavior, not visual presentation.
+
+## Workflow
+
+### Step 1: Detect Resume or Fresh Start
+
+Check for existing use case output:
+
+1. Look for `use-cases/README.md` at the project root
+2. If found, scan for `use-cases/UC-*.md` files
+
+**If existing use cases found:**
+
+Ask the user:
+
+**"I found an existing use cases directory with [N] use case files. Which would you prefer?"**
+
+Options:
+1. **Continue** — I will read the existing use cases and offer to add new ones or revise existing ones
+2. **Fresh start** — I will begin from scratch (existing files will be overwritten)
+
+If continuing: read all existing use case files and the README. Present the current catalog to the user. Ask what they want to change, add, or revise. Skip to the appropriate step.
+
+**If no existing use cases:** Proceed to Step 2.
+
+### Step 2: Configure Debate Parameters
+
+1. Check for Agent Teams support (whether your platform supports it)
+2. Record the debate mode: "agent_teams" if supported, otherwise "sequential". **The mode selection is based ONLY on Agent Teams support. File-based review output works identically in both modes and does NOT affect mode selection. When Agent Teams is supported, always use Agent Teams mode.**
+3. Check `arn-spark-ux-specialist` availability by attempting to invoke it with a minimal prompt (e.g., "Respond with OK to confirm availability"). If the agent is not found or the invocation fails, record single-reviewer mode.
+
+Present the configuration:
+
+"**Debate configuration:**
+
+- **Debate mode:** [Agent Teams (parallel debate) / Sequential (simulated debate)]
+- **Reviewers:** arn-spark-product-strategist + arn-spark-ux-specialist [/ arn-spark-product-strategist only (UX specialist unavailable)]
+- **Max review rounds:** 2 (each round: expert debate + writer revision)
+
+Ask the user:
+
+**"Confirm debate configuration or adjust?"**
+
+Options:
+1. **Confirm** — Proceed with these settings
+2. **Adjust** — Change max review rounds (1-4) or other settings"
+
+If Agent Teams is not enabled, also note: "Agent Teams is not enabled. The debate will run sequentially (I will pass feedback between experts). Enable Agent Teams if your platform supports it. Alternatively, use `/arn-spark-use-cases` for independent sequential reviews (lower cost)."
+
+If `arn-spark-ux-specialist` is unavailable: "UX specialist is not available. Review will be strategist-only (no debate). Consider `/arn-spark-use-cases` which handles single-reviewer mode identically."
+
+Wait for user confirmation or adjustments.
+
+### Step 3: Identify Actors and Propose Use Case Catalog
+
+Load the product concept and extract actors and use cases. Read the base skill for the detailed actor and use case identification process:
+
+> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/SKILL.md` — follow its Step 2 (Identify Actors and Propose Use Case Catalog) for the actor extraction, use case derivation, level classification, and relationship mapping process.
+
+Present the actor catalog, proposed use case catalog, and relationship diagram as specified in that step. Wait for user confirmation or adjustments.
+
+### Step 4: Draft All Use Cases and Create Task List
+
+Draft use cases in parallel by invoking multiple `arn-spark-use-case-writer` agents simultaneously. Follow the same grouping strategy and invocation pattern as `/arn-spark-use-cases` Step 3:
+
+- Group use cases with direct includes/extends relationships into clusters
+- Each writer receives the FULL catalog for cross-reference awareness but only its assigned UC-IDs to draft
+- Each writer receives: product concept, actor catalog, full use case catalog, assigned UC-IDs, use case template (`${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/use-case-template.md`), output directory (`use-cases/`), prototype screens (if any), architecture vision (if available)
+- After all parallel writers complete, invoke one final writer to produce the README index using the index template (`${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/use-case-index-template.md`)
+
+Create the task list based on the configured max_rounds. For max_rounds=2:
+
+```
+Task 1: Draft all use cases
+Task 2: Expert review debate (Round 1)
+Task 3: Revise use cases (Round 1)
+Task 4: Expert review debate (Round 2)
+Task 5: Revise use cases (Round 2)
+Task 6: User review
+```
+
+Mark Task 1 as completed. Present the task list to the user in conversation and update it visually after each completed step. Present a brief summary: "**[N] use cases drafted.** Files written to `use-cases/`. Starting expert review debate."
+
+### Step 5: Expert Review Debate (Iterative)
+
+For each review round (up to max_rounds):
+
+Read the debate protocol:
+> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases-teams/references/debate-protocol.md`
+
+#### 5a: Debate
+
+Create the `[use-cases-dir]/reviews/` directory if it does not exist.
+
+**If debate_mode is "agent_teams":**
+
+Follow the Agent Teams Mode Invocation Detail in the debate protocol. Spawn both experts simultaneously as teammates. Each expert receives the expert review template path (`${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases/references/expert-review-template.md`) and a unique file path to write to (no file contention — each agent writes to a different file). Phase 1: both experts write independent reviews to their respective files in parallel. Phase 2: each expert reads the other's completed file and writes its cross-review to a separate file. File-based output works naturally with Agent Teams — do not fall back to sequential mode because of file output.
+
+**If debate_mode is "sequential":**
+
+Follow the Sequential Mode Invocation Detail in the debate protocol:
+
+1. Invoke `arn-spark-product-strategist` with all UC content, product concept, actor catalog, business review focus instructions, expert review template path, and file path to write to: `[use-cases-dir]/reviews/round-N-business-review.md`. The strategist writes its Phase 1 review to the file.
+2. Invoke `arn-spark-ux-specialist` with all UC content, product concept, screens (if any), flow review focus instructions, expert review template path, the business reviewer's file path to read (`[use-cases-dir]/reviews/round-N-business-review.md`), and file path to write to: `[use-cases-dir]/reviews/round-N-flow-review.md`. Instruct: "Review independently first using the Phase 1 format. Then read the business reviewer's review at the specified file path and respond to each finding using the Phase 2 cross-review format. Write your complete review (Phase 1 + Phase 2 combined) to the specified file path."
+3. Invoke `arn-spark-product-strategist` with the flow reviewer's file path to read (`[use-cases-dir]/reviews/round-N-flow-review.md`), expert review template path, and file path to write to: `[use-cases-dir]/reviews/round-N-business-cross-review.md`. Instruct: "Read the flow reviewer's review at the specified file path. Respond to their findings and their responses to your review using the Phase 2 cross-review format. Write your cross-review to the specified file path."
+
+**If arn-spark-ux-specialist is unavailable (single-reviewer mode):**
+
+Invoke `arn-spark-product-strategist` only with all UC content, business review focus instructions, expert review template path, and file path to write to: `[use-cases-dir]/reviews/round-N-business-review.md`. No cross-review phase. Note limitation.
+
+#### 5b: Synthesize Debate Report
+
+Read the review report template:
+> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases-teams/references/review-report-template.md`
+
+Read all expert review files written during Step 5a (never from conversation context):
+- `[use-cases-dir]/reviews/round-N-business-review.md` (Phase 1)
+- `[use-cases-dir]/reviews/round-N-flow-review.md` (Phase 1, or Phase 1 + Phase 2 combined in sequential mode)
+- `[use-cases-dir]/reviews/round-N-business-cross-review.md` (Phase 2, if it exists)
+- `[use-cases-dir]/reviews/round-N-flow-cross-review.md` (Phase 2, Agent Teams mode only, if it exists)
+
+Synthesize from all expert review files:
+- **Consensus:** Items both experts flagged, or one raised and the other agreed in cross-review
+- **Additions:** Items one expert raised that the other did not dispute
+- **Disagreements:** Items where experts explicitly disagreed and the disagreement persisted
+
+Save the report to `[use-cases-dir]/reviews/round-N-review-report.md`.
+
+#### 5c: Resolve Conflicts
+
+**If disagreements exist:** For each disagreement, present both positions and the trade-off summary, then ask:
+
+Ask the user:
+
+> **Expert disagreement on UC-[NNN] [Title]: [brief description]. Which direction?**
+> 1. **Business Reviewer's position** — [brief summary]
+> 2. **Flow Reviewer's position** — [brief summary]
+> 3. **Compromise** — I will describe a middle ground
+
+If the user chooses option 3, collect their compromise as free-form text. Update the report with all resolutions.
+
+**If no disagreements:** Skip this sub-step.
+
+#### 5d: Revise Use Cases
+
+Revise use cases in parallel using the same grouping strategy as Step 4. Each `arn-spark-use-case-writer` receives:
+- **Existing draft paths:** the current use case files for its assigned UC-IDs
+- **Combined debate report:** the "Recommended Changes for Writer" section, filtered to its assigned UCs (plus any cross-cutting changes that apply to all UCs)
+- **Use case catalog:** the FULL catalog (for cross-reference awareness)
+- **Use case template:** (same shared path)
+- **Output directory:** `use-cases/` (overwrites existing files)
+
+After all parallel writers complete, invoke one final writer to update the README index.
+
+#### 5e: Convergence Check
+
+Evaluate the debate report's convergence status using the convergence criteria defined in the debate protocol (`${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-use-cases-teams/references/debate-protocol.md`, Convergence Criteria section). The debate report's "Round recommendation" field provides a preliminary assessment — verify it against the full criteria.
+
+Present the round summary: "**Round [N] complete.** [M] use cases revised. [Summary of major changes]. [Convergence status: converged / another round needed]."
+
+If converged: skip remaining rounds, mark remaining debate+revision tasks as completed, proceed to Step 6.
+
+### Step 6: User Review
+
+Present the final use case catalog:
+
+"**Use case authoring complete.**
+
+**Summary:**
+- **Use cases:** [N] total ([X] user-goal, [Y] subfunction, [Z] summary)
+- **Actors:** [N] actors ([X] primary, [Y] secondary, [Z] supporting)
+- **Debate mode:** [Agent Teams / Sequential / Single-Reviewer]
+- **Review rounds:** [N] of [max_rounds]
+
+**Use Case Catalog:**
+| UC-ID | Title | Actor | Level | Priority | Status |
+|-------|-------|-------|-------|----------|--------|
+| UC-001 | [Title] | [Actor] | User Goal | Must-have | Final |
+| ... | ... | ... | ... | ... | ... |
+
+All files are in the `use-cases/` directory. Debate reports are in `use-cases/reviews/`.
+
+Ask the user:
+
+**"What would you like to do?"**
+
+Options:
+1. **Adjust a specific use case** — Tell me which one and what to change
+2. **Add new use cases** — I will extend the catalog
+3. **Proceed** — Use cases are complete"
+
+If the user wants adjustments: invoke `arn-spark-use-case-writer` with the specific use case and the user's change request.
+If the user wants new use cases: return to Step 3 with the additions (existing use cases are preserved).
+If the user is satisfied: proceed to Step 7.
+
+### Step 7: Write Final Report
+
+Write `use-cases/reviews/final-report.md` with:
+- Complete debate history across all rounds
+- Aggregated review arc: how findings evolved, what converged, what the user decided
+- Links to all per-round reports
+- Final convergence status
+- Summary statistics (total findings, consensus count, disagreement count, user decisions)
+
+### Step 8: Recommend Next Steps
+
+"Use cases saved to `use-cases/`. Debate reports saved to `use-cases/reviews/`.
+
+These use cases are now available as input for downstream skills:
+1. **Scaffold the project:** Run `/arn-spark-scaffold` to set up the development skeleton
+2. **Explore visual style:** Run `/arn-spark-style-explore` to establish the visual direction
+3. **Prototype the UI:** Run `/arn-spark-clickable-prototype` -- use cases will enrich screen derivation and replace manually defined journeys
+4. **Extract features:** Run `/arn-spark-feature-extract` -- use cases provide structured behavioral specs for richer feature extraction
+
+Use cases are living documents. As the project evolves, run `/arn-spark-use-cases-teams` again to add or revise them."
+
+## Agent Invocation Guide
+
+| Situation | Action |
+|-----------|--------|
+| Draft all use cases (Step 4) | Invoke multiple `arn-spark-use-case-writer` agents in parallel, each with full catalog + assigned UC subset. Then one final writer for the README index. |
+| Expert debate -- Agent Teams (Step 5a) | Spawn both experts simultaneously. Each gets expert review template path + file path to write to. Phase 1: write independent reviews to files. Phase 2: read each other's files, write cross-reviews to separate files. Follow debate protocol. |
+| Expert debate -- Sequential (Step 5a) | (1) Invoke strategist with UCs + business focus + file path to write to. (2) Invoke UX specialist with UCs + flow focus + strategist's file path to read + own file path to write to. (3) Invoke strategist with UX specialist's file path to read + cross-review file path to write to. Follow debate protocol. |
+| Expert debate -- UX unavailable (Step 5a) | Invoke strategist only with file path to write to. No debate phases. Note limitation in report. |
+| Synthesize debate report (Step 5b) | Skill reads all expert review files (not from conversation). Synthesizes and saves to `[use-cases-dir]/reviews/round-N-review-report.md`. |
+| Resolve conflicts (Step 5c) | Present each disagreement to user with both positions. Wait for decisions. Update report. |
+| Revise use cases (Step 5d) | Invoke multiple `arn-spark-use-case-writer` agents in parallel, each with its assigned UC drafts + debate report changes. Then one final writer for the README index. |
+| User requests specific UC adjustment (Step 6) | Invoke `arn-spark-use-case-writer` with the specific UC path and the user's change description |
+| User wants to add new use cases | Return to Step 3 with additions to the catalog |
+| User asks about technology choices | Defer: "Use cases describe behavior, not implementation. Technology choices are in `/arn-spark-arch-vision`." |
+| User asks about screen design | Defer: "Screen design is handled by `/arn-spark-style-explore` and `/arn-spark-clickable-prototype`. Use cases focus on what the system does, not how it looks." |
+| User asks about features | Defer: "Feature extraction happens in `/arn-spark-feature-extract`, which will consume these use cases as input." |
+| User asks about implementation specs | Defer: "Implementation specifications are created by `/arn-code-feature-spec` (requires arn-code plugin). Use cases provide the behavioral foundation that feature specs build on." |
+| Strategist returns vague review | Re-invoke with more specific prompt: "Review each use case individually. For each, provide at least one Critical or Minor feedback item with a specific observation and suggestion." |
+| UX specialist returns vague review | Re-invoke with more specific prompt focusing on flow analysis: "For each use case, assess the main scenario naturalness, step granularity, and identify at least one missing interaction pattern (cancel, timeout, retry, empty state)." |
+
+## Error Handling
+
+- **Agent Teams not enabled:** Fall back to sequential debate mode automatically. Inform user and offer `/arn-spark-use-cases` as lower-cost alternative.
+- **Expert unresponsive in Agent Teams mode:** Fall back to sequential mode for this round. Note the issue in the debate report.
+- **arn-spark-ux-specialist unavailable:** Single-reviewer mode. No debate, strategist reviews alone. Suggest `/arn-spark-use-cases` as equivalent for single-reviewer. Note limitation in all reports.
+- **No product concept found and user declines to describe:** Cannot proceed meaningfully. Suggest: "Run `/arn-spark-discover` first to define what you are building."
+- **Product concept is very brief:** Proceed but warn: "The product concept has limited detail. Use cases may be thin and need more revision."
+- **arn-spark-use-case-writer fails to write files:** Print the use case content in conversation so the user can copy it manually.
+- **Very large number of use cases (>15):** Warn the user: "This is a large number of use cases, which increases debate time and token cost. I recommend focusing on must-have use cases first."
+- **Debate loops without convergence at max_rounds:** Proceed to user review with remaining issues noted in the final report.
+- **No actors identified from product concept:** Ask the user directly: "I could not identify clear actors from the product concept. Who uses this application and what do they want to accomplish?"
+- **Review reports directory creation fails:** Print report content in conversation so the user can save it manually.
+- **User cancels mid-process:** Inform the user that partial use case files exist in `use-cases/` and any completed debate reports exist in `use-cases/reviews/`. They can resume later.
+- **User wants to add a use case during review (Step 5):** Accept the addition. Add it to the catalog and include it in the current or next writer invocation.
+- **Resume with corrupted or incomplete files:** Offer a fresh start. If the user wants to preserve partial work, read what exists and present it for the user to decide what to keep.