Prumo

Prumo is a Git-native protocol and CLI for software projects built with humans and AI agents.

The repository is the durable source of truth. Prumo stores canonical project state in Markdown, JSON, JSON Schema, and Git; generated adapters, caches, indexes, and runtime state remain derived.

Current release line

Prumo v0.5 is a pure Go distribution (ADR 002).

• Go v0.5 is the official single-binary CLI and Core implementation.
• Python v0.3 has been completely retired (ADR 002).
• Zero external runtime dependencies (no Python, pip, or virtualenv required).
• All canonical assets (schemas, catalog, workforce, adapters) are embedded directly into the Go binary.

What Prumo provides

• Project initialization from a profile.
• Deterministic agent, skill, recipe, risk, and model-policy resolution.
• Goal lifecycle with SHA-256 lock integrity and formal amendments.
• Plan DAG validation, Events, Evidence, Gates, and Doctor diagnostics.
• JSON Schema Draft 2020-12 validation with local $ref resolution.
• Lean Progressive Context planning and project intelligence reports.
• Compiler adapters for Generic, ChatGPT, Claude, Kimi, Codex, Claude Code, Traycer, Gemini, OpenCode, and Google Antigravity.
• Machine-readable JSON envelopes for automation and harness integrations.
• Conformance tests comparing Go behavior with golden specification baselines.
• Portable installation state, connector ownership, setup, and safe uninstall.

Quick start from source

Requirements:

• Go 1.22+;
• Git.

git clone [email protected]:raillen/prumo.git
cd prumo

go run ./cmd/prumo version
go run ./cmd/prumo --json version

Expected version output:

0.5.0

Run prumo --help or prumo <command> --help to view all available commands, options, and quick examples. You can also consult the CLI reference.

Initialize a project

Create a profile with at least one preferred model, then initialize a project:

go run ./cmd/prumo init ./my-project \
  --profile examples/brasa/project-profile.json \
  --non-interactive

go run ./cmd/prumo validate ./my-project
go run ./cmd/prumo doctor ./my-project

prumo init creates canonical project files such as prumo.json, .ai/, docs/PRUMO.md, PROJECT_STATE.md, and .prumo/history/. It does not install a harness globally.

Work with Goals

go run ./cmd/prumo goal new P00-G01 "Foundation" \
  --phase P00 \
  --objective "Establish the project foundation." \
  --path ./my-project

go run ./cmd/prumo goal state P00-G01 PLANNED --path ./my-project
go run ./cmd/prumo goal state P00-G01 LOCKED --path ./my-project
go run ./cmd/prumo goal list --path ./my-project

Locked Goals must be changed through goal amend; direct edits are detected by the lock digest.

Compile a harness adapter

go run ./cmd/prumo compile --target generic --path ./my-project
go run ./cmd/prumo compile --target codex --path ./my-project
go run ./cmd/prumo compile --target claude-code --path ./my-project

Generated artifacts are derived. The canonical project files and workforce packages remain the source of truth.

One-Link Install (Linux, macOS & Windows)

Linux & macOS

Downloads the release binary, verifies SHA-256 checksums, installs to ~/.local/bin/prumo, and configures your shell PATH automatically:

curl -fsSL https://raw.githubusercontent.com/raillen/prumo/main/scripts/install.sh | sh

Windows (PowerShell)

Downloads the Windows binary, verifies SHA-256 checksums, installs to %LOCALAPPDATA%\Programs\prumo\prumo.exe, and permanently configures user PATH:

powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/raillen/prumo/main/scripts/install.ps1 | iex"

For a reversible uninstall, review the script before running it:

curl --fail --location https://raw.githubusercontent.com/raillen/prumo/main/scripts/uninstall.sh -o uninstall.sh
sh uninstall.sh --mode pure --dry-run
sh uninstall.sh --mode pure

Use a portable installation home when testing or working in CI:

go run ./cmd/prumo --home ./prumo-home setup
go run ./cmd/prumo --home ./prumo-home install connector opencode
go run ./cmd/prumo --home ./prumo-home uninstall --connectors --purge-cache --purge-global-config

Uninstall never removes project files, .ai/, docs, Goals, Plans, Evidence, or other repository data. Read the installation manual and uninstall manual.

Machine output

Commands that support automation accept --json:

go run ./cmd/prumo --json version
go run ./cmd/prumo --json doctor ./my-project
go run ./cmd/prumo --json framework-check

The envelope is:

{
  "protocol_version": "1",
  "ok": true,
  "data": {},
  "diagnostics": [],
  "warnings": []
}

stdout is reserved for JSON when --json is used. Diagnostics belong on stderr. JSON output contains no ANSI formatting.

Development checks

gofmt -l cmd internal embedded_assets.go
go test ./... -race
go vet ./...

The Go suite includes comprehensive tests for initialization, resolver behavior, Goals, Plans, Doctor, Explain, migration, snapshots, all seven compiler targets, connectors, and adoption engine.

Documentation map

• Install manual
• Uninstall manual
• Usage manual
• CLI reference
• First project
• Core concepts
• v0.4 product scope
• Architecture
• ADR 001: Go Core
• ADR 002: Retire Python Runtime
• Migration status
• Conformance strategy
• Development blueprint
• Testing strategy
• Security and trust model
• Runtime Control Plane
• Documentation System v2
• Documentation source map

Use docs/PRUMO.md as the repository documentation router. Do not load the entire documentation tree for a single task.

License and contribution

Before contributing, read AGENTS.md, the coding standards, the dependency rules, and the testing strategy.