/bootstrap-project

name: bootstrap-project
description: >
  Bootstrap a fresh or existing repo with nyann. TRIGGER when the user says "set up this project",
  "initialize git workflow", "bootstrap this repo", "scaffold this project", "ngyamm this repo",
  "use my <name> profile" / "apply the nextjs-prototype profile" (profile mode).
  ALSO trigger on "standard setup" / "usual stack" / "the usual setup" /
  "install all the standard hooks" / "give this repo the usual setup" /
  "make this repo standard" / "install nyann" — these read as opinionated bulk setup,
  not narrow edits, even though they sound small.
  Also trigger on any phrasing that mentions wiring up git hooks + branching +
  conventions + docs as a single opinionated setup. DO NOT trigger on narrow requests
  like "add a lint hook" or "update CLAUDE.md" — those are edits, not bootstraps.
  DO NOT trigger on "audit this project" / "fix what's drifted" / "bring into compliance" —
  those are retrofit. DO NOT trigger on "check this project's health" / "is this healthy" —
  those are doctor.
  When in doubt, run the detection step and ask.

bootstrap-project

You are executing nyann's main bootstrap flow. The goal is to take an empty directory, a fresh repo, or an existing messy repo and bring it up to the conventions in a nyann profile — without silently mutating anything.

**Work in phases.** Each phase is one or more bash scripts in `bin/`. Never run a destructive action outside a preview-confirmed plan. If a phase emits a structured skip record (`{"skipped": "...", "reason": "..."}`), log it in your final summary and continue with the remaining phases.

0. Team profile freshness check (quick, non-blocking)

Run `bin/check-team-staleness.sh` before starting. If it produces output, show the notification to the user (e.g. "Your team profiles have upstream changes. Run `/nyann:sync-team-profiles` to update before bootstrapping, or continue with the current versions."). Do not block — let the user decide whether to sync first.

1. Detect

1. Run `bin/detect-stack.sh --path <target>` and capture the JSON to a temp file (e.g. `bin/detect-stack.sh --path <target> > "${TMPDIR:-/tmp}/nyann-stack.json"`) so step 2 can pass it via `--stack`. Never proceed without it. 2. If `confidence < 0.6`, tell the user what you found and ask them to confirm the stack before continuing. Show the top two or three reasoning entries so they can see *why* you chose what you chose. 3. If `is_monorepo` is true, note it — bootstrap will auto-resolve per-workspace configs (hooks, lint-staged entries, commit scopes) using `bin/resolve-workspace-configs.sh`.

See `references/python.md` and `references/javascript.md` for stack-specific notes Claude should fold into its follow-ups. Only load them when the detected stack matches.

2. Pick a profile

Three branches:

• **User named a profile.** Load it with `bin/load-profile.sh <name>`. If the loader exits 2

(profile not found), list the available profiles it reported and ask the user to pick one.

• **No profile named.** Run `bin/suggest-profile.sh --target <repo> --stack <stack-json-file>`

to get a ranked list of matching profiles with confidence scores. Pass the StackDescriptor JSON captured in step 1 via `--stack` so the script reuses it instead of re-running detect-stack.sh (which would duplicate the directory walk).

Show the user the top suggestion (or top 2-3 if scores are close): > "Detected: TypeScript + Next.js. Suggested profile: `nextjs-prototype` (confidence: 90). > Use this profile?"

Rules:

• If the top suggestion has confidence ≥ 70, propose it directly.
• If the top suggestion has confidence 40-69, propose it but ask the user to confirm.
• If no suggestion has confidence ≥ 40, fall back to `default` — **warn the user**

because `default` means "skip all stack-specific hooks".

• If suggestions is empty (no matches at all), use `default` with the same warning.

**Multi-stack repos (monorepo with workspace_suggestions):** If the `workspace_suggestions[]` array is non-empty, each workspace has its own best-matching profile. Present per-workspace profile assignments to the user:

> "This monorepo has multiple stacks. Here are the suggested profiles: > > | Workspace | Stack | Suggested profile | Confidence | > |-----------|-------|-------------------|------------| > | apps/web | TypeScript + Next.js | `nextjs-prototype` | 90 | > | apps/api | TypeScript + Express | `node-api` | 85 | > | apps/mobile | Dart + Flutter | `flutter-app` | 92 | > > Accept these assignments?"

Rules for workspace profiles:

• If `workspace_suggestions[].confidence >= 70`, propose it directly.
• If confidence 40-69, include but flag for confirmation.
• If confidence < 40 or suggestion is null, workspace inherits the root profile.
• User can override any workspace assignment (e.g., "use `react-vite` for apps/web

instead").

• Confirmed workspace→profile mappings are written into the root profile's

`workspaces` field with `"profile": "<name>"` entries. This persists the choice for future bootstraps.

**Legacy secondary_suggestions:** If `workspace_suggestions` is empty but `secondary_suggestions` is non-empty, fall back to the legacy behaviour: mention the secondary stacks as informational.

• **Audit mode** ("check hygiene", "is this healthy"). Invoke the `doctor` skill instead.
• **Retrofit mode** ("fix what's drifted", "bring into compliance"). Invoke the `retrofit`

skill instead — it handles audit + remediation for existing repos.

3. Recommend branching (unless the profile already pins one)

1. Pipe the StackDescriptor into `bin/recommend-branch.sh`. 2. If `needs_user_confirm` is true, show the three top reasoning strings and ask the user to confirm before writing the strategy into the plan. 3. Otherwise, feed the recommendation straight into the action plan.

4. Route docs

4a. Archetype prompt (v1.6.0+)

The StackDesc