Gentle-AI v2.9.1 is a configuration layer for the AI coding agents your team already runs, and it is worth a look if you want shared memory, one change workflow, and review evidence instead of six developers prompting six different ways. It is not a drop-in: v2.9.1 is a hotfix, the issue backlog is large, and managed review has documented gaps in at least one runtime. Prove it on your own runtime first.

This is a source and documentation review by Xiang Peng for XP812. It draws on the public repository, its published release notes, and its open issue record as collected on 2026-09-16. Nothing was installed, executed, benchmarked, or deployed for this review, and no statement below is a production endorsement.

key facts at a glance

what gentle-ai actually is

The maintainers describe Gentleman-Programming/gentle-ai as a deterministic engineering environment for the AI coding agent you already use. In practice that means a Go binary plus managed configuration assets that write into agents you already have installed: Pi, OpenCode, Claude Code, Codex, Cursor, VS Code Copilot, Gemini CLI and others, 16 integrations according to the repository README. The project states that it never installs an agent for you.

The named components, again as described by the maintainers: Engram for persistent project memory; Organic Driven Development (ODD) as the everyday workflow; Spec-Driven Development (SDD) as an explicitly chosen formal path with proposal, spec, design and task artifacts; Receipt-Driven Development (RDD) as an opt-in bounded review in which the candidate is frozen before anything reads it; a skills library; optional Context7 MCP; a read-only CodeGraph; a security deny-list that blocks ~/.ssh, .env and credential files; configuration snapshots taken before every write; and gentle-ai doctor as a read-only health report.

Two design claims matter more than the feature list. First, the binary, not a model, owns SDD status and RDD review transitions by reading state from files, so a different agent, model or session is meant to produce the same next valid step. Second, RDD output is informational: the README states that commit, push and release remain the human’s call. If you are looking for an automatic quality gate, this is not one.

what changed in v2.9.1 and what it tells an operator

The v2.9.1 release notes declare no new features and no breaking changes, and keep the review provider contract at 1.2.0. The release is a hotfix for two runtimes. On Claude Code, the notes state that every sdd-* delegation had been denied since v2.8.0 because the SDD dispatch guard minted its only allow path from a record a model-started process could forge; the guard now derives parent-confirmed preflight from the session transcript itself. On OpenCode, review consent no longer stalls when the active question schema exposes multiple but not custom.

Two things follow for operators. First, the fix is a managed-asset change, not only a binary change: the notes require Claude Code users to run gentle-ai sync after upgrading so the rewritten SDD dispatch hook arrives, and OpenCode users to run it for corrected orchestrator instructions. Second, a delegation path was refused across releases in between, which a team experiences as “the agent stopped working” rather than as a version note. The window here was short, with v2.8.0 published 2026-09-13 and v2.9.1 on 2026-09-14, but it shows how tightly this layer tracks other vendors’ agent internals.

maintenance and support signals

The project ships quickly. Across the two days before this review the release list shows v2.8.0 on 2026-09-13, v2.8.1 and v2.8.2 later that day, then v2.9.0 and v2.9.1 on 2026-09-14. Narrow, fast hotfixes are a reasonable sign for a configuration layer that has to follow several agents, but they also mean the surface you standardize on moves.

Against 6,855 stars and 751 forks in the snapshot, the repository carries 1,007 open issues. Two long-running audits, written by contributors rather than by this review, quantify what that backlog contains. Issue #2471, created 2026-08-04, claims that roughly 250 of 438 open issues traced back to 20 root causes, and names three verification holes: a classifier that accepted an execute transition with no runnable command, no test that ran the commands the documentation printed, and a shell end-to-end suite that on pull requests ran only Tier 1 and truncated at the first unguarded failure. Issue #3841, with a baseline frozen 2026-08-28, inventories 702 issues, 189 pull requests and 690 roots, lists P0 items still in flight including an advisory-lock API review and a recovery continuation for managed assets, and states that closed does not mean fixed.

Those are the project’s own numbers from its own point-in-time audits. They are the strongest argument for pinning a version and re-running your own acceptance checks after each upgrade instead of trusting a green result from someone else’s CI.

deployment and upgrade concerns

• Install paths in the README are Homebrew, a curl install script, and go install. Windows is supported only through the Go path; the v2.9.1 notes state that official Windows binary archives and Scoop publication remain unavailable and that Windows upgrades fail closed to Go-based guidance rather than downloading unsigned binaries. A Windows-heavy team should plan for a Go toolchain before anything else.
• Signed release archives exist for linux_amd64, linux_arm64, darwin_amd64 and darwin_arm64, alongside checksums.txt, a minisign signature and a separate provenance asset. If you cannot run your own verification step over those artifacts, the evaluation is not finished.
• gentle-ai sync after every upgrade is part of the operating procedure, not an optional tidy-up. It reconciles the installed binary with managed agent, reviewer and runtime assets, and it is exactly the step that delivers the corrected v2.9.1 Claude Code hook.
• Configuration is written into developers’ agent config directories. v2.9.0 notes that sync now accepts a config root symlinked into a dotfiles repository while still refusing indirection inside that root, so stow-style or symlink-farm setups are supported under specific rules.
• Feature parity is not promised. The README states that each integration uses the agent’s native capabilities, so delegation and RDD review availability differ per agent. Treat every decision as per-runtime rather than per-project.

