Get the FREE Ultimate OpenClaw Setup Guide →

speckit-plan

npx machina-cli add skill h3y6e/speckit-skills/speckit-plan --openclaw
Files (1)
SKILL.md
3.1 KB

Speckit Plan Skill

Outline

  1. Setup: Run scripts/setup-plan.sh --json from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot").

  2. Load context: Read FEATURE_SPEC and specs/constitution.md. Load IMPL_PLAN template (already copied).

  3. Execute plan workflow: Follow the structure in IMPL_PLAN template to:

    • Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
    • Fill Constitution Check section from constitution
    • Evaluate gates (ERROR if violations unjustified)
    • Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
    • Phase 1: Generate data-model.md, contracts/, quickstart.md
    • Phase 1: Update agent context by running the agent script
    • Re-evaluate Constitution Check post-design

  4. Stop and report: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.

Phases

Phase 0: Outline & Research

  1. Extract unknowns from Technical Context above:

    • For each NEEDS CLARIFICATION → research task
    • For each dependency → best practices task
    • For each integration → patterns task

  2. Generate and dispatch research agents:

    For each unknown in Technical Context:
  Task: "Research {unknown} for {feature context}"
For each technology choice:
  Task: "Find best practices for {tech} in {domain}"

  3. Consolidate findings in research.md using format:

    • Decision: [what was chosen]
    • Rationale: [why chosen]
    • Alternatives considered: [what else evaluated]

Output: research.md with all NEEDS CLARIFICATION resolved

Phase 1: Design & Contracts

Prerequisites: research.md complete

  1. Extract entities from feature spec → data-model.md:

    • Entity name, fields, relationships
    • Validation rules from requirements
    • State transitions if applicable

  2. Define interface contracts (if project has external interfaces) → /contracts/:

    • Identify what interfaces the project exposes to users or other systems
    • Document the contract format appropriate for the project type
    • Examples: public APIs for libraries, command schemas for CLI tools, endpoints for web services, grammars for parsers, UI contracts for applications
    • Skip if project is purely internal (build scripts, one-off tools, etc.)

  3. Agent context update:

    • Run scripts/update-agent-context.sh codex
    • These scripts detect which AI agent is in use
    • Update the appropriate agent-specific context file
    • Add only new technology from current plan
    • Preserve manual additions between markers

Output: data-model.md, /contracts/*, quickstart.md, agent-specific file

Key rules

  • Use absolute paths
  • ERROR on gate failures or unresolved clarifications

Source

git clone https://github.com/h3y6e/speckit-skills/blob/main/skills/speckit-plan/SKILL.mdView on GitHub

Overview

Speckit Plan converts feature specifications into a structured implementation plan, outlining architecture, tech choices, data models, and contracts. It produces artifacts like plan.md, research.md, data-model.md, contracts/, and quickstart.md, guiding teams through Phase 0 (research), Phase 1 (design & contracts), and agent-context updates with a clear NEEDS CLARIFICATION workflow.

How This Skill Works

It loads FEATURE_SPEC, constitution.md, and the IMPL_PLAN template, then fills the Technical Context (marking unknowns as NEEDS CLARIFICATION) and follows the plan workflow to Phase 0, Phase 1, and agent-context updates. After design, it re-evaluates the Constitution Check and outputs the artifacts (research.md, data-model.md, contracts/, quickstart.md) and reports the branch and IMPL_PLAN path.

When to Use It

  • When starting a new feature with a complete SPEC and constitution.md to generate a full implementation plan.
  • When you need a robust architecture, data model, and contract design before coding begins.
  • When external interfaces or contracts exist and must be documented early.
  • When cross-team alignment is critical and a single source of truth plan is required.
  • When you want to automatically generate plan artifacts in a repo and update agent context.

Quick Start

  1. Step 1: Run scripts/setup-plan.sh --json from repo root to load FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH.
  2. Step 2: Ensure your SPEC and constitution.md are present; the system fills Technical Context and Mark NEEDS CLARIFICATION as needed.
  3. Step 3: Review generated artifacts (research.md, data-model.md, contracts/, quickstart.md) and commit the plan branch.

Best Practices

  • Start from a complete FEATURE_SPEC and the constitution.md to feed accurate planning.
  • Explicitly mark unknowns as NEEDS CLARIFICATION and resolve them in Phase 0.
  • Follow the IMPL_PLAN structure and keep output artifacts in absolute paths.
  • Apply gate checks and fail on unresolved clarifications to avoid ambiguous designs.
  • Run scripts/update-agent-context.sh codex to refresh agent context after design changes.

Example Use Cases

  • Feature: user authentication flow — outputs research.md resolving OAuth options, data-model.md for User, contracts for login API, and a quickstart to run locally.
  • Feature: inventory microservice integration — artifacts include data-model.md for Item/Stock, contracts for inventory endpoints, and Phase 1 plan artifacts.
  • Feature: CLI tool with command schemas — contracts describe command formats, data-model defines command state, and quickstart demonstrates usage.
  • Feature: data export service — research resolves export formats, data-model defines export schemas, and plan includes deployment contracts.
  • Feature: external API integration — IMPL_PLAN yields interface contracts, security considerations, and a sample quickstart for integration.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