SpecKit Author

Purpose

Creates detailed specifications and implementation plans for features, releases, and hotfixes within worktree directories.

When to Use

•Current directory: worktree (feature/release/hotfix)
•Phase: Specification (Phase 2)

Document Templates

Templates are located in templates/:

•spec.md.template - Detailed technical specification (297 lines)
•plan.md.template - Task breakdown and implementation plan (367 lines)

Interactive Callable Tool

SpecKit is now an interactive callable tool that runs as a Python script in feature worktrees.

Invocation

Command:

bash

python .claude/skills/speckit-author/scripts/create_specifications.py \
  <workflow_type> <slug> <gh_user> [--todo-file <path>]

Arguments:

•workflow_type: feature, release, or hotfix
•slug: Feature slug (e.g., my-feature)
•gh_user: GitHub username
•--todo-file: Optional path to TODO file (default: auto-detect)
•--no-commit: Skip git commit (for testing)

Example:

bash

# In feature worktree
cd /Users/user/german_feature_my-feature

python .claude/skills/speckit-author/scripts/create_specifications.py \
  feature my-feature stharrold \
  --todo-file ../TODO_feature_20251024T143000Z_my-feature.md

Interactive Session Flow

With BMAD Planning (Recommended)

Session output:

code

Working in worktree: /Users/user/german_feature_my-feature
Branch: feature/20251024T143000Z_my-feature
✓ Auto-detected TODO file: ../TODO_feature_20251024T143000Z_my-feature.md

======================================================================
SpecKit Interactive Specification Tool
======================================================================

✓ Detected BMAD planning context: ../planning/my-feature/

BMAD Summary:
  - Requirements: 15 functional requirements, 5 user stories
  - Architecture: Technology stack defined
  - Epics: 3 epics defined

Implementation Questions:
----------------------------------------------------------------------

Database migrations strategy?
  1) Alembic (recommended)
  2) Manual SQL migrations
  3) None needed
  [default: Alembic (recommended)]
> 1

Include end-to-end (E2E) tests? (Y/n) > n

Include performance/load tests? (Y/n) > n

Include security tests (OWASP checks)? (Y/n) > n

Task granularity preference?
  1) Small tasks (1-2 hours each)
  2) Medium tasks (half-day each)
  3) Large tasks (full-day each)
  [default: Small tasks (1-2 hours each)]
> 1

Follow epic priority order from epics.md? (Y/n) > Y

Any additional implementation notes or constraints? (optional)
> Use type hints throughout

======================================================================
Generating specifications...
======================================================================
✓ Created specs/my-feature/spec.md (1247 chars)
✓ Created specs/my-feature/plan.md (1583 chars)
✓ Created specs/my-feature/CLAUDE.md
✓ Created specs/my-feature/README.md
✓ Updated TODO file: ../TODO_feature_20251024T143000Z_my-feature.md
  Added 0 tasks across 0 categories

✓ Committed changes to branch

======================================================================
SpecKit Specifications Created Successfully!
======================================================================

Files created:
  - specs/my-feature/spec.md
  - specs/my-feature/plan.md
  - specs/my-feature/CLAUDE.md
  - specs/my-feature/README.md

Next steps:
  1. Review spec.md and plan.md
  2. Implement tasks from plan.md
  3. Update TODO task status as you complete each task
  4. Refer to ../planning/my-feature/ for BMAD context

What happens:

•Script detects ../planning/my-feature/ directory
•Reads requirements.md, architecture.md, epics.md
•Displays BMAD summary
•Asks 5-8 implementation-specific questions
•Generates spec.md + plan.md aligned with BMAD
•Creates compliant specs/<slug>/ directory structure
•Updates TODO_*.md with tasks parsed from plan.md
•Commits changes

Generated spec.md includes:

•Reference to BMAD planning documents
•Implementation context from Q&A responses
•Technology stack from architecture.md
•Functional requirements from requirements.md
•Detailed component specifications

Generated plan.md includes:

•Tasks organized by epics from epics.md
•Task IDs (impl_001, impl_002, test_001, etc.)
•Dependencies based on epic order
•Acceptance criteria
•Verification commands

Without BMAD Planning

Session output:

code

======================================================================
SpecKit Interactive Specification Tool
======================================================================

⚠ No BMAD planning found for 'my-feature'
I'll gather requirements through comprehensive Q&A.

