# Gentle Pi > Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery. - **Type:** MCP server - **Install:** `agentstack add mcp-gentleman-programming-gentle-pi` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Gentleman-Programming](https://agentstack.voostack.com/s/gentleman-programming) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Gentleman-Programming](https://github.com/Gentleman-Programming) - **Source:** https://github.com/Gentleman-Programming/gentle-pi - **Website:** https://gentle-ai.gentlemanprogramming.com/ ## Install ```sh agentstack add mcp-gentleman-programming-gentle-pi ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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](https://gentle-ai.gentlemanprogramming.com/)** • **[Gentle-AI wiki](https://gentle-ai-wiki.gentlemanprogramming.com/)** • **[Engram](https://engram.gentlemanprogramming.com/)** **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](https://github.com/Gentleman-Programming/gentle-ai), built by [Gentleman Programming](https://github.com/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](https://github.com/Gentleman-Programming) - YouTube: [Gentleman Programming](https://www.youtube.com/c/GentlemanProgramming) - Community Discord: [Gentleman Programming](https://discord.com/invite/gentleman-programming-769863833996754944) Startup intro collaboration: thanks to [@aporcelli](https://github.com/aporcelli) for [`pi-gentle-startup`](https://github.com/aporcelli/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: ```ts 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 ```bash 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`. ```bash # 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: ```bash 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: ```bash 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 ```text /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](https://github.com/Gentleman-Programming/gentle-ai/blob/main/docs/review-authority-threat-model.md) and [Chapter 21 — Verifiable Trust](https://the-amazing-gentleman-programming-book.vercel.app/en/book/Chapter21_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: ```text 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](https://github.com/Gentleman-Programming) - **Source:** [Gentleman-Programming/gentle-pi](https://github.com/Gentleman-Programming/gentle-pi) - **License:** MIT - **Homepage:** https://gentle-ai.gentlemanprogramming.com/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-gentleman-programming-gentle-pi - Seller: https://agentstack.voostack.com/s/gentleman-programming - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.