arn-code-feature-spec

Arness Feature Spec

Develop a feature idea into a well-formed specification through iterative conversation, aided by architectural analysis from the arn-code-architect agent and, when the feature involves UI, user experience design from the arn-code-ux-specialist agent. This is a conversational skill that runs in normal conversation (NOT plan mode). The primary artifact is a feature specification written to the project's specs directory that captures requirements, architectural assessment, and decisions from the exploration conversation. The spec then informs plan creation via the /arn-code-plan skill.

Step 0: Ensure Configuration

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md and follow its instructions. This guarantees a user profile exists and ## Arness is configured with Arness Code fields before proceeding.

Workflow

Step 1: Capture the Feature Idea

1a. Detect Backlog Feature (Greenfield Path)

Before asking the user to describe their feature, check if the trigger includes a greenfield feature backlog entry:

1. Check if the trigger message contains an F-NNN pattern (regex: F-\d{3}). Accept natural invocations like:
2. feature spec F-002
3. spec F-002: Device Pairing
4. feature spec: Device Pairing (fuzzy match against feature file names in the features directory)

1. Check if conversation context from arn-code-pick-issue includes feature file content (look for markers: ## Description, ## Journey Steps, ## Acceptance Criteria that indicate an F-NNN file was passed inline).

1. If either condition is met: extract the feature ID and proceed to Step 1b.

1. If neither condition is met: fall through to the standard flow below (ask the user to describe the feature).

1b. Load Greenfield Feature Context

Only runs when a backlog entry is detected in Step 1a. Loads the feature file, referenced UC documents, and scope boundary context (related features from the Feature Tracker) to provide rich context for the spec exploration. If any greenfield artifact is missing, falls back gracefully.

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

• 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.

1c. Detect XL Decomposition

Only runs after Step 1b successfully loads a greenfield feature.

1. Check if the loaded feature file has:
2. Complexity: XL
3. A ## Decomposition Hints section with at least 2 suggested sub-features

1. If both conditions are met: Set a flag: decomposition_mode = true. Hold the decomposition hints (suggested sub-features, split rationale, inter-dependencies) for use in Step 5. Inform the user:

"This is an XL feature with decomposition hints. I will create separate sub-feature specs (F-NNN.1, F-NNN.2, ...) instead of a single spec, each scoped to an implementation slice. Let me analyze the implementation approach."

1. If the feature is XL but has NO or insufficient decomposition hints (fewer than 2 sub-features): Warn the user:

Ask (using AskUserQuestion):

"Feature F-NNN is estimated as XL but has no decomposition hints (or fewer than 2 sub-features). How would you like to proceed?"

Options:

1. Provide decomposition hints now -- Suggest 2-4 sub-features with journey segment mappings
2. Proceed with a single spec anyway -- Not recommended for XL features
3. Return to the backlog -- Run /arn-spark-feature-extract to add decomposition hints

If Provide decomposition hints now: the user provides hints inline, capture them in the same structure as the feature entry template's ## Decomposition Hints section and set decomposition_mode = true. If Proceed with a single spec anyway: set decomposition_mode = false and continue normally.

1. If the feature is not XL: Set decomposition_mode = false. Proceed to Step 2.

1d. Standard Flow (No Backlog Entry)

Ask the user to describe their feature idea. Accept anything from a single sentence to a detailed description. Do not require a specific format.

If the user already provided the feature idea in their trigger message (e.g., "feature spec: add WebSocket support for real-time notifications"), use that directly without asking again.

Acknowledge the idea with a brief restatement to confirm understanding.

Step 2: Load Codebase Context

Read the project's CLAUDE.md and extract the ## Arness section to find the Code patterns path and Specs directory path.

Read the stored pattern documentation:

• <code-patterns-dir>/code-patterns.md
• <code-patterns-dir>/testing-patterns.md
• <code-patterns-dir>/architecture.md
• <code-patterns-dir>/ui-patterns.md (if it exists)
• <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 agent to generate fresh analysis. Write the results to the Code patterns directory. Summarize the key findings relevant to the feature idea.

Hold this context for use throughout the conversation. Do not dump all of it on the user — reference specific parts when relevant.

Sketch detection: Check if a arness-sketches/ directory exists at the project root. If it does, scan for a subdirectory whose name matches the feature being specified (by feature name, F-NNN ID, or keyword overlap). If a matching sketch directory is found:

1. Read arness-sketches/<sketch-name>/sketch-manifest.json
2. If the manifest file cannot be read or parsed (malformed JSON, empty file, permission error), set sketch_context_loaded = false and proceed normally — treat as if no sketch exists.
3. Verify the manifest has componentMapping and composition fields (Phase 1 enrichment)
4. If both fields are present, set sketch_context_loaded = true and hold the manifest data (sketch directory path, manifest path, status, paradigm, componentMapping entries, composition metadata) for use in Step 5
5. If the manifest exists but lacks componentMapping or composition, set sketch_context_loaded = false — the sketch predates the enrichment and cannot be referenced in the spec
6. If no matching sketch directory is found, set sketch_context_loaded = false and proceed normally

This check is silent — do not announce sketch detection to the user unless the sketch will affect the spec content.

If greenfield context was loaded in Step 1b, hold both the codebase patterns AND the greenfield context (feature file + UC documents) as combined context. The greenfield context provides behavioral requirements (WHAT to build), while the codebase patterns provide implementation conventions (HOW the codebase does things). These two sources complement each other and are both used in subsequent steps.

Step 2b: Check for Existing Draft

After loading codebase context, check <specs-dir>/ for files matching DRAFT_FEATURE_*.md.

If one or more DRAFT files exist:

1. If only one DRAFT exists, present it: "I found an in-progress draft: DRAFT_FEATURE_<name>.md. Would you like to resume editing this draft, or start fresh?"
2. If multiple DRAFTs exist, list them and ask which to resume (or start fresh).

If resuming:

• Read the DRAFT file
• Present the current state: which sections are populated, what decisions are logged, what open items remain
• Derive the spec name from the DRAFT filename (strip DRAFT_FEATURE_ prefix and .md