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

$3

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

$3

Option A: Using npm
``bash npm install -g @tmddev/tmd@latest`

Verify installation:`bash tmd --version`

Option B: Using pnpm`bash pnpm install -g @tmddev/tmd@latest`

Option C: Use locally`bash 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`bash 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.
$3

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

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

Optional:

- pnpm build:native — Rebuild only the tmd-skillsRust 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:

`bash

`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
$3

`bash 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"
$3

`bash tmd do

`or use alias`


tmdd


This creates:
- Execution document
- Data collection document
$3

`bash tmd check

`or use alias`


tmdc


This creates:
- Evaluation document
- Deviation analysis document
$3

`bash tmd act

`or use alias`


tmda

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

`$3`

- ✅ 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 --help), or see docs/.

`$3`

`bash tmd init tmd plan "Describe the work" tmd do tmd check tmd act`

`$3`

- tmd skills add defaults to the ecosystem CLI (npx skills add), installs skills under {project_root}/.agents/skills/, 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.

`$3`

- 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`

`$3`

`bash

`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.
$3

`bash

`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  --skill generate-readme-multilang

$3

`bash

`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`

`$3`

`bash

`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`

`bash

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

`$3`

`bash

`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

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!

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

Installation

$3

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

$3

Option A: Using npm
``bash npm install -g @tmddev/tmd@latest`

Verify installation:`bash tmd --version`

Option B: Using pnpm`bash pnpm install -g @tmddev/tmd@latest`

Option C: Use locally`bash 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`bash 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.
$3

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

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

Optional:

Example: install a skill from an ecosystem repo (defaults to npx skills), then re-index into the skills DB:

`bash

`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
$3

`bash 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"
$3

`bash tmd do

`or use alias`


tmdd


This creates:
- Execution document
- Data collection document
$3

`bash tmd check

`or use alias`


tmdc


This creates:
- Evaluation document
- Deviation analysis document
$3

`bash tmd act

`or use alias`


tmda

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.

`$3`

`Commands`

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

`$3`

`bash tmd init tmd plan "Describe the work" tmd do tmd check tmd act`

`$3`

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

`$3`

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

`Directory Structure`

`.agents/ └── skills/ └── [skill-name]/ ├── SKILL.md ├── steps.yaml ├── config.yaml └── metadata.yaml`

`Examples`

`$3`

`bash

`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.
$3

`bash

`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  --skill generate-readme-multilang

$3

`bash

`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

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

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

Pipe completed successfully`

`$3`

`bash

`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`

`bash

`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:

`Contributing`

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

`$3`

`bash

`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