AgentSkillsCN

speckit-03-plan

针对需求验证，生成领域专属的质量检查清单

SKILL.md
--- frontmatter
name: speckit-03-plan
description: Create technical implementation plan from feature specification

Spec-Kit Plan

Execute the implementation planning workflow using the plan template to generate design artifacts.

User Input

text
$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Constitution Loading (REQUIRED)

Before ANY action, load and internalize the project constitution:

  1. •

    Read constitution:

    bash
    cat .specify/memory/constitution.md 2>/dev/null || echo "NO_CONSTITUTION"
  2. •

    If file doesn't exist:

    code
    ERROR: Project constitution not found at .specify/memory/constitution.md

Cannot proceed without constitution.
Run: /speckit-00-constitution
  3. •

    Parse all principles, constraints, and governance rules.

  4. •

    Extract Enforcement Rules:

    • •Find all lines containing "MUST", "MUST NOT", "SHALL", "SHALL NOT", "REQUIRED", "NON-NEGOTIABLE"
    • •Build an enforcement checklist from these rules
    • •Example extraction:
      code
      CONSTITUTION ENFORCEMENT RULES:
[MUST] Use TDD - write tests before implementation
[MUST NOT] Use external dependencies without justification
[REQUIRED] All code must have error handling
  5. •

    Validation commitment: Every output will be validated against each principle before being written.

  6. •

    Hard Gate Declaration: State explicitly:

    code
    CONSTITUTION GATE ACTIVE
Extracted X enforcement rules
ANY violation will HALT planning with explanation

Prerequisites Check

  1. •

    Run setup script (choose based on platform):

    Unix/macOS/Linux:

    bash
    .tessl/tiles/tessl-labs/spec-kit/skills/speckit-01-specify/scripts/bash/setup-plan.sh --json

    Windows (PowerShell):

    powershell
    pwsh .tessl/tiles/tessl-labs/spec-kit/skills/speckit-01-specify/scripts/powershell/setup-plan.ps1 -Json
  2. •

    Parse JSON for:

    • •FEATURE_SPEC - path to spec.md
    • •IMPL_PLAN - path to plan.md
    • •SPECS_DIR - feature directory
    • •BRANCH - current branch name
  3. •

    If error or missing spec.md:

    code
    ERROR: spec.md not found in feature directory.

Run: /speckit-01-specify <feature description>

Smart Validation

BEFORE proceeding to planning, perform semantic validation:

Spec Quality Gate

Read the spec.md and validate:

  1. •

    Requirement Count Check:

    • •Count functional requirements (FR-XXX patterns)
    • •If fewer than 3 requirements:
      code
      WARNING: Spec may be underspecified (found X requirements, recommend 3+).
    • •If 0 requirements:
      code
      ERROR: Cannot plan without requirements.

The spec.md has no functional requirements (FR-XXX).
Run: /speckit-01-specify to add requirements, or manually add FR-XXX items to spec.md
  2. •

    Measurable Success Criteria Check:

    • •Scan Success Criteria section for numeric values, percentages, or time measurements
    • •If no measurable criteria found:
      code
      WARNING: No measurable success criteria found.

Recommendation: Add metrics like "under 3 seconds", "95% uptime", "10,000 users".
  3. •

    Unresolved Clarification Check:

    • •Search for [NEEDS CLARIFICATION] markers
    • •If found, list each one and ask: "Resolve these before planning, or proceed with assumptions?"
    • •If user says proceed, document assumptions explicitly in plan.md
  4. •

    User Story Coverage Check:

    • •Verify each user story has at least one acceptance scenario
    • •If any story lacks scenarios:
      code
      WARNING: User Story X has no acceptance criteria.

Recommendation: Add acceptance scenarios to validate the story is complete.
  5. •

    Cross-Reference Validation:

    • •Check that requirements reference user stories (or vice versa)
    • •If orphan requirements exist:
      code
      WARNING: Orphan requirement detected (FR-XXX not linked to any user story).

Recommendation: Link requirements to user stories for traceability.

Quality Score Report

Calculate and display:

code
╭─────────────────────────────────────────────╮
│  SPEC QUALITY REPORT                        │
├─────────────────────────────────────────────┤
│  Requirements:     X found (min: 3)    [✓/✗]│
│  Success Criteria: X found (min: 3)    [✓/✗]│
│  User Stories:     X found (min: 1)    [✓/✗]│
│  Measurable:       X criteria have metrics  │
│  Clarifications:   X unresolved             │
│  Coverage:         X% requirements linked   │
├─────────────────────────────────────────────┤
│  OVERALL SCORE: X/10                        │
│  STATUS: [READY/NEEDS WORK]                 │
╰─────────────────────────────────────────────╯

If score < 6: Recommend running /speckit-02-clarify first If score >= 6: Proceed with planning

Execution Flow

1. Setup

  • •Run setup script to get paths and copy plan template
  • •Read FEATURE_SPEC and constitution
  • •Load IMPL_PLAN template

2. Execute Plan Workflow

