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.
"The workspace.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.
Proof of Work
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:
The chain either holds or it doesn't.
Features
| 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 |
Roles
| 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. |
Install
Homebrew
brew tap amangsingh/castra brew install castra
Download binary
Pre-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.
Build from source
Quickstart
Step 1 — Initialize globally
Run once per machine. Creates the device identity at ~/.castra/ (Ed25519 keypair, encrypted global DB).
Step 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" --desc "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" --desc "Ed25519-based request signing" --prio 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 — Dual-gate approval
# QA approves first castra persona activate --role qa-functional # Returns: <qa-token> castra task submit --session <qa-token> <task-id> # Security approves second castra persona activate --role security-ops # Returns: <sec-token> castra task update --session <sec-token> --status done <task-id>
Agent Platform Compatibility
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: auto-memory
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.
Upgrade from v2.x
brew upgrade castra castra db encrypt --sovereign
castra db encrypt --sovereign migrates the existing workspace.db from integer primary keys to UUIDv7, applies all pending schema migrations, encrypts the database at rest with AES-256-CTR, and renames the source to workspace.db.v2.bak.
Documentation
| File | Contents |
|---|---|
| AGENTS.md | Sovereign operating contract for all AI agents — the protocol definition |
| 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/SECURITY.md | Threat model, device identity, DB encryption, CWE mitigations, vulnerability reporting |
| CHANGELOG.md | Full version history from v1.0 through v3.1.2 |
| CONTRIBUTING.md | Contribution doctrine — opens post v5.0.0 |
v5.0.0
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.
License
MIT