Garda Agent Orchestrator

<p align="center"> <img src="docs/assets/garda-github-social-preview.png" alt="Garda - Governed workflows for AI coding agents" /> </p>

Governed workflows for AI coding agents.

Garda supports multiple AI coding agent provider surfaces through one canonical workflow. See Supported Providers for the current provider list, entrypoints, bridge profiles, and known provider-specific limitations.

GARDA = Governed Agent Runtime, Deployment, and Audit.

Website · Quick Start · User Guide · Providers · Architecture · Work Example · CLI Reference · Configuration · Changelog

Watch the 2-minute demo

See how scoped reviews, focused fixes, tests, and completion evidence fit together. The video illustrates an Orders API workflow and includes evidence from an earlier recorded demo task.

Watch on YouTube (English captions) · Garda Studio product page

Without Garda / With Garda

| Without Garda | With Garda | |---|---| | Agent jumps straight into edits | Agent enters a controlled task workflow | | Tests, reviews, and docs checks depend on discipline | Gates run in a defined order | | Completion means whatever the agent claims | Completion is checked before being accepted | | Review context can drift | Review artifacts are required | | No shared audit trail | Task-event history records the workflow | | Each provider needs separate habits | One workflow surface across agents |

Workflow

Task -> enter-task-mode -> load-rule-pack -> preflight -> compile -> review-context -> required reviews -> doc-impact -> completion

Garda does not replace your coding agent. It gives every agent the same controlled path to done.

Why Garda?

AI coding agents are powerful, but in real repositories they can skip steps, lose context, avoid reviews, and mark work as done too early.

Garda adds a governance layer:

• task lifecycle: TODO → IN_PROGRESS → IN_REVIEW → DONE
• mandatory gates: preflight, compile, review, doc-impact, completion
• provider-agnostic rules with documented provider entrypoints and bridge profiles
• auditable task events and review artifacts
• local Node/TypeScript CLI runtime
• token-economy defaults for compact green-path execution

Quick Start

Install Node.js 24 LTS (recommended) or 22.13+ on the Node 22 line, and Git. Open a terminal in the local Git repository you want Garda to manage; run git init first if it is a new project.

npm install -g garda-agent-orchestrator
garda setup

Then give your coding agent the local garda-agent-orchestrator/AGENT_INIT_PROMPT.md file created in your project (preview the prompt). The agent reuses existing init answers, confirms active agent files, initializes or refreshes project memory from repository evidence, offers optional skill packs, and finishes with garda agent-init.

Setup: PASSED with Verify: PENDING_AGENT_CONTEXT means installation is complete but agent initialization is still required; the workspace is not ready for task execution yet.

After garda agent-init passes, pick a task from TASK.md and tell the agent:

Execute task T-001 from TASK.md strictly through the orchestrator. Use `next-step` as the navigator before the first gate, after each suggested command, and after failures.

The active profile (balanced, fast, strict, docs-only) and the TASK.md Profile column provide the default execution mode. Let next-step print the current mandatory command instead of hardcoding gate order in the prompt.

Temporary fallback without global install:

npx -y garda-agent-orchestrator setup

npx runs the package once and does not keep garda or gao in your PATH. If you want persistent commands, install globally.

Key Features

| Feature | Description | |---|---| | Many Provider Surfaces | One canonical workflow with provider-specific entrypoints and bridges; see Supported Providers for the current list | | Mandatory Quality Gates | Preflight → Compile → Review → Doc-Impact → Completion | | Token Economy | Reviewer-context compaction, scoped diffs, gate output filtering — saves 60–100% on green builds | | Task Lifecycle | TODO → IN_PROGRESS → IN_REVIEW → DONE with hash-chain integrity | | Specialist Review Lanes | code, db, security, refactor, api, test, performance, infra, and dependency reviews when the task scope requires them | | Extensible Review Catalog | Guarded custom review lanes, profile states, dependency graphs, immutable task snapshots, and legacy-compatible defaults | | Node Runtime | Public CLI and gate flows run through the Node/TypeScript router with no shell runtime dependency | | Compact Command Hints | Agent rules teach efficient CLI flags for everyday commands |

Supported Providers

The provider list is maintained in docs/providers.md. That page documents current entrypoints, bridge profiles, shared AGENTS.md providers, and Antigravity 2.0 / CLI delegated-review support notes.

CLI Commands

