📦 Gentleman-Programming/gentle-ai

首次来到这里？请按照 安装 部分完成前置条件和平台对应的二进制命令，然后执行：

# 选择你的 Agent、组件和 Persona
gentle-ai

# 验证安装
gentle-ai doctor

你已经安装了 Claude Code、OpenCode、Cursor 或 Codex。它会编写代码——但会在会话之间遗忘一切，对你的项目如何运作没有自己的理解，也不会提供除你亲自逐行阅读之外的工作检查方式。

**Gentle-AI 是一个生态配置器。**它接管你机器上已有的 Agent 运行时，为其配备持久记忆、规划工作流、精选技能库、MCP 工具服务器、模型路由、面向教学的 Persona，以及可选的基于证据的审查步骤。

之前

“我安装了一个 AI Agent，但它只是一个会写代码的聊天机器人。”

| 之后

Agent 会记住你的决策，遵循项目约定，选择与任务规模相匹配的工作方式，并能为其所作的变更产出可审查的证据。

---|---

• 已经每天都在使用 AI 编程 Agent，并希望它不再每次都从零开始的开发者。
• 希望在不同 Agent 运行时和机器上获得一致 Agent 行为的团队。
• 希望能够验证 Agent 做了什么，而不是相信其总结的任何人。

重要

Gentle-AI **绝不会替你安装 AI Agent。**它只配置已存在的运行时。如果你选择的 Agent 无法被检测到，它会拒绝继续，并打印你需要自行运行的准确命令——不会在你的机器上静默安装软件。

Gentle-AI 会安装一组组件。你可以逐个选择，也可以使用预设。

Engram™ · 推荐 跨会话持久记忆——决策、Bug 修复和上下文会在重启后保留。	Skills · 推荐 当任务匹配时由 Agent 加载的精选编程技能库。
Persona · 可选 面向教学的表达风格（Gentleman 或中性），也可使用你自己的自定义 Persona。	SDD · 可选 Spec-Driven Development——适用于较大功能的规划工作流。
Context7 · 可选 一个获取实时框架和库文档的 MCP 服务器。	Permissions · 可选 安全优先的防护措施，包括针对 ~/.ssh、.env 和凭据文件的拒绝列表。
GGA · 可选 Gentleman Guardian Angel——一个 AI 提供商切换器。	Theme · 可选 可为 Claude Code 和 OpenCode 选择 Gentleman 与 Gentleman-Cute 主题。

预设会为你打包这些组件

预设	包含内容
Dev Stack + Polish full-gentleman	全部组件和全部技能
Dev Stack ecosystem-only	Engram、SDD、Skills、Context7、GGA，以及全部技能
Memory Only minimal	Engram 和 SDD 技能
Custom	由你选择；现有 Persona 和设置保持不变

完整说明：组件、技能与预设。

支持哪些 Agent

Gentle-AI 使用每个 Agent 自己的原生功能进行配置，因此能力会有所不同。委派模型说明该 Agent 能否将工作交给专注的子 Agent，还是在单个对话中完成所有工作。

完整委派可将工作交给专注的子 Agent

Agent	机制	核心功能
Claude Code	Task 工具	子 Agent、输出样式
OpenCode	多模式覆盖层	按阶段进行模型路由
Kilo Code	多模式覆盖层	位于 ~/.config/kilo 的 OpenCode 兼容配置
Gemini CLI	实验性	位于 ~/.gemini/agents/ 的自定义 Agent
Cursor	原生子 Agent	位于 ~/.cursor/agents/ 的 10 个 SDD Agent
VS Code Copilot	runSubagent	并行执行
Codex	原生多 Agent	CLI 原生 TOML 配置；默认启用，并提供单 Agent 回退模式
Antigravity	动态子 Agent	Mission Control 在 SDD 阶段使用 define_subagent + invoke_subagent
Kimi Code	原生自定义 Agent	位于 ~/.kimi 的模块化提示词模板
Kiro IDE	原生子 Agent	原生 ~/.kiro/agents/ + steering 编排
Qwen Code	原生子 Agent	斜杠命令、~/.qwen/commands/、auto_edit 模式
Pi	包管理的子 Agent	一等公民 gentle-pi Harness，具备 Pi 原生 Persona/模型、SDD 和 Engram 记忆
Hermes	delegate_task	临时的全新上下文工作者；YAML MCP 配置和 SOUL.md Persona

单 Agent 在一个对话中完成所有工作

Agent	核心功能
Windsurf	Plan Mode、Code Mode、原生工作流
OpenClaw	工作区优先的 AGENTS.md / SOUL.md，带全局 MCP 配置
Trae	字节跳动桌面应用；~/.trae/skills/ + 操作系统特定规则

**Hermes 必须先手动安装。**Gentle-AI 会检测并配置已有运行时；不会安装 Hermes。

说明

**Pi 不只是被配置，而是由包管理。**选择 Pi 会安装一等公民 gentle-pi Harness，它负责 Pi 原生 Persona 与模型控制、SDD 资源、链路和记忆接入。

说明

本项目取代了现已归档的 Agent Teams Lite。ATL 提供的所有功能均已包含于此，并且具备更好的安装体验、自动更新和持久记忆。

各 Agent 的详细信息与完整功能矩阵：Agents。

第 1 步——检查前置条件

