arn-spark-use-cases-teams

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 CLAUDE.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 CLAUDE.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 (using AskUserQuestion):

"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 via Bash: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
2. Record the debate mode: "agent_teams" if the value is "1", otherwise "sequential". The mode selection is based ONLY on this environment variable. File-based review output works identically in both modes and does NOT affect mode selection. When Agent Teams is enabled, 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 (using AskUserQuestion):

"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). For parallel debate, set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in ~/.claude/settings.json. 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/.