arn-spark-init

Arness Spark Init

Set up Arness for a greenfield project by configuring output directories for all greenfield artifacts and detecting the project's platform setup. This is optional — Arness Spark auto-configures with sensible defaults on first skill invocation. Use this to customize directories, add design tool integrations (Figma, Canva), or review your current settings.

This skill is lightweight and focused: it configures only what greenfield skills need (artifact directories and platform integration). It does NOT set up code patterns, report templates, plans, or documentation directories — those are handled when the project transitions to the development phase. Design tool integration (Figma/Canva) is only available through this skill — ensure-config does not configure design tools.

The ## Arness section written by this skill is forward-compatible with Arness Code and Arness Infra. When either plugin's ensure-config or init runs later, it detects the existing configuration and adds the remaining fields without disrupting greenfield 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
4. Ask via AskUserQuestion:
5. Review — Show current configuration summary, no changes
6. Update — Check for missing greenfield fields and fill them in
7. Reconfigure — Re-run the full setup flow from scratch
8. Keep — No changes
9. If Review → display a clean summary of all ## Arness fields relevant to Arness Spark, then exit the skill
10. If Keep → done, exit the skill
11. If Reconfigure → continue to Step 2, pre-filling known values as defaults
12. If Update → check which greenfield fields are missing (Vision directory, Use cases directory, Prototypes directory, Spikes directory, Visual grounding directory, Reports directory, Git, Platform, Issue tracker, Figma, Canva) and only process those. For missing directory fields, ask the user with the existing value as the default. For missing Git/Platform/Issue tracker, re-run Step 3 detection. For missing Figma/Canva, re-run Step 3.4 design tool integration. Then proceed to Step 4 to write the updated config. Preserve all existing fields that are not managed by this skill (such as Plans directory, Specs directory, Report templates, etc.).

Step 2: Configure Output Directories

Ask the user about each output directory. All defaults are under .arness/ to centralize Arness artifacts in one place.

2.1. Vision directory:

"Where should Arness store greenfield vision documents (product concept, architecture vision, style brief, spike results, feature backlog)?"

• Default: .arness/vision
• Used by: /arn-spark-discover, /arn-spark-arch-vision, /arn-spark-spike, /arn-spark-style-explore, /arn-spark-feature-extract, /arn-spark-dev-setup

2.2. Use cases directory:

"Where should Arness store use case documents?"

• Default: .arness/use-cases
• Used by: /arn-spark-use-cases, /arn-spark-use-cases-teams

2.3. Prototypes directory:

"Where should Arness store prototype versions and review reports?"

• Default: .arness/prototypes
• Used by: /arn-spark-static-prototype, /arn-spark-clickable-prototype

2.4. Spikes directory:

"Where should Arness store technical spike POC code?"

• Default: .arness/spikes
• Used by: /arn-spark-spike

2.5. Visual grounding directory:

"Where should Arness store visual grounding assets (reference images, design mockups, brand assets)?"

• Default: .arness/visual-grounding
• Used by: /arn-spark-style-explore, /arn-spark-static-prototype, /arn-spark-clickable-prototype

Create three subfolders inside the visual grounding directory: references/, designs/, brand/.

2.6. Reports directory:

"Where should Arness store stress test reports and other analysis output?"

• Default: .arness/reports
• Used by: /arn-spark-stress-interview, /arn-spark-stress-competitive, /arn-spark-stress-premortem, /arn-spark-stress-prfaq, /arn-spark-concept-review

After creating the Reports directory (mkdir -p <chosen-path>), also create the stress-tests/ subdirectory: mkdir -p <chosen-path>/stress-tests/

For each directory:

• Accept any relative path the user provides (relative to the project root)
• If updating an existing config (from Step 1), show the current path as the default
• Create the directory if it does not exist: mkdir -p <chosen-path>

Step 3: Detect Git, Platform, and Issue Tracker

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-code-init or arn-infra-init), skip detection and preserve the existing values — unless the user chose Reconfigure in Step 1. This prevents overwriting values set by another plugin 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 (Arness Code: /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 4.

3.2. Remote classification:

1. Run git remote -v and classify the remote URL:
2. Contains github.com → candidate: github
3. Contains bitbucket.org → candidate: bitbucket
4. 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-spark-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
2. If NOT available → read and show the setup instructions from ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-init/references/bkt-setup.md, then STOP init
3. Run bkt auth status to check authentication
4. If NOT authenticated → read and show the auth instructions from ${CLAUDE_PLUGIN_ROOT}/skills/arn-spark-init/references/bkt-setup.md, then STOP init
5. Platform: bitbucket (confirmed)
6. Ask (using AskUserQuestion):

> Do you use Jira for issue tracking on this project? > 1. Yes — Verify Atlassian MCP server and select a Jira project > 2. No — Skip issue tracker integrati