Gentle Pi

gentle-pi

[](https://www.npmjs.com/package/gentle-pi) [](https://pi.dev/packages/gentle-pi) [](LICENSE) [](https://github.com/Gentleman-Programming/gentle-pi/stargazers) [](https://github.com/Gentleman-Programming/gentle-ai) [](https://github.com/Gentleman-Programming) [](https://www.youtube.com/c/GentlemanProgramming) [](https://discord.com/invite/gentleman-programming-769863833996754944) [](#sddopenspec-flow) [](#what-it-adds)

Gentle-AI website • Gentle-AI wiki • Engram

Turn Pi from a powerful coding agent into a controlled development harness.

gentle-pi installs el Gentleman in Pi: a senior-architect operating layer for Spec-Driven Development, focused subagents, strict TDD evidence, reviewable work units, safety guards, project/user skill discovery, and bounded native review.

Pi already has strong tools. gentle-pi adds the discipline for using them well, keeps review evidence Git-derived instead of agent narration, and leaves delivery decisions to ordinary repository policy.

gentle-pi is the Pi-native package from the Gentle-AI ecosystem, built by Gentleman Programming: the broader open-source project for turning AI coding agents into disciplined engineering environments with SDD workflows, skills, memory integrations, model routing, and review guardrails across multiple agents.

> Trademark notice: The gentle-pi name and logo are trademarks of Alan Buscaglia. The MIT License applies to the code; it does not permit implying endorsement or official affiliation. See [TRADEMARKS.md](TRADEMARKS.md).

Follow the project and the community around it:

• GitHub: Gentleman-Programming
• YouTube: Gentleman Programming
• Community Discord: Gentleman Programming

Startup intro collaboration: thanks to @aporcelli for pi-gentle-startup, which inspired the clean-screen startup animation, compact runtime panel, and pink visual treatment.

The problem

Most coding-agent sessions fail for operational reasons, not model reasons:

• the agent jumps into code before requirements are clear;
• architectural decisions disappear into chat history;
• one request quietly becomes a huge multi-area diff;
• tests run late, or not at all;
• reviewers get handed a wall of changes;
• subagents are available, but the parent session has no orchestration discipline;
• project skills exist, but the model forgets to load them.

gentle-pi fixes the workflow around the agent.

What it adds

| Capability | What it does | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | el Gentleman persona | Makes Pi behave like a senior architect and teacher, not a generic chatbot. Spanish responses use Rioplatense voseo by default; neutral mode is saved globally with project overrides. | | Configurable startup intro | Adds a rose/text-logo startup intro, compact runtime panel, color presets, and commands to hide or show the decorative parts. | | Work routing discipline | Small tasks stay inline. Context-heavy exploration can be delegated. Large or risky changes go through SDD/OpenSpec. | | SDD/OpenSpec assets | Installs phase agents and chains for init, onboard, explore, proposal, spec, design, tasks, apply, verify, sync, and archive. | | Lazy SDD preflight | Resolves SDD mode, artifact store, delivery strategy, and review budget once per session; prompts only when a choice is genuinely unresolved. | | Subagent orchestration | Keeps one parent session responsible while child agents explore, implement, test, or review with focused context. | | Strict TDD support | When project config declares a test command, apply/verify phases must record RED → GREEN → TRIANGULATE → REFACTOR evidence. | | Closed choice prompts | Per-option hover/click/wheel in fullscreen; keyboard selection in either TUI mode. | | Native pointer regions | Compose hover, press, click, and wheel behavior around public TUI components. | | Reviewer protection | Surfaces review workload risk before a task turns into an oversized PR. | | Per-agent model assignment | Pi-native modal for assigning stronger or cheaper models to specific SDD/custom agents. | | Skill discovery registry | Maintains .atl/skill-registry.md from project and user skills so review/comment/PR workflows do not silently miss the right skill. | | Skill creation workflow | Provides the gentle-ai-skill-creator/gentle-ai-skill-improver skills, /skill-creation prompt, and packaged style guide for LLM-first skills. | | Delivery skills | Includes issue-first PRs, chained PRs, work-unit commits, cognitive docs, comment writing, and Judgment Day review. | | Bounded native review | Freezes one candidate, dispatches only controller-selected lenses, and records native authority. Review outcomes are informational; delivery follows ordinary repository policy. | | Verified native runtime | Provisions the exact package-local Gentle AI v2.6.0 runtime: signed, SHA-256-pinned release archives on Darwin/Linux and a Go SumDB-verified source build on Windows x64/arm64. It validates package-local integrity and rejects PATH, global, sibling, symlink, and mode fallbacks. | | Runtime safety | Blocks destructive shell commands, asks for confirmation for sensitive operations, and blocks direct read/write/edit access to sensitive paths. |

Native pointer regions

Compose pointer behavior around public Text, Box, or custom content without making it a keyboard target:

const scope = createNativePointerScope();
const openInput = scope.wrap(new Text("Open input", 0, 0), {
  onClick: () => {
    openInputEditor();
    return { handled: true };
  },
});
const panel = new Container();
panel.addChild(openInput);
const observer = scope.createMouseObserver(() => tui.requestRender());

Pass observer around the root's native mouse dispatch; reuse panel as custom or overlay content. Pointer input is fullscreen-only. Regions preserve a consuming child's native result and do not focus Text, activate on press or wheel, synthesize outside leave events, or alter terminal tracking. Callers own keyboard policy, theme state, and business actions.

Migration note: Do not enable pi-tool-cards and quiet-tools together: Pi rejects duplicate bash, read, edit, and write registrations. Disable or remove the standalone package during migration; gentle-pi does not alter user configuration or delete that repository.

Install

pi install npm:gentle-pi@0.14.0

RDD version policy

Native RDD started in gentle-pi v0.15.0 on 2026-07-10 with bounded review transactions. Every release from v0.15.0 onward is part of the unstable RDD development line. New releases will continue improving RDD until the project declares the line stable. The stable version for normal use without native RDD is the last preceding release, v0.14.0.

# Stable version without native RDD
pi install npm:gentle-pi@0.14.0

# Latest released RDD build (unstable)
pi install npm:gentle-pi@latest

The latest RDD package installs Gentle AI only into its private .gentle-ai/ directory. Darwin and Linux use pinned release assets with asset and executable SHA-256 verification (signed archives for stable pins such as the current v2.6.0; raw prerelease binaries only under a prerelease pin). Windows x64 and arm64 build the exact v2.6.0 source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, GOTOOLCHAIN=local, and GOSUMDB=sum.golang.org; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, not Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private node_modules is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses PATH or a global gentle-ai installation. For development or offline installs only, set GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1; native review operations then fail closed with an actionable package-local-binary-missing error until the package is reinstalled normally.

Recommended companion packages:

pi install npm:pi-intercom
pi install npm:gentle-engram
pi install npm:pi-web-access
pi install npm:pi-lens
pi install npm:@juicesharp/rpiv-ask-user-question

Then start Pi in a project:

pi

gentle-pi provides SDD agents as global Pi runtime assets, not per-project setup. The first SDD flow in a session still runs a one-time SDD preflight for preferences; for natural-language requests, el Gentleman decides when SDD is needed and runs the explicit preflight first.

Quick start

/gentle:status          Check package, SDD assets, OpenSpec, and global model config.
/gentle:doctor          Run read-only diagnostics for SDD assets, config, tools, and guards.
/gentle:sdd-preflight   Run or reuse the session SDD preflight explicitly.
/gentle-sdd-init           Create or refresh openspec/config.yaml (openspec/both stores only).
/gentle:models             Assign global model/effort routing to SDD/custom agents.
/gentle:persona            Switch between gentleman and neutral persona modes.
/gentle:background-subagents  Show or set the managed background-subagents policy, with its deciding source.
/gentle:banner             Configure startup rose, text logo, and color preset.

Typical flow:

1. Open Pi in your repo.
2. Run /gentle:status.
3. Run /gentle-sdd-init once per project, or when test/project capabilities change. This also runs the session SDD preflight.
4. For a substantial change, ask Pi to use SDD. Natural-language requests are classified by the parent agent, not by brittle runtime regexes.
5. Review the phase artifacts instead of trusting floating chat context.

Core workflow

1. Install and inspect. Install gentle-pi, open Pi in the target repository, then run /gentle:status or /gentle:doctor.
2. Plan when risk justifies it. Small work stays direct; substantial work uses SDD with Engram, OpenSpec, or both so requirements and decisions survive compaction.
3. Build with evidence. One focused writer implements the approved scope. When Strict TDD is available, apply and verify preserve RED → GREEN → TRIANGULATE → REFACTOR evidence.
4. Use runtime-owned RDD when available. Gentle AI supplies any runtime-specific review instructions; this package does not recreate a lifecycle in documentation or prompts.
5. Deliver through ordinary repository policy. Review and Judgment Day evidence is informational only; Pi never creates a delivery route, authorization, target rederivation, or receipt gate.

> Trust what the system can derive, not what an agent claims. Agents analyze the candidate. The package-local Gentle AI runtime owns scope, risk, findings, and review authority. Review outcomes inform delivery; ordinary repository policy decides delivery commands. Dangerous-command safety and destructive-review consent remain independent. See Gentle AI's review authority threat model and Chapter 21 — Verifiable Trust.

How the harness decides what to do

gentle-pi routes through the smallest safe workflow:

| Request shape | Harness | | --------------------------------------------------------------------------- | ---------------------------- | | Small, clear, local edit | Inline direct work. | | Unknown codebase area or context-heavy investigation | Focused subagent delegation. | | Large, ambiguous, architectural, product-facing, or high-review-risk change | SDD/OpenSpec flow. |

The goal is not ceremony. The goal is to avoid accidental chaos. Once a task stops being small, delegation is mandatory.

Delegation triggers

gentle-pi keeps the parent session thin and delegates at the narrowest useful point. When the Pi Subagents extension is installed, the preferred runtime is the subagent_* tool family because it runs the user's configured project/global subagent definitions and preserves history/background behavior. With the background policy on, delegations default to background mode: the terminal stays free and each result comes back as a message that starts a new turn; task mode is reserved for delegations that must ask the user something mid-flight. If those tools are unavailable, the parent should fall back to Pi's native Agent tool or another available delegation mechanism. The requirement is delegation; the runtime is capability-dependent.

| Trigger | Required behavior | | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | Reading 4+ files to understand a flow | Launch scout, context-builder, or the closest read-only mapping subagent. | | Touching 2+ non-trivial code files | Delegate one writer; do not continue inline unless delegation is unavailable. | | Commit, push, or PR after code changes | Follow the loaded native instruction, or ordinary repository policy when none is supplied. | | Wrong cwd, worktree/git accident, merge recovery, confusing test/env issue | Stop, preserve the affected scope, and investigate separately before resuming. | | Long monolithic session with accumulating complexity, roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits | Pause and delegate the remaining work, or stop and explain the exact blocker. |

The intended balanced loop for a bounded bugfix is:

parent git/status + clarify → one worker writes authorized fixes → focused verification → parent reports

scout/context-builder save parent context by compressing broad exploration. worker preserves a single writer thread. Any RDD-specific actor behavior belongs to the runtime ins

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Gentleman-Programming
• Source: Gentleman-Programming/gentle-pi
• License: MIT
• Homepage: https://gentle-ai.gentlemanprogramming.com/

Install and usage instructions live in the source repository linked above.