The Universal Protocol for Agentic Software Development
Castra is a tool of coercion. It does not ask LLMs to behave — it makes behaving the only available option. A single compiled binary enforces a 7-role RBAC system, cryptographic audit chain, AES-256-CTR encrypted storage at rest, and dual-gate approval (QA + Security) on every task, with zero infrastructure, zero client-server, and zero configuration drift. Every action is logged. Every approval is gated. Every role has a jurisdiction it cannot leave.
Architecturally: Castra is Kubernetes for agent orchestration. A multi-agent, multi-cluster orchestration substrate — rigorous, self-healing, self-regulating — that runs whatever workloads you build using AI agents. The workloads span the full spectrum: small tools, multi-tenant SaaS, compliance-driven enterprise systems, research pipelines, content production, household-of-agents systems, substrate-runtimes for digital cognition, and recursively another factory. Castra is the OSS orchestration plane; what gets built on top of it is the workload. (See docs/ROADMAP.md for the full architectural framing.)
"The castra.db is the only truth." — The Universal Constitution
State lives in the database. The conversation history of any LLM is irrelevant. A session can cap, a context window can fill, a model can be swapped — the project state is unchanged. Any agent that can read a markdown file can pick up exactly where the last one stopped.
This repository was planned, built, and shipped by AI agents governed by Castra.
castra-log.jsonl — the cryptographic audit chain of this codebase.
castra-audit-log-pre-v3.jsonl — the pre-cryptographic build record from v2.0.0 onward.
Verify it yourself:
castra log verifyThe chain either holds or it doesn't.
| Feature | Detail |
|---|---|
| 7-Role RBAC | Architect, Senior Engineer, Junior Engineer, Designer, QA, Security Ops, Doc Writer — each with a compiled skill definition and enforced jurisdictional boundary |
| Dual-Gate Approval | Tasks require explicit, sequential QA approval followed by Security approval before reaching done. Neither gate is optional. Break-glass bypasses are tracked via dedicated boolean columns (qa_bypassed, security_bypassed). |
| HATEOAS Affordance Engine | After every successful command, role-gated next-action hints are printed. The system tells the agent what it is allowed to do next — the agent never has to guess. |
| Immutable Log Chain | Per-project SHA-256 hash-linked chain. Each project's chain is fully isolated — independent seq numbering, independent verification. project_id is a canonical hash field, making cross-project chain splicing cryptographically detectable. castra log export --project <id> produces a self-contained, verifiable proof-of-work artifact. |
| AES-256-CTR Encrypted DB | Custom SQLite VFS (castra-vfs) encrypts every page at rest. Key derived via HKDF-SHA256 from the device Ed25519 private key. WAL-safe. Unreadable by plain sqlite3. |
| Session Management | Session token with configurable action cap, warning threshold, and refresh interval. castra persona refresh reinforces the active identity mid-session — prints role reminder, prohibitions, capabilities, and action count. Capped sessions permit only log add and note add. Resume from any agent, any model, any session. |
| Multi-Vendor / LLM-Agnostic | AGENTS.md is the protocol contract. Any LLM — Claude, Copilot, Gemini, or any future model — can activate a role and operate within the protocol. No vendor agent files. No prompt engineering. |
| Terminal UI | castra tui — live project dashboard with task hierarchy, affordance bar, and audit drill-down |
| Worktree Lifecycle | castra worktree create/merge/delete — git worktree management tied to the task state machine |
| Sovereign Mode | --sovereign flag bypasses session entirely, role is set to "sovereign", every invocation is logged to the chain |
| Custom DB Path | --config-path <path> global flag opens a custom database instead of ~/.castra/castra.db — useful for multi-machine setups or isolated test environments |
| Role | Identity | Authority |
|---|---|---|
architect |
The Lawgiver | Plans milestones, sprints, and tasks. No implementation code. |
senior-engineer |
The Core Builder | Implements complex blueprints. No milestone creation. |
junior-engineer |
The Maintainer | Executes routine, scoped tasks assigned by the architect. |
designer |
The Shaper | UI/UX specifications and assets. No backend code. |
qa-functional |
The Guardian | Verifies behavior against requirements. No feature code. |
security-ops |
The Sentinel | Security audits and hardening. No feature code. |
doc-writer |
The Chronicler | Technical documentation. No implementation code. |
brew tap amangsingh/castra
brew install castraPre-built binaries for macOS and Linux are available on the releases page.
# macOS (Apple Silicon)
curl -L https://github.com/amangsingh/castra/releases/latest/download/castra_darwin_arm64.tar.gz | tar xz
sudo mv castra /usr/local/bin/
# macOS (Intel)
curl -L https://github.com/amangsingh/castra/releases/latest/download/castra_darwin_amd64.tar.gz | tar xz
sudo mv castra /usr/local/bin/
# Linux (amd64)
curl -L https://github.com/amangsingh/castra/releases/latest/download/castra_linux_amd64.tar.gz | tar xz
sudo mv castra /usr/local/bin/Verify the download against checksums.txt on the releases page.
The canonical post-git pull rebuild path — every contributor should run this
after pulling main so the installed binary tracks the substrate verbs:
git pull
make rebuild # = go install -ldflags <version,commit,date> ./...
# restart any long-running shells / agent sessions so they pick up the new binarymake rebuild installs a fully-stamped binary into $(go env GOBIN) (falling
back to $GOPATH/bin) — make sure that directory is on your PATH. Confirm
the result with:
castra version # e.g. castra v1.0.0 (a1b2c3d) darwin/arm64
castra version --check # exits non-zero if the running binary is stalePlain go build -o ./castra . is fine for ad-hoc smoke tests but produces an
unstamped binary (Version=dev, BuildCommit=unknown) and does not place it
on PATH. Prefer make rebuild for anything that reaches a running session.
CI publishes a fully-stamped binary artifact for every push to main (see
.github/workflows/ci.yml) — download it from the
"Build" workflow run if you would rather not rebuild locally. Tagged releases
publish signed archives via the release workflow.
Step 1 — Initialize globally
Run once per machine. Creates the device identity at ~/.castra/ (Ed25519 keypair, encrypted global DB).
castra init -gStep 2 — Initialize a project workspace
Run from the git repo root. Generates AGENTS.md and CLAUDE.md for the project.
castra init --name "Project Name"Step 3 — Activate a persona
castra persona activate --role architect
# Returns: <token>All subsequent commands require --session <token>.
Step 4 — Create a project and add a task
castra project add --session <token> --name "Project Alpha" --description "Next-gen AI platform"
# Returns: <project-id>
castra milestone add --session <token> --project <project-id> --name "M1 — Core API"
# Returns: <milestone-id>
castra task add --session <token> --project <project-id> --milestone <milestone-id> \
--title "Implement auth layer" --description "Ed25519-based request signing" --priority high
# Returns: <task-id>Step 5 — Claim a task and create a worktree
castra task claim --session <token> <task-id>
castra worktree create --session <token> --task <task-id>Step 6 — Merge and dual-gate approval
The engineer merges the worktree, which atomically transitions the task doing → review. Then QA and Security each run task approve in sequence. Both gates must pass before the task reaches done — neither gate is optional, and task submit cannot bypass them.
# Engineer merges the worktree — this atomically advances doing → review
castra worktree merge --session <token> --task <task-id>
# QA approves first — sets qa_approved
castra persona activate --role qa-functional
# Returns: <qa-token>
castra task approve --session <qa-token> --note "Behavior verified against acceptance criteria" <task-id>
# Security approves second — sets security_approved AND advances review → done
castra persona activate --role security-ops
# Returns: <sec-token>
castra task approve --session <sec-token> --note "No new attack surface; audit trail intact" <task-id>Castra governance is defined in AGENTS.md and enforced via CLAUDE.md. Compliance varies by platform.
| Platform | Compliance | Notes |
|---|---|---|
| Claude Code CLI | ✅ Recommended | Lower tool count, CLAUDE.md loaded as system-reminder, PreToolUse hook enforces session on every tool call |
| Claude Code Desktop (light config) | Same architecture as CLI but governance competes with all loaded MCP instructions at equal priority | |
| Claude Code Desktop (heavy config) | 120+ MCP tools consume the majority of the context window before any task begins. CLAUDE.md is structurally at the same tier as Pencil, Gmail, Figma, and other MCP definitions — attention dilution is significant | |
| Other agents (Cursor, Windsurf, etc.) | ✅ Full | AGENTS.md is read natively as a first-class instruction file |
Claude Code Desktop includes a built-in auto-memory system that writes persistent notes to ~/.claude/. This is an Anthropic platform behavior — castra cannot suppress or intercept it.
This conflicts with Law 9 (No Side-Channels / The Seal) in AGENTS.md, which prohibits all state persistence outside the castra database. When running castra under Claude Code Desktop, the platform may write memory files that exist outside the audit trail.
This is not a castra limitation. No workaround is provided — the correct fix is for Anthropic to expose a setting to disable auto-memory.
brew upgrade castra
castra --sovereign db encryptcastra --sovereign db encrypt performs an in-place AES-256-CTR encryption of the existing global castra.db at ~/.castra/castra.db. It derives the encryption key via HKDF-SHA256 from the device Ed25519 private key, copies every page through the castra-vfs layer, and stamps an encryption sentinel. Already-encrypted databases are detected and the command is a no-op. Schema migrations are applied automatically on first open by any subsequent castra invocation — there is no separate migration step.
Getting Started
| File | Contents |
|---|---|
| docs/ADOPTING_CASTRA.md | Operator onboarding — install, configure, and run your first governed project |
| AGENTS.md | Sovereign operating contract for all AI agents — the protocol definition |
Operations
| File | Contents |
|---|---|
| docs/OPERATIONS.md | Day-to-day runbook — session lifecycle, task pipeline, worktree management, incident response |
| docs/RELEASE_RUNBOOK.md | Release process — tagging, binary publish, changelog, signoff checklist |
| docs/sovereign-deployment.md | Sovereign deployment guide — encrypted DB, device identity, self-hosted setup |
Architecture
| File | Contents |
|---|---|
| docs/ARCHITECTURE.md | System topology, command routing pipeline, cryptographic layer, log chain, worktree lifecycle |
| docs/TECHNICAL_SPEC.md | Schema reference, package inventory, CLI command index, session lifecycle, archetype system |
| docs/SUBSTRATE.md | Substrate self-healing — spec-realign, drift detection, task realign protocol |
| docs/EMBEDDINGS_ARCHITECTURE.md | Embeddings layer — semantic search, FTS5 remote daemon, episodic memory routing |
| docs/ROADMAP.md | Roadmap — Kubernetes-for-agent-orchestration framing, upcoming milestones |
Security
| File | Contents |
|---|---|
| docs/SECURITY.md | Threat model, device identity, DB encryption, CWE mitigations, vulnerability reporting |
Reference
| File | Contents |
|---|---|
| docs/UNIVERSAL_LAW.md | Universal Constitution — the immutable laws governing all Castra substrate behaviour |
| docs/lints.md | Lint rules and static analysis constraints enforced across the codebase |
Contributing
| File | Contents |
|---|---|
| docs/vendorwriter-contributing.md | Vendor and doc-writer contribution guide |
| CONTRIBUTING.md | Contribution doctrine — opens post v5.0.0 |
History
| File | Contents |
|---|---|
| CHANGELOG.md | Full version history from v1.0 onward |
Contributions open at v5.0.0. All PRs will be submitted through Castra governance — QA gate, Security gate, cryptographic audit trail on every merge.
The world's first cryptographically governed open source project.
MIT