# Naga > Source-as-spec architecture enforcer. Uses deep AST fingerprinting to ensure AI-generated code perfectly mirrors your internal coding standards. - **Type:** MCP server - **Install:** `agentstack add mcp-enchanter-ai-naga` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [enchanter-ai](https://agentstack.voostack.com/s/enchanter-ai) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [enchanter-ai](https://github.com/enchanter-ai) - **Source:** https://github.com/enchanter-ai/naga ## Install ```sh agentstack add mcp-enchanter-ai-naga ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Naga > **An @enchanter-ai product — algorithm-driven, agent-managed, self-learning.** Observes an existing artifact's structural and stylistic fingerprint and generates new artifacts that match the observed shape, vocabulary, and naming idiom. Source-as-spec replication — orthogonal to from-scratch prompt engineering (Wixie) and codebase mapping (Gorgon). **6 sub-plugins. 5 engines. 3 agents. 5 slash commands. Single PreCompact hook by design (skill-invoked, like Wixie). One install.** > Developer runs `/naga:observe ../vis/packages/core/conduct/discipline.md`. **naga-fingerprinter** extracts the AST/Markdown shape vector via **N1 Zhang-Shasha** (148 nodes), the TF-IDF token signature via **N2 Spärck Jones** (84 distinct stems), and the heading/identifier naming convention via **N3 Levenshtein** (kebab-case, 4-level nesting). Fingerprint hash `a3f2…` persists to `state/patterns/`. Developer then runs `/naga:match ../vis/packages/core/conduct/discipline.md shared/conduct/security.md` to scaffold a new sibling module. **naga-shaper** generates chunk-by-chunk, scoring each via **N4 Salton-Wong-Yang cosine** against the fingerprint; chunks below the per-(`claude-md`, current target) **N5** posterior threshold trigger rewrite. Final fidelity: `0.87 (CI 0.82–0.92, N=232)` — clears the 0.78 threshold. `/compact` fires later — **naga-learning** updates the `(claude-md × claude-md)` posterior to tighten next-time's threshold. > > Time: deterministic fingerprint, bounded generation loop. Developer effort: invoke one slash command. ## TL;DR **In plain English:** "Match the style of this file" is a coin flip. The AI averages your example against the entire internet and ships almost-right. Naga makes it actually match — and proves it with a score. **Technically:** N1 Zhang-Shasha tree edit distance extracts the postorder AST shape signature from the source artifact; N2 Spaerck Jones TF-IDF captures the identifier/comment/structure token fingerprint; both are stored atomically in `state/patterns/.json`. N4 Salton-Wong-Yang cosine fidelity is scored per generated chunk against the fingerprint, and chunks below the per-(pattern-class × target-domain) N5 Gauss posterior threshold are rewritten once then dropped — validated output ships with `(score, ci_low, ci_high, N)` from a bootstrap 95% CI. --- ## Origin **Naga** takes its name from **Twilight Forest** — the verdant serpent boss whose long coiled body shifts to match the hedge-maze terrain of its lair. Scale-pattern, segment-length, and turn-radius all conform to the surrounding shape. That is literally the function of this plugin: observe a source artifact's shape, vocabulary, and naming idiom, and generate new artifacts whose form follows that observed environment, segment by segment, until the fidelity score clears the per-class threshold. The question this plugin answers: *Make something new that looks like this existing thing.* ## Who this is for - Developers propagating idioms across sibling modules — when `../vis/packages/core/conduct/discipline.md` is the gold standard and the next five conduct modules must match its shape, vocabulary, and naming convention exactly. - Teams scaffolding from existing artifacts instead of from a template repo: point Naga at the real source at invocation time; no separate template to maintain or drift. - Anyone who has heard "it's almost right" from a reviewer — that phrase diagnoses single-axis replication (correct structure, alien naming, or vice versa); Naga requires N1 + N2 + N3 to jointly clear the N4 fidelity threshold. Not for: - Prompt engineering from scratch. Naga replicates an observed shape; Wixie engineers a new shape from a technique catalog. "Make me a B2B ticket router prompt" is Wixie. "Make this new conduct module look like `discipline.md`" is Naga. - Continuous background scanning. Naga is skill-invoked by design — pattern replication is a deliberate developer request, not an ambient signal. ## Contents - [How It Works](#how-it-works) - [What Makes Naga Different](#what-makes-naga-different) - [The Full Lifecycle](#the-full-lifecycle) - [Install](#install) - [Quickstart](#quickstart) - [7 Plugins, 3 Agents](#7-plugins-3-agents) - [The Science Behind Naga](#the-science-behind-naga) - [vs Everything Else](#vs-everything-else) - [Agent Conduct (13 Modules)](#agent-conduct-13-modules) - [Architecture](#architecture) - [License](#license) ## How It Works On `/naga:observe `, **naga-observe** parses the source artifact via Source: [docs/assets/pipeline.mmd](docs/assets/pipeline.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md). stdlib `ast`, runs **N1 Zhang-Shasha tree edit distance** against an empty AST to derive the postorder shape signature, runs **N2 Spaerck Jones TF-IDF** over identifier/comment/structure tokens, and persists the resulting fingerprint atomically to `plugins/naga-observe/state/patterns/.json`. On `/naga:match `, **naga-shift** loads the fingerprint, reads the per-(pattern-class x target-domain) p10 threshold from the N5 posterior, and dispatches the **naga-shaper** Sonnet agent to emit chunk-by- chunk. Each chunk is scored via **N4 Salton-Wong-Yang cosine** against the source vector; chunks below threshold are rewritten once, then dropped. On `/naga:validate `, **naga-validate** re-scores cold via N1 + N4 and reports `(score, ci_low, ci_high, N)` with bootstrap 95% CI. On `PreCompact`, **naga-learning** folds new fidelity observations into the per-(pattern-class x target-domain) posterior via **N5 Gauss Accumulation**. This is the single hook binding in Naga. ## What Makes Naga Different ### The source is the spec — no template repo required Cookiecutter, Yeoman, and plopjs hardcode patterns at template-author time. The user maintains a separate template repo that drifts from the actual source; adding a new convention means editing the template, not pointing at a new example. Naga has no template authoring step. `/naga:match source target` — the source path passed at invocation time IS the spec. ### Fingerprint is multi-axis and multi-file by construction GitHub Copilot "complete in similar style" operates on a single-file, single-cursor context. Cross-file structural patterns — naming conventions, error-handling idioms, blank-line conventions — break across modules because Copilot never read the second file. Naga's N1 Zhang-Shasha tree edit distance compares ASTs across the **whole source artifact set**; N2 TF-IDF spans identifier, comment, and structure tokens; N3 Levenshtein pins naming-convention strings. All three must jointly contribute before N4 cosine fidelity clears the threshold. ### Generation operates inside a hard structural constraint, not against a prior Raw "few-shot from these examples" prompting relies on the LLM's prior. The model averages examples against its training distribution and emits something closer to its prior than to the examples; subtle source-specific conventions (a project's preference for `_internal` prefix) are washed out. Naga computes the fingerprint **deterministically** (N1 + N2 + N3) and passes it as a structural constraint to the naga-shaper Sonnet agent. The shaper generates inside that constraint, not against its prior. ### Drift is measured per chunk, not assumed absent Cursor and Aider mid-session refactors start matching the source, encounter a token where their prior is strong, switch to their prior, and never recover. Output is half-source, half-prior. Naga computes the **N4 cosine fidelity score per chunk during generation**; chunks that fall below the per-(pattern-class, target-domain) N5 posterior threshold trigger a rewrite. "Almost right" is rejected, not shipped. ### Honest numbers, or no numbers Every `/naga:validate` row and every `naga.fidelity.measured` event carries `(score, ci_low, ci_high, N)` from a non-parametric bootstrap. Missing N → the row is rejected by the Haiku validator gate, never emitted with an invented confidence band. ## The Full Lifecycle Naga is **skill-invoked by design** — 1 hook (PreCompact persistence) + 5 skill commands. No phase runs continuously in the background. .json fingerprint and target output; single PreCompact hook fires naga-learning to update N5 per-(pattern-class × target-domain) Gauss posterior, refining next-session per-class thresholds" width="100%" style="max-width: 1100px;"> Source: [docs/assets/lifecycle.mmd](docs/assets/lifecycle.mmd) · Regeneration command in [docs/assets/README.md](docs/assets/README.md). | Phase | Event or Skill | Sub-plugin | Engines | Output | |-------|----------------|------------|---------|--------| | Observe | `/naga:observe ` | `naga-observe` | N1 + N2 | `state/patterns/.json`; `naga.pattern.fingerprinted` | | Fingerprint (read-only) | `/naga:fingerprint ` | `naga-fingerprint` | N2 + N3 | N2 + N3 report; no state writes | | Generate | `/naga:match ` | `naga-shift` | N1 + N2 + N3 + N4 + N5 gate | generated artifact; `naga.artifact.generated` | | Validate | `/naga:validate ` | `naga-validate` | N1 + N4 | fidelity score with bootstrap CI; `naga.fidelity.measured` | | Cross-repo | `/naga:match-across ` | `naga-cross-repo` | N1 + N2 + N3 + N4 | generated artifact; Opus escalation on domain mismatch | | Learn | PreCompact | `naga-learning` | N5 | `state/posterior.json`, `state/learnings.jsonl` | The PreCompact hook is the single hook binding in Naga and is intentional — do not add SessionStart, PostToolUse, or UserPromptSubmit bindings. ## Install ``` /plugin marketplace add enchanter-ai/naga /plugin install full@naga ``` Or cherry-pick: `/plugin install naga-fingerprint@naga`. ## Quickstart ```bash git clone https://github.com/enchanter-ai/naga cd naga ./scripts/bootstrap.sh # canonical first command — installs vis sibling ``` Without `./scripts/bootstrap.sh`, conduct imports will silently miss and Claude Code's `@`-loader will fail-soft. Always bootstrap first. ## 7 Plugins, 3 Agents | Plugin | Trigger | Engines | Agent (tier) | |---------------------|------------------------------------|---------------|------------------------------| | naga-observe | /naga:observe | N1, N2 | naga-fingerprinter (Haiku) | | naga-shift | /naga:match | N1, N2, N3, N4| naga-shaper (Sonnet) + naga-orchestrator (Opus, on escalation) | | naga-validate | /naga:validate | N1, N4 | naga-fingerprinter (Haiku) | | naga-cross-repo | /naga:match-across | N1, N2, N3, N4| naga-shaper (Sonnet) + naga-orchestrator (Opus) | | naga-fingerprint | /naga:fingerprint | N2, N3 | naga-fingerprinter (Haiku) | | naga-learning | PreCompact | N5 | (none — pure compute) | | full | meta | — | — | **Why one hook?** Naga is skill-invoked by design like Wixie. Pattern replication is a deliberate request, not a continuous background signal. The single PreCompact hook persists the cross-session posterior; every other sub-plugin fires from a slash command. Do NOT add SessionStart, PostToolUse, or UserPromptSubmit bindings — the 1-hook count is intentional. ## What You Get Per Match Every `/naga:observe` extracts a fingerprint and persists it; every `/naga:match` generates a target artifact under per-chunk N4 fidelity gating; every `PreCompact` folds the per-(pattern-class × target-domain) fidelity envelope into the cross-session posterior. All writes go through the atomic `shared/scripts/state_io.atomic_write_json` helper. ``` plugins/naga-observe/state/patterns/ └── .json N1 shape vector + N2 TF-IDF terms + N3 naming convention plugins/naga-shift/state/ └── last-match.json most recent /naga:match (source, target, fidelity, ci, N) plugins/naga-validate/state/ └── last-validation.json most recent /naga:validate output plugins/naga-fingerprint/state/ └── last-report.json most recent /naga:fingerprint output plugins/naga-learning/state/ ├── posteriors.json per-(pattern-class × target-domain) fidelity posterior (N5 EMA) └── learnings.jsonl per-match append-only fidelity summary (backtesting source) ``` Events published on the `naga.*` namespace (Phase-1 file-tail fallback via shared `publish.py`): - `naga.pattern.fingerprinted` — `{source_path, fingerprint_hash, n1_signature, n2_terms, captured_at}` - `naga.artifact.generated` — `{source_path, target_path, fidelity_score, ci_low, ci_high, N}` - `naga.fidelity.measured` — `{generated_path, source_pattern, score, ci_low, ci_high, N}` - `naga.pattern.refreshed` — `{pattern_class, n_observations, posterior}` Optional subscriptions (Phase-2 enrichment): `gorgon.snapshot.captured` (target-domain hint), `wixie.prompt.crafted` (propagate Wixie-engineered seeds across siblings). ## Roadmap Tracked in [docs/ROADMAP.md](docs/ROADMAP.md) and the shared [ecosystem map](https://github.com/enchanter-ai/wixie/blob/main/docs/ecosystem.md). For upcoming work specific to Naga, see issues tagged [roadmap](https://github.com/enchanter-ai/naga/labels/roadmap). ## The Science Behind Naga | ID | Name | Reference | |----|---------------------------------------|----------------------------------------------------------------------------------------| | N1 | Zhang-Shasha Tree Edit Distance | Zhang K. and Shasha D. (1989), SIAM Journal on Computing 18(6):1245-1262 | | N2 | Spaerck Jones TF-IDF | Spaerck Jones K. (1972), Journal of Documentation 28(1):11-21 | | N3 | Levenshtein Edit Distance | Levenshtein V.I. (1966), Soviet Physics Doklady 10(8):707-710 | | N4 | Salton-Wong-Yang Cosine Similarity | Salton G., Wong A., Yang C.S. (1975), Communications of the ACM 18(11):613-620 | | N5 | Gauss Accumulation: Fidelity Drift | Gauss C.F. (1809), "Theoria motus corporum coelestium" (least-squares foundation) | Full derivations: [`docs/science/README.md`](docs/science/README.md). ## vs Everything Else Honest comparison against adjacent tools. | Feature | Naga | Cookiecutter | LangChain templates | Copilot "complete in style" | Wixie (sibling) | |----------------------------------------------|:----:|:------------:|:-------------------:|:---------------------------:|:---------------:| | Reads source at invocation (no template repo)| Yes | No | No | Yes | No | | Multi-axis fingerprint (N1+N2+N3 -> N4) | Yes | No | No | No | No | | Per-(class, domain) p10 threshold | Yes | No | No | No | No | | Honest-numbers (score, CI, N) per artifact | Yes | No | No | No | Yes | | Engineers prompts from a technique catalog | No | No | No | No | Yes | | Dependencies | stdlib| Python+jinja| Python+vec DB | binary | bash+jq | Naga answers a replication question that adjacent tools either don't ask or collapse into one axis. ## Agent Conduct (13 Modules) Every skill inherits a reusable behavioral contract from [shared/conduct/](shared/vis/conduct/) — loaded once into [CLAUDE.md](CLAUDE.md), applied across all plugins. | Module | What it governs … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [enchanter-ai](https://github.com/enchanter-ai) - **Source:** [enchanter-ai/naga](https://github.com/enchanter-ai/naga) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-enchanter-ai-naga - Seller: https://agentstack.voostack.com/s/enchanter-ai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.