known limitations and open integration gaps

Two open issues are directly relevant to anyone planning to rely on the review workflow.

Issue #1658, opened 2026-07-22 against v2.1.11 and still open at this snapshot, reports that the managed OpenCode integration has no consumer-owned capture path for external.authorize_recovery. The reporter’s claim is that the lifecycle stops at recovery_authorization_required, the shipped OpenCode plugin only captures reviewer results, and the contract permits no inferred command-line fallback. The issue carries the repository’s bug, high-priority and approved-for-implementation labels.

Issue #2029, opened 2026-07-30 against 2.2.2 on macOS with OpenCode 1.18.9, describes a high-risk managed review of a nested Git repository stalling through two separate integration gaps: reviewer child sessions inheriting the parent working directory, and proof references written in abbreviated form so that native admission rejected them as outside the frozen manifest. The same report notes untracked skill-registry files appearing inside the frozen target during recovery. It is open, labeled as a bug with high priority, and marked as needing a design decision.

Both were filed against earlier versions and both concern OpenCode. Release notes published since then claim related work, with v2.9.0 rewriting OpenCode review transport decoding and v2.9.1 correcting OpenCode consent handling, so the honest statement is that this review cannot tell you whether either issue reproduces on v2.9.1. That is a check to run, not a conclusion to copy.

Two further limits are structural rather than bug-shaped. Review evidence is informational and delivery stays human-owned, so nothing here prevents a merge that a maintainer did not approve. And the everyday ODD path and the formal SDD path are chosen explicitly, because the maintainers state that size, ambiguity and risk alone do not select SDD. A team expecting the tool to impose phase discipline will be disappointed by design.

who should consider gentle-ai

Consider it if you run a small engineering team, roughly three to thirty people, that already pays for more than one coding agent and feels a specific operational cost: decisions re-explained at the start of every session, no memory of earlier choices, and review evidence that varies by whoever asked. The proposition here is a shared AI coding agent configuration, meaning memory, one workflow and one evidence format across agents you have already chosen, on macOS or Linux, with a team able to own a config directory and an upgrade step.

Skip it, or wait, if your constraint is different. Regulated delivery that requires every code path to be gated before merge is the wrong fit, because review is informational. A Windows-only fleet without a Go toolchain should not begin with this release. And a team that needs a quiet, low-churn interface should weigh five releases in two days and decide whether it wants to own that cadence. If you are making a build-versus-adopt call and want a second read on the tradeoffs, XP812’s software development services cover exactly this kind of evaluation and integration work.

questions to answer before you standardize

1. Which agent, and which exact version, will your team run? Parity differs per integration, so a pilot on one runtime proves nothing about another.
2. On v2.9.1, does sdd-* delegation work in your runtime, and does review consent complete? Run it on your real repository layout, including nested repositories and worktrees.
3. Who runs gentle-ai sync after each upgrade, and how do you detect that the binary and the managed assets have drifted apart?
4. What does the frozen candidate actually include in your project, and does the credential deny-list match where your secrets live? That list is a maintainer-stated control, not something this review verified.
5. What is your rollback, given that configuration is written into developers’ agent config directories?
6. When a managed review stalls, who diagnoses it, and what stopping rule turns a stuck lifecycle into a decision instead of another retry?

verdict

Gentle-AI addresses a real problem, teams adopting coding agents without a shared workflow, and it does so in the least lock-in-prone way available: configuring agents you already own rather than replacing them. The maintenance posture is strong for a project this young, with an MIT license, fast iteration, signed artifacts and active self-audit. The risk sits in the same place as the value. The managed workflow layer runs on top of other vendors’ agent internals, it is only as reliable as each individual integration, and the project’s own audits show that verification gaps have shipped before.

Use it, if you use it, as a pinned, per-runtime configuration that you retest on every upgrade, not as infrastructure you assume is stable because it installs quickly.

how i would help you evaluate this

If you are deciding whether a layer like Gentle-AI belongs in your team’s workflow, I can help you scope that decision and then carry it out: choose the runtime, write the acceptance checks your team actually cares about, and integrate the workflow into your existing repositories and release process. The evidence I would need first is specific rather than grand: which agents and versions you run, one representative repository including any nested or worktree layout, how developer machines are configured and imaged, and what your current review and release steps look like. With that in hand I can tell you where this fits, where it does not, and what custom development or ongoing ownership the gap implies. I will not promise an outcome before I have seen your environment, and you can start that conversation on the contact page.

sources

• Gentleman-Programming/gentle-ai repository README (repository)
• Gentle-AI v2.9.1 release notes (release)
• Gentle-AI v2.9.0 release notes (release)
• Issue #2471: the 20 roots behind roughly 250 open issues (issue)
• Issue #3841: complete open-backlog audit and decision ledger (issue)
• Issue #1658: OpenCode recovery authorization capture path (issue)
• Issue #2029: managed review in a nested repository (issue)