Gentle-AI

Gentle-AI — Ecosystem, Frameworks, Workflows for AI coding agents.

[!IMPORTANT] Receipt-Driven Development (RDD) is opt-in and provides bounded review evidence. v2.2.0 was the historical release where that path became supported after RDD began in v1.47.0: small work stays direct, broader implementation is delegated, SDD stays optional, and once RDD is enabled every route can converge on structural proof and an informational bounded-review outcome. Ordinary repository policy owns delivery. RDD is off until you enable it with gentle-ai review mode enable --scope global.

The current stable release is v2.3.0. @latest is the stable channel:

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

To opt into the current prerelease, v2.4.0-rc.1, install its exact tag:

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@v2.4.0-rc.1

Use @main only for unreleased development changes. See the full RDD version policy.

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

What It Does

Gentle-AI is NOT an AI agent installer. It adapts the agent runtime(s) already on your machine; it never installs one for you. If a selected agent isn't detected, Gentle-AI refuses and names the exact command you'd run yourself instead. It is an ecosystem configurator that equips the AI coding agent(s) you already use with persistent memory, Spec-Driven Development (SDD), curated skills, MCP servers, model routing, a teaching-oriented persona, and bounded native review.

Before: "I installed Claude Code / OpenCode / Cursor, but it's just a chatbot that writes code."

After: Your agent now has memory, skills, workflow, MCP tools, and a persona that actually teaches you.

Supported Agent Integrations

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.

Organic Routing and Review Boundaries

Every configured agent receives the same outcome-first routing, even when the optional SDD component is not selected. Ask for the outcome; the agent uses exactly one implementation route and reviews the candidate only after implementation.

Implementation routing does not decide review strength, and per-action test, build, install, or review workers do not change the selected route. Native commands own repository identity, candidate scope, lifecycle transitions, receipts, and safe continuations. See Organic Implementation Routing, the Organic RDD architecture, and the review authority threat model.

Quick Start

Install (recommended)

[!NOTE] gentle-ai install requires Node.js 18+ and npm on every platform (it warns if either is missing). See Prerequisites for your distro's install hint.

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] Windows source builds and CI/runtime tests remain supported, but official Windows binary distribution and Scoop are temporarily 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.

[!IMPORTANT] After replacing or upgrading the gentle-ai binary, run gentle-ai sync to refresh its managed assets. See the sync and upgrade reference.

Configure project context

Once your agents are configured, open your AI agent in a project and run these two commands to register the project context:

These are not required for basic usage. The SDD orchestrator runs /sdd-init automatically if it detects no context. Startup hooks normally keep the skill registry fresh for agents that support hooks, including Codex, Claude Code, OpenCode, and Pi through gentle-pi. If you start Pi with pi -ns, startup skill loading/hooks are skipped, so run the registry refresh manually when you need updated project rules.

Run gentle-ai doctor at any time for a read-only health check of your ecosystem (tool binaries, state.json, Engram reachability, disk space).

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

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

gentle-ai install --scope=workspace

# 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

# macOS / Linux
GENTLE_AI_CHANNEL=beta gentle-ai upgrade

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

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

go install github.com/gentleman-programming/gentle-ai/v2/cmd/gentle-ai@v2.4.0-rc.1
gentle-ai version

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

Core Workflow

1. Install and configure. Run the installer, select the agents and components you want, then open your agent in a project.
2. Use the smallest implementation route. Keep bounded work direct, delegate actions that need fresh context, and use SDD only after an explicit request or an accepted proposal. SDD artifacts can live in Engram for cross-session memory, OpenSpec for versioned files, or hybrid for both.
3. Build with discipline. /sdd-init detects project testing capabilities; when Strict TDD is active, SDD apply works test-first. SDD verify audits RED/GREEN evidence and runs verification. Agents that support delegation use focused subagents instead of one growing conversation.
4. Review one candidate. After implementation, bounded native review freezes the candidate and reports an informational outcome. Commit, push, PR, and release remain separate decisions under ordinary repository policy; review does not authorize, block, or govern them.

Trust what the system can derive, not agent narration. Chapter 21 — Verifiable Trust explains the mental model: agents assess the candidate; native review records bounded evidence while ordinary repository policy owns delivery.

5. Upgrade, then sync. Refresh the binary and the managed agent assets together:

   gentle-ai upgrade
   gentle-ai sync
   

The flow at a glance

Once you enable it, both implementation routes can converge on RDD: a bounded native review freezes the candidate and reports an informational outcome — review is never reopened for unchanged content. RDD is opt-in, and ordinary repository policy owns delivery whether it is on or off.