要求	原因
Node.js 18+ 和 npm	所有平台上的 gentle-ai install 都需要。缺少任一项时会发出警告并打印发行版特定提示——不会替你安装它们。
Git 2.38+	用于项目检测和审查范围界定。
Go 1.25.10+	Windows 以及从源码安装的任何环境均需要。
你的 AI Agent	已安装且位于你的 PATH 中。Gentle-AI 配置它；不会安装它。

各发行版提示：Prerequisites。

第 2 步——安装二进制文件

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash

Windows（PowerShell）

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest

警告

**在 Windows 上，请从源码安装——这是受支持的路径。**Windows 是经过完整测试的平台——完整测试套件会在其 CI 通道上运行——但目前没有官方 Windows 二进制分发和 Scoop。Windows 安装与升级需要 Go 1.25.10+；若不满足条件，将以安全失败方式仅提供源码安装指引；绝不会下载未经签名的 Gentle AI 可执行文件，或执行远程更新脚本。

预期结果：gentle-ai version 会输出版本号。

第 3 步——配置你的 Agent

启动交互式 TUI：

选择你的 Agent、组件（或预设）和 Persona。

**预期结果：**Gentle-AI 会将配置文件写入每个已选 Agent 的全局配置目录——包括系统提示词、技能、SDD Agent、Persona 文件和 MCP 条目。会先为你此前的配置创建快照（参见 Backups）。

**预期结果：**获得一份只读健康报告，覆盖工具二进制文件、state.json、Engram 可达性和磁盘空间。它还会对损坏的受管路径进行分类——悬空的祖先符号链接、配置符号链接循环以及不可读取的受管文件。不会修改任何内容。任何时候发现异常，都可以运行此检查。

现在你已经可以像平常一样使用 Agent。

Agent 如何决定工作方式

这是核心理念，适用于每一个已配置的 Agent——即使你从不启用 SDD 或审查。

**你提出一个目标。Agent 会选择实现该目标的最小路径。**它不会因为一个任务“看起来很大”就升级流程仪式。

情况	Agent 的行为
理解需要查看 1–3 个文件，或者已理解单项机械式变更	直接内联——直接完成工作
理解需要查看 4 个以上文件、阅读是写入前的准备、需要广泛研究，或会修改 2 个以上非平凡文件	委派式直接处理——一个范围明确的探索者或一个专注的编写者，不产生额外产物
持久化的提案、规格、设计和任务产物能够实质性降低真实歧义	提供可选 SDD——仅在你提出要求或接受提案后才会选用
提交、推送、PR 或发布	遵循常规仓库策略

三个值得牢记的规则：

• **规模绝不决定是否使用 SDD。**文件数量、变更行数和感知风险本身都不会强制采用更重的路径。只有明确请求或被接受的提案才会触发。
• **路由不决定审查强度。**二者是独立选择。
• **按操作划分的工作者不会改变路径。**在全新的工作者中运行测试、构建或安装，仍会保持选定路径不变。

深入了解：Organic Implementation Routing。

可选：Spec-Driven Development（SDD）

SDD 是一个**适用于较大功能的规划工作流。**Agent 不会直接跳入代码，而是先探索代码库，提出一个由你批准的方法，编写需求，设计架构，将其拆分为有序任务，实施，然后根据已达成的一致内容独立验证结果。

当工作存在足够多的歧义，而持久的书面产物——提案、规格、设计、任务列表——确实能够减少这些歧义时，应使用它。对于 Bug 修复或小功能，它属于额外负担。

你不需要学习各阶段。只需说 “use SDD”，Agent 就会启动工作流；或者在 Agent 提供该选项时接受它。你需要在决策点进行审查和批准。

说明

在 Claude Code 中，每个 SDD 命令均使用 /gentle-sdd-* 前缀——例如 /gentle-sdd-new 和 /gentle-sdd-continue。其他运行时保留不带此前缀的 /sdd-* 名称。

SDD 产物可在安装时选择存放于三个位置：

存储位置	最适合
Engram	跨会话记忆，仓库中不产生文件
OpenSpec	与代码一起提交并进行版本管理的文件
Hybrid	两者兼有

你声明的存储位置具有权威性：阶段 Agent 会获得应读取的位置，绝不会猜测产物存放在哪里。

• **研究路径。**在 Explore 之后，如果提案需要外部证据，你可以立即选择 SDD Research。这条可选路径要求明确授予文档或开放网络访问权限，并记录带有来源映射、可审计的证据。选择后，Research 必须在 Propose 之前完成。
• **严格 TDD。**启用 Strict TDD 后，SDD apply 会以测试优先方式工作，SDD verify 会在通过前审计 RED/GREEN 证据。
• **独立于审查。**SDD status v2 运行时状态独立于审查。没有任何审查绑定、回执或门禁会控制 SDD Archive 或交付；常规仓库策略仍然是交付的权威。

SDD 周期的内部工作方式

