Speckit Automation Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• .agents/commands/speckit.auto.run.md
• .agents/commands/speckit.specify.md
• dev/adr/0001-context-nuggets-pattern.md
• specs/001-infrahub-testcontainers/plan.md
• specs/archive/20260604-141223-session-branch-recovery/tasks.md
• AGENTS.md

The Speckit Automation Workflow defines a structured, iterative process for managing feature lifecycles within the infrahub-mcp repository. It utilizes AI agent commands to transform abstract ideas into technical specifications, implementation plans, and discrete executable tasks. This workflow ensures that every feature undergoes rigorous design validation, architecture alignment, and security checks before implementation begins.

This system relies on the Context Nuggets pattern, which organizes project knowledge into small, focused files to optimize AI agent context usage and maintainability. The workflow is orchestrated through the .specify/ directory, which contains templates and scaffolding for specifications, plans, and task lists.

Sources: dev/adr/0001-context-nuggets-pattern.md, AGENTS.md, .agents/commands/speckit.specify.md

Core Workflow Phases

The Speckit workflow follows a linear progression from initial conception to implementation readiness. Each phase produces specific artifacts that serve as inputs for the next stage.

1. Specification Phase

The AI agent uses the speckit.specify command to create a spec.md file. This document focuses on functional requirements, user scenarios, and success criteria without including implementation details. The process includes:

• Extracting requirements from user descriptions.
• Identifying edge cases and assumptions.
• Defining measurable success criteria (e.g., SC-001, SC-002).

Sources: .agents/commands/speckit.specify.md, specs/001-infrahub-testcontainers/plan.md

2. Planning Phase

Once the specification is accepted, the workflow moves to creating a plan.md. This phase identifies the technical path forward, including:

• Constitution Check: A mandatory gate that verifies the proposed design against project principles, such as branch-safety and type safety.
• Research: Resolving technical unknowns and recording them in a research.md file.
• Data Modeling: Defining the state models and contracts for new features.

Sources: specs/001-infrahub-testcontainers/plan.md, specs/archive/20260604-141223-session-branch-recovery/tasks.md

3. Task Generation and Execution

The tasks.md file serves as the final executable artifact. It organizes the work into logical phases (e.g., Foundational, MVP, Polish) and tracks completion via Markdown checkboxes.

Sources: specs/archive/20260604-141223-session-branch-recovery/tasks.md

Artifact Structure

The Speckit workflow utilizes a standardized directory structure for every feature to maintain project clarity.

File	Purpose	Key Content
spec.md	Functional definition	User stories, acceptance scenarios, functional requirements.
plan.md	Technical strategy	Architecture, dependencies, Constitution check results.
tasks.md	Execution roadmap	Phased task list, file paths, dependency-ordered steps.
research.md	Knowledge gathering	Resolution of technical unknowns and design alternatives.

Sources: specs/001-infrahub-testcontainers/plan.md, specs/archive/20260604-141223-session-branch-recovery/tasks.md

The Constitution Gate

A critical component of the Speckit workflow is the Constitution Check. Before implementation tasks are generated, the architect must verify the plan against the Infrahub MCP Server Constitution. This ensures that new features do not violate core tenets like:

• Branch-Safe by Default: Isolation of writes to session branches.
• Infrahub SDK Integration: Mandating SDK usage over raw HTTP.
• Security Boundaries: Validating inputs at system boundaries.

Repository Organization

The workflow is integrated into the repository through the following directory structure:

• dev/: Contains the project constitution.md, Architecture Decision Records (adr/), and guidelines.
• .agents/commands/: Stores the logic for Speckit commands like speckit.auto.run and speckit.specify.
• .specify/: Holds the templates and extensions used to scaffold feature documentation.
• specs/: Stores the output artifacts (spec, plan, tasks) for every feature, organized by name or ID.

Sources: dev/adr/0001-context-nuggets-pattern.md, AGENTS.md

Implementation Procedure

To implement a feature using Speckit, you follow these steps:

1. Initialize the specification using the speckit.specify command based on a feature request.
2. Conduct research to resolve unknowns, recording findings in research.md.
3. Draft the plan.md and complete the Constitution Check table.
4. Generate tasks.md, organizing them by Phase (e.g., Phase 1: Setup, Phase 2: Foundational).
5. Execute tasks sequentially, updating the checkboxes in tasks.md as work progresses.

Sources: specs/001-infrahub-testcontainers/tasks.md, specs/archive/20260604-141223-session-branch-recovery/tasks.md

The Speckit Automation Workflow provides a disciplined framework for infrastructure code development. By enforcing design documentation and principle-based validation, it reduces architectural drift and ensures high-quality implementation in the infrahub-mcp project.