Follow the structure in IMPL_PLAN template to:

  1. •

    Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION"):

    • •Language/Version
    • •Primary Dependencies
    • •Storage
    • •Testing
    • •Target Platform
    • •Project Type
    • •Performance Goals
    • •Constraints
    • •Scale/Scope
  2. •

    Fill Constitution Check section from constitution principles

  3. •

    Evaluate gates - ERROR if violations cannot be justified

3. Tessl Tile Discovery (MANDATORY if Tessl installed)

Purpose: Discover, install, and catalog Tessl tiles for all technologies in the Technical Context. Tiles provide documentation, rules, and skills that improve implementation quality.

3.1 Check Tessl Availability

Platform Detection:

  • •Unix/Linux/macOS: command -v tessl >/dev/null 2>&1
  • •Windows PowerShell: Get-Command tessl -ErrorAction SilentlyContinue

If Tessl NOT Available: Display once and continue without tile operations:

code
ℹ️ Tessl not installed. Tile-based documentation unavailable.
   Install Tessl for enhanced library documentation: https://tessl.io

If Tessl Available: Proceed with tile discovery.

3.2 Check Tessl Status

code
mcp__tessl__status()

This shows authentication status and any existing tiles.

3.3 Extract Technologies from Technical Context

From the drafted Technical Context, extract:

  • •Language/Version (e.g., "Python 3.12", "TypeScript 5.x")
  • •Primary Dependencies (e.g., "Click", "Express", "React")
  • •Storage (e.g., "SQLite", "PostgreSQL", "MongoDB")
  • •Testing (e.g., "pytest", "Jest", "Vitest")
  • •Any other frameworks/libraries mentioned

3.4 Search and Install Tiles for Each Technology

For each technology identified:

  1. •

    Search for tiles:

    code
    mcp__tessl__search(query="<technology>")
  2. •

    For each tile found, identify type:

    • •Documentation tile: Contains library usage specs (has describes field)
    • •Rules tile: Contains behavioral guidelines (has rules section)
    • •Skills tile: Contains invocable AI commands (has skill section)
  3. •

    Install relevant tiles:

    code
    mcp__tessl__install(packageName="<workspace/tile-name>")
  4. •

    Document in research.md (Tessl Tiles section):

    code
    ## Tessl Tiles

### Installed Tiles

| Technology | Tile | Type | Version |
|------------|------|------|---------|
| Python | tessl/python | Documentation | 1.2.0 |
| Click | tessl/click | Documentation | 0.8.0 |
| pytest | tessl/pytest | Documentation + Rules | 1.0.0 |

### Available Skills

The following skills are available from installed tiles:
- `/<skill-name>` - Description of what the skill does

### Technologies Without Tiles

- <technology>: No tile found in registry
  5. •

    If no tiles found for a technology:

    • •Note in research.md: "No Tessl tile available for <technology>"
    • •Continue without tile for that technology

3.5 Query Installed Documentation Tiles for Best Practices

For each installed documentation tile, query for best practices:

code
mcp__tessl__query_library_docs(query="best practices for <library>")

Incorporate findings into research.md decisions section.

3.6 Catalog Installed Skill Tiles

List all available skills from installed tiles:

  • •Record skill name and purpose
  • •Note in research.md: "Available skills: /<skill-1>, /<skill-2>, ..."
  • •Skills become available for use in subsequent phases (especially /speckit-08-implement)

3.7 Handle Failures Gracefully

  • •Network issues: Log warning, continue without affected tiles
  • •Registry unavailable: Log warning, continue without tiles
  • •Authentication required: Prompt user to run tessl login, continue without tiles
  • •Search returns no results: Note in research.md, continue

4. Phase 0: Outline & Research (includes Tessl findings)

  1. •

    Extract unknowns from Technical Context:

    • •For each NEEDS CLARIFICATION -> research task
    • •For each dependency -> best practices task
    • •For each integration -> patterns task
  2. •

    Research each unknown and document findings

  3. •

    Consolidate findings in research.md:

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

Output: research.md with all NEEDS CLARIFICATION resolved (includes Tessl Tiles section if Tessl available)

5. 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. •

    Generate API contracts from functional requirements:

    • •For each user action -> endpoint
    • •Use standard REST/GraphQL patterns
    • •Output OpenAPI/GraphQL schema to /contracts/
  3. •

    Create quickstart.md with test scenarios

  4. •

    Agent context update (choose based on platform):

    Unix/macOS/Linux:

    bash
    .tessl/tiles/tessl-labs/spec-kit/skills/speckit-01-specify/scripts/bash/update-agent-context.sh claude

    Windows (PowerShell):

    powershell
    pwsh .tessl/tiles/tessl-labs/spec-kit/skills/speckit-01-specify/scripts/powershell/update-agent-context.ps1 -AgentType claude

    This updates CLAUDE.md with the new technology stack.

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

6. Constitution Check (Post-Design)

Re-evaluate the Constitution Check after design phase:

  • •Verify all technical decisions align with principles
  • •If ANY violation detected:
    • •STOP immediately
    • •State: "CONSTITUTION VIOLATION: [Principle Name]"
    • •Explain what specifically violates the principle
    • •Suggest compliant alternative approach
    • •DO NOT proceed with "best effort" or workarounds

