Agents

There are two different things an agent can do with your codebase.

It can write code in it — read some files, follow the conventions it finds, open a diff. Most tooling supports this, because it only requires the repository to be readable.

It can operate it — know what a change affects before making it, run the right jobs, read the result as data, tell you what is not production-ready and why. That requires the system to state what it is, in a form something other than its author can parse.

Putnami is built for the second one. This page is the contract that makes it possible. For the practical setup — assistant context files, prompt patterns — see Develop with AI assistants.


Orientation: read the system, not the files

When you run putnami init, the workspace gets one short Putnami block in AGENTS.md (which a new CLAUDE.md imports). That is the whole of what Putnami writes. Your own durable rules go in .agents/constraints.md, a file you create yourself. The block tells an assistant to read it when it exists, and Putnami never writes it. Agent skills come only when you run putnami extensions install @putnami/contributor (see Develop with AI assistants). Adding an extension later? putnami context generate refreshes the block and the skills.

That teaches an assistant your conventions. Two commands teach it your system.

putnami context map — where things are

putnami context map                         # print the map as Markdown
putnami context map --output=json           # print the map document as data
putnami context map --projects <project-id> # print only the projects you name

The workspace orientation map, rebuilt from committed artifacts — project manifests, schema/openapi.json, schema/config.jsonschema.json, READMEs, and the docs tree. It answers "which project owns X", "what depends on Y", "where are the APIs, the config keys, the docs" without shell exploration.

It is byte-deterministic on an unchanged tree, and nothing writes it: neither the command nor a build stores a copy. putnami context map prints it, rebuilt on every call. --projects and --impacted narrow the printed projects.

putnami context pack — how one project is composed

putnami context pack --project <project-id>
putnami context pack --output=json    # every project's document, as data

It prints one deterministic agent-context document per project and writes no file:

  • identity and graph — id, name, path, type, tags, languages, and the ids of dependencies and dependents;
  • composition roots — the application main, the describe entrypoint, and other roots, each with a path and a provenance tag;
  • capabilities, contracts, infra, migrations — references carrying a path and a sha256: digest, pointing at the committed artifacts;
  • representative sources — ordered ranges (path, startLine, endLine, a reason, a token estimate). Ranges only;
  • tests — referenced conformance packs and fixture digests — or, when there are none, a machine-readable reason for their absence;
  • docs — adjacent documentation, each marked checked or unchecked;
  • config — a config-schema reference and refs-only hints about the operational surface;
  • provenance — the workspace revision, the generator, and the aggregation method.

Three properties are worth stating plainly, because they are what make the document safe to hand to a tool you don't control.

It aggregates by reference. Paths, digests, and line ranges. Never file content. The types have no slot for content, and the safety gate rejects any string long enough to look like it anyway.

It is never stored. Every read builds it again from the working tree, so no copy can go stale. It embeds the workspace revision and content digests, so a stored copy would churn on every commit. Determinism is pinned byte-for-byte by tests at a fixed tree.

Publication fails closed. Before a document can leave the workspace for an authorized index, a redaction gate runs and reports as hard errors: a reference to a sensitive path that is not flagged sensitive, anything resembling embedded content, any path that is absolute or escapes the workspace, and any duplicated reference. An empty document fails the gate, so it can never pass vacuously.

You can adjust the document, narrowly. <project>/schema/agent-context.overrides.json adds or removes representative-source and doc entries and force-flags paths as sensitive. It cannot override identity, capabilities, or provenance — those are framework-owned facts, and an author who could rewrite them could make the document lie.


Through the CLI

An agent reaches the workspace with the commands a person runs. Add --output=jsonl to a query for structured output.

Commands What they answer
Orient putnami projects list · putnami projects describe · putnami context pack · putnami context map What is in this workspace, how is this project composed, where should I read first
Blast radius putnami projects owner · putnami projects deps · putnami projects why · putnami <verb> --impacted --dry-run Which project owns this path, what depends on what, what does my change affect, and by what path
Intent putnami features · putnami specs (from @putnami/sdd) What was this built for, what were the non-goals, what did the team agree to
Execute putnami lint · putnami test · putnami build Run the jobs, then read every failure as file:line:col with severity and code

Putnami serves no protocol server and writes no agent-host registration. An earlier Putnami wrote a putnami entry to .mcp.json; putnami install and putnami upgrade remove it when it is the entry Putnami wrote.

Graph answers read the recorded workspace view

Project identity and dependency edges belong to the language extensions. The CLI keeps a local copy in .putnami/workspace-index.json. When the copy is missing, the graph commands say so and point at putnami projects sync, because an empty graph would read as "there is nothing here" rather than "nobody has told me yet".

A preview before a run

--dry-run returns the selected dependency plan without starting a subprocess. Pair it with --impacted to see what a change would run before it runs.