flowchart TD
    A["User: sdd-new / sdd-explore<br/>(gentle-sdd-* in Claude Code)"] --> B["Explore<br/>investigate codebase and approaches"]
    B --> BR{"External research<br/>selected?"}
    BR -->|"yes"| BX["Research<br/>auditable external evidence<br/>exact grant · source mappings"]
    BR -->|"no"| C["Propose<br/>intent · scope · approach"]
    BX --> C
    C --> D{"User approves<br/>the proposal?"}
    D -->|"no"| B
    D -->|"yes"| E["Spec<br/>requirements + scenarios"]
    E --> F["Design<br/>architecture decisions"]
    F --> G["Tasks<br/>ordered deliverable checklist"]
    G --> H["Apply<br/>sub-agent implements against specs<br/>(sdd-attempt acquire/settle · CAS · budgets)"]
    H --> Q["Verify<br/>independent verification against<br/>spec · design · tasks"]
    Q -->|"passes"| R["Archive<br/>merge delta-specs · close the cycle"]
    Q -->|"fails"| H
    Q -.->|"optional, informational"| I["RDD review offer"]

    subgraph RDD["RDD — same machine as the organic route"]
        I --> J{"Risk"}
        J -->|"low"| K["Structural readback"]
        J -->|"medium / high"| L["1 lens or 4R + consent"]
        L --> M{"Severe findings?"}
        M -->|"yes"| N["One bounded correction<br/>+ fix validator"]
        M -->|"no"| O["Review outcome: approved<br/>(informational)"]
        K --> O
        N -->|"validates"| O
        N -->|"fails"| P["Escalated → recover"]
        O --> AK["review.acknowledge-approved<br/>only the exact acknowledgement<br/>burns/closes the lineage"]
    end

    R --> S["Ordinary repository policy"]
    S --> T["Commit → Push → PR"]

    style O fill:#2D4F67,color:#fff
    style P fill:#B8860B,color:#fff
    style T fill:#2D4F67,color:#fff

加载中

参考资料：Intended Usage 和 OpenSpec Config。

可选：Receipt-Driven Development（RDD）

重要

**RDD 为主动选择功能，默认关闭。**在你运行 gentle-ai review mode enable --scope global 之前，以下内容均不会发生。

Agent 告诉你“我修好了，测试也通过了”。除了亲自阅读整个 diff 外，你无法检查这一说法。RDD 用系统能够独立推导的证据替代 Agent 的叙述。

你需要了解六个术语。每一个都建立在前一个之上：

术语	含义
Candidate	正在审查的精确字节集合——一项特定变更，没有其他内容
Freeze	在开始时锁定这些字节，确保审查者与代码不会在审查过程中发生偏移
Lens	一个专注的审查视角。四个规范视角是 Risk、Resilience、Readability 和 Reliability（“4R”）
Correction	最多进行一轮有边界的修正

First time here? Follow Install for prerequisites and the platform-specific binary command, then:

# Pick your agents, components and persona
gentle-ai

# Verify the installation
gentle-ai doctor

Table of contents

You installed Claude Code, OpenCode, Cursor or Codex. It writes code — but it forgets everything between sessions, has no opinion about how your project works, and gives you no way to check its work beyond reading every line yourself.

Gentle-AI is an ecosystem configurator. It takes the agent runtime already on your machine and equips it with persistent memory, a planning workflow, a curated skill library, MCP tool servers, model routing, a teaching-oriented persona, and an optional evidence-based review step.

Before

"I installed an AI agent, but it's just a chatbot that writes code."

| After

The agent remembers your decisions, follows your project's conventions, picks a working style that matches the size of the task, and can produce reviewable evidence for what it changed.

---|---

• Developers who already use an AI coding agent daily and want it to stop starting from zero.
• Teams that want consistent agent behavior across different agent runtimes and machines.
• Anyone who wants to verify what an agent did instead of trusting its summary.

Important

Gentle-AI never installs an AI agent for you. It configures runtimes that are already present. If you select an agent it cannot detect, it refuses and prints the exact command you'd run yourself — it will not silently install software on your machine.

Gentle-AI installs a set of components. You pick them individually, or take a preset.

Engram™ · Recommended Persistent memory across sessions — decisions, bug fixes, and context survive restarts.	Skills · Recommended A curated library of coding skills the agent loads when the task matches.
Persona · Optional A teaching-oriented voice (Gentleman or neutral), or your own custom persona.	SDD · Optional Spec-Driven Development — a planning workflow for substantial features.
Context7 · Optional An MCP server that fetches live framework and library documentation.	Permissions · Optional Security-first guardrails, including a deny list for ~/.ssh, .env, and credential files.
GGA · Optional Gentleman Guardian Angel — an AI provider switcher.	Theme · Optional Selectable Gentleman and Gentleman-Cute themes for Claude Code and OpenCode.

Presets bundle these for you

Preset	Includes
Dev Stack + Polish full-gentleman	Every component and every skill
Dev Stack ecosystem-only	Engram, SDD, Skills, Context7, GGA + all skills
Memory Only minimal	Engram and SDD skills
Custom	You choose; existing persona and settings stay untouched

Full breakdown: Components, Skills& Presets.

Which agents it works with

Gentle-AI configures each agent using that agent's own native features, so capabilities differ. Delegation model tells you whether the agent can hand work to focused sub-agents or runs everything in one conversation.

Full delegation can hand work to focused sub-agents

Agent	Mechanism	Key feature
Claude Code	Task tool	Sub-agents, output styles
OpenCode	Multi-mode overlay	Per-phase model routing
Kilo Code	Multi-mode overlay	OpenCode-compatible config in ~/.config/kilo
Gemini CLI	Experimental	Custom agents in ~/.gemini/agents/
Cursor	Native subagents	10 SDD agents in ~/.cursor/agents/
VS Code Copilot	runSubagent	Parallel execution
Codex	Native multi-agent	CLI-native TOML config; enabled by default with solo-agent fallback
Antigravity	Dynamic subagents	Mission Control uses define_subagent + invoke_subagent for SDD phases
Kimi Code	Native custom agents	Modular prompt templates in ~/.kimi
Kiro IDE	Native subagents	Native ~/.kiro/agents/ + steering orchestration
Qwen Code	Native sub-agents	Slash commands, ~/.qwen/commands/, auto_edit mode
Pi	Package-managed subagents	First-class gentle-pi harness with Pi-native persona/models, SDD, and Engram memory
Hermes	delegate_task	Ephemeral fresh-context workers; YAML MCP config and SOUL.md persona

