Gentle AI Documentation

Gentle AI equips the AI coding agents already on your machine with persistent memory, specification-driven development, curated skills, MCP servers, model routing, a teaching-oriented persona, and native bounded review.

Stable v2.4.0Latest RC v2.5.0-rc.1Go 1.25.10+License MIT16 supported agents

What is Gentle AI

It is an ecosystem configurator. It takes your AI coding agent and adds the pieces it needs to become more than a chatbot that writes code.

The golden rule

Gentle AI configures your agent with memory, skills, workflows, and a persona — then gets out of the way. Its own documentation says: the less you think about Gentle AI after installation, the better it is working.

Installation

Prerequisites

• Git 2.38+ on every platform.
• Go 1.25.10+ to build from source (required on Windows because installation there uses go install).
• Node.js 18+ and npm: gentle-ai install verifies them as requirements on every platform and provides a distribution-specific installation suggestion if either is missing. It does not install them for you.
• macOS: Homebrew on the PATH. If the tap requests trust, run brew trust --formula gentleman-programming/tap/gentle-ai once.
• Ubuntu/Debian, Arch, Fedora/RHEL: the corresponding package manager (apt-get, pacman, dnf) and sudo access.
• Pi: if you select the Pi agent, pi must be installed and available on the PATH.

macOS / Linux

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

Homebrew

brew tap Gentleman-Programming/homebrew-tap
brew trust --formula gentleman-programming/tap/gentle-ai
brew install gentle-ai

Go install (any platform with Go 1.25.10+)

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

Notice the /v2 suffix in the module path: Go requires it for major version 2 and later. Releases before v2.0.0 use the path without the suffix.

Installation scope

By default, gentle-ai install writes per-agent files to the global configuration directory of each selected agent. To keep the stack isolated to one project:

gentle-ai install --scope=workspace

The workspace scope applies to per-agent files: system prompts, skills, SDD agents, and persona files are written to the current project root when the agent supports local configuration. Integrations that exist only globally — such as package installation or settings that an agent reads only from its global configuration — remain global by design. You can also set GENTLE_AI_INSTALL_SCOPE for CI or non-interactive use.

Project context

After configuring your agents, open an agent in a project. These two commands register project context. Neither is required for basic use.

The SDD orchestrator runs /sdd-init automatically when it does not detect context. Startup hooks usually keep the skill registry current for agents that support hooks — Codex, Claude Code, OpenCode, and Pi through gentle-pi. Starting Pi with pi -ns skips skill loading and startup hooks, so refresh the registry manually in that case.

At any time, you can run gentle-ai doctor, a read-only ecosystem health check.

Components, skills, and presets

Components

Default-denied sensitive-path list

The permissions component applies this deny list:

