Skip to main content
Generaljpoutrin

create-tech-spec

Create a new Technical Specification for implementation details

Stars
13
Source
jpoutrin/product-forge
Updated
2026-03-01
Slug
jpoutrin--product-forge--create-tech-spec
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/jpoutrin/product-forge/HEAD/plugins/devops-data/skills/create-tech-spec/SKILL.md -o .claude/skills/create-tech-spec.md

Drops the SKILL.md into .claude/skills/create-tech-spec.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

create-tech-spec

Category: Technical Architecture

Usage

/create-tech-spec <spec-title> [--rfc RFC-XXXX]

Arguments

  • <spec-title>: Required - Descriptive title for the Tech Spec (will be kebab-cased for filename)
  • --rfc RFC-XXXX: Optional - Link to RFC that this spec implements

Execution Instructions

When this command is run, Claude Code should:

  1. Determine Tech Spec Number

    • Scan tech-specs/ directory (all subdirectories) for existing files
    • Find highest TS-XXXX number
    • Increment by 1 for new spec
    • If no specs exist, start with TS-0001

  2. Create Directory Structure (if not exists)

    tech-specs/
├── draft/
├── approved/
├── reference/
└── archive/
    └── YYYY/

  3. Generate Tech Spec File

    • Convert title to kebab-case: "User Authentication API" → "user-authentication-api"
    • Create file: tech-specs/draft/TS-XXXX-<kebab-title>.md
    • Use template from skill references

  4. Populate Metadata

    • Set tech_spec_id to new number
    • Set title from argument
    • Set status to DRAFT
    • Set decision_ref to RFC if provided
    • Set created and last_updated to today's date
    • Leave author for user to fill

  5. If RFC provided, validate and link

    • Check RFC exists
    • Add link in metadata
    • Suggest copying relevant technical details from RFC

  6. Confirm Creation

    Created TS-XXXX: <title>

Location: tech-specs/draft/TS-XXXX-<kebab-title>.md
Status: DRAFT
RFC Link: RFC-XXXX (if provided)

Next steps:
1. Fill in the Executive Summary
2. Document the Design Overview with architecture diagram
3. Complete API and Data Model sections
4. When ready: /tech-spec-status TS-XXXX --set APPROVED

Template Reference

Use the template from: plugins/devops-data/skills/technical-specification/references/tech-spec-template.md

Example Usage

# Standalone tech spec
/create-tech-spec User Authentication API

# Tech spec implementing an RFC
/create-tech-spec Payment Gateway Integration --rfc RFC-0042

Creates:

  • tech-specs/draft/TS-0001-user-authentication-api.md
  • tech-specs/draft/TS-0002-payment-gateway-integration.md

Validation

  • Title must be provided (not empty)
  • Title should be 2-6 words for clarity
  • If RFC provided, verify it exists and is APPROVED
  • Warn if similar Tech Spec already exists

Error Handling

  • If tech-specs/ directory doesn't exist, create it with full structure
  • If title is empty, prompt user for title
  • If RFC not found, warn but allow creation
  • If similar spec exists, ask for confirmation