Solo-agent runs everything in one conversation

Agent	Key feature
Windsurf	Plan Mode, Code Mode, native workflows
OpenClaw	Workspace-first AGENTS.md / SOUL.md with global MCP config
Trae	Desktop app by ByteDance; ~/.trae/skills/ + OS-specific rules

Hermes must be installed manually first. Gentle-AI detects and configures the existing runtime; it does not install Hermes.

Note

Pi is package-managed, not just configured. Selecting Pi installs the first-class gentle-pi harness, which owns Pi-native persona and model controls, SDD assets, chains, and memory wiring.

Note

This project supersedes Agent Teams Lite (now archived). Everything ATL provided is included here with better installation, automatic updates, and persistent memory.

Per-agent details and the complete feature matrix: Agents.

Step 1 — Check prerequisites

Requirement	Why
Node.js 18+ and npm	Required by gentle-ai install on every platform. It warns if either is missing and prints a distro-specific hint — it does not install them for you.
Git 2.38+	Used for project detection and review scoping.
Go 1.25.10+	Required on Windows, and anywhere you install from source.
Your AI agent	Already installed and on your PATH. Gentle-AI configures it; it does not install it.

Per-distro hints: Prerequisites.

Step 2 — Install the binary

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash

Windows (PowerShell)

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest

Warning

On Windows, install from source — this is the supported path. Windows is a fully tested platform — the complete suite runs on its CI lane — but official Windows binary distribution and Scoop are unavailable. Windows installation and upgrades require Go 1.25.10+ and fail closed to source-install guidance; they never download an unsigned Gentle AI executable or execute a remote update script.

Expected result: gentle-ai version prints a version number.

Step 3 — Configure your agents

Launch the interactive TUI:

Select your agent(s), your components (or a preset), and your persona.

Expected result: Gentle-AI writes config files into each selected agent's global config directory — system prompts, skills, SDD agents, persona files and MCP entries. Your previous configs are snapshotted first (see Backups).

Expected result: a read-only health report covering tool binaries, state.json, Engram reachability and disk space. It also classifies broken managed paths — dangling ancestor symlinks, config symlink loops and unreadable managed files. Nothing is modified. Run this any time something looks wrong.

You are now ready to use your agent normally.

How your agent decides how to work

This is the core idea, and it applies to every configured agent — even if you never enable SDD or review.

You ask for an outcome. The agent picks the smallest route that gets there. It does not escalate ceremony because a task "feels big".

Situation	What the agent does
Understanding needs 1–3 files, or one mechanical change is already understood	Direct inline — just does the work
Understanding needs 4+ files, reading prepares a write, broad research is needed, or 2+ non-trivial files change	Delegated direct — one narrow explorer or one focused writer, no extra artifacts
Durable proposal, spec, design and task artifacts would materially reduce real ambiguity	Offers optional SDD — selected only after you ask or accept the proposal
Commit, push, PR, or release	Follows ordinary repository policy

Three rules worth internalizing:

• Size never selects SDD. File count, changed lines and perceived risk never force the heavier route on their own. Only an explicit request or an accepted proposal does.
• Routing does not decide review strength. They are independent choices.
• Per-action workers don't change the route. Running tests, builds or installs in a fresh worker keeps the selected route intact.

Deep dive: Organic Implementation Routing.

Optional: Spec-Driven Development (SDD)

SDD is a planning workflow for substantial features. Instead of jumping straight into code, the agent explores the codebase, proposes an approach you approve, writes requirements, designs the architecture, breaks it into ordered tasks, implements, then independently verifies the result against what was agreed.

When the work is ambiguous enough that durable written artifacts — a proposal, a spec, a design, a task list — would genuinely reduce that ambiguity. For a bug fix or a small feature, it's overhead.

You don't learn the phases. Say "use SDD" and the agent starts the workflow, or accept it when the agent offers. You review and approve at the decision points.

Note

In Claude Code, every SDD command uses the /gentle-sdd-* prefix — for example, /gentle-sdd-new and /gentle-sdd-continue. Other runtimes keep the bare /sdd-* names.

SDD artifacts can live in three places, chosen at install time:

Store	Best for
Engram	Cross-session memory, no files in the repo
OpenSpec	Versioned files committed alongside your code
Hybrid	Both

The store you declare is authoritative: phase agents are handed the locations to read and never guess where artifacts live.

• Research lane. Immediately after Explore, you can select SDD Research when the proposal needs external evidence. This optional lane requires an exact documentation or open-web grant and records auditable evidence with source mappings. Once selected, Research must finish before Propose.
• Strict TDD. When Strict TDD is active, SDD apply works test-first, and SDD verify audits the RED/GREEN evidence before it passes.
• Independent from review. SDD status v2 runtime state is independent from review. No review binding, receipt or gate controls SDD Archive or delivery; ordinary repository policy remains authoritative for delivery.

How the SDD cycle works internally

