Shura: Breaking the Single-Repo AI Guardrail
If you’ve been experimenting with the current generation of terminal-based AI tools (like Claude Code), you already know the workflow is incredibly fast for self-contained tasks. You give it a localized command, it modifies a few files, runs your test suite, and hooks into your local git workflow.
But it hits a massive brick wall the second you hand it a modern, real-world architectural problem: cross-repository coordination.
The moment you need to change a shared data contract, update a backend API while simultaneously refactoring the consuming frontend, or orchestrate a migration across five microservices, the single-context loop breaks. You end up copy-pasting code fragments, manually bridging the context gap, and acting as a gloriously overpaid copy-paste router for your AI terminal.
To solve this, I’m building Shura—a multi-agent, multi-repository orchestration plugin designed specifically for Claude Code.
The Core Concept: A Consultative Council
The name Shura (شُورَى) comes from the Arabic concept of a consultative council. Instead of throwing a massive, bloated codebase context at a single LLM instance and praying it doesn’t hallucinate under the weight of its own tokens, Shura enforces a rigid, hierarchical organizational structure using standard git mechanisms.
It treats cross-repo development exactly like an engineering organization does: by dividing labor and isolating domains.
User ─── /get-manager ──► Program Manager (PM)
│
┌──────────┼──────────┐
▼ ▼ ▼
Engineering Engineering Engineering
Manager (EM) Manager (EM) Manager (EM)
│
▼
Product Owner (PO)
│
┌────┴────┐
▼ ▼
Dev Dev
The Rules of Engagement
To keep agents from stepping on each other's toes, the framework establishes strict boundaries:
- The User Only Talks to the PM: You don't micromanage developers. You define a high-level cross-repo mission with the Program Manager.
- Domain Isolation via Git Worktrees: When you register a local or remote repository via
/add-repo, Shura isolates the environment into individual workspaces on a dedicated project branch. - Rigid Escalation Paths: Developers write code, execute local test suites, and talk only to their Product Owner. POs break down epics into verifiable tasks. If a developer faces a cross-repo conflict or gets stuck after three failed implementation attempts, they escalate up the chain.
- The Board Meeting: If a repo-level Engineering Manager flags a blocking architectural discrepancy, the PM triggers a virtual "Board Meeting," feeding the localized perspectives of all EMs into a collective session to negotiate a solution before resuming parallel execution.
Architectural State & Failure Recovery
One of the major gaps in complex agent workflows is resilience. If a network call drops or an agent crash occurs deep inside a sub-task, you shouldn't have to restart a multi-repo migration from scratch.
Shura handles this by keeping a lightweight, canonical JSON state and an append-only Decision Log inside a localized .shura/ directory:
<project-dir>/
├── .shura/
│ ├── config.json # Project identity + mission state
│ ├── decisions.md # PM cross-repo decision log
│ └── repos/
│ └── <slug>/
│ ├── config.json # Repo registration & assigned Epic
│ └── decisions.md # Local team engineering tradeoffs
└── repos/
└── <slug>/ # Clean worktree or clone (The actual code)
These decision logs act as a shared memory wall. They record every technical tradeoff, scope boundary change, and workaround applied by the agents. If a team fails or requires a manual restart, running /recover re-spawns the entire council simultaneously, forcing the new agent instances to read the log before executing so they don't re-open settled debates.
The Workflow in Action
The framework boils down the management of an entire cross-functional team into four command steps directly in your terminal:
Bash
# 1. Spin up a new cross-repo initiative
/init payment-revamp
# 2. Link your services (Shura auto-handles branch creation and worktrees)
/add-repo Frontend-App
/add-repo Backend-API
# 3. Define the mission and let the PM negotiate epics with you
/goal
# 4. (If disaster strikes) Re-launch all parallel teams with intact history
/recover
Once /goal passes your verification, the stakeholder meeting concludes, epics are written to state, and the framework automatically fires up parallel subagents to execute. EMs run the tests locally inside their respective worktrees, and when a domain's definition of done is met, they push the tracking branch up to your remote origin for final integration or human PR review.
Current Status & Next Steps
Shura is a playground for testing the limits of Spec-Driven Development (SDD) and agentic orchestration frameworks within terminal-native environments. By enforcing organizational boundaries and strict communication protocols on top of git, we can build multi-agent systems that don't decay into chaos when software spans more than a single directory.
Full disclosure: The repository is still very much a work in progress. I am currently ironing out the edge cases in multi-agent parallel execution loops and refining the state synchronization schema.
That said, the core architecture is locked in, and I am actively tracking toward a v0.1.0 first release very soon.
If you want to look at the prompt templates, break the skill definitions, or contribute to the architecture before the first tag drops, check out the repository here: