L-Spec PI (Beta)

SDD (Spec-Driven Development) for PI.dev — new AND existing projects.

Don't know where to start? L-Spec maps existing code, builds documentation, and only then implements. Everything starts with spec, never with code.

Spec-Driven Development — never edit without spec. The sequential pipeline with blocking gates verifies spec, context, blast radius, and state before any change. Works on new projects (forward) and existing code (map). Mandatory research — the agent asks, never invents. No phase is skipped.

Install, Update, Uninstall

# Install
pi install npm:@by-lua/lspec-pi

# Update
pi update npm:@by-lua/lspec-pi

# Uninstall
pi uninstall npm:@by-lua/lspec-pi

Alternative (Git): curl -fsSL https://raw.githubusercontent.com/by-lua/lspec-pi/main/install.sh | bash

Subagents

by-lua/lspec-subagents — 9 specialized agents for the L-Spec flow (orchestrator, explorer, fixer, oracle, designer, librarian, observer, council, councillor). Each with optimized model (Claude Opus, Sonnet, GPT-4o-mini). Run in parallel via CodeX, Gemini, or any provider. Uses the same L-Spec PI native tools (cymbal_*, lsp_*). Ideal for deep research, parallel debugging, senior code review, or visual analysis of images/PDFs.

Optional Dependencies (Recommended)

Tool	Use	Agents
pi install npm:pi-cymbal	Code navigation	explorer, oracle, fixer, orchestrator
pi install npm:@davehardy20/pi-lsp-tools	LSP-powered code tools	explorer, fixer, oracle
pi install npm:pi-mermaid	Mermaid diagrams	orchestrator, designer

Each agent uses available tools with grep/read fallback if the package is not installed.

Usage Mode

Just say what you want:

/lspec I need to create the auth module
/lspec there's a bug in login that doesn't validate the token
/lspec add email validation to the registration form
/lspec refactor the payments service

L-Spec automatically detects context:

• Existing code, no spec → Map: maps the code, understands the structure, creates the spec, and helps you proceed. Use /lspec map to trigger.
• Existing code, with spec → runs normal flow: verifies state, proposes changes, applies with gates
• New project → Comprehensive Discovery: asks strategic questions to discover features, defines scope and structure

No configuration needed. No need to create files first. Just say what you want or what's broken — the flow adjusts itself.

---

What is SDD?

SDD is developing by specification first and code later. In L-Spec PI this means: adaptive discovery, clear requirements, atomic tasks, and verifiable execution.

Why SDD exists (and what you lose without it)?

Most AI sessions waste 40–60% of tokens on rework: ambiguity, rewriting, and "I thought that's what you meant". SDD reduces this waste by defining what will be done before implementation.

Without SDD you lose

• Scope clarity (project grows on the fly)
• Traceability (hard to prove what was validated)
• Continuity between sessions (each conversation starts from scratch)
• Delivery quality (more bugs, more rework, confusing commits)

With L-Spec PI you gain

• Adaptive discovery + clear requirements before coding
• Execution by atomic, verifiable tasks
• Less rewriting, fewer bugs, and cleaner commits
• Context living in the project (.specs/) and not just in the agent's memory

In L-Spec PI, project knowledge is versioned in the repository.
Any agent can continue from where it left off, without depending on a specific session's memory.

---

Complete Flow with Gates

┌─────────────────────────────────────────────────────────────────────────────────┐
│                        L-SPEC PI PIPELINE WITH GATES                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐   │
│  │DISCOVERY │───▶│ RESEARCH │───▶│ SPECIFY  │───▶│  TASKS   │───▶│ EXECUTE  │   │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘   │
│       │              │              │                           │              │
│       ▼              ▼              ▼                           ▼              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐              ┌──────────┐        │
│  │ DISCUSS* │    │ DISCUSS* │    │ CLARIFY* │              │  GATE    │        │
│  └──────────┘    └──────────┘    └──────────┘              │  CHECK   │        │
│       │              │              │                      └──────────┘        │
│       ▼              ▼              ▼                           │              │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐                  ▼              │
│  │  STATE   │    │  STATE   │    │  STATE   │              ┌──────────┐       │
│  │  GATE    │    │  GATE    │    │  GATE    │              │  COMMIT  │       │
│  └──────────┘    └──────────┘    └──────────┘              └──────────┘       │
│                                                                                  │
│  (*) OPTIONAL — only if gray/ambiguous area or architectural need              │
└─────────────────────────────────────────────────────────────────────────────────┘

