Naga

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

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. For upcoming work specific to Naga, see issues tagged 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
• Source: enchanter-ai/naga
• License: MIT

Install and usage instructions live in the source repository linked above.