Recommendation: Use BMAD planning for future features
======================================================================

What is the main purpose of this feature?
> Add vocabulary search functionality

Who are the primary users of this feature?
> German language learners

How will success be measured? (metrics, goals)
> Users can search vocabulary by German word, English translation, or POS

Technology Stack:

Web framework (if applicable)?
  1) FastAPI
  2) Flask
  3) Django
  4) None
  [default: None]
> 4

Database?
  1) SQLite (dev)
  2) PostgreSQL
  3) MySQL
  4) None
  [default: None]
> 1

Database migration strategy?
  1) Alembic
  2) Manual SQL
  3) None
  [default: Alembic]
> 1

Testing framework?
  1) pytest (recommended)
  2) unittest
  3) other
  [default: pytest (recommended)]
> 1

Performance target? (e.g., '<200ms response time', 'not critical')
> < 100ms query time

Security requirements? (e.g., 'authentication', 'encryption', 'none')
> none

Test coverage target? [80%]
> 85

Include E2E tests? (y/N) > n

Include performance tests? (y/N) > n

Task size preference?
  1) Small (1-2 hours)
  2) Medium (half-day)
  3) Large (full-day)
  [default: Small (1-2 hours)]
> 1

[... generates spec.md and plan.md ...]

What happens:

•Script finds no planning context
•Conducts comprehensive Q&A (10-15 questions)
•Gathers requirements, tech stack, testing preferences
•Generates spec.md + plan.md from scratch
•Creates compliant specs/<slug>/ directory structure
•Updates TODO_*.md with tasks
•Commits changes
•Recommends creating BMAD planning for next feature

Script Architecture

create_specifications.py

Location: .claude/skills/speckit-author/scripts/create_specifications.py

Implements:

•
Context Detection
- •Verifies running in worktree (not main repo)
- •Auto-detects or accepts TODO file path
- •Checks for BMAD planning in ../planning/<slug>/
•
Interactive Q&A
- •Adapts questions based on BMAD availability
- •With BMAD: 5-8 implementation-specific questions
- •Without BMAD: 10-15 comprehensive requirements questions
•
Template Processing
- •Loads spec.md.template and plan.md.template
- •Replaces placeholders ({{TITLE}}, {{SLUG}}, {{DATE}}, etc.)
- •Injects Q&A context as implementation notes
•
Directory Creation
- •Creates specs/<slug>/ with compliant structure
- •Generates CLAUDE.md and README.md
- •Creates ARCHIVED/ subdirectory
•
TODO Update
- •Parses task IDs from plan.md
- •Updates TODO_*.md YAML frontmatter
- •Groups tasks by category (impl, test, doc, etc.)
•
Git Commit
- •Stages specs/<slug>/ and TODO file
- •Creates descriptive commit message
- •References TODO file in commit

Directory Structure

Specification documents are created in:

code

specs/
└── <feature-slug>/
    ├── spec.md           # Technical specification
    ├── plan.md          # Implementation plan
    ├── CLAUDE.md        # Context for this spec
    ├── README.md        # Human-readable overview
    └── ARCHIVED/        # Deprecated specs

update_asbuilt.py

Location: .claude/skills/speckit-author/scripts/update_asbuilt.py

Used in: Phase 4 (Integration + Feedback) after PR merge

Implements:

•
Read As-Built Specs
- •Reads specs/<slug>/spec.md and plan.md
- •Reads TODO_*.md for effort/timeline data
•
Compare with Planning
- •Auto-detects deviations (technology changes)
- •Interactive Q&A for manual deviation identification
•
Gather Metrics
- •Epic completion (estimated vs actual effort)
- •Quality metrics (coverage, performance)
- •Lessons learned
•
Update Planning Docs
- •Appends "## As-Built Notes" to requirements.md
- •Appends "## As-Built Architecture" to architecture.md
- •Appends "## Epic Completion Status" to epics.md
•
Git Commit
- •Commits updated planning documents
- •Creates feedback loop for future planning

Invocation:

bash

# From main repo on contrib branch after PR merge
python .claude/skills/speckit-author/scripts/update_asbuilt.py \
  planning/my-feature specs/my-feature

Integration with Workflow

The workflow-orchestrator calls SpecKit scripts during workflow phases.

