Agents, Governance, Orchestration, Roles & Artifacts
Agora is a local, Markdown-first, Git-native framework for governing software delivery across humans, AI agents, services, and swarms. It materializes the roles, lifecycle rules, permissions, evidence, and durable work records that a team chooses for each project.
Agora is independent of the project's programming language, LLM provider, agent environment, and development process. Its Python application services coordinate the protocol; the CLI is an optional adapter and does not introduce an LLM SDK or runtime into the governed codebase.
Developed by Modern Ash.
Agora is intentionally split into a small set of cooperating projects. The boundaries are part of the design: the Core owns governance and durable state, Studio provides a local visual control plane, and Truco Agora is a concrete application that demonstrates the method with real human and LLM participants.
| Project | Role | When to use it |
|---|---|---|
| Agora Core | Python domain, application services, CLI, Method Packs, Tool Packs, persistence, gates, evidence, and actor governance | Install it in any existing or new repository to govern an SDLC workflow |
| Agora Studio | Local-first web control plane over the same Core application services | Browse projects, swarms, work, specifications, lifecycle, artifacts, evidence, approvals, and Activity |
| Truco Agora | End-to-end demonstration application | See Scrum/spec-driven ideas applied to a playable domain with human seats, LLM agents, provider discovery, observability, and tests |
flowchart LR
C[Agora Core\nGovernance + persistence] --> T[Agora CLI\nTerminal and automation]
C --> S[Agora Studio\nLocal visual control plane]
C --> D[Truco Agora\nMethodology demo application]
T -. operates .-> P[Project .agora/\nGit-backed records]
S -. reads and approves through .-> P
D -. demonstrates and records work in .-> P
The projects are complementary rather than three competing implementations. Start with Core when you need to govern a project, add Studio when a visual read/review surface helps adoption, and open Truco Agora when you want a runnable reference for the complete workflow. Studio does not replace the CLI, and Truco Agora does not redefine Core's lifecycle rules.
Agora is an alpha (0.x) framework that is ready for controlled pilots. The published CLI can
initialize and adopt repositories, execute complete governed workflows, authenticate actors,
coordinate recursive swarms, run reviewed external tools, and validate its durable state.
| Area | Current maturity |
|---|---|
| Core lifecycle | Implemented, exercised end to end, and covered by automated tests |
| Bundled workflows | Spec-Driven, Scrum, and Kanban Method Packs |
| Actor forms | Human, AI, service, automation, and recursively composed swarm |
| Integrations | Provider-neutral Tool Packs plus reviewed native CLI adapters |
| Persistence | Human-readable Markdown, Git history, and rollback-protected compound lifecycle writes |
| Compatibility | Explicit project migrations and agora upgrade support |
| Stability | Alpha: CLI and Markdown contracts may still evolve before 1.0 |
Use Agora now for evaluation and controlled team adoption. Before production use, review the selected Method Pack, actor permissions, execution environment, external adapters, and recovery policy for your organization.
- One governance model for every participant. A role can be held by a human, an AI, a service, or a swarm without changing the lifecycle contract.
- Process is configuration. Method Packs define roles, states, transitions, gates, evidence, and work-in-progress rules; Scrum and Kanban are examples, not hard-coded behavior.
- The LLM remains replaceable. Codex, Claude, local models, and custom runners consume the same portable commands without provider dependencies in the core.
- Work survives the session. Decisions, handoffs, approvals, signatures, artifacts, Tool Runs,
and usage records remain inspectable in
.agora/and Git. - External tools stay governed. Provider-neutral capabilities are translated by reviewed, bounded adapters that prefer an installed native CLI.
Agora complements issue trackers, source hosts, CI/CD systems, documentation platforms, and cloud providers. It is not a project-management UI, an agent runtime, or a replacement for those systems.
Multi-agent frameworks (OpenAI Swarm, AutoGen, CrewAI, LangGraph, and others) use "swarm" for runtime coordination: several agents exchanging messages or handing off control to solve a task in one session. Spec-driven tools (spec-kit and similar) generally have no equivalent concept at all — one agent works a spec to completion.
An Agora swarm is neither. It is the durable governance unit for one objective: a Method Pack, the
roles it requires, and the human, AI, service, or swarm actors assigned to hold them, with every
transition checked against a permission and gate contract and recorded in .agora/ and Git. A
swarm can be a single human role-holder and a single AI role-holder working sequentially through a
gated lifecycle — as most swarms are — or it can compose recursively into a delegated team. It is
not runtime message-passing between agents, and it does not imply parallelism or autonomy. If you
know "swarm" from a multi-agent runtime, expect Agora's version to be about who is allowed to do
what, and the durable record of what they did — not about how agents talk to each other.
flowchart LR
H[Human] --> CLI[Agora CLI]
A[AI agent] --> CLI
S[Swarm] --> CLI
CLI --> P[Project protocol<br/>.agora/]
P --> M[Method Packs]
P --> T[Tool Packs]
P --> R[Durable records<br/>work, evidence, actions]
T --> C[Reviewed native CLI adapters]
C --> E[GitHub, GitLab, Jira,<br/>Confluence, CI/CD, cloud]
G[Git] <--> P
Programmatic interfaces import the versioned contracts in agora.application. Agora CLI and the
local-first Agora Studio API are peer adapters over those services; neither interface owns
lifecycle policy or edits durable records outside Core. See the application-service contract
reference for the Core 0.8 compatibility boundary.
Configuration is resolved predictably:
Agora defaults < ~/.agora < project .agora < swarm configuration
Agora requires Python 3.11 or newer. Install the published CLI with
uv:
uv tool install agora-framework
agora self-testTo work from this repository:
uv sync --extra dev
uv run agora self-testself-test runs the role conformance harness in temporary workspaces. It exercises every bundled
method with human, AI, and swarm role holders without changing the current project.
See Installation and customization for user-level configuration, upgrades, editable installs, and team rollout options.
The recommended first experience is an interactive review of runtime, model, Method Pack, starter team, actor security, Git branch, and persistence scope:
cd my-project
agora setupFor an existing Git repository, agora adopt runs the read-only preflight before showing or
applying the plan. Both wizards collect one decision at a time and write nothing before final
confirmation. See the guided setup guide.
Create and advance daily work without assembling long commands:
agora work start
agora continue
agora work finishwork start selects a ready swarm and compatible assigned actor, collects acceptance criteria one
at a time, and writes only after review. continue previews one bounded action. At a human boundary
it lets the role holder act directly, use a capability-compatible AI executor without surrendering
the role, or create a formal handoff when responsibility truly changes. work finish reviews
criteria, artifacts, evidence, Git policy, and approvals before recording explicit acceptance and
the Method Pack completion transition. The declarative commands remain the stable automation
surface.
Run the read-only adoption preflight, then create the governed feature branch and workspace:
cd existing-service
agora adopt --check --id payment-idempotency --base main
agora quickstart \
--id payment-idempotency \
--base main \
--objective "Deliver payment idempotency"The preflight checks repository state, branch safety, runtime availability, reserved identities, existing Agora state, and ignore rules. Quickstart is transactional: if a later step fails, Agora rolls back the branch and state it created.
The executable existing-codebase pilot demonstrates this path without requiring an LLM account or network service.
mkdir my-project
cd my-project
git init
agora quickstart --objective "Ship the first increment"Quickstart initializes the protocol, registers a human and an AI actor, creates a swarm, assigns the roles required by the active Method Pack, and writes the selected environment adapter.
Add --secure to generate an external Ed25519 keypair for each quickstart actor and require signed
authentication:
agora quickstart --objective "Ship the first increment" --securePrivate keys remain outside Agora. Only public identity, rotation or revocation history, and signed verification evidence become durable protocol records.
Agora installs operational Markdown rather than a hidden database:
<project>/
├── .agora/
│ ├── project.md # Effective project configuration
│ ├── constitution.md # Project principles and restrictions
│ ├── PROTOCOL.md # Collaboration protocol
│ ├── STANDARDS.md # Cross-actor engineering standards
│ ├── PACKS.lock.md # Deterministic pack composition
│ ├── methods/ # Roles, transitions, gates, and policy
│ ├── actors/ # Actor identity and public-key history
│ ├── swarms/ # Work state and usage ledgers
│ ├── actions/ # Prepared and applied mutations
│ ├── artifacts/ # Governed artifact references
│ ├── sessions/ # Resolved execution context
│ ├── tool-runs/ # External invocation requests and results
│ ├── intents/ # Reviewed problems and desired outcomes
│ ├── evaluations/ # Continuous evaluation contracts and results
│ ├── reviews/ # Structured review findings and decisions
│ ├── guardrails/ # Deterministic pre-action policies
│ ├── triggers/ # Idempotent external event routing
│ └── control-bands/ # Production signals and proposed intents
└── .agents/ or .claude/ # Environment-specific command projection
The repository ships the sources for these files under packs/. Actor, swarm, action,
work, evidence, and Tool Run records are created dynamically as work progresses. The
artifact location reference maps distribution sources to
their materialized project paths.
The active Method Pack defines the lifecycle, not the CLI core.
| Bundled method | Best fit | Governs |
|---|---|---|
spec-driven |
Feature work that needs explicit intent before implementation | Clarification, specification, planning, implementation, validation |
scrum |
Time-boxed delivery with accountable product and facilitation roles | Backlog, sprint flow, review, acceptance, increment evidence |
kanban |
Continuous pull-based delivery | Queue policy, WIP limits, review, service acceptance |
Teams can author and install a custom Method Pack for another process without changing Agora's kernel. Start with the Method Pack reference and the custom lifecycle sample.
For continuous agent operation, Agora also stores reviewed intent, evaluation outcomes, structured review findings, deterministic guardrails, idempotent event routing, production control-band findings, and derived delivery metrics. See the AI-native SDLC controls guide.
agora configure --integration codex
agora configure --integration claude
agora configure --integration generic --provider internal --model reviewed-model| Integration | Execution model |
|---|---|
codex |
Materializes portable commands for the installed Codex CLI |
claude |
Materializes the same protocol for the installed Claude CLI |
generic |
Uses an explicit structured runner supplied at launch time by the team |
The configured model and provider are project or user choices. Agora governs the resulting work;
it does not embed provider credentials or an LLM client in its core. See
LLM environments. Generic sessions accept the runner explicitly,
for example agora run --runner "company-agent run" --launch.
Both native integrations run unattended, so their commands are built with a non-interactive
approval posture: codex exec runs with its own default read-only, unattended approval behavior,
and claude --print is launched with --permission-mode bypassPermissions, since a governed
session has nobody available to approve an interactive permission prompt. Changing an actor's
runtime with agora actor runtime takes effect immediately, including on the next automatic retry
of a failed session (agora resume / agora run --until-blocked recompute the launch command from
the actor's current runtime rather than replaying the failed attempt's command) — the one exception
is the generic integration, which has no runtime to derive a command from and always requires an
explicit --runner, so a runner-less retry there reuses the prior explicit runner.
Actors may also declare ordered, reviewed fallbacks. Agora chooses the first executable declared runtime, and skips a runtime only when its most recent matching session contains a recognized quota or rate-limit signal; ordinary task failures remain on the primary runtime:
agora actor runtime --actor delivery-agent \
--integration codex --provider openai --model primary \
--fallback claude:anthropic:fallback-modelFor specification tooling, agora work clarify, work checklist, work verify-consistency, and
work gherkin create Markdown, evidence, and artifacts without transitioning work by themselves.
The bundled Spec-Driven Method Pack requires the latest clarification run to cover current inputs
and leave no unanswered questions before drafting -> clarified; other methods can opt into the
same gate policy. Use agora work traceability to detect generated output made stale by changed
criteria or artifacts, and agora status --board for a one-frame aggregate view. See the
spec-tooling and runtime resilience guide.
Clarification is Method Pack-aware: Core supplies the active lifecycle, protocol, gates, roles, and
assignments to the configured runtime without privileging Scrum, Kanban, or Spec-driven behavior.
sequenceDiagram
participant O as Role holder
participant A as Agora
participant F as Filesystem and Git
participant X as External runtime or tool
O->>A: Inspect next authorized action
A->>F: Resolve method, role, work, and evidence
A-->>O: Return bounded action and context
O->>X: Perform or launch governed work
X-->>A: Submit result and evidence
A->>F: Validate and persist transition
O->>F: Review and commit durable records
Use the guided controller for one reviewed action at a time. The explicit controller remains available for bounded automation:
agora continue
agora work finish
agora next
agora run --until-blocked --max-steps 10
agora inbox
agora validate
git status --shortEvery lifecycle mutation is checked against the active Method Pack at the time it is applied. In
authenticated projects, mutations use prepared ACTION.md intents whose signatures bind the actor,
operation, work preconditions, and materialized session context.
The operational loop guide covers stopping, resuming, human handoffs, and durable failure recovery.
When Agora is driven from Codex, Claude Code, CI, or another non-TTY host, enable its independent engine trace to see progress without corrupting the structured result:
agora --trace compact run --until-blocked --max-steps 10
AGORA_TRACE=jsonl agora statusTrace phases are flushed to stderr; final JSON remains on stdout. Agora-launched agent sessions
default to AGORA_TRACE=compact, so chat integrations can relay lifecycle phases while keeping
provider reasoning and raw output out of the observation stream.
Agora separates stable capabilities from provider-specific translation:
- Provider-neutral Tool Packs cover repositories, code review, work management, CI/CD, releases, repository governance, security scanning, documentation, cloud infrastructure, observability, and portfolio management.
- Reviewed CLI adapters currently cover the GitHub and GitLab delivery ecosystems, Jira, Confluence, Terraform, and read-only AWS and Google Cloud inventory.
- A provider-neutral Core issue port binds and explicitly reconciles GitHub and Jira through the
same normalized snapshot contract. A
closed -> openfact can create a new authorized local work revision; the synchronization itself remains read-only on the provider. Reopen currently fails closed for actors that require signed lifecycle actions until its prepare/apply contract exists. - Native CLIs are preferred when they are installed, version-compatible, and non-interactive. MCP remains an explicit alternative transport rather than an implicit dependency.
flowchart TD
W[Governed work] --> P[Provider-neutral operation]
P --> A[Reviewed adapter]
A --> V{CLI version and<br/>capability valid?}
V -- no --> B[Block with durable reason]
V -- yes --> Q[Prepared structured command]
Q --> R[Bounded external runner]
R --> E[Redacted result and evidence]
E --> D[Durable Tool Run]
Adapter commands are structured and shell-free, contain no credentials, and have explicit timeout and captured-output limits. Write or destructive capabilities such as merge, deployment, release publication, infrastructure apply, and incident resolution remain opt-in and policy-controlled.
Every launched operation persists RUN.md plus a bounded RESULT.md. Inspect both through the
typed read command instead of parsing provider output from terminal logs:
agora tool result --run <tool-run-id>Prepared runs return result: null; completed and failed runs return their validated status, exit
code, result kind, stdout, stderr, and durable path. The
Jira ACLI sample demonstrates this boundary through actual child
processes without requiring Jira Cloud credentials.
See the GitHub ecosystem guide, CLI-first adapter guide, and Tool Pack reference.
Agora enforces governance at the protocol boundary while leaving operating-system isolation and credential custody to the execution environment:
- Actor private keys and provider credentials are never stored by Agora.
- Public-key rotation and revocation history remain auditable.
- Authenticated changes are prepared, signed externally, verified, and revalidated before apply.
- Tool permissions are bounded by actor capability, role, Method Pack policy, evidence, and explicit approvals.
- Tool Sync and issue reconciliation are read-only and explicit; Agora performs no background polling or provider mutation through either path.
- Containers or external runners provide filesystem, network, syscall, and resource isolation.
Read Actor authentication, Signed lifecycle actions, and Execution boundaries before enabling authenticated or write-capable integrations.
Run the installed role harness:
agora self-testRun the repository's complete verification pipeline:
uv sync --extra dev
uv run python scripts/verify_all.pyThe verifier formats and lints Python, runs unit and failure-path tests, validates documentation links and packaging, exercises the role harness, discovers and runs every executable sample, and builds the distribution. CI repeats the supported Python-version matrix and the complete verifier.
For focused commands and expected output, see Complete verification and Role conformance test harness.
Agora deliberately does not claim that governance files alone make arbitrary agent output safe or correct. Teams remain responsible for reviewing their Method Packs, custom runners, external tool authority, product evidence, and infrastructure isolation.
During the alpha series:
- CLI and Markdown schemas may change with explicit migrations.
- Custom Method and Tool Packs need organization-specific conformance and failure-path tests.
- Provider behavior outside a reviewed adapter's exact operation subset is unsupported.
- Production authorization should use organization-managed identities and keys, not quickstart credentials.
- External systems remain sources of operational state; Agora persists their verified references and evidence rather than silently mirroring them.
- Atomic replacement protects every individual Markdown document. Multi-document rollback currently covers work creation and specialized upgrade, registry, and pack transactions; extending one shared transaction boundary to every compound lifecycle mutation remains planned core work.
Start with:
Understand the model:
- Architecture
- Domain model
- Core improvement roadmap
- Documentation and artifact locations
- Full documentation index
Operate and extend it:
- Operations and validation
- AI-native SDLC controls
- Project upgrades
- Cycle revalidation and issue trackers
- Method Pack reference
- Tool Pack reference
- Pack registries and trust
Executable scenarios live under samples/. They are part of the verification suite and
show the protocol working without requiring live provider credentials.
uv sync --extra dev
uv run python scripts/verify_all.pyContributions must preserve Agora's language, model, provider, and process independence; keep the protocol Markdown-first; and use Conventional Commits. See CONTRIBUTING.md.
Agora is developed by Modern Ash and licensed under the Apache License 2.0, an open-source license.