flowchart TD
    A["User: sdd-new / sdd-explore<br/>(gentle-sdd-* in Claude Code)"] --> B["Explore<br/>investigate codebase and approaches"]
    B --> BR{"External research<br/>selected?"}
    BR -->|"yes"| BX["Research<br/>auditable external evidence<br/>exact grant · source mappings"]
    BR -->|"no"| C["Propose<br/>intent · scope · approach"]
    BX --> C
    C --> D{"User approves<br/>the proposal?"}
    D -->|"no"| B
    D -->|"yes"| E["Spec<br/>requirements + scenarios"]
    E --> F["Design<br/>architecture decisions"]
    F --> G["Tasks<br/>ordered deliverable checklist"]
    G --> H["Apply<br/>sub-agent implements against specs<br/>(sdd-attempt acquire/settle · CAS · budgets)"]
    H --> Q["Verify<br/>independent verification against<br/>spec · design · tasks"]
    Q -->|"passes"| R["Archive<br/>merge delta-specs · close the cycle"]
    Q -->|"fails"| H
    Q -.->|"optional, informational"| I["RDD review offer"]

    subgraph RDD["RDD — same machine as the organic route"]
        I --> J{"Risk"}
        J -->|"low"| K["Structural readback"]
        J -->|"medium / high"| L["1 lens or 4R + consent"]
        L --> M{"Severe findings?"}
        M -->|"yes"| N["One bounded correction<br/>+ fix validator"]
        M -->|"no"| O["Review outcome: approved<br/>(informational)"]
        K --> O
        N -->|"validates"| O
        N -->|"fails"| P["Escalated → recover"]
        O --> AK["review.acknowledge-approved<br/>only the exact acknowledgement<br/>burns/closes the lineage"]
    end

    R --> S["Ordinary repository policy"]
    S --> T["Commit → Push → PR"]

    style O fill:#2D4F67,color:#fff
    style P fill:#B8860B,color:#fff
    style T fill:#2D4F67,color:#fff

Loading

Reference: Intended Usage and OpenSpec Config.

Optional: Receipt-Driven Development (RDD)

Important

RDD is opt-in and off by default. Nothing below happens until you run gentle-ai review mode enable --scope global.

An agent tells you "I fixed it and the tests pass." You have no way to check that claim except reading the whole diff yourself. RDD replaces agent narration with evidence the system can derive independently.

You need six terms. Each builds on the last:

Term	Meaning
Candidate	The exact set of bytes being reviewed — one specific change, nothing else
Freeze	Locking those bytes at the start, so reviewers and the code can't drift apart mid-review
Lens	One focused reviewer perspective. The four canonical ones are Risk , Resilience , Readability and Reliability ("4R")
Correction	At most one bounded round of fixes for severe findings — there is no loop-until-clean
Outcome	The result of the review. It is informational : it records evidence, it does not authorize or block anything
Acknowledgement	The explicit confirmation that your agent received the outcome. Until it runs, the review is approved but not finished

Once implementation finishes, RDD freezes the candidate and picks review effort from evidence, not from size :

Risk (frozen at start)	Review performed
Low	Structural readback — 0 lenses, silent. A passive documentation change is approved right at the start
Medium	1 focus lens, with consent
High	All four lenses (4R), with consent and a cost forecast

If reviewers find severe findings caused by the candidate itself, RDD permits one bounded correction, then a read-only validator checks it. Pre-existing findings become follow-ups, not blockers.

Approval waits to be acknowledged

In stablev2.7.0, a review does not end when it is approved. It ends when your agent confirms it received that approval.

Why this exists: previously, approval destroyed its own authority and returned a response. If that response never reached the host — a crash, a dropped connection — the review was over and nothing said so.

Final approval creates an exact review.acknowledge-approved operation carrying a one-time token. Only running that exact acknowledgement burns/closes the lineage. This is handled by your agent, not typed by you, but it explains two behaviors you may notice:

• Re-entering a review is safe. Asking for status again returns the same operation, arguments, token and revision — it does not start a new review.
• A stale or repeated acknowledgement is refused and leaves no successor lineage or partial state.

If a host decodes the acknowledgement but never runs it, the review stays approved and cannot be closed — by design, rather than silently vanishing.

The review hands back its own next command

Re-entering a frozen review used to be described in prose, which could drift from what the CLI accepted.

Stablev2.7.0 carries that knowledge in the protocol instead of prose. A negotiated START returns a gentle-ai.review-integration.start/v4 envelope whose next_transition contains the complete command that re-enters the transaction. Your agent runs it verbatim rather than reconstructing it.

The practical rule, and the one worth knowing even if you never read an envelope: the agent should run the command the provider returned, never one assembled from a description of it. You can check which protocol version your build speaks with:

gentle-ai review capabilities --contract gentle-ai.review-integration/v2

Caution

Review never governs delivery. Commit, push, PR and release stay separate human decisions under your ordinary repository policy — whether RDD is on or off. When it's off, delivery reports disabled/unmanaged; it never fabricates an approval.

From the command line:

gentle-ai review mode status  --cwd .   # read-only; changes nothing
gentle-ai review mode enable --scope global --cwd .
gentle-ai review mode disable --cwd .

Or from the interactive TUI: run gentle-ai and open Receipt-Driven Development , which offers the same global controls.

Rules worth knowing:

• With no source expressing an opinion, the effective mode is off, reported as decided by default.
• Off always wins. Any global or clone-local disabled source turns review off.
• A clone can opt out with --scope clone, but cannot force review on. --scope global is the only way in.
• Enabling applies to future candidates only. Declining a single review prompt does not change the mode.
• --scope global works from any directory, including one that is not a Git repository. A workspace that is not versioned yet gets a local Git bootstrap before its first review, rather than a refusal.

