Nyann

ငြမ်း is Burmese for scaffolding. Nyann is a Claude Code plugin that sets up and maintains project governance: git workflow, hooks, branching, commits, releases, CI, docs routing, and health monitoring. From first init through every PR after.

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).

Supported stacks

Nyann detects your stack automatically and applies the right profile. Every profile includes branching strategy, commit conventions, and documentation scaffolding. All profiles use Conventional Commits and GitHub Flow by 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.

Quickstart

1. Install nyann as a Claude Code plugin.

Install from the community marketplace:

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

Or install from the nyann repo directly:

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

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, and on confirmation produces:

• Initialized git with correct base branches
• .gitignore assembled from stack-aware templates
• Git hooks (linting, formatting, Conventional Commits, secret scanning, per stack)
• docs/ (architecture, ADR-000 + template) and memory/ with README
• CLAUDE.md as a compact router under 3 KB
• .editorconfig if the profile declares it

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 31 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
bin/add-team-source.sh --name our-team --url https://github.com/our-org/nyann-profiles.git

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

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.

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/                   # 65 shell scripts + 1 python helper (orchestrators + subsystems)
commands/              # 31 Claude Code slash-command registrations
evals/                 # 25 skill-level trigger + output-quality specs
hooks/                 # Claude Code PreToolUse block-main hook
profiles/              # 18 starter profiles (+ _schema.json)
schemas/               # 43 JSON Schemas for every exchanged shape
skills/                # 31 skills (SKILL.md, optionally with references/ and scripts/)
templates/             # gitignore, pre-commit configs, husky, docs, CI, memory
monitors/              # Monitor manifest (monitors.json, currently empty)
tests/                 # 820 bats tests + fixtures

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