nornkit

An engineering toolkit for Claude Code and Codex.

nornkit packages one set of engineering practices — product definition, architecture decisions, implementation, review, and documentation — as a single plugin that installs into both hosts.

Status: scaffold. Structure, manifests, rules, and tooling are in place. rules/ ships common, TypeScript, and Python rule sets. No skills, agents, or templates have been authored yet.

Rules or skills?

nornkit splits standards from procedures, because Claude Code loads them very differently.

	rules/	skills/
Contains	Standards — naming, error handling, test structure, security defaults	Procedures — a sequence the agent runs
Answers	What does good look like?	What do I do next?
Loads	Always (common/), or when a matching file is read (path-scoped)	Name and description always; body on invocation
Scales to	Many, at no standing cost	A handful before descriptions start colliding

Language coding styles are rules. A TypeScript naming convention is not a procedure — it is a standard the agent holds while writing TypeScript. It lives in rules/typescript/coding-style.md, scoped with paths frontmatter so it enters context only when a .ts file is in play.

Skills are the scarce resource: every skill's description sits in the session prompt permanently and competes for selection against every other installed plugin. Rules cost nothing until they apply. When something could be either, make it a rule.

Repository layout

The repository root is the plugin root — manifest paths must start with ./ and resolve inside it, so root-level skills/ requires exactly this layout.

.
├── .claude-plugin/
│   ├── plugin.json                 # Claude manifest
│   └── marketplace.json            # Claude marketplace (source: "./")
├── .codex-plugin/plugin.json       # Codex manifest
├── .agents/plugins/marketplace.json # Codex marketplace
├── skills/                         # Shared skills (Claude + Codex)
├── rules/                          # Coding standards
│   ├── common/                     #   always-on, language-agnostic
│   ├── typescript/                 #   path-scoped to **/*.ts
│   └── python/                     #   path-scoped to **/*.py
├── templates/                      # Baselines copied into projects
├── agents/                         # Claude role definitions
├── hooks/hooks.json                # Claude session hook
├── bin/                            # Verification and maintenance scripts
├── .mcp.json                       # MCP servers (none yet)
├── .lsp.json                       # Language servers (none yet)
├── AGENTS.md                       # Provider-neutral contributor guide
├── CLAUDE.md                       # Claude-specific notes
├── RULES.md                        # Format contract for this repository
└── skills-lock.json                # Vendored third-party skills

Provider-specific integration belongs in that provider's manifest or directory. Project-specific configuration belongs in the project, not in this plugin.

Two hosts, one package

Host	Role
Claude Code	Primary orchestration experience. Adds named agents, the session hook, and LSP integration on top of the shared skills and rules.
Codex	Runs the same provider-neutral skills and rules. Claude-only manifests, hooks, and agents are ignored.
Claude + Codex	Claude may delegate an independent review or second opinion to Codex, grounded in the same spec, diff, and verification output.

Installation

Claude Code

claude plugin marketplace add nornverk/nornkit
claude plugin install nornkit@nornverk --scope user

Use --scope project for a repository-only installation.

Codex

codex plugin marketplace add nornverk/nornkit
codex plugin add nornkit@nornverk

Rules, per project

Installing the plugin does not install its rules. rules is not a plugin manifest field, and Claude Code reads rules only from .claude/rules/ and ~/.claude/rules/. Run this from a project root to copy them in:

nornkit-rules typescript python

That writes .claude/rules/nornkit/common/ plus one directory per language. Commit the result so the whole team works to the same standards. Run nornkit-rules with no arguments to list the available sets, and --force to overwrite an existing install.

Local development

pnpm install
pnpm validate
claude --plugin-dir .

For a local Codex installation, add this repository's absolute path as the marketplace source, then install nornkit@nornverk.

Scripts

Command	Purpose
pnpm validate	Validate manifests, skill frontmatter and descriptions, the rules contract, and shell syntax
pnpm rules	Install rule sets into a project (pnpm rules typescript)
pnpm skills:update	Refresh vendored skills, then sync them into skills/
pnpm skills:sync	Sync already-staged skills into skills/

bin/nornkit-verify is the shared quality gate for projects built with nornkit: it runs whichever of check, lint, test, and build scripts the target project defines.

Contributing

RULES.md is the format contract. AGENTS.md covers editing rules and the release checklist. rules/README.md explains the rule loading model and how to add a language. Run pnpm validate before submitting a change.

nornkit is licensed under the Apache License 2.0.