Skip to main content

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.28.0, published on PyPI. What each version changes, engine and project apart: CHANGELOG.md. What is open: 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 its forge<br/>on GitHub: nstack settings --apply"]:::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

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.

Five files are never merged again, because their content is the product's: the front page README.md, the security policy, the module map and the two decision indexes. nstack init writes them as a form — headings and the place of a diagram — and each is asked for when its moment comes, never before: the sentence at the discovery's go, the page at the charter's acceptance, the map at a module's first code. The foundation's manual sits one click away, in .nstack/handbook/INSTALL.md (PDR-0010).

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

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.28.0" nstack init my-project
uv tool install "napkinstack @ git+https://github.com/NapkinStack/engineering-os@v0.28.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, the next steps for its forge (--forge, GitHub by default)
nstack doctor Checks the workstation and, on GitHub, its settings, read-only; off GitHub says what it cannot verify; names a newer published version
nstack settings [--apply] Prints the calls that would bring the GitHub settings to the checklist; with --apply, makes them under the person's own credential, then reads the result back — never an agent's, never in CI
nstack new-module <name> <owner> <criticality> Creates a module, with no imposed stack
nstack new-contract <name> Creates a contract and, the first time, the module that holds them all
nstack check, test, bootstrap, clean [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 Opens with what needs a person, or says nothing does; then the discovery, the charter and the cycles: formats, one cycle at a time, closures, and the decisions due at a closure; the project across its cycles, and who holds what
nstack claim <deliverable> [--take-over]; nstack unclaim <deliverable> Takes a ready deliverable for a session before its first change, on a branch of its own the shared remote refuses to a second taker; gives it back (ADR-0007)
nstack deliver <deliverable> --held [N=]#PR Records that a merged deliverable is delivered, criterion by criterion, with no pull request; refused with no merge of it; --write-states writes the states at a closure (PDR-0022)
nstack agent add <name>; nstack agent run <name> -- <command>; nstack agent status Gives an agent its own GitHub App and a clone that commits as it and runs the project's hooks — add is a person's, two clicks at the forge; starts the agent there without the person's credentials, says what it keeps of them, gives Claude Code settings of its own; status tells an agent who it is (ADR-0004)
nstack board [--dry-run] Shows the cycles and their deliverables on the forge, one way: milestones and issues (ADR-0008)
nstack fitness Manifests, boundaries between modules, skills, plan, hygiene — each also runs alone: manifests, boundaries, 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 — one run at a time on a machine
nstack release [module] [args] Makes each module's artefacts into dist/<module>/, each after what it assembles; what follows a named module goes to its command
nstack pr-check The test sheet, the cycle and the attested checks, read from the pull request description
nstack landed --span <before>..<after> What reached this branch outside a pull request, recorded
nstack attest --base <base> --body-file <description> The CI's checks run here, on a clean head; the run recorded on the commit, in git (refs/notes/nstack/checks), and shown on GitHub as nstack / local checks; attesting the same commit again keeps the module checks it passed (--again runs them)
nstack skills Exposes the playbooks as skills for the agent
nstack update [--session <id>] [--forge <name>] Lays the new version on a branch to review; an agent's session as the commit's Agent-Session trailer; --forge moves the project to another forge, its own lines kept

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, and doctor says the repository unguarded (PDR-0006). Off GitHub (GitLab, Forgejo, Gitea, another forge or none), the checks are attested on the workstation and every command says what it cannot verify (PDR-0018).

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

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 and its manual, CI, hooks — and five forms the project writes
copier.yml The questions asked at creation, and the files no update touches again (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.

Metadata

Release files for napkinstack 0.28.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for napkinstack 0.28.0
File Size Uploaded Provenance Actions
napkinstack-0.28.0.tar.gz 157.0 kB With provenance Details for napkinstack-0.28.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for napkinstack 0.28.0
File Interpreter ABI Platform Actions
napkinstack-0.28.0-py3-none-any.whl Python 3 none any Details for napkinstack-0.28.0-py3-none-any.whl

Total release size: 335.9 kB

Release files / napkinstack-0.28.0.tar.gz

Download URL napkinstack-0.28.0.tar.gz
Size 157.0 kB
Tags Source
SHA-256 checksum
How to use checksums
846b3f427cfbf73bebd3cdef914a22491e1bdae1eeea639cae123c6f4e12a21c
BLAKE2b-256 checksum
How to use checksums
bab2781b1c6527ce97b8e461f90717c9b4666c5c67389df3a8fb6b5655aae2a2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / napkinstack-0.28.0-py3-none-any.whl

Download URL napkinstack-0.28.0-py3-none-any.whl
Size 178.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ceba538fab56637117e0f7cfe58bdf711090592e9683fa75a9158377f0af2479
BLAKE2b-256 checksum
How to use checksums
d1805436cbfa73fa250cfd91d69f56a95c9ef8f7a96eddad4ff2c6c5b2770fdd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for napkinstack 0.28.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for napkinstack-0.28.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.28.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page