Phase Table

┌────────────┬──────────────────────────────────────────────────────────────────────┐
│ PHASE      │ WHEN IT RUNS                                                        │
├────────────┼──────────────────────────────────────────────────────────────────────┤
│ Discovery  │ ALWAYS                                                              │
│ Research   │ ALWAYS (REQUIRED before Specify)                                   │
│ Discuss*   │ OPTIONAL — only if gray/ambiguous area                            │
│ Specify    │ ALWAYS (REQUIRED)                                                  │
│ Clarify*   │ OPTIONAL — only if ambiguity in requirements                       │
│ Design*    │ OPTIONAL — only if architectural need                              │
│ Tasks      │ ALWAYS                                                              │
│ Execute    │ ALWAYS                                                              │
└────────────┴──────────────────────────────────────────────────────────────────────┘

Auto-detection

• BUG → Short Discovery (3 questions) → Research → Tasks → Execute
• FEATURE → Focused Discovery → Research → Specify → Tasks → Execute
• NEW → 6 complete phases + Research

---

Don't know where to start? L-Spec maps existing code, builds documentation, and only then implements. Everything starts with spec, never with code.

How It Works

You: /lspec [request]

→ Discovery (asks what you want)
→ SAVE state
→ Research (analyzes code)
→ SAVE state
→ [Discuss?] (if there's ambiguity)
→ SAVE state
→ Specify (specifies requirements)
→ SAVE state
→ [Clarify?] (if there's ambiguity)
→ SAVE state
→ [Design?] (if there's architectural decision)
→ SAVE state
→ Tasks (breaks into tasks)
→ SAVE state
→ Execute (implements)
→ SAVE state
→ Done

SINGLE command: /lspec [what you want]

The system executes the ENTIRE pipeline in order, saving after each phase. Never asks which phase to run. Never skips. Never goes directly to code.

---

Artifact Enforcement

Each phase produces an artifact that the next one uses:

Discovery  → STATE.md       → Research
Research   → research.md     → Discuss?
Discuss    → discuss.md      → Specify
Specify    → spec.md         → Clarify?
Clarify    → clarify.md      → Design?
Design     → design.md       → Tasks
Tasks      → tasks.md        → Execute

No artifact = blocks. The phase doesn't start without the previous one's artifact.

---

Gates and Blockers (Enforcement)

L-Spec PI uses blocking gates to ensure quality. Each gate must pass before advancing.

1. Compliance Gate (Blocking)

Before ANY edit to code, execute the checklist:

┌────────────────────────────────────────────────────────────────┐
│ COMPLIANCE GATE CHECKLIST                                      │
├────────────────────────────────────────────────────────────────┤
│ [ ] 1. Discovery complete — context collected                  │
│ [ ] 2. Clear requirements — spec.md exists                    │
│ [ ] 3. Design verified — design.md exists (if applicable)    │
│ [ ] 4. Tasks approved — tasks.md with defined artifacts      │
│ [ ] 5. State updated — STATE.md reflects current state        │
└────────────────────────────────────────────────────────────────┘

If any item ❌ → BLOCKS. Resolve before editing.

2. State Saved Gate (Blocking)

Between each phase, verify:

┌────────────────────────────────────────────────────────────────┐
│ STATE SAVED GATE                                               │
├────────────────────────────────────────────────────────────────┤
│ [ ] STATE.md exists for this feature                           │
│ [ ] Last completed phase is marked                            │
│ [ ] Progress updated (ROADMAP.md)                             │
│ [ ] Decisions documented (AD-NNN)                             │
│ [ ] Blockers identified (B-NNN)                               │
└────────────────────────────────────────────────────────────────┘

3. Design Reference Enforcement

Before implementing (Execute), if Design was executed:

┌────────────────────────────────────────────────────────────────┐
│ DESIGN REFERENCE ENFORCEMENT                                   │
├────────────────────────────────────────────────────────────────┤
│ [ ] design.md exists in features/[name]/                       │
│ [ ] Design was approved by user                               │
│ [ ] Components defined in design                             │
│ [ ] Interfaces documented                                     │
│ [ ] Code reuse identified                                     │
└────────────────────────────────────────────────────────────────┘

4. Artifact Enforcement

Each phase produces artifacts that the next phase needs. No artifact = blocks.

┌────────────┬────────────────────────┬─────────────────────────────────────┐
│ PHASE      │ PRODUCES               │ NEXT PHASE NEEDS                    │
├────────────┼────────────────────────┼─────────────────────────────────────┤
│ Discovery  │ PROJECT.md, ROADMAP.md │ Research, Specify                  │
│ Research   │ findings documented    │ Design, Specify                     │
│ Specify    │ spec.md                │ Tasks, Design                       │
│ Design     │ design.md              │ Tasks                               │
│ Tasks      │ tasks.md               │ Execute                             │
│ Execute    │ code + commits         │ final validation                   │
└────────────┴────────────────────────┴─────────────────────────────────────┘

No artifact from previous phase → Execute blocked.

5. Gate Check (Verify)

During Execute, each task has a gate level:

┌────────────────────────────────────────────────────────────────┐
│ TIERED GATE CHECKS                                             │
├────────────────────────────────────────────────────────────────┤
│ Task with unit tests          │ Gate: QUICK  (unit only)       │
│ Task with e2e/integration     │ Gate: FULL (unit + e2e)       │
│ Last task of phase            │ Gate: BUILD (build + lint + all)│
│ Task without tests            │ Gate: BUILD (build + lint only)│
└────────────────────────────────────────────────────────────────┘

Rule: Never proceed with a red gate.

---

Enforcement Pattern

The enforcement pattern combines Compliance Gate + State Saved Gate:

┌─────────────────────────────────────────────────────────────────┐
│ ENFORCEMENT PATTERN (REQUIRED)                                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  BEFORE EACH PHASE:                                             │
│  ┌──────────────────┐    ┌──────────────────┐                   │
│  │ Compliance Gate  │ AND │ State Saved Gate │                   │
│  │ (5 items)        │     │ (verification)    │                   │
│  └────────┬─────────┘    └────────┬─────────┘                   │
│           │                       │                              │
│           └───────────┬───────────┘                              │
│                       ▼                                          │
│              ┌──────────────┐                                    │
│              │ ADVANCE?     │                                    │
│              └──────────────┘                                    │
│                                                                  │
│  BOTH gates must pass to proceed.                               │
│  If one fails → BLOCK and resolve first.                         │
└─────────────────────────────────────────────────────────────────┘

---

Absolute Rules

NEVER:

• ❌ Skip required phase (Discovery, Research, Specify, Tasks, Execute)
• ❌ Go directly to code
• ❌ Implement without spec
• ❌ Edit without going through the pipeline
• ❌ Create duplicate spec — verify if it already exists in .specs/features/[name]/
• ❌ Ignore design reference — if design.md exists, READ and FOLLOW

ALWAYS:

• ✓ Save state after each phase
• ✓ Next phase uses previous one's artifact
• ✓ Optional phases activated when needed
• ✓ Structural changes → update .specs/project/{PROJECT.md, ROADMAP.md}
• ✓ SPEC Enforcement: change occurs → verify if spec exists. If yes → update. If no → create.

---

NUNCA Rules (Complete)

NEVER:

• Quick mode
• Auto-sizing
• Skip required phases
• Stop mid-flow
• Edit code outside of spec/design
• Skip State Autosave
• Proceed with red gate
• Create fixes/ structure (everything is a feature)
• Fabricate information (if you don't know, say "I don't know")
• Modify tests written in RED
• Weaken assertions to pass
• "While I'm here" during implementation

ALWAYS:

• ✓ Complete pipeline (even in BUG flow)
• ✓ State Autosave at each phase
• ✓ Confirm before advancing
• ✓ Update STATE.md
• ✓ Verify design.md before implementing
• ✓ Tests first (RED phase)
• ✓ Gate check after each task
• ✓ Atomic commit per task
• ✓ Reuse existing code

---

Operation Modes

Mode: Forward (default)

/lspec [request] → Discovery → Research → [Discuss?] → Specify → [Clarify?] → [Design?] → Tasks → Execute

For: new project, feature, bug, improvement

Adaptive Discovery:

• Bug: short questions (1-3)
• Feature: medium questions (5-8)
• New project: complete questions (10-15)

Mode: Map

/lspec map → Map existing code → SPEC.md

For: analyze existing code and generate spec

When to use:

• Project without documentation
• Legacy code to understand
• "How does this project work?"

Mode: Map (brownfield)

/lspec map → Analyze codebase → 7 architecture docs

For: existing projects need a map

---

Which Command to Use

Single Entry Point — /lspec

The /lspec command is the only entry point. It auto-detects the project type and executes the complete pipeline.

No need to choose command by phase. The system advances automatically.

Scenario	Command	What happens
New project	/lspec create a system for...	Complete Discovery (17 questions) → Research → Specify → ...
Feature in existing project	/lspec add login with...	Focused Discovery → Research → Specify → ...
Bug in existing project	/lspec fix error with...	Short Discovery (3 questions) → Research → Tasks → Execute
Existing project without specs	/lspec map current code	Map mode — code survey → spec auto-generated

Map — When to Use

Use /lspec map (or /lspec mapear) when:

• Project exists but doesn't have .specs/
• Need to understand structure before touching
• Taking over project from someone else

The map scans the code, generates .specs/project/ and .specs/features/[name]/ automatically.

Flow by Type

NEW PROJECT:

Discovery (complete) → Research → Discuss? → Specify → Clarify? → Design? → Tasks → Execute

BUG:

Discovery (short) → Research → Specify → Tasks → Execute

FEATURE:

Discovery (focused) → Research → Specify → Clarify? → Tasks → Execute

EXISTING PROJECT (without .specs/):

Discovery (short) → Research → Specify → Clarify? → Design? → Tasks → Execute

---

Complete Forward Flow

You say: /lspec I want to add JWT authentication

System does:

1. Discovery
   → "What type of authentication?"
   → Saves .specs/project/STATE.md

2. Research
   → Analyzes: does auth exist in project?
   → Analyzes: what auth stack?
   → Analyzes: where to integrate?
   → Saves features/jwt-auth/research.md

3. Discuss? (if there's ambiguity)
   → Captures gray area
   → Saves features/jwt-auth/discuss.md

4. Specify
   → Uses Discovery + Research
   → Writes spec.md with requirements
   → Saves features/jwt-auth/spec.md

5. Clarify? (if there's ambiguity)
   → Resolves ambiguity
   → Saves features/jwt-auth/clarify.md

6. Design? (if there's architectural decision)
   → Architecture decisions
   → Saves features/jwt-auth/design.md

7. Tasks
   → Uses spec.md
   → Breaks into tasks
   → Saves features/jwt-auth/tasks.md

8. Execute
   → Uses tasks.md
   → Implements code
   → Saves changes

→ Done!

You don't need to call each phase manually. The system advances on its own.

---

Research

REQUIRED phase between Discovery and Specify.

When to execute:

• Feature involves unfamiliar technology
• Integrations with new systems
• Patterns not used before in this codebase

Knowledge Verification Chain (strict order):

Codebase → Project docs → Context7 MCP → Web search → Flag as uncertain

CRITICAL: NEVER assume or fabricate information. If you can't find an answer, say "I don't know" or "I couldn't find documentation for this." Made-up information propagates through design → tasks → implementation and causes cascading failures.

---

Project Structure

.specs/
├── project/
│   ├── PROJECT.md       # Vision, goals, stack
│   ├── ROADMAP.md       # Features and milestones
│   └── STATE.md         # Decisions, blockers, current state
└── features/
    └── [feature]/
        ├── spec.md      # Testable requirements
        ├── context.md   # Gray area decisions (optional)
        ├── design.md    # Architectural decisions (optional)
        └── tasks.md     # Atomic tasks

Note: Bugs are registered as features in features/ — prefix fix- or bug- in name.

---

State Autosave

At each phase, WHEN COMPLETING:

1. Save decisions to STATE.md
2. Update progress in ROADMAP.md
3. Persist context for next session

STATE.md updated with:

• AD-NNN: decisions
• B-NNN: blockers
• L-NNN: learnings
• All pending items
• Deferred ideas

---

Git Workflow

Where to edit:

1. Clone the project's git repository
2. Edit in local clone
3. Atomic commit per task
4. Push when gate passes

NEVER edit skills locally. Skills live in the git repository, not in the agent's local filesystem.

Commit format (Conventional Commits 1.0.0):

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Allowed types:

• feat — New feature
• fix — Bug fix
• refactor — Code change (no bug fix, no feature)
• docs — Documentation
• test — Tests
• style — Formatting
• perf — Performance
• build — Build system
• ci — CI config
• chore — Maintenance

Rules:

• One task = one commit
• Description = what was DONE, not planned
• Include only files in task definition
• Tests in same commit if part of the task

---

Recommended Tools

Hermes (agent-lsp)

Hermes uses agent-lsp for code navigation. Not pi-cymbal.

┌────────────────────────────────────────────────────────────────┐
│ agent-lsp Skills (66 tools + 23 workflow skills)                │
├────────────────────────────────────────────────────────────────┤
│ Before editing:        blast_radius — blast-radius analysis    │
│ Before applying:       preview_edit — preview diagnostic delta │
│ After changing:        get_diagnostics, run_build, run_tests    │
└────────────────────────────────────────────────────────────────┘

Task-to-tool mapping:

Task	Use this	Not this
See file structure	list_symbols	Read + manual scanning
Find a symbol by name	find_symbol	Grep across files
Find all usages	find_references	Grep for the name
Understand a symbol	inspect_symbol	Read the file
What calls this function	find_callers	Grep for the name
Replace a function body	replace_symbol_body	Edit with text matching
Delete unused symbol	safe_delete_symbol	Edit to remove lines

Skills available via /lsp-*:

• /lsp-architecture — Structural overview
• /lsp-concurrency-audit — Concurrency safety
• /lsp-cross-repo — Cross-repository analysis
• /lsp-dead-code — Dead code detection
• /lsp-edit-export — Safe workflow for public APIs
• /lsp-refactor — End-to-end safe refactor
• /lsp-rename — Two-phase safe rename
• /lsp-safe-edit — Wrap edits with preview
• /lsp-verify — Three-layer verification (LSP + build + tests)

PI Packages (built-in to PI.dev)

PI.dev provides native navigation tools — no installation needed:

cymbal_ — structural navigation:*

• cymbal_map, cymbal_search, cymbal_outline, cymbal_show, cymbal_refs, cymbal_impact, cymbal_importers, cymbal_impls

lsp_ — technical precision:*

• lsp_goto_definition, lsp_find_references, lsp_diagnostics, lsp_symbols, lsp_rename

Use directly — they're part of the PI.dev runtime.

---

Critical Pitfalls

1. Information Fabrication

❌ "It probably works like this..."
✅ "I don't know, let me search"

2. Skipping Gates

❌ "I'll skip the gate check, it looks ok"
✅ "Red gate = stop and resolve"

3. Scope Creep

❌ "While I'm here, I'll also do X"
✅ "Is this in my task definition? If no, don't touch it"

4. Silencing Tests

❌ "I'll temporarily disable this test"
✅ "Failing test = real problem, resolve it"

5. Auto-sizing

❌ "Looks like that's all, I'll adjust"
✅ "Manually verify blast radius"

6. Skipping Autosave

❌ "I'll remember the state mentally"
✅ "STATE.md updated after each phase"

7. Weak Tests

❌ "Test passes without implementation = ok"
✅ "Test must fail in RED, pass in GREEN"

8. Silent SPEC_DEVIATION

❌ "Implementation diverged, but it's fine"
✅ "// SPEC_DEVIATION: [what diverged] // Reason: [why]"

---

Golden Rules

1. ALWAYS Complete Pipeline — no exceptions
2. Autosave — state saved at each phase
3. Confirm — before advancing to next phase
4. Never Fabricate — if you don't know, say "I don't know"
5. Spec is Truth — code deviates = SPEC_DEVIATION marker
6. Gate is Deterministic — the test runner decides, not the agent
7. Reuse is King — copy existing patterns, don't reinvent
8. Atomic Commit — one task = one commit

---

Internal References

• skills/lspec/README.md
• skills/lspec/SKILL.md
• skills/lspec-discovery/SKILL.md
• skills/lspec-specify/SKILL.md
• skills/lspec-design/SKILL.md
• skills/lspec-tasks/SKILL.md
• skills/lspec-execute/SKILL.md
• skills/lspec-auto/SKILL.md
• skills/lspec-next/SKILL.md
• skills/lspec-validate/SKILL.md
• skills/lspec-resume/SKILL.md
• skills/lspec-pause/SKILL.md
• references/pi-version-setup.md
• references/pi-packages-guide.md
• references/pi-v2-architecture.md
• references/subagent-context-budget.md

---

Credits

Conceptual base inspired by TLC Spec-Driven (Tech Lead's Club), with practical evolution for the PI ecosystem by by-lua.test