Arn Code Init

---
name: arn-code-init
description: >-
  Optional customization and upgrade tool. This skill should be used when the user says
  "initialize arness code", "arness code init", "arn-code-init", "init arness code", "setup arness code",
  "arness code setup", "set up arness code", "start arness code", "upgrade arness code", "update arness code",
  "configure arness code for this project", "add arness code to this project", "reconfigure arness code",
  "review arness config", "customize arness config", "arness settings",
  or wants to customize Arness configuration, review current settings, or upgrade after a plugin update.
  Handles both existing codebases (analyzes patterns) and greenfield projects (recommends patterns
  based on technology choices). Also handles upgrades after plugin updates.
version: 1.1.0
---

# Arness Init

Set up Arness for a project by analyzing or defining code patterns, choosing configuration options, and persisting everything to CLAUDE.md. This is optional — Arness auto-configures with sensible defaults on first skill invocation. Use this to customize directories, add integrations, update templates, or review your current settings.

## Workflow

### Step 1: Check Existing Configuration

Read the project's CLAUDE.md and look for a `## Arness` section. If no CLAUDE.md exists, create one at the project root before proceeding.

**If the section does not exist:**
- Proceed to Step 2 (fresh init)

**If the section exists:**
1. Parse all config fields from the existing `## Arness` block
2. Read the current plugin version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`
3. Show the user their current configuration and version comparison:
   - Config template version vs current plugin version
   - Number of config fields present vs expected
4. Ask via `AskUserQuestion`:
   - **Review** — Show current configuration summary, no changes
   - **Upgrade (recommended)** — Check for gaps and update only what's needed. Best after a plugin update.
   - **Reconfigure** — Re-run the full setup flow from scratch (change directories, regenerate patterns, etc.)
   - **Keep** — No changes
- If **Review** → display a clean summary of all `## Arness` fields, then exit the skill
- If **Keep** → done, exit the skill
- If **Reconfigure** → continue to Step 2, pre-filling known values as defaults
- If **Upgrade** → proceed to the **Upgrade Flow** section

---

### Step 2: Detect Project State

Determine whether this is an existing codebase or a greenfield project.

Look for indicators of an existing codebase:
- Package manifests: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `Gemfile`, `composer.json`
- Source directories: `src/`, `app/`, `lib/`, `cmd/`, `pkg/`
- Framework markers: `manage.py`, `next.config.*`, `angular.json`, `vite.config.*`, `main.go`, `main.rs`
- Meaningful source files (not just README, LICENSE, .gitignore)

**If existing codebase detected** → proceed to **Flow A** (Step 3A)

**If empty or minimal project** → proceed to **Flow B** (Step 3B)

Tell the user which flow was detected and why: "I detected an existing [language/framework] project" or "This looks like a new project with no existing code."

---

### Step 3: Detect Git, Platform, and Issue Tracker

> **Note:** Step 3 runs for ALL projects (both Flow A and Flow B). Steps 3A and 3B are flow-specific and run after Step 3.

**Shared field preservation:** If `## Arness` already exists and the shared fields (Git, Platform, Issue tracker, Jira site, Jira project) are already present from a prior init (this plugin or another — e.g., arn-spark-init, arn-infra-init, or ensure-config auto-detection), **skip detection and preserve the existing values** — unless the user chose **Reconfigure** in Step 1. If these fields were set by ensure-config auto-detection, preserve them unless the user chose Reconfigure. This prevents overwriting values set by another plugin or by ensure-config in a monorepo.

Check if the project uses Git, determine the code hosting platform, and identify the issue tracker.

**3.1. Git check:**
1. Run `git rev-parse --is-inside-work-tree` to check for a git repository
2. If Git is not detected, inform the user: "This project is not a git repository. Git-dependent skills (`/arn-code-ship`, `/arn-code-review-pr`, `/arn-code-create-issue`, `/arn-code-pick-issue`) will be unavailable." Record Git: no, Platform: none, Issue tracker: none and proceed to Step 3A/3B.

**3.2. Remote classification:**
1. Run `git remote -v` and classify the remote URL:
   - Contains `github.com` → candidate: **github**
   - Contains `bitbucket.org` → candidate: **bitbucket**
   - Neither → Platform: none, Issue tracker: none. Inform the user: "No supported platform detected. PR and issue management skills will be unavailable."

