setup

name

setup

description

First-run onboarding for nyann. Creates the user config directory, collects preferences through AskUserQuestion interactive pickers, and writes ~/.claude/nyann/preferences.json. TRIGGER when the user says "set up nyann", "configure nyann", "nyann setup", "onboard me", "first time using nyann", "initialize nyann", "nyann first run", "get nyann ready", "/nyann:setup". ALSO trigger when: the user runs any nyann command for the first time and ~/.claude/nyann/preferences.json does not exist — suggest running setup first, but don't block them. Do NOT trigger on "set up this project" or "bootstrap this repo" — those are bootstrap-project. Do NOT trigger on "check prereqs" — that is check-prereqs. This skill configures nyann itself, not a repo.

setup

CRITICAL: This skill uses the AskUserQuestion tool for ALL user choices. NEVER ask questions as plain text. Every user choice goes through AskUserQuestion with the exact JSON shown below.

Script paths: nyann is a Claude Code plugin, NOT a CLI tool. Do NOT search for it via which, npm list, pip list, or brew list. All scripts are at the plugin root. Determine the plugin root from this SKILL.md's path (<plugin_root>/skills/setup/SKILL.md) — the scripts are at <plugin_root>/bin/. Use bash <plugin_root>/bin/<script> for all commands below.

Re-runnable: if preferences already exist, show current values and offer to update them.

Step 1: Status + prereqs (parallel, one turn)

Run both commands in parallel (single tool-call turn):

• bash <plugin_root>/bin/setup.sh --check --json
• bash <plugin_root>/bin/check-prereqs.sh --json

Do NOT show the raw JSON to the user. Parse the prereqs array and build separate small tables by category. Use pipe-delimited markdown (NO box-drawing characters, NO manual padding). Shorten version strings (e.g., git version 2.50.1 (Apple Git-155) → 2.50.1).

Example output:

**Required**

| Tool | Status | Version |
|---|---|---|
| git | ok | 2.50.1 |
| jq | ok | 1.7.1 |
| bash | ok | 3.2.57 |

**JS / TS**

| Tool | Status | Version |
|---|---|---|
| node | ok | v25.9.0 |
| pnpm | ok | 10.13.1 |

**Python**

| Tool | Status | Version |
|---|---|---|
| python3 | ok | 3.14.4 |
| pre-commit | ok | 4.6.0 |
| uv | ok | 0.9.15 |

**Other**

| Tool | Status | Version |
|---|---|---|
| go | ok | 1.26.2 |
| cargo | missing | https://rustup.rs |
| gh | ok | 2.83.1 |
| gitleaks | ok | 8.30.1 |
| shellcheck | ok | 0.11.0 |

All hard prerequisites satisfied.

Group tools by: Required (kind=hard), JS / TS (node, npm, pnpm, yarn, bun), Python (python3, pre-commit, uv), Other (everything else). Skip empty groups. For missing tools, show the hint field instead of a version.

Then display a single combined message:

• If status == "configured": show current preferences as a table, then ask "Want to update any of these?" If no, skip to Step 4.

• If status == "not_configured": show the welcome greeting, then the prereqs table, then continue to Step 2 immediately:

  Welcome to nyann! Let's get you set up.

Continue to Step 2 — do NOT pause for prereqs.

Step 2: Quick or custom setup

Call AskUserQuestion — this is the first and possibly only picker:

{
  "questions": [
    {
      "question": "How would you like to configure nyann?",
      "header": "Setup",
      "multiSelect": false,
      "options": [
        { "label": "Quick setup (Recommended)", "description": "Use smart defaults: auto-detect stack & branching, conventional commits, GitHub CLI enabled, local docs" },
        { "label": "Customize", "description": "Choose each setting individually" }
      ]
    }
  ]
}

• Quick setup → skip to Step 3 with all defaults.
• Customize → continue to Step 2b.

Step 2b: Custom preferences (only if Customize)

Check command -v gh first. If gh is NOT installed, skip the GitHub CLI question and default to --no-gh-integration.

Call AskUserQuestion with up to 4 questions:

