arn-code-sketch

Arness Sketch

Create a working interface preview of a feature using the project's actual framework, conventions, and styling system. The sketch renders the new feature in context -- showing it within the real application where it will live, not in isolation. This lets the user see and interact with a preview before committing to the full implementation pipeline.

Sketches are real code: runnable artifacts written with the project's conventions, served from a dedicated arness-sketches/ namespace. They can be iterated on via feedback, promoted into the real codebase, or cleaned up when no longer needed.

This is a conversational skill. It runs in normal conversation (NOT plan mode).

Prerequisites

1. Arness must be configured. Read the project's CLAUDE.md and check for a ## Arness section. If missing, inform the user: "Arness is not configured for this project yet. Run /arn-implementing to get started — it will set everything up automatically." Do not proceed without it.

1. Sketch strategy must exist. Read ui-patterns.md from the project's code patterns directory (the path under Code patterns: in the ## Arness config). Look for a ## Sketch Strategy section. If absent, halt with:

"No sketch strategy found. Run /arn-implementing to get started — pattern documentation will be generated on first use, including the sketch strategy if your project has a UI framework."

Do not proceed without a sketch strategy.

Pipeline Position

Entry points:
  - Direct: user says "sketch this" / "preview this"
  - From feature-spec: proactively offered after initial proposal when UI is involved
  - From feature-spec-teams: proactively offered after debate converges when UI is involved
  - From swift: after swift assessment, offered for interface changes above threshold

                    arn-code-sketch (this skill)
                    =========================
                    For interface preview before implementation

  Input:  Feature description (from spec, swift, or direct)
            |
            v
  Load:    Sketch strategy + paradigm reference from pattern docs
            |
            v
  Assess:  Should this be sketched? (threshold rules)
            |
            +--- Below threshold --> "This change is small enough to implement
            |                         directly. Proceed with /arn-code-swift or
            |                         /arn-code-feature-spec instead."
            |
            +--- Above threshold --> Continue
            |
            v
  Create:  arness-sketches/[feature-name]/ artifact namespace
            |
            v
  Build:   Spawn arn-code-sketch-builder agent
            |
            v
  Present: Show preview instructions, iterate on feedback
            |
            v
  Finish:  Promote to real codebase OR clean up

Workflow

Step 1: Load Sketch Strategy and Paradigm Reference

Load the sketch setup and paradigm routing rules:

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-sketch/references/sketch-setup.md

Follow the setup sequence:

1. Read ui-patterns.md from the project's code patterns directory (already read in Prerequisites). Parse the ## Sketch Strategy section to extract:
2. Paradigm -- the interface type (e.g., web, cli, tui, desktop, mobile)
3. Artifact structure -- what sketch files to create and where
4. Preview mechanism -- how the user previews the sketch (browser URL, terminal command, etc.)
5. Promotion rules -- how sketch artifacts move into the real codebase

1. Read architecture.md from the code patterns directory for Technology Stack confirmation (framework, language, key libraries).

1. Load paradigm reference -- based on the paradigm extracted from the sketch strategy:

> Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-sketch/references/paradigm-<paradigm>.md

If the paradigm-specific reference file does not exist, fall back to:

> Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-sketch/references/paradigm-stub.md

1. Hold the sketch strategy context (paradigm, artifact structure, preview mechanism) and paradigm reference for use by the builder agent.

Step 2: Read Feature Context

Determine what to sketch from one of these sources (check in order):

1. From conversation context -- if invoked after /arn-code-feature-spec or /arn-code-swift, the feature description and architectural decisions are already in the conversation. Extract the interface-relevant portions.

1. From a spec file -- if the user references a spec (e.g., "sketch F-001" or "sketch the auth feature"), read the spec file from the project's specs directory.

1. From direct description -- if the user describes what they want directly (e.g., "sketch a settings page with a profile form and notification preferences"), use that description.

If the feature description is vague, ask one clarifying question focused on what the user wants to SEE:

"What should I show in the preview? For example: 'a settings page with profile form and notification toggles', 'the new dashboard widget showing recent activity', 'the deploy command with its subcommands and flags', or 'the status screen with live metrics'."

Step 3: Assess Sketch Threshold

Not every interface change warrants a sketch. Apply these threshold rules based on the paradigm:

Skip sketching (below threshold):

• Web: single component additions (e.g., "add a loading spinner"), style-only changes, text content changes, icon swaps, single field additions to existing forms
• CLI: add a single flag, change help text, rename a subcommand, adjust a default value
• TUI: change a label, adjust a column width, reorder a single field

For below-threshold changes, suggest the direct path:

"This change is straightforward enough to implement directly. Would you like to proceed with /arn-code-swift instead?"

Offer sketching (above threshold):

• Web: new pages or routes, new forms with 3+ fields, new sections or panels, layout changes (sidebar, navigation, dashboard grids), multi-component features, features where the visual result is ambiguous
• CLI: new command group with 3+ subcommands, interactive wizard or multi-step prompts, new output format (table, tree, structured report), complex argument combinations
• TUI: new screen or view, new widget panel, multi-widget layout, dashboard or status display

If the user explicitly asked for a sketch (e.g., "sketch this", "preview this"), always proceed regardless of threshold.

Step 4: Create Sketch Artifacts

Create the artifact structure as specified by the loaded paradigm reference file. The paradigm reference (loaded in Step 1) defines the exact files, directory layout, and naming conventions for the current paradigm.

The artifact namespace is arness-sketches/[feature-name]/. For web paradigms, the paradigm reference file may specify a framework-specific location within the routing directory (e.g., app/arness-sketches/ for Next.js App Router, src/routes/arness-sketches/ for SvelteKit). The project root arness-sketches/ is the default for non-web paradigms. Every sketch includes a sketch-manifest.json:

{
  "featureName": "",
  "description": "",
  "sourceSpec": "",
  "paradigm": "",
  "framework": "",
  "createdAt": "",
  "targetPage": "",
  "previewCommand": "",
  "components": [],
  "componentMapping": [],
  "composition": {
    "blueprint": "",
    "layout": [],
    "dataFlow": [],
    "interactionSequence": [],
    "animation": []
  },
  "status": "draft"
}

Where targetPage is the real location where this feature will eventually live (a route for web, a command module for CLI, a screen for TUI). The paradigm field records the interface type. The previewCommand field records how to run or view the sketch (e.g., a URL for web, a shell command for CLI/TUI).

The composition.animation array documents animations implemented in the sketch. Each entry records: t