Declare the system once. Humans review it. Agents operate it.
Putnami is a workspace model, framework primitives for Go and TypeScript, and a layer of wire protocols underneath them. Your build, your CI, your infrastructure and your agents all read the same contracts — from your laptop to production.
Your system is real. Your description of it isn’t.
The system only exists at runtime
Config in five dialects, infrastructure in another repo, CI in provider YAML. Nothing in git states what the system is — only fragments of how to rebuild it, if you already know.Every boundary is a convention
The CLI knows what the framework emits because the same person wrote both. Add a language, a second consumer, or an agent, and the convention lives only in someone’s head.Drift isn’t unfixed. It’s invisible.
Local, CI and production diverge quietly, because nothing in the system compares them. You find out at the worst possible moment.Agents can edit. They can’t operate.
An agent can write code against your repo. Operating your system — knowing the blast radius, reading the state, undoing a mistake — needs a contract, and you don’t have one to hand it.One declaration. Everything downstream reads it.
You write intent next to the code it describes. Putnami derives the rest, deterministically, and publishes it as a contract anyone can parse — including the tools you didn’t write.
| You declare | Putnami derives | Who reads it |
|---|---|---|
| putnami.json | the workspace graph | the CLI, every extension, every task |
| an HTTP handler | a route inventory | your edge, as a generated default-deny allowlist |
| an infra need, next to the code | one merged manifest, with provenance | your deploy target |
| putnami.ci.json | a validated job graph | any execution plane — it reads the document, it never widens it |
| a migration, a repository | a bundle digest | Go and TypeScript adapters, the test provisioner |
| — nothing. it’s derived | the agent context | your agent, over MCP |
Your branch is already an environment. Git carries the intent — what changed, by whom, against what — and every document above is derived from it, so one workspace structure, one set of commands and one set of contracts hold from your laptop through CI to whatever runs it. Managed per-branch previews and deploys are where this is going; nothing in the chain requires an account.
Every row above is a wire protocol: a published schema, a corpus of valid and invalid fixtures, and a strict parser in each language that implements it. Read the protocols →
An agent doesn’t need to be taught your repository.
It reads the same contracts your build reads.
putnami context pack
A deterministic per-project orientation document: identity and dependency graph, composition roots, capability and contract references, representative source ranges, tests, docs, provenance. Aggregated by reference — paths, digests and ranges, never file contents — behind a fail-closed publish-safety gate. Served read-only over MCP.--impacted
The blast radius of a change, before anything acts on it. An agent that knows what it is about to affect is an agent you can let run.--output=json · jsonl
Exit codes, output modes and machine documents are a versioned contract, not an implementation detail that moves under a parser. The same corpus validates the Go and the TypeScript CLI.putnami doctor
Production-readiness findings under a deployment profile, a frozen check-code taxonomy, and a remediation baked into every check. “What’s wrong and what do I do about it” is data, not prose.One JSONL event stream per job, so the agent watching a build and the human reading the log are parsing the same lines.
One package per boundary. No shared assumptions.
The frameworks, the tooling and the platform don’t integrate through shared code. They integrate through protocols: a published schema, a corpus of valid and invalid fixtures, a strict parser in every language that implements it, and at least one real consumer.
A protocol without consumers is a spec, not a contract.
The repository publishes a conformance matrix — who implements or consumes each contract, and how it’s verified. It has three states, and the middle one is published on purpose: tested, aligned by hand (drift possible), and not a consumer. A matrix that only showed green would be marketing.
Constraints, not aspirations. Violations are bugs.
Observable by construction. Every runtime emits structured signals by default. Local, preview and production expose the same shape.
Performance is a constraint. Defaults must survive production load. Regressions are detectable in CI. Abstractions expose their cost.
Deterministic and reviewable. Git defines system intent. Deployments are pure functions of versioned state. Drift is detectable.
Security is foundational. Secure defaults are enforced. The system fails closed. Unsafe paths require explicit acknowledgment.
Data ownership is non-negotiable. Data lives in stores you control. Schemas are versioned, portable, and part of the contract.
Automation is a first-class user. The CLI is the primary interface. Output is deterministic and machine-readable, so humans and machines follow the same rules.
Three surfaces. One declaration.
Putnami
Structural precision. The workspace model, the framework primitives, the CLI, and the protocol layer underneath them. Complete locally, no account required. FSL-1.1-MIT.Putnami Cloud
Operational depth on the same documents: release provenance, runtime correlation, incident context, rollout protection. It reads your route inventory to build an allowlist, your infra manifest to provision, your CI document to execute. It gets no private dialect.Putnami Intelligence
What ships today: agent orientation over MCP, a versioned workspace index, and spec-driven development — features, specs and architecture recorded next to the code. The review-and-audit loop, with freshness and receipts on every finding, is where this is going. It stands alone: useful with neither Putnami frameworks nor Putnami Cloud.Adopting putnami.dev sharpens what Intelligence knows about your structure. Adopting Cloud deepens what it knows about your operations. Neither is a prerequisite — and Cloud integrates through the same published contracts as any third-party adapter. Its advantage is zero-configuration correlation, not a private backchannel.
Tooling first. Language depth when you need it.
Start with a workspace.
Everything above runs on your machine, without an account. The platform is there when operating it stops being your job.