TMD - Task Markdown Driven

Ten seconds to Ten minutes Task Markdown Driven Development!

Ten seconds to Ten minutes Task Markdown Driven Development!

A lightweight PDCA cycle management framework integrated with OpenSpec for specification-driven development.

This project is available at: https://tmdd.dev

Ten seconds to Ten minutes Task Markdown Driven Development!

TMD (Task Markdown Driven) combines OpenSpec's specification-driven development with the PDCA (Plan-Do-Check-Act) continuous improvement methodology. It provides a structured, traceable development management tool that ensures transparency and traceability through documentation-driven processes.

At the core of TMD is the principle that tasks should be pee-break (10 seconds to 10 minutes) sized - small, atomic, and completable in a single focused session.

• PDCA Cycle Management: Four-phase commands for Plan, Do, Check, and Act
• Pipe Execution: Automated PDCA cycles without human input for CI/CD and AI agent workflows
• Ten sec to Ten min Task!: Tasks are designed to be pee-break (10 seconds to 10 minutes) sized for quick completion
• OpenSpec Integration: Automatic creation and linking of OpenSpec change proposals
• Skills System: Reusable capabilities for AI agents with cross-agent invocation support
• Step Executors: Built-in executors for bash commands, file operations, and API calls
• English Language Standard: All documents and specifications use English
• Markdown-Based: All documentation stored in Markdown format
• CLI Interface: Simple command-line interface with aliases

• Node.js >= 20.19.0 or Bun >= 1.0 — Check with node --version or bun --version

Option A: Using npm

npm install -g @tmddev/tmd@latest

Verify installation:

tmd --version

Option B: Using pnpm

pnpm install -g @tmddev/tmd@latest

Option C: Use locally

git clone https://github.com/sdd330/tmd.git
cd tmd
pnpm install
pnpm run build
pnpm link --global  # Optional: link for local development

Option D: Using Bun

bun install -g @tmddev/tmd@latest
# or run without global install:
bun x @tmddev/tmd --version
bun run tmd --help   # when in a project with @tmddev/tmd as a dependency

In the TMD repo: bun install, bun run build, bun run test, and bun ./bin/tmd.js --version are all supported.

Prerequisites: Node.js >=20.19.0 or Bun >=1.0, pnpm, Rust (for the tmd-skills binary), git.

git clone https://github.com/sdd330/tmd.git
cd tmd
pnpm install
pnpm build          # includes the tmd-skills native binary
pnpm link --global  # optional: use `tmd` from this build

Optional:

• pnpm build:native — Rebuild only the tmd-skills Rust binary (faster when only Rust code changed).
• ./bin/agent-browser install — When using the agent-browser skill, install the agent-browser CLI if this script is provided (e.g. by the agent-browser project; skip if not present).

Example: add the pdf skill from anthropics/skills and symlink to all detected agents:

tmd skills add anthropics/skills --github --skill pdf --all

tmd plan "Generate README in different languages"
# or use alias
tmdp "Generate README in different languages"

This creates:

• Task directory structure
• Plan document template
• Resources document

Important: Task Size Guidelines - Ten sec to Ten min Task!

Tasks in the plan should be atomic and completable in pee-break (10 seconds to 10 minutes) sized tasks. This ensures:

• Tasks are actionable and completable by AI agents or humans
• Progress tracking is meaningful (tasks are either done or not done)
• No task requires complex multi-step coordination
• Agent Skills can be designed to complete individual tasks

Good atomic tasks:

• "Add import statement"
• "Update function signature"
• "Create test file"
• "Fix typo in documentation"

Tasks to break down:

• "Implement authentication and authorization" → Break into: "Add auth middleware", "Create login endpoint", "Add password validation"
• "Create API and update frontend" → Break into: "Create API endpoint", "Update frontend component", "Add API integration"

tmd do <task-id>
# or use alias
tmdd <task-id>

This creates:

• Execution document
• Data collection document

tmd check <task-id>
# or use alias
tmdc <task-id>

This creates:

• Evaluation document
• Deviation analysis document

tmd act <task-id>
# or use alias
tmda <task-id>

This creates:

• Improvement actions document
• Standardization document (if --standardize flag is used)

Ten seconds to Ten minutes Task Markdown Driven Development!

Tasks should be pee-break (10 seconds to 10 minutes) sized.

This principle ensures tasks are:

