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 v3.4.0Go 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/v3/cmd/gentle-ai@latest

Notice the /v3 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.

Only an explicitly selected SDD workflow may run /sdd-init automatically when it needs context. Detectable tests do not enable Strict TDD: resolve its mode, source, and exact runner from project/session configuration or an explicit choice. 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 — optional evidence

Research is optional read-only work for a named uncertainty. It can inform ODD or explicitly selected SDD, but it is not an SDD phase or administrative contract.

How to use it

State the question and use only actually available, authorized tools. Prefer primary sources when they answer the question; do not infer access from a tool name or from an unavailable source class. When delegated, the dedicated collector is an output-only evidence collector: it does not read local artifacts or repository state, and the orchestrator supplies code context.

What it returns

Return concise, attributed evidence: material claims link to source URLs or code locations and distinguish verified facts, assumptions, contradictions, freshness, and explicit gaps. The parent handles any authorized persistence under existing project practices.

How it informs a proposal

Research supports a recommendation, tradeoffs, open questions, and implementation implications. Missing evidence is disclosed rather than invented; only an unsafe decision that depends on it pauses. Research does not create an SDD phase, contract, admission grant, persistence requirement, readiness gate, or proposal block.

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

Resolve Strict TDD from project/session configuration or an explicit choice, with its source and exact runner. Detectable test support alone does not activate it.

• When enabled, observe RED → GREEN → REFACTOR: add a focused behavior test, observe its failure, implement the minimum change, then keep focused checks green while improving clarity.
• When disabled, run ordinary functional checks; disabled TDD never means no checks.
• Record and forward the resolved mode, source, and exact runner to implementation work. For this project, openspec/config.yaml configures Strict TDD and npx playwright test is the runner.
• Unknown or conflicting mode, or a missing runner, fails closed to a clarification for the next action. Do not invent precedence, a command, or a /sdd-init run.

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 creates formal SDD artifacts only after an explicit request or an accepted proposal.

• For substantial authorized work, ODD persists continuity in odd/tasks/<feature>.md with an Engram mirror, then resumes unfinished work from those reconciled records.
• ODD uses the resolved configured TDD mode and its exact runner. The presence of tests alone does not silently enable TDD.
• Every completed ODD task closes with a reviewable work-unit commit on the feature branch.
• When RDD is enabled, each commit is assessed against the last reviewed boundary: high-risk commits review immediately, medium-risk work accumulates into reviewable PR slices, and chained PR strategy applies when needed.

When a trigger in the Delegation stop rules table fires, delegation is mandatory; the table defines those triggers without changing the implementation route.

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 resolves it in ODD through research, clarification, or Needs your decision; it does not offer or select formal SDD artifacts from ambiguity alone.

Delegation stop rules

The orchestrator must stop acting as a monolithic executor when complexity appears. These triggers are mandatory, not advisory:

Public states

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

The SDD status projection is the gentle-ai.sdd-status/v2 contract. Runtime state carries planning, task, verification, selected-untracked, and attempt truth, and it does not project active review bindings or receipts. Historical runtime records containing binding, receipt, or binding/set refuse rather than being replayed.

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 → terminal capture → approved pending exact acknowledgement → acknowledgement burns authority → ordinary repository policy

A terminal reviewer, refuter, validator, correction-plan, or zero-lens result records approved; the approved authority remains pending its exact acknowledgement. There is no separate FINALIZE step. No compact receipt or delivery authority survives.

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 and review capture-result carries those exact tokens. After terminal approval, bound STATUS reoffers the same acknowledgement while the authority remains pending. 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 awaits acknowledgement

Native code returns approved with one exact acknowledgement continuation. Only the exact acknowledgement continuation burns the authority: it validates the bound lineage, target, revision, and token, then removes that authority and its artifacts. A wrong, stale, or failed acknowledgement is non-mutating; bound STATUS reoffers the pending continuation. No compact receipt 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 compact review permits exactly one correction transaction. START freezes its correction budget at 0 for zero original lines; otherwise max(2, min(200, ceil(original_changed_lines / 2))). The old min(200, ceil(original_changed_lines / 2)) formula remains only for historical and non-compact authority.

• 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

Compact receipts and their delivery gates are retired. Delivery follows ordinary repository policy, and no receipt state counts as an approval.

gentle-ai review validate and its named gates — post-apply, pre-commit, pre-push, pre-pr, and release — survive only as 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. A projection only selects which bytes are frozen at START: compact receipts are retired, so no projection issues one.

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

Successful acknowledgement burns and removes approved authority. Retained, open, or degraded lineages can accumulate in a long-lived clone, so reset remains available for the authority that still exists.

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

