nyann

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 72 cross-layer JSON shapes (ActionPlan, DriftReport, StackDescriptor, BootRecord, …) are locked by JSON Schema. A field rename without a schema bump fails CI. 2136 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	ruby-rails	RuboCop	RuboCop	Bundler
Deno	deno-app	deno lint	deno fmt	deno
Bun	bun-app	ESLint (opt)	Biome / Prettier	bun
SvelteKit	sveltekit-app	ESLint, svelte-check	Prettier	npm / pnpm / yarn / bun
Astro	astro-site	ESLint, astro-check	Prettier	npm / pnpm / yarn / bun
Nuxt	nuxt-app	ESLint	Prettier	npm / pnpm / yarn / bun
Elixir / Phoenix	phoenix-app	mix credo	mix format	mix
NestJS	nestjs-service	ESLint	Prettier	npm / pnpm
C/C++ CMake	cpp-cmake	clang-tidy	clang-format	-
Terraform (monorepo)	terraform-monorepo	tflint, tfsec, terraform validate	terraform fmt	-
AWS CDK	aws-cdk-app	ESLint, cdk synth	Prettier	npm / pnpm / yarn / bun
Pulumi	pulumi-app	pulumi preview	-	-
Kubernetes / Kustomize	kubernetes-app	kubeconform, kube-linter, kustomize build	-	-
Helm chart	helm-chart	helm lint, helm template	-	-
Ansible	ansible-playbook	ansible-lint, yamllint, syntax-check	-	-
Any / Unknown	default	-	-	-

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
plugin	.claude-plugin/plugin.json, engines.vscode in package.json, browser-extension manifest.json with manifest_version	architecture.md, decisions/, glossary.md
fallback	unknown — when none of the above match	architecture.md, decisions/ (pre-v1.6.0 default)

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