**3.3a. If candidate is github:**
1. Run `gh auth status` to check for GitHub CLI authentication
2. If authenticated → Platform: **github**, Issue tracker: **github**
3. If NOT authenticated → warn the user, suggest `gh auth login`, and **STOP init** (do not continue until resolved)
4. Create 7 Arness labels for issue management. Use `gh label create` for each label (the command is idempotent — it will skip labels that already exist):

| Label | Color | Description |
|-------|-------|-------------|
| `arness-backlog` | `d4c5f9` | Deferred items from PRs or postponed features |
| `arness-feature-issue` | `0e8a16` | Feature requests tracked via Arness |
| `arness-bug-issue` | `d93f0b` | Bug reports tracked via Arness |
| `arness-priority-high` | `b60205` | High priority |
| `arness-priority-medium` | `fbca04` | Medium priority |
| `arness-priority-low` | `c5def5` | Low priority |
| `arness-rejected` | `e4e669` | Issue reviewed and rejected as invalid or out of scope |

> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/platform-labels.md` for label details and which skills use each label.

**3.3b. If candidate is bitbucket:**
1. Run `bkt --version` to check if the Bitbucket CLI is installed
   - If NOT available → read and show the setup instructions from `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/bkt-setup.md`, then **STOP init**
2. Run `bkt auth status` to check authentication
   - If NOT authenticated → read and show the auth instructions from `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/bkt-setup.md`, then **STOP init**
3. Platform: **bitbucket** (confirmed)
4. Ask the user: "Do you use Jira for issue tracking on this project?"
   - **YES** → verify the Atlassian MCP server:
     - Attempt to list Jira projects via the MCP tool
     - If MCP NOT available → read and show the setup instructions from `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/jira-mcp-setup.md`, then **STOP init**
     - If MCP available → list projects, present to user, user picks one
     - Store: Issue tracker: **jira**, Jira site: (from MCP context or ask user), Jira project: (user's pick)
     - No label creation needed (Jira labels are implicit — see `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/platform-labels.md`)
   - **NO** → Issue tracker: **none**
     - Inform the user: "Issue management skills (`/arn-code-create-issue`, `/arn-code-pick-issue`) will be unavailable. PR and code workflow skills still work via bkt."

**3.4. Record results:**
- **Git:** yes | no
- **Platform:** github | bitbucket | none
- **Issue tracker:** github | jira | none
- **Jira site:** (only if Issue tracker is jira)
- **Jira project:** (only if Issue tracker is jira)

---

## Flow A: Existing Codebase

### Step 3A: Analyze Codebase Patterns

Invoke the `arn-code-codebase-analyzer` agent via the Task tool, passing the model from `.arness/agent-models/code.md` as the `model` parameter (see `plugins/arn-code/skills/arn-code-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:
- The detected project type (backend/frontend/fullstack — infer from the codebase)
- The source root path (infer from project structure)
- Any framework hint (infer from manifests/markers)

The agent returns structured pattern documentation covering code patterns, testing patterns, and architecture — with real file paths and code snippets.

Review the output. If it seems incomplete (e.g., missed a major area of the codebase), re-invoke with more specific guidance.

Proceed to **Step 4**.

---

## Flow B: Greenfield Project

### Step 3B: Gather Technology Choices

Walk the user through the questions defined in `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/greenfield-questions.md`.

**Required questions** (always ask):
1. Project type — backend, frontend, or fullstack?
2. Language — what programming language?
3. Framework — suggest popular options based on language and project type
4. Testing approach — suggest default based on language

**Contextual questions** (ask based on earlier answers):
5. Database — if backend or fullstack
6. API style — if backend or fullstack
7. Package manager — suggest default, confirm
8. Project layout — src layout, flat, monorepo
9. Authentication — if backend or fullstack
10. Additional tooling — linting, formatting, CI
11. UI component library — if frontend or fullstack
12. Styling approach — if frontend or fullstack
13. Accessibility requirements — if frontend or fullstack

Be conversational, not rigid. Skip questions where the answer is obvious from prior answers. Summarize the choices before proceeding.

### Step 3B-2: Generate Recommended Patterns

