define-tech-spec

name	define-tech-spec
description	Create tech specs with architecture for Stage C of the VibeFlow docs-first workflow
metadata	{"triggers":["tech spec","specification","Stage C","system specification"]}

define-tech-spec

Create tech specs with architecture for Stage C of the VibeFlow docs-first workflow.

Purpose

This skill creates and validates Tech Spec documents for Stage C:

• Define architecture and interfaces
• Document data contracts and SLOs
• Specify component inventory and topology

Workflow

Stage C: Specify
    │
    ├── Create/update Tech Specs
    ├── Define architecture and interfaces
    └── Document data contracts and SLOs

Usage

Create/Update Tech Spec

/define-tech-spec <spec-name>

Creates or updates docs/specs/spec-<name>.md.

Example:

/define-tech-spec api
/define-tech-spec llm

Document Requirements

Tech Spec (docs/specs/spec-<name>.md)

Required sections:

• Header (version, status, PRD link, contract versions)
• Overview & Goals
• Architecture (topology diagram + component inventory)
• Interfaces & Data Contracts
• Data & Storage
• Reliability & SLIs/SLOs
• Security & Privacy
• Evaluation Plan

Validation

• scripts/validate_techspec.py — Validate tech spec

References

See assets/:

• techspec-template.md — Tech spec template

Context7 Library Research

Follow the workflow in .claude/rules/context7-research.md to fetch current library documentation.

What to look for: API surfaces, configuration options, integration patterns, version constraints.

Where to incorporate findings:

• Architecture — topology and component interactions with external dependencies
• Interfaces & Data Contracts — exact types, parameters, and return values from library APIs
• Reliability — known limitations, failure modes, and SLO implications

Manifest Update

After completing Stage C, update docs/workflow-state.yaml:

• Set stage: C
• Append to docs.specs[]: docs/specs/spec-<name>.md

Git Commit

After completing this stage, ask the user for permission before committing:

git add docs/specs/spec-<name>.md docs/workflow-state.yaml
git commit -m "feat(spec): define <name> tech spec (#ft-<ID>)"

Replace <name> and <ID> with actual values.

Auto-Advance

After the commit is complete, directly run /manage-work advance <ID> to advance to the next stage.