~/.ssh/*            ~/.ssh/**/*        **/*.pem
**/*.key            **/.env*           ~/.credentials/*
~/.aws/credentials  ~/.config/gh/hosts.yml
~/Library/Keychains/*                  **/secrets/*
**/*.p12            **/*.pfx

Presets

The persona is selected separately on its own screen and is applied independently of the preset.

Engram — persistent memory

Engram is your agent's persistent memory. It stores decisions, discoveries, bug fixes, and context between sessions automatically. The agent manages it through MCP tools.

Everyday commands

# Browse memories visually: search, filter, and open each observation
engram tui

# Search from the terminal without opening the TUI
engram search "auth refactor"

# Export project memories to .engram/ so they can be committed to Git
engram sync

engram tui is the fastest way to see what your agent has been saving. Start there.

Project management

Since v1.11.0, Engram groups memories by project name, automatically detected from your Git remote. Sometimes one project ends up with duplicate names ("my-app" vs "My-App" vs "my-app-frontend"). These commands resolve that:

engram projects list          # List all projects with their observation count
engram projects consolidate   # Interactively merge duplicate names

The MCP equivalent is mem_merge_projects, which the agent can call directly when it detects naming drift.

How project detection works

Since v1.11.0, Engram reads the Git remote URL at startup, normalizes it to lowercase, and uses it as the project name. If it finds similar existing names, it notifies you. This prevents the most common problem: the same project accumulating memories under slightly different names. Outside a Git repository, Engram uses the directory name.

Sharing with the team

By default, memories remain local. To share them through Git:

# After a work session: export to .engram/ in your repository
engram sync

# On another machine: import memories after cloning
engram sync --import

Add .engram/ to the repository and commit it. When someone clones the repository and runs engram sync --import, they receive the complete project context. This is especially useful for onboarding: new teammates start with the accumulated knowledge.

Core MCP tools

Advanced tools — mem_update, mem_suggest_topic_key, mem_session_start/mem_session_end, mem_stats, mem_delete, mem_timeline, mem_capture_passive, and mem_merge_projects — are rarely needed, but available.

SDD — specification-driven development

SDD is a structured planning workflow for substantial features. It has phases, but you do not need to learn any of them.

The ten phases

This is joined by Judgment Day (judgment-day): a parallel adversarial review in which two independent judges review the same objective.

Where artifacts live

SDD artifacts can be persisted in three modes:

• Engram — memory between sessions.
• OpenSpec — versioned files in the repository.
• Hybrid — both.

Sub-agents: smarter than they seem

When the orchestrator delegates work to a sub-agent, that sub-agent is not a simple script executor. It is a complete agent with its own session, tools, and context.

1. The orchestrator keeps them focused. It resolves the skill registry once, passes relevant SKILL.md paths in each sub-agent prompt, and gives it a concrete role. Sub-agents read the exact skill files instead of receiving generated summaries.
2. They adapt to your project. An sdd-apply sub-agent working with React receives React patterns. The same sub-agent working with Go receives Go testing conventions. Rules depend on the registry and task context, not a hard-coded list.
3. They persist phase artifacts when the backend supports it. In Engram-backed SDD workflows, phase agents save artifacts before returning. The next phase can continue from the saved proposal, spec, design, tasks, or apply progress — even across sessions.

SDD Research — the evidence lane

SDD had local exploration but no first-class lane for auditable external evidence. Research is offered immediately after sdd-explore, and it is optional — but selecting it makes its admission and persistence checks mandatory.

flowchart TD
    A["sdd-explore"] --> B{"Select the research lane?"}
    B -->|"no"| G["Propose"]
    B -->|"yes"| C["Declare capability
documentation / open-web"]
    C --> D["Collect sources
claims - contradictions - uncertainty"]
    D --> E["Persist the artifact
OpenSpec - Engram - both"]
    E --> F{"Evidence done - store ready
decisions confirmed?"}
    F -->|"no"| H["Blocked
no validated claim"]
    H --> D
    F -->|"yes"| G
    G --> I["Spec - Design - Tasks"]

    style G fill:#2B3328,stroke:#98BB6C,color:#DCD7BA
    style H fill:#43242B,stroke:#D27E99,color:#DCD7BA

How it is declared

On installs that expose the slash command, /sdd-research <questions> runs the lane after Session Preflight and sdd-init have established the active change, the requested source classes, the artifact store, and the runtime capability declaration.

Research accepts only the versioned gentle-ai.sdd-research-capability/v1 declaration, with an exact grant for documentation or open-web. Nothing else opens the lane.

What it persists

It writes a gentle-ai.sdd-research/v1 artifact recording questions, grants, sources, claim-to-source mappings, contradictions, uncertainty, freshness, and separate non-authoritative product choices.

A one-sided hybrid failure recovers only from retained pre-write intent and canonical content. Otherwise the research and the proposal stay blocked — the system never prefers one copy over the other. No-store research cannot make a proposal ready.

The proposal gate

Once research is selected, propose requires done evidence, valid references, a ready backend, and confirmed product decisions. This is the part worth internalizing: choosing the lane is optional, finishing it is not.

OpenSpec — openspec/config.yaml

openspec/config.yaml is a documented project-level convention for SDD when you work in openspec or hybrid persistence mode.

What you can customize

• Project context reused between phases.
• Strict TDD activation.
• Phase-specific rules for proposal, specs, design, tasks, apply, verify, and archive.
• Testing-command and coverage overrides used by apply/verify prompts.
• A cache of detected testing capabilities for apply/verify workflows.

Which phases reference it

Example structure

Combining the shared convention document, the sdd-init guide, and apply/verify references, the practical top-level structure looks like this:

schema: spec-driven

context: |
  Tech stack: ...
  Architecture: ...
  Testing: ...
  Style: ...

strict_tdd: true

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then for scenarios
  design:
    - Document architecture decisions with rationale
  tasks:
    - Keep tasks completable in one session
  apply:
    - Follow existing code patterns
  verify:
    test_command: ""
    build_command: ""
    coverage_threshold: 0
  archive:
    - Warn before merging destructive deltas

testing:
  strict_tdd: true
  detected: "YYYY-MM-DD"
  runner:
    command: "go test ./..."
    framework: "Go standard testing"

Treat this as a practical synthesis of fields that the prompt layer can read or emit today, not as a strict schema definition.

Known inconsistencies

The file shape is not yet uniform. Current examples show:

• sdd-init presents rules.apply and rules.verify as flat instruction lists.
• The shared convention document presents rules.apply with tdd and test_command, and rules.verify with structured override keys.
• sdd-apply/strict-tdd.md refers to rules.apply.test_command.
• sdd-verify refers to rules.verify.test_command, rules.verify.build_command, and rules.verify.coverage_threshold.

In other words, rules.apply and rules.verify are currently treated as if they can contain structured keys, while other examples show the same phase rules as flat lists.

Strict TDD

Strict TDD mode is enabled when the project has detectable testing support.

• /sdd-init detects the project's testing capabilities and enables Strict TDD when they are available.
• When Strict TDD is active, sdd-apply works test-first.
• sdd-verify audits RED/GREEN evidence and runs verification.
• The strict_tdd flag in openspec/config.yaml enables or disables it; sdd-init, orchestrator prompts, sdd-apply, and sdd-verify reference it.
• The testing section caches detected capabilities so apply/verify workflows do not need to rediscover them every time.
• It can also be enabled when synchronizing with gentle-ai sync --strict-tdd.

In Pi, support assets live in .pi/gentle-ai/support/strict-tdd.md and .pi/gentle-ai/support/strict-tdd-verify.md.

Skills and the skill registry

Two skill layers

Gentle AI installs SDD skills and base skills (workflow and testing patterns) directly in your agent's skills directory. They are embedded in the binary and always current. There are 22 skill files.

For code skills — React 19, Angular, TypeScript, Tailwind 4, Zod 4, Playwright, and more — the community maintains a separate repository: Gentleman-Programming/Gentleman-Skills. Install them manually:

git clone https://github.com/Gentleman-Programming/Gentleman-Skills.git
cp -r Gentleman-Skills/curated/react-19 ~/.claude/skills/
cp -r Gentleman-Skills/curated/typescript ~/.claude/skills/
# ... or copy the entire curated/ directory

Once installed, the agent detects what you are working on and loads relevant skills automatically. You do not need to activate or invoke them.

Included base skills

The skill registry

The registry is a local project index that lets every supported agent find the same skills without rewriting them. It stores names, full descriptions, scopes, and exact SKILL.md paths.

gentle-ai skill-registry refresh

# Only if you explicitly need to rescan everything:
gentle-ai skill-registry refresh --force
gentle-ai skill-registry refresh --cwd /path/to/project --quiet

Refresh flow

gentle-ai skill-registry refresh
   │
   ├─ Scan project skill roots first
   │     skills/, .opencode/skills/, .claude/skills/, .github/skills/, ...
   │
   ├─ Then scan global agent roots
   │     ~/.config/opencode/skills/, ~/.claude/skills/, ...
   │
   ├─ Deduplicate by skill name
   │     the project skill takes precedence over the global skill
   │
   ├─ Parse frontmatter
   │     name + full description + path + scope
   │
   └─ Write .atl/skill-registry.md + cache

Runtime flow

User task
   │
   ▼
The orchestrator reads .atl/skill-registry.md
   │
   ▼
Compares the task and file context against full descriptions
   │
   ▼
Passes exact SKILL.md paths to the sub-agent
   │
   ▼
The sub-agent reads complete skills before working
   │
   ▼
The sub-agent executes with the skill's original intent intact

Registry contract

Excluded skills

The registry never indexes _shared, skill-registry, or any sdd-* skill. The first two are internal plumbing; sdd-* skills are managed by the SDD workflow, not the delegator. The exclusion is intentional and silent, so a user skill whose name collides with these prefixes is discarded without warning.

Inspect without writing

gentle-ai skill-registry list          # name<TAB>scope<TAB>path
gentle-ai skill-registry list --json   # machine-readable, including descriptions

The cache uses a fingerprint that includes the schema version plus the path, mtime, and size of every discovered SKILL.md, so a normal startup is a cheap cache hit when skills have not changed.

Personas

custom is a compatibility and ownership choice, not a persona editor. Use it when you already have persona instructions and want Gentle AI to leave them untouched.

Organic implementation routing

Ask for the outcome. Gentle AI keeps already-understood work inline, delegates only actions that benefit from fresh context, and offers SDD only when durable planning materially reduces uncertainty.

The three routes

File counts describe the context needed for the current action, not a risk score or an SDD threshold. Risk may strengthen native verification or review, but never forces SDD.

Delegation also applies per action: tests, builds, installations, and native review actors may use fresh workers without changing the implementation route or creating an SDD run. Direct and delegated work do not create SDD artifacts, phase attempts, or synthetic SDD cycles.

If apparently simple work reveals substantial ambiguity, Gentle AI can offer SDD at the next safe boundary. Declining it leads to safely reduced scope, a justified direct or delegated route, or Needs your decision — never silent SDD enrollment.

Delegation stop rules

The orchestrator must stop acting as a monolithic executor when complexity appears:

Public states

Normal interaction reports only four states. The user does not choose internal review states, hashes, receipts, or lifecycle transitions.

A question is necessary only when the answer changes requested scope, destructive or irreversible impact, permission or security exposure, verification cost or external side effects, accepted residual risk, or delivery.

RDD — Receipt-Driven Development

RDD reviews a completed candidate without taking ownership of delivery. It is deliberately small: native code freezes a worktree candidate, coordinates bounded review, burns completed authority, and returns control to the human.

The model in three sentences

Turning RDD on and off

gentle-ai review mode status --cwd <repo>
gentle-ai review mode enable --scope global --cwd <repo>
gentle-ai review mode disable --cwd <repo>
gentle-ai review mode disable --scope clone --cwd <repo>
gentle-ai review mode enable  --scope clone --cwd <repo>

Any disabled source wins. A clone can opt out, but it cannot require review from the user, so global scope is the only way to opt in. With no source expressing an opinion, the effective mode is off, reported as decided by default.

Interactive starts ask before review work, once per clone. Accepting records that choice; "not now" applies only to that candidate and does not change review mode. Non-interactive tier-1/tier-2 starts proceed without asking and report how to disable review mode.

While RDD is disabled, work continues through direct inline routing, direct delegation, or optional SDD, without starting, retrying, or reactivating review on its own. Native delivery gates report disabled/unmanaged when no exact receipt applies, and never fabricate approval.

The atomic cycle

STATUS without a selector → exact START → bounded collection/finalize → approved + burn → ordinary repository policy

1. STATUS without a selector only performs preflight

STATUS without a selector evaluates only the current worktree candidate and renders one exact START invocation. It does not discover ambient authority, resume another worktree, recover history, or select an old lineage. The parent runs only the returned next_transition and its ordered tokens.

gentle-ai review status \
  --cwd <repo> \
  --contract gentle-ai.review-integration/v2 \
  --agent claude-code \
  --next-transition

This prevents historical authority, a sibling worktree, or a stale lifecycle response from directing the current candidate.

2. START freezes an independent transaction

START freezes the candidate in a compact transaction explicitly bound to its lineage, worktree, and target. It selects risk and lenses natively. The parent captures the returned lineage, revision, and target tokens.

An exact replay of an active START can return replayed. A genuinely new START is independent. A burned lineage is never reused.

3. Bound calls manage the transaction

Every subsequent STATUS, review capture-result, and FINALIZE carries those exact tokens. The parent routes only from the returned next_transition:

A forecast is descriptive, not a route. It is fully reported, but only next_transition is executed.

4. Approval burns authority

On success, native code reads back terminal approval and then burns the exact lineage and its artifacts before returning approved. No terminal receipt, tombstone, witness, mirror, or delivery authority survives. Other lineages and worktrees remain intact.

Cross-repository continuity

A session rooted in repository A can review a user-explicitly-authorized nested target in unrelated repository B. Go resolves the requested path to B's canonical worktree root; adapters remain opaque and never parse authorization or roots.

This lifecycle is available only to Claude Code, Codex, OpenCode, and Pi. Unsupported runtimes fail before any repository or authority mutation.

Risk and lenses

START classifies risk once from repository evidence and freezes it. A correction cannot recalculate risk downward to escape review, or upward to create more work.

That 0, 1, or 4 shape is structural cost control. A documentation-only change should not pay for four broad model calls. A normal code change benefits from one focused pass. Authentication, payments, service tokens, security-sensitive paths, or a large change deserve four independent perspectives.

Lenses are read-only

Each selected lens is read-only and separate from authorship. It reads the candidate, judges one concern, emits a strict JSON result, and stops. No lens edits files, creates a corrector, or advances lifecycle state. As Chapter 21 says: the jury is not the contractor.

Reviewers receive provider-issued immutable context, not live workspace state. They inspect only provider-bound immutable trees: never the live worktree, index, HEAD, or another review. Candidate bytes must not pass through /tmp, a repository scratch file, or GENTLE_AI_FROZEN_CANDIDATE_CONTEXT.

The shape of a reviewer result

{
  "findings": [
    {
      "location": "internal/auth/token.go:84",
      "severity": "CRITICAL",
      "claim": "the candidate accepts an expired service token",
      "proof_refs": [
        "TestExpiredToken passes on base and fails on candidate"
      ],
      "evidence_class": "deterministic",
      "causal_disposition": "introduced"
    }
  ],
  "evidence": [
    "inspected the complete candidate diff and ran the focused differential test"
  ]
}

The omission is deliberate: no finding ID, lens name, hash, or lineage metadata. The facade already knows which lens result arrived in which selected position. Go fills missing IDs, canonicalizes order, validates required proof, and rejects unknown fields. A model is good at claims and evidence; it is a poor choice for constructing canonical bytes.

Independent evidence

Review opinion and verification evidence are different things. A lens can say "the tests look adequate." Evidence says go test ./... succeeded, the build completed, and acceptance examples passed.

Bounded correction

Only severe findings caused by the candidate can block. Pre-existing or base-only findings become follow-ups; unknown findings escalate; WARNING and SUGGESTION remain information.

An ordinary review permits exactly one correction transaction. START freezes the correction budget at min(200, ceil(original_changed_lines / 2)).

• Before editing, a positive forecast is provided, and work continues only through the provider's returned next transition.
• After the bounded edit, a read-only fix validator runs only when the exact collection input requests it.
• A validator that cannot inspect immutable trees has no verdict. Report that block instead of submitting failed validation: an inconclusive check recorded as failed irreversibly consumes the single correction attempt.
• Once the attempt is accepted — even with a measured zero-line delta — the ordinary correction is exhausted. A later change requires an authorized successor.
• Later observations are follow-ups, not another correction.

Delivery and gates

gentle-ai review validate and its named gates — post-apply, pre-commit, pre-push, pre-pr, and release — are compatibility and information commands. They never discover authority or decide delivery:

They never permit, approve, block, commit, push, or open a pull request.

Candidate projections

gentle-ai review start uses the workspace projection by default. For a monorepo or shared worktree, you can review exactly what is in the Git index:

git add apps/mi-servicio
git diff --cached
gentle-ai review start --projection staged

The staged projection freezes the complete existing index, including every already-staged path. It excludes unstaged and untracked worktree content, and does not modify the live index or worktree when deriving evidence. It starts review, but does not by itself issue an approved receipt.

Existing authority never converts automatically between projections. Recovery inherits the predecessor's projection when --projection is omitted.

Stop codes

A stop carries exactly one reason code and no executable transition. These are some common codes and their continuation:

For every clone-scoped exit, gentle-ai review mode disable --scope clone --cwd <repo> returns delivery to ordinary repository policy. No stop code is resolved by changing runtime, provider, or toolchain.

Trust boundaries

The mental model comes from Chapter 21 — Verifiable Trust:

"The model judges the candidate. The facade constructs authority. The gate re-derives truth."

The central separation: Go does deterministic work; the model does judgment work. The model does not invent a lineage ID, calculate hashes, serialize operation payloads for fifteen state transitions, freeze ledgers by hand, or construct gate contexts.

What the threat model protects — and what it does not

The compact review store protects valid authority from accidental corruption and concurrent writers. It does not claim to authenticate state against a malicious local actor with the same user and filesystem access: without an external trust anchor, that actor can rewrite state, the receipt, the Git repository, or the binary.

Retained controls

• Strict schema and semantic validation before accepting or replacing authority.
• Legal-transition validation against the currently locked state and repository-derived evidence.
• Atomic file replacement, with file and directory synchronization where practical.
• A writer lock and expected revision to detect concurrent writers.
• A shared maintenance lock at <git-common-dir>/gentle-ai/REVIEW-MAINTENANCE.lock, outside the replaceable authority subtree. It coordinates only cooperative Gentle AI participants; it is not a defense against a malicious actor with the same user.
• Recognition of exact retries for idempotent operations.
• Re-derivation of context from live Git instead of trusting persisted mirrors.
• Checksums only where useful for detecting accidental corruption: they are not authentication.

Input schemas

Versioned JSON schemas can be printed:

gentle-ai review schema reviewer
gentle-ai review schema refuter
gentle-ai review schema validator
gentle-ai review schema verification-evidence-record
gentle-ai review schema final-verification-incident

Raw verification evidence remains arbitrary non-empty bytes, but by itself is never result authority. Native capture persists a strict gentle-ai.review-verification-evidence/v2 record with a closed outcome and immutable candidate, revision, payload, path, and ledger bindings.

Review store maintenance

Review authority accumulates without limit: every candidate leaves a lineage behind and nothing removes one already delivered, so a long-lived clone eventually has hundreds of lineages and hundreds of megabytes of candidate checkouts.

Removes candidate-views/ and the v1, v2, quarantine, effect-markers, and incidents subtrees of review-transactions/.

Preserves the RDD switch — in both review-mode/ and the pre-#2882 mirror — together with sdd-runtime/, defect-reports/, review-artifacts/, incidents/, and REVIEW-MAINTENANCE.lock. Reviews that were off remain off. The list is allowlisted, so any path the command does not recognize — including one added by a future release — is reported and left in place instead of guessed at.

Retains reviews/, the graph store written by the gentle-pi adapter, and removes it only with --include-adapter-reviews. A default run cannot distinguish a dead graph from a live review, and a destructive command does not delete what it cannot guarantee.

The TUI exposes the same action as Reset review store in the main menu, between Manage backups and Managed uninstall, with its confirmation cursor starting on Cancel. The TUI has no equivalent for --include-in-flight or --include-adapter-reviews: when open reviews exist it refuses and prints the CLI invocation, so destroying in-flight work is never one keystroke away.

Complete organic workflow

The agent chooses the smallest useful route, and RDD enters at the end over the frozen candidate.

flowchart TD
    A["The user requests a change"] --> B{"Implementation
route"}
    B -->|"decide/verify
1-3 files"| C["Inline direct"]
    B -->|"explore 4+ files
or write 2+ non-trivial ones"| D["Delegated direct
(one bounded worker)"]
    C --> E["Implementation + tests"]
    D --> E
    E --> F{"Is RDD enabled?
(user opt-in)"}
    F -->|"off (default)"| Z["Ordinary delivery
reports disabled/unmanaged"]
    F -->|"enabled"| G["review status --next-transition
(provider-negotiated route)"]
    G --> H{"Risk frozen
at START"}
    H -->|"low"| I["Structural reading
0 lenses - silent"]
    H -->|"standard"| J["1 focus lens
+ consent"]
    H -->|"high"| K["Canonical 4R + consent
+ cost forecast"]
    J --> L["Reviewers inspect
the immutable candidate"]
    K --> L
    L --> M{"Severe findings
caused by the candidate?"}
    I --> N["Result: approved
(informative)"]
    M -->|"no"| N
    M -->|"yes"| O["One bounded correction
(frozen budget)"]
    O --> P["Fix validator
(read-only)"]
    P -->|"passes"| N
    P -->|"fails with evidence"| Q["Escalation"]
    P -->|"no diff access"| R["Inconclusive: the attempt
is not consumed"]
    R --> P
    Q --> S["review recover
(authorized successor)"]
    N --> T["Ordinary repository
policy"]
    T --> U["Commit → Push → PR"]
    Z --> U

    style N fill:#2B3328,stroke:#98BB6C,color:#DCD7BA
    style Q fill:#49443C,stroke:#FF9E3B,color:#DCD7BA
    style U fill:#43242B,stroke:#D27E99,color:#DCD7BA
    style Z fill:#1F1F28,stroke:#54546D,color:#727169

Complete SDD workflow

First come durable planning artifacts, then apply, independent verification, and an optional RDD review offer. Archiving and delivery follow ordinary repository policy.

flowchart TD
    A["sdd-new / sdd-explore
(or sdd-ff to advance planning)"] --> B["Explore
investigate code and approaches"]
    B --> C["Propose
intent - scope - approach"]
    C --> D{"Does the user approve
the proposal?"}
    D -->|"no"| B
    D -->|"yes"| E["Spec
requirements + scenarios"]
    E --> F["Design
architecture decisions"]
    F --> G["Tasks
ordered checklist"]
    G --> H["Apply
the sub-agent implements
against the specs"]
    H --> Q["Verify
independent verification against
spec - design - tasks"]
    Q -->|"fails"| H
    Q -->|"passes"| I["Optional RDD review offer"]
    I --> J{"Risk"}
    J -->|"low"| K["Structural reading"]
    J -->|"standard / high"| L["1 lens or canonical 4R + consent"]
    L --> M{"Severe findings?"}
    M -->|"yes"| N["One bounded correction
+ fix validator"]
    M -->|"no"| O["Result: approved
(informative)"]
    K --> O
    N -->|"validates"| O
    N -->|"fails"| P["Escalation → recover"]
    O --> R["Archive
merges delta specs - closes the cycle"]
    R --> S["Ordinary repository policy"]
    S --> T["Commit → Push → PR"]

    style O fill:#2B3328,stroke:#98BB6C,color:#DCD7BA
    style P fill:#49443C,stroke:#FF9E3B,color:#DCD7BA
    style T fill:#43242B,stroke:#D27E99,color:#DCD7BA

Supported agent matrix

Multi-mode SDD support

All agents support the SDD orchestrator and single-mode SDD. Multi-mode — assigning different models to each SDD phase — is supported by:

• OpenCode and Kilo Code, through the OpenCode-compatible multi-mode overlay.
• Kiro IDE, through native sub-agent model: frontmatter.
• Pi, where multi-mode is a package property: gentle-pi installs SDD agents and chains in .pi/agents/ and .pi/chains/, and model overrides live in those files or chain steps.

All other agents run in single mode: the orchestrator handles everything with the model the agent is already using. Single mode is not a downgrade: it is the simplest default and works well. Multi-mode is useful when you deliberately want to trade off cost, speed, or reasoning by phase.

Delegation models

Notes by agent

Claude Code

• Sub-agents through the native Task tool with isolated context windows.
• MCP servers configured as plugins in ~/.claude/mcp/.
• Output styles in ~/.claude/output-styles/.
• System prompt through Markdown sections in ~/.claude/CLAUDE.md.

OpenCode

• Full multi-agent overlay with 11 named agents in opencode.json: gentle-orchestrator plus 10 SDD phase agents.
• Slash commands for SDD phases (/sdd-new, /sdd-explore, etc.).
• Managed background execution is configured with --opencode-background-subagents=auto|on|off or GENTLE_AI_OPENCODE_BACKGROUND_SUBAGENTS. CLI precedence is: flag, non-empty environment, prior managed state, then auto.
• Background jobs are process-local and non-durable, have no filesystem isolation, and must not be used for dependent phases or parallel writers in the same worktree.
• Custom models in opencode.json must explicitly declare tool_call: true to appear as selectable SDD-capable options.
• Multi-mode requirement: connect your AI providers first, then run opencode models --refresh.
• Gentle AI sets SDD agent sharing to disabled by default for privacy; user-managed share values such as manual or auto are preserved.

Codex

• Native CLI agent with TOML configuration in ~/.codex/config.toml.
• Model-selection profiles written as separate files in ~/.codex/<nombre>.config.toml. GPT-5.6 defaults require Codex >= 0.144.0.
• The three lanes are divided by what the phase actually does: sdd-strong reasons about supplied context, sdd-mid writes code in an agentic loop where effort matters more than raw model strength, and sdd-cheap performs structured transcription with short context and verifiable output — so it buys effort instead of a larger model.
• Multi-agent delegation is enabled by default: features.multi_agent = true, agents.max_threads = 4, and agents.max_depth = 2 are written. If configuration or native tools are unavailable, orchestration gracefully falls back to inline single-agent execution.

Cursor

• Native sub-agents in ~/.cursor/agents/sdd-{fase}.md (10 files). Cursor Agent delegates automatically to the correct sub-agent according to the YAML frontmatter description field.
• sdd-explore and sdd-verify run with readonly: false so they can inspect code and run verification commands.
• Skills in ~/.cursor/skills/, system prompt in ~/.cursor/rules/gentle-ai.mdc, MCP in ~/.cursor/mcp.json.

Kiro IDE

• Detection: the kiro binary on the PATH. A configuration directory alone does not mark Kiro as installed.
• Steering file at ~/.kiro/steering/gentle-ai.md with inclusion: always frontmatter.
• MCP configuration is always at a separate root: ~/.kiro/settings/mcp.json.
• Kiro's native specs flow: .kiro/specs/<feature>/requirements.md, design.md, tasks.md, with approval gates before the apply and archive phases.
• Manual installation only from kiro.dev/downloads.

Windsurf

• Runs as a single agent and uses native features: Plan Mode (persistent plan documents that can be @mentioned between sessions, ideal for spec and design artifacts), Code Mode, and native workflows (sdd-new available in .windsurf/workflows/sdd-new.md).
• The orchestrator routes tasks through Small/Medium/Large decision paths.

Hermes

• Detect-only: Gentle AI cannot install Hermes. Install it manually first, then run gentle-ai install --agent hermes.
• Ephemeral delegation is adjusted in ~/.hermes/config.yaml under the delegation key: max_spawn_depth (2), max_concurrent_children (4), max_iterations, child_timeout_seconds, inherit_mcp_toolsets (false), and subagent_auto_approve (false).
• Toolsets, MCP servers, and skills are not inherited automatically from the parent: pass them explicitly in the mission.
• Worker output is treated as self-report: verify file writes, test results, URLs, and external effects before reporting success.

OpenCode SDD profiles

They let you assign different models to different SDD phases: a powerful one for design, a fast one for implementation, and an inexpensive one for exploration. OpenCode uses gentle-orchestrator as the base SDD conductor.

# Create a "cheap" profile with a free model for every phase
gentle-ai sync --profile cheap:openrouter/qwen/qwen3-30b-a3b:free

# Override the design phase with a stronger model
gentle-ai sync --profile-phase cheap:sdd-design:anthropic/claude-sonnet-4-20250514

# Create several profiles in one command
gentle-ai sync \
  --profile cheap:openrouter/qwen/qwen3-30b-a3b:free \
  --profile premium:anthropic/claude-sonnet-4-20250514

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

If you prefer a runtime profile manager that keeps profiles outside opencode.json, Gentle AI also supports it: during sync, OpenCode can auto-detect external profile files in ~/.config/opencode/profiles/*.json and switch to a safer compatibility path that preserves the active gentle-orchestrator prompt instead of overwriting it. Enable it with --sdd-profile-strategy external-single-active.

Pi and the gentle-pi harness

Installation

Pi must be installed and available as pi on the PATH. Then:

gentle-ai install --agent pi
pi

If Pi is the only selected agent, the installer still provisions the real Engram component, but skips persona, ecosystem-component selection, and Strict TDD questions because gentle-pi owns those decisions inside Pi.

Packages it installs

pi install npm:gentle-pi
pi install npm:gentle-engram
pi install npm:pi-mcp-adapter
npm exec --yes --package gentle-engram@latest -- pi-engram init
pi install npm:pi-subagents-j0k3r
pi install npm:@juicesharp/rpiv-ask-user-question
pi install npm:pi-web-access
pi install npm:@juicesharp/rpiv-todo
pi install npm:pi-btw

Pi commands

/gentle-ai:persona and /gentle-ai:models continue to work as compatibility aliases.

Recommended model assignment

Project files

During a normal session_start, gentle-pi copies local project assets without overwriting local edits:

.pi/agents/sdd-*.md
.pi/chains/sdd-*.chain.md
.pi/gentle-ai/support/strict-tdd.md
.pi/gentle-ai/support/strict-tdd-verify.md

Troubleshooting

CLI reference

Interactive TUI

gentle-ai

The Bubbletea TUI guides agent, component, skill, preset, and managed-uninstall selection. Before modifying any managed file, Gentle AI creates a backup snapshot.

install

# Complete ecosystem for several agents
gentle-ai install \
  --agent claude-code,opencode,gemini-cli \
  --preset full-gentleman

# Minimal setup for Cursor
gentle-ai install --agent cursor --preset minimal

# Choose specific components and skills
gentle-ai install \
  --agent claude-code \
  --component engram,sdd,skills,context7,persona,permissions \
  --skill go-testing,skill-creator,branch-pr,issue-creation \
  --persona gentleman

# Preview without applying changes
gentle-ai install --dry-run --agent claude-code,opencode --preset full-gentleman

When installing one agent with --agent X, Gentle AI merges the new agent into the existing installed_agents list in state.json and preserves any existing model_assignments. It does not overwrite the complete state.

install flags

sync

Refreshes managed assets to the current version. Run it after replacing or updating the binary, including with brew upgrade, gentle-ai upgrade, or go install. It does not reinstall binaries: it only updates prompts, skills, MCP configurations, and SDD orchestrators.

gentle-ai sync --dry-run                          # Preview the scope
gentle-ai sync                                     # Agents registered in state.json
gentle-ai sync --agent claude-code --agent opencode # Only specific agents

Sync is safe and idempotent: running it twice produces no changes the second time. It does not support --component; for opt-in components excluded from the default scope, use --include-permissions and --include-theme.

sync flags

uninstall

Removes only configuration managed by Gentle AI from one or more agents. It does not uninstall external packages or binaries. A backup snapshot is created before any change is applied.

gentle-ai uninstall --agent claude-code --agent opencode
gentle-ai uninstall --agent claude-code --component sdd,persona,context7
gentle-ai uninstall --all
gentle-ai uninstall --agent cursor --component skills --yes

When --component is omitted from a partial uninstall, all managed uninstallable components are removed from the selected agent set.

update / upgrade

gentle-ai update    # Check whether a newer version is available
gentle-ai upgrade   # Update to the latest release

After any update or manual binary replacement, run gentle-ai sync.

If GitHub rate-limits update checks, export GITHUB_TOKEN or GH_TOKEN before running update/upgrade.

doctor

gentle-ai doctor

Read-only health diagnostics: it makes no changes to your configuration.

Every check reports pass, warn, or fail, with an optional remediation suggestion. Run doctor first when something differs from the expected result.

Typical workflow

# First time: install everything
brew install gentleman-programming/tap/gentle-ai
gentle-ai install --agent claude-code,cursor --preset full-gentleman

# After a new release: upgrade and synchronize
brew upgrade gentle-ai
gentle-ai sync

# Remove only the managed SDD and persona configuration from one agent
gentle-ai uninstall --agent claude-code --component sdd,persona

# Add a new agent later
gentle-ai install --agent windsurf --preset full-gentleman

Backups and rollback

The backup system takes a snapshot of your configuration files before every install, sync, and upgrade. Backups are compressed, deduplicated, and automatically pruned.

How it works

1. Calculates a checksum for every file to back up.
2. Skips the backup if it would be identical to the most recent one (deduplication).
3. Creates a compressed snapshot (snapshot.tar.gz) with all your configuration files.
4. Prunes old backups: retains the 5 most recent and deletes the rest.

Snapshot contents

• manifest.json — metadata: origin, timestamp, file count, checksum, pin state.
• snapshot.tar.gz — compressed archive containing every backed-up file.
• For paths that did not exist before the operation, the manifest records existed=false.

Retention policy

Managing from the TUI

Restore behavior

• If existed=true: restores the snapshot file to its original path.
• If existed=false: removes the file, reverting files created during installation.
• Restoration is atomic per file write: there are no partial restores.
• Works with compressed (tar.gz) backups and legacy ones before v1.16 (the files/ directory with flat copies).

If verification fails

1. Review the failed checks in the verification report.
2. Restore from the latest snapshot through the TUI or gentle-ai restore latest.
3. Run install again with --dry-run to validate the plan.
4. Run install again after fixing external dependencies.

Release verification

Official macOS and Linux release files require an authenticated checksums.txt. The built-in updater verifies its Minisign signature, its exact binding to Gentleman-Programming/gentle-ai plus the release tag, and the selected file checksum before replacing the installed binary.

Release files have a 128 MiB cap, including chunked or unknown-length responses. Missing, oversized, malformed, untrusted, or padding key material fails closed without changing the installed binary.

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

Windows release files and Scoop publication remain omitted until publicly trusted RSA Authenticode signing is provisioned, both executables (amd64 and arm64) are signed before assets and checksums are generated, and release verification fails if either is unsigned.

Version policy

RDD began in gentle-ai v1.47.0 (2026-07-10) with the first bounded native review transactions, and became the supported stable path in v2.2.0. The negotiated public review contract was published in v2.1.6.

A candidate line is open ahead of v2.4.0, so @latest and the latest RC no longer point at the same line: @latest still resolves to stable, and v2.5.0-rc.1 is reached only through its exact pin. The managed installer follows the newest channel version and does not accept an arbitrary release pin, so use go install to run the candidate, or whenever reproducibility requires an exact version. Use @main only to test changes that are not part of a release.

The beta-channel managed installer follows main and 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

Glossary

Candidate candidate

The exact set of bytes to be reviewed. It exists before the review begins and is frozen at START.

Lineage lineage

The identifier of a review transaction. It is captured at START and replicated unchanged in every later call. A burned lineage is never reused.

Receipt

The terminal evidence of a completed review transaction. It is informative: it never authorizes delivery. On approval, it is burned together with the authority. Retired in v2.5.0-rc.1, where the review closes at its terminal event without publishing one.

Lens lens

A read-only reviewer that judges one concern and emits strict JSON. The four canonical lenses are Risk, Resilience, Readability, and Reliability (4R).

Burn burn

The removal of the exact authority and its artifacts when a review is approved. No receipt, tombstone, witness, or mirror survives.

Projection projection

What START freezes: workspace (the entire workspace, default) or staged (exactly the Git index).

Gate

A named checkpoint — post-apply, pre-commit, pre-push, pre-pr, release. These are informative compatibility commands: they never allow or block delivery. Retired in v2.5.0-rc.1 together with compact receipts.

Candidate-caused finding

A finding introduced by the change. Only severe findings of this class can block. Pre-existing findings become follow-ups.

Correction budget

The line limit for the single permitted correction: min(200, ceil(original_changed_lines / 2)). It is frozen at START and is not recalculated.

Delta-spec

The partial specification for a change in progress. At archive time, it is merged into the project's main specs.

Escalated escalated

The state of a lineage whose correction failed with evidence. No other reviewer, refuter, correction, or validator starts: it requires an authorized successor through review recover.

Official documentation

This page summarizes the official Gentle AI documentation. If there is any discrepancy, the linked repository documents above are the source of truth. Gentle AI is distributed under the MIT License.