From arn-code
This skill should be used when the user says "feature spec", "arness code feature spec", "arn-code-feature-spec", "spec this feature", "help me spec", "design this feature", "feature design", "write a spec", "create a specification", "I have an idea for a feature", "let's flesh out this feature", "decompose feature", "spec XL feature", "resume spec", "continue spec", "finish my spec", "break down feature", or wants to iteratively develop a feature idea into a well-formed specification through guided conversation with architectural analysis. For XL features with decomposition hints, creates multiple sub-feature specs with full traceability. Produces specification documents capturing WHAT to build and WHY, which then feed into plan creation.
npx claudepluginhub appsvortex/arness --plugin arn-codeThis skill uses the workspace's default tool permissions.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
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.
Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/ensure-config.md and follow its instructions. This guarantees a user profile exists and ## Arness is configured with Arness Code fields before proceeding.
Before asking the user to describe their feature, check if the trigger includes a greenfield feature backlog entry:
Check if the trigger message contains an F-NNN pattern (regex: F-\d{3}). Accept natural invocations like:
feature spec F-002spec F-002: Device Pairingfeature spec: Device Pairing (fuzzy match against feature file names in the features directory)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).
If either condition is met: extract the feature ID and proceed to Step 1b.
If neither condition is met: fall through to the standard flow below (ask the user to describe the feature).
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.mdfor the full loading sequence and error handling.
Only runs after Step 1b successfully loads a greenfield feature.
Check if the loaded feature file has:
**Complexity:** XL## Decomposition Hints section with at least 2 suggested sub-featuresIf 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."
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:
/arn-spark-feature-extract to add decomposition hintsIf 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.
If the feature is not XL: Set decomposition_mode = false. Proceed to Step 2.
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.
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:
arness-sketches/<sketch-name>/sketch-manifest.jsonsketch_context_loaded = false and proceed normally — treat as if no sketch exists.componentMapping and composition fields (Phase 1 enrichment)sketch_context_loaded = true and hold the manifest data (sketch directory path, manifest path, status, paradigm, componentMapping entries, composition metadata) for use in Step 5componentMapping or composition, set sketch_context_loaded = false — the sketch predates the enrichment and cannot be referenced in the specsketch_context_loaded = false and proceed normallyThis 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.
After loading codebase context, check <specs-dir>/ for files matching DRAFT_FEATURE_*.md.
If one or more DRAFT files exist:
DRAFT_FEATURE_<name>.md. Would you like to resume editing this draft, or start fresh?"If resuming:
DRAFT_FEATURE_ prefix and .md extension)If starting fresh (or no DRAFTs found):
Greenfield path (Step 1b loaded):
DRAFT_FEATURE_F-001_device-setup.md)Derive a spec name for the feature to use for both the DRAFT and final spec files.
If greenfield context loaded (Step 1b):
F-NNN_<kebab-name> (e.g., F-001_device-setup)If standard flow (Step 1d):
websocket-notifications)<name>. Good?"Hold the spec name for use in Steps 3-5. The draft file will be <specs-dir>/DRAFT_FEATURE_<name>.md. The final file will be <specs-dir>/FEATURE_<name>.md.
Before invoking agents, determine whether the feature involves UI:
ui-patterns.md exists in the code patterns directory (with a ## Sketch Strategy section), or if the Technology Stack table in architecture.md contains a frontend framework entry (React, Vue, Svelte, Angular, Next.js, Nuxt, SvelteKit, etc.) or a CLI/TUI/desktop/mobile framework entry (Click, Typer, Rich, Textual, BubbleTea, Ratatui, Qt, Electron, SwiftUI, Jetpack Compose, or similar)Result: "involves UI" or "no interface work"
Before invoking any agents, read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/specialist-pre-check.md and apply the security relevance pre-check using the pattern documentation loaded in Step 2 and the feature description:
security_relevant: true if BOTH: (1) security-patterns.md exists in the code patterns directory, AND (2) the feature description contains security terms (auth, login, password, token, payment, upload, API key, PII, encrypt, permission, session, cookie, CORS, CSRF, rate limit, secret, credential -- case-insensitive)Parallel agent dispatch based on pre-check:
If security_relevant is true: Dispatch the following agents in parallel:
arn-code-architect (always)arn-code-ux-specialist (if the feature involves UI, from Step 3a)arn-code-security-specialistIf security_relevant is false: Dispatch the following agents in parallel:
arn-code-architect (always)arn-code-ux-specialist (if the feature involves UI, from Step 3a)All dispatched agents run in parallel (independent analyses, no cross-agent dependencies).
For arn-code-architect, provide:
User expertise context:
--- BEGIN USER EXPERTISE ---
[Read from ~/.arness/user-profile.yaml or .claude/arness-profile.local.md (project override takes precedence)]
Role: [role]
Experience: [development_experience]
Technology preferences: [technology_preferences]
Expertise-aware: [expertise_aware]
--- END USER EXPERTISE ---
--- BEGIN PROJECT PREFERENCES ---
[Read from .arness/preferences.yaml if it exists, otherwise omit this section]
--- END PROJECT PREFERENCES ---
When presenting technology recommendations, apply the advisory pattern: present the technically optimal recommendation first, then present any preference-aligned alternative with honest pros/cons. Let the user decide.
Feature idea: The user's description from Step 1d, OR (if greenfield context loaded) the feature file's Description section from Step 1b.
Codebase context: The full content of the stored pattern documentation files loaded in Step 2 (code-patterns.md, testing-patterns.md, architecture.md, and ui-patterns.md if present). If these were not available and arn-code-codebase-analyzer was used instead, pass that output.
Behavioral context (if greenfield context loaded): The full UC main success scenarios and extensions from the loaded UC documents, technical notes from the feature file, and business rules as constraints. Add instruction: "The behavioral requirements are well-defined by the use case documents. Focus your analysis on HOW to implement these behaviors within the existing codebase patterns, not on WHAT to implement."
Style context (if style-brief loaded in Step 1b): The project has a validated style-brief with toolkit configuration. The following tokens and config have been validated through static prototype showcase and clickable prototype screens: [toolkit configuration section from style-brief]. Note: Reference these tokens in the architectural assessment's component integration points. Implementation should use these exact values rather than generating new ones.
Animation context (if loaded from style-brief): Animation approach, motion philosophy, timing characteristics, key patterns. Consider: animation library/framework integration, animation cleanup on route/view changes, and performance implications for the project's platform.
Specific question: None for the initial invocation.
Note: If architecture.md contains "Architectural Constraints" (from greenfield architecture-vision), the architect will validate the proposed implementation against pillar and business constraints. Constraint conflicts will appear in the architect's output as flagged risks with a "Constraint Compliance" section.
For arn-code-ux-specialist (when dispatched), provide:
Feature idea: The user's description from Step 1d, OR (if greenfield context loaded) the feature file's Description section from Step 1b.
Codebase context: Same pattern documentation files as the architect.
UI context (if greenfield context loaded): The feature file's UI Behavior section, Components list (library + product-specific with prototype references), journey summary, and debate insights about UI decisions. Add instruction: "The UI components and interaction patterns are already validated in the prototype. Focus on mapping these to the codebase's UI patterns and identifying any implementation gaps between the prototype design and the current frontend architecture."
Style context (if style-brief loaded in Step 1b): The style-brief's toolkit configuration has been validated through static prototype showcase and clickable prototype screens. The following design tokens are production-ready: [full color palette, typography, spacing from style-brief] [toolkit configuration code from style-brief]. Map your component hierarchy recommendations to these validated tokens. Reference specific token names (e.g., "primary-500", "heading-1") rather than abstract descriptions.
Animation context (if loaded from style-brief): Motion design tokens, timing scale, easing functions. Describe which components in this feature should animate, what triggers the animation, and how it matches the product's tone commitment. Output a "Motion Design" subsection in UI Design using platform-agnostic intent language.
Operating mode hint: "existing frontend" if ui-patterns.md exists or architecture.md shows a frontend framework, otherwise "greenfield frontend".
For arn-code-security-specialist (when dispatched in parallel), provide:
Feature idea: The user's description from Step 1d, OR the feature file's Description from Step 1b.
Codebase context: The content of security-patterns.md plus the feature description and codebase patterns context.
Prompt: "List 3-5 security considerations for this feature given the codebase context. Focus on threats, required mitigations, and any security patterns that should be followed. Keep it brief -- this is design-time guidance, not a full security review."
This is a lightweight invocation -- the output feeds into the spec's Non-Functional Requirements (security bullet) and Feasibility & Risks section. It does NOT block or replace the architect's analysis.
False-negative follow-up (only when security_relevant was false):
After the parallel batch completes, check the architect's assessment for security signals. If the architect's output mentions security concerns, authentication, authorization, data protection, or vulnerability AND security_relevant was false: dispatch arn-code-security-specialist sequentially with the architect's assessment as additional context. Provide the same prompt as above, plus the architect's proposal.
False-negative follow-up for UI (only when no UX specialist was dispatched):
If the architect's response reveals UI involvement that was not detected in Step 3a (e.g., the user said "no UI" to the clarifying question but the architect identifies UI components, screens, or interface work), and no arn-code-ux-specialist was dispatched: dispatch arn-code-ux-specialist sequentially as a follow-up with the same context as the initial invocation plus the architect's assessment.
All follow-up dispatches are silent -- no user notification or status message. The user sees the combined output from all agents (parallel + sequential) as a single result.
Present the combined output to the user as the initial proposal. Highlight:
Proactive sketch offer (conditional): If ALL of these conditions are met:
ui-patterns.md exists in the code patterns directory with a ## Sketch Strategy sectionThen include in the proposal presentation:
Ask (using AskUserQuestion):
"This feature involves interface work. Would you like to see a visual preview before we dive deeper?"
Options:
If Yes, sketch it: Invoke Skill: arn-code:arn-code-sketch with the current feature context (description, architectural assessment, UX specialist output). After the sketch session completes, resume the exploration conversation. The sketch output informs subsequent spec decisions.
If No, continue with the spec: Proceed to exploration.
If sketch conditions are NOT met (no UI involvement or no Sketch Strategy), skip this offer entirely — do not mention sketch.
Then ask: "What do you think? Any questions, concerns, or changes?"
After presenting the initial proposal to the user (3c), write the draft spec to disk as an automatic save point.
Read the feature spec template at ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-feature-spec/references/feature-spec-template.md.
Populate the template with what is available from the initial analysis:
| Section | Source | Completeness |
|---|---|---|
| Problem Statement | User's feature description (Step 1) | Full |
| Functional Requirements | Initial requirements from architect analysis | Partial — mark with "[Draft — may be refined during exploration]" |
| Non-Functional Requirements | From architect + security specialist (if invoked) | Partial |
| Architectural Assessment | Full architect output (approach, components, integration points) | Full initial analysis |
| Key Decisions | From initial agent outputs | Partial — only initial decisions |
| Proposed UI Stack | From UX specialist (if greenfield UI) | Full if applicable |
| UI Design | From UX specialist (if UI involved) | Full initial analysis |
| Scope & Boundaries | From feature description + initial analysis | Partial |
| Behavioral Specification | From Step 1b greenfield context (if loaded) | Full if applicable |
| Feasibility & Risks | From architect + security specialist | Partial |
| Decisions Log | Empty or minimal (exploration has not started yet) | Empty |
| Open Items | Open questions from agents | Full initial list |
| Recommendation | "In progress — exploring with user" | Placeholder |
Add a draft status marker at the top of the file (before the title):
> **Status: DRAFT** — This specification is under active development. Last updated during exploration. Run `/arn-code-feature-spec` to resume or finalize.
Write to <specs-dir>/DRAFT_FEATURE_<name>.md.
Inform the user (brief, one line — not a decision gate): "Draft spec saved to <specs-dir>/DRAFT_FEATURE_<name>.md — I'll keep it updated as we explore."
Do NOT ask the user for approval to write the draft. This is an automatic save point, not a decision gate. The user's attention should remain on the initial proposal and their response to "What do you think?"
If the draft write fails (permissions, path issues), continue without the draft and fall back to the current behavior (write everything at Step 5). Inform the user: "Could not save draft — I'll write the spec at the end instead."
When greenfield context is loaded: The exploration phase should be shorter and more focused. The behavioral requirements (what to build) are already defined by the feature file and use cases. Exploration should focus on: (1) implementation approach within the codebase, (2) gaps between the defined behavior and what the codebase can support, (3) technical decisions not covered by the feature file. Do not re-explore requirements that are already well-defined in the loaded context.
When decomposition mode is active: The exploration phase should additionally validate the decomposition hints: are the suggested sub-feature boundaries correct? Do the journey segment mappings make sense? Are the inter-sub-feature dependencies accurate? The user can adjust the decomposition during this phase. Each sub-feature should be independently implementable and testable.
Scope boundary awareness (when scope boundary context is loaded from Step 1b): Before raising any question about whether to include adjacent functionality in this feature's spec, FIRST check the loaded scope boundary context (related feature descriptions, journey steps, and acceptance criteria). Apply this rule:
/arn-spark-feature-extract."This prevents scope creep by ensuring the agent knows what sibling features already handle, and only escalates genuine gaps to the user.
This is a conversation loop. Each iteration:
Listen — the user responds with feedback, questions, concerns, or new requirements.
Decide how to respond — first apply the scope boundary awareness rule above (check sibling features before raising scope questions), then consult the Agent Invocation Guide table below to determine whether to invoke an agent or answer directly.
Summarize the current state — after each substantive exchange, briefly state where things stand: what has been decided, what is still open.
Update the draft — if a draft file exists (written in Step 3d or loaded during resume in Step 2b), apply the Draft Update Protocol below.
Check for readiness — when the conversation feels like it is converging (open questions are being resolved, the user is agreeing more than questioning), ask:
"I think we have enough to finalize the feature specification. Ready for me to finalize it, or do you want to explore anything else first?"
Do not ask this after every single exchange. Use judgment — typically after 2-4 rounds of substantive discussion, or when the user signals readiness (e.g., "I think that covers it", "looks good").
Note: The proactive sketch offer happens in Step 3c (after the initial proposal). This section handles the case where the user requests a sketch later during exploration — either because they declined the initial offer, or because the conversation evolved and they now want to visualize something specific.
During exploration, if the user asks to see what the feature would look like (e.g., "show me what this looks like", "can I see a preview", "what would the UI look like", "sketch this"), and the feature involves interface work (detected in Step 3a), and ui-patterns.md exists with a ## Sketch Strategy section, invoke Skill: arn-code:arn-code-sketch with the current feature context (description, architectural assessment, UX specialist output if available). After the sketch session completes, resume the exploration conversation where it left off. The sketch output can inform subsequent spec decisions (component structure, layout choices, interaction patterns).
If the feature involves interface work but ui-patterns.md does not exist or has no ## Sketch Strategy section, inform the user: "Sketch is not available for this project. Pattern documentation will be generated on first use and will include a Sketch Strategy if your project has a UI framework." Continue the exploration without sketching.
After a sketch session completes: If a arn-code-sketch session was invoked during exploration and produced a manifest with componentMapping and composition fields, capture the sketch context for Step 5. Set sketch_context_loaded = true and hold the manifest data (sketch directory path, manifest path, status, paradigm, componentMapping entries, composition metadata). This is the same data that Step 2 would detect from an existing sketch — the difference is that here the sketch was created during this spec session rather than before it.
After each substantive exchange that changes the spec content, update the DRAFT file using the Edit tool. A "substantive exchange" is one where:
Do NOT update the draft for:
When updating, use the Edit tool to modify specific sections (surgical edits). Do not rewrite the entire file on each update.
After updating, do NOT announce it to the user. The update is silent — the user's conversational flow should not be interrupted by draft-save notifications. Exception: if the Edit fails, inform the user that the draft could not be updated, and continue the conversation normally. The draft may be partially stale but the conversation holds the latest state — Step 5 finalization will reconcile any gaps.
If the draft file was deleted externally during exploration, detect this at the next update attempt and recreate the draft from conversation context before continuing.
When invoking agents during exploration, pass this context:
Feature: [current refined feature description incorporating all decisions]
Codebase context: Pattern documentation was loaded in Step 2. Key patterns
relevant to this feature:
- [list 2-4 specific patterns from the docs that matter]
Greenfield context (if loaded): Feature file F-NNN and UC documents loaded
in Step 1b. Relevant behavioral detail:
- [reference specific UC steps, extensions, or business rules that apply]
Conversation context:
- Decisions made so far: [bullet list]
- Current question: [the specific question to investigate]
For arn-code-ux-specialist, also include the operating mode hint and any prior UX decisions.
When the user says yes to writing the spec:
If decomposition_mode is true (XL Decomposition):
Create multiple sub-feature specs, update the Feature Tracker, and optionally create child issues. After writing all sub-feature specs, delete the DRAFT file.
Read
${CLAUDE_PLUGIN_ROOT}/skills/arn-code-feature-spec/references/xl-decomposition.mdfor the full decomposition procedure, Feature Tracker updates, child issue creation, and error handling.
The decomposition flow is self-contained. Do not proceed to the standard single-spec flow below.
If decomposition_mode is false (standard single-spec flow):
Read the feature spec template at ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-feature-spec/references/feature-spec-template.md.
Read the current draft from <specs-dir>/DRAFT_FEATURE_<name>.md. Review each section against the template and the full exploration conversation. Fill in any remaining gaps, refine partial content, and ensure all sections are complete.
Specific finalization actions:
> **Status: DRAFT**... block at the top of the filesketch_context_loaded is true, populate the Sketch Reference section:
componentMapping entries (one row per component: sketch file path, target location, promotion mode, description)composition field (blueprint path, layout description, data flow, interaction flow)sketch_context_loaded is false, omit the Sketch Reference section entirely.If no draft file exists (draft write failed in Step 3d, or the skill fell back to in-conversation mode), populate the template from scratch using the conversation content — same as the previous behavior:
arn-code-architect invocations (initial proposal + subsequent answers), merged with arn-code-ux-specialist output (component design, accessibility, UI stack) if the feature involves UIsketch_context_loaded is true): Populate from the held manifest data — sketch directory, manifest path, status, paradigm, Component Mapping table (from componentMapping), Composition Summary (from composition). Omit this section entirely if sketch_context_loaded is false.Write the finalized spec to <specs-dir>/FEATURE_<name>.md (where <specs-dir> is the Specs directory from the ## Arness config). If the specs directory does not exist, create it: mkdir -p <specs-dir>/
Delete the draft file: remove <specs-dir>/DRAFT_FEATURE_<name>.md. If the delete fails or the file does not exist, continue without error.
Present a summary to the user:
Inform the user of next steps:
"Feature specification saved to <specs-dir>/FEATURE_<name>.md.
To create an implementation plan, run /arn-code-plan FEATURE_<name>.
The skill will load this spec and your project's codebase patterns, invoke the planner agent to generate a plan, and let you review and refine it before saving."
Consult ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-feature-spec/references/agent-invocation-guide.md to determine when to invoke each agent (arn-code-architect, arn-code-ux-specialist, arn-code-security-specialist) vs. answer directly during exploration.
<specs-dir>/DRAFT_FEATURE_<name>.md) so they can resume later by running /arn-code-feature-spec again (the draft will be detected in Step 2b).arn-code-architect or arn-code-ux-specialist returns an unhelpful or empty response, summarize the issue to the user and offer to try a more specific question or proceed with what is known.${CLAUDE_PLUGIN_ROOT}/skills/arn-code-feature-spec/references/greenfield-loading.md (Error Handling section).${CLAUDE_PLUGIN_ROOT}/skills/arn-code-feature-spec/references/xl-decomposition.md (Error Handling section).