From 72c865e59afb9d02157e4303f4f2ee7a7b885b52 Mon Sep 17 00:00:00 2001 From: Huynh Duc Dung Date: Tue, 16 Dec 2025 15:30:32 +0800 Subject: [PATCH 1/2] feat: add spec-driven development example using markdown agents --- examples/spec-driven/README.md | 60 +++++++++++ examples/spec-driven/constitution.claude.md | 31 ++++++ examples/spec-driven/implement.claude.md | 86 +++++++++++++++ examples/spec-driven/plan.claude.md | 58 ++++++++++ examples/spec-driven/specify.claude.md | 45 ++++++++ examples/spec-driven/tasks.claude.md | 112 ++++++++++++++++++++ 6 files changed, 392 insertions(+) create mode 100644 examples/spec-driven/README.md create mode 100644 examples/spec-driven/constitution.claude.md create mode 100644 examples/spec-driven/implement.claude.md create mode 100644 examples/spec-driven/plan.claude.md create mode 100644 examples/spec-driven/specify.claude.md create mode 100644 examples/spec-driven/tasks.claude.md diff --git a/examples/spec-driven/README.md b/examples/spec-driven/README.md new file mode 100644 index 0000000..085a32c --- /dev/null +++ b/examples/spec-driven/README.md @@ -0,0 +1,60 @@ +# Spec-Driven Development Example + +This folder demonstrates spec-driven development using mdflow—a lightweight, markdown-based approach inspired by GitHub's Spec Kit. + +## The Pattern + +Instead of complex frameworks, use simple markdown files with YAML frontmatter to guide development through phases: + +1. **constitution.claude.md** - Define project principles and values +2. **specify.claude.md** - Write user stories and requirements +3. **plan.claude.md** - Create technical architecture and design +4. **tasks.claude.md** - Break down into actionable tasks +5. **implement.claude.md** - Execute and validate implementation + +## How to Use + +Run each phase in order: + +```bash +# Define principles +md constitution.claude.md + +# Write requirements +md specify.claude.md + +# Plan technical approach +md plan.claude.md + +# Break into tasks +md tasks.claude.md + +# Execute implementation +md implement.claude.md +``` + +## Why This Approach? + +- **Lightweight**: Just markdown files, no complex frameworks +- **AI-friendly**: YAML frontmatter + structured content works well with AI assistants +- **Versionable**: Keep specifications in git alongside code +- **Incremental**: Each phase builds on previous work +- **Reusable**: Copy these files as templates for new projects + +## Key Difference from Spec Kit + +Spec Kit is a **full framework** with CLI tools and specialized agents. This mdflow pattern is a **lightweight alternative** that: +- Uses mdflow's `.md` agent files directly +- Relies on your AI assistant's capabilities +- Requires no additional tooling beyond mdflow +- Focuses on the spec-driven mindset over tooling + +## Example Workflow + +1. Start with `constitution.claude.md` to establish your team's values +2. Use `specify.claude.md` to clarify what you're building +3. Have Claude create a technical `plan.claude.md` +4. Use `tasks.claude.md` to decompose the work +5. Execute `implement.claude.md` to guide implementation + +Each file is standalone but references the previous phases, creating a coherent narrative of your feature development. diff --git a/examples/spec-driven/constitution.claude.md b/examples/spec-driven/constitution.claude.md new file mode 100644 index 0000000..e6ea57b --- /dev/null +++ b/examples/spec-driven/constitution.claude.md @@ -0,0 +1,31 @@ +--- +model: opus +--- + +# Constitution: Project Development Principles + +Define the core principles and values that will guide all development decisions for this project. + +## 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 + +## User Experience +- Intuitive command-line interfaces +- Clear error messages with actionable guidance +- Fast feedback loops for interactive tools +- Comprehensive help documentation diff --git a/examples/spec-driven/implement.claude.md b/examples/spec-driven/implement.claude.md new file mode 100644 index 0000000..208b1f4 --- /dev/null +++ b/examples/spec-driven/implement.claude.md @@ -0,0 +1,86 @@ +--- +model: opus +--- + +# Implementation: Execute the Plan + +Execute all tasks to build the feature according to the plan. + +## Pre-Implementation Checklist +- [ ] Constitution established and agreed upon +- [ ] Specification reviewed and approved +- [ ] Technical plan validated +- [ ] Task breakdown accepted +- [ ] Team understanding confirmed + +## Execution Instructions + +### Step 1: Validate Prerequisites +```bash +# Ensure development environment is ready +bun --version +git status +``` + +### Step 2: Execute Phase 1 (Core Infrastructure) +Process Task 1.1, 1.2, 1.3 sequentially: +- Create type definitions +- Implement parser +- Set up build configuration + +### Step 3: Execute Phase 2 (Configuration & Templating) +Process Task 2.1, 2.2, 2.3: +- Build configuration loader +- Integrate LiquidJS templates +- Add environment handling + +### Step 4: Execute Phase 3 (Import System) +Process Task 3.1, 3.2, 3.3: +- File import parser +- Glob support with filtering +- Command output injection + +### Step 5: Execute Phase 4 (Command Execution) +Process Task 4.1, 4.2, 4.3: +- Command resolution logic +- CLI argument building +- Process execution and streaming + +### Step 6: Execute Phase 5 (History & State) +Process Task 5.1, 5.2: +- Frecency tracking system +- Variable persistence and recall + +### Step 7: Execute Phase 6 (CLI & Logging) +Process Task 6.1, 6.2: +- Pino logging setup +- CLI command interface + +### Step 8: Execute Phase 7 (Testing & Documentation) +Process Task 7.1, 7.2, 7.3: +- Unit test suite +- Integration tests +- Complete documentation + +## Validation Gates + +After each phase, verify: +- ✓ Code compiles without errors +- ✓ Existing tests still pass +- ✓ New functionality works as specified +- ✓ Documentation is updated +- ✓ Examples reflect new features + +## Rollout Plan +1. Merge to main branch +2. Tag release version +3. Run smoke tests on all platforms +4. Update CHANGELOG.md +5. Publish release notes + +## Success Criteria +- All phases completed as planned +- Test coverage above 80% +- All CLI commands functional +- Documentation comprehensive +- No breaking changes to existing API diff --git a/examples/spec-driven/plan.claude.md b/examples/spec-driven/plan.claude.md new file mode 100644 index 0000000..d12ae4f --- /dev/null +++ b/examples/spec-driven/plan.claude.md @@ -0,0 +1,58 @@ +--- +model: opus +--- + +# Implementation Plan: Technical Approach + +Describe your chosen technology stack and architecture for solving the specification. + +## Technology Stack +- **Runtime**: Bun (fast JavaScript/TypeScript runtime) +- **Language**: TypeScript (type safety) +- **Template Engine**: LiquidJS (flexible templating) +- **Validation**: Zod (schema validation) +- **Logging**: Pino (structured logging) +- **CLI**: Commander.js (command framework) + +## Architecture Overview + +### Core Components +1. **Frontmatter Parser**: Parse YAML from markdown files +2. **Template Engine**: Process LiquidJS templates with variable substitution +3. **Import System**: Handle file imports, globs, and command execution +4. **Command Resolver**: Determine which CLI tool to invoke +5. **Execution Engine**: Execute commands with proper argument passing + +### Data Flow +``` +.md file + → Parse frontmatter (YAML) + → Load global config + → Apply defaults + → Expand imports (@./file.md, !`cmd`) + → Substitute templates ({{ _varname }}) + → Build CLI args + → Execute command +``` + +## Module Structure +``` +src/ +├── index.ts # CLI entry point +├── command.ts # Command resolution and execution +├── config.ts # Configuration management +├── template.ts # Template variable substitution +├── imports.ts # File/glob/command imports +├── env.ts # Environment loading +├── types.ts # Type definitions +├── schema.ts # Validation schemas +├── logger.ts # Logging setup +└── history.ts # Frecency and variable history +``` + +## Key Design Decisions +1. **Markdown + YAML**: Simple, readable, version-controllable +2. **Passthrough architecture**: Only consume system keys, pass rest to CLI tool +3. **Template-first**: Variables are processed before command execution +4. **Modular imports**: Compose agents from multiple files +5. **History-aware**: Learn from previous variable inputs diff --git a/examples/spec-driven/specify.claude.md b/examples/spec-driven/specify.claude.md new file mode 100644 index 0000000..ac800ca --- /dev/null +++ b/examples/spec-driven/specify.claude.md @@ -0,0 +1,45 @@ +--- +model: opus +--- + +# Specification: What We're Building + +Describe what you want to build, focusing on the **what** and **why**, not the technical details. + +## Feature Name +[e.g., "Markdown Agent Executor"] + +## User Stories + +### As a developer, I want to... +Define clear user-focused outcomes that the feature should enable. + +**Story 1: Create and run markdown-based agents** +- Define AI agents as simple markdown files +- Configure behavior with YAML frontmatter +- Execute agents from the command line +- Get results in print or interactive mode + +**Story 2: Use template variables and imports** +- Reference dynamic values in markdown content +- Import external files or command outputs +- Use conditional logic in templates +- Access command-line arguments + +**Story 3: Manage configuration globally** +- Set command defaults in `~/.mdflow/config.yaml` +- Override defaults per agent +- Store and recall variable history +- Track usage frequency + +## Success Criteria +- [ ] Agents can be defined and executed via markdown files +- [ ] Template variables work correctly +- [ ] File imports and command outputs integrate seamlessly +- [ ] Configuration management works as expected +- [ ] All core CLI commands are functional + +## Out of Scope +- GUI interface +- Complex build processes +- Non-markdown agent definitions diff --git a/examples/spec-driven/tasks.claude.md b/examples/spec-driven/tasks.claude.md new file mode 100644 index 0000000..10625a4 --- /dev/null +++ b/examples/spec-driven/tasks.claude.md @@ -0,0 +1,112 @@ +--- +model: opus +--- + +# Task Breakdown: Actionable Implementation Steps + +Convert the plan into specific, sequenced implementation tasks. + +## Phase 1: Core Infrastructure +- [ ] **Task 1.1**: Set up project structure and build tooling + - Create tsconfig.json + - Set up Bun package.json with dependencies + - Configure TypeScript paths + +- [ ] **Task 1.2**: Implement type system and schemas + - Define AgentFrontmatter interface + - Create Zod validation schemas + - Add type exports + +- [ ] **Task 1.3**: Build frontmatter parser + - Parse YAML from markdown frontmatter + - Validate against schema + - Handle parsing errors gracefully + +## Phase 2: Configuration & Templating +- [ ] **Task 2.1**: Implement configuration system + - Load global config from ~/.mdflow/config.yaml + - Merge with frontmatter values + - Implement defaults per command + +- [ ] **Task 2.2**: Build template engine + - Integrate LiquidJS + - Support variable substitution {{ _varname }} + - Handle filters and conditionals + - Validate template syntax + +- [ ] **Task 2.3**: Add environment loading + - Load .env files + - Parse _env frontmatter key + - Apply to process.env + +## Phase 3: Import System +- [ ] **Task 3.1**: Implement file imports + - Support @./path.md syntax + - Handle relative paths + - Cache imported content + +- [ ] **Task 3.2**: Add glob support + - Support @./src/**/*.ts patterns + - Respect .gitignore + - Sort results consistently + +- [ ] **Task 3.3**: Implement command execution + - Support !`command` syntax + - Capture stdout/stderr + - Inject command output into templates + +## Phase 4: Command Execution +- [ ] **Task 4.1**: Build command resolver + - Parse command from filename + - Support MA_COMMAND env override + - Validate command availability + +- [ ] **Task 4.2**: Implement argument builder + - Convert frontmatter to CLI flags + - Handle array values + - Support positional mapping ($1, $2, etc.) + +- [ ] **Task 4.3**: Create execution engine + - Spawn child processes + - Handle both print and interactive modes + - Stream output appropriately + +## Phase 5: History & State +- [ ] **Task 5.1**: Build history system + - Calculate frecency scores + - Track agent usage + - Store variable history + +- [ ] **Task 5.2**: Implement variable persistence + - Save variable values to ~/.mdflow/variable-history.json + - Load previous values for prompting + - Support --_no-history flag + +## Phase 6: CLI & Logging +- [ ] **Task 6.1**: Set up logging infrastructure + - Configure Pino logger + - Create ~/.mdflow/logs directory + - Log per-agent activity + +- [ ] **Task 6.2**: Build CLI interface + - Implement `md ` command + - Add `md create [name]` subcommand + - Add `md setup`, `md logs`, `md help` + - Parse CLI arguments properly + +## Phase 7: Testing & Documentation +- [ ] **Task 7.1**: Write unit tests + - Test parser functionality + - Test template engine + - Test command resolution + - Test argument building + +- [ ] **Task 7.2**: Create integration tests + - End-to-end agent execution + - Template variable flow + - Import system behavior + +- [ ] **Task 7.3**: Document API and usage + - Write CLAUDE.md guide + - Create example agents + - Document frontmatter keys From dbefc2431a7b6af962e5904da072385ada461a4b Mon Sep 17 00:00:00 2001 From: Huynh Duc Dung Date: Tue, 16 Dec 2025 18:31:14 +0800 Subject: [PATCH 2/2] feat: spec-driven development example with mdflow features Add comprehensive spec-driven development workflow: - 7 interconnected markdown agents (constitution, specify, clarify, plan, tasks, review, implement) - ai-slop-remover agent for cleaning AI-generated code artifacts - Demonstrates mdflow features: template variables, file imports, inline commands, interactive mode, agent composition --- examples/spec-driven/README.md | 209 ++++++++++++++++---- examples/spec-driven/clarify.claude.md | 60 ++++++ examples/spec-driven/constitution.claude.md | 24 ++- examples/spec-driven/implement.claude.md | 160 ++++++++------- examples/spec-driven/plan.claude.md | 102 ++++++---- examples/spec-driven/review.claude.md | 93 +++++++++ examples/spec-driven/specify.claude.md | 93 +++++---- examples/spec-driven/tasks.claude.md | 184 +++++++---------- 8 files changed, 627 insertions(+), 298 deletions(-) create mode 100644 examples/spec-driven/clarify.claude.md create mode 100644 examples/spec-driven/review.claude.md diff --git a/examples/spec-driven/README.md b/examples/spec-driven/README.md index 085a32c..e797714 100644 --- a/examples/spec-driven/README.md +++ b/examples/spec-driven/README.md @@ -1,60 +1,191 @@ -# Spec-Driven Development Example +# Spec-Driven Development with mdflow -This folder demonstrates spec-driven development using mdflow—a lightweight, markdown-based approach inspired by GitHub's Spec Kit. +A lightweight, spec-driven development workflow using markdown agents. Inspired by GitHub's Spec Kit, optimized for mdflow. ## The Pattern -Instead of complex frameworks, use simple markdown files with YAML frontmatter to guide development through phases: +Five interconnected markdown agents that guide you from vision to implementation: -1. **constitution.claude.md** - Define project principles and values -2. **specify.claude.md** - Write user stories and requirements -3. **plan.claude.md** - Create technical architecture and design -4. **tasks.claude.md** - Break down into actionable tasks -5. **implement.claude.md** - Execute and validate implementation +``` +constitution.claude.md + ↓ + specify.claude.md + ↓ + plan.claude.md + ↓ + tasks.claude.md + ↓ + implement.claude.md +``` -## How to Use +## Quick Start -Run each phase in order: +### 1. Establish Principles +```bash +md constitution.claude.md --_project "MyFeature" --_team "TeamName" +``` +Defines project values, engineering standards, and team agreements. +### 2. Define Requirements ```bash -# Define principles -md constitution.claude.md +md specify.claude.md --_project "MyFeature" +``` +Interactive session to clarify what you're building (what & why). -# Write requirements -md specify.claude.md +### 3. Plan Architecture +```bash +md plan.claude.md --_project "MyFeature" --_tech_stack "Node.js + React" +``` +Creates technical approach with design decisions and risk assessment. -# Plan technical approach -md plan.claude.md +### 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. -# Break into tasks -md tasks.claude.md +## mdflow Features Used -# Execute implementation -md implement.claude.md +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"` -## Why This Approach? +### File Imports (`@./path`) +```markdown +@./package.json +@./src/**/*.ts +@./tsconfig.json:1-20 +``` +Reference actual project files directly in the agent. -- **Lightweight**: Just markdown files, no complex frameworks -- **AI-friendly**: YAML frontmatter + structured content works well with AI assistants -- **Versionable**: Keep specifications in git alongside code -- **Incremental**: Each phase builds on previous work -- **Reusable**: Copy these files as templates for new projects +### Inline Commands (`` !`cmd` ``) +```markdown +!git status +!npm test +!npm list --depth=0 +``` +Execute commands and inject output into the agent prompt. -## Key Difference from Spec Kit +### 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 -Spec Kit is a **full framework** with CLI tools and specialized agents. This mdflow pattern is a **lightweight alternative** that: -- Uses mdflow's `.md` agent files directly -- Relies on your AI assistant's capabilities -- Requires no additional tooling beyond mdflow -- Focuses on the spec-driven mindset over tooling +For an authentication feature: + +```bash +# 1. What's our principle on auth security? +md constitution.claude.md --_project "Auth" --_team "Security" -## Example Workflow +# 2. What do we need to build? +md specify.claude.md --_project "Auth" -1. Start with `constitution.claude.md` to establish your team's values -2. Use `specify.claude.md` to clarify what you're building -3. Have Claude create a technical `plan.claude.md` -4. Use `tasks.claude.md` to decompose the work -5. Execute `implement.claude.md` to guide implementation +# 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" +``` -Each file is standalone but references the previous phases, creating a coherent narrative of your feature development. +## 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 index e6ea57b..0f773e8 100644 --- a/examples/spec-driven/constitution.claude.md +++ b/examples/spec-driven/constitution.claude.md @@ -1,11 +1,22 @@ --- model: opus +_project: "{{ _project | default: 'MyProject' }}" +_team: "{{ _team | default: 'Engineering Team' }}" --- -# Constitution: Project Development Principles +# 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 @@ -24,8 +35,19 @@ Define the core principles and values that will guide all development decisions - 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 index 208b1f4..3a38ce8 100644 --- a/examples/spec-driven/implement.claude.md +++ b/examples/spec-driven/implement.claude.md @@ -1,86 +1,96 @@ --- model: opus +_project: "{{ _project | default: 'MyProject' }}" +_task: "{{ _task | default: '1.1' }}" +_interactive: true --- -# Implementation: Execute the Plan +# Implementation: {{ _project }} - Task {{ _task }} -Execute all tasks to build the feature according to the plan. +Guide for executing individual tasks or all tasks in sequence. -## Pre-Implementation Checklist -- [ ] Constitution established and agreed upon -- [ ] Specification reviewed and approved -- [ ] Technical plan validated -- [ ] Task breakdown accepted -- [ ] Team understanding confirmed +**Task Reference**: @./tasks.claude.md +**All Specs**: @./plan.claude.md +**Mode**: Interactive - ask questions as you work -## Execution Instructions +## 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 -### Step 1: Validate Prerequisites +Once task is done: ```bash -# Ensure development environment is ready -bun --version -git status +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 ``` -### Step 2: Execute Phase 1 (Core Infrastructure) -Process Task 1.1, 1.2, 1.3 sequentially: -- Create type definitions -- Implement parser -- Set up build configuration - -### Step 3: Execute Phase 2 (Configuration & Templating) -Process Task 2.1, 2.2, 2.3: -- Build configuration loader -- Integrate LiquidJS templates -- Add environment handling - -### Step 4: Execute Phase 3 (Import System) -Process Task 3.1, 3.2, 3.3: -- File import parser -- Glob support with filtering -- Command output injection - -### Step 5: Execute Phase 4 (Command Execution) -Process Task 4.1, 4.2, 4.3: -- Command resolution logic -- CLI argument building -- Process execution and streaming - -### Step 6: Execute Phase 5 (History & State) -Process Task 5.1, 5.2: -- Frecency tracking system -- Variable persistence and recall - -### Step 7: Execute Phase 6 (CLI & Logging) -Process Task 6.1, 6.2: -- Pino logging setup -- CLI command interface - -### Step 8: Execute Phase 7 (Testing & Documentation) -Process Task 7.1, 7.2, 7.3: -- Unit test suite -- Integration tests -- Complete documentation - -## Validation Gates - -After each phase, verify: -- ✓ Code compiles without errors -- ✓ Existing tests still pass -- ✓ New functionality works as specified -- ✓ Documentation is updated -- ✓ Examples reflect new features - -## Rollout Plan -1. Merge to main branch -2. Tag release version -3. Run smoke tests on all platforms -4. Update CHANGELOG.md -5. Publish release notes - -## Success Criteria -- All phases completed as planned -- Test coverage above 80% -- All CLI commands functional -- Documentation comprehensive -- No breaking changes to existing API +**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 index d12ae4f..da80f42 100644 --- a/examples/spec-driven/plan.claude.md +++ b/examples/spec-driven/plan.claude.md @@ -1,58 +1,78 @@ --- model: opus +_project: "{{ _project | default: 'MyProject' }}" +_tech_stack: "{{ _tech_stack | default: 'TypeScript + Bun' }}" --- -# Implementation Plan: Technical Approach +# Implementation Plan: {{ _project }} -Describe your chosen technology stack and architecture for solving the specification. +Technical architecture and implementation approach based on requirements. -## Technology Stack -- **Runtime**: Bun (fast JavaScript/TypeScript runtime) -- **Language**: TypeScript (type safety) -- **Template Engine**: LiquidJS (flexible templating) -- **Validation**: Zod (schema validation) -- **Logging**: Pino (structured logging) -- **CLI**: Commander.js (command framework) +**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. **Frontmatter Parser**: Parse YAML from markdown files -2. **Template Engine**: Process LiquidJS templates with variable substitution -3. **Import System**: Handle file imports, globs, and command execution -4. **Command Resolver**: Determine which CLI tool to invoke -5. **Execution Engine**: Execute commands with proper argument passing +1. **[Component A]**: Purpose and responsibilities +2. **[Component B]**: Purpose and responsibilities +3. **[Component C]**: Purpose and responsibilities -### Data Flow +### Data Flow Diagram ``` -.md file - → Parse frontmatter (YAML) - → Load global config - → Apply defaults - → Expand imports (@./file.md, !`cmd`) - → Substitute templates ({{ _varname }}) - → Build CLI args - → Execute command +Input + ↓ +[Process] + ↓ +Output ``` -## Module Structure +### 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`: ``` -src/ -├── index.ts # CLI entry point -├── command.ts # Command resolution and execution -├── config.ts # Configuration management -├── template.ts # Template variable substitution -├── imports.ts # File/glob/command imports -├── env.ts # Environment loading -├── types.ts # Type definitions -├── schema.ts # Validation schemas -├── logger.ts # Logging setup -└── history.ts # Frecency and variable history +@./plan.claude.md ``` -## Key Design Decisions -1. **Markdown + YAML**: Simple, readable, version-controllable -2. **Passthrough architecture**: Only consume system keys, pass rest to CLI tool -3. **Template-first**: Variables are processed before command execution -4. **Modular imports**: Compose agents from multiple files -5. **History-aware**: Learn from previous variable inputs +**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 index ac800ca..5f72495 100644 --- a/examples/spec-driven/specify.claude.md +++ b/examples/spec-driven/specify.claude.md @@ -1,45 +1,70 @@ --- model: opus +_project: "{{ _project | default: 'MyProject' }}" +_interactive: true --- -# Specification: What We're Building +# Specification: {{ _project }} Requirements -Describe what you want to build, focusing on the **what** and **why**, not the technical details. +Define what you want to build, focusing on the **what** and **why**, not the technical details. -## Feature Name -[e.g., "Markdown Agent Executor"] +**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 -### As a developer, I want to... -Define clear user-focused outcomes that the feature should enable. - -**Story 1: Create and run markdown-based agents** -- Define AI agents as simple markdown files -- Configure behavior with YAML frontmatter -- Execute agents from the command line -- Get results in print or interactive mode - -**Story 2: Use template variables and imports** -- Reference dynamic values in markdown content -- Import external files or command outputs -- Use conditional logic in templates -- Access command-line arguments - -**Story 3: Manage configuration globally** -- Set command defaults in `~/.mdflow/config.yaml` -- Override defaults per agent -- Store and recall variable history -- Track usage frequency - -## Success Criteria -- [ ] Agents can be defined and executed via markdown files -- [ ] Template variables work correctly -- [ ] File imports and command outputs integrate seamlessly -- [ ] Configuration management works as expected -- [ ] All core CLI commands are functional +### 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 -- GUI interface -- Complex build processes -- Non-markdown agent definitions +- 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 index 10625a4..9f57c10 100644 --- a/examples/spec-driven/tasks.claude.md +++ b/examples/spec-driven/tasks.claude.md @@ -1,112 +1,80 @@ --- model: opus +_project: "{{ _project | default: 'MyProject' }}" --- -# Task Breakdown: Actionable Implementation Steps - -Convert the plan into specific, sequenced implementation tasks. - -## Phase 1: Core Infrastructure -- [ ] **Task 1.1**: Set up project structure and build tooling - - Create tsconfig.json - - Set up Bun package.json with dependencies - - Configure TypeScript paths - -- [ ] **Task 1.2**: Implement type system and schemas - - Define AgentFrontmatter interface - - Create Zod validation schemas - - Add type exports - -- [ ] **Task 1.3**: Build frontmatter parser - - Parse YAML from markdown frontmatter - - Validate against schema - - Handle parsing errors gracefully - -## Phase 2: Configuration & Templating -- [ ] **Task 2.1**: Implement configuration system - - Load global config from ~/.mdflow/config.yaml - - Merge with frontmatter values - - Implement defaults per command - -- [ ] **Task 2.2**: Build template engine - - Integrate LiquidJS - - Support variable substitution {{ _varname }} - - Handle filters and conditionals - - Validate template syntax - -- [ ] **Task 2.3**: Add environment loading - - Load .env files - - Parse _env frontmatter key - - Apply to process.env - -## Phase 3: Import System -- [ ] **Task 3.1**: Implement file imports - - Support @./path.md syntax - - Handle relative paths - - Cache imported content - -- [ ] **Task 3.2**: Add glob support - - Support @./src/**/*.ts patterns - - Respect .gitignore - - Sort results consistently - -- [ ] **Task 3.3**: Implement command execution - - Support !`command` syntax - - Capture stdout/stderr - - Inject command output into templates - -## Phase 4: Command Execution -- [ ] **Task 4.1**: Build command resolver - - Parse command from filename - - Support MA_COMMAND env override - - Validate command availability - -- [ ] **Task 4.2**: Implement argument builder - - Convert frontmatter to CLI flags - - Handle array values - - Support positional mapping ($1, $2, etc.) - -- [ ] **Task 4.3**: Create execution engine - - Spawn child processes - - Handle both print and interactive modes - - Stream output appropriately - -## Phase 5: History & State -- [ ] **Task 5.1**: Build history system - - Calculate frecency scores - - Track agent usage - - Store variable history - -- [ ] **Task 5.2**: Implement variable persistence - - Save variable values to ~/.mdflow/variable-history.json - - Load previous values for prompting - - Support --_no-history flag - -## Phase 6: CLI & Logging -- [ ] **Task 6.1**: Set up logging infrastructure - - Configure Pino logger - - Create ~/.mdflow/logs directory - - Log per-agent activity - -- [ ] **Task 6.2**: Build CLI interface - - Implement `md ` command - - Add `md create [name]` subcommand - - Add `md setup`, `md logs`, `md help` - - Parse CLI arguments properly - -## Phase 7: Testing & Documentation -- [ ] **Task 7.1**: Write unit tests - - Test parser functionality - - Test template engine - - Test command resolution - - Test argument building - -- [ ] **Task 7.2**: Create integration tests - - End-to-end agent execution - - Template variable flow - - Import system behavior - -- [ ] **Task 7.3**: Document API and usage - - Write CLAUDE.md guide - - Create example agents - - Document frontmatter keys +# 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 }}"`