Invoke the `arn-code-pattern-architect` agent via the Task tool, passing the model from `.arness/agent-models/code.md` as the `model` parameter (see `plugins/arn-code/skills/arn-code-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback), with all the technology choices gathered above.

The agent returns recommended code patterns, testing patterns, and architecture — with concrete best-practice examples marked as "Recommended" rather than real file references.

Present the recommendations to the user for review:
- Show a summary of what was recommended
- Ask: "Does this look good? Would you like to adjust anything?"
- If adjustments needed → discuss and re-invoke the agent, or manually adjust the output
- If approved → proceed to **Step 4**

---

## Common Steps (both flows converge here)

### Step 4: Set Up Pattern Docs Directory

Ask the user: "Where should Arness store the code pattern documentation for this project?"

- Suggest `.arness/code-patterns` at the project root as the default
- Accept any path the user provides (relative to project root or absolute)
- If updating an existing config (from Step 1), show the current path as the default

Create the directory if it does not exist.

### Step 5: Choose Specs Directory

Ask the user: "Where should Arness store feature and bug specifications?"

- Suggest `.arness/specs` as the default
- Accept any path the user provides (relative to project root or absolute)

Create the directory if it does not exist: `mkdir -p <chosen-path>`

These specifications are created by `arn-code-feature-spec` and `arn-code-bug-spec` and drive the planning workflow via `/arn-code-plan`.

### Step 6: Write Pattern Documentation

Read the pattern documentation schema at `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/pattern-schema.md`. This defines the exact structure each file must follow.

**Greenfield Architecture Bridge:**

Before generating pattern documentation, check if an `architecture-vision.md` exists. Read `## Arness` config for greenfield fields (Vision directory — set by the arn-spark plugin during greenfield exploration). If Vision directory is configured, check `<vision-dir>/architecture-vision.md`.

**If architecture-vision.md is found:**

1. Read the architecture-vision.md
2. Extract and carry forward into the generated architecture.md:
   - **Technology Stack table** — use as the source for architecture.md's Technology Stack section (for Flow B: skip the technology choices gathering in Step 3B since they are already captured)
   - **Pillar Alignment table** → populate the "Architectural Constraints: Product Pillars" section in architecture.md
   - **Business Constraints & Trade-offs table** (if present) → populate the "Architectural Constraints: Business Constraints" section
   - **Known Risks & Mitigations table** → populate the "Known Risks & Mitigations" section
3. Inform: "Found architecture-vision.md from greenfield exploration. Seeding architecture.md with technology choices, pillar constraints, business constraints, and known risks."

**If architecture-vision.md is NOT found:** proceed normally (Flow A: analyze codebase, Flow B: ask for technology choices).

Split the agent output (from Step 3A or Step 3B-2) into three to five files based on the top-level headings: `# Code Patterns`, `# Testing Patterns`, `# Architecture`, and optionally `# UI Patterns` and `# Security Patterns`.

**Before writing each file**, validate the content against the schema:
- Every pattern has all required fields (Description, Reference, Example, How to apply / Fixtures/Helpers)
- Required sections are present (Project Stack in code-patterns.md, Test Framework in testing-patterns.md, Technology Stack and Project Layout in architecture.md, UI Stack in ui-patterns.md)
- References contain real file paths with line numbers (not placeholders)
- Code examples are actual snippets from the codebase (not pseudocode)

If the agent output is missing required fields or uses the wrong structure, reformat it to match the schema before writing.

Write the files to the chosen pattern docs location:

1. **`code-patterns.md`** — Project stack info + code patterns (naming, structure, API/routing, data layer, error handling, configuration)
2. **`testing-patterns.md`** — Test framework info + testing patterns (organization, fixtures, markers, setup/teardown)
3. **`architecture.md`** — Technology stack table, architectural decisions, dependencies, project layout, codebase references
4. **`ui-patterns.md`** *(frontend and fullstack projects only)* — UI stack info + UI patterns (component patterns, layout/styling, state management, accessibility, form handling, navigation, animation). Write this file if the project type is "frontend" or "fullstack" (from question 1 for greenfield, or detected type for existing codebases), OR if the codebase analyzer detected a frontend framework during analysis.
5. **`security-patterns.md`** *(projects with security surface)* — Security stack info +
   security patterns (authentication, authorization, input validation, data protection,
   API security, dependency security). Write this file if the codebase analyzer or pattern
   architect detected security-relevant patterns (auth middleware, API endpoints, user input
   handling, sensitive data). Do not write it for projects with no security surface (pure
   utility libraries, CLI tools with no auth/API/user input).
6. **`linting.md`** — Linter detection per service/package, produced by the codebase analyzer (step 3C of `arn-code-codebase-analyzer`). Always write this file: if no linters were detected, the analyzer returns the single-line "No linters detected." marker, which is what gets written. The lint configuration question in Step 8b uses this file to suggest a default.

### Step 7: Configure Plans and Templates

Ask the user:

**1. Plans directory**

"Where should Arness save structured project plans?"
- Suggest `.arness/plans` as the default
- Accept any path

Create the directory if it does not exist: `mkdir -p <chosen-path>`

**2. Report templates**

"Arness includes default report templates (implementation, testing, progress tracking).
Would you like to use the defaults, or design custom ones?"

For default templates, copy all JSON templates from the plugin to `.arness/templates/`, generate SHA-256 checksums, and write a `.checksums.json` file for version tracking. For custom templates, show the defaults as a starting point and iterate with the user. After setup, ask the user's preference for handling future template updates (ask, auto, or manual).

> Read `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/template-setup.md` for the full template setup procedure.

### Step 8: Choose Documentation Directory

Ask the user: "Where should Arness save project documentation?"

- Suggest `.arness/docs/` at the project root as the default
- Accept any path the user provides

Create the directory if it does not exist: `mkdir -p <chosen-path>`

Documentation generated by `/arn-code-document-project` will be saved here.

### Step 8b: Configure Linting

Read `<code-patterns-dir>/linting.md` (written in Step 6). Use its content to decide the suggested default for the question below:

- If `linting.md` contains the marker `No linters detected.` → suggested default: `None`
- Otherwise (linters were detected) → suggested default: `Enabled`

Ask (using `AskUserQuestion`):

> **How should Arness handle linting for this project? \<suggested default shown above\>**
> 1. **Enabled** — discover and use the project's linters as a gate before commits
> 2. **None** — project has no linters configured
> 3. **Skip** — keep the lint gate disabled (you can change this later)

Record the answer for the config write in Step 9.

If `linting.md` does not exist (e.g., the analyzer failed earlier in Step 6, or this is a partial init), default the question's suggested value to `Skip` so the user is not blocked, and note in the config that linting will be re-checked on the next `arn-code-ensure-config` run.

### Step 8c: Choose Model Profile for arn-code Agents

Run the **Profile selection** procedure documented in `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md` under the "Model profile field" section. That procedure is the single source of truth for the prompt + write + copy + checksum flow — do NOT duplicate the AskUserQuestion or file-copy logic here.

The procedure performs (in order):
1. Cross-plugin default suggestion (read sibling plugin profile fields if present in the existing `## Arness` block)
2. AskUserQuestion with title "Choose model profile for arn-code agents" and two options: `all-opus` (default unless a sibling chose `balanced`) and `balanced`
3. Append `- **Code agent model profile:** <choice>` to the `## Arness` block
4. `mkdir -p .arness/agent-models/` then copy `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/agent-models-presets/<choice>.md` to `.arness/agent-models/code.md`
5. Compute SHA-256 and record it in `.arness/agent-models/.checksums.json` along with the profile name and version
6. Inform the user with a one-line confirmation

The field write in step 3 of the procedure is captured for the CLAUDE.md write in Step 9 of this init flow — write the chosen value to a holding variable and let Step 9 emit it inline with all other fields. The preset copy + checksum (steps 4-5 of the procedure) happen here regardless of when the CLAUDE.md write is performed.

Record the chosen profile for the config write in Step 9.

---

### Step 9: Persist Configuration to CLAUDE.md

Write (or update) the `## Arness` section in the project's CLAUDE.md:

```markdown
## Arness

- **Plans directory:** [chosen-path]
- **Specs directory:** [chosen-specs-path]
- **Report templates:** default | custom
- **Template path:** [relative-path, e.g., .arness/templates]
- **Template version:** [version from plugin.json]
- **Template updates:** ask | auto | manual
- **Code patterns:** [chosen-pattern-docs-path]
- **Docs directory:** [chosen-docs-path]
- **Linting:** enabled | none | skip
- **Code agent model profile:** all-opus | balanced | custom
- **Git:** yes | no
- **Platform:** github | bitbucket | none
- **Issue tracker:** github | jira | none
- **Jira site:** <site>.atlassian.net
- **Jira project:** <KEY>
- **Task list ID:** <task-list-id>
```

The template path MUST be relative to the project root, never absolute. This ensures portability across machines and plugin updates.

The `Task list ID` field is conditional — only written if the user opts in during Step 9b. Omit it if the user chose not to enable persistent task lists.

The Git, Platform, and Issue tracker fields are auto-detected in Step 3 and are not user-configurable.

The Jira site and Jira project fields are only written when Issue tracker is jira. Omit them entirely for other issue trackers.

If updating an existing config, replace the existing `## Arness` section in place. Do not duplicate it. **Preserve all fields not managed by this skill** — this includes greenfield fields (Vision directory, Use cases directory, Prototypes directory, Spikes directory, Visual grounding directory, Figma, Canva) and infra fields (Deferred, Experience level, Project topology, Application path, Providers, Providers config, Default IaC tool, Environments, Environments config, Tooling manifest, Resource manifest, Cost threshold, Validation ceiling, Infra plans directory, Infra specs directory, Infra docs directory, Infra report templates, Infra template path, Infra template version, CI/CD platform, Reference overrides, Reference version, Reference updates). For shared fields (Git, Platform, Issue tracker, Jira site, Jira project): if already present, preserve them — do not re-detect unless the user chose Reconfigure in Step 1.

### Step 9b: Set Up Persistent Task List (Recommended)

Ask the user:

"Would you like to enable persistent task lists? (Recommended)

This sets `CLAUDE_CODE_TASK_LIST_ID` in your project's `.claude/settings.json` so that tasks created by `/arn-code-taskify` survive across sessions. Without this, tasks are lost when a session ends and must be recreated.

Benefits:
- Resume `/arn-code-execute-plan` after a session restart
- Multiple sessions on the same project see the same task state
- Worktree-based parallel execution shares the task list"

Options:
1. **Yes** (Recommended) — Set up with auto-generated ID based on project directory name
2. **Yes, with custom ID** — Let me specify the task list ID
3. **No** — Skip (tasks will be session-scoped)

**If Yes:**
1. Derive the task list ID:
   - **Auto:** slugify the current project directory name (e.g., `/home/user/my-project` → `my-project`)
   - **Custom:** use the user's provided ID
2. Read `.claude/settings.json` in the project root (create the file and `.claude/` directory if they don't exist)
3. Add or update the `env` object, preserving any existing env vars (e.g., `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`):
   ```json
   {
     "env": {
       "CLAUDE_CODE_TASK_LIST_ID": "<task-list-id>"
     }
   }
   ```
4. Add `- **Task list ID:** <task-list-id>` to the `## Arness` config block written in Step 9
5. Inform: "Persistent task list configured. Tasks will persist across sessions at `~/.claude/tasks/<task-list-id>/`."

**If No:**
- Do not write to `.claude/settings.json`
- Omit `Task list ID` from the `## Arness` config block
- Inform: "Task lists will be session-scoped. You can enable persistence later by re-running `/arn-code-init`."

### Step 10: Verify and Summarize

Confirm with the user:

- [ ] Project state detected correctly (existing vs greenfield)
- [ ] Code patterns analyzed (Flow A) or recommended (Flow B)
- [ ] Pattern documentation written:
  - `[pattern-dir]/code-patterns.md`
  - `[pattern-dir]/testing-patterns.md`
  - `[pattern-dir]/architecture.md`
  - `[pattern-dir]/ui-patterns.md` (if frontend/fullstack)
  - `[pattern-dir]/security-patterns.md` (if security surface detected)
- [ ] Plans directory configured
- [ ] Report templates configured
- [ ] Specs directory configured and created
- [ ] Template checksums generated (`.arness/templates/.checksums.json`)
- [ ] Git, Platform, and Issue tracker detected and configured
- [ ] GitHub labels created (if Platform is github)
- [ ] Jira project selected (if Issue tracker is jira)
- [ ] Documentation directory configured
- [ ] `## Arness` section written to CLAUDE.md

List all created/modified files with their paths.

**Next steps:**
- To spec a new feature: run `/arn-code-feature-spec` (or `/arn-code-feature-spec-teams` for team debate)
- To spec a bug fix: run `/arn-code-bug-spec`
- To create an issue: run `/arn-code-create-issue` (requires Issue tracker: github or jira)
- To pick an issue from the backlog: run `/arn-code-pick-issue` (requires Issue tracker: github or jira)

## Upgrade Flow

Entered from Step 1 when the user chooses **Upgrade**. Diagnoses gaps using the `arn-code-doctor` agent and surgically fixes only what's missing — preserving all existing user choices.

### Step U1: Run Diagnostic

Invoke the `arn-code-doctor` agent via the Task tool, passing the model from `.arness/agent-models/code.md` as the `model` parameter (see `plugins/arn-code/skills/arn-code-ensure-config/references/ensure-config.md` "Dispatch convention" for fallback). Context:
- Description: "Comprehensive health check for arn-code-init upgrade. Check ALL categories: config fields, directories, template files, checksums, Git/Platform/Issue tracker state, platform labels, and pattern doc schema compliance. Use only Read/Glob/Grep and the allowed Bash commands (git status, git remote -v, gh auth status, gh label list, bkt --version, bkt auth status, ls). Do NOT run claude CLI commands."
- Project root path
- The parsed `## Arness` config content
- Plugin version from `${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json`
- Instruction to read the knowledge base at `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-report/references/arness-knowledge-base.md`

The agent should check for:
- Platform field presence and validity (github | bitbucket | none)
- Issue tracker field presence and validity (github | jira | none)
- If Issue tracker is jira: Jira site and Jira project fields populated
- Old `GitHub:` field presence (indicates migration is needed)
- Deferred visual testing layers: look for `#### Layer N:` subsections under `### Visual Testing` in the project's CLAUDE.md where `**Status:** deferred` is present. If found, report the layer names.
- All other standard checks (directories, templates, checksums, pattern docs)

Wait for the agent to complete and collect the diagnostic report.

---

### Step U2: Parse and Present Findings

Categorize each `[ISSUE]` from the doctor's report:

| Category | Examples |
|----------|----------|
| `missing_config_auto` | Git, Platform, Issue tracker fields absent from config |
| `legacy_config` | Old `GitHub: yes\|no` field present (needs migration to Platform + Issue tracker) |
| `missing_config_user` | Docs directory, Plans dir, Specs dir, Code patterns, template prefs absent |
| `missing_config_jira` | Jira site or Jira project absent when Issue tracker is jira |
| `missing_directory` | Directory referenced in config but path doesn't exist |
| `outdated_templates` | Template version in config < current plugin version |
| `missing_labels` | GitHub labels not present in repository (Platform: github only) |
| `pattern_schema` | Pattern docs missing required sections or files absent |
| `visual_deferred_layers` | Deferred visual testing layers detected in `### Visual Testing` config |

If all findings are `[OK]`, inform the user: "Arness is fully up to date. No changes needed." and exit.

Otherwise, present a summary: "Found N items to address:" followed by a brief list of the categories.

---

### Step U3: Auto-Fix (No User Input)

Process these categories silently, then report what was done:

1. **Platform detection** (if Platform/Issue tracker fields absent, or legacy `GitHub:` field present):
   Run the same detection logic as Step 3:
   - `git rev-parse --is-inside-work-tree`
   - `git remote -v` (classify: github.com, bitbucket.org, or other)
   - Platform-specific auth checks (`gh auth status` or `bkt --version` + `bkt auth status`)
   - Record Git, Platform, and Issue tracker values.

   **Migration from legacy config:**
   - If `GitHub: yes` is found → set Platform: github, Issue tracker: github. Remove the `GitHub` field.
   - If `GitHub: no` is found → re-run full detection (the remote may now be Bitbucket). Remove the `GitHub` field.
   - If no `GitHub` field and no `Platform` field → full detection runs as described above.

2. **Missing directories** (for config fields that already have a value but the directory doesn't exist): `mkdir -p <path>` for each.

3. **Missing platform labels** (if Platform is github): Run `gh label create --force` for each missing label per `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/platform-labels.md`. These commands are idempotent. Skip label creation for Bitbucket and Jira (Jira labels are implicit).

Report to the user what was auto-fixed:
```
Auto-fixed:
- Detected Git: yes, Platform: github, Issue tracker: github
- Migrated legacy GitHub: yes → Platform: github + Issue tracker: github
- Created missing directory: .arness/docs/
- Created 3 missing GitHub labels: arness-backlog, arness-priority-high, arness-priority-low
```

---

### Step U4: User-Input Gaps

For each missing config field that needs a user-provided value, ask **one focused question** using the same prompt and default as the corresponding full-flow step:

| Missing Field | Prompt | Default | Source Step |
|---------------|--------|---------|------------|
| Code patterns | "Where should Arness store the code pattern documentation?" | `.arness/code-patterns` | Step 4 |
| Specs directory | "Where should Arness store feature and bug specifications?" | `.arness/specs` | Step 5 |
| Plans directory | "Where should Arness save structured project plans?" | `.arness/plans` | Step 7 |
| Report templates | "Use default or custom report templates?" | `default` | Step 7 |
| Template updates | "How should Arness handle template updates?" | `ask` | Step 7 |
| Docs directory | "Where should Arness save project documentation?" | `.arness/docs/` | Step 8 |
| Jira site | "What is your Atlassian site URL? (e.g., mycompany.atlassian.net)" | none | Step 3 |
| Jira project | "Which Jira project should Arness use?" | list via MCP and pick | Step 3 |

**Rules:**
- Only ask about fields that are genuinely absent from the config. Never re-ask about fields that already have a value.
- Jira site and Jira project are only asked when Issue tracker is jira and the fields are missing. If the Atlassian MCP server is available, list projects and let the user pick instead of typing manually.
- If a field had a backward-compatibility default (e.g., Docs directory defaults to `.arness/docs/`), still ask so it gets persisted explicitly. Mention the current default: "This field wasn't set in your config. The default is `.arness/docs/`. Would you like to use this, or choose a different path?"
- After each directory answer, create the directory if it does not exist: `mkdir -p <path>`
- If Report templates is missing and the user chooses "default", copy template files and generate checksums per the template setup procedure in `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/template-setup.md`.

---

### Step U5: Template Upgrades

This step only runs if `Template version` in the config is older than the current plugin version.

1. Read the user's `Template updates` preference from the config
2. Read the existing `.checksums.json` from the user's template directory
3. Compute current SHA-256 checksums of the user's template files to detect customizations

Then follow the preference:

- **`ask`:** Show the user which templates have changed between versions. Ask: "The plugin has updated templates. Would you like to update? Files you've customized will be preserved." If yes → copy new defaults for unmodified templates (checksum matches stored value), skip modified ones and warn. Regenerate `.checksums.json`.
- **`auto`:** For each template: if checksum matches stored value (unmodified), overwrite with new default. If checksum differs (user customized), skip and warn. Regenerate `.checksums.json`.
- **`manual`:** Inform the user: "New template versions are available in the plugin. Your templates were not changed." Do not touch files.

In all cases, update `Template version` in the config to the current plugin version.

---

### Step U6: Pattern Doc Schema Check

This step only runs if the doctor flagged `pattern_schema` issues.

- **Files exist but non-compliant** (missing required sections, wrong structure): Ask the user: "Your pattern documentation files exist but don't fully comply with the current schema. Would you like me to regenerate them? Your existing content will be used as context." If yes → re-invoke `arn-code-codebase-analyzer` (existing project) or `arn-code-pattern-architect` (greenfield), validate output against the schema at `${CLAUDE_PLUGIN_ROOT}/skills/arn-code-init/references/pattern-schema.md`, and write the updated files.
- **Files entirely missing** (directory exists but pattern doc files absent): Ask the user: "No pattern documentation files found. Would you like to generate them now? This will analyze your codebase." If yes → run the full Flow A (Step 3A) or Flow B (Step 3B) detection + Step 6 writing flow.

---

### Step U7: Update Config

Write (or update) the `## Arness` section in CLAUDE.md, merging:
- Existing values (preserved as-is for fields that were already configured)
- Newly detected values (Git, Platform, Issue tracker from Step U3)
- Newly chosen values (from Step U4, including Jira site/project if applicable)
- Updated Template version (from Step U5)

The config includes up to 14 fields (11 core + 3 conditional: 2 Jira fields + 1 Task list ID). The old `GitHub:` field is removed if present (replaced by Platform + Issue tracker). Jira site and Jira project fields are only written when Issue tracker is jira. Task list ID is only written when the user opts in during Step 9b.

Replace the existing `## Arness` section in place. Format matches Step 9 exactly. **Preserve all fields not managed by this skill** (greenfield fields, infra fields) as documented in Step 9.

---

### Step U7b: Deferred Visual Testing Layer Notice

If deferred visual testing layers were detected (`visual_deferred_layers` category):

Present: "Deferred visual testing layers found: [layer names]. Run `/arn-spark-visual-readiness` (requires arn-spark plugin) to check if they can be activated now."

This is informational only — do not auto-fix or block the upgrade flow.

---

### Step U8: Task List Persistence Check

Check if `Task list ID` is present in the existing `## Arness` config.

**If NOT present:**

"Persistent task lists are not configured for this project. Would you like to enable them? (Recommended — ensures tasks survive across sessions)"

Options:
1. **Yes** (Recommended) — Set up with auto-generated ID based on project directory name
2. **Yes, with custom ID** — Let me specify the task list ID
3. **No** — Skip

If Yes: follow the same logic as Step 9b (derive ID, write to `.claude/settings.json`, add to `## Arness` config).

If No: skip silently.

**If already present:**
- Read `.claude/settings.json` and check if `CLAUDE_CODE_TASK_LIST_ID` matches the configured Task list ID
- If `.claude/settings.json` is missing or the env var is absent/mismatched: update it to match. Note: "Updated `.claude/settings.json` to match Task list ID: `<id>`."
- If matching: skip silently

### Step U9: Summarize

Present a change summary:

```
Upgrade Complete (Plugin version: X.Y.Z)

Changes made:
- Migrated legacy config: GitHub: yes → Platform: github + Issue tracker: github
- Added config field: Docs directory → .arness/docs/
- Added config field: Git → yes
- Added config field: Platform → github
- Added config field: Issue tracker → github
- Removed legacy field: GitHub
- Created directory: .arness/docs/
- Updated 4 templates to vX.Y.Z
- Created 7 GitHub labels
- Updated ## Arness config in CLAUDE.md

No changes to:
- Plans directory: plans/ (unchanged)
- Specs directory: specs/ (unchanged)
- Code patterns: .arness/code-patterns (unchanged)
- Pattern documentation (up to date)
```

List all created/modified files with their paths (same style as Step 10).

---

## Error Handling

- If the user cancels at any step, confirm and exit gracefully. Do not leave partially written configuration.
- If an agent invocation (`arn-code-codebase-analyzer` or `arn-code-pattern-architect`) fails or returns empty output, report the issue to the user and suggest providing pattern information manually.
- If writing to CLAUDE.md fails (e.g., permissions), inform the user and print the `## Arness` config block so they can insert it manually.
- **Upgrade mode:** If the `arn-code-doctor` agent fails during upgrade, fall back to offering Reconfigure or Keep.
- **Upgrade mode:** If template upgrade fails (file permission, missing source), warn and skip — do not abort the entire upgrade.
- **Upgrade mode:** If the user cancels mid-upgrade, persist whatever was already resolved and inform the user that the upgrade is partial.

## Re-running Arness Init

This skill is safe to re-run. When re-running:
- Step 1 detects the existing `## Arness` section and offers three options: Upgrade, Reconfigure, or Keep
- **Upgrade** (recommended after plugin updates): Runs arn-code-doctor to diagnose gaps and fills in only what's missing — no re-asking of existing questions
- **Reconfigure**: Re-runs the full setup flow with existing values as defaults — use this to change directories, regenerate patterns, or start fresh
- CLAUDE.md config section is updated in place

**Backward compatibility:** Missing `Docs directory` defaults to `.arness/docs/`. Missing `Git`/`Platform`/`Issue tracker` fields default to runtime detection (checks are run on demand by skills that need them). Legacy `GitHub: yes|no` configs are auto-migrated to `Platform` + `Issue tracker` during upgrade. After a plugin update, the Upgrade flow handles migration of these fields automatically.