{"id":44791730,"url":"https://github.com/amangsingh/castra","last_synced_at":"2026-04-15T18:04:14.397Z","repository":{"id":337722351,"uuid":"1154914747","full_name":"amangsingh/castra","owner":"amangsingh","description":"A tool of coercion. Deterministic governance for multi-agent software development. DB is the truth.","archived":false,"fork":false,"pushed_at":"2026-04-10T11:34:16.000Z","size":11353,"stargazers_count":9,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T12:33:29.866Z","etag":null,"topics":["agents","ai-governance","audit-log","cli","developer-tools","golang","llm","multi-agent","rbac","sqlite"],"latest_commit_sha":null,"homepage":"https://agents.md","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amangsingh.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T23:09:44.000Z","updated_at":"2026-04-10T11:34:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amangsingh/castra","commit_stats":null,"previous_names":["amangsingh/castra"],"tags_count":43,"template":false,"template_full_name":null,"purl":"pkg:github/amangsingh/castra","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amangsingh%2Fcastra","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amangsingh%2Fcastra/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amangsingh%2Fcastra/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amangsingh%2Fcastra/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amangsingh","download_url":"https://codeload.github.com/amangsingh/castra/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amangsingh%2Fcastra/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31853280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai-governance","audit-log","cli","developer-tools","golang","llm","multi-agent","rbac","sqlite"],"created_at":"2026-02-16T11:29:04.181Z","updated_at":"2026-04-15T18:04:14.391Z","avatar_url":"https://github.com/amangsingh.png","language":"Go","readme":"# Castra\n\n**The Universal Protocol for Agentic Software Development**\n\nCastra 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.\n\n\u003e **\"The castra.db is the only truth.\"** — *The Universal Constitution*\n\nState 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.\n\n---\n\n## Proof of Work\n\nThis repository was planned, built, and shipped by AI agents governed by Castra.\n\n`castra-log.jsonl` — the cryptographic audit chain of this codebase.  \n`castra-audit-log-pre-v3.jsonl` — the pre-cryptographic build record from v2.0.0 onward.\n\nVerify it yourself:\n```bash\ncastra log verify\n```\nThe chain either holds or it doesn't.\n\n---\n\n## Features\n\n| Feature | Detail |\n| :--- | :--- |\n| **7-Role RBAC** | Architect, Senior Engineer, Junior Engineer, Designer, QA, Security Ops, Doc Writer — each with a compiled skill definition and enforced jurisdictional boundary |\n| **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`). |\n| **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. |\n| **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 \u003cid\u003e` produces a self-contained, verifiable proof-of-work artifact. |\n| **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`. |\n| **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. |\n| **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. |\n| **Terminal UI** | `castra tui` — live project dashboard with task hierarchy, affordance bar, and audit drill-down |\n| **Worktree Lifecycle** | `castra worktree create/merge/delete` — git worktree management tied to the task state machine |\n| **Sovereign Mode** | `--sovereign` flag bypasses session entirely, role is set to `\"sovereign\"`, every invocation is logged to the chain |\n| **Custom DB Path** | `--config-path \u003cpath\u003e` global flag opens a custom database instead of `~/.castra/castra.db` — useful for multi-machine setups or isolated test environments |\n\n---\n\n## Roles\n\n| Role | Identity | Authority |\n| :--- | :--- | :--- |\n| `architect` | The Lawgiver | Plans milestones, sprints, and tasks. No implementation code. |\n| `senior-engineer` | The Core Builder | Implements complex blueprints. No milestone creation. |\n| `junior-engineer` | The Maintainer | Executes routine, scoped tasks assigned by the architect. |\n| `designer` | The Shaper | UI/UX specifications and assets. No backend code. |\n| `qa-functional` | The Guardian | Verifies behavior against requirements. No feature code. |\n| `security-ops` | The Sentinel | Security audits and hardening. No feature code. |\n| `doc-writer` | The Chronicler | Technical documentation. No implementation code. |\n\n---\n\n## Install\n\n### Homebrew\n\n```bash\nbrew tap amangsingh/castra\nbrew install castra\n```\n\n### Download binary\n\nPre-built binaries for macOS and Linux are available on the [releases page](https://github.com/amangsingh/castra/releases/latest).\n\n```bash\n# macOS (Apple Silicon)\ncurl -L https://github.com/amangsingh/castra/releases/latest/download/castra_darwin_arm64.tar.gz | tar xz\nsudo mv castra /usr/local/bin/\n\n# macOS (Intel)\ncurl -L https://github.com/amangsingh/castra/releases/latest/download/castra_darwin_amd64.tar.gz | tar xz\nsudo mv castra /usr/local/bin/\n\n# Linux (amd64)\ncurl -L https://github.com/amangsingh/castra/releases/latest/download/castra_linux_amd64.tar.gz | tar xz\nsudo mv castra /usr/local/bin/\n```\n\nVerify the download against `checksums.txt` on the releases page.\n\n### Build from source\n\n```bash\ngo build -o ./castra .\n```\n\n---\n\n## Quickstart\n\n**Step 1 — Initialize globally**\n\nRun once per machine. Creates the device identity at `~/.castra/` (Ed25519 keypair, encrypted global DB).\n\n```bash\ncastra init -g\n```\n\n**Step 2 — Initialize a project workspace**\n\nRun from the git repo root. Generates `AGENTS.md` and `CLAUDE.md` for the project.\n\n```bash\ncastra init --name \"Project Name\"\n```\n\n**Step 3 — Activate a persona**\n\n```bash\ncastra persona activate --role architect\n# Returns: \u003ctoken\u003e\n```\n\nAll subsequent commands require `--session \u003ctoken\u003e`.\n\n**Step 4 — Create a project and add a task**\n\n```bash\ncastra project add --session \u003ctoken\u003e --name \"Project Alpha\" --desc \"Next-gen AI platform\"\n# Returns: \u003cproject-id\u003e\n\ncastra milestone add --session \u003ctoken\u003e --project \u003cproject-id\u003e --name \"M1 — Core API\"\n# Returns: \u003cmilestone-id\u003e\n\ncastra task add --session \u003ctoken\u003e --project \u003cproject-id\u003e --milestone \u003cmilestone-id\u003e \\\n  --title \"Implement auth layer\" --desc \"Ed25519-based request signing\" --prio high\n# Returns: \u003ctask-id\u003e\n```\n\n**Step 5 — Claim a task and create a worktree**\n\n```bash\ncastra task claim --session \u003ctoken\u003e \u003ctask-id\u003e\ncastra worktree create --session \u003ctoken\u003e --task \u003ctask-id\u003e\n```\n\n**Step 6 — Dual-gate approval**\n\n```bash\n# QA approves first\ncastra persona activate --role qa-functional\n# Returns: \u003cqa-token\u003e\ncastra task submit --session \u003cqa-token\u003e \u003ctask-id\u003e\n\n# Security approves second\ncastra persona activate --role security-ops\n# Returns: \u003csec-token\u003e\ncastra task update --session \u003csec-token\u003e --status done \u003ctask-id\u003e\n```\n\n---\n\n## Agent Platform Compatibility\n\nCastra governance is defined in `AGENTS.md` and enforced via `CLAUDE.md`. Compliance varies by platform.\n\n| Platform | Compliance | Notes |\n| :--- | :--- | :--- |\n| Claude Code CLI | ✅ Recommended | Lower tool count, CLAUDE.md loaded as system-reminder, PreToolUse hook enforces session on every tool call |\n| Claude Code Desktop (light config) | ⚠️ Reduced | Same architecture as CLI but governance competes with all loaded MCP instructions at equal priority |\n| Claude Code Desktop (heavy config) | ⚠️ Degraded | 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 |\n| Other agents (Cursor, Windsurf, etc.) | ✅ Full | AGENTS.md is read natively as a first-class instruction file |\n\n### Claude Code Desktop: auto-memory\n\nClaude 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.\n\nThis 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.\n\nThis is not a castra limitation. No workaround is provided — the correct fix is for Anthropic to expose a setting to disable auto-memory.\n\n---\n\n## Upgrade from v2.x\n\n```bash\nbrew upgrade castra\ncastra db encrypt --sovereign\n```\n\n`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`.\n\n---\n\n## Documentation\n\n| File | Contents |\n| :--- | :--- |\n| [AGENTS.md](AGENTS.md) | Sovereign operating contract for all AI agents — the protocol definition |\n| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System topology, command routing pipeline, cryptographic layer, log chain, worktree lifecycle |\n| [docs/TECHNICAL_SPEC.md](docs/TECHNICAL_SPEC.md) | Schema reference, package inventory, CLI command index, session lifecycle, archetype system |\n| [docs/SECURITY.md](docs/SECURITY.md) | Threat model, device identity, DB encryption, CWE mitigations, vulnerability reporting |\n| [CHANGELOG.md](CHANGELOG.md) | Full version history from v1.0 through v3.1.2 |\n| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution doctrine — opens post v5.0.0 |\n\n---\n\n## v5.0.0\n\nContributions open at v5.0.0. All PRs will be submitted through Castra governance — \nQA gate, Security gate, cryptographic audit trail on every merge.\n\nThe world's first cryptographically governed open source project.\n\n---\n\n## License\n\nMIT\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famangsingh%2Fcastra","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famangsingh%2Fcastra","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famangsingh%2Fcastra/lists"}