How the review lifecycle works internally

The organic route, with RDD entering at the end over the frozen candidate:

flowchart TD
    A["User requests a change<br/>(Claude Code · OpenCode · Codex...)"] --> B{"Implementation<br/>route"}
    B -->|"decide/verify<br/>1–3 files"| C["Direct inline"]
    B -->|"4+ file exploration<br/>or 2+ non-trivial writes"| D["Delegated direct<br/>(one bounded worker)"]
    C --> E["Implementation + tests"]
    D --> E
    E --> F{"RDD enabled?<br/>(user-owned, opt-in)"}
    F -->|"off (default)"| Z["Ordinary delivery<br/>reports disabled/unmanaged"]
    F -->|"on (explicitly enabled)"| G["review status --next-transition<br/>(provider-owned negotiated route)"]
    G --> H{"Risk frozen<br/>at START"}
    H -->|"low"| I["Structural readback<br/>0 lenses · silent"]
    H -->|"medium"| J["1 focus lens<br/>+ consent"]
    H -->|"high"| K["Canonical 4R + consent + forecast<br/>Risk · Resilience · Readability · Reliability"]
    J --> L["Reviewers inspect the immutable candidate<br/>(review inspect-candidate)"]
    K --> L
    L --> M{"Severe candidate-caused<br/>findings?"}
    I --> N["Review outcome: approved<br/>(informational)"]
    M -->|"no"| N
    M -->|"yes"| O["One bounded correction<br/>(frozen budget)"]
    O --> P["Fix validator<br/>(read-only, immutable trees)"]
    P -->|"passes"| N
    P -->|"fails with evidence"| Q["Escalated"]
    P -->|"no access to the diff"| R["Inconclusive: attempt not<br/>consumed, capture again"]
    R --> P
    Q --> S["review recover<br/>(authorized successor)"]
    N --> AK["review.acknowledge-approved<br/>exact one-time token · only this<br/>burns/closes the lineage"]
    AK --> T["Ordinary repository policy"]
    T --> U["Commit → Push → PR"]
    Z --> U

    style N fill:#2D4F67,color:#fff
    style AK fill:#2D4F67,color:#fff
    style Q fill:#B8860B,color:#fff
    style U fill:#2D4F67,color:#fff

Loading

Native review transitions own repository identity, candidate scope, lifecycle transitions and safe continuations. When scope changes or an operation is interrupted, use provider-owned status and recovery — never infer authority from agent narration. Compact receipts, FINALIZE and delivery gates are retired. Historical compatibility reads may remain, but they never regain authority; review validate and gate compatibility surfaces are unmanaged and never govern delivery.

Technical references: Organic RDD architecture, Review Authority Threat Model, Review Integration Contract.

The mental model in one sentence: trust what the system can derive, not what the agent says. Chapter 21 — Verifiable Trust explains why.

Refresh the binary and its managed agent assets together :

gentle-ai upgrade
gentle-ai sync

Important

sync is not optional after an upgrade. If you replace the gentle-ai binary by any means, run gentle-ai sync to refresh the managed assets it writes into your agents. See the sync and upgrade reference.

Whatsync writes in v2.7.0:

• Usage telemetry, enrollment first. The first install, update, or sync after this upgrade prints a one-line notice and sends nothing; later runs send closed-enum statistics only (version, OS, architecture, installed agents and components, activity counters). No paths, repository names, usernames, hostnames, or IP addresses. Turn it off with gentle-ai telemetry disable, DO_NOT_TRACK, GENTLE_AI_TELEMETRY=0, or CI=true; see the Telemetry section below.

Whatsync writes in v2.6.0:

• Claude Code review hooks. Stop and SessionStart entries are written into ~/.claude/settings.json as managed entries. They remind the agent to preflight a review once per session candidate, and stay silent when review mode is off or the worktree is clean. uninstall removes them and preserves every hook it does not own.
• Pi system prompt cleanup. Stale managed blocks left by older builds are stripped from ~/.pi/agent/APPEND_SYSTEM.md. The file is preserved; only the blocks Gentle-AI wrote are removed.
• Only the agents you selected. sync derives its agent set from the agents recorded at install time, not from what it finds on disk. If you relied on sync writing into an agent you never selected, run gentle-ai and select it first.

Every install, sync and upgrade automatically snapshots your config files. Backups are compressed (tar.gz), deduplicated (identical configs are not re-backed up) and auto-pruned (the 5 most recent are kept). Pin important backups via the TUI (p key) to protect them from pruning.

Restoring a snapshot: Backup& Rollback Guide.

We count how many installs are active and which features (agents, components, receipt-driven development) are actually used, so we know what is worth maintaining. Nothing else.

What is sent, per event:

• a random install id (a UUID generated locally; it identifies the installation, not a person or a machine)
• the gentle-ai version
• OS and CPU architecture
• the list of agents and components you selected
• whether receipt-driven development is on
• on heartbeats only, a handful of counters: syncs, SDD phase runs, and reviews approved / corrected / escalated

One install event is sent per installation, and at most one heartbeat per day — triggered by install, update, sync, finishing a native review, or finishing an SDD phase, whichever comes first.