• Atomic: Cannot be meaningfully broken down further
• Actionable: Clear single action that can be completed
• Trackable: Either done or not done (no partial states)
• Agent-friendly: Suitable for AI agent autonomous execution
• Skill-compatible: Can be completed by a single Agent Skill

• ✅ Good: "Add import statement", "Update function signature", "Create test file"
• ❌ Too large: "Implement authentication and authorization", "Create API and update frontend"
• 💡 Break down large tasks into smaller atomic tasks before planning

• tmd init [path] - Initialize TMD in your project (creates .tmd/ and schemas/pdca/ when missing; default path .)
• tmd view - Display a dashboard of tasks by phase and status
• tmd validate [task-id] - Validate task documents or PDCA schemas
  • --schemas [name] - Validate schemas only (name optional)
  • --all - Validate all tasks and schemas
  • --strict - Stricter checks (e.g. task size)
  • --json - Output as JSON
• tmd schemas - List available workflow schemas
  • --json - Output as JSON

• tmd plan <description> / tmdp - Create a new plan

  • --openspec - Create or link OpenSpec change proposal
  • --skill - Create skill definition
  • --use-skill <skill-name> - Use existing skill
  • --validate-tasks - Validate task size: pee-break (10 seconds to 10 minutes)

• tmd do <task-id> / tmdd - Execute actions

  • --data <key=value> - Record data
  • --skill <skill-name> - Execute skill

• tmd check <task-id> / tmdc - Evaluate results

  • --compare - Automatic comparison
  • --validate-skill - Validate skill execution

• tmd act <task-id> / tmda - Take improvement actions

  • --standardize - Generate standardization document
  • --complete - Mark task as completed

• tmd list - List all tasks

  • --status <status> - Filter by status
  • --phase <phase> - Filter by phase

• tmd show <task-id> - Show task details

• tmd pipe init <task-id> - Initialize pipe configuration

  • --force - Overwrite existing configuration

• tmd pipe run <task-id> - Run full PDCA cycle automatically

  • --from <phase> - Start from specific phase (do, check, act)
  • --dry-run - Preview execution without making changes

• tmd pipe status <task-id> - Show pipe execution state

  • --json - Output in JSON format

• tmd skills list - List all available skills
  • --tag <tag> - Filter by tag (repeatable, OR semantics)
• tmd skills search <query> - Search skills
• tmd skills show <skill-name> - Show skill details
• tmd skills invoke <skill-name> --input <params> - Invoke a skill
• tmd skills create <name> - Create a skill (optionally --description <desc>, --tags <t1,t2>)
• tmd skills update <name> - Update metadata (--description <desc>, --tags <t1,t2>; at least one required)
• tmd skills remove <name> - Remove a skill (--force to skip confirmation)

Skills are reusable capabilities for AI agents that can be defined, shared, and executed within PDCA cycles.

tmd plan "As a developer, I want to generate README files in multiple languages, so as to make the project accessible to international contributors" --skill

This creates a skill with:

• User story format
• Executable steps definition
• Configuration
• Metadata for AI agent discovery

# .tmd/skills/generate-readme-multilang/metadata.yaml
name: generate-readme-multilang
version: 1.0.0
description: Generate README files in multiple languages
interface:
  input:
    - name: template_path
      type: string
      required: true
      description: Path to README.md template
    - name: target_languages
      type: array
      required: true
      description: List of target languages (e.g., ["zh", "es", "fr"])
  output:
    generated_files: array of file paths
    validation_status: enum (passed/failed)
    language_index_updated: boolean

Skills can be invoked by any AI agent:

tmd skill invoke generate-readme-multilang --input "template_path=README.md target_languages=[zh,es,fr]"

Pipe execution enables fully automated PDCA cycles without human intervention - ideal for CI/CD integration and AI agent workflows.

tmd pipe init <task-id>

This creates a pipeline.yaml configuration file in the task's plan directory with customizable settings for each phase.

tmd pipe run <task-id>

This automatically executes:

1. Do phase: Executes all tasks, runs skill steps, captures output
2. Check phase: Compares results against goals, analyzes deviations
3. Act phase: Processes results, generates improvements, marks task complete

# pipeline.yaml
version: "1.0"
phases:
  do:
    auto: true
    parallel: false
    maxConcurrency: 4
    successCriteria:
      minTasksCompleted: "100%"
  check:
    auto: true
    analyze: true
    recommend: true
  act:
    auto: true
    standardize: true
    carryForward: true
    completeOnSuccess: true

Pipeline supports three step types for automated task execution:

