Garda Agent Orchestrator

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

Without Garda / With Garda

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

npm install -g garda-agent-orchestrator
garda setup

Then give AGENT_INIT_PROMPT.md to your coding agent. 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.

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

Execute task T-001 from TASK.md strictly through all mandatory orchestrator gates.

The active profile (balanced, fast, strict, docs-only) provides the default execution mode; use explicit depth= only as a one-run override.

Mandatory gate order: enter-task-mode -> load-rule-pack -> handshake-diagnostics -> shell-smoke-preflight -> classify-change -> load-rule-pack -> compile-gate -> build-review-context -> required-reviews-check -> doc-impact-gate -> completion-gate

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

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

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.1.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.
• 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 -> test -> pack -> install/invoke, and checks the worktree again before release handoff.
• GitHub Actions CI mirrors the hot path: ci.yml runs typecheck, test, validate:release, and a cross-platform lifecycle smoke that installs from the current workflow branch instead of drifting to the repository default branch.
• Root tsconfig.json extends tsconfig.node-foundation.json, so editors like IntelliJ IDEA or WebStorm can discover the repository without custom setup.

Documentation

Release Background

Garda was not started from scratch in this repository. Earlier versions were developed privately as shell/Python prototypes before being rewritten and consolidated into the current Node/TypeScript implementation. This public repository intentionally starts from the first stable public release, v1.0.0, so the earlier internal incubation history is not reflected in the public commit log.

Recent Changes

• Completed the final TS-only source transition: src/bin/garda.ts now owns the public CLI launcher and bin/garda.js is build-generated only.
• Source checkouts keep consumer install lifecycle scripts disabled; run npm run build explicitly before using the generated launcher and compiled runtime from source.
• Packaging tests now build in isolated fixture repositories, removing cross-test races on shared dist/ state.
• Stabilized the Node gate router for scoped diff, review-context, task-event summary, and completion flows.
• Added root tsconfig.json for standard editor/IDE TypeScript discovery and included it in the published package surface.
• Full tests/node/** baseline now completes cleanly without temp workspace helper noise.
• Compact Command Hints added to agent rules for token-efficient CLI usage.
• E2E smoke tests covering full install/reinit/uninstall lifecycle matrix.
• Token-economy defaults aligned: enabled=true with enabled_depths=[1,2].
• LF line endings enforced for pre-commit hook and bash artifacts on all platforms.
• Parser-aware gate compaction and review-context artifacts for token-economy mode.
• Added update workflow with version check and npm-based update source resolution.
• Completed the runtime cutover to a Node-only lifecycle and gate surface.
• Added npm package CLI with garda, gao, garda-agent-orchestrator aliases.

Important Notes

• garda setup can collect the 6 init answers itself and write runtime/init-answers.json without an agent.
• After CLI setup or update, use AGENT_INIT_PROMPT.md so the agent reuses existing init answers, clarifies language when it cannot recognize it confidently, explicitly confirms which agent entrypoint files are actively used, initializes or refreshes live/docs/project-memory/** from repository evidence, optionally manages built-in skill packs, and finishes with the hard garda agent-init gate.
• Setup and update reports always include the canonical project-memory init/refresh handoff prompt because users may be upgrading from stale or template-seeded memory.
• With a valid runtime/agent-init-state.json, garda status and garda preprompt task surface the state-gated project-memory init/refresh prompt while the state does not yet record both ProjectMemoryInitialized=true and ProjectMemoryValidated=true. Malformed agent-init state is reported as invalid first; rerun garda agent-init after repair so the memory readiness fields can be trusted. Once both flags are true, green-path task startup does not ask for full memory initialization again.
• Optional skills are discovered from the compact live/config/skills-index.json index. After the user selects a built-in pack, it should be installed into live/skills/** without reading the full optional SKILL.md immediately. Full optional skill files should be opened only later, when the selected skill is actually activated for a task or a hard activation rule requires it.
• garda without arguments is now non-destructive and only prints overview/help.
• The public CLI owns the validated runtime surface for lifecycle commands and gate routes.
• Update trust is allowlist-first by default. Any bypass for local paths or non-standard update sources must be explicit via --trust-override --no-prompt, and ordinary CLI flows ignore the legacy GARDA_UPDATE_TRUST_OVERRIDE environment variable.
• Lock diagnostics cover task-event locks under garda-agent-orchestrator/runtime/task-events/*.lock and review-artifact locks under garda-agent-orchestrator/runtime/reviews/*.lock. Use garda doctor --cleanup-stale-locks --dry-run before removing stale lock directories.
• bin/garda.js is a generated launcher compiled from src/bin/garda.ts; repository builds run from dist/src/**/*.js, tests can stage .node-build/src/**/*.js, and packaged installs invoke the same compiled contract from node_modules.
• Root tsconfig.json is the editor-facing entrypoint and simply extends tsconfig.node-foundation.json.
• Installer is non-destructive for existing project files outside managed blocks.
• Commit message format is project-defined; conventional commits are optional.
• For detailed deployment, lifecycle, and configuration information, see the docs/ directory.

Support GARDA

GARDA is an independent open-source project for governed AI coding workflows.

Support helps cover AI tokens, model subscriptions, release validation, documentation, compatibility testing, and maintenance.

• Ko-fi: https://ko-fi.com/gardaworkflow
• Crypto: https://nowpayments.io/donation/garda

License

Apache License 2.0. See LICENSE.

Author

• Dmytro Shubchynskyi
• Email: d.shubchynskyi@gmail.com
• LinkedIn: https://www.linkedin.com/in/shubchynskyi