Organic route (no SDD) — the agent picks the smallest useful route and RDD enters 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 -->|"standard"| J["1 focus lens<br/>+ consent"]
    H -->|"high"| K["Canonical 4R + consent + forecast<br/>Risk · Readability · Reliability · Resilience"]
    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 --> T["Ordinary repository policy"]
    T --> U["Commit → Push → PR"]
    Z --> U

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

SDD route — durable planning artifacts first, then apply, independent verify, and an optional RDD review offer; archive and delivery follow ordinary repository policy:

flowchart TD
    A["User: sdd-new / sdd-explore<br/>(or sdd-ff to fast-forward planning)"] --> B["Explore<br/>investigate codebase and approaches"]
    B --> C["Propose<br/>intent · scope · approach"]
    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"| I["Optional RDD review offer"]
        Q -->|"fails"| H

    subgraph RDD["RDD — same machine as the organic route"]
        I --> J{"Risk"}
        J -->|"low"| K["Structural readback"]
        J -->|"standard / 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"]
    end

    O --> R["Archive<br/>merge delta-specs · close the cycle"]
    Q -->|"fails"| H
    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

Size, file count, or perceived risk never select SDD on their own — only an explicit request or an accepted proposal does. Either way, one candidate gets one review, one possible correction, and one receipt.

Control receipt-driven development

Review mode is user-owned and available independently of the review lifecycle. Receipt-driven development is opt-in: it is off until you turn it on.

gentle-ai review mode status --cwd .
gentle-ai review mode enable --scope global --cwd .
gentle-ai review mode disable --cwd .

status is read-only. With no source expressing an opinion the effective mode is off, reported as decided by default; only an explicit global enable turns review on. Any global or clone-local disabled source wins; a clone can opt out with --scope clone but cannot force review on, so --scope global is the only way in. Enabling applies only to future candidates, while declining a one-candidate review prompt does not change the mode. When review is off, native review does not run. Review outcomes are informational in every mode, and ordinary repository policy decides delivery without fabricated approval.

Historical note: v2.2.2 introduced the native disabled/unmanaged disposition. Current SDD status does not use that disposition: with review disabled, it skips review authority, emits no reviewGate, and pre-verify continues without routing to a review that cannot start. Archive and delivery proceed under ordinary repository policy; any present review outcome is informational.

Release verification

Official macOS and Linux release archives require an authenticated checksums.txt. The built-in upgrader verifies its Minisign signature, its exact Gentleman-Programming/gentle-ai + release-tag binding, and the selected 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 a release manually, 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 for the first-signed-release procedure, exact CI injection points, and rotation runbook.

Windows archives and Scoop publication remain omitted until publicly trusted RSA Authenticode signing is provisioned (prefer managed OIDC with Azure Artifact Signing), both amd64 and arm64 executables are signed before archive and checksum generation, and release verification fails if either executable is unsigned.

Review a focused staged candidate

For a monorepo or shared worktree, explicitly 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 all previously staged paths. It starts review but does not itself issue an approved receipt; unstaged and untracked worktree content is excluded. The default workspace projection remains the complete workspace review, and an existing authority is never auto-converted between projections. See the review authority threat model for delivery and base-ref details.

Backups

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 (keeps the 5 most recent). Pin important backups via the TUI (p key) to protect them from pruning.

See Backup & Rollback Guide for details.

Key Features You Should Know About

OpenCode SDD Profiles

Assign different AI models to different SDD phases -- a powerful model for design, a fast one for implementation, a cheap one for exploration. OpenCode uses gentle-orchestrator as the base SDD conductor, and generated named profiles still appear as sdd-orchestrator-{name} entries.

# 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 (default) and your custom profiles.

Full guide: OpenCode SDD Profiles

Engram (Persistent Memory)

Your AI agent automatically remembers decisions, bugs, and context across sessions. You don't need to do anything -- but when you do:

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

Full reference: Engram Commands

Documentation

Community Highlights

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/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.

Contributors

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

Next Steps

• Just installed? Read Intended Usage for the mental model, then run gentle-ai doctor if anything looks wrong.
• Starting work? Read Organic Implementation Routing to understand direct, delegated, and optional SDD behavior.
• Reviewing a focused change? Start with the Organic RDD architecture and review authority threat model.
• Maintaining Gentle AI? Use the Codebase Guide to find package ownership and review boundaries.
• Using Pi? Read Pi Agent for the gentle-pi harness, Pi commands, persona, and model assignments.
• Ready to contribute? Start at the Community Roadmap — everything labelled up-for-grabs is scoped, approved and unclaimed. Then read CONTRIBUTING.md.