Launchpad Spec

Iterative feature development framework ensuring zero ambiguity before execution.

Quick Reference

Core Principle

Iterate until clarity: No task execution begins until ALL questions are resolved and the spec is unambiguous. Claude must be able to execute without interruptions.

Phase 1: /lp:spec - Create Specification

Trigger: /lp:spec <description> or "I want to build/add X"

Workflow

1. Check `specs/` folder:

• If missing: Create specs/ and specs/README.md
• If exists: Read specs/README.md for project overrides

1. Detect project context:

• Scan repo for language indicators (go.mod, pyproject.toml, package.json, etc.)
• Note primary language(s) for later skill invocation
• Check specs/README.md for language overrides

1. Generate spec file:

• Filename: specs/{feature-slug}.md (kebab-case)

1. Fill initial sections:

• Parse user intent into Objective
• List initial requirements (functional/non-functional)
• Mark status as DRAFT

1. Generate clarifying questions:

• Identify ambiguities, edge cases, unknowns
• List as numbered questions in "Open Questions" section
• STOP and present questions to user

Output

Created: specs/feature-name.md (DRAFT)

Questions requiring clarification:
1. [Question about scope]
2. [Question about behavior]
3. [Question about constraints]

Use `/lp:clarify` to answer, or `/lp:refine` to research solutions.

Phase 2: /lp:refine - Research & Improve

Trigger: /lp:refine [section] (e.g., /lp:refine solution, /lp:refine requirements)

Workflow

1. Load active spec: Find most recent DRAFT spec in specs/

1. Check project conventions:

• Read specs/README.md for behavior overrides
• Load relevant language skill (auto-detected or overridden)

1. Research phase:

• Search codebase for similar patterns
• Check skill references for best practices

1. Update spec:

• Fill "Technical Strategy" with concrete approach
• Add architecture decisions with rationale
• Update requirements based on findings

1. Re-evaluate clarity:

• Are there new questions?
• Are existing questions resolved?
• If questions remain: STOP and present them

Phase 3: /lp:clarify - Answer Questions

Trigger: /lp:clarify <response> or /lp:clarify Q1: answer, Q2: answer

Workflow

1. Load active spec with open questions

1. Parse user response:

• Match answers to numbered questions
• Accept free-form responses for single questions

1. Update spec:

• Move answered questions to relevant sections
• Add decisions/constraints to Requirements or Strategy
• Remove resolved questions from "Open Questions"

1. Check for new questions:

• Does the answer introduce new ambiguities?
• If questions remain: present them
• If no questions: announce spec is ready for `/lp:tasks`

Example

User: /lp:clarify Q1: We need OAuth2 with Google provider only. Q2: No, admin can also delete.

Updated specs/auth-system.md:
- Added OAuth2/Google to Technical Strategy
- Updated permissions: admin can delete

Remaining questions: None
Spec is ready. Use `/lp:tasks` to create task breakdown.

Phase 4: /lp:tasks - Task Breakdown

Trigger: /lp:tasks

Prerequisites

• Active spec must have status DRAFT or APPROVED
• "Open Questions" section must be empty
• If questions exist: STOP and redirect to `/lp:clarify`

Workflow

1. Validate spec readiness:

   If open_questions > 0:
       ERROR: Spec has unresolved questions. Use /lp:clarify first.

1. Mark spec as APPROVED

1. Generate task file: specs/{feature-slug}.tasks.md

1. Break down by component:

• Group tasks by logical component/module
• Each task = one logical unit (not TDD-granular)
• TDD practice enforced during /lp:run-task, not here

1. Add task metadata:

• Link back to spec
• Context summary
• Acceptance criteria per task

1. Final review:

• Present task list to user
• Ask: "Any tasks missing or need splitting?"

Task Granularity

Tasks should be high-level logical units:

• "Implement authentication middleware"
• "Create user model and repository"
• "Add API endpoints for user CRUD"

TDD cycle (Red-Green-Refactor) happens WITHIN each task during /lp:run-task.

Phase 5: /lp:run-task - Execute Tasks

Trigger: /lp:run-task [task#] (e.g., /lp:run-task, /lp:run-task 3)

Prerequisites

• Task file must exist: specs/{feature}.tasks.md
• If no task file: STOP and redirect to `/lp:tasks`

Workflow

1. Load task file and find next unchecked task (or specified task#)

1. Load context:

• Read linked spec for requirements
• Read specs/README.md for project overrides

1. Execute with TDD:

• RED: Write failing test first
• GREEN: Minimal code to pass
• REFACTOR: Clean up
• COMMIT: After each phase

1. Update task file:

• Mark task as [x] complete
• Add notes if needed

1. Continue or pause:

• If more tasks: Ask "Continue to next task?"
• If blocked: Document blocker, ask for input
• If all done: Mark spec as COMPLETED

Execution Rules

• No interruptions: If questions arise during execution, the spec was not ready
• Respect hooks: Pre-commit hooks must pass before marking complete

Project Configuration: specs/README.md

Override default behaviors per-project:

# Spec Configuration

## Language Override
Primary: golang
Secondary: python

## Conventions
- All specs require security section
- Tasks must include rollback plan
- Use feature branches: feature/{spec-name}

## Templates
Use custom templates from: ./templates/

## Auto-invoke
- Always run /trivy before marking complete

State Management

Spec Status Flow

DRAFT -> APPROVED -> IN_PROGRESS -> COMPLETED
          |              |
          v              v
       (questions?)   (blocked?)
          |              |
          v              v
        DRAFT      IN_PROGRESS

File Structure

project/
└── specs/
    ├── README.md           # Project overrides
    ├── auth-system.md      # Spec (APPROVED)
    ├── auth-system.tasks.md # Task breakdown
    ├── user-dashboard.md   # Spec (DRAFT)
    └── ...

Session Resume

On context compaction or session resume:

1. Check specs/ for files with status IN_PROGRESS
2. Check .tasks.md files for unchecked items
3. Report: "Found in-progress spec: X with Y tasks remaining"
4. Ask: "Continue with /lp:run-task?"

Error Handling