Phase 2: Create Specifications (Step 2.3)

Workflow orchestrator code:

python

# In workflow orchestrator - Phase 2.3
if current_phase == 2 and current_step == '2.3':
    import subprocess

    # Call SpecKit interactive tool
    result = subprocess.run([
        'python',
        '.claude/skills/speckit-author/scripts/create_specifications.py',
        workflow_type,  # feature, release, hotfix
        slug,           # my-feature
        gh_user,        # stharrold
        '--todo-file', f'../TODO_{workflow_type}_{timestamp}_{slug}.md'
    ], check=True)

    # SpecKit handles:
    # - Interactive Q&A with user
    # - BMAD context detection
    # - spec.md and plan.md generation
    # - TODO_*.md update
    # - Git commit

    print("✓ SpecKit specifications created")
    print(f"  Next: Implement tasks from specs/{slug}/plan.md")

Phase 4: Update As-Built (Step 4.4)

After PR merge to contrib branch:

python

# In workflow orchestrator - Phase 4.4
if current_phase == 4 and current_step == '4.4':
    import subprocess

    # Call as-built update tool
    result = subprocess.run([
        'python',
        '.claude/skills/speckit-author/scripts/update_asbuilt.py',
        f'planning/{slug}',
        f'specs/{slug}'
    ], check=True)

    # update_asbuilt.py handles:
    # - Deviation analysis
    # - Interactive metrics gathering
    # - Planning document updates
    # - Git commit

    print("✓ BMAD planning updated with as-built details")
    print(f"  Feedback loop completed for {slug}")

Template Placeholders

Both templates use these placeholders:

•{{TITLE}} - Feature name (title case)
•{{WORKFLOW_TYPE}} - feature, release, or hotfix
•{{SLUG}} - Feature slug (kebab-case)
•{{DATE}} - Creation date (YYYY-MM-DD)
•{{GH_USER}} - GitHub username

Using BMAD Planning Context

When BMAD planning documents exist in ../planning/<feature>/:

SpecKit Should:

1. Read planning context:

python

# Read BMAD planning docs from main repo
requirements = Path('../planning/<feature>/requirements.md').read_text()
architecture = Path('../planning/<feature>/architecture.md').read_text()
epics = Path('../planning/<feature>/epics.md').read_text()

2. Extract key information:

•
From requirements.md:
- •Functional requirements (FR-001, FR-002...)
- •Non-functional requirements (performance, security, scalability)
- •User stories and acceptance criteria
- •Success criteria and constraints
•
From architecture.md:
- •Technology stack and framework choices
- •Data models and database schema
- •API endpoint definitions
- •Container configuration
- •Security and error handling strategies
•
From epics.md:
- •Epic breakdown (E-001, E-002...)
- •Epic priorities (P0, P1, P2)
- •Epic dependencies
- •Implementation timeline

3. Generate spec.md informed by planning:

markdown

# spec.md sections should reference BMAD docs

## Functional Requirements
FR-001 from requirements.md: [Requirement description]
  - Acceptance Criteria (from requirements.md):
    - [ ] AC 1...
    - [ ] AC 2...

## Technology Stack
Stack defined in architecture.md:
  - Language: Python 3.11+
  - Framework: FastAPI (chosen in architecture.md)
  - Database: PostgreSQL (from architecture.md)

## Security Requirements
From architecture.md Section "Security Considerations":
  - Authentication: JWT tokens
  - Authorization: RBAC
  - Input validation: JSON schema

4. Generate plan.md informed by epics:

markdown

# plan.md tasks organized by epic

## Epic E-001: Data Layer (from epics.md)
Priority: P0 (Foundation)
Dependencies: None

Tasks:
- [ ] impl_001: Create database schema (from architecture.md data models)
- [ ] impl_002: Implement ORM entities
- [ ] test_001: Unit tests for data layer

## Epic E-002: API Layer (from epics.md)
Priority: P0 (Core functionality)
Dependencies: E-001

Tasks:
- [ ] impl_003: Create API endpoints (from architecture.md)
- [ ] impl_004: Implement request validation
- [ ] test_002: API integration tests

Interactive Prompts

When planning exists:

code

I found BMAD planning documents:
  ✓ planning/<feature>/requirements.md (15 functional requirements)
  ✓ planning/<feature>/architecture.md (Python/FastAPI stack, PostgreSQL)
  ✓ planning/<feature>/epics.md (3 epics: Data, API, Tests)