ODD follows seven stages: authorize the request, explore, resolve uncertainty, classify the work, track substantial work before the first write, implement task by task, and close with verified results.

flowchart TD
    A["1. Authorize
change or read-only request"] --> B{"Authorized
implementation?"}
    B -->|"no"| Z["Read-only outcome"]
    B -->|"yes"| C["2. Explore
code and requirements"]
    C --> D["3. Resolve uncertainty
research, clarification, or challenge"]
    D --> E["4. Classify
small or substantial"]
    E -->|"substantial"| F["5. Track before the first write
feature document + Engram mirror"]
    E -->|"small"| G["6. Implement task by task
configured TDD + applicable checks"]
    F --> G
    G --> H["7. Close
verified outcome, checks, next step"]

    style H fill:#2B3328,stroke:#98BB6C,color:#DCD7BA
    style Z fill:#1F1F28,stroke:#54546D,color:#727169

Complete SDD workflow

First come durable planning artifacts, then apply. Verify is optional and does not gate Archive. It may suggest returning to Apply, but any report can proceed to Archive actual state. Archive can record unfinished work when the user chooses it. SDD never invokes RDD. 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["Optional Verify
practical diagnostics against
spec - design - tasks"]
    H --> R["Archive
merges delta specs - closes the cycle"]
    Q -->|"suggests rework"| H
    Q -->|"reports findings"| R
    Q -->|"complete"| R
    R --> S["Ordinary repository policy"]
    S --> T["Commit → Push → PR"]

    style R fill:#2B3328,stroke:#98BB6C,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 --verbose to inspect discovered models.
• Gentle AI sets SDD agent sharing to disabled by default for privacy; user-managed share values such as manual or auto are preserved.
• OpenCode V1 behavior remains unchanged. OpenCode V2 beta uses its own native configuration handling, managed plugins, and beta presentation.
• Unknown OpenCode versions fail closed. Native RDD review on OpenCode V2 remains unavailable in v3.4.0.

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:@juicesharp/rpiv-ask-user-question
pi install npm:pi-web-access
pi install npm:pi-btw

Discovering and running SDD agents from .pi/agents/ is provided by gentle-pi's Gentle Agents, which ships the same subagent_* tools that the retired companion package provided. When a settings file pins gentle-pi below 2.5.0, Gentle AI keeps npm:pi-subagents-j0k3r. For a current or unpinned install, or a gentle-pi pin at 2.5.0 or later, it removes npm:pi-subagents-j0k3r and npm:@juicesharp/rpiv-todo from settings.json on the next install or update so Pi uninstalls them on its next package sync.

Pi commands

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

v3.4.0 publishes eight assets under one signed checksum manifest: four platform .tar.gz archives for macOS and Linux (amd64 and arm64), gentle-ai-review-provider-contract-1.2.0.tar.gz, the release-provenance archive, checksums.txt, and checksums.txt.minisig. The checksum manifest covers the six archives and is authenticated by the Minisign signature.

Official macOS and Linux release files require that 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 trusted comment on v3.4.0: repo=Gentleman-Programming/gentle-ai;tag=v3.4.0
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. Until then, Windows installs from source with go install.

Version policy

v3.4.0 was released as stable on 2026-09-19. This page is a pinned snapshot of that release; its provider contract remains byte-frozen at 1.2.0.

@latest describes the stable channel and @main describes unreleased development. For this reproducible snapshot, install the exact release instead: go install github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai@v3.4.0.

Upgrading to v3.4.0

What's new

• review assess reports candidate.consumed, review_due, review_due_reason, and the exact next_transition for host routing.
• Pi refuter and validator roles are host-mediated.
• Each runtime proves its context fits within 200 KiB before START.

Breaking change: the RTK integration is retired.

Six fixes: OpenCode V1 lens-capture provider-task relay; VictoriaMetrics 64 MiB scrape ceiling; telemetry dedup retention and daily compaction; no OpenCode configuration when it is unselected; the native Claude discovery test gated at CLI v2.1.154; and Windows Full Suite test fixes.

After replacing the binary, run gentle-ai sync to install matching managed assets. The 1.2.0 provider contract remains byte-frozen.

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 bound call, including the pending acknowledgement. A burned lineage is never reused.

Approval

The terminal approved state pending its exact acknowledgement. It is not delivery authority.

Receipt

A historical terminal record. Compact review does not publish a receipt, and no receipt authorizes delivery.

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 after the exact acknowledgement succeeds. It is not a compact receipt or delivery authority.

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 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 compact correction: 0 for zero original lines; otherwise max(2, min(200, ceil(original_changed_lines / 2))). It is frozen at START; the old formula applies only to historical and non-compact authority.

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.