Spec-Driven Development
Relevant source files
The following files were used as context for generating this wiki page:
Spec-Driven Development (SDD) is a framework used for complex changes in Infrahub, such as designing new schema nodes or building cascading generator chains. It requires an agent to reason through requirements and plan the implementation before generating code. This process identifies design issues, such as incorrect relationship cardinality or missing configuration keys, before they require debugging in a live environment.
Sources: README.md:92-96, README.md:104-106
SDD Workflow
The SDD framework utilizes a structured approach to move from a natural-language description to implemented resources. You provide a specification, and the assistant generates a plan that is validated against Infrahub skills. This plan is then decomposed into discrete, actionable tasks.
Sources: README.md:104-106, specs/001-towncrier-release-process/plan.md:3-5
Phases of SDD
The standard workflow consists of four distinct stages:
| Stage | Action | Output |
|---|---|---|
| Specify | You describe the desired feature or system. | Requirements capture and workflow selection. |
| Plan | The agent creates an implementation plan. | A plan validated against Infrahub skill conventions. |
| Tasks | The plan is broken into specific steps. | A task list where each item is mapped to a skill. |
| Implement | The agent executes each task. | Working Infrahub code (schemas, checks, etc.). |
Sources: README.md:108-112
Process Flow Diagram
The following diagram illustrates the transition from a user requirement to the final implemented artifact through the SDD phases.
The SDD workflow ensures that reasoning and design validation occur before any code implementation begins. Sources: README.md:104-112
Implementation Artifacts
In an SDD project, specific files document the design and execution steps. These are typically stored in a dedicated directory within the repository.
Design Documentation
- Specification (
spec.md): Defines the feature requirements and user stories. - Implementation Plan (
plan.md): Outlines the technical context, dependencies, and project structure changes. - Task List (
tasks.md): Lists discrete tasks, often grouped by user story or implementation phase.
Sources: specs/001-towncrier-release-process/plan.md:1-5, specs/001-towncrier-release-process/tasks.md:1-10
Plan Structure
A comprehensive implementation plan includes several critical sections to ensure technical accuracy:
- Summary: High-level goal of the change.
- Technical Context: Versions, primary dependencies, and storage requirements.
- Constraints: Specific limitations, such as version synchronization across multiple files (e.g.,
plugin.json,SKILL.md,pyproject.toml). - Constitution Check: Validation against project-specific rules, such as versioning requirements or test coverage for new skills.
Sources: specs/001-towncrier-release-process/plan.md:7-40
Task Management
Tasks are organized to allow for parallel execution where possible and to define clear dependencies between steps.
The task list serves as the bridge between the validated plan and the final implementation skills. Sources: README.md:111-112, specs/001-towncrier-release-process/tasks.md:7-14
Task Formatting
Tasks are typically formatted to include specific metadata:
- ID: Unique identifier (e.g., T001).
- Parallel Flag [P]: Indicates if the task can run independently.
- Story Reference: Links the task back to a user story in the specification.
Sources: specs/001-towncrier-release-process/tasks.md:12-16
Usage Scenarios
While simple changes like adding an attribute can use "Direct Mode," SDD is required for architectural changes.
| Scenario | Recommended Approach |
|---|---|
| Designing new schema nodes with relationships | Spec-driven |
| Building cascading generator chains | Spec-driven |
| Standing up a complete new domain | Spec-driven |
| Refactoring relationships across multiple files | Spec-driven |
Sources: README.md:116-125
Summary
Spec-Driven Development provides a disciplined framework for managing infrastructure data complexity. By prioritizing reasoning and planning, it ensures that Infrahub resources—such as schemas and generators—adhere to project constraints and best practices before deployment. This approach minimizes technical debt and synchronization errors across the Infrahub ecosystem.