define-tech-spec
npx machina-cli add skill hardness1020/VibeFlow/define-tech-spec --openclawdefine-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
Manifest Update
After completing Stage C, update docs/workflow-state.yaml:
- Set
stage: C - Append to
docs.specs[]:docs/specs/spec-<name>.md
To advance to the next stage: /manage-work advance <ID>
Source
git clone https://github.com/hardness1020/VibeFlow/blob/main/.claude/skills/define-tech-spec/SKILL.mdView on GitHub Overview
Creates and validates Tech Spec documents for Stage C of the VibeFlow docs-first workflow. It defines architecture and interfaces, documents data contracts and SLOs, and inventories components and topology.
How This Skill Works
Accepts a spec-name via /define-tech-spec <name>, creating or updating docs/specs/spec-<name>.md. It enforces required sections (Header, Overview, Architecture, Interfaces & Data Contracts, Data & Storage, Reliability & SLIs/SLOs, Security & Privacy, Evaluation Plan) and validates the file with scripts/validate_techspec.py using the techspec-template.md.
When to Use It
- When starting Stage C for a feature or system
- When documenting architecture, topology, and component inventory
- When specifying data contracts and SLIs/SLOs
- When aligning interfaces between components
- When preparing for verification and validation before implementation
Quick Start
- Step 1: /define-tech-spec <spec-name>
- Step 2: Fill docs/specs/spec-<name>.md with required sections (Header, Overview, Architecture, Interfaces & Data Contracts, Data & Storage, Reliability & SLOs, Security & Privacy, Evaluation Plan)
- Step 3: Run scripts/validate_techspec.py and update docs/workflow-state.yaml; advance with /manage-work advance <ID>
Best Practices
- Start with the official header including version, status, PRD link, and contract versions
- Include a topology diagram and a complete component inventory in Architecture
- Clearly define data contracts and SLIs/SLOs with testable criteria
- Reuse assets/techspec-template.md to maintain consistency
- Validate with scripts/validate_techspec.py and update workflow state after approval
Example Use Cases
- Tech spec for Payments API detailing architecture, interfaces, and data contracts
- Tech spec for LLM inference pipeline with topology and SLOs
- Tech spec for User Authentication service with security/privacy considerations
- Tech spec for Data Ingestion pipeline including data contracts and storage
- Tech spec for Edge service topology and reliability requirements
