\n\n# Nyann\n\n> **ငြမ်း** 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.\n\n[](LICENSE)\n[](https://github.com/thettwe/nyann/actions/workflows/ci.yml)\n[](tests/)\n[](https://github.com/thettwe/nyann/releases)\n\n## Is nyann for you?\n\n**Use nyann when:**\n\n- You start new projects more than once a month.\n- You maintain multiple repos and want consistent hygiene across all of them.\n- You use Claude Code and want git + hooks + docs setup to be conversational.\n- You lead a small team and want shared conventions via profiles.\n\n**Skip nyann when:**\n\n- You start maybe one project a year. The setup time to learn nyann outweighs what it saves.\n- You have mature internal scaffolding you're happy with.\n- You want a code generator (nyann does not scaffold application code; that's `create-next-app` / `cookiecutter` territory).\n\n## What makes it different\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **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.\n- **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.\n\n## Supported stacks\n\n**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.\n\n| Stack | Profile | Linting | Formatting | Package Manager |\n|---|---|---|---|---|\n| TypeScript / Next.js | `nextjs-prototype` | ESLint | Prettier | npm / pnpm / yarn / bun |\n| TypeScript Library | `typescript-library` | ESLint, tsc | Prettier | npm / pnpm / yarn / bun |\n| React + Vite | `react-vite` | ESLint | Prettier | npm / pnpm / yarn / bun |\n| Node.js API | `node-api` | ESLint | Prettier | npm / pnpm / yarn / bun |\n| Python CLI | `python-cli` | Ruff | Ruff | uv |\n| Django | `django-app` | Ruff | Ruff | uv |\n| FastAPI | `fastapi-service` | Ruff | Ruff | uv |\n| Go | `go-service` | go vet, golangci-lint | gofmt | go |\n| Rust | `rust-cli` | Clippy | rustfmt | cargo |\n| Swift / iOS | `swift-ios` | SwiftLint | SwiftFormat | SPM |\n| Kotlin / Android | `kotlin-android` | detekt | ktlint | Gradle |\n| Shell / Bash | `shell-cli` | ShellCheck | shfmt | - |\n| Java / Spring Boot | `java-spring-boot` | Checkstyle | - | Maven / Gradle |\n| C# / .NET | `dotnet-api` | dotnet format | dotnet format | dotnet |\n| PHP / Laravel | `php-laravel` | Pint | Pint | Composer |\n| Dart / Flutter | `flutter-app` | dart analyze | dart format | pub |\n| Ruby / Rails | `ruby-rails` | RuboCop | RuboCop | Bundler |\n| Deno | `deno-app` | deno lint | deno fmt | deno |\n| Bun | `bun-app` | ESLint (opt) | Biome / Prettier | bun |\n| SvelteKit | `sveltekit-app` | ESLint, svelte-check | Prettier | npm / pnpm / yarn / bun |\n| Astro | `astro-site` | ESLint, astro-check | Prettier | npm / pnpm / yarn / bun |\n| Nuxt | `nuxt-app` | ESLint | Prettier | npm / pnpm / yarn / bun |\n| Elixir / Phoenix | `phoenix-app` | mix credo | mix format | mix |\n| NestJS | `nestjs-service` | ESLint | Prettier | npm / pnpm |\n| C/C++ CMake | `cpp-cmake` | clang-tidy | clang-format | - |\n| Terraform (monorepo) | `terraform-monorepo` | tflint, tfsec, terraform validate | terraform fmt | - |\n| AWS CDK | `aws-cdk-app` | ESLint, cdk synth | Prettier | npm / pnpm / yarn / bun |\n| Pulumi | `pulumi-app` | pulumi preview | - | - |\n| Kubernetes / Kustomize | `kubernetes-app` | kubeconform, kube-linter, kustomize build | - | - |\n| Helm chart | `helm-chart` | helm lint, helm template | - | - |\n| Ansible | `ansible-playbook` | ansible-lint, yamllint, syntax-check | - | - |\n| Any / Unknown | `default` | - | - | - |\n\nAll profiles also include `block-main` (prevent direct commits to main) and `gitleaks` (secret scanning) hooks.\n\nDon't see your stack? You can [create a custom profile](#customizing-profiles) or [learn one from an existing repo](#customizing-profiles).\n\n## Archetypes\n\nOrthogonal 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.\n\n| Archetype | Detected from | Scaffolds |\n|---|---|---|\n| `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` |\n| `web-app` | Frontend frameworks (Next.js, Nuxt, SvelteKit, Astro, React, Vue, Remix) | `architecture.md`, `runbook.md`, `deployment.md`, `decisions/`, `glossary.md` |\n| `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` |\n| `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` |\n| `cli-tool` | `package.json` with `bin`, `pyproject.toml` with `[project.scripts]`, Cargo `[[bin]]`, Go `cmd/*/main.go` | `architecture.md`, `runbook.md`, `decisions/`, `glossary.md` |\n| `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` |\n| `plugin` | `.claude-plugin/plugin.json`, `engines.vscode` in `package.json`, browser-extension `manifest.json` with `manifest_version` | `architecture.md`, `decisions/`, `glossary.md` |\n| _fallback_ | `unknown` — when none of the above match | `architecture.md`, `decisions/` (pre-v1.6.0 default) |\n\nDetection 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`.\n\nOverride detection by setting `\"archetype\"` in your profile, or pass `--archetype ` to `/nyann:bootstrap` / `/nyann:route-docs`. Archetype-aware scaffolding is opt-in via `documentation.use_archetype_scaffolds: true` in the profile.\n\n## Quickstart\n\n**1. Install nyann as a Claude Code plugin.**\n\nInstall from the community marketplace (Anthropic-curated, reviewed releases):\n\n```text\nclaude plugin marketplace add anthropics/claude-plugins-community\nclaude plugin install nyann@claude-community\n```\n\nOr install from the nyann repo directly (latest tag, fastest to update):\n\n```text\n/plugin marketplace add thettwe/nyann\n/plugin install nyann@nyann-plugins\n```\n\n> 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.\n\nFor development / hacking on nyann itself, clone directly:\n\n```sh\ngit clone https://github.com/thettwe/nyann ~/.claude/plugins/nyann\n```\n\n**2. Bootstrap a repo.**\n\nOpen Claude Code in an empty (or existing) project directory and say:\n\n> \"set up this project\"\n\nOr use the slash command directly:\n\n> `/nyann:bootstrap`\n\nClaude detects your stack, previews a plan with a unified diff for merge actions, and on confirmation produces:\n\n- Git initialized with the right base branches for the detected branching strategy\n- `.gitignore` merged from stack-specific templates (existing user lines preserved — never overwritten)\n- **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.\n- `docs/` archetype-aware scaffold (api-service / cli-tool / library / web-app / mobile-app / plugin) — architecture, ADR-000, and matching templates\n- `memory/` with README plus the BootRecord under `memory/.nyann/bootstraps//` so the run is reversible\n- `CLAUDE.md` as a router-mode file under the 3 KB soft cap (8 KB hard cap)\n- `.editorconfig`, `.github/workflows/ci.yml`, `.github/PULL_REQUEST_TEMPLATE.md`, `.github/ISSUE_TEMPLATE/`, and `CODEOWNERS` (monorepo) when the profile opts in\n- GitHub branch + tag protection auto-applied via `gh` if installed and authenticated\n\nTotal wall time on a clean directory: **~2 seconds** (excluding `npm install` / `pip install` / etc.).\n\n**3. Keep using nyann.**\n\nYou don't need to memorize slash commands. Just describe what you need:\n\n| You say | What happens |\n|---|---|\n| \"commit these changes\" | Generates a Conventional Commits message and commits |\n| \"start a feature branch for login\" | Creates a strategy-compliant branch |\n| \"is this repo healthy?\" | Graded health score (0–100), per-category deltas, sparkline trend from history |\n| \"cut a patch release\" | Auto-detects the semver bump from Conventional Commits, regenerates CHANGELOG, tags, optionally creates a GitHub release |\n| \"pull and rebase\" | Syncs upstream changes with conflict guidance |\n| \"undo that\" | Reverses the last commit on a feature branch |\n| \"undo the bootstrap\" | Reverses the last `bootstrap` (or `retrofit`) run from its boot record |\n| \"open a PR\" | Creates a GitHub PR from the current branch |\n| \"ship it\" | Opens a PR and either auto-merges (returns immediately) or polls CI then merges |\n| \"generate CI for this project\" | Writes a GitHub Actions workflow + optional governance gate |\n\nEvery skill also has a slash command (`/nyann:commit`, `/nyann:doctor`, etc.) listed in the [full command reference](#skills--commands) below.\n\n## What you get\n\n| Area | What nyann does |\n|---|---|\n| **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). |\n| **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. |\n| **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. |\n| **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. |\n| **Commit** | Reads the staged diff, generates a Conventional Commits message scoped to touched workspaces (monorepo), and retries once on hook rejection. |\n| **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. |\n| **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`. |\n| **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. |\n| **Release** | **Auto-detects the next semver bump** from Conventional Commits since the last tag. Generates the CHANGELOG section, optionally bumps profile-declared manifest files (`package.json`, `plugin.json`, `pyproject.toml`, …), creates an annotated tag, pushes a GitHub release. Pre-release support for `-rc.N` / `-beta.N`. CI-gated tagging — `--push` waits for green CI on HEAD's PR by default (opt out with `--no-wait-for-checks`). Monorepo: `--workspace` and `--all-workspaces` for per-workspace versioning with scoped tags (`core@2.1.0`); `--batch-commit` groups all workspace releases into a single commit. |\n| **Hotfix** | Branch topology for patch releases against a previously tagged version. Creates `release/.` from the source tag if missing, then `hotfix/` off it. Pairs with `release` for the actual cut. |\n| **PR risk score** | `/nyann:ship` computes a composite risk score (churn × test gap × health delta) and surfaces `low | medium | high` with actionable recommendations before opening the PR. Highlights \"many source changes without matching test updates\" and hotspot files. |\n| **CI generation** | Generates `.github/workflows/ci.yml` matched to your stack and profile (lint + typecheck + test jobs). Optional `governance-check.yml` posts inline PR comments when drift exceeds threshold or health drops below the floor. |\n| **GitHub protection** | Audit (`--check`) or apply branch protection, tag rulesets, signing requirements, security settings, and Dependabot config. Output validates against `protection-audit.schema.json` so other tooling can consume it. |\n| **Docs routing** | Routes docs to local Markdown, Obsidian (MCP), Notion (MCP), or a per-doc-type split. Standalone re-routing after bootstrap regenerates the scaffold to match. `memory/` stays local. |\n| **Glossary** | Auto-populates `docs/glossary.md` from detected exported types (Go, TS, JS, Python, Rust, Java, Kotlin, Swift) at bootstrap and retrofit time. Marker-bracketed auto block; user content outside markers is preserved. Profile-gated via `documentation.glossary.auto_populate`. |\n| **CLAUDE.md** | Router-mode generation under 3 KB soft / 8 KB hard cap. Standalone regeneration via `gen-claudemd`. **Usage-based optimization** trims sections Claude never references, based on `analytics/claudemd-usage.jsonl`. |\n| **Inline drift checks** | Drift detection runs at point-of-use (commit / PR / ship / release) — not on session start. Surfaces broken links, orphans, doc staleness, CLAUDE.md size, and protection drift. Non-blocking nudge by default; CI gate on opt-in. |\n| **IaC governance** | First-class support for Terraform / OpenTofu, AWS CDK, Pulumi, Kubernetes / Kustomize, Helm, and Ansible. `/nyann:plan` previews a read-only add/change/destroy summary; `/nyann:apply` is opt-in with a destroy-gate, credentials kept off argv, and an audit `IacApplyRecord`. Drift detection (unpinned refs, missing lockfiles, secrets-in-vars, version-lag) folds into `doctor`; `release` versions each unit / chart independently in dependency order. |\n| **CI sentinel** | `/nyann:watch` polls open PRs for state transitions (checks / review / merge) and queues notifications. Runs as a supervised background daemon (launchd / systemd / `nohup`), delivers to Slack / Discord / webhook / email (secrets referenced by env-var name, never stored), a per-repo GitHub issue digest (one issue, one comment per batch), or a native OS toast (macOS / Linux) — and aggregates across many repos with a rate-limit-aware scheduler and a `read-notifications --all` merged view. |\n| **Coverage-delta guard** | Opt-in, advisory PR guard that reuses an existing CI coverage artifact (js / python / go / rust), compares it against a stored baseline, and warns when coverage drops past a threshold. Never runs a test suite; never blocks. |\n| **Fleet** | A registry of your local repos (`fleet.json` — add one, or scan a directory) powering bulk governance: `/nyann:fleet` renders a worst-first cross-repo health dashboard (score, trend sparkline, drift counts; live or instant-cached; markdown export for team channels) with a repo-tagged drift roll-up, and `/nyann:fleet-retrofit` walks the fleet fixing drift — and optionally bootstrapping un-governed repos — with a preview and explicit confirmation **per repo**, each individually undoable. |\n\n## Skills & commands\n\n| Command | Purpose |\n|---|---|\n| `/nyann:setup` | First-run onboarding + preferences. Optional `--simulate ` previews what `/nyann:bootstrap` would do without writing. |\n| `/nyann:bootstrap [--profile ]` | Full setup flow. |\n| `/nyann:retrofit [--profile ] [--json]` | Audit drift + offer remediation. |\n| `/nyann:doctor [--profile ] [--json] [--explain]` | Read-only hygiene + docs audit. `--explain` translates drift to plain English. |\n| `/nyann:commit` | Generate + commit a Conventional Commits message. |\n| `/nyann:branch ` | Strategy-compliant branch creation. |\n| `/nyann:pr [--draft] [--auto-merge]` | Open a GitHub PR from current branch. |\n| `/nyann:ship [--client-side] [--merge-strategy s]` | Combined PR + auto-merge (or poll-and-merge). |\n| `/nyann:wait-for-pr-checks [--pr ] [--timeout ]` | Poll a PR's checks until pass / fail / timeout. |\n| `/nyann:release --version ` | Generate changelog, commit, and tag. |\n| `/nyann:hotfix --from --slug ` | Set up hotfix branch topology. |\n| `/nyann:sync` | Pull + rebase with conflict guidance. |\n| `/nyann:undo [--hard]` | Reverse last commit on a feature branch. |\n| `/nyann:undo-bootstrap [--manifest ] [--scope ] [--force] [--dry-run]` | Reverse a bootstrap or retrofit run from its BootRecord manifest. |\n| `/nyann:cleanup-branches [--yes]` | Prune local branches whose work is merged. |\n| `/nyann:gen-ci [--profile ]` | Generate GitHub Actions CI workflow. |\n| `/nyann:gen-templates [--profile ]` | Generate PR + issue templates. |\n| `/nyann:gen-claudemd [--profile ] [--force]` | Regenerate CLAUDE.md without a full bootstrap. |\n| `/nyann:gen-dependency-updater` | Generate profile-aware Dependabot or Renovate config. |\n| `/nyann:gen-devcontainer` | Generate profile-aware `.devcontainer/devcontainer.json` for Codespaces. |\n| `/nyann:explain-diff` | Translate a drift report into plain-English markdown. |\n| `/nyann:gh-protect [--check] [--profile ]` | Audit or apply GitHub protection rules. |\n| `/nyann:route-docs [--routing ]` | Change doc storage routing + regenerate scaffold. |\n| `/nyann:optimize-claudemd [--force]` | Optimize CLAUDE.md based on usage data. |\n| `/nyann:record-decision ` | Create a numbered ADR. |\n| `/nyann:explain-state` | Summarize repo state for handoff. |\n| `/nyann:suggest [--profile <name>]` | Suggest profile updates from repo state. |\n| `/nyann:diff-profile --left <a> --right <b>` | Structured diff between two profiles. |\n| `/nyann:inspect-profile <name>` | Pretty-print a profile. |\n| `/nyann:migrate-profile --to <name>` | Switch profile with diff + re-bootstrap. |\n| `/nyann:learn-profile [--target <path>] [--name <kebab>]` | Extract a reusable profile from an existing repo. |\n| `/nyann:add-team-source --name <n> --url <u>` | Register a team profile repo. |\n| `/nyann:sync-team-profiles [--force]` | Sync team profiles from remote. |\n| `/nyann:check-prereqs [--json]` | Survey hard + soft prereqs. |\n| `/nyann:diagnose [--json]` | Bundle a redacted support snapshot. |\n| `/nyann:settings [<key> <value>]` | Interactive preferences menu (or direct `<key> <value>` shortcut). |\n| `/nyann:watch [--pr <n>] [--stop]` | One-shot CI sentinel poll — queues state-transition notifications. |\n| `/nyann:plan [--unit <path>]` | Preview an IaC change (terraform / opentofu / aws-cdk / pulumi / helm / kubernetes / kustomize / ansible) — read-only add/change/destroy summary, never applies. |\n| `/nyann:apply [--unit <path>] [--apply] [--confirm-destroy]` | Apply an IaC change. Opt-in: previews + confirms first; destructive applies require an explicit confirmation. Writes an audit IacApplyRecord. |\n| `/nyann:fleet [--cached] [--drift] [--markdown]` | Manage the fleet registry (add / scan / prune) and render the cross-repo health dashboard. Read-only. |\n| `/nyann:fleet-retrofit [--bootstrap-missing] [--tag <t>] [--only <csv>]` | Bulk remediation across the fleet — per-repo preview + confirmation, per-repo BootRecord. |\n\nAll 41 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.\n\n## Profiles\n\n### Customizing profiles\n\nNyann picks the right profile automatically. If the starter profiles don't fit, you have two options:\n\n**Learn from an existing repo.** If you already have a well-configured project, nyann can extract a reusable profile from it:\n\n```sh\nbin/learn-profile.sh --target ~/projects/my-good-app --name good-app\n```\n\nThis infers stack, hooks, branching, and conventions from the repo's files and last 50 commits.\n\n**Inspect any profile.** To see what a profile contains before using it:\n\n```sh\nbin/inspect-profile.sh nextjs-prototype\n```\n\n### Profile precedence\n\nWhen multiple profiles exist with the same name, the most specific one wins:\n\n1. `~/.claude/nyann/profiles/<name>.json` user profiles\n2. `~/.claude/nyann/cache/<source>/.../<name>.json` team profiles (synced from a git URL)\n3. `<plugin>/profiles/<name>.json` starter profiles\n\nA namespaced name like `our-team/frontend-baseline` bypasses user shadowing.\n\n### Team profiles\n\nShare conventions across a team by syncing profiles from a git repo:\n\n```sh\n# Register a source — optionally pinned to a tag, SHA, or branch\nbin/add-team-source.sh --name our-team \\\n --url https://github.com/our-org/nyann-profiles.git \\\n --pin-strategy tag --pin-ref v1.0.0\n\n# Sync (shallow clone, respects sync_interval_hours)\nbin/sync-team-profiles.sh [--force]\n\n# When pinned: check what would change before accepting an update\nbin/sync-team-profiles.sh --check-updates --name our-team\nbin/sync-team-profiles.sh --accept-update --name our-team\n```\n\nWhen 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. <!-- drift-ignore: historical version reference -->\n\n### Profile composition (`extends`)\n\nAvoid copy-paste between similar profiles. A child profile can inherit from a parent via `\"extends\"`:\n\n```json\n{\n \"name\": \"my-react-vite\",\n \"extends\": \"react-vite\",\n \"branching\": { \"scopes\": [\"api\", \"web\"] }\n}\n```\n\nDeep 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.\n\n## Project Memory\n\nnyann 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.\n\n```\n CLAUDE.md ──→ docs/ (durable Project Memory)\n │ ──→ memory/ (ephemeral team scratch)\n │\n └─ router-mode (≤ 3 KB), points into both.\n```\n\nFive properties define it:\n\n1. **AI-retrieval-first** — bounded scope per doc, predictable structure, decision rationale captured.\n2. **Size-budgeted** — docs fit in context windows. CLAUDE.md is router-mode (≤3 KB soft cap), not a content dump.\n3. **Drift-aware** — broken links, orphans, and staleness surfaced automatically by `doctor` and CI.\n4. **Storage-agnostic** — local Markdown, Obsidian (MCP), or Notion (MCP). Equal citizens.\n5. **Dual-audience** — high-signal structure works for AI agents AND humans reading reference docs.\n\nSee [`docs/principles/documentation.md`](docs/principles/documentation.md) for the full definition.\n\n### Storage routing\n\nBy default `CLAUDE.md` links to local `docs/` and `memory/`.\n\nWhen Claude Code has an Obsidian or Notion MCP configured, nyann asks where each doc type should live:\n\n```text\nadrs:obsidian, research:local, architecture:local\n```\n\n`memory/` is **always** local — it's the ephemeral team-shared scratch layer, distinct from Project Memory itself.\n\n## Prereqs\n\nRun `/nyann:check-prereqs` (or `bin/check-prereqs.sh`) for a live inventory.\n\n**Hard** (required):\n\n- `git`\n- `jq` (`brew install jq` / `apt install jq`)\n- `bash` 3.2+ (macOS default is fine)\n\n**Soft** (feature-gated; nyann skips with a reason when missing):\n\n| Feature | Needs |\n|---|---|\n| JS/TS hooks | `node` + `npm` / `pnpm` / `yarn` / `bun` |\n| Python hooks | `python3` + `pre-commit` (or `uv` / `uvx`) |\n| Go hooks | `go` |\n| Rust hooks | `cargo` |\n| Swift hooks | `swiftlint`, `swiftformat` |\n| Kotlin hooks | `ktlint`, `detekt` |\n| Shell hooks | `shellcheck`, `shfmt` |\n| Secret scanning | `gitleaks` |\n| Branch protection | `gh` with `gh auth status` green |\n| Schema validation | `uv` (provides `uvx check-jsonschema`) or `check-jsonschema` |\n| Dev loop | `shellcheck`, `bats-core` |\n\nNyann never prompts for credentials. `gh auth status` is a passive read; missing auth surfaces as a skip, not a prompt.\n\n## Repository layout\n\n```\nbin/ # 93 top-level shell scripts + 65 extracted modules + 1 python helper\ncommands/ # 39 Claude Code slash-command registrations\nevals/ # 26 skill-level trigger + output-quality specs\nhooks/ # Claude Code PreToolUse + UserPromptSubmit hooks\nprofiles/ # 32 starter profiles (+ _schema.json)\nschemas/ # 72 JSON Schemas for every exchanged shape\nskills/ # 41 skills (SKILL.md, optionally with references/ and scripts/)\ntemplates/ # gitignore, pre-commit configs (incl. iac), husky, docs, CI, memory, launchd/systemd daemon units\nmonitors/ # Monitor manifest (monitors.json, currently empty)\ntests/ # 2136 bats tests + fixtures\n```\n\n## Recent changes\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for the full release history. Most recent: **v1.14.0** — *Fleet*. nyann's governance verbs go multi-repo: a fleet registry of your local repos powers bulk audit, a cross-repo health dashboard, and bulk remediation with per-repo confirmation. Highlights:\n\n- **Fleet registry** — `~/.claude/nyann/fleet.json` holds your local repos (add one, or `--scan` a directory — preview-first); an entry's optional GitHub slug joins it to the CI watch-list (`--add --watch` mirrors it).\n- **Cross-repo health dashboard** — `/nyann:fleet` runs the per-repo doctor across the fleet: worst-first board with scores, trend sparklines, and drift counts; instant `--cached` snapshots with staleness flags; `--markdown` export; a repo-tagged drift roll-up with plain-English `--explain`.\n- **Bulk remediation** — `/nyann:fleet-retrofit` walks the fleet fixing drift (and, opt-in, bootstrapping un-governed repos) with a preview and explicit confirmation **per repo**; every repo writes its own BootRecord and stays individually undoable.\n- **GitHub issue digest delivery** — sentinel notifications land as comments on one per-repo digest issue (never issue-per-notification), through `gh`'s own auth; messages are hardened against markdown/@mention injection.\n- **Native OS notifications** — one toast per batch via macOS `osascript` / Linux `notify-send`, with injection hardening and headless soft-skips.\n\n---\n\nIssues and feature requests: <https://github.com/thettwe/nyann/issues>.\n",
"bytes": 30267,
"sha": "0de0789060d9addcded19ec23f6e083acc543c8194808ddff772c06aebd8fd21",
"repo_slug": "thettwe/nyann",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/plg_thettwe_nyann_nyann_33b5c463/readme"
}
![\"nyann](\"logo-banner.jpg\")
\n