Gentle-Pi: Transforming Vibe Coding with Spec-Driven Development, Strict TDD, and Subagent Orchestration

The emergence of vibe coding—authoring software through conversational prompts and delegating code generation to AI models—has enabled founders and development teams to prototype features at unprecedented speeds. However, in enterprise environments and long-lived codebases, unstructured vibe coding quickly triggers operational collapse:

• The AI begins generating code before project specifications are fully established.
• Architectural decisions vanish as conversation histories are truncated.
• A minor feature request silently turns into an uncontrolled 1,000-line diff spanning 15 different files.
• Tests are executed late or completely omitted.
• Human reviewers are confronted with opaque walls of code that are painful to audit.

To address this challenge at its root, the team at Gentleman Programming (led by Alan Buscaglia) built gentle-pi, a native Pi package that transforms raw AI coding agents into a disciplined engineering harness powered by Spec-Driven Development (SDD), Strict TDD, and multi-lens review guardrails.

In this technical guide, we break down its architecture, installation workflow, and how engineering teams can apply it to build production-grade software without accumulating technical debt.

1. What is gentle-pi and How Does It Structure Vibe Coding?

gentle-pi is not merely a collection of prompts; it is a comprehensive runtime operating layer that equips Pi with the persona and rigor of a senior technical architect (el Gentleman):

The harness enforces four non-negotiable engineering pillars:

1. Work Routing Discipline

The harness evaluates the complexity and risk of every incoming task before writing code:

• Small, localized edit: Handled directly in the primary session thread.
• Context-heavy investigation (reading 4+ files): Automatically delegated to read-only subagents (scouts or context-builders) to preserve parent session memory.
• High-risk or architectural modification (modifying 2+ core files): Obligatorily routed through a Spec-Driven Development (SDD / OpenSpec) pipeline.

2. Spec-Driven Development (SDD / OpenSpec)

Instead of relying on ephemeral chat context, gentle-pi breaks complex features into Git-versioned specification artifacts:

Explore ➔ Proposal ➔ Spec ➔ Design ➔ Tasks ➔ Apply ➔ Verify ➔ Sync

If the session restarts or the model compacts its memory window, architectural decisions and task checklists remain securely recorded in the repository.

3. Strict TDD (Test-Driven Development)

When a project declares an automated test command, the agent must generate verifiable evidence following the classic cycle:

RED (Write failing test) ➔ GREEN (Minimal code to pass) ➔ TRIANGULATE (Edge cases) ➔ REFACTOR (Clean code)

4. The 4R Native Review Framework

Before changes are merged, the code undergoes scrutiny across four distinct evaluation lenses:

• review-readability: Clear naming conventions, file structure, and style guide adherence.
• review-reliability: Determinism, regression testing, and error handling coverage.
• review-resilience: Partial failure tolerance, process decoupling, and recovery mechanics.
• review-risk: Security boundaries, permissions, secret exposure, and dependency vulnerabilities.

2. Installation and Initial Configuration

Installing gentle-pi is performed directly on the Pi runtime via npm:

# 1. Install gentle-pi
pi install npm:gentle-pi@0.14.0

# 2. Install recommended ecosystem companion packages
pi install npm:pi-subagents-j0k3r
pi install npm:pi-intercom
pi install npm:gentle-engram
pi install npm:pi-web-access
pi install npm:pi-lens

Initializing the Harness in Your Repository

Launch Pi in the root directory of your repository and run the diagnostic commands:

/gentle:status          # Checks package state, OpenSpec assets, and model bindings
/gentle:doctor          # Runs read-only diagnostics on tools, guards, and configs
/sdd-init               # Initializes openspec/config.yaml in the repository
/gentle:models          # Assigns specific models and effort tiers to subagents
/gentle:persona         # Toggles between 'gentleman' and 'neutral' persona modes

3. Practical Example: Building an Enterprise Feature with SDD and TDD

Suppose your organization needs to implement an automated invoice validation service for VeriFactu e-invoicing or connect internal databases via Executor.sh / MCP gateways.

Rather than asking the agent to "write an invoice validation script", the gentle-pi harness enforces disciplined execution:

// invoice-validator.test.ts (TDD Evidence - RED Phase)
import { describe, it, expect } from "vitest";
import { validateInvoicePayload } from "./invoice-validator";

describe("Strict VeriFactu Invoice Validation", () => {
  it("should reject invoices with malformed issuer Tax IDs", () => {
    const invalidInvoice = {
      nifEmisor: "123456", // Invalid tax ID format
      totalFactura: 150.00,
      cuotaIva: 31.50,
    };

    const result = validateInvoicePayload(invalidInvoice);
    expect(result.isValid).toBe(false);
    expect(result.errorCode).toBe("INVALID_ISSUER_NIF");
  });

  it("should correctly compute 21% VAT breakdowns", () => {
    const validInvoice = {
      nifEmisor: "B12345678",
      baseImponible: 100.00,
      tipoIva: 0.21,
      cuotaIva: 21.00,
      totalFactura: 121.00,
    };

    const result = validateInvoicePayload(validInvoice);
    expect(result.isValid).toBe(true);
  });
});

Once the testing subagent confirms that tests fail for the right reasons (RED), the implementation worker implements minimal code to pass (GREEN), adds boundary condition tests (TRIANGULATE), and applies the 4R review lenses prior to commit.

4. Multi-Model Routing for Performance and Cost Optimization

A core architectural capability of gentle-pi is assigning specialized models to specific subagents via /gentle:models:

This tiered setup reduces API costs by over 75% compared to monolithic commercial models and can run locally on workstations like the Apple Mac Studio M5 or private European clusters like NaN Builders.

5. Strategic Benefits for SMEs and Software Engineering Teams

For small development teams and technical founders, adopting gentle-pi delivers three immediate advantages:

1. Eliminating Invisible Technical Debt: AI-generated code often functions initially but breaks later due to missing edge-case handling or unmanaged dependencies. gentle-pi mandates documentation and automated test verification.
2. Accelerated Developer Onboarding: Specification artifacts stored in openspec/ enable new engineers to understand architectural decisions without reverse-engineering thousands of lines of code.
3. Safe Production Execution: Built-in runtime guards block hazardous shell commands (rm -rf, unverified secret edits, or sensitive file overwrites).

6. Strategic Takeaway

Unstructured vibe coding was the initial step in AI-assisted programming. To deliver production-ready enterprise software, organizations must transition toward disciplined engineering harnesses.

gentle-pi demonstrates the optimal path forward: rigorous specifications, strict test-driven validation, and structured subagent orchestration.

Transform Your AI Software Engineering Workflows with IA4PYMES → We build custom agentic development harnesses, implement automated testing pipelines, and train engineering teams in modern AI architecture best practices.

7. Frequently Asked Questions

Is gentle-pi compatible with IDEs like Cursor or VS Code?

gentle-pi is built natively for the Pi CLI environment, but its output artifacts (openspec/ markdown and YAML files) are open standards fully compatible with Cursor, Windsurf, or Claude Code.

What happens if my repository has no existing test suite?

The harness operates flexibly, but will notify developers of missing test configurations (npm test, pytest, cargo test) and propose creating a baseline test suite during the specification phase.

Is gentle-pi free and open-source?

Yes. gentle-pi is licensed under the MIT License and can be utilized with both commercial APIs and self-hosted open-weights models without additional software licensing fees.