• bash: Execute shell commands

  - type: bash
    command: "npm run build"

• file: File operations (read, write, copy, delete)

  - type: file
    operation: write
    path: output.txt
    content: "Hello World"

• api: HTTP requests

  - type: api
    url: "https://api.example.com/data"
    method: POST
    body: { "key": "value" }

Preview pipe execution without making changes:

tmd pipe run <task-id> --dry-run

Start from a specific phase (useful for recovering from failures):

tmd pipe run <task-id> --from check

TMD automatically integrates with OpenSpec projects:

tmd plan "Description" --openspec

This:

• Detects OpenSpec project structure
• Creates OpenSpec change proposal
• Links TMD task to OpenSpec change
• Maintains bidirectional traceability

.tmd/
├── plan/
│   └── [task-id]/
│       ├── plan.md
│       └── resources.md
├── do/
│   └── [task-id]/
│       ├── execution.md
│       └── data.md
├── check/
│   └── [task-id]/
│       ├── evaluation.md
│       └── deviation.md
├── act/
│   └── [task-id]/
│       ├── improvement.md
│       └── standardization.md
└── skills/
    └── [skill-name]/
        ├── skill.md
        ├── steps.yaml
        ├── config.yaml
        └── metadata.yaml

# Plan (with atomic tasks in plan.md)
tmd plan "Generate README in different languages"
# Tasks in plan.md should be broken down, e.g.:
# - [ ] Read README.md template file
# - [ ] Extract translatable sections
# - [ ] Translate content to Chinese
# - [ ] Translate content to Spanish
# - [ ] Generate README.zh.md
# - [ ] Generate README.es.md
# - [ ] Validate markdown syntax
# - [ ] Update language index in main README

# Do
tmd do 20240115-generate-readme-different-languages

# Check
tmd check 20240115-generate-readme-different-languages --compare

# Act
tmd act 20240115-generate-readme-different-languages --standardize --complete

Note: The plan should break down the high-level goal into atomic pee-break (10 seconds to 10 minutes) sized tasks (Ten sec to Ten min Task!) in the Tasks section of plan.md.

# Create a skill
tmd plan "As a developer, I want to generate README files in multiple languages, so as to make the project accessible to international contributors" --skill

# Use the skill in a new task
tmd plan "Generate README for new project" --use-skill generate-readme-multilang

# Execute the skill
tmd do <task-id> --skill generate-readme-multilang

# Create a plan with tasks
tmd plan "Build and deploy application"

# Initialize pipe configuration
tmd pipe init 20260123-build-and-deploy-application

# Preview what will happen (dry run)
tmd pipe run 20260123-build-and-deploy-application --dry-run

# Run the full automated PDCA cycle
tmd pipe run 20260123-build-and-deploy-application

# Check pipe status
tmd pipe status 20260123-build-and-deploy-application

Output:

Pipe: 20260123-build-and-deploy-application
──────────────────────────────────────────────────

  Phase: DO
    Tasks to execute: 5/5
  Phase do completed

  Phase: CHECK
    Goals met: 3/3
  Phase check completed

  Phase: ACT
    Task marked as completed
  Phase act completed
──────────────────────────────────────────────────

Pipe completed successfully

All documents and specifications use English. The system:

• Generates all templates in English
• Validates user input (warns if non-English detected)
• Enforces English for OpenSpec specifications

# Install dependencies
pnpm install

# Build
pnpm run build

# Development mode (watch)
pnpm run dev

# Test
pnpm test

TMD follows the PDCA (Plan-Do-Check-Act) cycle:

┌────────────────────┐
│ Plan               │
│ Define objectives  │
│ Set goals & tasks  │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ Do                 │
│ Execute tasks      │
│ Collect data       │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ Check              │
│ Evaluate results   │
│ Analyze deviations │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│ Act                │
│ Improve &          │
│ Standardize        │
└────────────────────┘

Ten seconds to Ten minutes Task Markdown Driven Development!

Tasks should be pee-break (10 seconds to 10 minutes) sized. This ensures:

• Tasks are atomic and completable
• Progress tracking is meaningful
• No complex multi-step coordination required
• Agent-friendly for AI autonomous execution

Contributions are welcome! Please ensure all documentation follows the English language standard.

# Install dependencies
pnpm install

# Build
pnpm run build

# Test
pnpm test

# Development mode (watch)
pnpm run dev

# Lint
pnpm lint

See MAINTAINERS.md for maintainer information.

Apache-2.0