<p align="center"> <img src="logo-banner.jpg" alt="nyann — bamboo scaffolding for your codebase" width="100%" /> </p>

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 26 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 — 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 63 cross-layer JSON shapes (ActionPlan, DriftReport, StackDescriptor, BootRecord, …) are locked by JSON Schema. A field rename without a schema bump fails CI. 1583 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 26 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.

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.

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:

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

What you get

Skills & commands

All 37 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):

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

Repository layout

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

Recent changes

See CHANGELOG.md for the full release history. Most recent: v1.12.0 — Proactive Awareness. nyann shifts from purely reactive to proactively surfacing drift, validating preconditions, and watching CI state — quiet unless something actually changed. Highlights:

• Mandatory setup gate with new /nyann:settings interactive menu (per-user preferences schema bumps to v2).
• Session-start triage UserPromptSubmit hook with fingerprint-based dedup — silent unless drift state changed.
• Pre-action guards (commit / pr / release / ship) — built-in checks for staged-files, merge-conflict markers, branch-pushed, WIP commits, clean-tree, with profile-promoted severity.
• Proactive commit hygiene — scope suggestion, incomplete-staging detection, debug-artifact + dead-code scan folded into /nyann:commit.
• Public-doc governance — version-ref, file-ref, script-ref, count-claim drift detectors fold into /nyann:doctor.
• README SVG toolkit — shields.io badge + skillicons.dev tech-stack generators with marker-bracketed idempotent rewrites.
• CI sentinel — /nyann:watch polls open PRs and queues state-transition notifications surfaced by the session-start hook.
• IaC minimal — infra archetype + terraform-monorepo starter profile + 5 IaC hook templates (fmt / validate / tflint / tfsec / terraform-docs) with install-hooks --iac phase.

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