7. Phase Separation Validation (REQUIRED)

Before finalizing, scan the draft plan for governance content that belongs in /speckit-00-constitution:

Check for violations - plan MUST NOT contain:

  • •Project governance principles or "laws"
  • •Non-negotiable development rules (e.g., "always use TDD", "code review required")
  • •Quality standards that apply project-wide (e.g., "100% test coverage")
  • •Amendment procedures or versioning policies
  • •Compliance or audit requirements
  • •Team workflow rules (e.g., "PRs must be approved by 2 reviewers")
  • •Coding standards that aren't technology-specific

Plan SHOULD contain (these are appropriate here):

  • •Technology stack decisions (languages, frameworks, databases)
  • •Architecture patterns for THIS feature
  • •Implementation approach and rationale
  • •Data models and API contracts
  • •Performance targets for THIS feature
  • •Technology-specific best practices

If violations found:

code
╭─────────────────────────────────────────────────────────────────╮
│  PHASE SEPARATION VIOLATION DETECTED                           │
├─────────────────────────────────────────────────────────────────┤
│  Plan contains governance content:                             │
│  - [list each violation]                                       │
│                                                                 │
│  Governance principles belong in /speckit-00-constitution.     │
│  Plan defines HOW to implement THIS feature, not project laws. │
├─────────────────────────────────────────────────────────────────┤
│  ACTION: Moving governance content to constitution reference...│
╰─────────────────────────────────────────────────────────────────╯

Auto-fix: Replace governance statements with constitution references:

  • •"Always use TDD" → "Per constitution: [reference TDD principle]"
  • •"Code must have 100% coverage" → "Coverage target per constitution"
  • •"All PRs require review" → (remove - this is workflow, not implementation)

Re-validate after fixes until no violations remain.

Output Validation (REQUIRED)

Before writing ANY artifact:

  1. •Review output against EACH constitutional principle
  2. •If ANY violation detected:
    • •STOP immediately
    • •State: "CONSTITUTION VIOLATION: [Principle Name]"
    • •Explain: What specifically violates the principle
    • •Suggest: Compliant alternative approach
  3. •If compliant, proceed and note: "Validated against constitution v[VERSION]"

Key Rules

  • •Use absolute paths
  • •ERROR on gate failures or unresolved clarifications
  • •Command ends after Phase 1 design is complete

Report

Output:

  • •Branch name
  • •IMPL_PLAN path
  • •Generated artifacts list:
    • •research.md (includes Tessl Tiles section if Tessl available)
    • •data-model.md
    • •contracts/*
    • •quickstart.md
  • •Agent file update status
  • •Tessl integration status:
    • •Tiles installed (with versions)
    • •Skills available for implementation phase
    • •Technologies without tiles

Semantic Diff on Re-run

If plan.md already exists with content, perform semantic diff before overwriting:

1. Detect and Parse Existing Plan

If plan.md exists and has Technical Context filled in:

  1. •

    Extract semantic elements:

    • •Language/Version
    • •Primary Dependencies
    • •Storage choice
    • •Project structure decisions
  2. •

    Compare with new content:

    code
    ╭─────────────────────────────────────────────────────╮
│  SEMANTIC DIFF: plan.md                             │
├─────────────────────────────────────────────────────┤
│  Tech Stack:                                        │
│    ~ Language: Python 3.11 → Python 3.12            │
│    + Added: Redis for caching                       │
│    - Removed: None                                  │
│                                                     │
│  Architecture:                                      │
│    ~ Changed: Switched from REST to GraphQL         │
│    + Added: Event sourcing pattern                  │
├─────────────────────────────────────────────────────┤
│  DOWNSTREAM IMPACT:                                 │
│  ⚠ tasks.md MUST be regenerated (architecture change)│
│  ⚠ contracts/ need updates (API change)            │
│  ⚠ data-model.md may need updates                  │
╰─────────────────────────────────────────────────────╯
  3. •

    Flag breaking changes:

    • •Language change → ALL tasks affected
    • •Framework change → Most tasks affected
    • •Storage change → Data layer tasks affected

2. Automatic Downstream Invalidation

If significant changes detected:

code
WARNING: Plan changes detected that invalidate downstream artifacts.
Recommend re-running:
- /speckit-06-tasks (REQUIRED - architecture changed)
- /speckit-07-analyze (RECOMMENDED - verify consistency)

Next Steps

After completing the plan:

  1. •

    Recommended: Run /speckit-04-checklist to create domain-specific quality checklists

    • •Generates "unit tests for English" to validate requirements quality
    • •Helps catch requirement gaps before implementation
    • •Required to reach 100% before /speckit-08-implement
  2. •

    Required: Run /speckit-06-tasks to generate the task breakdown

Suggest to user:

code
Plan complete! Next steps:
- /speckit-04-checklist - (Recommended) Generate quality checklists for requirements validation
- /speckit-06-tasks - Generate task breakdown from plan