NapkinStack

An engineering framework for several teams and their agents working in one repository: modules, contracts, guardrails in CI. On the Django or Rails model, one command creates the project, which then receives new versions on demand; no application stack is imposed. Positioning and vocabulary: PRODUCT.md §1.

Status: v0.5.0, published (PyPI): every barrier the framework announces refuses what it claims to — the boundaries read the contracts a module uses, a contract version someone relies on changes only with a proof, the module checks and stale approvals are enforced, a verifier is not an author, and every verdict names the framework that gave it. Proved on the project that exposed the defects: eight probes replayed, each refused or accepted as announced. The contract proof now runs in the base's tree, so a change cannot rewrite what judges it; the diagnosis says whether anything refuses at all; and a record names what reached the default branch outside a pull request — it records, it never refuses. A first pilot project, private, starts from here. Tracking: engine roadmap, move to English, frame, verify, approve, every barrier refuses, docs/governance/workstreams.md.

A project's journey

flowchart LR
    I["Install<br/>uv tool install"]:::cmd --> N["nstack init"]:::cmd
    N --> G["Publish on GitHub<br/>apply the checklist"]:::human
    G --> D["nstack doctor<br/>read-only"]:::cmd
    D --> M["nstack new-module"]:::cmd
    M --> W["Work in pull requests<br/>the team and its agent"]:::human
    W --> U["nstack update<br/>merged branch"]:::cmd
    U --> P["PR reviewed<br/>validated by CI"]:::human
    P -->|"next version"| U

    classDef cmd fill:#1f2937,color:#fff
    classDef human fill:#065f46,color:#fff

Loading

Legend — grey: a NapkinStack command · green: the team's action. Decision: PDR-0001.

The project owns its skeleton and adapts it freely. Every new version reaches it on demand, merged with its adaptations; the conflicts are left to the team.

flowchart LR
    V1["Skeleton v0.1<br/>common base"]:::ref --> F{"Three-way<br/>merge"}
    V2["Skeleton v0.2<br/>NapkinStack fixes"]:::ns --> F
    PR["Project<br/>the team's adaptations"]:::team --> F
    F -->|"different lines"| B["Update branch<br/>fixes + adaptations"]:::ok
    F -->|"same line changed"| X["Conflict marked<br/>commit refused"]:::ko

    classDef ref fill:#374151,color:#fff
    classDef ns fill:#1e3a8a,color:#fff
    classDef team fill:#065f46,color:#fff
    classDef ok fill:#065f46,color:#fff
    classDef ko fill:#7c2d12,color:#fff

Loading

Legend — grey: the version the project came from · blue: the new version · green: the team's work and the accepted result · red: a conflict left to the team.

Install

uv tool install napkinstack --with-executables-from pre-commit   # prerequisites: uv and git
nstack init my-project

To try it without installing anything, or to install it from this repository instead of the registry — always pinned to a release tag:

uvx --from "git+https://github.com/NapkinStack/engineering-os@v0.4.0" nstack init my-project
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.4.0"

Two channels, one published artefact. The registry publishes: the PyPI artefact of a vX.Y.Z tag carries a provenance attestation tying it to the workflow and the commit of this repository. The forge distributes that same tag's source, which is a supported way in and never a published one — a tag can be moved, and carries no attestation — so a run installed that way says where its rules came from, on every line that judges (ADR-0002, PDR-0005). The project itself is unaffected: created from either channel at the same tag, it records the same version and its CI installs from the registry.

Each project then pins its version and changes it through nstack update.

The commands

Command	Role
nstack init <folder>	Creates the project: skeleton, git repository, initial commit, GitHub checklist
nstack doctor	Checks the workstation and the GitHub settings, read-only
nstack new-module <name> <owner> <criticality>	Creates a module, with no imposed stack
nstack check, test, bootstrap [module]; nstack run <module>	Run the commands declared in the module's manifest
nstack discover <idea-file>	Starts a discovery for your agent: the idea kept, its document created
nstack plan	The discovery, the charter and the cycles: formats, one cycle at a time, closures
nstack fitness	Manifests, boundaries between modules, skills, plan, hygiene
nstack pr-scope	One PR = one module, review budget
nstack modules [--changed-since <base>]	The project's modules, or those with a file changed since a base
nstack compat [module] --base <base>	A contract version consumed or stable changes only with the project's merged comparator
nstack e2e [module]	Runs the module's end-to-end scenarios, when declared
nstack pr-check	The test sheet and the cycle, read from the pull request description
nstack skills	Exposes the playbooks as skills for the agent
nstack update	Lays the new version on a branch to review

Prerequisites: uv and git. The guardrails really block on a public GitHub repository, or on a private one under the Team or Pro plan; on a private repository on the Free plan CI informs without blocking (a clarification of PDR-0001).

AI: NapkinStack embeds none. The team's agent (Claude Code, Codex, Copilot…) reads the kernel and the playbooks, runs the commands, and CI accepts or refuses its proposals exactly as it would any other contributor's.

This repository

flowchart LR
    S["skeleton/<br/>the project skeleton"]:::shipped -->|"copier.yml"| P["A team's project"]:::project
    E["src/napkinstack/<br/>the nstack engine"]:::shipped -.->|"pinned version"| P
    A["PRODUCT.md · docs/governance/<br/>platform/ · this repository's CI"]:::internal

    classDef shipped fill:#1e3a8a,color:#fff
    classDef project fill:#065f46,color:#fff
    classDef internal fill:#374151,color:#fff

Loading

Legend — blue: shipped to projects · green: a generated project, which owns its skeleton · grey: developing NapkinStack itself, never copied (PDR-0001 R6). Solid line: generation; dotted: a versioned dependency.

Path	Role
skeleton/	What every project receives: kernel, playbooks, handbook, CI, hooks
copier.yml	The questions asked at creation (a Copier template, ADR-0001)
src/napkinstack/	The engine, the nstack command
platform/	The engine module's envelope: manifest, runbook, tests
PRODUCT.md, docs/governance/	The working context for NapkinStack itself
docs/adr/, docs/pdr/	NapkinStack's decisions

Developing NapkinStack

uv sync                               # prerequisite: uv
uv run pre-commit install
uv run nstack fitness                 # this repository's guardrails
uv run bash platform/tests/run.sh     # the oracle: every guardrail proves it can fail
uv run nstack init /tmp/trial --source . --ref HEAD   # a trial project from the working tree
uv run nstack doctor --root /tmp/trial                # workstation and GitHub settings, read-only

Contributing: CONTRIBUTING.md, after PRODUCT.md.

Licence: MIT.