I'll use these as context to create detailed SpecKit specifications.

Based on the requirements, I see these priority P0 epics:
  - E-001: Data Layer (Foundation)
  - E-002: API Layer (Core functionality)

The architecture specifies:
  - Framework: FastAPI
  - Database: PostgreSQL with SQLAlchemy
  - Testing: pytest with ≥80% coverage

Would you like me to expand on any areas before generating specs? (Y/n)

When no planning:

code

No BMAD planning documents found.

I'll create specifications from scratch through interactive Q&A.

What is the main purpose of this feature?
> [User describes]

What technology stack should we use?
> [User specifies or accepts defaults]

Any specific performance or security requirements?
> [User answers]

Generating specifications...

Best Practices

When BMAD Planning Exists:

•Use planning as foundation: Reference ../planning/<feature>/requirements.md sections
•Be consistent: Technology choices must match architecture.md
•Epic-driven tasks: Break down plan.md tasks by epic from epics.md
•Acceptance criteria alignment: spec.md AC must cover requirements.md success criteria
•Traceability: spec.md references FR-001, FR-002...; plan.md references E-001, E-002...
•Justify deviations: If deviating from architecture.md, document why

When BMAD Planning Doesn't Exist:

•Gather requirements interactively: Ask user for purpose, users, success criteria
•Document assumptions: State technology choices and rationale
•Start simple: Can always add complexity later
•Ask clarifying questions: Better to clarify upfront than rework later

Always:

•Be specific: Include exact file names, function signatures, data structures
•Code examples: Show actual implementation patterns
•API contracts: Define exact request/response formats
•Test cases: Specify what to test and expected outcomes
•Dependencies: List what must be done first (refer to epic dependencies)

SpecKit → BMAD Feedback (As-Built Documentation)

After implementation completes and PR is merged to contrib branch, SpecKit outputs should update BMAD planning docs with as-built details.

When to Update BMAD Planning

Trigger: Phase 4, after feature PR merged to contrib/<gh-user>

Location: Back in main repo on contrib branch

Process:

bash

# After PR merge, back in main repo
cd /Users/user/Documents/GitHub/german
git checkout contrib/stharrold
git pull origin contrib/stharrold

# Run as-built documentation update
python .claude/skills/speckit-author/scripts/update_asbuilt.py \
  planning/<feature>/ \
  specs/<feature>/

What Gets Updated

planning/<feature>/requirements.md:

markdown

## As-Built Notes

**Implementation Date:** 2025-10-23
**Final Implementation:** specs/<feature>/spec.md in feature worktree

### Deviations from Original Plan

**FR-001: Original Requirement**
- Planned: Use Redis for caching
- As-Built: Used in-memory caching (LRU cache)
- Reason: Redis not needed for current scale, simpler deployment

**FR-003: Original Requirement**
- Planned: Real-time WebSocket updates
- As-Built: Polling every 30 seconds
- Reason: Simpler implementation, meets performance requirements

### Lessons Learned

- Database connection pooling: Default settings were sufficient
- Testing: Achieved 87% coverage (exceeded 80% goal)
- Performance: Response times < 100ms (better than 200ms target)

planning/<feature>/architecture.md:

markdown

## As-Built Architecture

**Implemented:** 2025-10-23
**Detailed Spec:** specs/<feature>/spec.md

### Technology Stack (Final)

Matches planned architecture with these changes:
- Database: PostgreSQL (as planned)
- Caching: ~~Redis~~ → Python LRU cache
- API Framework: FastAPI (as planned)

### Actual Data Models

Final database schema implemented in src/models/:
- [Link to actual code files]
- Schema migration: migrations/versions/abc123_initial.py

### API Endpoints (Implemented)

All planned endpoints implemented:
- POST /api/endpoint (spec.md line 89)
- GET /api/endpoint/{id} (spec.md line 144)
- Additional endpoint added: GET /api/endpoint/search (user request)

### Performance Metrics (Actual)

- Response time p95: 87ms (target: 200ms) ✓
- Throughput: 1200 req/s (target: 1000 req/s) ✓
- Test coverage: 87% (target: 80%) ✓

planning/<feature>/epics.md:

markdown

## Epic Completion Status

