@nimiplatform/nimi-coding

English · 简体中文

A vendor-neutral, AI-native methodology toolkit for governing high-risk AI-assisted software work. Bootstraps a project-local .nimi/** truth surface, ships the nimicoding CLI, and turns "AI plausibly finished this" into "the four closure dimensions are evidenced."

Reader documentation: https://docs.nimi.ai/nimicoding npm package: @nimiplatform/nimi-coding

Why This Exists

AI-assisted implementation routinely produces output that compiles, passes existing tests, looks plausible to a reviewer, and is still wrong about authority, scope, semantics, or product meaning. These are not bugs in the conventional sense — they are closure failures: the work was claimed done in a state where the closure conditions had not actually held.

A short, non-exhaustive list of failure shapes Nimi Coding is designed to catch:

• Stale-doc anchoring — the assistant follows a document that looked authoritative but had drifted from the active spec.
• Implicit scope expansion — the assistant edits an adjacent surface "while it's in the file"; ownership silently shifts.
• Plausible synthesis — when authoritative source is missing, the assistant invents a coherent answer indistinguishable from a real one.
• Old-route preservation — a new route is added alongside the old one as "safe migration"; the old route was supposed to be deleted.
• Build-pass closure — work declared done because tests run, even though consumer-facing behavior is wrong.
• Pseudo-success — a typed contract failure is hidden behind a fallback that returns "something" instead of failing closed.

Better prompts and better tests do not address this. The loop reviewing the AI's output is the same loop that produced it. Nimi Coding introduces structural separation instead.

What Nimi Coding Is (And Is Not)

Nimi Coding is not another AI coding assistant. It does not write code, dispatch to a provider, or run an agent loop.

It is the standalone host-agnostic boundary package that sits as a governance layer under whichever AI host you use (Claude, Codex, Gemini, OMX, or your own). It ships:

• a package-owned methodology under methodology/**
• typed contracts under contracts/**
• bootstrap + host profile config under config/**
• a bootstrap spec seed under spec/**
• the nimicoding CLI for bootstrap, validation, skill handoff, local closeout, topic lifecycle, sweep audit, sweep design, and high-risk execution gates
• host adapter profile overlays for external AI hosts

It deliberately does not ship:

• a packet-bound run kernel
• provider-backed AI execution
• a scheduler
• notification infrastructure
• an automation backend
• self-hosted methodology execution

Runtime ownership stays with an external AI host. The methodology and contracts stay portable. You can change AI hosts tomorrow without changing the methodology contract.

When a host project runs nimicoding start, the package-owned sources are projected into that project's .nimi/{config,contracts,methodology,spec}/** surface. The adopted project then owns its .nimi/spec/** product authority. The package does not make a host read package source paths directly — the adopted project always reads its own projected .nimi/**.

The Mental Model

Four moves separate Nimi Coding from a checklist:

See Four Closures and The Paradigm for the full framework.

Who This Is For

If you have ever watched an AI-assisted change look complete to every available signal — type checker green, tests green, reviewer approved — and turn out to be wrong about authority, scope, or product meaning, this package is for you.

Requirements

A version-controlled project is recommended — start creates files.

Install

In the repository that should receive the .nimi/** governance layer:

npm install --save-dev @nimiplatform/nimi-coding
# or
pnpm add -D @nimiplatform/nimi-coding

Check the CLI:

npx nimicoding --version
npx nimicoding --help

5-Minute Minimal Path

Most projects should start small. The first successful path is:

# 1. Bootstrap .nimi/** in your project root
npx nimicoding start

# 2. Check the bootstrap is healthy
npx nimicoding doctor --json

# 3. Hand off canonical spec reconstruction to your AI host
npx nimicoding handoff --skill spec_reconstruction --json

# 4. After the host consumes that payload and materializes .nimi/spec/**,
#    validate the canonical tree
npx nimicoding validate-spec-tree .nimi/spec
npx nimicoding validate-spec-audit

After this, you have a project-local .nimi/** truth surface, a typed reconstruction of project authority into .nimi/spec/**, and mechanical validators you can re-run on every change.

handoff exports an authoritative task payload. It does not call an AI provider or run the reconstruction itself; the external host must consume the payload, write or return the expected artifacts, and then the local validators check the result.

You do not need to create topics, freeze packets, or run high-risk gates for ordinary low-risk changes. Those tools exist for authority-bearing, cross-module, multi-wave, or audit-sensitive work.

To remove only package-managed bootstrap material from a test project (preserves .nimi/spec/**, .nimi/local/**, .nimi/cache/**, and locally modified bootstrap files):

npx nimicoding clear --yes

When You Need More: Topics, Waves, Packets

For authority-bearing, high-risk, or cross-module work, escalate to the topic lifecycle. A topic groups one strategic change; waves split the topic into bounded units of work; each wave freezes a packet before the worker begins.

nimicoding topic create <slug> --justification <text>
nimicoding topic wave add <topic-id> <wave-id> <slug> \
  --goal <text> --owner-domain <domain>
nimicoding topic packet freeze <topic-id> --from <draft-path>
nimicoding handoff --skill high_risk_execution --json
nimicoding ingest-high-risk-execution --from result.json
nimicoding review-high-risk-execution --from ingest.json
nimicoding decide-high-risk-execution --from review.json \
  --acceptance accept.md --verified-at <iso8601>

Each step is bounded by typed validation. Skipping a step or smuggling fields through means the CLI refuses (fail closed, no exceptions).

The Four Declared Skills

External AI hosts implement these skills; the handoff CLI emits a machine-readable payload for each:

See Skills for contract detail.

CLI Surface

Common commands, grouped by entry scenario:

# Bootstrap
nimicoding start
nimicoding sync --check
nimicoding doctor --json
nimicoding clear --yes

# Skill handoff and local closeout
nimicoding handoff --skill <id> --json
nimicoding closeout --from result.json --write-local

# Spec audit
nimicoding validate-spec-tree .nimi/spec
nimicoding validate-spec-audit
nimicoding blueprint-audit

# Topic lifecycle
nimicoding topic create <slug> --justification <text>
nimicoding topic wave add|select|admit ...
nimicoding topic packet freeze ...
nimicoding topic worker dispatch ...
nimicoding topic result record ...
nimicoding topic closeout ...
nimicoding topic true-close-audit ...
nimicoding topic run-next-step <topic-id> --json

# Sweep audit / sweep design
nimicoding sweep audit plan --root <dir> --json
nimicoding sweep audit chunk ...
nimicoding sweep design intake|packet-build|result-ingest|finalize ...

# High-risk execution gates
nimicoding admit-high-risk-decision --from <json> --admitted-at <iso8601>
nimicoding ingest-high-risk-execution --from <json>
nimicoding review-high-risk-execution --from <json>
nimicoding decide-high-risk-execution --from <json> \
  --acceptance <path> --verified-at <iso8601>

# Mechanical artifact validators
nimicoding validate-execution-packet <path>
nimicoding validate-orchestration-state <path>
nimicoding validate-prompt <path>
nimicoding validate-worker-output <path>
nimicoding validate-acceptance <path>

Conceptual CLI overview: https://docs.nimi.ai/nimicoding/cli Field-level reference: https://docs.nimi.ai/nimicoding/reference/cli-commands

How Does This Compare To …

Nimi Coding sits underneath the AI host you already use. It is the machinery that lets the work AI did graduate from "looks done" to "closed across four dimensions, with evidence."

Repository Map

Adopted projects use .nimi/** for the projected layer. This repository itself keeps the package-owned source directly under config/**, contracts/**, methodology/**, and spec/**.

Development

pnpm install
pnpm test           # runs the node:test suite
pnpm check:pack     # npm pack --dry-run
pnpm check:ci       # test + pack + CLI help/version smoke

Local CLI smoke:

node ./bin/nimicoding.mjs --version
node ./bin/nimicoding.mjs --help

Before opening a pull request, read CONTRIBUTING.md. The short version: keep changes scoped, preserve the host-agnostic boundary, do not add runtime ownership unless the methodology contract is explicitly redesigned, and run the relevant tests before claiming the work is done.

Publishing

Releases are tag-driven through GitHub Actions. A vX.Y.Z tag publishes the matching package.json version after tests, dry-run packing, and CLI smoke checks pass. The workflow also supports a manual dry-run release gate.

The package publishes with npm provenance enabled.

Security

Do not disclose vulnerabilities in public GitHub issues. Use a private channel:

• GitHub private security advisory for nimiplatform/nimi-coding
• security@nimi.ai

See SECURITY.md for the supported reporting path.

Documentation

Full reader documentation lives at https://docs.nimi.ai/nimicoding, including:

• The Paradigm
• Four Closures
• False Closure Typology
• Forbidden Shortcuts
• Role Separation
• Topic Lifecycle
• The Package
• CLI Surface
• Installation
• Adoption Path
• Comparison
• Walkthrough

License

MIT. See LICENSE.