What is never sent: repository names, file paths, code, diffs, prompts, reviewer output, usernames, hostnames, e-mail addresses, or IP addresses (the collector does not store the sender's address either).

See the exact payload before anything leaves your machine with gentle-ai telemetry preview --json. The first run only prints a notice and sends nothing; the first real event goes out starting from the next run.

Turn it off with gentle-ai telemetry disable, or DO_NOT_TRACK set to anything but 0 / GENTLE_AI_TELEMETRY=0. CI or GITHUB_ACTIONS set to anything but 0/false disables it automatically, and builds without a release identity (dev, 0.0.0-dev) never send. gentle-ai telemetry status shows the deciding source.

It goes to a collector we run ourselves, whose source is in this repository (cmd/gentle-telemetry). Raw events are kept for 90 days, then only aggregated counts remain. Full contract and schema: Telemetry.

Release channels and version policy

There are two current channels. Install @latest unless you are deliberately testing unreleased development code.

Channel	Current	Install
Stable	v2.7.0	go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@latest
Development	main	go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@main

Verify with gentle-ai version after any of them.

Use @main only to test changes that are not part of a release. The managed installer tracks a channel's latest version and does not accept an arbitrary release pin — use go install when you need an exact version.

About the/v2 suffix: Go requires it for major version 2 and above. Releases before v2.0.0 use the unsuffixed import path.

Stablev2.7.0 publishes six archives under a signed checksum manifest: four platform .tar.gz archives for macOS and Linux (amd64 and arm64), the provider-contract archive, and the release-provenance archive. checksums.txt covers all six and is authenticated by checksums.txt.minisig.

Receipt-Driven Development became the supported stable path in v2.2.0; the negotiated public review contract was published in v2.1.6.

Alternative install methods

Homebrew (macOS / Linux)

brew tap gentleman-programming/tap
brew trust --formula gentleman-programming/tap/gentle-ai  # one-time, if Homebrew requires trust
brew install gentle-ai

To install several tools from this tap, run brew trust gentleman-programming/tap instead. That broader option trusts all current and future formulas, casks and external commands published in the tap.

Scoop (Windows) — temporarily unavailable while official Windows binary distribution is held for public-trust Authenticode signing. Use the Windows go install command above.

Beta channel (tracksmain) — requires Go 1.25.10+:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/Gentleman-Programming/gentle-ai/main/scripts/install.sh | bash -s -- --channel beta

# Windows (PowerShell)
$env:GENTLE_AI_CHANNEL="beta"; go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@main

To update a beta installation later, preserve the channel — both installers default to stable:

# macOS / Linux
GENTLE_AI_CHANNEL=beta gentle-ai upgrade

# Windows (PowerShell)
$env:GENTLE_AI_CHANNEL="beta"; gentle-ai upgrade

If a manual go install ...@main does not pick up recent commits because proxy.golang.org is stale, bypass it:

GOPROXY=direct go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@main
# PowerShell
$env:GOPROXY="direct"; go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@main

Installing to one project instead of globally

By default, gentle-ai install writes agent-scoped files to each selected agent's global config directory. To keep the Gentleman stack isolated to a single project:

gentle-ai install --scope=workspace

Workspace scope covers agent-scoped files — system prompts, skills, SDD agents and persona files. Global-only integrations remain global by design.

Verifying a release signature manually

Stable channel — Minisign. Stable v2.7.0 publishes six archives: four macOS/Linux platform archives, the provider-contract archive, and the release-provenance archive. All six are covered by an authenticated checksums.txt. The built-in upgrader verifies its Minisign signature, its exact Gentleman-Programming/gentle-ai + release-tag binding, and the selected platform archive checksum before replacing the installed binary. Release archives are capped at 128 MiB , including chunked or unknown-length responses. Missing, oversized, malformed, untrusted or placeholder key material fails closed without changing the installed binary.

To verify yourself, obtain the production public-key payload and fingerprint from a maintainer-controlled channel, then download checksums.txt and checksums.txt.minisig from the same release:

minisign -VQm checksums.txt -x checksums.txt.minisig -P "$GENTLE_AI_MINISIGN_PUBLIC_KEY"
# Expected output: repo=Gentleman-Programming/gentle-ai;tag=vX.Y.Z
sha256sum --check --strict --ignore-missing checksums.txt

Do not bootstrap trust from a public key downloaded only beside the artifacts it verifies. See Release signing and key rotation.

Provider contract bundle. Stable v2.7.0 publishes gentle-ai-review-provider-contract-1.2.0.tar.gz. Verify and inspect it from the tagged source:

go run ./internal/providercontractbundlecmd verify --archive <bundle>
tar -tzf <bundle>

Release provenance bundle. gentle-ai-release-provenance-v1.tar.gz carries the stable release provenance materials and is covered by the same signed checksums.

Reviewing only what is staged (monorepos)

In a monorepo or shared worktree, review exactly what is in the Git index:

git add apps/my-service
git diff --cached
gentle-ai review start --projection staged

The staged projection freezes the complete existing index , including paths staged earlier. It starts a review but does not itself produce an approved outcome or authorize delivery; unstaged and untracked worktree content is excluded. The default workspace projection reviews the complete workspace, and an existing authority is never auto-converted between projections.

Details: review authority threat model.

OpenCode: assigning different models per SDD phase

Use a powerful model for design, a fast one for implementation, a cheap one for exploration. OpenCode uses gentle-orchestrator as the base SDD conductor; generated named profiles appear as sdd-orchestrator-{name}.

# Via CLI
gentle-ai sync --profile cheap:openrouter/qwen/qwen3-30b-a3b:free
gentle-ai sync --profile-phase cheap:sdd-design:anthropic/claude-sonnet-4-20250514

# Or via TUI: gentle-ai → "OpenCode SDD Profiles" → Create

After creating a profile, open OpenCode and press Tab to switch between gentle-orchestrator and your custom profiles.

What you need	Use this
Default SDD conductor	gentle-orchestrator
Legacy configs	sdd-orchestrator is migrated to gentle-orchestrator on sync
Named model profiles	sdd-orchestrator-cheap, sdd-orchestrator-premium, etc.

Full guide: OpenCode SDD Profiles.

Using Engram memory from the terminal

Your agent manages memory automatically — you don't need these. But when you want to look:

engram projects list          # See all projects with memory counts
engram projects consolidate   # Fix name drift ("my-app" vs "My-App")
engram search "auth bug"      # Find a past decision from the terminal
engram tui                    # Visual memory browser
engram sync                   # Export project memories to .engram/ for git tracking
engram sync --import          # Import memories after cloning a repo with .engram/

Full reference: Engram Commands.

Command reference

gentle-ai                     # Launch the interactive TUI
gentle-ai install             # Configure AI coding agents on this machine
gentle-ai uninstall           # Remove Gentle AI managed files
gentle-ai sync                # Sync agent configs and skills to the current version
gentle-ai update              # Check for available updates
gentle-ai upgrade             # Apply updates to managed tools
gentle-ai restore             # Restore a config backup
gentle-ai doctor              # Run ecosystem health diagnostics
gentle-ai version             # Print version
gentle-ai skill-registry refresh
gentle-ai review mode <enable|disable|status>
gentle-ai review capabilities --contract gentle-ai.review-integration/v2

Run gentle-ai help for the complete surface, including SDD orchestration and review lifecycle subcommands.

Your task	Start here
Understand the Gentle-AI mental model	Intended Usage
Choose direct, delegated, or optional SDD routing	Organic Implementation Routing
Plan substantial work with SDD	Intended Usage and OpenSpec Config
Configure a supported agent	Agents for the feature matrix and per-agent notes
Use the Pi package harness	Pi Agent for packages, Pi-native commands, models, and troubleshooting
Configure OpenCode phase models	OpenCode SDD Profiles
Review or deliver a change safely	Review Integration Contract, Review Authority Threat Model, and Chapter 21 — Verifiable Trust
Find or share persistent context	Engram Commands
Refresh or troubleshoot an installation	Usage, Backup & Rollback, and Platforms
Extend or contribute to Gentle AI	Codebase Guide, Components, Skills & Presets, Skill Registry, and Architecture & Development
Understand how agent behavior is tested	Testing Agents Deterministically
Understand or opt out of usage telemetry	Telemetry

Community

This project gets better when the community builds on top of it.

Community integrations

• sub-agent-statusline — optional OpenCode TUI plugin that shows sub-agent activity, status, elapsed time, and token/context usage when OpenCode exposes it.
• sdd-engram-plugin — optional OpenCode TUI plugin to manage SDD profiles and browse Engram memories directly from OpenCode, with runtime profile activation and no restart required.

When you select OpenCode in the installer, Gentle-AI asks whether to register each community plugin and offers a browser shortcut to review the repository first. Gentle-AI only ensures ~/.config/opencode/tui.json exists and adds the plugin package names to its plugin array; OpenCode installs and loads those packages the next time it starts. Once OpenCode has materialized a plugin under ~/.config/opencode/node_modules/, gentle-ai update can compare its local package.json version with the plugin's GitHub releases.

Start at the Community Roadmap — everything labelled up-for-grabs is scoped, approved and unclaimed. Then read CONTRIBUTING.md and the Codebase Guide.

This project exists because of the community. See CONTRIBUTORS.md for the full list.

Gentle-AI is built by Alan Buscaglia (Gentleman Programming): 15 years of enterprise architecture, a community of thousands of developers testing these tools daily, and a simple rule for AI-assisted work: verifying beats generating. The goal is never speed at any cost. It is a team that learns to direct AI with process and quality, instead of depending on a consultant.

Consulting: AI adoption for development teams

Most teams that reach out share the same problem: they want to adopt AI, and it is not working. Some developers resist it, everyone prompts their own way, and there is no shared process or quality bar. This is AI adoption for engineering teams, not a prompting course.

Engagements run on the same open-source tools you see in this repository (Gentle-AI, Engram, the 4R review framework), applied to the team's own codebase and stack.

Adoption program

1. Team diagnosis: technical level, resistance points, and opportunities.
2. Group session before implementation: AI as a tool, demystification, and real cases.
3. Tech lead session before implementation: align workflows and adoption strategy.
4. Tech lead session after implementation: follow-up and friction points.
5. Group session after implementation: consolidate learnings and next steps.
6. Deliverable: documentation and workflows tailored to the team's stack.

Hands-on variant

Three sessions: collect the team's real problems and assign a task, demonstrate Gentle-AI and the agentic ecosystem solving exactly those problems, then review how the developers are using it and calibrate recommendations. The team sees the full flow working on its own code.

Phased engagements for longer collaborations and recorded training modules on quality, agent orchestration, and AI-assisted code review are also available.

---

Trademark notice: The Gentle AI™ and Engram™ names and logos are trademarks of Alan Buscaglia. Both marks are used throughout this document; the symbol appears on the first prominent mention of each, and this notice covers the rest. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See TRADEMARKS.md.