# intent-driven.dev — Full Content (llms-full.txt) Master Spec-Driven Development for AI coding agents URL: https://intent-driven.dev/llms-full.txt This is the full-content variant of https://intent-driven.dev/llms.txt. It inlines the complete text of the knowledge hub pages and blog posts so AI coding agents can ground responses in intent-driven.dev's actual content without fetching every page individually. The curated index of links lives at https://intent-driven.dev/llms.txt. Generated automatically by the site build — do not edit by hand. ================================================================================ # KNOWLEDGE HUB ================================================================================ -------------------------------------------------------------------------------- # AsyncAPI & Event-Driven SDD | Spec-Driven Development URL: https://intent-driven.dev/knowledge/asyncapi-event-driven/ Home > Knowledge > AsyncAPI & Event-Driven SDD AsyncAPI & Event-Driven SDD Category: Best Practices & Advanced Topics Last updated: December 28, 2025 Overview AsyncAPI is a specification format for describing event-driven architectures (EDA). When combined with spec-driven development practices, AsyncAPI provides a powerful bridge between design intent and AI-generated code for asynchronous, message-based systems. Note: This page will be expanded with detailed examples and patterns after the DeveloperWeek San Jose talk (February 18-20, 2026): "Supercharging Spec-Driven Development for Event-Driven Architectures with AsyncAPI" Why AsyncAPI for SDD? Event-driven architectures introduce unique challenges for spec-driven development: Asynchronous communication: Traditional specs assume synchronous request-response patterns Event schemas: Message formats must be precisely defined for producers and consumers Channel definitions: Topics, queues, and routing need clear specification Protocol details: AMQP, Kafka, WebSockets, etc. each have specific requirements Producer-consumer contracts: Both sides must agree on message structure and behavior AsyncAPI provides a structured format for specifying all these aspects, making it an ideal foundation for SDD in event-driven systems. AsyncAPI & Spec-Driven Development AsyncAPI specifications serve multiple roles in SDD: 1. Design Intent Documentation AsyncAPI specs explicitly define what events exist, their schemas, and how systems interact through messages. This captures design intent before implementation begins. 2. AI Agent Guidance AI coding agents can use AsyncAPI specs to generate: Event producer code with correct message formats Event consumer handlers matching specified schemas Protocol-specific connection and configuration code Validation logic ensuring messages conform to specs 3. Contract Validation AsyncAPI enables contract testing between producers and consumers, ensuring both sides remain synchronized with the specification. 4. Documentation Generation AsyncAPI tools can generate human-readable documentation from specs, keeping documentation synchronized with actual system design. Event-Driven Architecture Patterns Common EDA patterns that benefit from AsyncAPI specifications: Pub/Sub: Publishers emit events to topics; subscribers consume them Message Queue: Point-to-point messaging with work distribution Event Sourcing: State changes recorded as immutable events CQRS: Command and query responsibility segregation with event-driven sync Saga Patterns: Distributed transactions coordinated through events Each pattern requires precise specification of message flows, schemas, and error handling—exactly what AsyncAPI provides. Upcoming: DeveloperWeek Talk Supercharging Spec-Driven Development for Event-Driven Architectures with AsyncAPI DeveloperWeek San Jose 2026 February 18-20, 2026 San Jose Convention Center This talk will demonstrate practical patterns for combining AsyncAPI with SDD tools, show real-world examples, and provide actionable guidance for teams building event-driven systems. View speaker page → This knowledge page will be significantly expanded with detailed examples, code snippets, and integration patterns after the conference. Getting Started with AsyncAPI While this page awaits detailed SDD integration content, you can start exploring AsyncAPI: AsyncAPI Official Website Specification documentation, tools, and getting started guides. AsyncAPI Getting Started Tutorial Learn how to create your first AsyncAPI specification. Related Topics SDD Workflows Core workflow patterns applicable to event-driven systems. Best Practices SDD principles for maintaining specification quality. Context Engineering Foundational practice for structuring event-driven specifications. -------------------------------------------------------------------------------- # Best Practices | Spec-Driven Development URL: https://intent-driven.dev/knowledge/best-practices/ Home > Knowledge > Best Practices Best Practices for Spec-Driven Development Category: Best Practices Last updated: November 20, 2025 Overview Effective Spec-Driven Development (SDD) requires more than just writing specifications before code—it demands disciplined practices that keep specifications human-reviewable, meaningfully decomposed, and continuously aligned with implementation. These best practices ensure teams maintain the value of specification-first development without overwhelming context windows or creating documentation that no one actually validates. The practices outlined here focus on real-world effectiveness, particularly when working with AI coding agents that can quickly generate extensive specifications but require human oversight to maintain intentionality and clarity. This is a curated summary from practical implementation guides. Read about managing context length in SDD → Core Principles Prioritize Human Reviewability The fundamental test: Are the artifacts human reviewable? If you find yourself skimming specification changes while thinking "the AI probably got it right," the feature is too large. Specifications must maintain their intended clarity and intentionality rather than becoming auto-generated documentation no one actually validates. Human review ensures specifications capture genuine design intent. When specifications become too lengthy to review effectively, they lose their value as sources of truth and become liability rather than asset. Start with Minimal Specifications Begin by fully specifying features concisely—avoid long chains of "and" statements that balloon complexity. Large monolithic specifications force AI agents into extensive clarification phases and exhaust context windows unnecessarily. Minimal doesn't mean incomplete. It means capturing exactly what's needed for the current feature without prematurely specifying future requirements or edge cases that aren't immediately relevant. Decompose Meaningfully Break oversized features into valuable, independently-deliverable slices rather than attempting comprehensive specifications upfront. Apply frameworks like INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable) to validate story quality, and use MoSCoW prioritization (Must have, Should have, Could have, Won't have) to focus on must-haves first. Meaningful decomposition creates features that provide value on their own, rather than arbitrary technical splits that deliver no user benefit until fully assembled. Context Management Strategies Address the "Lost in the Middle" Problem While specifications help engineer context to avoid recency/primacy bias, oversized specs themselves suffer from these same issues. Forgotten clarifications and requirement drift can emerge during development when the specification document itself becomes too lengthy. Keep specifications focused enough that the entire specification remains accessible to the AI agent or human developer throughout implementation. This prevents the specification from becoming part of the problem it's meant to solve. Leverage Subagents Strategically Delegate research and validation tasks to subagents with isolated contexts to reduce overall burden and enable parallelization—but only after right-sizing the feature itself. Subagents are a capability multiplier, not a substitute for good feature decomposition. Tool Selection Matters Less Than Thinking Switching tools or debating markdown efficiency won't solve fundamental decomposition problems. Structured thinking about feature sizing precedes any tooling optimization. Choose tools that support your workflow, but recognize that no tool compensates for poorly decomposed features. Maintaining Specification Quality Specification as Source of Truth Maintain specifications as the authoritative reference for system behavior. This creates shared understanding across teams and provides a validation anchor for implementations. When specifications drift from implementation, they become unreliable—defeating the entire purpose of spec-driven development. Systems Thinking for Cross-Feature Analysis Features interact in non-linear ways. Apply systems thinking to detect cross-feature conflicts, feedback loops, and cascading effects before implementation. Understanding how features interact prevents emergent problems that appear only in production. For example, adding an inventory alert feature to an e-commerce system might seem straightforward until systems analysis reveals potential notification storms during peak traffic when combined with existing features. Continuous Validation Specifications provide value when continuously validated against implementation. Automated checks ensure alignment between specification and code, catching drift early when it's cheapest to fix. Validation isn't a one-time gate—it's an ongoing practice throughout development. Working Effectively with AI Agents Specifications Prevent "Vibe Coding" AI coding agents can quickly generate implementations, but without clear specifications, those implementations may drift from original intentions. Specifications provide design boundaries that keep agents aligned with intended outcomes rather than optimizing for speed alone. Human Review and Intentionality AI agents excel at translating clear specifications into code, but human judgment determines whether specifications capture the right intent. Maintain human oversight of specification quality—the human role shifts from writing code to ensuring specifications reflect genuine design decisions. Parallel Development with Clear Specifications Well-defined specifications enable parallel work streams. Different teams or agents can work simultaneously on frontend, backend, and integration when specifications clearly define interfaces and behavior. This parallelization accelerates delivery without sacrificing coordination. Common Anti-Patterns to Avoid Specification Theater: Writing detailed specs that no one reads or validates. Specifications must be living documents that teams actively use. Premature Comprehensiveness: Attempting to specify everything upfront rather than iteratively refining. Start minimal and evolve as understanding deepens. Tool Over-Reliance: Believing the right tool solves decomposition problems. Tools support good practices but don't substitute for structured thinking. Spec-Implementation Drift: Allowing specifications to diverge from implementation. Continuous validation prevents this decay. Ignoring Cross-Feature Effects: Analyzing features in isolation without systems thinking. Features interact—specifications should account for this. AI-Generated Specification Bloat: Accepting verbose AI-generated specs without human editing. Conciseness requires intentional curation. Learn More Mind the Context Length in Spec-Driven Development Practical strategies for keeping specifications human-reviewable and effective with AI agents. Source of Truth Specifications with OpenSpec How maintaining a single source of truth enables better workflows and continuous validation. Analyzing Across Features with Systems Thinking Using systems thinking to detect cross-feature conflicts and emergent behaviors. Related Topics Spec-Driven Development Workflows Learn about the fundamental SDD workflow and how to apply it effectively. OpenSpec Explore OpenSpec's source of truth approach to specifications. GitHub Spec Kit Discover how GitHub Spec Kit structures specification-first workflows. -------------------------------------------------------------------------------- # Context Engineering | Spec-Driven Development URL: https://intent-driven.dev/knowledge/context-engineering/ Home > Knowledge > Context Engineering Context Engineering Category: Core Concepts Last updated: December 28, 2025 Overview Context Engineering is the foundational practice of deliberately structuring information so AI agents understand what you need. It's about organizing your requirements, constraints, examples, and domain knowledge in a way that enables AI coding agents to build what you actually want, rather than what they infer from ambiguous prompts. In the era of AI-assisted development, the quality of your outputs depends directly on the quality of your inputs. Context engineering transforms "vibe coding"—where developers iteratively nudge AI toward desired outcomes—into a systematic approach where clear, structured context guides AI agents to correct implementations from the start. Whether you're using tactical approaches like plan mode or strategic frameworks like Spec-Driven Development, context engineering is the underlying practice that makes AI collaboration effective. Why Context Engineering Matters AI coding agents are powerful pattern matchers and code generators, but they lack deep understanding of your specific goals, constraints, and domain requirements. Without deliberate context engineering: Intent-to-implementation drift: AI implements what it thinks you want, leading to gradual divergence from your actual goals Missing constraints: Important business rules, security requirements, or performance needs get overlooked Inconsistent patterns: AI makes reasonable but conflicting architectural choices across different features Wasted iterations: Time spent nudging AI back toward intended behavior instead of building new capabilities Difficult validation: No clear reference point to verify whether AI implemented what you actually needed Structured context engineering addresses these issues by making your intent explicit, verifiable, and machine-readable. Context Engineering in Practice Poor Context Engineering Vague prompts that leave too much to AI interpretation: "Add user authentication to the app. Make it secure and easy to use." This lacks critical details: What authentication method? What security requirements? What does "easy to use" mean? Which parts of the app need protection? Good Context Engineering Structured, explicit context that guides AI to the right implementation: "Implement email/password authentication with the following requirements: Use JWT tokens with 24-hour expiration Passwords must meet OWASP guidelines (min 12 chars, mixed case, numbers, special chars) Rate limit login attempts: max 5 per 15 minutes per IP Protected routes: /dashboard, /settings, /api/* (except /api/public/*) Redirect authenticated users away from /login and /signup Store refresh tokens in httpOnly cookies Use our existing User model and Postgres database. Follow the authentication patterns from the existing session middleware." This provides clear requirements, constraints, and references to existing patterns. Approaches to Context Engineering Context engineering exists on a spectrum from tactical to strategic: Tactical: Plan Mode In plan mode, context engineering happens through conversational prompts and incremental clarification. You provide context as needed, AI proposes a plan, you refine it, and implementation proceeds. This works well for small features and exploratory work but requires active oversight to prevent drift. Learn more about Plan Mode vs Spec-Driven Development → Strategic: Spec-Driven Development Spec-Driven Development (SDD) is a strategic approach to context engineering where you create structured specification documents that serve as the authoritative source of truth. These specs explicitly define requirements, scenarios, and acceptance criteria before implementation begins. SDD tools like OpenSpec, GitHub Spec Kit, and Kiro provide frameworks for maintaining these specifications and keeping them synchronized with your codebase. Choosing Your Approach The right level of context engineering depends on your project's complexity, team size, and need for long-term maintainability. Many teams use both: plan mode for quick prototypes and experiments, SDD for production features and complex systems. Understand the differences between Vibe Coding and SDD → Learn More Vibe Coding vs Spec-Driven Development: Intent to Implementation Deviation and Context Engineering How vibe coding and spec-driven development differ in workflow and intent alignment. Which Spec-Driven Development Tool Should You Choose? Comprehensive comparison of tactical and strategic context engineering tools. Spec-Driven Development with OpenSpec: Source of Truth Specification How OpenSpec's source of truth approach enables better context engineering. Related Topics Plan Mode vs Spec-Driven Development Understand the difference between tactical and strategic context engineering approaches. Vibe Coding vs Spec-Driven Development Learn how vibe coding and SDD differ in workflow and intent alignment. Tool Selection Guide Choose the right context engineering tools for your team and project. Spec-Driven Development Workflows Learn about SDD workflow patterns and implementation approaches. -------------------------------------------------------------------------------- # Context Length Management | Spec-Driven Development URL: https://intent-driven.dev/knowledge/context-length/ Home > Knowledge > Context Length Context Length Management Category: Best Practices & Advanced Topics Last updated: December 28, 2025 Overview As LLM context windows expand, a natural question arises: does spec-driven development become less important? The relationship between SDD and context length is more nuanced than it appears. This is a curated summary. Read the full analysis → The Context Length Paradox Assumption: Larger context windows mean AI can "see" more code, reducing the need for explicit specifications. Reality: Context length and specification clarity serve different purposes: Context length provides information access - AI can read more code Specifications provide intent clarity - AI knows what you want More information doesn't automatically mean clearer intent. In fact, larger context can introduce more ambiguity if intent isn't explicit. When Context Length Helps Understanding existing code: AI can analyze larger codebases to understand current patterns Finding related code: Locate all places where a feature is implemented Maintaining consistency: See architectural patterns across files Reducing repetition: Don't need to manually copy-paste context into prompts These are valuable, but they don't replace explicit specifications. When Specs Still Matter Defining "correct": Code can compile and run but not match your actual requirements Edge cases: Existing code might not cover all scenarios you need Business rules: Domain constraints aren't always evident from code structure Security requirements: Critical requirements that must be explicit, not inferred Team alignment: Shared understanding of what system should do Optimization Strategies 1. Hierarchical Specifications Structure specs from high-level to detailed: System level: Overall architecture and key invariants Feature level: Specific requirements and scenarios Component level: Detailed behavior specs where needed AI can start with relevant level based on task scope. 2. Reference vs Inline Balance between including full specs vs referencing them: Include inline: Critical requirements that must not be missed Reference: Secondary constraints and background context 3. Progressive Disclosure Start with essential specs, add detail as needed: Core requirements first Main scenarios second Edge cases and constraints third 4. Spec Modularization Break large specs into focused modules: Easier to find relevant sections Better context utilization Clearer dependencies Trade-offs Approach Pros Cons Detailed specs Maximum clarity, comprehensive Uses more context, slower to write Minimal specs Fast to write, less context used Risk of ambiguity, incomplete requirements Balanced Core requirements explicit, detail as needed Requires judgment on what to include Best Practices Explicit over implicit: When in doubt, state it explicitly in specs Prioritize critical paths: Detailed specs for security, business logic, edge cases Leverage code context: Let AI read code for understanding current patterns Keep specs focused: One spec per capability or feature area Use examples: Concrete scenarios often clearer than abstract rules Learn More Spec-Driven Development - Mind the Context Length Comprehensive exploration of the relationship between SDD and LLM context windows. Related Topics Best Practices General SDD best practices and principles. SDD Workflows Learn workflow patterns for managing specs. -------------------------------------------------------------------------------- # Enterprise Spec-Driven Development URL: https://intent-driven.dev/knowledge/enterprise-sdd/ Home > Knowledge > Enterprise SDD Enterprise Spec-Driven Development Category: Enterprise Adoption Last updated: March 1, 2026 Overview Diagrams by Hari Krishnan, published in "Spec-Driven Development – Adoption at Enterprise Scale" . For more details, read the full article. The Harness Feedback Loop SDD Harness Feedback Loop Read the full article on InfoQ Learn about Intent Harness → Spec-Driven Development — Detailed Workflow SDD Detailed Workflow Read the full article on InfoQ Additional Workflow Perspectives Plan Mode Workflow Explore Plan Mode vs SDD → Vibe Coding Workflow Explore Vibe Coding vs SDD → Related Topics Spec-Driven Development Workflows Core SDD workflow patterns: write spec, implement, validate. OpenSpec Source of truth specification management for SDD teams. Best Practices Principles and practices for effective spec-driven development. Plan Mode vs SDD Vibe Coding vs SDD -------------------------------------------------------------------------------- # Getting Started with SDD | Spec-Driven Development URL: https://intent-driven.dev/knowledge/getting-started/ Home > Knowledge > Getting Started Getting Started with Spec-Driven Development Category: Workflows & Guides Last updated: December 28, 2025 Overview Adopting spec-driven development doesn't require a complete workflow overhaul. Start small, learn the fundamentals, and gradually increase adoption as you see benefits. Step 1: Understand Context Engineering Before diving into tools, understand the foundational concept: Learn context engineering - The practice of structuring information for AI agents Recognize the problem: Vibe coding leads to drift between intent and implementation Understand the solution: Explicit specifications provide clear reference points Step 2: Choose Your Starting Point Option A: Start Tactical (Recommended for Beginners) Begin with plan mode in your existing AI assistant: For your next feature, ask the AI to create a plan first Review and refine the plan before implementation Notice how explicit planning reduces iteration cycles Learn about plan mode → Option B: Start Strategic Choose a dedicated SDD tool and try it on a small feature: OpenSpec: Good for unified specifications and brownfield projects GitHub Spec Kit: Natural fit if you're already on GitHub Kiro: Easiest learning curve with all-in-one IDE Compare tools and choose → Step 3: Write Your First Spec Start simple. A good first spec includes: What it does: Clear description of the feature Requirements: Explicit list of what must be true Scenarios: Concrete examples of expected behavior Constraints: What the feature should NOT do Example: Simple Login Spec ## Login Feature **What it does:** Allows registered users to access the application. **Requirements:** - SHALL accept email and password - SHALL validate email format before submission - SHALL display error for invalid credentials - SHALL redirect to dashboard on successful login - SHALL rate-limit to 5 attempts per 15 minutes **Scenarios:** 1. Valid credentials → redirect to /dashboard 2. Invalid credentials → show error, do not redirect 3. Empty fields → show validation errors 4. 6th failed attempt → show rate limit message **Constraints:** - SHALL NOT store passwords in plain text - SHALL NOT allow brute force attacks - SHALL NOT expose whether email exists Step 4: Implement and Validate Give spec to AI: Use your spec to guide AI implementation Validate scenarios: Check that each scenario works as specified Iterate on spec: Update spec if you discover requirements were incomplete Keep spec synchronized: When implementation changes, update the spec Step 5: Gradual Adoption Expand SDD usage based on what works: If plan mode works: Continue using it for more features If you need more rigor: Graduate to a dedicated SDD tool If specs help: Apply to more complex features first If validation matters: Focus on critical business logic and security features Not every feature needs a formal spec. Use SDD where clarity and correctness matter most. Common Mistakes to Avoid Over-specifying: Don't write specs longer than the code. Stay focused on requirements and scenarios. Under-specifying: Specs that just repeat the feature name aren't helpful. Include concrete scenarios. Spec rot: Keep specs updated when implementation changes, or they become worse than no spec. All-or-nothing: You don't need specs for everything. Start with critical features. Next Steps Learn SDD workflow patterns → Discover SDD best practices → Compare SDD tools → Get expert training and workshops → Related Topics Context Engineering Foundation: Learn the core practice. SDD Workflows Understand common workflow patterns. Tool Selection Choose the right tool for your needs. -------------------------------------------------------------------------------- # Kiro | Spec-Driven Development URL: https://intent-driven.dev/knowledge/kiro/ Home > Knowledge > Kiro Kiro Category: Tools Last updated: November 20, 2025 Overview Kiro is an all-in-one AI IDE (based on a VS Code fork) designed for Spec-Driven Development. Unlike lightweight CLI tools, Kiro provides a comprehensive, integrated development environment that guides developers through structured workflows for building software with AI assistance. As an integrated IDE, Kiro emphasizes a complete development experience within a single environment, bringing together specification, design, and implementation tooling in one place. Learn more about Kiro and other SDD tools. Read about the SDD tools landscape → Core Workflow Kiro guides users through a structured three-phase workflow: 1. Requirements The first phase focuses on capturing and defining what needs to be built, establishing clear requirements before moving to design. 2. Design Once requirements are established, the design phase translates those requirements into technical specifications and architectural decisions. 3. Task List The final phase breaks down the design into concrete, implementable tasks that guide development work. This structured progression ensures teams move systematically from understanding what to build, through how to build it, to executing the implementation. Kiro's Approach As an IDE-centric tool, Kiro distinguishes itself from CLI-based alternatives by providing: Integrated Environment: All specification, design, and development work happens within a single IDE rather than across multiple tools Visual Workflows: IDE-based workflows provide visual structure and guidance through the SDD process AI-First Design: Built specifically for AI-assisted development, integrating AI capabilities throughout the workflow Comprehensive Tooling: Rather than being a lightweight addition to existing workflows, Kiro provides a complete environment When to Consider Kiro Kiro may be a good fit for teams that: Prefer integrated IDE experiences over CLI-based workflows Want a comprehensive environment for AI-assisted development Value visual workflows and structured guidance through development phases Are comfortable adopting a VS Code fork as their primary development environment Want all specification, design, and implementation tooling in one place The IDE-centric approach means Kiro is a more comprehensive commitment compared to lightweight CLI tools that integrate into existing workflows. Learn More Kiro Official Website Official Kiro website with documentation, downloads, and getting started guides. Growing List of Spec-Driven Development Tools Overview of the SDD tools landscape including Kiro and alternatives. Related Topics Spec-Driven Development Workflows Learn about common SDD workflow patterns across different tools. OpenSpec Compare with OpenSpec's lightweight CLI approach. GitHub Spec Kit Explore GitHub Spec Kit's GitHub-integrated workflow. -------------------------------------------------------------------------------- # OpenSpec | Spec-Driven Development URL: https://intent-driven.dev/knowledge/openspec/ Home > Knowledge > OpenSpec OpenSpec Category: Tools Last updated: May 10, 2026 On This Page Overview How OpenSpec Works Video Tutorials Workflow Diagrams Blog Posts Key Benefits When to Use OpenSpec Resources Related Topics Overview OpenSpec is a Spec-Driven Development (SDD) tool that emphasizes maintaining a single, unified specification document as the authoritative reference for a system's design and capabilities. Unlike traditional approaches that distribute specifications across multiple files, OpenSpec consolidates the current state of a system into one "living" specification that continuously evolves with the codebase. This source of truth approach addresses persistent challenges in fragmented specification systems, where the overall system intent becomes hard to grasp holistically, feature interactions go undetected until implementation, and validating the complete specification against the live system becomes nearly impossible. How OpenSpec Works The OpenSpec workflow revolves around three key artifact types: Change Specifications (Delta Specs) Delta specs represent proposed modifications. These interim documents mark sections as "ADDED," "MODIFIED," or "REMOVED," clearly communicating what has changed. This makes it easy for both humans and AI agents to understand exactly what's being proposed without needing to diff entire documents. Source of Truth Specification The primary specification represents the system's actual state. All delta changes eventually merge into this single document during the archive phase, creating a definitive reference that stakeholders can consult. This ensures everyone is working from the same understanding of what the system does. Archived Specifications Archived specs preserve the historical lineage of earlier delta specs once they've been incorporated into the source of truth, maintaining an audit trail of evolution. This creates accountability and allows teams to understand how and why decisions were made. Parallel Development with Git WorkTrees Git WorkTrees let you check out multiple branches simultaneously in separate directories. Combined with SubAgents in OpenCode, this enables genuine parallel feature development: propose on the main branch, apply each change in an isolated worktree via a SubAgent, then merge and archive in order. Each SubAgent runs Verify before merge, keeping the source of truth spec consistent across all parallel streams. Architectural Decision Records Custom OpenSpec schemas can extend the workflow with additional durable artifacts. The spec-driven-with-adr schema introduces Architectural Decision Records (ADRs) that live alongside the source of truth spec, outside of any single change. Specs capture the current state of the system's functionality; ADRs capture the current state of its architecture — the context, options, choices, and consequences behind every significant technical decision. Both artifacts persist after a change is archived, so future proposals can leverage prior reasoning during design instead of rediscovering it. Video Tutorials Learn OpenSpec workflows and best practices through our video tutorials. The playlist covers everything from getting started to advanced integration patterns. Watch Full Playlist Subscribe to Channel Workflow Diagrams Visual guides to understanding OpenSpec workflows and integration patterns. OpenSpec Workflow Diagram The complete Propose → Apply → Archive workflow showing how delta specs evolve into the source of truth specification. View on GitHub Linear MCP + OpenSpec Workflow Integration workflow showing how Linear MCP keeps the backlog in sync through the Propose, Apply, and Archive stages. Read the guide Git WorkTrees + OpenSpec Workflow How Git WorkTrees enable parallel OpenSpec changes, keeping each change isolated in its own worktree alongside the main branch. Read the guide Spec-Driven with ADR Schema How the spec-driven-with-adr custom schema keeps Architectural Decision Records as a durable artifact alongside the source of truth spec. Read the guide Blog Posts In-depth articles covering OpenSpec concepts, workflows, and integration patterns. Spec-Driven Development with OpenSpec and OpenCode May 10, 2026 — A walkthrough of the intent-driven template that wires OpenSpec setup, the openspec-git-discipline skill, grill-me proposals, C4 diagrams, ADRs, and the intent-driven custom schema into a single Spec-Driven Development workflow. Architectural Decision Records with Spec-Driven Development using OpenSpec April 29, 2026 — A custom OpenSpec schema that keeps Architectural Decision Records alongside specs, so architectural reasoning persists for future change proposals instead of being lost when a change is archived. OpenSpec, Git WorkTrees and OpenCode April 1, 2026 — A workflow for using Git WorkTrees and SubAgents in OpenCode to build features in parallel with OpenSpec: propose on main, apply in isolated worktrees, merge then archive. Spec-Driven Development with Brownfield Projects March 10, 2026 — Using custom OpenSpec profiles and the explore workflow to incrementally apply SDD to brownfield projects, with Repomix for context management. OpenSpec Custom Schemas February 12, 2026 — Custom schemas in OpenSpec let you tailor spec-driven workflows to your domain. Covers minimalist and event-driven schema examples. OpenSpec 1.0 Release January 26, 2026 — Release update for OpenSpec 1.0 with the walkthrough video and workflow highlights. Linear MCP + OpenSpec: A Spec-Driven Development Workflow January 11, 2026 — A practical walkthrough of using Linear MCP with OpenSpec to keep the backlog in sync. Covers roles, handoffs, and separating business use cases (What) from technical implementation (How). Spec-Driven Development with OpenSpec: Source of Truth Specification November 9, 2025 — Comprehensive guide explaining the OpenSpec workflow and source of truth specification concept. The foundational article for understanding OpenSpec. Key Benefits Spec-Anchored Alignment: By maintaining a unified specification, OpenSpec enables validation at any point against the current, authoritative specification. This contrasts with fragmented approaches that typically remain in "Spec-First" territory, where specifications guide initial design but gradually become unreliable as the implementation diverges. Faster Iteration Cycles: The streamlined workflow supports better flow states and quicker implementation cycles, especially when working with AI coding agents. Brownfield Support: Natural support for brownfield and legacy projects—you can capture existing system states without requiring complete rewrites. Feature Interaction Detection: Understanding unintended interactions between features becomes easier when everything is in one specification. Continuous Validation: Confidence that specifications remain synchronized with implementation through the source of truth model. When to Use OpenSpec OpenSpec excels for teams practicing incremental, spec-driven development who need confidence that specifications remain synchronized with implementation. It works particularly well for: Projects requiring continuous validation between specification and code Brownfield or legacy system modernization efforts Teams that value quick iteration and frequent specification updates Systems where understanding unintended interactions between features is critical Development workflows involving AI coding agents The tool assumes comfort with AI-assisted development and maintaining disciplined change practices through small, focused modifications. Resources OpenSpec GitHub Repository Official OpenSpec repository with documentation, examples, and CLI tool. OpenSpec GitHub Discussion Community discussion and feedback on OpenSpec workflows and best practices. Related Topics Spec-Driven Development Workflows Learn about common SDD workflow patterns and how to implement them effectively. GitHub Spec Kit Compare with GitHub Spec Kit's GitHub-integrated workflow approach. Spec Kit vs OpenSpec Detailed head-to-head comparison of both tools with recommendations. Kiro Explore Kiro's all-in-one IDE approach to spec-driven development. Best Practices Learn best practices for effective spec-driven development. -------------------------------------------------------------------------------- # Plan Mode vs Spec-Driven Development URL: https://intent-driven.dev/knowledge/plan-mode-vs-sdd/ Home > Knowledge > Plan Mode vs SDD Plan Mode vs Spec-Driven Development Tactical vs Strategic Context Engineering Category: Context Engineering Approaches Last updated: December 28, 2025 Overview Context engineering exists on a spectrum from tactical to strategic. Plan mode and spec-driven development represent different points on this spectrum, each suited for different scenarios and team needs. Plan mode is a tactical approach where AI agents create implementation plans based on conversational prompts. You describe what you want, the AI proposes a plan, you refine it through dialogue, and implementation proceeds. Context engineering happens through the conversation itself. Spec-driven development is a strategic approach where you create structured, persistent specifications that serve as the source of truth. Context engineering happens through deliberate specification writing, and these specs guide both AI and human developers over the long term. Plan Mode: Tactical Context Engineering Plan mode is built into many AI coding assistants (Claude Code, Cursor, etc.). The workflow: Describe the task: Provide a natural language description of what you want to build AI creates a plan: The AI agent breaks down the task into steps Review and refine: You review the plan and provide clarifications Execute: AI implements the plan, potentially creating files and code Iterate as needed: Adjust based on results Strengths of Plan Mode Low ceremony: Start coding with minimal upfront overhead Fast iteration: Quickly explore different approaches Good for small features: Effective for isolated, well-scoped tasks Learning-friendly: Natural conversation makes it accessible Exploration: Great for prototyping when requirements are unclear Limitations of Plan Mode Ephemeral context: Plans exist only in conversation history, not as persistent artifacts Difficult to review: Hard for others to understand what was intended without reading full conversation No source of truth: When implementation drifts, there's no authoritative reference Doesn't scale: Becomes unwieldy for complex, multi-component features Limited validation: Hard to verify if implementation matches original intent after time passes Spec-Driven Development: Strategic Context Engineering SDD creates persistent, structured specifications as the foundation for development. The workflow: Write specifications: Create structured docs defining requirements and scenarios Review specifications: Validate specs capture your intent (cheapest place to fix issues) Implement: Use specs to guide AI (and human) implementation Validate: Verify implementation matches specification requirements Evolve specs: Keep specifications synchronized as system evolves Strengths of SDD Persistent source of truth: Specs serve as long-term reference for what system should do Reviewable: Specs can be reviewed by team members, stakeholders, even AI agents Validation: Can verify implementation matches specs at any time Scales well: Handles complex, multi-component systems effectively Prevents drift: Explicit specs make deviation obvious Team alignment: Shared understanding documented in specs Limitations of SDD Higher upfront cost: Writing specs takes time before coding begins Learning curve: Requires learning spec frameworks and tools Overhead for simple tasks: Can feel excessive for tiny features Requires discipline: Team must commit to keeping specs synchronized Choosing the Right Approach Use Plan Mode For: Quick experiments and throwaway prototypes Learning and exploration when requirements are genuinely unclear Small, isolated features with minimal complexity Personal projects where long-term maintenance isn't critical One-off scripts or tools Use Spec-Driven Development For: Production systems requiring long-term maintenance Complex features with multiple interactions and edge cases Team environments where shared understanding is essential Projects where validation and compliance matter Systems where context needs to persist beyond conversational memory Brownfield projects where understanding existing behavior is critical Hybrid Approach Many teams use both: plan mode for initial exploration, then transition to SDD for production implementation. This combines the speed of tactical context engineering with the rigor of strategic approaches. The key is matching the level of formality to the stakes and complexity of what you're building. Learn More Which Spec-Driven Development Tool Should You Choose? Comprehensive comparison including tactical vs strategic approaches. Related Topics Context Engineering Understand the foundational practice underlying both approaches. Vibe Coding vs SDD Compare informal vibe coding with structured SDD workflows. Tool Selection Guide Choose the right SDD tools for your approach. -------------------------------------------------------------------------------- # Spec Kit Alternatives | Spec-Driven Development URL: https://intent-driven.dev/knowledge/spec-kit-alternatives/ Home > Knowledge > Spec Kit Alternatives Spec Kit Alternatives Category: Comparisons Last updated: January 26, 2026 Overview If you're evaluating alternatives to GitHub Spec Kit for specification-driven development, OpenSpec is the closest one-to-one match. Both tools are CLI-based and share similar workflow phases (specify, plan, implement), making OpenSpec the most natural transition path. While other SDD tools exist (like Kiro, which is IDE-based), they represent different paradigms rather than direct alternatives. This page focuses on OpenSpec as the closest architectural match for teams currently using or considering Spec Kit. Why OpenSpec Is the Closest Alternative OpenSpec and Spec Kit share fundamental characteristics that make them comparable: CLI-based workflows: Both operate through command-line interfaces, integrating naturally with developer toolchains Similar workflow phases: Both guide development through specification, planning, and implementation stages Repository-based: Both maintain specifications alongside code in version control AI agent compatible: Both are designed to work with AI coding agents Key Differentiators While similar in approach, OpenSpec offers several architectural differences that may better suit certain teams: Unified Specification OpenSpec maintains a single source of truth specification rather than distributing specifications across multiple files. This unified approach makes it easier to understand the complete system state and detect feature interactions. Learn more about the source of truth approach → Potentially Spec-Anchored OpenSpec's architecture potentially enables Spec-Anchored alignment, where specifications can be validated against implementation at any point. This contrasts with Spec-First approaches where specifications guide initial design but may drift over time. How well this works depends on implementation discipline. Understand alignment levels → Brownfield-Friendly OpenSpec provides natural support for brownfield and legacy projects. You can capture existing system states without requiring complete rewrites, making it practical for teams with established codebases. Faster Iteration The streamlined workflow supports quicker iteration cycles, particularly when working with AI coding agents. The lightweight approach enables better flow states without sacrificing specification rigor. Detailed Comparison For a comprehensive side-by-side analysis of both tools, including comparison tables and specific use case recommendations: View Spec Kit vs OpenSpec Comparison Getting Started with OpenSpec Ready to explore OpenSpec? Here are your next steps: OpenSpec Knowledge Page Comprehensive guide to OpenSpec concepts, workflows, and resources. OpenSpec GitHub Repository Official repository with documentation, examples, and CLI tool. Related Topics GitHub Spec Kit Learn about Spec Kit's features and workflow approach. OpenSpec Explore OpenSpec's source of truth specification approach. Spec Kit vs OpenSpec Detailed head-to-head comparison of both tools. Tool Selection Guide How to choose the right spec-driven development tool for your team. -------------------------------------------------------------------------------- # Spec Kit vs OpenSpec | Spec-Driven Development URL: https://intent-driven.dev/knowledge/spec-kit-vs-openspec/ Home > Knowledge > Spec Kit vs OpenSpec Spec Kit vs OpenSpec Category: Comparisons Last updated: January 26, 2026 Overview GitHub Spec Kit and OpenSpec are both CLI-based spec-driven development tools, but they take fundamentally different approaches to specification management. This comparison helps you understand the trade-offs and choose the right tool for your team. Both tools share a common goal: preventing the "vibe coding" problem where implementations drift from original intentions. However, they differ significantly in how they structure specifications and maintain alignment between specs and code. Quick Comparison Aspect GitHub Spec Kit OpenSpec Spec Structure Fragmented across multiple files per feature Unified single source of truth document Alignment Potential Spec-First (guides initial design) Potentially Spec-Anchored (continuous validation) Iteration Speed Comprehensive phases, more structured Lightweight, faster iteration cycles Project Fit Greenfield, complex multi-feature systems Brownfield, legacy modernization, incremental Workflow Phases /specify, /plan, /tasks, implement Propose, Apply, Archive (delta-based) Integration GitHub-native, extension system Repository-agnostic, AI agent focused Specification Structure The most significant difference between these tools is how they organize specifications. GitHub Spec Kit: Feature-Centric Fragmentation Spec Kit maintains separate specification files for each feature. This approach enables detailed cross-feature analysis and systems thinking, allowing you to detect how different features interact. However, understanding the complete system state requires assembling information from multiple sources. OpenSpec: Unified Source of Truth OpenSpec consolidates specifications into a single, living document that represents the current system state. Changes are proposed through delta specs (marking sections as ADDED, MODIFIED, or REMOVED) and merged into the source of truth during archiving. This makes it easier to grasp the complete system holistically. Learn more about unified vs fragmented specification approaches → Alignment Levels How well do specifications stay aligned with implementation over time? Spec-First (GitHub Spec Kit) Spec Kit follows a Spec-First approach where specifications guide initial design and implementation. Specifications are created upfront and inform development, but validation of the complete specification against the live system becomes difficult as the codebase grows. Over time, specifications may drift from actual implementation. Potentially Spec-Anchored (OpenSpec) OpenSpec's architecture potentially enables Spec-Anchored alignment, where the unified specification can be validated against implementation at any point. The emphasis is on "potentially"—how well this works depends on implementation discipline and the tooling used for validation. The unified structure makes validation more feasible than with fragmented specifications. Understand Spec-First vs Spec-Anchored alignment levels → Workflow and Iteration Speed The tools differ in how quickly you can move from specification to implementation. GitHub Spec Kit: Comprehensive Phases Spec Kit guides development through four sequential phases: /specify (create feature specs), /plan (generate design documents), /tasks (decompose into work items), and implement. This comprehensive approach ensures thoroughness but requires moving through each phase systematically. OpenSpec: Lightweight Iteration OpenSpec uses a three-phase cycle: Propose (create delta specs), Apply (implement changes), and Archive (merge into source of truth). The streamlined workflow supports faster iteration cycles and better flow states, particularly when working with AI coding agents. Small, focused changes can move quickly through the cycle. Compare workflow approaches in detail → When to Choose Each Tool Choose GitHub Spec Kit When: You're building greenfield projects where comprehensive upfront specification is valuable Your system has complex multi-feature interactions that benefit from cross-feature analysis You want GitHub-native integration with your existing workflow Your team values systems thinking and detecting emergent behaviors before deployment You prefer structured, phase-driven development with clear progression You want an extension system for custom experimental commands Choose OpenSpec When: You're working with brownfield or legacy projects that need to capture existing state You prioritize fast iteration cycles and quick feedback loops You want continuous validation potential between specs and implementation Your team works heavily with AI coding agents and needs lightweight processes You prefer a unified view of your system's complete specification You practice incremental, disciplined changes through small modifications Resources GitHub Spec Kit Knowledge Page Comprehensive guide to GitHub Spec Kit concepts and workflow. OpenSpec Knowledge Page Comprehensive guide to OpenSpec concepts and workflow. Tool Selection Guide How to choose the right spec-driven development tool for your team. OpenSpec Source of Truth Blog Post Deep dive into OpenSpec's source of truth specification approach. Choosing a Spec-Driven Development Tool Blog Post Framework for evaluating and selecting SDD tools. Related Topics Spec Kit Alternatives Overview of alternatives to GitHub Spec Kit. SDD Workflows Learn about common spec-driven development workflow patterns. Kiro Explore Kiro's all-in-one IDE approach to spec-driven development. -------------------------------------------------------------------------------- # GitHub Spec Kit | Spec-Driven Development URL: https://intent-driven.dev/knowledge/spec-kit/ Home > Knowledge > GitHub Spec Kit GitHub Spec Kit Category: Tools Last updated: November 20, 2025 Overview GitHub Spec Kit is a GitHub-integrated command-line framework for specification-driven development that structures software development around specifications created before implementation. It addresses the gap between original intent and actual code by providing a structured workflow that guides teams from initial requirements through to implementation, particularly valuable when working with AI coding agents. The tool emphasizes specification-first development, ensuring design intentions are captured upfront and maintained throughout the development lifecycle. This prevents the "vibe coding" problem where implementations drift from original intentions, especially critical when autonomous coding agents optimize for speed over alignment. This is a curated summary from comprehensive workflow guides. Read about GitHub Spec Kit and specification-first workflows → Core Workflow GitHub Spec Kit guides development through four sequential phases that ensure specifications drive implementation: 1. Specify (/specify) Creates feature-level specifications capturing requirements and design intent. This phase establishes what needs to be built and why, providing a foundation for all subsequent work. 2. Plan (/plan) Generates detailed design specifications (such as OpenAPI for APIs) that serve as the foundational design document. The planning phase captures the technical approach and architecture decisions. 3. Tasks (/tasks) Decomposes specifications into implementable work items. This phase breaks down the design into concrete, actionable tasks that development teams or AI agents can execute. 4. Implement Executes the identified tasks while maintaining alignment with the original specification. The structured approach ensures implementations stay true to design intentions. Key Features Cross-Feature Analysis with Systems Thinking GitHub Spec Kit includes experimental capabilities for cross-feature analysis using the /cross-feature command. This applies systems thinking principles to detect how different features interact across a system, identifying potential conflicts, circular dependencies, and cascading issues before implementation. While vertical analysis (via /analyze) ensures internal consistency within a single feature, horizontal analysis examines non-linear interactions between features—detecting problems like notification storms or resource conflicts that emerge only when features interact in production. Extension System The spec-kit-extensions repository provides an incubation space for experimental commands. Extensions use the /speckit.extn prefix to distinguish experimental functionality from core features, enabling rapid iteration and community validation before formal integration. This extension architecture allows teams to test new capabilities in real-world workflows without committing to core repository changes, gathering feedback on usability and design before upstream proposals. GitHub Integration Designed specifically for GitHub-based workflows, Spec Kit maintains specifications alongside code in repositories, integrating naturally with existing development practices while adding structure and validation. When to Use GitHub Spec Kit GitHub Spec Kit works particularly well for teams that: Use GitHub for source control and want specification workflows integrated into their existing toolchain Need structured, phase-driven development with clear progression from requirements to implementation Work on complex systems where understanding cross-feature interactions is critical Want to prevent specification drift when using AI coding agents Value systems thinking and want to detect emergent behaviors before deployment Prefer command-line workflows with extensibility for custom capabilities The tool assumes teams are comfortable with command-line interfaces and value explicit, structured phases in their development workflow. Learn More Spec-Driven Development: Specification-First with GitHub Spec Kit Comprehensive guide to specification-first workflows with GitHub Spec Kit. Cross-Feature Analysis with Systems Thinking How GitHub Spec Kit applies systems thinking to detect cross-feature conflicts. GitHub Spec Kit Extensions Framework Understanding the extension system for experimental command development. Exploring Options? If you're evaluating spec-driven development tools, we have resources to help you compare approaches and make the right choice for your team. Spec Kit Alternatives - Overview of alternative tools Spec Kit vs OpenSpec - Detailed head-to-head comparison Related Topics Spec-Driven Development Workflows Learn about common SDD workflow patterns and how to implement them effectively. OpenSpec Compare with OpenSpec's source of truth specification approach. Kiro Explore Kiro's all-in-one IDE approach to spec-driven development. -------------------------------------------------------------------------------- # Tool Selection Guide | Spec-Driven Development URL: https://intent-driven.dev/knowledge/tool-selection/ Home > Knowledge > Tool Selection Tool Selection Guide Category: Workflows & Guides Last updated: December 28, 2025 Overview Choosing the right spec-driven development tool depends on your team's workflow preferences and integration needs. This guide helps you navigate the options. This is a curated summary. Read the comprehensive comparison → Key Selection Criteria 1. Workflow Integration How deeply does the tool integrate with your existing development workflow? Standalone CLI tools: Run independently (OpenSpec) GitHub-integrated: Native GitHub workflow (Spec Kit) All-in-one IDE: Integrated development environment (Kiro) 2. Source of Truth Model How does the tool maintain specification truth? Unified specification: Single source of truth document (OpenSpec) Distributed specifications: Multiple spec files for different features (Spec Kit) Integrated specs: Specs embedded in IDE workspace (Kiro) 3. Team Size & Collaboration Individual developers: Any tool works; focus on personal workflow preferences Small teams (2-5): GitHub-integrated or CLI tools with git workflows Larger teams: Tools with robust collaboration features and code review integration 4. Learning Curve Low: Kiro (all-in-one IDE), Plan mode in existing AI assistants Medium: GitHub Spec Kit (if familiar with GitHub workflows) Higher: OpenSpec (requires understanding source of truth workflow) Tool Comparison OpenSpec Best for: Teams wanting unified source of truth, brownfield projects, continuous validation ✅ Single unified specification document ✅ Delta-based change workflow ✅ Strong brownfield support ✅ Continuous spec-to-code validation ⚠️ Requires learning source of truth workflow GitHub Spec Kit Best for: GitHub-native teams, feature-by-feature specs, systems thinking ✅ Native GitHub integration ✅ Distributed spec model (spec per feature) ✅ Cross-feature analysis ✅ Familiar GitHub workflow ⚠️ Requires GitHub Kiro Best for: Teams wanting all-in-one experience, lower learning curve ✅ Integrated IDE experience ✅ Requirements, design, tasks in one place ✅ Lower learning curve ⚠️ Proprietary platform Decision Framework Start here: Are you on GitHub? → Consider Spec Kit Need unified source of truth? → Consider OpenSpec Want all-in-one simplicity? → Consider Kiro Just exploring SDD? → Try plan mode in your current AI assistant Then ask: Do we need brownfield support? How important is continuous validation? What's our team's comfort with new tooling? Learn More Which Spec-Driven Development Tool Should You Choose? Comprehensive comparison with detailed analysis of tools, criteria, and use cases. Spec-Driven Development: Growing List of Amazing Tools Comprehensive list of SDD tools including emerging options. Related Topics OpenSpec Learn about OpenSpec's source of truth specification approach. GitHub Spec Kit Explore Spec Kit's GitHub-integrated workflow. Kiro Discover Kiro's all-in-one IDE approach. -------------------------------------------------------------------------------- # Vibe Coding vs Spec-Driven Development URL: https://intent-driven.dev/knowledge/vibe-coding-vs-sdd/ Home > Knowledge > Vibe Coding vs SDD Vibe Coding vs Spec-Driven Development Category: Context Engineering Approaches Last updated: December 28, 2025 Overview In AI-assisted development, two distinct approaches have emerged: vibe coding and spec-driven development. Understanding the difference between these approaches is crucial for choosing the right workflow for your team and project. Vibe coding is an informal, conversational approach where developers iteratively guide AI agents through natural language prompts, refining outputs through back-and-forth dialogue until the implementation "feels right." Spec-driven development (SDD) is a structured approach where developers first create explicit specifications defining requirements and expected behavior, then use these specs to guide AI implementation and validate outputs. This is a curated summary from the comprehensive analysis. Read the full comparison → Vibe Coding Workflow The vibe coding workflow follows an iterative, exploratory pattern: Describe what you want: Provide a natural language description of the desired feature AI generates code: The AI agent produces an initial implementation Review and adjust: You test the output and provide feedback Iterate: Back-and-forth refinement continues until the result feels acceptable Move forward: Once satisfied, move on to the next feature This approach works well for quick prototypes, exploration, and when requirements are truly unclear. However, it's prone to intent-to-implementation drift—gradual divergence between what you actually wanted and what got built. Spec-Driven Development Workflow SDD follows a more structured pattern: Write specifications: Create structured specs defining requirements, scenarios, and acceptance criteria Review specs: Validate that specs capture your actual intent (cheaper to fix here than in code) AI generates code: AI implements based on clear, explicit specifications Validate against specs: Verify implementation matches specification requirements Update specs: Keep specifications synchronized as the system evolves This approach frontloads clarity, making intent explicit before implementation begins. While it requires more upfront work, it reduces costly rework and maintains alignment over time. Intent Alignment & Drift Management Vibe Coding: Reactive Drift Management In vibe coding, drift is managed reactively. When you notice the implementation diverging from your intent, you course-correct through additional prompts. This works initially but becomes increasingly difficult as the codebase grows and interactions between features become complex. The challenge: without an explicit reference point, it's hard to know if subtle drift has occurred until it causes problems. SDD: Proactive Drift Prevention SDD prevents drift by maintaining specifications as the source of truth. When implementation diverges from specs, it's immediately visible. You can validate at any time by comparing code behavior against specification requirements. The specification serves as a "contract" that both humans and AI agents can reference, making deviations obvious before they compound into larger problems. When to Use Each Approach Use Vibe Coding For: Quick prototypes and throwaway experiments Exploring solution spaces when requirements are genuinely unclear Small, isolated features with minimal interactions Personal projects where long-term maintenance isn't critical Learning and experimentation Use Spec-Driven Development For: Production systems requiring long-term maintenance Complex features with multiple interactions and edge cases Team environments where shared understanding is essential Projects where validation and compliance matter Systems where drift has high costs (financial, security, user experience) Hybrid Approach Many teams use both: vibe coding for initial exploration and prototyping, then transition to SDD for production implementation. This combines the speed of vibe coding with the rigor of SDD. Learn More Vibe Coding vs Spec-Driven Development: Intent to Implementation Deviation and Context Engineering Comprehensive comparison of workflows, intent alignment, and drift management approaches. Related Topics Context Engineering Understand the foundational practice underlying both approaches. Plan Mode vs Spec-Driven Development Compare tactical plan mode with strategic SDD approaches. Tool Selection Guide Choose the right tools for your approach and team needs. SDD Workflows Learn common SDD workflow patterns and implementation approaches. -------------------------------------------------------------------------------- # Spec-Driven Development Workflows URL: https://intent-driven.dev/knowledge/workflows/ Home > Knowledge > Workflows Spec-Driven Development Workflows Category: Workflows Last updated: January 16, 2026 Overview Spec-Driven Development (SDD) follows a clear workflow pattern: write specification → implement code → validate alignment. This approach ensures that design intentions and actual implementations stay synchronized, preventing drift and enabling fast, confident iteration—especially valuable when working with AI coding agents. The workflow emphasizes maintaining a living specification that evolves with your system, allowing teams to work with clarity and shared understanding of what's being built. This is a curated summary from in-depth workflow guides. Read about SDD workflows and source of truth specifications → The Fundamental SDD Workflow Spec-Driven Development begins with specification first—defining what you're building before writing implementation code. The workflow follows three key phases: 1. Define the Specification Teams first define the system specification before writing any implementation code. This specification serves as the shared understanding between all parties—different teams, stakeholders, and AI coding agents working on the project. 2. Implement Against the Specification Once the specification is established and agreed upon, development can proceed with clarity. Teams build according to the specification, ensuring everyone is working toward the same vision without constant coordination overhead. 3. Validate Through Automated Checks Automated validation ensures implementations match the specification. Tests verify that the system behaves as specified, catching misalignments early when they're cheapest to fix. Evolution Beyond Initial Features As systems grow beyond their first feature, the methodology's true value emerges. The key insight: evolution requires regression prevention, especially when autonomous coding agents optimize for speed. Rather than allowing incremental changes to introduce drift, successful SDD workflows maintain a living specification that captures the system's current state. Each new feature must align with this evolving specification, ensuring the system grows coherently rather than fragmenting into disconnected implementations. Specification as Source of Truth The core principle: maintain the specification as the single source of truth for what the system does. This creates powerful alignment benefits: Shared understanding: Everyone works from the same definition of system behavior Clear intent: Specifications capture the "why" and "what" before implementation details Validation anchor: The specification provides a reference point to verify implementations AI agent alignment: Agents can reference the specification to stay on track with system goals This clarity is critical for velocity—teams make progress confidently because they're aligned on what they're building. Backward Compatibility as Guardrail A crucial innovation in modern SDD workflows: backward compatibility checks happen at design time rather than discovery time. By embedding compatibility validation into the planning phase (before any code generation), teams catch breaking changes when they're cheapest to fix. Automated validation tools can check proposed specification changes, preventing incompatibilities from reaching implementation. This shifts quality checks left in the development cycle, enabling fast iteration without sacrificing stability. Workflow Support in Different Tools Various tools support the SDD workflow with different emphases: OpenSpec: Source of truth specification with delta specs for changes Kiro: Continuous validation between specification and implementation Github Spec Kit: GitHub-integrated workflow for specification evolution Each tool provides mechanisms for the core workflow (define → implement → validate) while offering unique features for different team needs. Learn More Linear MCP + OpenSpec: A Spec-Driven Development Workflow Practical walkthrough of using Linear MCP with OpenSpec to keep the backlog in sync through Propose, Apply, and Archive stages. Spec-Driven Development with OpenSpec: Source of Truth Deep dive into source of truth specifications and workflow patterns. Analyzing Across Features with Systems Thinking Applying systems thinking to detect cross-feature conflicts in SDD workflows. Mind the Context Length in SDD Understanding the relationship between SDD and LLM context length management. Related Topics OpenSpec Learn about OpenSpec's source of truth specification approach to workflows. GitHub Spec Kit Discover GitHub Spec Kit's structured workflow approach. Kiro Explore Kiro's IDE-integrated workflow approach. Best Practices Discover SDD best practices and principles for effective workflows. ================================================================================ # BLOG POSTS ================================================================================ -------------------------------------------------------------------------------- # Linear + OpenSpec Without Forking: A Skill-Based SDD Workflow URL: https://intent-driven.dev/blog/2026/05/29/linear-openspec-skill-based-sdd/ Date: 2026-05-29 In my earlier article, I walked through keeping a Linear backlog in sync with OpenSpec as an agent moved a change through Propose, Apply, and Archive. That workflow worked, but it relied on modifying OpenSpec itself. This revisit achieves the same workflow without touching OpenSpec at all. The Linear sync now lives entirely in a skill — openspec-linearized — that runs on stock OpenSpec. What the Skill Does The skill overlays Linear issue management onto the OpenSpec change lifecycle while keeping a clear ownership boundary: Linear owns the business context — goals, acceptance criteria, and stakeholder-facing status. The repository owns the technical design and implementation. Initial Configuration In order to let the coding agent know about which Linear project, team and label we want to associate this repository with, the skill asks us for the details and stores them in openspec/linear.yaml. Once this file is created when we subsequently ask the coding agent to pick up an issue from Linear, it exactly knows where to look. Mapping Linear issue status with OpenSpec change proposal phases Propose — Binds a Linear Backlog issue as the business brief, and moves it to Todo. proposal.md stays lean, with Linear metadata in its frontmatter. Apply — Moves the story to In Progress while the tasks are implemented. Archive — Completes the OpenSpec archive first, then mirrors the finalized specs into Linear Project Documents (titled OpenSpec: ) and moves the issue to Done. Video Walkthrough References openspec-linearized skill — intent-driven-dev/openspec-schemas Earlier walkthrough — Linear MCP + OpenSpec: A Spec-Driven Development Workflow OpenSpec — Fission-AI/OpenSpec -------------------------------------------------------------------------------- # Spec-Driven Development with OpenSpec and OpenCode URL: https://intent-driven.dev/blog/2026/05/10/spec-driven-development-openspec-opencode/ Date: 2026-05-10 The intent-driven-template wires OpenSpec, OpenCode, and a set of OpenCode skills into an end-to-end Spec-Driven Development workflow. This post walks through each step the template sets up — from openspec init to the custom schema that ties it all together. 1. OpenSpec Setup Start by initializing OpenSpec in the project: openspec init Then pick the new, continue, verify and any other commands that you need in addition to what is included in core profile. Profiles were introduced in OpenSpec 1.2. 2. OpenSpec Git Discipline The template ships an openspec-git-discipline skill that enforces a single rule: every OpenSpec state change must cross main before the next lifecycle phase depends on it. That means the proposal must be on main before apply starts, and implementation must be merged back to main before archive runs. The skill defines explicit gates around propose, continue, apply, and archive so the agent stops and asks rather than silently violating the rule. The reasoning behind these gates — especially when running parallel changes in worktrees — is covered in OpenSpec, Git WorkTrees and OpenCode. 3. Proposal — Grill Me Before You Create proposal.md During the proposal step, the template uses Matt Pocock’s grill-me skill to interrogate the plan one question at a time, walking down each branch of the design tree until there is a shared understanding between the user and the agent. This pulls open questions out into the proposal before specs are written, rather than discovering them later. 4. Design — C4 Diagrams In the design step, the template uses the c4-diagrams skill to clarify architecture before detailed design. The skill produces system context, container, component, dynamic, or deployment diagrams — only the levels that answer a real question — in plain ASCII or Mermaid. The skill also gates on purpose, format, and rigor up front, requires assumptions and open questions to be called out alongside the diagram, and refuses to drift into detailed design until the diagram is approved. This is especially useful in the brownfield context — see Spec-Driven Development with Brownfield Projects for more on that. 5. ADR — Recording the Architectural Decisions The design step almost always surfaces architectural decisions worth keeping. The template uses an architectural-decision-records skill to draft each ADR with explicit context, considered options, decision, and consequences — supporting MADR full, MADR minimal, Nygard, Y-Statement, and custom styles. ADRs are kept outside the change so they persist after the change is archived. The reasoning behind that choice — and why specs alone are not enough — is covered in Architectural Decision Records with Spec-Driven Development. 6. Superpowers for Worktree-Based Parallelism The template uses Obra’s Superpowers in two places: During the explore phase, Superpowers’ brainstorming skill kicks in automatically. During bulk apply, our openspec-bulk-apply-change skill leverages Superpowers’ worktrees and subagents skills to run multiple OpenSpec changes in parallel — each in its own worktree and SubAgent — without them stepping on each other. The mechanics of doing this with OpenSpec — proposing on main, applying inside worktrees, and merging before archive — are covered in OpenSpec, Git WorkTrees and OpenCode. 7. Bringing It Together — The intent-driven Schema OpenSpec uses schemas to control which artifacts are generated during the proposal phase. The template activates the intent-driven schema from intent-driven-dev/openspec-schemas, which produces five artifacts in order: proposal -> specs -> design -> adr -> tasks Schemas are what make all the previous steps fit together as a single workflow rather than a pile of separate tools — the schema is what tells OpenSpec to ask for an ADR after design, and tasks only after that. Custom schemas were introduced in the OpenSpec 1.0 release, where config.yaml first opened up workflow customization. Video Walkthrough References Intent-Driven Template — intent-driven-dev/intent-driven-template Template skills — .agents/skills OpenSpec — Fission-AI/OpenSpec Matt Pocock’s grill-me skill — mattpocock/skills Obra’s Superpowers — obra/superpowers intent-driven schema — intent-driven-dev/openspec-schemas -------------------------------------------------------------------------------- # Architectural Decision Records with Spec-Driven Development using OpenSpec URL: https://intent-driven.dev/blog/2026/04/29/spec-driven-development-with-adr/ Date: 2026-04-29 Architectural decisions deserve a durable log so that future change proposals can leverage prior reasoning during design — not rediscover it. OpenSpec with the default spec-driven schema captures that reasoning in design.md while a change is in flight, but once the change is archived, only specs.md is carried forward into openspec/specs/. The design rationale stays behind in the archive, out of reach of future proposals. The new spec-driven-with-adr schema closes that gap by keeping Architectural Decision Records outside the change, alongside specs, so every architectural decision persists and the current state of the architecture stays visible to future proposals. The Default spec-driven Schema OpenSpec ships with a default schema called spec-driven that produces four artifacts per change: proposal.md, specs.md, design.md, and tasks.md. When a change is archived, only specs.md is preserved — it is synced into openspec/specs/ and lives on. The proposal, design, and tasks are archived with the change under openspec/changes/archive/... and are not considered when the next change is proposed. For more on how schemas plug into this pipeline, see the earlier post on OpenSpec Custom Schemas. Why This Matters for Architectural Decisions The rationale behind an architectural choice usually lives in design.md. Because design.md is archived with the change, that rationale becomes invisible to future proposals. New changes then get designed in the dark — the same trade-offs get re-litigated, fresh designs can quietly contradict prior ones, and the team loses the ability to see why the architecture looks the way it does. How spec-driven-with-adr Differs The spec-driven-with-adr schema adds an ADR artifact that lives outside the change, outside the openspec/ folder. Every change can write one or more ADRs (when there are significant architectural changes or decisions being made), and those records persist after the change is archived. That gives the workflow two things the default schema does not: A durable record of every architectural decision — context, options considered, choice, and consequences — captured at the moment the decision is made. A visible current-state view of the architecture that future change proposals can read and design against. The intent matches the rest of OpenSpec: keep the reasoning close to the code so future contributors — human or agent — can read the why without spelunking through pull requests, Slack, or memory. Specs and ADRs Together Represent Current State The earlier Source of Truth post framed openspec/specs/ as the living spec representing the current state of the system. The spec-driven-with-adr schema extends that same idea to architectural reasoning: Specs represent the current state of the application’s overall functionality — what the system does today. ADRs represent the current state of the application’s architecture — how and why the system is built that way today. Both are durable, and both are read by future change proposals during design. Proposals, designs, and tasks are scaffolding that gets archived once a change ships; specs and ADRs are the load-bearing artifacts that future changes design against. A Small Example Suppose an early change picks Postgres over DynamoDB for the primary store. With the default schema, that decision is reasoned through in design.md — the alternatives considered, the cost and operational trade-offs, the consequences for query patterns — and then archived once the change ships. With spec-driven-with-adr, the same reasoning is captured as an ADR that persists outside the change. A few months later, someone proposes “add full-text search”. During design, the agent (or human) reading sees the storage ADR, knows the system is on Postgres, and naturally evaluates pg_trgm and tsvector before reaching for a separate search service to infer the same from code. Without the ADR, that proposal can easily start by re-debating the storage choice, or worse, silently introduce a second store that contradicts the original decision. Video Walkthrough References Architectural Decision Records — adr.github.io spec-driven-with-adr schema — openspec-schemas Previous post — OpenSpec Custom Schemas -------------------------------------------------------------------------------- # OpenSpec, Git WorkTrees and OpenCode URL: https://intent-driven.dev/blog/2026/04/01/openspec-git-worktrees-opencode/ Date: 2026-04-01 Git WorkTrees let you check out multiple branches simultaneously in separate directories — each with its own working state. Combined with SubAgents in OpenCode, this unlocks genuine parallel feature development inside a Spec-Driven Development workflow. The key is knowing where each step of the OpenSpec workflow belongs: proposal on main, implementation in worktrees, archive after merge. Propose on the Main Branch Always run /opsx:propose (or /opsx:explore + continue) on the main branch, never inside a worktree branch. OpenSpec’s proposal step analyses your active changes alongside the source-of-truth specifications to detect conflicts and gaps. If you propose from a worktree branch, OpenSpec only sees that branch’s delta — it loses visibility into other in-flight changes and the authoritative specs on main. Proposing on main keeps everything in view. Once a proposal is created, you can immediately start on the next proposal for a different feature, still on main. Proposals are lightweight — they don’t touch implementation yet. Apply with SubAgents and WorkTrees With proposals ready on main, hand each one off to a SubAgent with its own WorkTree. Each SubAgent works in an isolated branch, applying its change independently. Because worktrees share the same git object store, you get true parallelism without duplicating the repository. Before a worktree branch is eligible to merge, run Verify inside that same SubAgent session. Verify checks that the implementation matches the proposal’s spec, design, and task artifacts. Running it within the worktree ensures verification before merge so that we can address any issues flagged in the report within that worktree. Merge First, Then Archive Once a worktree branch passes Verify, merge it back to main before running Archive. Archive syncs the change’s delta specs into the source-of-truth specifications on main. If you archive while still on a worktree branch, the spec merge runs against an incomplete view of main — other merged features aren’t visible yet — and conflicts become likely. The rule: merge → archive, in that order, every time. You can Archive each change individually after its merge, or merge all completed worktrees first and then run Bulk-Archive in one pass. Commit Discipline More commits means more recovery points. Aim to commit at every logical boundary: After the change proposal is created, or after each proposal artifact is generated individually (spec, design, tasks) After each logical code change inside the worktree branch After running Archive (the spec sync is a meaningful state change) There is no such thing as too many commits in this workflow. If a SubAgent session goes wrong mid-apply, a dense commit history gives you a clean point to resume from rather than starting over. Video For a reference skill that automates the bulk-apply workflow, see the openspec-bulk-apply-change skill. For worktree-based skills, Superpowers is worth exploring — it provides a skill framework designed to work with git worktrees. -------------------------------------------------------------------------------- # Spec-Driven Development with Brownfield Projects URL: https://intent-driven.dev/blog/2026/03/10/spec-driven-development-brownfield/ Date: 2026-03-10 What is a Brownfield Project? The term “Legacy code” has many definitions, the most relatable IMHO is how Michael Feathers defines it in his book Working Effectively with Legacy Code. Any code that does not have tests is effectively legacy. Similarly “Brownfield”, in the context of SDD, can be defined as projects that were not built based on specs. The only artifact that is available to us is the implementation or the code itself. Can We Reverse-Engineer Specs? In theory, we can reverse-engineer it. A quick way to achieve it is by using tools like repomix to pack the code into smaller sizes and give it to an LLM along with context of the SDD tool we are using. This can help generate the overall spec. In practice, however, AI-generated specs are often inaccurate. The model doesn’t fully capture the original developer’s intent or the subtle nuances embedded in the code. The result is a spec that looks plausible on the surface but diverges from reality. This can’t be trusted as a foundation for future development. The Issues with Reverse-Engineering Reverse Engineering the spec itself can be quite involved. And even if we do, reviewing the specs may not be practical. In the context of Test-Driven Development, when dealing with legacy code which does not have tests, should we start by writing all the tests first? That is not practical. In Feathers’ work in Working Effectively with Legacy Code the approach taken is largely to cover the area of code change with tests to first establish current behavior (characterization tests). Then we can test drive the remaining code. Similarly it is a lot more practical to incrementally author specs for brownfield projects. There is also the problem of alignment loss. A reverse-engineered spec is a derived artifact. When new features are developed against a misaligned spec, the risk of regressions and unintended side effects rises sharply, because the spec no longer reflects the real ground truth of the system. Why Incremental is Better The incremental approach focuses specs on a single, upcoming change rather than attempting to capture the whole codebase at once. Before making a modification, you author a spec for just that area — the change you are about to make. This is far more economical: the scope is bounded, the context is fresh, and the resulting spec accurately reflects intent. Over time, this practice compounds. Each change leaves behind a spec that covers its slice of the system. As spec density grows in frequently touched areas, those sections start to behave like greenfield zones. The coverage builds naturally where it matters most. For a deeper look at how this applies at scale, see my article on Enterprise Spec-Driven Development on InfoQ. Brownfield Spec-Driven Development with OpenSpec Use a Custom Profile and the Explore → Continue Workflow When applying SDD to brownfield projects with OpenSpec, prefer using a custom OpenSpec profile over the default propose command. For more information on custom profiles, please see OpenSpec 1.2 release blog post. The recommended workflow for brownfield is: /opsx:explore — explore the change and understand the codebase before any spec is written Review the exploration output /opsx:continue (or fast-forward through artifacts) — progress through proposal, spec, design, and tasks one at a time In brownfield projects reviewing each artifact individually gives you more control over what gets generated thereby keeping the spec grounded in the real codebase. Pass Codebase Context During Explore with Repomix MCP During the explore phase, pass context about the existing codebase using Repomix MCP. This educates the AI on the brownfield codebase before spec writing begins, so the resulting artifacts reflect the actual system rather than assumptions. Example command: /opsx:explore I would like to remove the maybe option in RSVP, use repomix mcp to understand existing code Repomix packages your codebase into a format the AI can consume directly, giving the explore phase accurate grounding in what already exists. For large codebases, tools like Repomix are especially helpful in managing context window usage. Conclusion Incremental approach gives you control, accuracy, and progressively growing coverage, without requiring a big upfront investment in reverse-engineering specs that may not hold up. You start where the work is, build specs that reflect genuine intent, and let the brownfield gradually transform over time. To see this in action, watch the video below. It walks through a real-world example demonstrating how to use RepoMix to package an existing codebase, feed it to an AI model for analysis, and then author a targeted spec for the next change. Video -------------------------------------------------------------------------------- # OpenSpec 1.2 Release URL: https://intent-driven.dev/blog/2026/02/25/openspec-1-2-release/ Date: 2026-02-25 View the full-size diagram → OpenSpec 1.2 is officially released. The 1.2 release focuses on balancing workflow simplicity which we saw in 0.x releases with advanced customization introduced in release 1.0. OpenSpec Profiles and Schemas The primary addition in 1.2 is profiles, which manage the command workflow. Profiles Core Profile: This is the new default. It uses a simplified process: explore, propose, apply, and archive. The propose command behaves exactly like it did in the 0.x releases, generating all change proposal artifacts at once. Custom Profile: This profile provides access to advanced commands. It lets you step through proposal artifacts, such as “proposal.md”, “spec.md”, “design.md”, and “tasks.md”, using the continue command, or generate them all at once using fast-forward command. Schemas While profiles manage the workflow, schemas (introduced in version 1.0) control which artifacts are generated during the proposal phase. The default OpenSpec schema is “Spec-Driven” which generates “proposal.md”, “spec.md”, “design.md”, and “tasks.md”. If you are interested in creating your own custom schemas, please have a look at my earlier post about “custom schemas”. And you can find my custom openspec-schemas on GitHub. Examples: Minimalist: Reduces output to strictly the spec and task artifacts. Event-Driven: Tailored for event-driven architectures, generating specialized artifacts including event storming, event modeling, and AsyncAPI specifications. Customizability While the 1.0 release introduced customizability, it also made the process quite granular to improve control. Release 1.2 seems to strike a good balance between keeping the basic workflow easy to adopt and retaining the customizability which is really important. This flexibility is essential for adoption at scale, which I have covered in detail in my recent InfoQ article about “Spec-Driven Development – Adoption at Enterprise Scale”. Video Walkthrough -------------------------------------------------------------------------------- # The Intent Harness URL: https://intent-driven.dev/blog/2026/02/23/intent-harness/ Date: 2026-02-23 An agentic harness is the execution layer that channels LLM capability into useful work. It does this by combining the model’s reasoning with tools, workflow control, memory, and guardrails. For sustained autonomous execution, it relies on sufficiently structured context that makes intent, constraints, and success conditions explicit. Without this structure, the agent may act in ways that are not aligned with the intended outcome. This results in constant supervision being necessary. In order to achieve sustained autonomous execution without the risk of losing alignment between intent and implementation, we need to close the gap in shared understanding. The Intent Harness fills this void by helping transform ideas into well-articulated intent that an agent can execute with less supervision. Intent Harness Most useful ideas do not begin as fully formed specifications. They begin as intuition. A team senses a feature that should exist. A product manager sees a pattern in customer behavior. An engineer notices an architectural weakness. A founder feels that a workflow should be simpler. Sometimes that intuition comes from expertise. Sometimes it is supported by data. Either way, it starts out incomplete. That incompleteness is not a flaw. It is actually useful. Intuition is valuable precisely because it leaves room to explore options, test assumptions, and discover better paths before committing to implementation. The problem is not that ideas begin vaguely. The problem is what happens when we send that vagueness straight into an execution system. Without a disciplined process for clarification, the result is shallow prompting, weak task framing, and low-quality execution. The agent may still produce output, but that output remains tightly coupled to constant human supervision. The Intent Harness exists to solve this. Being a layer above the Agentic Harness, its job is to help humans articulate intent clearly before execution begins. It achieves this by enabling dialog between humans and AI to establish shared understanding. Just as the agentic harness helps channel raw LLM capability into useful work, the intent harness helps channel raw intuition and ideas into well-engineered intent. Spec-Driven Development plays a major role here by giving that intent a structured, reviewable form. It helps us harness intent without forcing us to prematurely lock down every detail. That means creating a system that helps us: examine an idea from multiple angles challenge assumptions make constraints explicit define success criteria decide what should and should not be built break work into meaningful units before execution starts Harness Engineering If the questions we ask, the review discipline we apply, and the framework we use to think all shape the resulting intent, then the quality of that system is critical. Engineering the harness determines how well we articulate intent and how much reliable autonomy we can expect from our agents. Weak intent engineering produces weak execution: specs become shallow task boundaries become fuzzy review becomes ceremonial agents need constant correction Strong intent engineering produces better outcomes: clearer specifications better task decomposition earlier surfacing of ambiguities longer, more focused independent agent execution This is why the conversation around AI-assisted delivery should not stop at model capability or coding-agent ergonomics. The real leverage increasingly comes from the quality of the harness that shapes intent before execution starts. Looking at it from this angle, how we interpret bugs, mismatches, and execution failures also changes. Click here to view full image Image from my InfoQ article about Spec-Driven Development Adoption at Enterprise Scale. A defect in implementation is not always just an implementation problem. Sometimes it is a signal that the harness itself needs improvement. For example: a bug in code may point to a gap in the spec a gap in the spec may point to insufficient human review insufficient review may point to a pattern of high-volume, low-quality specs being generated the structure and quality of those specs may ultimately indicate a weak workflow Seen this way, execution failures are not only quality issues in the output. They are also feedback on the quality of the system that produced the output. That is an important shift. It means we should not ask only, “Why did the agent get this wrong?” We should also ask, “What in our elicitation, specification, review, or validation process allowed this ambiguity to survive?” This is where the harness metaphor becomes genuinely useful. The purpose of the harness is not just to make the agent productive. It is to make the overall human–AI system learnable and improvable. Closing thoughts A good Intent Harness should do more than help teams generate artifacts. Its primary responsibility is to enable human and AI collaboration that helps elicit intent thoroughly, encourages meaningful review, and ultimately ensures alignment between intent and implementation. This post is a living document. I intend to continue updating it. -------------------------------------------------------------------------------- # Spec-Driven Development – Adoption at Enterprise Scale URL: https://intent-driven.dev/blog/2026/02/19/enterprise-spec-driven-development/ Date: 2026-02-19 My article on InfoQ, “Spec-Driven Development – Adoption at Enterprise Scale”, was published today. It explores what it takes to move Spec-Driven Development beyond individual workflows and into organisations at scale. Read the full article on InfoQ: Spec-Driven Development – Adoption at Enterprise Scale -------------------------------------------------------------------------------- # OpenSpec Custom Schemas URL: https://intent-driven.dev/blog/2026/02/12/openspec-custom-schemas/ Date: 2026-02-12 In the OpenSpec 1.0 release post, I mentioned how config.yaml lets you tailor the OpenSpec workflow to your team’s needs. Custom schemas take that idea further. Instead of just configuring the workflow, you define the artifacts themselves, shaping what gets generated and in what order. OpenSpec ships with a default schema called spec-driven. It produces four artifacts in sequence: proposal.md, specs.md, design.md, and tasks.md. Each artifact feeds into the next, creating a deliberate path from idea to implementation. This works well for general-purpose projects, but not every project may fit that mold. Custom Schemas I built a few custom schemas to explore what different workflows could look like: openspec-schemas on GitHub. Let us look at what is in this repository. Example 1: The Minimalist Schema Not every project needs four artifacts we discussed above. For well-scoped, low-risk changes, the minimalist schema strips the workflow down to two: specs.md and tasks.md. Specs are authored as user stories with Given/When/Then acceptance criteria. Tasks follow directly from those specs. There is no separate proposal or design step. Details like tech stack and project constraints live in config.yaml, so the schema can stay lean without losing context. This is a good fit when the scope is clear and the team does not need a formal proposal or design review before moving to implementation. Example 2: Event-Driven Architectures For complex systems built around asynchronous messaging, the event-driven schema adds discovery and modeling steps before the usual spec-design-task flow. The workflow starts with event storming, capturing domain events, commands, actors, and bounded contexts. Next, event modeling transforms those into structured flows with Mermaid diagrams that visualize interactions and timelines. From there, the schema moves through specs.md and design.md into AsyncAPI spec generation, producing a validated asyncapi.yaml before any implementation tasks are created. This schema is purpose-built for teams working with message brokers and event-driven patterns, ensuring that the async contract is specified and validated before code is written. Getting started with custom schemas The quickest way to get started is with the OpenSpec CLI. To create a new schema from scratch: openspec schema init my-workflow --description "My custom workflow" --artifacts "specs,design,tasks" This scaffolds a complete schema folder under openspec/schemas/my-workflow/ with a schema.yaml and starter templates for each artifact. To start from an existing schema and customize it: openspec schema fork minimalist This copies the schema into your project as minimalist-custom, ready for you to modify. You can also provide a custom name: openspec schema fork minimalist my-lightweight You can also grab schemas directly from the openspec-schemas repository by copying a schema folder into your project’s openspec/schemas/ directory. Once a schema is in place, set the schema field in your config.yaml to activate it: schema: minimalist context: | Project: My project ... OpenSpec resolves schemas in this order: Project-level — openspec/schemas//schema.yaml in your repo User-level — your global OpenSpec config folder (e.g. ~/.openspec/schemas//schema.yaml) for schemas shared across projects Built-in — schemas bundled with the OpenSpec package (like spec-driven) The first match wins. This means a project-level schema always takes precedence, so you can override a built-in schema without modifying the package. Understanding what is inside a schema If you want to understand how a schema works or build your own, here is what is inside. A schema is a folder containing a schema.yaml file and a templates/ directory with the Markdown templates it references. Using the minimalist schema as an example: openspec/ ├── config.yaml └── schemas/ └── minimalist/ ├── schema.yaml └── templates/ ├── specs/ │ └── spec.md └── tasks.md The templates/ directory contains the Markdown files referenced by the template field in each artifact definition. The schema.yaml defines the artifacts, their output paths, templates, and dependencies: name: minimalist version: 1 description: Lightweight schema for well-scoped, low-risk changes artifacts: - id: specs generates: specs/**/*.md description: Specifications authored as user stories with Given/When/Then acceptance criteria template: specs/spec.md requires: [] - id: tasks generates: tasks.md description: Implementation checklist with trackable tasks template: tasks.md requires: - specs apply: requires: - tasks tracks: tasks.md Each artifact declares what it generates, which template to use, and what it requires before it can be created. The apply block tells OpenSpec which artifact gates implementation and which file tracks progress. Video Walkthrough Custom schemas let OpenSpec fit your process rather than the other way around. Pick one from the schemas repository or use it as a starting point to build your own. -------------------------------------------------------------------------------- # OpenSpec 1.0 Release URL: https://intent-driven.dev/blog/2026/01/26/openspec-1-0-release/ Date: 2026-01-26 View the full-size workflow diagram → OpenSpec 1.0 is officially released. In an earlier post, I wrote about how the OpenSpec workflow anchors development to specs as the source of truth, ensuring that what gets built stays aligned with what was intended. This spec-anchored approach has been central to OpenSpec from the beginning. In this post, let us look at some of the major changes that come with the 1.0 release. Explore Before You Build One of the most significant additions is the Explore Mode. Before diving into implementation, you can now use OpenSpec to think through ideas which require more clarity, investigate problems, and clarify requirements. Step-by-Step Generation OpenSpec 1.0 introduces a more deliberate artifact creation process. Instead of generating everything at once, you can now step through each artifact such as proposal.md, design.md, etc. one at a time. This step-by-step approach helps improve the review process as each artifact can be checked before the next one is generated. Intent Verification Before archiving a completed change, OpenSpec now includes a verification step. This checks that the implementation actually matches what was specified in the change artifacts. It’s a final checkpoint that catches any intent alignment issues. Noteworthy mentions in 1.0 release The config.yaml file in OpenSpec 1.0 looks really interesting. Seamless Integrations OpenSpec’s config system makes it straightforward to integrate with external tools. For example, you can connect OpenSpec with Linear using MCP to automatically sync issues and track progress. I had earlier achieved this by forking and modifying OpenSpec, that may not be necessary anymore. Customizable Workflows Beyond integrations, config.yaml lets you tailor the OpenSpec workflow to your team’s needs. Video Walkthrough -------------------------------------------------------------------------------- # Linear MCP + OpenSpec: A Spec-Driven Development Workflow URL: https://intent-driven.dev/blog/2026/01/11/linear-mcp-openspec-sdd-workflow/ Date: 2026-01-11 Update, May 30, 2026: An updated version of this workflow is now available: Linear + OpenSpec Without Forking: A Skill-Based SDD Workflow. The newer approach keeps the Linear integration in a skill and runs on stock OpenSpec without modifying OpenSpec itself. There are three high-level topics that often come up during my discussions with people trying to adopt Spec-Driven Development (SDD): The Starting Point: Can I pick a story from my existing backlog in Jira, Azure DevOps (ADO), or GitHub Issues? Roles and Handoffs: Do all my team members, including the Product Team, now require Git access just to view the specs? All artifacts in a single monorepo: While colocation of artifacts may have its advantages, should we risk overcrowding the repository with business use cases, technical designs, tasks, and code? While many of us eventually switch to entirely new workflows, adoption is much smoother when we provide onboarding ramps. It helps to see the value of SDD before making fundamental changes to how we work. In this article, I attempt to address these questions through a demo workflow using OpenSpec for SDD and Linear for product planning. Starting Where the Backlog Lives One of the most frequent questions I get regarding Spec-Driven Development (SDD) is: Where is the starting point? Should you pick a story from Jira, Azure DevOps, or Linear? The answer is: Wherever your backlog lives. If that is where your requirements start, that is where your SDD workflow can begin. With most SDD tools largely focused on maintaining all artifacts in a single place, it can take a while to figure out how we integrate them into our workflows. We may also need to sync progress back to the team and keep everyone in the loop without forcing non-developers into a code repository. In this walkthrough, I use Linear and OpenSpec to explore a workflow that lets us use a project management tool or board view alongside an SDD-based workflow. Click here to view the workflow diagram → It is easy enough to feed a ticket to an AI agent. But what happens as the agent makes progress? In a typical siloed workflow, the developer has to manually update the ticket status. In this walkthrough, I demonstrate how OpenSpec (via MCP) can handle the paperwork for you. As the agent moves through the Propose, Apply, and Archive stages, the corresponding Linear issue automatically shifts from Backlog to In Progress and finally to Done. This ensures that the source of truth for project status is updated in real-time, without manual intervention. Roles and Handoffs A common friction point in SDD is the Git barrier. Do Product Owners or stakeholders now need to learn Git to view the latest application specifications? By keeping the product backlog in Linear in sync with the specs in the repo, we can address this point to an extent. Product Owners can stay in the tools they love (like Linear) to define the business use case and monitor progress. Developers/Agents handle the technical detailing of the use cases and implementation within the repository. This workflow uses the backlog as a communication bridge, allowing for human-AI collaboration without forcing every role into the codebase. Separate the What from the How An important point to think about is the separation of concerns. The What: The business use cases and acceptance criteria (stored in Linear or other product backlogs). The How: The technical design and detailed task list (stored in the Git Repo). Maintaining this separation is a necessary first step in addressing another important point, which is about the suitability of SDD for non-monorepo code organization. If we can separate the “What” from the “How”, then whether the “How” is handled in a monorepo or several repos (example: frontend, backend, etc.) can be tackled later. Click here to view the workflow diagram in full size GitHub code: OpenSpec Linear MCP fork What’s Next? To keep this article focused, I have not yet touched on: Multi-repo use cases: How to manage specs that span across code repos. AI-Assisted Backlog Generation: Using AI to help write the stories in the first place. And more: Parallel implementation of stories, sync issues, etc. I will be covering these in future articles. I would love to hear your feedback. How are you integrating SDD into your existing toolset? Are you finding success in syncing your AI progress back to your project management boards? -------------------------------------------------------------------------------- # Which Spec-Driven Development Tool Should You Choose? URL: https://intent-driven.dev/blog/2025/12/26/choosing-spec-driven-development-tool/ Date: 2025-12-26 Click here to view the diagram in full size Before selecting a tool for Spec-Driven Development (SDD) it is good to get a bearing on our workflow and the level of rigor our project demands. This post intends to provide a practical way of thinking through which tool to use. Context Engineering Approaches Before we jump into Spec-Driven Development, itself let us quickly look at how it differs from “Plan Mode”. This is a question I often get asked and thought I will start with that first. There are two ways to look at Context Engineering. Tactical (Plan-Mode) What it is: Best for rapid problem-solving. We create a plan or to-do list to think through the solution, build it, and then discard the plan. The code is the only long-term asset. Now based on our preference for CLI vs IDE based tools, there are several choices. Here are some examples that I have used. Tools: Claude Code (CLI): Plan mode creates temporary implementation plans Antigravity (IDE): Implementation plans that guide development. Even though the plan appears in your IDE window it is not part of your repo. Strategic (Spec-Driven) What it is: Here the specification is a first-class citizen. It is as important as the implementation itself. Maybe even more important in comparison to the code itself (Theoretically, we can generate the code all over again if we have the spec). These specs are persistent and version controlled or stored through other means. Again here, based on our preference for CLI vs IDE based approaches we have several choices. Tools: IDE Kiro CLI OpenSpec SpecKit BMAD-Method Other Considerations 1. Levels of “Spec-Driven” Not all of the above tools handle the relationship between spec and code the same way. Spec-First: Tools: Kiro, SpecKit Philosophy: The purpose of the spec is to articulate intent. Over time, the code and spec might not be aligned. Spec-Anchored: Tool: OpenSpec Philosophy: In addition to articulating intent, the spec remains aligned at all times with the implementation. For a deeper dive into the spec-anchored philosophy, see my LinkedIn post on Spec-Driven Development with OpenSpec: Source of Truth Specification. 2. Rigor vs. Speed How many steps do you actually want to follow? Lightweight (3-4 phases): OpenSpec Comprehensive (Full Agile lifecycle): BMAD-Method More rigor is not always better, it depends on how much groundwork we have already done. If we already have stories in our familiar tools like Linear, GitHub boards, Jira, etc. then maybe better to choose a tool that works with smaller features. If we want to think through a solution from an overall nebulous idea, BMAD may be necessary. 3. Legacy Code and Lock-in Compatibility: Greenfield vs. Legacy Greenfield-friendly: Most tools work well with new projects where you can establish patterns from day one Legacy-specialized: OpenSpec claims to be specifically designed to handle the complexity of existing codebases (brownfield and 0 to 1 projects) Exit Strategy: Portability and Lock-in Since most of us are evaluating these tools, it may be a good idea to see if the approach allows being able to switch from one tool to another without context loss when we switch spec formats. Video Walkthrough For a visual explanation of this decision framework and tool landscape, watch this walkthrough: Conclusion Better not to overthink it, start with the tool that feels most aligned with your workflow, and adjust as you learn what works for your team. Want to dive deeper into spec-driven development practices? Explore our Knowledge Hub for detailed guides on workflows, best practices, and OpenSpec. -------------------------------------------------------------------------------- # Vibe Coding vs Spec-Driven Development: Intent to Implementation Deviation and Context Engineering URL: https://intent-driven.dev/blog/2025/12/15/vibe-coding-vs-spec-driven-development/ Date: 2025-12-15 Introduction One of the most common ways to critique vibe coding is by pointing to technical limitations such as context length, token limits, or LLM “amnesia.” While those are real constraints, the deeper issue IMHO is the workflow. In real life, we rarely expect a human counterpart to take a single-line request or a short PRD and return a perfectly working solution. We expect clarifying questions, intermediate artifacts, reviews, and course correction which can be expensive. Over time, engineering practices such as Behaviour-Driven Development emerged precisely to help teams articulate intent clearly before implementation by promoting better dialogue between stakeholders. When working with AI coding agents, the same principle applies. If we cannot articulate our intent clearly to ourselves first, what eventually gets built will almost certainly deviate from what we originally wanted, regardless of how capable the model is. This article looks at the fundamental workflow differences between vibe coding and spec-driven development, and how those workflows either amplify or reduce intent-to-implementation deviation. The Vibe Coding Lifecycle In a typical vibe coding flow, we describe what we want in a single prompt, review the generated code, provide feedback, and iterate until we are satisfied. It is fast, flexible, and requires very little upfront planning. Vibe Coding Workflow: Iterative prompt-feedback cycles with growing intent deviation. Diagram by Hari Krishnan. How Vibe Coding Works The vibe coding workflow usually follows a linear loop: Single-line prompt describing what needs to be built General-purpose agent that interprets the prompt and fills in gaps Code generation based on those assumptions Review and feedback from the human Iteration using the updated prompt or follow-up instructions This feels natural, especially because chat-based interfaces encourage getting something working quickly and using that output as the basis for further refinement. The workflow optimizes for speed and momentum. Implicit Assumptions Accumulate The core problem emerges as iterations progress. Each prompt and correction focuses on the current concern. To satisfy new feedback, the agent often revises or overrides earlier decisions. Constraints that were previously implied or loosely stated are weakened or forgotten. Initially, intent deviation may reduce as obvious gaps are fixed based on feedback. Over time, however, corrections become fragile. Changes in one area introduce regressions in another. The human ends up in a sustained negotiation loop with the agent, repeatedly restating intent in different ways to keep the output on track. This is not a model failure, it is a workflow limitation where context is not managed effectively. The Spec-Driven Development Workflow Spec-driven development takes a fundamentally different approach. Instead of starting with implementation, it focuses on establishing clear intent before asking the agent to write code. By breaking work into explicit phases with review gates, the spec-driven workflow makes intent articulation deliberate and verifiable, significantly reducing downstream deviation. Spec-Driven Development: Four-phase workflow with review gates maintaining intent alignment. Diagram by Hari Krishnan. The Four Phases of Spec-Driven Development Each tool may have a few more or a few less, however overall these aspects are usually covered. Phase 1: What (Specify / Propose / Requirements) This phase focuses on defining what needs to be built: Feature requirements and acceptance criteria User needs and business goals Scope, boundaries, and non-goals Success metriccs Phase 2: How (Design / Plan) Once intent is clear, the next phase addresses how it will be implemented: Architecture and technical approach Technology and pattern choices Data models, APIs, and interfaces Risks and dependencies Phase 3: Task (Granular Steps with Checks) With design approved, work is decomposed into concrete tasks: Small, verifiable work items Clear validation criteria per task Explicit dependencies and ordering Testing and verification strategy At this point, task ordering and parallelization opportunities can be reviewed. Tasks may also be delegated to sub-agents, reducing context burden in the primary thread while keeping intent anchored. Phase 4: Build (Implementation) Only after intent, design, and tasks are validated does implementation begin: Tasks executed sequentially or in parallel Validation against acceptance criteria Automated tests run Implementation reviewed against specs Output: Working code that matches documented intent. Conversation Matters Spec-Driven Development is sometimes criticized as an anti-pattern because it appears to conflict with “Working software over comprehensive documentation” from the Agile Manifesto. This criticism often stems from viewing specs as artifacts rather than as a mechanism for intent negotiation. To give you an analogy, Behaviour-Driven Development was never about Gherkin syntax for its own sake. It was about enabling collaboration between business and technology through structured conversation. That aligns with “Collaboration over contract negotiation.” Similarly, SDD facilitates structured conversation between humans and coding agents. Specs and plans are not the goal, they are scaffolding that helps clarify and stabilize intent. Tooling quality and verbosity vary, but the underlying purpose remains the same, ensuring that intent is explicit, reviewable, and durable across iterations. Watch: Deeper Dive into Vibe Coding vs Spec-Driven Development For a comprehensive walkthrough of these workflows and their practical implications, watch this video: Conclusion Vibe coding and spec-driven development represent two fundamentally different philosophies for working with AI coding agents. Vibe coding optimizes for speed. It favors rapid iteration, minimal planning, and flexibility. It works well for prototypes, scripts, and exploratory work. Spec-driven development optimizes for intent alignment. It emphasizes clarity, validation, and verifiable outcomes. This makes it better suited for production systems, team environments, and long-lived codebases, and, over time, even for smaller prototypes. The critical differentiator is intent management. Vibe coding accepts deviation as a cost of speed. Spec-driven development reduces deviation by introducing structure, review gates, and explicit intent articulation. If intent matters beyond the next prompt, structure wins. Ready to Learn More? Explore our Knowledge Hub for in-depth guides on: Spec-Driven Development fundamentals OpenSpec framework Workflow best practices Tool ecosystem Related viewing: No Vibes Allowed: Solving Hard Problems in Complex Codebases – Dex Horthy, HumanLayer -------------------------------------------------------------------------------- # Spec-Driven Development with OpenSpec - Source of Truth Specification URL: https://intent-driven.dev/blog/2025/11/09/spec-driven-development-openspec-source-truth/ Date: 2025-11-09 Click here to view the full diagram → In one of my previous articles I mentioned that I have been experimenting with several Spec-Driven Development (SDD) tools, both to evaluate them and to use them in my own work. Among these, OpenSpec has increasingly become one of my preferred SDD tools. It introduces an interesting idea of having a single top level “source of truth” spec. In this article I will look at the workflow, advantages of the “source of truth” spec and other observations about OpenSpec. OpenSpec - Change Workflow Click here to view the full diagram → When I started with GitHub Spec-Kit, a feature workflow diagram by Roslyn Zolandor was immensely helpful. Taking inspiration from the same, I created a workflow diagram for OpenSpec, partly to deepen my own understanding, and partly to articulate the model for others who may be exploring OpenSpec. If you spot any gaps or improvements in the above diagram, I am happy to be corrected. The diagram above focuses on the files generated during a change, in addition to the basic workflow already documented in OpenSpec’s README. Here are a few key aspects. Change Specification (Delta Spec) - These are the spec files generated when we propose a change. They follow the convention of marking sections as “ADDED,” “MODIFIED,” or “REMOVED.” “Source of Truth” Specification - This is the living spec representing the current state of the system. All delta changes eventually merge into this single document (as part of the archive step), which serves as the definitive reference. Archived Specifications - As the name suggests, these preserve the historical record of earlier delta specs once they have been merged into the “Source of Truth” spec. Why the “Source of Truth” Spec Matters? To understand its importance, it helps to reflect on some of the difficulties I faced with tools like Spec-Kit and Kiro in this context. Without a top-level spec, feature-level specs are often fragmented across subfolders within the “specs” directory. This fragmentation introduces below issues: Fragmented Understanding - The overall intent of the system becomes scattered across multiple files, making it difficult to maintain a cohesive picture. Evolving specs - There are several questions and confusions that seem to arise in the context of spec evolution which has been well discussed in related discussions. Unintended Interactions - Every new feature added risks unintentionally affecting existing behaviour, since there is no unified view for validation. In my experience, Spec-Kit works best when we keep our changes small and focused (a good idea in general), which also helps manage context length as detailed in my earlier article. And with these small focused changes, I have come to treat the specs folder as a ledger where entries are added but not updated. This means even if we modify or remove capabilities, we are effectively just appending new specs. If we need an overall spec for the app, we can try to construct an overall spec by sequentially applying all changes. However what we get is only a derivative view, not the primary one. It is difficult to say whether this cumulative spec remains valid or aligned with the real system over time. This leads naturally to the question of what level of validation we can conceptually expect from such a setup. Levels of Alignment - Spec and Implementation I found Birgitta Boeckeler’s article, “Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl” (recommended reading) really helpful in this context. She outlines three categories of alignment between specs and implementation. Spec-First Spec-Anchored Spec-As-Source Even conceptually, when we rely on fragmented specs (as in Spec-Kit or Kiro), we eventually face an alignment problem. As features are deprecated or evolve, related specs become partially invalid. Over time, this makes it impossible to validate all specs against the current system state and expect consistent results. So, this fragment spec approach essentially keeps us in the Spec-First category, where specs are useful for initial exploration and feature definition, but may not remain aligned with the implementation in the long term. In contrast, by maintaining a top-level spec that continuously represents the live system, OpenSpec is capable of being a Spec-Anchored tool, where validation remains possible at any time against the unified, source-of-truth specification. I will leave out discussing “Spec-As-Source” in this article in the interest of keeping it focused. Other observations about OpenSpec Iterating Quickly - I tend to prefer small, incremental changes, and in this setup, the overall proposal cycle in OpenSpec feels noticeably faster. With Spec-Kit, the planning phase often takes longer (not necessarily a bad thing, since it seems to perform deeper analysis) but OpenSpec’s responsiveness helps maintain a steady rhythm of iteration. Flow State - Because I am able to iterate quickly, I context switch less often and I am able to remain in my zone of focus for longer. 1-N / Brownfield Projects - OpenSpec positions itself as more brownfield-friendly, and so far that seems to hold true. Whether through updates to the “project.md” file or by naturally evolving the source-of-truth spec, it is able to capture the current state of an existing system and support refactoring and incremental change. I have not yet tested it against a large, complex codebase to truly compare it with Spec-Kit and Kiro, but so far, OpenSpec’s workflow feels natural and unobtrusive when extending existing projects. Recap OpenSpec stands out as a particularly compelling tool in the growing Spec-Driven Development ecosystem. I would recommend giving it a try. That said, I am an active committer on both GitHub Spec-Kit and OpenSpec and continue to use Kiro regularly. From experience, frustration often arises not from the tools themselves but from mismatched expectations. I would love feedback, questions, or pointers to your own experience with OpenSpec and other SDD tools. Also published on blog.harikrishnan.io and LinkedIn. -------------------------------------------------------------------------------- # Spec-Driven Development - Mind the Context Length URL: https://intent-driven.dev/blog/2025/10/24/spec-driven-development-mind-context-length/ Date: 2025-10-24 Originally published on LinkedIn on October 24, 2025. The article examines the relationship between Spec-Driven Development (SDD) and LLM context length management. While SDD helps break down features and plan implementation with AI coding tools, poorly managed specifications can become counterproductive. Key Challenges Identified Single-Shot-Prompts Problem Large feature requests create massive specifications requiring extensive clarification. Tools like GitHub Spec Kit generate many “[NEEDS CLARIFICATION]” items, and the planning phase can exhaust context windows quickly. Mountain of Markdown Generated markdown files can become impractically long for human review. When specifications grow too extensive, developers risk auto-updating them without meaningful review—a trap I call “vibe specifying.” Lost in the Middle Phenomenon The article references the Stanford research paper on how language models struggle with information buried in long contexts. Oversized specs can suffer from recency and primacy bias even during the specification phase itself. Core Recommendations I propose four key principles: Start small: Begin with line-or-two feature descriptions; avoid extended “and” chains Specs are for humans first: If you cannot reasonably review it, it’s too large Slice meaningfully: Decompose using frameworks like INVEST and MoSCoW prioritization Context matters: Design specifications considering agent limitations Additional Insights Feature decomposition requires structured thinking that tooling alone cannot solve Subagents can help manage context by maintaining isolated environments and enabling parallelization Concepts like EARS (Easy Approach to Requirements Syntax) and user story frameworks remain valuable foundations Conclusion SDD, when properly scaled and reviewed, provides benefits over undisciplined “vibe coding” approaches to AI-assisted development. -------------------------------------------------------------------------------- # Spec-Driven Development: Growing List of Amazing Tools URL: https://intent-driven.dev/blog/2025/10/22/spec-driven-development-tools/ Date: 2025-10-22 Originally published on Hari Krishnan’s blog on October 22, 2025. Note: Logos are property of their respective owners Spec-driven development has been gaining momentum steadily and the growing number of tools also seems to indicate a clear demand. Here are a few tools that I am using/trialing for folks who are interested in SDD. Using / Trialing Kiro (https://kiro.dev/) - I first came across Specification-Driven Development (SDD) when I was exploring Kiro. An all-in-one AI IDE (VS Code fork) that takes you through a quick Requirements, Design and Task list phases. GitHub Spec Kit (https://github.com/github/spec-kit) - Has been my go-to for SDD for a while now. I personally prefer CLI tools and thereby this naturally fit my workflow better. You can find out more about these in my posts about speckit. OpenSpec (https://github.com/Fission-AI/OpenSpec) - I was looking for something lightweight. That is when I spotted OpenSpec and I am really beginning to like it. Overall it is definitely quicker among all the tools I have tried. I am currently evaluating its 1-N / Brownfield-first capabilities. ai-dev-tasks (https://github.com/snarktank/ai-dev-tasks) - “3-File System” - If you want to go even more lightweight, this is certainly something to look into. The repo only contains markdown files which you tag during each phase. In my TODO list AgentOS (https://buildermethods.com/agent-os) Tessl (https://tessl.io/) Final Thoughts IMHO, all of them have their strengths and can serve as a good starting point. I have been moving across tools to understand the philosophy, how opinionated they are, and their customisability. Would love to hear what others are using and how the experience has been. -------------------------------------------------------------------------------- # GitHub Spec Kit Extensions: Incubate, Test, and Distribute Commands URL: https://intent-driven.dev/blog/2025/10/15/spec-kit-extensions-incubate-test-distribute/ Date: 2025-10-15 Originally published on LinkedIn on October 15, 2025. This article introduces an experimental repository for extending GitHub Spec Kit with community-contributed commands. I previously published work on a “/cross-feature” command applying systems thinking across features and needed infrastructure for iterating on experimental functionality. Key Motivation Points I identified three main reasons for creating this extension space: Context-specific commands - Some commands may be better suited as opt-in rather than core features Rapid iteration - Provides “a low-friction way to trial commands before they’re upstreamed” Development efficiency - Avoids manual file copying during experimentation phases Technical Conventions To differentiate extension commands from standard GitHub Spec Kit offerings, I use a “/speckit.extn” prefix structure. The cross-feature command example follows this as “/speckit.extn.cross-feature”. Setup Instructions The process involves two steps: Initialize Spec Kit using the provided uvx command Install extensions via the provided installation script Resources Experimental Repository: https://github.com/polarizertech/spec-kit-extensions Related Discussion: GitHub issue #729 and discussion #898 I welcome feedback on naming conventions, command flags, and installation experience. -------------------------------------------------------------------------------- # Spec Driven Development: Analyzing Across Features with Systems Thinking URL: https://intent-driven.dev/blog/2025/10/03/spec-driven-development-systems-thinking/ Date: 2025-10-03 Originally published on LinkedIn on October 3, 2025. The main advantage of Specification Driven Development is that it helps break down a feature into a structured plan with actionable tasks. This way of working makes hidden details visible and makes instructing coding agents easier. Tools like GitHub Spec Kit guide this process through “/specify”, “/plan”, and “/tasks”, ensuring clarity before implementation. Recently GitHub Spec Kit also introduced a few nice optional commands like “/analyze” which ensures cross-artifact consistency (alignment between spec, plan and tasks) within the feature. Need for Non-Linear Analysis But features rarely exist in isolation. When they interact, linear thinking alone is not enough. Contradictions, feedback loops, or emergent behaviours often appear across features. That is when we need non-linear thinking, and this is where Systems Thinking helps. Until now, I was running ad-hoc prompts to verify multiple “spec.md” files against each other. Useful, but outside the natural Spec Kit workflow. So I started experimenting with a new command. “/cross-feature” - An optional GitHub Spec Kit command that can be run after specifying a new feature (with “/specify”). Here is a visual representation of how “/cross-feature” compares with “/analyze”. Or as a metaphor, /analyze is vertical alignment; /cross-feature is horizontal alignment. Real world example Having worked in conversion optimisation, I have often seen cart abandonment journeys cause complexity. Let us walk through a simple progression of features. Feature 1 - Add to Cart /specify add to cart - users can select several items and click on add to cart - as part of adding to cart the inventory for the items is reduced accordingly This would be followed by the usual “/plan”, “/tasks”, and “/implement”, and then merged back to main. Feature 2 - Abandoned Cart /specify abandoned cart journey - any cart that has exceeded 15 min of inactivity is considered abandoned - inventory that was blocked / reduced for the cart has to be restored once the cart is considered abandoned - a notification has to be sent to the inventory manager over mail for restored inventory Again, this goes through planning, tasking, implementation, and merging to main. Feature 3 - Low Stock Alert /specify low stock alert - A mail notification has to go to the inventory manager when stock goes below 5 units for an item - The mail has to go out within 5 min of the lower threshold being hit for the inventory This time, let us imagine I am a new product owner introducing this feature. The key question is, will this impact existing features like Add to Cart and Abandoned Cart? Time to check “/cross-feature” Just as we ask coding agents to review and test our code, we can also ask them to wear the product hat and review feature specs. When I ran “/cross-feature”, it generated a “cross-feature-analysis.md” with the following observation. Potential Side Effects Notification storm: During high-traffic periods, multiple concurrent add-to-cart operations could cause cascading low stock alerts if many items drop below threshold simultaneously This surfaced a cross-feature oscillation that is not obvious when reviewing features in isolation. Let us “/clarify” In addition to creating “cross-feature-analysis.md”, the “/cross-feature” command adds a reference to this file inside the feature’s “spec.md”: [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - should monitoring track total inventory, available inventory (excluding cart reservations), or sold inventory?] This ensures that when we run the optional “/clarify” command, Spec Kit will now ask targeted questions to resolve the issues flagged by “/cross-feature”. Example status table Category Status Notes Integration & External Dependencies ⚠️ Outstanding Cross-feature conflicts with cart system (see cross-feature-analysis.md) Example Clarification > /clarify is running… ⏺ Read(specs/003-low-stock-alert/spec.md) ⎿ Read 125 lines (ctrl+o to expand) ⏺ Read(specs/003-low-stock-alert/cross-feature-analysis.md) ⎿ Read 89 lines (ctrl+o to expand) ⏺ I've analyzed the specification and cross-feature alignment. There are critical cross-feature conflicts that need resolution. I'll ask up to 5 targeted questions focusing on the high-impact alignment issues. Question 1 of 5 Should low stock alerts monitor total inventory or only available (non-cart-reserved) inventory? Context: Cart additions (feature 001) reduce inventory temporarily, which could trigger false alerts if carts abandon and restore stock within 15 minutes. Option Description A Total inventory (triggers alerts even for cart-reserved stock) B Available inventory only (ignores cart reservations, alerts only on true stockouts) This helps prevent issues like the notification storm, which might otherwise be missed. Recap “/analyze” keeps a feature consistent with itself. “/cross-feature” (experimental) checks how a feature plays with others, using non-linear approaches such as Systems Thinking. This is still experimental, but it has already helped me surface issues like feedback loops, oscillations, and contradictions early, before implementation. I have used Systems Thinking as a starting point, but analysing across features may require additional points of view and mechanisms as this evolves. Curious to hear, how do you approach cross-feature alignment in your teams with GitHub Spec Kit? Would a command like “/cross-feature” fit into your workflow? UPDATE: I have put together a new repo called spec-kit-extensions to test experimental commands. This will let you try “/cross-feature” while the above Pull Request is awaiting review.