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):

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 defau