arn-code-feature-spec-teams

Arness Feature Spec Teams

Develop a feature idea through structured debate between specialist teammates — architects and UX experts — before synthesizing a specification. Uses Claude Code's experimental Agent Teams feature for direct inter-agent communication. Each teammate proposes, critiques, and revises independently, producing a richer spec than a single-agent approach.

Pipeline position:

arn-code-feature-spec-teams (team: propose -> critique -> revise -> resolve) -> /arn-code-plan

This is an alternative to arn-code-feature-spec (single-agent). Use this when:

• The feature is complex enough to benefit from multiple perspectives
• There is a significant UI/UX component that needs specialist advocacy
• Multiple architectural approaches are viable and warrant debate
• You want trade-offs and disagreements surfaced explicitly

Prerequisites

If no ## Arness section exists in the project's CLAUDE.md, inform the user: "Arness is not configured for this project yet. Run /arn-planning to get started — it will set everything up automatically." Do not proceed without it. For standard single-agent feature spec, use arn-code-feature-spec instead.

Limitations compared to arn-code-feature-spec:

• XL feature decomposition is not supported. Use arn-code-feature-spec for features that need to be broken into sub-features.
• Draft file management is not supported. If the session crashes, re-run the skill from the beginning.

Workflow

Step 1: Check Agent Teams Availability

Run via Bash: echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

If the variable is NOT set to "1": Inform the user: "This skill requires Claude Code's experimental Agent Teams feature."

Provide setup instructions:

• Add to ~/.claude/settings.json under "env":

``json "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" ``

• Or set the environment variable before running Claude Code:

``bash CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude ``

Suggest the alternative: "You can use /arn-code-feature-spec instead, which uses a single architect agent and doesn't require Agent Teams."

If enabled: proceed to Step 1b.

Step 1b: Detect Greenfield Context (Optional)

This step activates only when greenfield artifacts exist. Projects without greenfield skip this step silently.

1. Check the trigger message for an F-NNN pattern (regex: F-\d{3}). Accept natural invocations like "feature spec teams F-002" or "team spec: Device Pairing".

1. If detected, or if conversation context includes feature file content (look for markers: ## Description, ## Journey Steps, ## Acceptance Criteria):

> Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-feature-spec/references/greenfield-loading.md for the full loading sequence.

Execute the loading sequence to load:

• Feature file (F-NNN) with description, journey steps, UI behavior, components, acceptance criteria
• Referenced UC documents (main success scenarios, extensions, business rules)
• Scope boundary context (related features from Feature Tracker for cross-feature awareness)
• Style-brief (if available at [vision-dir]/style-brief.md — toolkit configuration, color tokens, typography)

If the style-brief has an "Animation and Motion" section, extract it as animation context. This will be passed to both the architect and UX specialist teammates.

1. Hold all loaded context for use in Step 4 (teammate spawn prompts).

1. If no F-NNN pattern detected and no feature file markers found: proceed to Step 2 as normal (standard flow).

Step 2: Capture Feature Idea and Load Context

1. If the user provided the feature idea in the trigger message, use it directly. Otherwise, ask.

1. Read the project's CLAUDE.md and extract the ## Arness section to find:
2. Code patterns -- path to the directory containing stored pattern documentation
3. Specs directory -- path to the directory containing specification files

1. Read the stored pattern documentation:
2. <code-patterns-dir>/code-patterns.md
3. <code-patterns-dir>/testing-patterns.md
4. <code-patterns-dir>/architecture.md
5. <code-patterns-dir>/ui-patterns.md (if it exists)
6. <code-patterns-dir>/security-patterns.md (if it exists)

If pattern documentation files are missing (no code-patterns.md, testing-patterns.md, or architecture.md in the Code patterns directory):

Inform the user: "This is the first time pattern documentation is being generated for this project. Analyzing your codebase to understand its patterns, conventions, and architecture. This is a one-time operation — future invocations will use the cached results."

Then invoke the arn-code-codebase-analyzer agentto generate fresh analysis. Write the results to the Code patterns directory.

1. If greenfield context was loaded in Step 1b, also extract from ## Arness:
2. Vision directory (for style-brief and feature files)
3. Use cases directory (for UC documents)
4. Prototypes directory (for screen references)

Step 3: Classify Feature and Determine Team Composition

Use three-axis detection to determine the right team:

Axis 1 — Project frontend state:

• Check if ui-patterns.md exists in the code patterns directory
• Check the Technology Stack table in architecture.md for frontend framework entries (React, Vue, Svelte, Angular, Next.js, Nuxt, SvelteKit, etc.)
• Result: "has frontend" or "no frontend"

Axis 2 — Feature scope:

• Analyze the feature description for UI-related terms (component, page, form, button, layout, dashboard, UI, UX, screen, view, modal, dialog)
• If ambiguous, ask the user to confirm
• Result: "involves UI", "backend only", or "complex full-stack" (feature touches backend, frontend, and cross-cutting concerns)

Axis 3 — Security sensitivity:

• Check if security-patterns.md exists in the code patterns directory
• Analyze the feature description for security-relevant terms (auth, login, password, token,

payment, upload, API key, PII, encrypt, permission, session, cookie, CORS, CSRF, rate limit, secret, credential)

• If ambiguous, ask the user to confirm
• Result: "security sensitive" or "no security concerns"

Team composition matrix:

| Project state | Feature scope | Security | Team | Notes | |---|---|---|---|---| | Any | Backend only | No security | 2 architects | Pure architecture debate | | Any | Backend only | Security sensitive | 2 architects + 1 security specialist | Security joins for auth/data features | | Has frontend | Involves UI | No security | 1 architect + 1 UX specialist | UX references existing patterns | | Has frontend | Involves UI | Security sensitive | 1 architect + 1 UX specialist + 1 security specialist | Full-stack with security | | No frontend | Involves UI | No security | 1 architect + 1 UX specialist | UX in greenfield mode | | No frontend | Involves UI | Security sensitive | 1 architect + 1 UX specialist + 1 security specialist | Greenfield UI with security | | Has frontend | Complex full-stack | No security | 2 architects + 1 UX specialist | Three-way debate | | Has frontend | Complex full-stack | Security sensitive | 2 architects + 1 UX specialist + 1 security specialist | Four-way debate (cost warning) |

Present the proposed team to the user with token estimates:

• 2-person team: estimate 40k-100k tokens (lower end for focused features with quick convergence, upper end for complex features requiring multiple revision rounds)
• 3-person team: estimate 60k-250k tokens (same range factors, plus three-way coordination overhead)
• 4-person team: estimate 80k-300k tokens (include cost warning: "This is a large team. Consider whether security can be addressed during review-implementation instead.")

Ask (using AskUserQuestion):

**"Based on the feature, I'll create a team of [composition]. A typical arn-code-feature-spec session uses 20k-50k tokens; expect [40k-100k / 60k-250k] tokens f