diff --git a/examples/spec-driven/README.md b/examples/spec-driven/README.md
new file mode 100644
index 0000000..e797714
--- /dev/null
+++ b/examples/spec-driven/README.md
@@ -0,0 +1,191 @@
+# Spec-Driven Development with mdflow
+
+A lightweight, spec-driven development workflow using markdown agents. Inspired by GitHub's Spec Kit, optimized for mdflow.
+
+## The Pattern
+
+Five interconnected markdown agents that guide you from vision to implementation:
+
+```
+constitution.claude.md
+        ↓
+    specify.claude.md
+        ↓
+      plan.claude.md
+        ↓
+      tasks.claude.md
+        ↓
+   implement.claude.md
+```
+
+## Quick Start
+
+### 1. Establish Principles
+```bash
+md constitution.claude.md --_project "MyFeature" --_team "TeamName"
+```
+Defines project values, engineering standards, and team agreements.
+
+### 2. Define Requirements
+```bash
+md specify.claude.md --_project "MyFeature"
+```
+Interactive session to clarify what you're building (what & why).
+
+### 3. Plan Architecture
+```bash
+md plan.claude.md --_project "MyFeature" --_tech_stack "Node.js + React"
+```
+Creates technical approach with design decisions and risk assessment.
+
+### 4. Break Into Tasks
+```bash
+md tasks.claude.md --_project "MyFeature"
+```
+Converts plan into sequenced, actionable tasks with owners and estimates.
+
+### 5. Execute Work
+```bash
+md implement.claude.md --_project "MyFeature" --_task "1.1"
+```
+Interactive guidance for implementing individual tasks with validation.
+
+## mdflow Features Used
+
+Each agent demonstrates mdflow capabilities:
+
+### Variables (`--_varname`)
+```yaml
+_project: "{{ _project | default: 'MyProject' }}"
+_team: "{{ _team | default: 'Engineering Team' }}"
+```
+Pass dynamic values: `md constitution.claude.md --_project "Auth Feature"`
+
+### File Imports (`@./path`)
+```markdown
+@./package.json
+@./src/**/*.ts
+@./tsconfig.json:1-20
+```
+Reference actual project files directly in the agent.
+
+### Inline Commands (`` !`cmd` ``)
+```markdown
+!git status
+!npm test
+!npm list --depth=0
+```
+Execute commands and inject output into the agent prompt.
+
+### File References
+```markdown
+**Reference**: @./specify.claude.md
+**Plan**: @./plan.claude.md
+```
+Cross-reference other phase documents.
+
+### Interactive Mode (`_interactive: true`)
+```yaml
+_interactive: true
+```
+Agents use `.i.` variant (or frontmatter flag) for live conversation.
+
+## Agent Composition
+
+Agents can pipe together for analysis:
+
+```bash
+# Security analysis flows into planning
+md security-scan.claude.md | md plan.claude.md
+```
+
+## Real-World Example
+
+For an authentication feature:
+
+```bash
+# 1. What's our principle on auth security?
+md constitution.claude.md --_project "Auth" --_team "Security"
+
+# 2. What do we need to build?
+md specify.claude.md --_project "Auth"
+
+# 3. What's our tech approach?
+md plan.claude.md --_project "Auth" --_tech_stack "OAuth2 + JWT"
+
+# 4. What are the concrete tasks?
+md tasks.claude.md --_project "Auth"
+
+# 5. Help me implement task 1.1
+md implement.claude.md --_project "Auth" --_task "1.1"
+```
+
+## Why mdflow + Spec-Driven?
+
+### Lightweight
+- No extra frameworks or CLI tools
+- Just markdown files + mdflow
+- Works with any AI assistant (claude, gemini, codex, etc.)
+
+### Composable
+- Agents reference each other via `@./` imports
+- Share data through stdout/stdin piping
+- Build workflows from simple, focused agents
+
+### Version-controllable
+- Keep specs in git alongside code
+- Review changes like code
+- Track evolution of requirements
+
+### AI-native
+- YAML frontmatter configures agent behavior
+- Markdown is easy to parse and modify
+- Template variables parameterize reuse
+
+## Customization
+
+Copy these files as templates for your project. Customize:
+
+1. **Add project-specific variables**:
+   ```yaml
+   _database: "{{ _database | default: 'PostgreSQL' }}"
+   _framework: "{{ _framework | default: 'Express' }}"
+   ```
+
+2. **Import your conventions**:
+   ```markdown
+   @./ENGINEERING_STANDARDS.md
+   @./ARCHITECTURE.md
+   @./TESTING_GUIDELINES.md
+   ```
+
+3. **Run project checks**:
+   ```markdown
+   !./scripts/validate-env.sh
+   !npm run lint
+   !npm audit
+   ```
+
+## Key Differences from Spec Kit
+
+| Aspect | Spec Kit | mdflow Pattern |
+|--------|----------|----------------|
+| Framework | Full CLI framework | Simple markdown files |
+| Dependencies | Python + Specify CLI | mdflow only |
+| Agent selection | Slash commands | Filename inference |
+| File imports | Limited | Full glob + symbol extraction |
+| Piping | Not primary | Built-in (stdout/stdin) |
+| Execution | Specialized workflows | Open-ended, composable |
+
+## Tips
+
+- **Start simple**: Use templates as-is, customize gradually
+- **Keep specs updated**: Treat them as living documents
+- **Reference actual code**: Use imports to ground specs in reality
+- **Iterate visually**: Use `.i.` variants for interactive refinement
+- **Compose agents**: Chain multiple agents for complex workflows
+- **Reuse templates**: Save project-specific versions to `~/.mdflow/`
+
+## Examples
+
+See `/examples/spec-driven/` for complete template files with all mdflow features demonstrated.
diff --git a/examples/spec-driven/clarify.claude.md b/examples/spec-driven/clarify.claude.md
new file mode 100644
index 0000000..7bbff23
--- /dev/null
+++ b/examples/spec-driven/clarify.claude.md
@@ -0,0 +1,60 @@
+---
+model: opus
+_project: "{{ _project | default: 'MyProject' }}"
+_interactive: true
+---
+
+# Clarification Workshop: {{ _project }}
+
+Interactive session to clarify underspecified areas before planning.
+
+**Specification**: @./specify.claude.md
+
+## Analysis
+
+Review current specification:
+@./specify.claude.md
+
+## Clarifying Questions
+
+Based on the specification above, ask clarifying questions about:
+
+1. **User Impact**
+   - Who is the primary user?
+   - What problem does this solve for them?
+   - What's the expected outcome?
+
+2. **Scope & Constraints**
+   - What's explicitly in scope?
+   - What's explicitly out of scope?
+   - Are there technical constraints?
+
+3. **Success Criteria**
+   - How will we measure success?
+   - What are the non-negotiables?
+   - What's nice-to-have?
+
+4. **Dependencies & Integration**
+   - What systems does this interact with?
+   - Are there integration points?
+   - Any external APIs or services?
+
+5. **Timeline & Resources**
+   - How quickly do we need this?
+   - Who's available to work on it?
+   - Are there blocking dependencies?
+
+## Output
+
+Generate a clarification summary that:
+- Resolves ambiguities from the specification
+- Documents key assumptions
+- Highlights areas needing more definition
+- Ready to pass to `md plan.claude.md`
+
+---
+
+**Next**: After clarifications are resolved, run:
+```bash
+md plan.claude.md --_project "{{ _project }}"
+```
diff --git a/examples/spec-driven/constitution.claude.md b/examples/spec-driven/constitution.claude.md
new file mode 100644
index 0000000..0f773e8
--- /dev/null
+++ b/examples/spec-driven/constitution.claude.md
@@ -0,0 +1,53 @@
+---
+model: opus
+_project: "{{ _project | default: 'MyProject' }}"
+_team: "{{ _team | default: 'Engineering Team' }}"
+---
+
+# Constitution: {{ _project }} Development Principles
+
+Define the core principles and values that will guide all development decisions for this project.
+
+**Project**: {{ _project }}  
+**Team**: {{ _team }}  
+**Date**: `!date +%Y-%m-%d`
+
+## Current Repository Status
+@./.gitignore
+@./package.json
+@./tsconfig.json:1-20
+
+## Engineering Principles
+- Write clean, maintainable code with clear abstractions
+- Prioritize readability over cleverness
+- Test-driven development for critical paths
+- Type safety through TypeScript
+
+## Code Quality Standards
+- Consistent naming conventions and code style
+- Comprehensive error handling and validation
+- Clear documentation for complex logic
+- Performance-conscious implementations
+
+## Development Workflow
+- Markdown-first specification approach
+- Clear separation of concerns
+- Incremental development with regular validation
+- Peer review and feedback integration
+
+## Team Agreements
+```
+Lint: `!npm run lint`
+Test: `!npm test`
+Build: `!npm run build`
+```
+
+## User Experience
+- Intuitive command-line interfaces
+- Clear error messages with actionable guidance
+- Fast feedback loops for interactive tools
+- Comprehensive help documentation
+
+---
+
+**Next Step**: Run `md specify.claude.md --_project "{{ _project }}"` to define requirements.
diff --git a/examples/spec-driven/implement.claude.md b/examples/spec-driven/implement.claude.md
new file mode 100644
index 0000000..3a38ce8
--- /dev/null
+++ b/examples/spec-driven/implement.claude.md
@@ -0,0 +1,96 @@
+---
+model: opus
+_project: "{{ _project | default: 'MyProject' }}"
+_task: "{{ _task | default: '1.1' }}"
+_interactive: true
+---
+
+# Implementation: {{ _project }} - Task {{ _task }}
+
+Guide for executing individual tasks or all tasks in sequence.
+
+**Task Reference**: @./tasks.claude.md  
+**All Specs**: @./plan.claude.md  
+**Mode**: Interactive - ask questions as you work
+
+## Pre-Work Checklist
+```
+!git status
+!npm test 2>&1 | head -20
+!git branch
+```
+
+## Current Task: {{ _task }}
+
+### Context
+Review the task definition from tasks.claude.md:
+@./tasks.claude.md
+
+### Implementation Steps
+
+1. **Understand the requirements**
+   - What needs to be built?
+   - What are the acceptance criteria?
+   - What files will be affected?
+
+2. **Write tests first** (TDD)
+   ```bash
+   npm test -- --watch
+   ```
+
+3. **Implement incrementally**
+   - Small, reviewable commits
+   - Test frequently
+   - Run linter: `!npm run lint`
+
+4. **Validate implementation**
+   ```bash
+   !npm test
+   !npm run lint
+   !npm run build
+   ```
+
+5. **Document changes**
+   - Update README if needed
+   - Add inline comments
+   - Update CHANGELOG.md
+
+## Parallel Tasks (if running multiple agents)
+
+Run task analysis in parallel:
+```
+md implement.claude.md --_project "{{ _project }}" --_task "1.1" | tee task-1.1-notes.md
+md implement.claude.md --_project "{{ _project }}" --_task "1.2" | tee task-1.2-notes.md
+```
+
+## Integration After Task Completion
+
+Once task is done:
+```bash
+git add -A
+git commit -m "feat: implement task {{ _task }}"
+!npm test
+```
+
+## When Stuck
+
+Ask for help or clarification:
+```bash
+md help.claude.md --_question "How do I handle [specific issue]?"
+```
+
+---
+
+**Quick Commands**:
+```bash
+# Run just this task
+md implement.claude.md --_project "{{ _project }}" --_task "{{ _task }}"
+
+# Watch tests
+!npm test -- --watch
+
+# Run full suite
+!npm test && npm run lint && npm run build
+```
+
+**Next Task**: Update tasks.claude.md when this task is complete.
diff --git a/examples/spec-driven/plan.claude.md b/examples/spec-driven/plan.claude.md
new file mode 100644
index 0000000..da80f42
--- /dev/null
+++ b/examples/spec-driven/plan.claude.md
@@ -0,0 +1,78 @@
+---
+model: opus
+_project: "{{ _project | default: 'MyProject' }}"
+_tech_stack: "{{ _tech_stack | default: 'TypeScript + Bun' }}"
+---
+
+# Implementation Plan: {{ _project }}
+
+Technical architecture and implementation approach based on requirements.
+
+**Technology Stack**: {{ _tech_stack }}  
+**Reference Spec**: @./specify.claude.md
+
+## Current Project Analysis
+```
+Dependencies:
+!npm list --depth=0
+
+Build config:
+!cat package.json | grep -A 5 '"scripts"'
+
+Existing architecture:
+!find src -type f -name "*.ts" | head -20
+```
+
+## Architecture Overview
+
+### Core Components
+1. **[Component A]**: Purpose and responsibilities
+2. **[Component B]**: Purpose and responsibilities
+3. **[Component C]**: Purpose and responsibilities
+
+### Data Flow Diagram
+```
+Input
+  ↓
+[Process]
+  ↓
+Output
+```
+
+### Technology Decisions
+| Decision | Choice | Reasoning |
+|----------|--------|-----------|
+| Runtime | {{ _tech_stack }} | [Why?] |
+| Language | TypeScript | Type safety |
+| Framework | [X] | [Why?] |
+
+## Implementation Approach
+
+### Phase 1: Foundation
+- Set up project structure
+- Configure tooling
+- Establish patterns
+
+### Phase 2: Core Features
+- Feature A
+- Feature B
+- Feature C
+
+### Phase 3: Integration
+- Connect components
+- End-to-end testing
+- Documentation
+
+## Risk Assessment
+| Risk | Mitigation |
+|------|-----------|
+| [Risk] | [Plan] |
+
+---
+
+**Usage**: Import this plan into `tasks.claude.md`:
+```
+@./plan.claude.md
+```
+
+**Next**: `md tasks.claude.md --_project "{{ _project }}"`
diff --git a/examples/spec-driven/review.claude.md b/examples/spec-driven/review.claude.md
new file mode 100644
index 0000000..f9a8636
--- /dev/null
+++ b/examples/spec-driven/review.claude.md
@@ -0,0 +1,93 @@
+---
+model: opus
+_project: "{{ _project | default: 'MyProject' }}"
+---
+
+# Spec Review: {{ _project }} Consistency & Coverage
+
+Cross-artifact analysis to ensure specs are complete and consistent.
+
+**Constitution**: @./constitution.claude.md  
+**Specification**: @./specify.claude.md  
+**Plan**: @./plan.claude.md  
+**Tasks**: @./tasks.claude.md
+
+## Quality Gates
+
+Analyze all artifacts for:
+
+### Consistency
+- [ ] Specification aligns with constitution principles
+- [ ] Plan aligns with specification requirements
+- [ ] Tasks implement all plan components
+- [ ] No contradictions between documents
+- [ ] Terminology is consistent
+
+### Coverage
+- [ ] All spec requirements mapped to plan sections
+- [ ] All plan sections mapped to tasks
+- [ ] Success criteria from spec are measurable
+- [ ] Risk assessment covers identified challenges
+- [ ] All assumptions are documented
+
+### Completeness
+- [ ] User stories have acceptance criteria
+- [ ] Tasks have clear owners and estimates
+- [ ] Dependencies between tasks are identified
+- [ ] Integration points are documented
+- [ ] Edge cases are addressed
+
+### Clarity
+- [ ] Requirements are unambiguous
+- [ ] Technical approach is justified
+- [ ] Task breakdowns are actionable
+- [ ] Success metrics are specific
+
+## Issues Found
+
+Identify and prioritize:
+
+1. **Critical Issues** (blocks implementation)
+   - Issue: [description]
+   - Location: [spec file and section]
+   - Resolution: [recommendation]
+
+2. **Major Issues** (should fix before starting)
+   - Issue: [description]
+   - Location: [spec file and section]
+   - Resolution: [recommendation]
+
+3. **Minor Issues** (nice to address)
+   - Issue: [description]
+   - Location: [spec file and section]
+   - Resolution: [recommendation]
+
+## Recommendations
+
+Suggest improvements:
+
+- [ ] Clarify [specific requirement]
+- [ ] Add [missing detail]
+- [ ] Simplify [complex section]
+- [ ] Document [assumption]
+- [ ] Define [edge case]
+
+## Sign-Off Checklist
+
+Before proceeding to implementation:
+
+- [ ] All critical issues resolved
+- [ ] Specifications reviewed by team
+- [ ] Plan approved by technical lead
+- [ ] Tasks assigned to owners
+- [ ] No blockers identified
+- [ ] Ready to execute
+
+---
+
+**Current Status**: Review in progress
+
+Once all checks pass, proceed with:
+```bash
+md implement.claude.md --_project "{{ _project }}" --_task "1.1"
+```
diff --git a/examples/spec-driven/specify.claude.md b/examples/spec-driven/specify.claude.md
new file mode 100644
index 0000000..5f72495
--- /dev/null
+++ b/examples/spec-driven/specify.claude.md
@@ -0,0 +1,70 @@
+---
+model: opus
+_project: "{{ _project | default: 'MyProject' }}"
+_interactive: true
+---
+
+# Specification: {{ _project }} Requirements
+
+Define what you want to build, focusing on the **what** and **why**, not the technical details.
+
+**Status**: Interactive workshop  
+**Reference**: @./constitution.claude.md
+
+## Feature Overview
+
+Describe the problem your feature solves:
+
+```
+What problem are we solving?
+Who has this problem?
+Why is it valuable?
+```
+
+## User Stories
+
+### Story 1: Core User Journey
+**As a [user type], I want to [action] so that [outcome]**
+
+- Acceptance criteria 1
+- Acceptance criteria 2
+- Acceptance criteria 3
+
+### Story 2: Advanced Usage
+**As a [power user], I want to [action] so that [outcome]**
+
+- Acceptance criteria 1
+- Acceptance criteria 2
+
+### Story 3: Integration Points
+**As a [developer], I want to [action] so that [outcome]**
+
+- Acceptance criteria 1
+- Acceptance criteria 2
+
+## Clarification Questions (if needed)
+
+Run this for deeper analysis:
+```
+md clarify.claude.md --_project "{{ _project }}"
+```
+
+## Success Metrics
+- [ ] User can accomplish [key outcome]
+- [ ] Performance meets [criteria]
+- [ ] Edge case [X] handled gracefully
+- [ ] Documentation complete
+
+## Out of Scope
+- Feature X (why?)
+- Feature Y (why?)
+- Future: Feature Z
+
+---
+
+**Next Step**: Once requirements are clear, run:
+```bash
+md plan.claude.md --_project "{{ _project }}"
+```
+
+This specification will be imported by downstream agents.
diff --git a/examples/spec-driven/tasks.claude.md b/examples/spec-driven/tasks.claude.md
new file mode 100644
index 0000000..9f57c10
--- /dev/null
+++ b/examples/spec-driven/tasks.claude.md
@@ -0,0 +1,80 @@
+---
+model: opus
+_project: "{{ _project | default: 'MyProject' }}"
+---
+
+# Task Breakdown: {{ _project }} Implementation
+
+Actionable, sequenced implementation tasks derived from the plan.
+
+**Plan Reference**: @./plan.claude.md  
+**Specification**: @./specify.claude.md
+
+## Analyze Current State
+```
+!find . -name "*.ts" -type f | wc -l
+!npm test 2>&1 | tail -20
+!git log --oneline -5
+```
+
+## Phase 1: Foundation
+- [ ] **Task 1.1**: [Specific action]
+  - [ ] Subtask A
+  - [ ] Subtask B
+  - Estimated: N hours
+  - Owner: [Team member]
+
+- [ ] **Task 1.2**: [Specific action]
+  - [ ] Subtask A
+  - [ ] Subtask B
+  - Estimated: N hours
+  - Owner: [Team member]
+
+- [ ] **Task 1.3**: [Specific action]
+  - [ ] Subtask A
+  - [ ] Subtask B
+  - Estimated: N hours
+  - Owner: [Team member]
+
+## Phase 2: Core Implementation
+- [ ] **Task 2.1**: [Specific action]
+  - Blocking: Task 1.1, 1.2
+  - Related tests: @./src/[component].test.ts
+
+- [ ] **Task 2.2**: [Specific action]
+  - Blocking: Task 2.1
+  - Related files: @./src/[module]/**/*.ts
+
+- [ ] **Task 2.3**: [Specific action]
+  - Blocking: Task 2.1
+
+## Phase 3: Integration & Testing
+- [ ] **Task 3.1**: Integration testing
+  - Run: `!npm test`
+  - Coverage threshold: 80%
+
+- [ ] **Task 3.2**: Documentation
+  - Update README
+  - Add examples
+  - Document API
+
+- [ ] **Task 3.3**: Review & Deploy
+  - Code review checklist
+  - Performance testing
+  - Deployment plan
+
+## Execution Commands
+
+Start work on a task:
+```bash
+md implement.claude.md --_project "{{ _project }}" --_task "1.1"
+```
+
+Check progress:
+```bash
+!npm test -- --watch
+```
+
+---
+
+**Next**: `md implement.claude.md --_project "{{ _project }}"`