stharrold/speckit-author

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:

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:

# 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:

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:

1. Script detects ../planning/my-feature/ directory
2. Reads requirements.md, architecture.md, epics.md
3. Displays BMAD summary
4. Asks 5-8 implementation-specific questions
5. Generates spec.md + plan.md aligned with BMAD
6. Creates compliant specs/<slug>/ directory structure
7. Updates TODO_*.md with tasks parsed from plan.md
8. 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:

======================================================================
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:

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

Script Architecture

create_specifications.py

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

Implements:

1. Context Detection

   • Verifies running in worktree (not main repo)
   • Auto-detects or accepts TODO file path
   • Checks for BMAD planning in ../planning/<slug>/

2. Interactive Q&A

   • Adapts questions based on BMAD availability
   • With BMAD: 5-8 implementation-specific questions
   • Without BMAD: 10-15 comprehensive requirements questions

3. Template Processing

   • Loads spec.md.template and plan.md.template
   • Replaces placeholders ({{TITLE}}, {{SLUG}}, {{DATE}}, etc.)
   • Injects Q&A context as implementation notes

4. Directory Creation

   • Creates specs/<slug>/ with compliant structure
   • Generates CLAUDE.md and README.md
   • Creates ARCHIVED/ subdirectory

5. TODO Update

   • Parses task IDs from plan.md
   • Updates TODO_*.md YAML frontmatter
   • Groups tasks by category (impl, test, doc, etc.)

6. Git Commit

   • Stages specs/<slug>/ and TODO file
   • Creates descriptive commit message
   • References TODO file in commit

Directory Structure

Specification documents are created in:

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:

1. Read As-Built Specs

   • Reads specs/<slug>/spec.md and plan.md
   • Reads TODO_*.md for effort/timeline data

2. Compare with Planning

   • Auto-detects deviations (technology changes)
   • Interactive Q&A for manual deviation identification

3. Gather Metrics

   • Epic completion (estimated vs actual effort)
   • Quality metrics (coverage, performance)
   • Lessons learned

4. Update Planning Docs

   • Appends "## As-Built Notes" to requirements.md
   • Appends "## As-Built Architecture" to architecture.md
   • Appends "## Epic Completion Status" to epics.md

5. Git Commit

   • Commits updated planning documents
   • Creates feedback loop for future planning

Invocation:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

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:

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:

# 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:

## 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:

## 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:

## 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:

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

What it does:

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

Interactive prompts:

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:

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