feat: add spec-driven development example using markdown agents

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.

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 }}"
+```

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.