Package Exports

@tmddev/tmd

Readme

TMD - Task Markdown Driven

Ten seconds to Ten minutes Task Markdown Driven Development!

TMD - Task Markdown Driven

Ten seconds to Ten minutes Task Markdown Driven Development!

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

🌐 Website

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

Overview

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.

Features

PDCA Cycle Management: Four-phase commands for Plan, Do, Check, and Act
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
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

Installation

Prerequisites

Node.js >= 20.19.0 - Check your version with node --version

Install the CLI globally

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

Quick Start

1. Create a Plan

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"

2. Execute (Do Phase)

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

This creates:

Execution document
Data collection document

3. Check Results

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

This creates:

Evaluation document
Deviation analysis document

4. Act on Results

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

This creates:

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

Task Size Principle

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

Guidelines

✅ 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

Commands

PDCA Commands

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

Task Management

tmd list - List all tasks
- --status <status> - Filter by status
- --phase <phase> - Filter by phase
tmd show <task-id> - Show task details

Skills Management

tmd skills list - List all available skills
tmd skills search <query> - Search skills
tmd skills show <skill-name> - Show skill details
tmd skills invoke <skill-name> --input <params> - Invoke a skill

Skills System

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

Creating 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

This creates a skill with:

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

Example: README Generation Skill

# 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

Cross-Agent Invocation

Skills can be invoked by any AI agent:

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

OpenSpec Integration

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

Directory Structure

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

Examples

Example 1: Generate README in Different Languages

# 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.

Example 2: Using Skills

# 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

Language Standard

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

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Development mode (watch)
pnpm run dev

# Test
pnpm test

How It Works

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        │
└────────────────────┘

Task Size Principle

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

Contributing

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

Development

# 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.

License

MIT