# gentle-pi: a senior-architect harness for the Pi coding agent

> gentle-pi is a Pi-native package that wraps the coding agent in Spec-Driven Development, subagent orchestration and review guardrails. It is built for teams who already use Pi and want the workflow around the model to be stricter, not the model itself.

**Gentleman-Programming/gentle-pi** — Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.

- Repository: https://github.com/Gentleman-Programming/gentle-pi
- Website: https://gentle-ai.gentlemanprogramming.com/
- Stars: 1,128 · Forks: 161
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/gentleman-programming-gentle-pi

## The operational failure gentle-pi is built to prevent

The README lists the failure modes it targets, and they are not model failures. An agent jumps into code before requirements are clear. Architectural decisions disappear into chat history. One request becomes a huge multi-area diff. Tests run late or not at all. Reviewers get a wall of changes. Subagents exist but the parent session has no orchestration discipline. Project skills exist but the model forgets to load them.

That list is worth reading carefully, because it defines the audience. gentle-pi is for engineers who already accept that a coding agent produces useful output but who keep losing the thread between sessions. The package does not try to make the model smarter. It installs what the README calls "a senior-architect operating layer": a persona, a set of phase agents, routing rules, and review evidence that is derived from Git rather than from the agent's own summary. If your pain is that the agent writes the wrong code, this is the wrong tool. If your pain is that the agent writes plausible code with no traceable requirements behind it, the design targets exactly that.

## How the SDD/OpenSpec phase chain and subagents fit together

The mechanism is a chain of named phases. The README states that the package installs phase agents and chains for init, onboard, explore, proposal, spec, design, tasks, apply, verify, sync and archive. Each name is a stage in a Spec-Driven Development flow, and the ordering matters: a proposal precedes a spec, a spec precedes design, design precedes tasks, and apply comes after tasks rather than before.

Around that chain sits work routing. Small tasks stay inline in the parent session. Context-heavy exploration can be delegated to a child agent. Large or risky changes go through SDD/OpenSpec. The README describes subagent orchestration as keeping one parent session responsible while child agents explore, implement, test or review with focused context. That is a deliberate constraint: the parent does not hand off ownership, it hands off context.

There is also a lazy preflight. On the first SDD invocation of every interactive session, the package confirms SDD mode, the artifact store, the delivery strategy and the review budget, including saved preferences. The word lazy is doing real work here. Nothing is asked until SDD is actually used, so a session that never touches the flow never pays the cost.

Strict TDD support is conditional. The README says the package enables it when project config declares a test command. That means TDD evidence is not automatic; it depends on configuration that the repository must supply.

## Installing gentle-pi and running a first SDD phase

gentle-pi is published to npm and also listed as a Pi package, so the install path depends on how you consume Pi packages. The npm route is the one the README badges point at.

```bash
npm install gentle-pi
```

The package.json declares a postinstall script, `node scripts/install-gentle-ai.mjs`, which runs automatically after the install. That script is where the Gentle-AI side of the setup is wired in, so an install that skips lifecycle scripts will leave the package present but not fully configured. If your environment sets `--ignore-scripts`, account for it.

After installation, the SDD flow is driven through the phase names rather than a single command. The README lists init and onboard as the first two phases, which is the order a new project would follow: init establishes the SDD artifacts, onboard brings an existing codebase into them. The first SDD invocation in an interactive session triggers the preflight described above, and you should expect to answer questions about SDD mode, artifact store, delivery strategy and review budget before any phase work begins.

To confirm what the package ships, the package.json files array is the authoritative list: assets, contracts, docs, extensions, lib, prompts, runtime, skills, scripts, tests, themes and README.md. Anything outside that list is not in the published tarball.

## The preflight is a gate, not a suggestion

The lazy SDD preflight is the design choice most likely to annoy a new user, and it is worth being direct about why. It confirms four things on the first SDD invocation of every interactive session: SDD mode, artifact store, delivery strategy and review budget. Saved preferences are respected, but the confirmation still happens.

The trade-off is real. A developer who wants to move fast inside a session will hit a prompt they did not ask for, and the package offers no documented way to bypass the preflight entirely. What it buys is consistency: the artifact store and delivery strategy cannot silently drift between sessions, which is precisely the failure the README describes as architectural decisions disappearing into chat history. If your team treats the agent as a scratchpad, this gate is friction with no payoff. If your team treats SDD artifacts as reviewable output, the gate is the point.

