📐 Overview

pi-spec-builder brings structured Spec-Driven Development (SDD) and architectural guardrails to Pi Coding Agent.

Left unchecked, AI coding agents frequently begin editing code immediately without clarifying requirements, designing interface contracts, or considering failure modes.

pi-spec-builder enforces a battle-tested 3-phase development lifecycle inside .specs/<feature>/:

1. Proposal: Clarify user problem, non-goals, and tradeoffs.
2. Specification: Detail TypeScript interface contracts, data models, and Mermaid architecture diagrams.
3. Tasks: Break work into atomic, verifiable checklists.

Code modification is gated until you review and approve the architectural specification.

┌─────────────────┐       /sdd init feature      ┌─────────────────────────┐
│                 │ ───────────────────────────> │  01-proposal.md         │
│                 │                              │  (Problem & Non-Goals)  │
│                 │ <─────────────────────────── └───────────┬─────────────┘
│                 │     /sdd approve proposal                │
│    Developer    │                                          ▼
│    (Terminal)   │                              ┌─────────────────────────┐
│                 │                              │  02-specification.md    │
│                 │                              │  (Interfaces & Mermaid) │
│                 │ <─────────────────────────── └───────────┬─────────────┘
│                 │     /sdd approve spec                    │
│                 │                                          ▼
│                 │                              ┌─────────────────────────┐
│                 │                              │  03-tasks.md            │
│                 │                              │  (Implementation Phase) │
└─────────────────┘                              └─────────────────────────┘

✨ Features

• 📑 Standardized SDD Artifacts: Automatically structures proposals, specs, and task lists.
• 🚦 Phase Transition Gates: Tracks approval states per feature in .specs/status.json.
• 📊 Architecture Diagrams: Integrated Mermaid boilerplate for sequence and component flows.
• 🛡️ Autonomous Guard (sdd_check_guard): Pi self-audits whether sign-off was given before making edits.

🚀 Installation

Via Pi Package Registry (Recommended)

pi install npm:pi-spec-builder

Direct from GitHub

pi install git:https://github.com/lleontor705/pi-spec-builder.git

From Local Source

git clone https://github.com/lleontor705/pi-spec-builder.git
cd pi-spec-builder
npm install && npm run build
pi install ./

📖 Usage & Commands

Slash Commands

| Command | Description | | :--- | :--- | | /sdd init <feature> | Scaffolds .specs/<feature>/ with standard markdown templates. | | /sdd status | Displays active features and their current phase / approval status. | | /sdd approve <feature> proposal | Approves Phase 1 (Proposal) and moves to Specification. | | /sdd approve <feature> specification | Approves Phase 2 (Spec) and unlocks code implementation. |

Agent Autonomous Tools

• sdd_init_feature: Pi initializes an SDD feature folder when tasked with a complex goal.
• sdd_check_guard: Pi checks if the specification is approved before touching source code.

// Prompt:
"We need to implement a rate-limiter using sliding-window Redis counters."

Pi creates .specs/rate-limiter/01-proposal.md and pauses:

"I have drafted the proposal in .specs/rate-limiter/01-proposal.md. Run /sdd approve rate-limiter proposal when you're ready to proceed to API specifications."

🏗️ Architecture & Development

# Clone
git clone https://github.com/lleontor705/pi-spec-builder.git
cd pi-spec-builder

# Install & Build
npm install
npm run build

📄 License

MIT © Luis Leon