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
• 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
• Built-in Spec Engine: OpenSpec-compatible specs/changes without external openspec
• 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

Installation

Prerequisites

• Node.js >= 20.19.0 or Bun >= 1.0 — Check with node --version or bun --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

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.

Install from source

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: install a skill from an ecosystem repo (defaults to npx skills), then re-index into the skills DB:

# List skills in a repo
tmd skills add vercel-labs/agent-skills --list

# Install a specific skill to the current project (non-interactive)
tmd skills add vercel-labs/agent-skills --skill web-design-guidelines -y

# If the Desktop UI doesn't show it yet:
tmd skills sync

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

For a full reference, run tmd --help (and tmd <command> --help), or see docs/.

Common workflow (PDCA)

tmd init
tmd plan "Describe the work"
tmd do <task-id>
tmd check <task-id>
tmd act <task-id>

Skills (npx-first)

• tmd skills add <source> defaults to the ecosystem CLI (npx skills add), installs skills under {project_root}/.agents/skills/<name>, and then indexes them into {project_root}/.tmd/skills.db.
• tmd skills sync re-indexes {project_root}/.agents/skills/ into {project_root}/.tmd/skills.db.

See docs/skills.md for commands, flags, and troubleshooting.

Desktop

• tmd ui launches the Desktop app (browse tasks, skills, agents, config)

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

.agents/
└── 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

Example 3: Automated Pipe

# 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

Example 4: Feishu CLI Integration

# List available Feishu chats
tmd feishu chats

# List chats in JSON format
tmd feishu chats --json

# Get messages from a chat
tmd feishu messages --chat-id oc_1234567890abcdef

# Get messages with pagination and sorting
tmd feishu messages --chat-id oc_1234567890abcdef --page-size 20 --sort-type ByCreateTimeAsc

# Send a message to a Feishu chat
tmd feishu message send --chat-id oc_1234567890abcdef --message "Hello from TMD!"

# Reply to a message
tmd feishu message reply --message-id om_1234567890abcdef --message "This is a reply"

# Get a specific message
tmd feishu message get --message-id om_1234567890abcdef

# Get message in JSON format
tmd feishu message get --message-id om_1234567890abcdef --json

Note: Feishu commands require credentials to be configured. Use tmd ui to open the desktop application and configure feishu_app_id and feishu_app_secret in Settings.

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

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

Apache-2.0