### E-001: Data Layer (COMPLETED)
- Status: ✓ Completed 2025-10-23
- Actual effort: 2.5 days (estimated: 3 days)
- Delivered:
  - Database models (src/models/example.py)
  - Migrations (migrations/versions/)
  - Unit tests (tests/test_models.py)
- Notes: Faster than expected, schema design was solid

### E-002: API Layer (COMPLETED)
- Status: ✓ Completed 2025-10-25
- Actual effort: 3 days (estimated: 3 days)
- Delivered:
  - FastAPI routes (src/api/routes.py)
  - Request/response models (src/api/models.py)
  - Integration tests (tests/test_api.py)
- Deviations:
  - Added search endpoint (not in original epic)
  - Used simpler caching strategy

### E-003: Testing & Quality (COMPLETED)
- Status: ✓ Completed 2025-10-26
- Actual effort: 1.5 days (estimated: 2 days)
- Delivered:
  - Test coverage: 87% (target: 80%)
  - All quality gates passing
- Notes: Exceeded coverage target

## Lessons Learned for Future Epics

1. **Estimation accuracy:** Data layer took less time due to good planning
2. **Scope changes:** Added search endpoint mid-implementation (user request)
3. **Technology choices:** Simpler caching was sufficient, saved complexity
4. **Quality gates:** Setting ≥80% coverage target was appropriate

Script: `update_asbuilt.py`

Location: .claude/skills/speckit-author/scripts/update_asbuilt.py

Purpose: Reads specs/ from worktree, updates planning/ with as-built details

Usage:

bash

python .claude/skills/speckit-author/scripts/update_asbuilt.py \
  planning/my-feature/ \
  specs/my-feature/

What it does:

•Read spec.md and plan.md from merged feature specs/
•Extract: deviations, actual timelines, lessons learned
•Update planning/ files with "As-Built" sections
•Prompt user for: deviation reasons, lessons learned, metrics
•Commit updates to contrib branch

Interactive prompts:

code

Reading as-built specs from merged feature...
  ✓ Found specs/my-feature/spec.md
  ✓ Found specs/my-feature/plan.md

Analyzing deviations from BMAD planning...

Found potential deviation:
  Planned: Redis caching (architecture.md line 64)
  As-Built: LRU cache (spec.md line 142)

Why was this changed?
> [User explains: Simpler, meets requirements]

[Continue for all deviations...]

Found completed epics:
  E-001: Data Layer (3 tasks completed)
  E-002: API Layer (4 tasks completed)

E-001 estimated 3 days, how long did it actually take?
> [User: 2.5 days]

Any lessons learned for E-001?
> [User: Schema design was solid, migrations went smoothly]

[Continue for all epics...]

Updating planning documents...
  ✓ Updated planning/my-feature/requirements.md (added as-built notes)
  ✓ Updated planning/my-feature/architecture.md (added as-built architecture)
  ✓ Updated planning/my-feature/epics.md (added completion status)

Commit these updates? (Y/n)

Why This Matters

Living Documentation:

•Planning docs evolve from "planned" to "as-built"
•Historical record of decisions and changes
•Future features can reference actual outcomes

Improved Planning:

•Learn from deviations (why did we change the plan?)
•Improve estimation accuracy (actual vs estimated effort)
•Identify patterns (certain epics always take longer)

Traceability:

code

requirements.md (planned) → spec.md (detailed) → src/ (code) → requirements.md (as-built)

•Complete lifecycle documented
•Easy to find why decisions were made
•Reference for similar future features

SpecKit Author

Purpose

When to Use

Document Templates

Interactive Callable Tool

Invocation

Interactive Session Flow

With BMAD Planning (Recommended)

Without BMAD Planning

Script Architecture

create_specifications.py

Directory Structure

update_asbuilt.py

Integration with Workflow

Phase 2: Create Specifications (Step 2.3)

Phase 4: Update As-Built (Step 4.4)

Template Placeholders

Using BMAD Planning Context

SpecKit Should:

Interactive Prompts

Best Practices

When BMAD Planning Exists:

When BMAD Planning Doesn't Exist:

Always:

SpecKit → BMAD Feedback (As-Built Documentation)

When to Update BMAD Planning

What Gets Updated

Script: update_asbuilt.py

Why This Matters

Script: `update_asbuilt.py`