gentle-pi: a Pi package that turns a coding agent into a spec-driven workflow

The failure mode gentle-pi is built around

The README lists the problems it targets, and they are all operational rather than model-related: 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 exist but the parent session has no orchestration discipline, and project skills exist but the model forgets to load them. That list is the product spec. gentle-pi does not claim to make the underlying model smarter. It claims to fix the workflow around the agent, which is a narrower and more defensible promise. The intended user is someone already running Pi who has watched a session produce a large diff nobody asked for, or watched a test suite get written after the implementation rather than before it. If that has never happened to you, the package has little to sell you.

What el Gentleman actually adds on top of Pi

The README describes gentle-pi as installing el Gentleman in Pi: a senior-architect operating layer. The pieces are a persona, a configurable startup intro, work routing discipline, SDD/OpenSpec assets, a lazy SDD preflight, subagent orchestration, and strict TDD support. Two of those deserve attention. Work routing discipline is the rule that small tasks stay inline, context-heavy exploration can be delegated, and large or risky changes go through SDD/OpenSpec. That is a triage rule, not a feature toggle, and it only works if the agent applies it consistently. The SDD/OpenSpec assets install phase agents and chains for init, onboard, explore, proposal, spec, design, tasks, apply, verify, sync, and archive. That is a named lifecycle with eleven phases, which is a lot of ceremony for a two-line bug fix and roughly the right amount for a change that touches several subsystems. The persona also has a language dimension: Spanish responses use Rioplatense voseo by default, and neutral mode is saved globally with project overrides. That is a real configuration surface, not decoration, and it implies the project expects a Spanish-speaking user base alongside an English-speaking one.

The lazy SDD preflight is the load-bearing piece

According to the README, the lazy SDD preflight confirms SDD mode, artifact store, delivery strategy, and review budget on the first SDD invocation of every interactive session, including saved preferences. Read that as four decisions made once per session rather than once per prompt. The artifact store matters most: it determines where specs, proposals and designs are written, so it decides whether SDD output is repository content your team can review in a pull request or ephemeral state that vanishes with the session. The review budget is the second: it bounds how much change lands in one reviewable unit, which is the direct answer to the wall-of-changes complaint. Delivery strategy is the third, and it is the one the README is most careful about. It states that gentle-pi keeps review evidence Git-derived instead of agent narration and leaves delivery decisions to ordinary repository policy. That is a deliberate boundary. The package will not tell you how to merge, deploy or gate; it will only try to make sure the evidence a reviewer sees comes from Git rather than from the agent's own summary of what it did. If you have ever read an agent's confident description of changes it did not actually make, that boundary is the reason to care.

Getting it running and what you configure

The README shows npm and Pi package badges pointing at the npm registry and at pi.dev/packages/gentle-pi, so installation goes through the Pi package channel rather than a bespoke installer. The README does not print a full install command in the material available here, so treat the exact invocation as something to confirm on the package page rather than something to guess. What is documented is the configuration surface. Project config can declare a test command, which is what strict TDD support keys off; the README's sentence on this is cut off mid-clause, so the precise behaviour when no test command is declared is not something I can state. The SDD preflight is where you set SDD mode, artifact store, delivery strategy and review budget, and saved preferences mean those answers persist across sessions rather than being re-asked. Language mode is set globally with per-project overrides. Commands exist to hide or show the decorative startup parts, which matters more than it sounds: a runtime panel and startup animation that cannot be turned off are the kind of thing that gets a tool uninstalled in a shared terminal.

Where it is the wrong tool

Eleven SDD phases, a preflight, a persona layer and subagent orchestration are overhead. For a one-file change, the routing rule says small tasks stay inline, so the ceremony is supposed to be skipped, but that depends on the agent correctly classifying the task as small. Misclassification in either direction is the obvious failure mode: a genuinely large change routed inline produces exactly the multi-area diff the package exists to prevent, and a small change routed through proposal, spec, design and tasks burns a session on paperwork. The second limitation is adoption cost. Strict TDD support only means something if the project config declares a test command that reflects what CI actually runs; a test command that exists only to satisfy the harness produces evidence that proves nothing. The third is that SDD artifacts need a home. If the artifact store points somewhere the team does not read, you have added files to the repository without adding review surface. None of this is a defect in the code. It is the price of the approach, and it is paid in discipline rather than in compute.

How it compares to a plain agent loop

The alternative is Pi with no harness: you prompt, the agent edits, you read the diff. That approach is faster to start and has no configuration surface at all. Its weakness is precisely the list in gentle-pi's problem section. Nothing in a bare loop forces requirements to be written down before code, nothing bounds the size of a change, and nothing makes the agent load project skills it was told about. A second alternative is putting the same discipline in your own prompt templates and repository conventions without installing a package. That keeps you free of an external dependency and its update cadence, but you own the phase definitions, the routing rules and the review budget yourself, and you will be reimplementing the preflight logic that gentle-pi already ships. The honest difference is that gentle-pi encodes a specific opinion about how much process a change deserves, and adopting it means adopting that opinion rather than writing your own.

Maintenance, licensing and the trademark carve-out

The package is MIT licensed, published on npm, and the release cadence visible in the material is brisk: v2.3.0, v2.4.0 and v2.5.0 landed within roughly a week of each other in September 2026, with the last push to main shortly after v2.5.0. Fast minor releases on a workflow tool mean your saved preflight preferences, config keys and phase names are the things most likely to move. Budget for reading release notes before upgrading, and expect the SDD phase set to be the least stable part of the surface. On licensing, the README carries an explicit trademark notice: the gentle-pi name and logo are trademarks of Alan Buscaglia, and while the MIT License covers the code it does not permit implying endorsement or official affiliation. If you fork, rebrand or ship this inside a product, read TRADEMARKS.md in the repository. That is a factual pointer, not legal advice; a lawyer is the right person to tell you what it means for your distribution. The package is also part of a wider Gentle-AI ecosystem with a website, a wiki and a separate Engram project, so some features may assume sibling components that are documented elsewhere.

Editorial conclusion

Adopt gentle-pi if you already run Pi and your sessions keep failing for operational reasons: unclear requirements, decisions lost in chat history, tests run late, or reviewers handed enormous diffs. Skip it if you want a lighter agent loop, if you do not use Pi at all, or if your team will not maintain SDD artifacts as real repository content. Verify three things before committing: that the test command your project config declares is the one you actually run in CI, that the SDD artifact store location matches where your team expects specs to live, and that the review budget configured during the lazy SDD preflight is one a human reviewer can genuinely absorb.

Official sources

1. Gentleman-Programming/gentle-pi on GitHub
2. License: MIT
3. Project website
4. README
5. Releases