Blast radius before action

putnami lint,test,build --impacted

--impacted resolves the projects affected by the current changes against a baseline, transitively through the dependency graph. The baseline is resolved in a fixed order — workspace config, nearest configured epic branch, trunk, local main or master, then the upstream tracking ref — and never the current branch itself, so it cannot quietly resolve to "nothing changed".

Run it once, before declaring the change complete. It also runs every project that depends on the change, so while iterating, select only the projects you changed with --projects <a>,<b>. The generated AGENTS.md gives agents the same rule.

When an agent needs to justify the result rather than trust it, putnami projects why <from> <to> prints the shortest path from the changed project to the impacted one over the same edges, with each edge's kind and the task scope, and putnami projects owner <path> maps a file path back to the project that owns it using the same logic.

Deliver in gated phases, not in small pull requests

An --impacted run ends with the size of the change, split into authored code, tests, docs and generated files. The size is information: no line count fails the run. A change that updates its tests and docs is larger by design, and agent work, such as an epic, is often large and legitimate.

What keeps a large change safe is how it lands:

  1. One pull request carries one intent.
  2. Work that spans several projects goes on an integration branch listed in the workspace epicBranches, one phase per commit.
  3. Every phase passes the gate before the next one starts.
  4. The branch merges as one unit that one revert undoes.

When the authored code of a change spans projects that no dependency relates, and the branch is not on an epic branch, the run prints a mixed-intent warning. The warning never changes the exit code. Both are also recorded as a selection:change-shape session event. The managed build workflow follows the same rule and preserves an allocated workspace branch. Delivery units follow observable value, compatibility, release and rollback boundaries. A project, worker or task count does not establish a separate unit or proposal. Intermediate units retain their parent's pending requirements and use non-closing references.


A surface that parses the same way every time

putnami build --output=json
putnami test  --output=jsonl

Exit codes, output modes, the reserved global-flag registry, and the machine documents are the cli protocol — versioned, and validated by one conformance corpus executed from both the Go and the TypeScript implementation. An agent that learned the shape does not have to relearn it because a release changed a log line.

Every job also emits one JSONL event stream — logs, progress, phases, diagnostics, metrics, artifacts, results — so the agent watching a build and the human reading the log are parsing the same lines.


Verifying the work

Generating a change is the easy half. The useful half is telling whether it is safe.

putnami doctor --profile production

doctor is a read-only production-readiness preflight. It derives findings from committed manifests — incomplete capabilities, missing required config, invalid committed schemas, config shadowing — and grades them by deployment profile. Under --profile production a high or critical finding exits 2; dev and test stay advisory. Config values are never read or emitted, so running it in a pipeline leaks nothing.

Each check carries a remediation baked into the check itself, and the code taxonomy is frozen. Findings you have consciously accepted go into a committed doctor.waivers.json — a waiver is a reviewable decision in git, not a flag someone remembered to pass.

Alongside it: conformance packs test declared capabilities against shared fixtures, and the orientation document is rebuilt on every read, so it cannot go stale behind the code.


The documentation is part of the surface

Stable URL prefixes per section, Copy as Markdown on every page, and /llms.txt as a machine-readable index of the whole tree. The structure an agent reads is the structure you read.

A session reports to its mission

An agent session can report to a mission: the work an owner follows, with its plan, its open decisions and the owner's messages. The memory and missions collaboration contracts carry it, and a workspace binds each one to a provider. Bound to @putnami/cloud, every operation is one call to Putnami Agency under your putnami cloud login, so each checkout and each session of the workspace reads the same missions:

"options": {
  "collaboration": {
    "memory": { "provider": "@putnami/cloud", "version": 1 },
    "missions": { "provider": "@putnami/cloud", "version": 2 }
  }
}

The same extension serves putnami agency: your routine's trigger, a build started on an issue, the organization's model key and the shared audit attestations.


What this deliberately does not do

  • The agent-context document is per project, and it references rather than embeds. It is an orientation artifact, not an index of your repository — an agent still reads the files it decides to read.
  • Author overrides are narrow on purpose. If you could rewrite identity or capabilities, the document could lie, and every guarantee above would be worth nothing.
  • None of this makes an agent correct.

That last one matters. What the contract buys you is that an agent's actions are bounded, inspectable, and reversible — which is the precondition for letting one run at all.


  • Protocols — the contracts underneath everything on this page.
  • Develop with AI assistants — the practical setup and prompt patterns.
  • Write a feature spec — how intent gets recorded so putnami specs inspect has something to return.
  • Spec-driven development — the loop that turns declared intent into a CI verdict, and the architecture contracts (ARC and DARC) that bound what agents may couple.
  • Principles — in particular, automation is a first-class user.