Nyann

ငြမ်း is Burmese for scaffolding. Nyann is the Claude Code plugin that picks expert git defaults for your stack — branching, working hooks (Husky / pre-commit.com / lefthook), commits, releases, CI, docs — then keeps the repo on those rails through every PR after. Conversational by default; every destructive change is previewed, schema-validated, and reversible.

Is nyann for you?

Use nyann when:

• You start new projects more than once a month.
• You maintain multiple repos and want consistent hygiene across all of them.
• You use Claude Code and want git + hooks + docs setup to be conversational.
• You lead a small team and want shared conventions via profiles.

Skip nyann when:

• You start maybe one project a year. The setup time to learn nyann outweighs what it saves.
• You have mature internal scaffolding you're happy with.
• You want a code generator (nyann does not scaffold application code; that's create-next-app / cookiecutter territory).

What makes it different

• Working hooks for 31 stacks, not just configs. nyann installs the right framework — Husky for JS/TS, pre-commit.com for Python, lefthook for Go/Rust, native .git/hooks for shell, and per-tool IaC hooks (Terraform, CDK, Pulumi, Kubernetes, Helm, Ansible) — with hooks that run on day one. No follow-up husky install required.
• Preview before every mutation. Every destructive path emits a JSON ActionPlan, renders a unified diff for merges, and waits for confirmation. The plan is SHA-bound, so the bytes you approve are the bytes that land — no TOCTOU between preview and execute.
• Reversible. bootstrap and retrofit write a BootRecord (manifest + pre-state file copies) before mutating. /nyann:undo-bootstrap consumes it to restore your repo to its pre-setup state — refusing to clobber files you've edited since.
• Schema-validated contracts between every script. All 69 cross-layer JSON shapes (ActionPlan, DriftReport, StackDescriptor, BootRecord, …) are locked by JSON Schema. A field rename without a schema bump fails CI. 2038 bats tests cover the surface.
• Team-shareable governance. Profiles are pure data — register a git URL and your team's branching, hooks, conventions, and doc routing sync across every repo automatically. Stale-team-profile detection nudges before the next bootstrap.
• Health-graded, drift-aware. doctor produces a 0–100 score with per-category deltas and trend sparklines from memory/health.json. Inline drift checks at commit / PR / ship time nudge (don't gate) when the repo drifts from its profile; governance-check.yml upgrades that to a CI gate when desired.

Supported stacks

Working hooks, branching, commits, and docs across 31 stacks. Nyann detects yours automatically and applies the right profile — branching strategy, commit conventions, language-specific hooks (Husky, pre-commit.com, lefthook, …) wired up to run on day one, and archetype-aware documentation scaffolding. All profiles default to Conventional Commits + GitHub Flow.

Stack	Profile	Linting	Formatting	Package Manager
TypeScript / Next.js	nextjs-prototype	ESLint	Prettier	npm / pnpm / yarn / bun
TypeScript Library	typescript-library	ESLint, tsc	Prettier	npm / pnpm / yarn / bun
React + Vite	react-vite	ESLint	Prettier	npm / pnpm / yarn / bun
Node.js API	node-api	ESLint	Prettier	npm / pnpm / yarn / bun
Python CLI	python-cli	Ruff	Ruff	uv
Django	django-app	Ruff	Ruff	uv
FastAPI	fastapi-service	Ruff	Ruff	uv
Go	go-service	go vet, golangci-lint	gofmt	go
Rust	rust-cli	Clippy	rustfmt	cargo
Swift / iOS	swift-ios	SwiftLint	SwiftFormat	SPM
Kotlin / Android	kotlin-android	detekt	ktlint	Gradle
Shell / Bash	shell-cli	ShellCheck	shfmt	-
Java / Spring Boot	java-spring-boot	Checkstyle	-	Maven / Gradle
C# / .NET	dotnet-api	dotnet format	dotnet format	dotnet
PHP / Laravel	php-laravel	Pint	Pint	Composer
Dart / Flutter	flutter-app	dart analyze	dart format	pub
Ruby / Rails

All profiles also include block-main (prevent direct commits to main) and gitleaks (secret scanning) hooks.

Don't see your stack? You can create a custom profile or learn one from an existing repo.

Archetypes

Orthogonal to the stack (language + framework), nyann classifies every project into one of 7 archetypes that drive archetype-aware doc scaffolding. The same TypeScript stack can be a web-app, library, cli-tool, or plugin depending on what the repo does — and gets a different set of docs accordingly.

Archetype	Detected from	Scaffolds
api-service	OpenAPI / proto specs, or server frameworks (FastAPI, NestJS, Django, Rails, Spring Boot, Phoenix, Laravel, Gin, Echo, ASP.NET, …) without a frontend	architecture.md, api-reference.md, runbook.md, deployment.md, decisions/, glossary.md
web-app	Frontend frameworks (Next.js, Nuxt, SvelteKit, Astro, React, Vue, Remix)	architecture.md, runbook.md, deployment.md, decisions/, glossary.md
infra	IaC monorepo signals — Terraform (*.tf in root / modules/ / environments/), AWS CDK (cdk.json), Pulumi (Pulumi.yaml), Helm (Chart.yaml + values.yaml/templates/), Kustomize (kustomization.yaml)	architecture.md, runbook.md, deployment.md, decisions/, glossary.md
mobile-app	iOS (xcodeproj/Podfile), Android (AndroidManifest.xml), Flutter (pubspec.yaml + flutter dep), React Native (react-native/expo in package.json)	architecture.md, runbook.md, deployment.md, decisions/, glossary.md
cli-tool	package.json with bin, pyproject.toml with [project.scripts], Cargo [[bin]], Go cmd/*/main.go	architecture.md, runbook.md, decisions/, glossary.md
library	Published-package signals without an entry-point binary (main/module/exports in package.json, Cargo [lib], Swift Package.swift)	architecture.md, api-reference.md, decisions/, glossary.md

Detection runs in priority order: plugin → infra → mobile-app → frontend frameworks defer artifact-based api-service until web-app is checked → api-service (server frameworks) → cli-tool → library. This ordering means a full-stack repo with Next.js + an OpenAPI spec for backend route handlers classifies as web-app (frontend is the user-visible primary surface), not api-service.

Override detection by setting "archetype" in your profile, or pass --archetype <name> to /nyann:bootstrap / /nyann:route-docs. Archetype-aware scaffolding is opt-in via documentation.use_archetype_scaffolds: true in the profile.

Quickstart

1. Install nyann as a Claude Code plugin.

Install from the community marketplace (Anthropic-curated, reviewed releases):

claude plugin marketplace add anthropics/claude-plugins-community
claude plugin install nyann@claude-community

Or install from the nyann repo directly (latest tag, fastest to update):

/plugin marketplace add thettwe/nyann
/plugin install nyann@nyann-plugins

The community-marketplace listing is SHA-pinned and syncs nightly after Anthropic's review pipeline approves a new version, so it can lag behind by one or more tags. The direct path picks up new tags as soon as you run /plugin marketplace update. Use the direct path if you want the newest fixes immediately; use the community path if you prefer to wait for an Anthropic-reviewed release.

For development / hacking on nyann itself, clone directly:

git clone https://github.com/thettwe/nyann ~/.claude/plugins/nyann

2. Bootstrap a repo.

Open Claude Code in an empty (or existing) project directory and say:

"set up this project"

Or use the slash command directly:

/nyann:bootstrap

Claude detects your stack, previews a plan with a unified diff for merge actions, and on confirmation produces:

• Git initialized with the right base branches for the detected branching strategy
• .gitignore merged from stack-specific templates (existing user lines preserved — never overwritten)
• Working git hooks wired to the right framework: Husky (JS/TS), pre-commit.com (Python), lefthook (Go/Rust), or native .git/hooks (shell). Linting, formatting, Conventional-Commits validation, secret scanning, and block-main are runnable on day one.
• docs/ archetype-aware scaffold (api-service / cli-tool / library / web-app / mobile-app / plugin) — architecture, ADR-000, and matching templates
• memory/ with README plus the BootRecord under memory/.nyann/bootstraps/<ts>/ so the run is reversible
• CLAUDE.md as a router-mode file under the 3 KB soft cap (8 KB hard cap)
• .editorconfig, .github/workflows/ci.yml, .github/PULL_REQUEST_TEMPLATE.md, .github/ISSUE_TEMPLATE/, and CODEOWNERS (monorepo) when the profile opts in
• GitHub branch + tag protection auto-applied via gh if installed and authenticated

Total wall time on a clean directory: ~2 seconds (excluding npm install / pip install / etc.).

3. Keep using nyann.

You don't need to memorize slash commands. Just describe what you need:

You say	What happens
"commit these changes"	Generates a Conventional Commits message and commits
"start a feature branch for login"	Creates a strategy-compliant branch
"is this repo healthy?"	Graded health score (0–100), per-category deltas, sparkline trend from history
"cut a patch release"	Auto-detects the semver bump from Conventional Commits, regenerates CHANGELOG, tags, optionally creates a GitHub release
"pull and rebase"	Syncs upstream changes with conflict guidance
"undo that"	Reverses the last commit on a feature branch
"undo the bootstrap"	Reverses the last bootstrap (or retrofit) run from its boot record
"open a PR"	Creates a GitHub PR from the current branch
"ship it"	Opens a PR and either auto-merges (returns immediately) or polls CI then merges
"generate CI for this project"	Writes a GitHub Actions workflow + optional governance gate

Every skill also has a slash command (/nyann:commit, /nyann:doctor, etc.) listed in the full command reference below.

What you get

Area	What nyann does
Bootstrap	Stack-detected, schema-validated ActionPlan previewed before any write. Per-language working hooks, archetype-aware doc scaffolds, CI workflow, GitHub templates, branch + tag protection, and .gitignore merge with diff-preview. Monorepo-aware (pnpm / Turborepo / Nx / Lerna / Cargo workspaces).
Reversibility	bootstrap / retrofit write a BootRecord (manifest + pre-state file copies) before mutating; /nyann:undo-bootstrap reverses the run. Refusal-by-default protects files edited after bootstrap, branches with stacked commits, and HEAD ahead of the bootstrap seed.
Retrofit	Scoped audit + remediation against a profile. --scope docs|hooks|branching|gitignore|editorconfig|github lets you fix one category without touching the others. Idempotent — safe to re-run. Boot-record-backed, so it's reversible too.
Doctor	Read-only hygiene audit with a numerical health score (0–100) persisted to memory/health.json, rendered as a per-category sparkline trend. Covers hook drift, gitignore, non-Conventional history, broken internal links, doc orphans, doc staleness, archetype conformance (misplaced docs), CLAUDE.md size budget, and GitHub protection drift. --explain flag pipes the drift report through explain-diff for a plain-English summary.
Commit	Reads the staged diff, generates a Conventional Commits message scoped to touched workspaces (monorepo), and retries once on hook rejection.
Branch	Creates strategy-compliant branch names off the right base for the active strategy (GitHub Flow / GitFlow / trunk-based). Validates slug; switches to an existing branch if one already matches.
PR	Opens a GitHub PR with a Conventional-Commits-style title generated from the commit range and a body summarizing the diff. Context-only mode works without gh.
Ship	Combined PR + merge in one step. Default uses GitHub's native auto-merge so the terminal returns immediately with outcome:"queued". --client-side polls CI in the foreground and runs gh pr merge when checks pass.
Release

Skills & commands

Command	Purpose
/nyann:setup	First-run onboarding + preferences. Optional --simulate <path> previews what /nyann:bootstrap would do without writing.
/nyann:bootstrap [--profile <name>]	Full setup flow.
/nyann:retrofit [--profile <name>] [--json]	Audit drift + offer remediation.
/nyann:doctor [--profile <name>] [--json] [--explain]	Read-only hygiene + docs audit. --explain translates drift to plain English.
/nyann:commit	Generate + commit a Conventional Commits message.
/nyann:branch <purpose> <slug-or-version>	Strategy-compliant branch creation.
/nyann:pr [--draft] [--auto-merge]	Open a GitHub PR from current branch.
/nyann:ship [--client-side] [--merge-strategy s]	Combined PR + auto-merge (or poll-and-merge).
/nyann:wait-for-pr-checks [--pr <n>] [--timeout <s>]	Poll a PR's checks until pass / fail / timeout.
/nyann:release --version <x.y.z>	Generate changelog, commit, and tag.
/nyann:hotfix --from <tag> --slug <slug>	Set up hotfix branch topology.
/nyann:sync	Pull + rebase with conflict guidance.
/nyann:undo [--hard]	Reverse last commit on a feature branch.
/nyann:undo-bootstrap [--manifest <path>] [--scope <csv>] [--force] [--dry-run]	Reverse a bootstrap or retrofit run from its BootRecord manifest.
/nyann:cleanup-branches [--yes]	Prune local branches whose work is merged.
/nyann:gen-ci [--profile <name>]	Generate GitHub Actions CI workflow.
/nyann:gen-templates [--profile <name>]	Generate PR + issue templates.
/nyann:gen-claudemd [--profile <name>] [--force]	Regenerate CLAUDE.md without a full bootstrap.
/nyann:gen-dependency-updater

All 39 skills respond to natural language, not just slash commands. See skills/*/SKILL.md for trigger-phrase lists. Every skill above also has a commands/*.md slash entry — invoke either way.

Profiles

Customizing profiles

Nyann picks the right profile automatically. If the starter profiles don't fit, you have two options:

Learn from an existing repo. If you already have a well-configured project, nyann can extract a reusable profile from it:

bin/learn-profile.sh --target ~/projects/my-good-app --name good-app

This infers stack, hooks, branching, and conventions from the repo's files and last 50 commits.

Inspect any profile. To see what a profile contains before using it:

bin/inspect-profile.sh nextjs-prototype

Profile precedence

When multiple profiles exist with the same name, the most specific one wins:

1. ~/.claude/nyann/profiles/<name>.json user profiles
2. ~/.claude/nyann/cache/<source>/.../<name>.json team profiles (synced from a git URL)
3. <plugin>/profiles/<name>.json starter profiles

A namespaced name like our-team/frontend-baseline bypasses user shadowing.

Team profiles

Share conventions across a team by syncing profiles from a git repo:

# Register a source — optionally pinned to a tag, SHA, or branch
bin/add-team-source.sh --name our-team \
  --url https://github.com/our-org/nyann-profiles.git \
  --pin-strategy tag --pin-ref v1.0.0

# Sync (shallow clone, respects sync_interval_hours)
bin/sync-team-profiles.sh [--force]

# When pinned: check what would change before accepting an update
bin/sync-team-profiles.sh --check-updates --name our-team
bin/sync-team-profiles.sh --accept-update --name our-team

When a team profile updates upstream, nyann checks for staleness at point-of-use (during bootstrap and profile migration) and prompts you to sync before proceeding. SHA and tag pinning (v1.11.0) keep the team source on a known-good revision; updates require explicit --accept-update and surface a changelog of what changed.

Profile composition (extends)

Avoid copy-paste between similar profiles. A child profile can inherit from a parent via "extends":

{
  "name": "my-react-vite",
  "extends": "react-vite",
  "branching": { "scopes": ["api", "web"] }
}

Deep merge semantics: scalars and objects merge recursively (child wins), arrays replace entirely, null removes a parent's field. Max chain depth: 3. Circular references are rejected. Namespaced team/name form is supported for team-source parents.

Project Memory

nyann scaffolds and maintains your project's Project Memory — a documentation layer designed for AI agents to retrieve, sized to fit their context, and kept in sync as your code evolves.

   CLAUDE.md  ──→  docs/        (durable Project Memory)
       │      ──→  memory/      (ephemeral team scratch)
       │
       └─ router-mode (≤ 3 KB), points into both.

Five properties define it:

1. AI-retrieval-first — bounded scope per doc, predictable structure, decision rationale captured.
2. Size-budgeted — docs fit in context windows. CLAUDE.md is router-mode (≤3 KB soft cap), not a content dump.
3. Drift-aware — broken links, orphans, and staleness surfaced automatically by doctor and CI.
4. Storage-agnostic — local Markdown, Obsidian (MCP), or Notion (MCP). Equal citizens.
5. Dual-audience — high-signal structure works for AI agents AND humans reading reference docs.

See docs/principles/documentation.md for the full definition.

Storage routing

By default CLAUDE.md links to local docs/ and memory/.

When Claude Code has an Obsidian or Notion MCP configured, nyann asks where each doc type should live:

adrs:obsidian, research:local, architecture:local

memory/ is always local — it's the ephemeral team-shared scratch layer, distinct from Project Memory itself.

Prereqs

Run /nyann:check-prereqs (or bin/check-prereqs.sh) for a live inventory.

Hard (required):

• git
• jq (brew install jq / apt install jq)
• bash 3.2+ (macOS default is fine)

Soft (feature-gated; nyann skips with a reason when missing):

Feature	Needs
JS/TS hooks	node + npm / pnpm / yarn / bun
Python hooks	python3 + pre-commit (or uv / uvx)
Go hooks	go
Rust hooks	cargo
Swift hooks	swiftlint, swiftformat
Kotlin hooks	ktlint, detekt
Shell hooks	shellcheck, shfmt
Secret scanning	gitleaks
Branch protection	gh with gh auth status green
Schema validation	uv (provides uvx check-jsonschema) or check-jsonschema
Dev loop	shellcheck, bats-core

Nyann never prompts for credentials. gh auth status is a passive read; missing auth surfaces as a skip, not a prompt.

Repository layout

bin/                   # 93 top-level shell scripts + 65 extracted modules + 1 python helper
commands/              # 39 Claude Code slash-command registrations
evals/                 # 26 skill-level trigger + output-quality specs
hooks/                 # Claude Code PreToolUse + UserPromptSubmit hooks
profiles/              # 32 starter profiles (+ _schema.json)
schemas/               # 69 JSON Schemas for every exchanged shape
skills/                # 39 skills (SKILL.md, optionally with references/ and scripts/)
templates/             # gitignore, pre-commit configs (incl. iac), husky, docs, CI, memory, launchd/systemd daemon units
monitors/              # Monitor manifest (monitors.json, currently empty)
tests/                 # 2038 bats tests + fixtures

Recent changes

See CHANGELOG.md for the full release history. Most recent: v1.13.0 — Infrastructure as Code. nyann becomes first-class for IaC repos and completes the proactive-awareness arc — the CI sentinel now runs in the background, delivers to external channels, and aggregates across repos. Highlights:

• First-class IaC for AWS CDK, Pulumi, Kubernetes / Kustomize, Helm, and Ansible (alongside Terraform / OpenTofu) — 5 new starter profiles, deep workspace discovery (unit dependency graph), drift detection, and per-unit / per-chart versioning.
• Plan/apply preview — /nyann:plan (read-only add/change/destroy summary, never applies) and /nyann:apply (opt-in, confirm-first, destroy-gated, credentials off argv) writing an audit IacApplyRecord.
• Backgrounded CI sentinel daemon — supervised under launchd / systemd user unit / nohup, with single-instance guard, 8h orphan backstop, and exponential backoff; doctor surfaces running and stale daemons.
• External notification delivery — Slack / Discord / webhook / email channels wired at the producer; secrets referenced by env-var name (never stored in preferences).
• Multi-repo aggregation — a watch-list + rate-limit-aware scheduler, read-notifications --all repo-tagged merged view, and a backgrounded aggregate daemon.
• Coverage-delta PR guard — opt-in, advisory: reuses an existing CI coverage artifact and warns when coverage drops past a threshold; never runs a suite, never blocks.

---

Issues and feature requests: https://github.com/thettwe/nyann/issues.