{
  "questions": [
    {
      "question": "What stack do you work with most often?",
      "header": "Stack",
      "multiSelect": false,
      "options": [
        { "label": "Auto-detect (Recommended)", "description": "nyann inspects the repo each time and picks the right profile" },
        { "label": "Next.js", "description": "nextjs-prototype profile — React + Next.js projects" },
        { "label": "FastAPI", "description": "fastapi-service profile — Python FastAPI services" },
        { "label": "Python CLI", "description": "python-cli profile — command-line Python tools" }
      ]
    },
    {
      "question": "Which branching strategy should nyann default to?",
      "header": "Branching",
      "multiSelect": false,
      "options": [
        { "label": "Auto-detect (Recommended)", "description": "nyann picks based on project size and type" },
        { "label": "GitHub Flow", "description": "Simple: main + feature branches" },
        { "label": "GitFlow", "description": "main + develop + feature/release/hotfix branches" },
        { "label": "Trunk-based", "description": "Short-lived branches, frequent merges to main" }
      ]
    },
    {
      "question": "Which commit message format should nyann enforce?",
      "header": "Commits",
      "multiSelect": false,
      "options": [
        { "label": "Conventional Commits (Recommended)", "description": "Enforces feat:, fix:, chore: etc. in commit hooks" },
        { "label": "Custom", "description": "No commit format enforcement" }
      ]
    },
    {
      "question": "Enable GitHub CLI integration for branch protection and PR helpers?",
      "header": "GitHub CLI",
      "multiSelect": false,
      "options": [
        { "label": "Yes (Recommended)", "description": "Enable branch protection audit and PR helpers via gh" },
        { "label": "No", "description": "Skip all gh-dependent features" }
      ]
    }
  ]
}

Docs and team sync use defaults (local, no). These are rarely changed and not worth an extra picker round-trip. Users who need non-default values can re-run /nyann:setup or use /nyann:route-docs.

Step 3: Write preferences

Value mapping

Picker label	Flag	Value
Auto-detect (Stack)	--default-profile	auto-detect
Next.js	--default-profile	nextjs-prototype
FastAPI	--default-profile	fastapi-service
Python CLI	--default-profile	python-cli
Auto-detect (Branching)	--branching-strategy	auto-detect
GitHub Flow	--branching-strategy	github-flow
GitFlow	--branching-strategy	gitflow
Trunk-based	--branching-strategy	trunk-based
Conventional Commits (Recommended)	--commit-format	conventional-commits
Custom	--commit-format	custom
Yes (GitHub CLI)	--gh-integration	(flag only)
No (GitHub CLI)	--no-gh-integration	(flag only)

If user picked "Other" for Stack, map to the matching profile name (react-vite, node-api, typescript-library, django-app, go-service, rust-cli, swift-ios, kotlin-android, shell-cli, default).

Use the exact values above. Never abbreviate (conventional-commits not conventional).

Quick setup defaults

bash <plugin_root>/bin/setup.sh \
  --default-profile auto-detect \
  --branching-strategy auto-detect \
  --commit-format conventional-commits \
  --gh-integration \
  --documentation-storage local \
  --no-auto-sync-team-profiles

If gh is not installed, use --no-gh-integration instead.

Custom setup

bash <plugin_root>/bin/setup.sh \
  --default-profile <mapped-value> \
  --branching-strategy <mapped-value> \
  --commit-format <mapped-value> \
  --gh-integration | --no-gh-integration \
  --documentation-storage local \
  --no-auto-sync-team-profiles

Step 3b: Optional simulation (v1.7.0+)

After preferences are written but before showing the final summary, ask the user if they want to see what /nyann:bootstrap would do in their current project. This is a no-mutation preview.

Call AskUserQuestion:

{
  "questions": [{
    "question": "Want to see what /nyann:bootstrap would do in your current repo?",
    "header": "Simulate",
    "multiSelect": false,
    "options": [
      { "label": "Yes",  "description": "Detect stack + suggest profile + plan writes; no changes" },
      { "label": "Skip", "description": "Move on to the summary" }
    ]
  }]
}

If the user picks Yes, run:

bash <plugin_root>/bin/setup.sh \
  --simulate "$PWD" \
  --default-profile <chosen-or-auto-detect> \
  --branching-strategy <chosen-or-auto-detect> \
  --commit-format <chosen> \
  --documentation-storage local

Echo the simulator's stderr verbatim — it's already formatted for human reading. Then proceed to Step 4.

If simulation: "partial" appears (monorepo case), tell the user the plan covers the base writes only and that running /nyann:bootstrap will add per-workspace lint-staged + commit scopes on top.

Step 4: Summary

Show a rich summary table and a clear next action:

**nyann configured!**

| Setting    | Value                |
|------------|----------------------|
| Stack      | auto-detect          |
| Branching  | auto-detect          |
| Commits    | conventional-commits |
| GitHub CLI | enabled              |
| Docs       | local                |
| Team sync  | off                  |

**Next:** run `/nyann:bootstrap` in a project to set it up.
Run `/nyann:setup` anytime to change these.

When to hand off

• "Now bootstrap this repo" → bootstrap-project skill.
• "Check my tools" → check-prereqs skill.
• "Add team profiles" → add-team-source skill.