| Command | Description | |---|---| | garda | Safe overview: help + current project status | | garda setup | First-run CLI onboarding without requiring an agent for the 6 answers | | garda agent-init | Hard code-level gate that finalizes agent onboarding | | garda next-step | Show the exact next orchestrator command for a task | | garda status | Short project status snapshot | | garda doctor | Run verify + manifest validation from existing answers | | garda preprompt | Build a read-only task brief with current context and canonical next commands | | garda html | Write a static read-only HTML report with optional snapshots | | garda ui | Start a read-only localhost UI with lazy task details | | garda ui --actions | Start the localhost UI with guarded allow-listed actions that require confirmation | | garda status why-blocked | Explain why blocked or stalled tasks cannot progress, including task-event lock blockers | | garda doctor explain | Print remediation steps for known failure IDs | | garda bootstrap | Bundle-only deploy without install | | garda install | Deploy/refresh orchestrator (requires init-answers.json) | | garda init | Re-materialize live/ from existing answers | | garda reinit | Change init answers without full reinstall | | garda check-update | Compare current deployment with a newer npm package or local source | | garda update | Apply the update workflow directly (--dry-run for preview) | | garda update git | Apply or preview an update from a git repo or local clone | | garda rollback | Roll back to a specific version or restore from the latest rollback snapshot | | garda cleanup | Preview/apply tiered runtime retention and inspect review-artifact policy | | garda repair | Inspect or rebuild runtime indexes, protected manifests, and stale lock state | | garda uninstall | Remove orchestrator while preserving TASK.md by default; queue removal requires explicit --keep-task-file no | | garda skills | List, suggest, add, remove, and validate optional built-in skill packs | | garda profile | List, switch, create, delete, and validate workspace profiles | | garda review-catalog | Inspect, validate, explain, and safely manage built-in/custom review lanes |

Published command names: garda, gao, garda-agent-orchestrator

Full reference: docs/cli-reference.md

Version

• Package: garda-agent-orchestrator
• Current version source of truth: VERSION
• Package manifest versions: package.json, package-lock.json
• Recommended CLI install: npm install -g garda-agent-orchestrator
• Recommended first command: garda setup
• One-off fallback without install: npx -y garda-agent-orchestrator setup
• Install locally only if you want repo-local binaries in node_modules/.bin: npm install garda-agent-orchestrator

Naming

• Package and bundle name: garda-agent-orchestrator
• Published command names: garda, gao, garda-agent-orchestrator
• Launcher path: bin/garda.js

Runtime Baseline

• Node.js 24 LTS is the primary runtime baseline for the public CLI, lifecycle commands, and gate commands. Node.js 22.13+ is also supported as the compatibility runtime line.
• A local Git working tree is required. Garda uses git status and git diff from the local repository to derive task scope, dirty-worktree baselines, zero-diff evidence, protected control-plane drift, and review freshness. The hosting service does not matter: GitHub, GitLab, Bitbucket, a private server, or no remote at all are all acceptable as long as the project is a local Git repository and the git CLI is available.
• 1.4.x compatibility stance: Node 22.13+ is covered by package.json engines, CI matrix coverage, release validation, runtime diagnostics, and documentation. Node 24 remains the primary line.
• Compatibility note: Node 23, Node 22 versions before 22.13.0, and Node 20 or older are outside the tested support matrix. Runtime diagnostics warn for those versions instead of blocking execution solely because of the Node version.
• Compile-first runtime contract: src/**/*.ts is the source of truth, src/bin/garda.ts compiles into the public bin/garda.js launcher, and that launcher executes compiled JavaScript from dist/src/**/*.js or the staged .node-build/src/**/*.js test build. Raw src/**/*.ts files are never executed directly.
• Compiled-only npm package: published tarballs include dist/**, bin/garda.js, templates, metadata, and public documentation, but omit the repository src/** and tests/** trees. Consumer installs do not require TypeScript, devDependencies, or a build step.
• Strict TypeScript means compiler-enforced typing across all maintained code paths: tsconfig.build.json runs strict:true for src/**/*.ts, and the wider repo graph (tsconfig.node-foundation.json / tsconfig.tests.json) covers src/**/*.ts, tests/node/**/*.ts, and scripts/node-foundation/**/*.ts.
• Release validation is explicit: npm run release:preflight runs static readiness, a short test:release-smoke runtime-contract suite, then the full validate:release proof. npm run validate:release still requires a clean tracked/untracked worktree, proves build -> embedded bundle parity when present -> regular tests/coverage -> explicit package smoke -> pack/install/invoke, and checks the worktree again before release handoff.
• GitHub Actions CI mirrors the release hot path with fast quality coverage: ci.yml runs typecheck, focused test shards, validate:release:fast on Linux and Windows, pack/install smoke, and a cross-platform lifecycle smoke that installs from the current workflow branch instead of drifting to the repository default branch. The local release handoff remains stricter: npm run release:preflight ends with the full validate:release proof.
• Root tsconfig.json extends tsconfig.node-foundation.json, so editors like IntelliJ IDEA or WebStorm can discover the repository without custom setup.

| Node.js line | 1.4.x support status | Release/CI contract | |---|---|---| | Node 24 LTS | Official primary runtime | package.json allows >=24.0.0; GitHub Actions typecheck, unit, release validation, and cross-platform smoke run on Node 24. | | Node 22.13+ LTS | Official compatibility runtime | `package.j