The second limitation is narrower but sharper. Strict TDD evidence depends on project config declaring a test command. A repository that has never declared one gets no TDD enforcement from this package, regardless of what the persona says.

## gentle-pi compared with Gentle-AI and plain Pi

The README positions gentle-pi as "the Pi-native package from the Gentle-AI ecosystem". That distinction is the alternative worth understanding. Gentle-AI is described as 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. gentle-pi is the Pi-specific member of that family.

The practical difference is scope. Gentle-AI spans multiple agents; gentle-pi commits to one. That means gentle-pi can install Pi-specific phase agents, a Pi startup intro with a rose text logo and compact runtime panel, and Pi skill discovery, none of which a cross-agent layer would express the same way. It also means the package is not portable. If your organisation runs more than one coding agent and wants one workflow across all of them, gentle-pi is the wrong layer and Gentle-AI is the one to evaluate.

The comparison against plain Pi is easier. Pi already has strong tools, as the README concedes. gentle-pi adds discipline around them. Nothing in the package replaces Pi's tooling; the phase agents, subagent orchestration and review guardrails sit on top.

## Licence, maintenance and what upgrades cost you

The code is MIT licensed, and the package.json confirms the license field. There is a separate trademark notice in TRADEMARKS.md: the gentle-pi name and logo are trademarks of Alan Buscaglia, and the README states that the MIT License applies to the code but does not permit implying endorsement or official affiliation. That is a normal arrangement, and it matters if you plan to fork under the same name. It is not legal advice; read TRADEMARKS.md yourself if branding is in scope.

Maintenance is current. The most recent release listed is v2.5.0 on 2026-09-08, and the last push to the default branch was on 2026-09-10. The repository is not archived. Note that package.json declares version 2.7.0 while the newest release listed is v2.5.0, so the published version may run ahead of the release notes you are reading.

Upgrade cost is concentrated in two places. The postinstall script runs on every install, so a change to `scripts/install-gentle-ai.mjs` affects your setup step directly. And the prepack and prepublishOnly scripts chain the test suite, a runtime module check and a package file check before anything ships, which tells you the maintainers treat packaging as a gated operation. For consumers, the practical implication is that a version bump can change generated assets, not just library code.

## Conclusion

Adopt gentle-pi if your team already runs Pi and wants SDD artifacts, subagent orchestration and Git-derived review evidence instead of chat narration; the package installs through npm and its postinstall script pulls in the Gentle-AI assets. Do not adopt it if you use a different coding agent, since the README describes it as Pi-native, or if you cannot accept an interactive preflight on the first SDD call of each session. Verify the Node version your Pi install requires, check the postinstall script's behaviour in your environment, and read the package.json scripts to confirm the test and packaging commands match your CI.

## FAQ

### What is gentle-pi?

It is a Pi-native package that turns Pi into what the README calls a senior-architect development harness, adding SDD/OpenSpec phase agents, subagent orchestration, strict TDD support and review guardrails. It is part of the wider Gentle-AI ecosystem and is MIT licensed.

### How do I install gentle-pi?

The README badges point at npm, so the install is npm install gentle-pi. The package declares a postinstall script that runs node scripts/install-gentle-ai.mjs, so an install with lifecycle scripts disabled will not complete the Gentle-AI setup.

### Does gentle-pi work with agents other than Pi?

The README describes gentle-pi as the Pi-native package from the Gentle-AI ecosystem, with Pi-specific phase agents, startup intro and skill discovery. For work across multiple coding agents, Gentle-AI is the broader project the README points to.

### Is strict TDD always enforced?

No. The README states that strict TDD support applies when project config declares a test command, so a repository without one gets no TDD enforcement from the package.

## Sources

- [Gentleman-Programming/gentle-pi on GitHub](https://github.com/Gentleman-Programming/gentle-pi)
- [License: MIT](https://github.com/Gentleman-Programming/gentle-pi/blob/main/LICENSE)
- [Project website](https://gentle-ai.gentlemanprogramming.com/)
- [README](https://github.com/Gentleman-Programming/gentle-pi/blob/main/README.md)
- [Releases](https://github.com/Gentleman-Programming/gentle-pi/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gentleman-programming-gentle-pi