Task O Matic

Task-O-Matic

AI-powered task management CLI for single projects. Helps initialize projects, parse PRDs into tasks, break down work with AI, and execute tasks with automatic retry and verification.

When to Use

Use when the user wants to:

• Initialize a new project with task-o-matic
• Attach task-o-matic to an existing project (detect stack automatically)
• Parse a PRD (Product Requirements Document) into structured tasks
• Break down tasks into smaller subtasks using AI
• Enhance tasks with AI-powered documentation research
• Execute tasks with AI coding assistants
• Configure AI providers and models

CLI Location

The CLI binary is at: packages/cli/dist/cli/bin.js (after building)

Run with: node packages/cli/dist/cli/bin.js <command> [options]

Or if installed globally: task-o-matic <command> [options]

Core Workflow

# New project workflow
1. Initialize project (task-o-matic init init)
2. Configure AI provider (task-o-matic config set-ai-provider)
3. Parse PRD into tasks (task-o-matic prd parse)
4. Split tasks into subtasks (task-o-matic tasks split --all)
5. Execute tasks (task-o-matic tasks execute-loop)

# Existing project workflow
1. Attach to existing project (task-o-matic init attach)
2. Configure AI provider (task-o-matic config set-ai-provider)
3. Generate PRD from codebase (task-o-matic prd generate --from-codebase)
4. Create tasks from PRD (task-o-matic prd parse)
5. Execute tasks (task-o-matic tasks execute-loop)

Common Commands

Initialize Project

# Basic initialization
task-o-matic init init --project-name my-app --package-manager bun

# With specific AI provider
task-o-matic init init --project-name my-app --ai-provider openrouter --ai-model xiaomi/mimo-v2-flash:free

# With Better-T-Stack bootstrap
task-o-matic init init --project-name my-app --frontend next --backend convex --auth better-auth

Options:

• --ai-provider <provider>: AI provider (openrouter/anthropic/openai/custom)
• --ai-model <model>: AI model
• --project-name <name>: Project name
• --package-manager <pm>: bun/npm/pnpm (default: npm)
• --frontend <frontends...>: Frontend framework(s) (default: next)
• --backend <backend>: Backend framework (default: convex)
• --auth <auth>: Authentication (default: better-auth)
• --directory <dir>: Working directory

Attach to Existing Project

# Attach to existing project (auto-detect stack)
task-o-matic init attach

# With full project analysis
task-o-matic init attach --analyze

# Dry run (just show detection, don't create files)
task-o-matic init attach --dry-run

# Force re-detection (update cached stack.json)
task-o-matic init attach --redetect

Options:

• --analyze: Run full project analysis (TODOs, features, structure)
• --dry-run: Just detect stack, don't create files
• --redetect: Force re-detection (overwrites cached stack.json)
• --ai-provider <provider>: AI provider (openrouter/anthropic/openai/custom)
• --ai-model <model>: AI model
• --context7-api-key <key>: Context7 API key

What it detects:

• Language (TypeScript/JavaScript)
• Framework(s) (Next.js, Express, Hono, etc.)
• Database (Postgres, MongoDB, SQLite, etc.)
• ORM (Prisma, Drizzle, etc.)
• Auth (Better-Auth, Clerk, NextAuth, etc.)
• Package Manager (npm, pnpm, bun, yarn)
• Runtime (Node, Bun)
• API style (tRPC, GraphQL, REST)
• Testing frameworks
• Build tools

What it creates:

• .task-o-matic/config.json - AI settings
• .task-o-matic/stack.json - Cached stack detection (used by AI context)
• .task-o-matic/mcp.json - Context7 config
• .task-o-matic/tasks/ - Task storage
• .task-o-matic/prd/ - PRD storage
• Updates .gitignore if git exists

Configure AI Provider

# Set provider and model
task-o-matic config set-ai-provider openrouter xiaomi/mimo-v2-flash:free

# Set with custom URL
task-o-matic config set-ai-provider custom https://api.example.com

# Check current config
task-o-matic config get-ai-config

Generate PRD from Codebase

# Analyze current project and generate PRD
task-o-matic prd generate

# With streaming output
task-o-matic prd generate --stream

# With custom output filename
task-o-matic prd generate --output my-project-prd.md

Parse PRD

# Basic parse
task-o-matic prd parse --file prd.md

# With streaming output
task-o-matic prd parse --file prd.md --stream

# With reasoning tokens (for models that support it)
task-o-matic prd parse --file prd.md --ai-reasoning 4000 --stream

# Multiple models with combination
task-o-matic prd parse --file prd.md --ai openrouter:model1 openrouter:model2 --combine-ai openrouter:combine-model

Options:

• --file <path>: Path to PRD file (required)
• --stream: Show streaming AI output
• --ai-reasoning <tokens>: Max reasoning tokens for supported models
• --ai <models...>: Multiple AI models
• --combine-ai <provider:model>: Model to combine results
• --tools: Enable filesystem tools for project analysis

Work with Tasks

List Tasks

task-o-matic tasks list

# With filters
task-o-matic tasks list --status todo
task-o-matic tasks list --tag frontend

Create Task

# Manual creation
task-o-matic tasks create --title "Add authentication" --content "Implement OAuth2 login"

# With AI enhancement
task-o-matic tasks create --title "Add authentication" --ai-enhance --stream

Split Tasks

# Split specific task
task-o-matic tasks split --task-id 1 --stream

# Split all tasks
task-o-matic tasks split --all --stream

# With filters
task-o-matic tasks split --all --status todo --stream

Options:

• --task-id <id>: Specific task to split
• --all: Split all tasks without subtasks
• --status <status>: Filter by status (todo/in-progress/completed)
• --stream: Show streaming output
• --ai-reasoning <tokens>: Enable reasoning
• --dry: Preview without changes

Enhance Tasks

# Enhance specific task
task-o-matic tasks enhance --task-id 1 --stream

# Enhance all tasks
task-o-matic tasks enhance --all --stream

# With filter
task-o-matic tasks enhance --all --status todo --stream

Options:

• --task-id <id>: Specific task to enhance
• --all: Enhance all tasks
• --status <status>: Filter by status
• --tag <tag>: Filter by tag
• --dry: Preview without changes
• --force: Skip confirmation

Task Status

# Set task status
task-o-matic tasks status --task-id 1 --status in-progress

# Available statuses: todo, in-progress, completed

Task Tree

# Show hierarchical task tree
task-o-matic tasks tree

Get Next Task

# Get next task to work on
task-o-matic tasks get-next

Execute Tasks

# Execute all todo tasks
task-o-matic tasks execute-loop --status todo

# Execute specific tasks
task-o-matic tasks execute-loop --ids 1,2,3

# With specific tool
task-o-matic tasks execute-loop --tool claude

# With planning phase
task-o-matic tasks execute-loop --plan --review-plan

# With verification
task-o-matic tasks execute-loop --verify "bun run test" --verify "bun run type-check"

# Progressive model escalation
task-o-matic tasks execute-loop --try-models "gpt-4o-mini,gpt-4o,claude:sonnet-4"

Options:

• --status <status>: Filter by status
• --tag <tag>: Filter by tag
• --ids <ids>: Comma-separated task IDs
• --tool <tool>: opencode/claude/gemini/codex (default: opencode)
• --max-retries <number>: Max retries per task (default: 3)
• --model <model>: Force specific model
• --verify <command>: Verification command (can be used multiple times)
• --plan: Generate implementation plan before execution
• --plan-model <model>: Model for planning
• --review-plan: Pause for human review of plan
• --review: Run AI review after execution
• --auto-commit: Auto-commit after each task
• --try-models <models>: Progressive models for retries
• --dry: Show what would execute

PRD Management

Create PRD from Description

task-o-matic prd create "Build a task management app with real-time updates"

Refine PRD with Questions

# Generate questions, answer interactively, refine PRD
task-o-matic prd refine --file prd.md --output prd_refined.md --stream

# Questions mode: AI generates clarifying questions
task-o-matic prd question --file prd.md

Combine PRDs

task-o-matic prd combine --files prd1.md,prd2.md --output master.md

Get Tech Stack Suggestion

task-o-matic prd get-stack --file prd.md

Interactive Workflow

The workflow command provides an all-in-one interactive experience:

# Full interactive workflow
task-o-matic workflow

# Skip specific steps
task-o-matic workflow --skip-bootstrap --skip-prd-question-refine

# Auto-accept all suggestions
task-o-matic workflow --auto-accept

# Use config file
task-o-matic workflow --config-file workflow-config.json

Workflow covers:

• Project initialization
• PRD creation/upload
• PRD question & refinement
• Task generation
• Task splitting
• Task execution

AI Providers

OpenRouter

task-o-matic config set-ai-provider openrouter xiaomi/mimo-v2-flash:free

Popular free models:

• xiaomi/mimo-v2-flash:free
• google/gemma-3-27b-it:free
• meta-llama/llama-3.3-8b-instruct:free

Anthropic

task-o-matic config set-ai-provider anthropic claude-3-5-sonnet-20241022

OpenAI

task-o-matic config set-ai-provider openai gpt-4o

Custom

task-o-matic config set-ai-provider custom https://api.example.com

Environment Variables

Set in .env file or environment:

AI_PROVIDER=openrouter
AI_MODEL=xiaomi/mimo-v2-flash:free
OPENROUTER_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

Project Structure

After initialization:

.task-o-matic/
├── config.json       # Project configuration
├── tasks.json        # Tasks database
├── prd.md            # PRD file
└── plans/            # Implementation plans

Best Practices

1. Always use `--stream` for long-running AI operations to see progress 2. Use `--ai-reasoning` with models that support it for better task breakdown 3. Filter by status when splitting/enhancing to avoid reprocessing completed tasks 4. Use `--dry` first for bulk operations to preview changes 5. Start with free models (OpenRouter free tier) before using paid models 6. Use `--verify` during execution to run tests after each task 7. Enable `--plan` for complex tasks to get implementation plans first

Example Session

# 1. Initialize
task-o-matic init init --project-name my-app --package-manager bun

# 2. Configure AI (optional if set in .env)
task-o-matic config set-ai-provider openrouter xiaomi/mimo-v2-flash:free

# 3. Parse PRD
task-o-matic prd parse --file prd.md --stream --ai-reasoning 4000

# 4. Review tasks
task-o-matic tasks tree

# 5. Split all tasks
task-o-matic tasks split --all --stream --ai-reasoning 4000

# 6. Enhance tasks with documentation
task-o-matic tasks enhance --all --stream

# 7. Execute
task-o-matic tasks execute-loop --status todo --verify "bun run test" --plan

Advanced Topics

Progressive Model Escalation

Use cheaper models first, escalate to better ones on failure:

task-o-matic tasks execute-loop \
  --try-models "xiaomi/mimo-v2-flash:free,gpt-4o-mini,claude:sonnet-4" \
  --max-retries 3

Planning Phase

Generate implementation plans before execution:

task-o-matic tasks execute-loop \
  --plan \
  --plan-model gpt-4o \
  --review-plan

Custom Verification

Run multiple verification commands:

task-o-matic tasks execute-loop \
  --verify "bun run type-check" \
  --verify "bun run test" \
  --verify "bun run lint"

See Also

• Complete Command Reference - Detailed command options
• Project README - Full project documentation
• Tutorial - Step-by-step guide

Task-O-Matic Complete Command Reference

Complete reference for all task-o-matic CLI commands and options.

Table of Contents

• init - Initialize projects
• config - Manage configuration
• prd - Manage PRDs
• tasks - Manage tasks
• workflow - Interactive workflow
• prompt - Build AI prompts
• install - Install documentation

---

init

Initialize task-o-matic project and bootstrap projects.

init init

Initialize a new task-o-matic project in the current directory.

task-o-matic init init [options]

Options:

Frontend options: next, native-bare, cli, etc. Backend options: convex, etc. CLI dependency levels: minimal, standard, full, task-o-matic

init bootstrap

Bootstrap a new project (web/native/cli).

task-o-matic init bootstrap [options] <name>

Arguments:

• name - Project name

init attach

Attach task-o-matic to an existing project with automatic stack detection.

task-o-matic init attach [options]

Options:

Stack Detection:

The command automatically detects:

• Language (TypeScript/JavaScript/Python/Go/Rust)
• Framework(s) (Next.js, Express, Hono, Vue, Svelte, etc.)
• Database (Postgres, MongoDB, SQLite, MySQL, Redis)
• ORM (Prisma, Drizzle, TypeORM, Mongoose)
• Auth (Better-Auth, Clerk, NextAuth, Auth0, Lucia)
• Package Manager (npm, pnpm, bun, yarn)
• Runtime (Node, Bun, Deno)
• API style (tRPC, GraphQL, REST, oRPC)
• Testing frameworks (Jest, Vitest, Mocha, Playwright)
• Build tools (Vite, Webpack, esbuild, Turborepo)

Created Files:

.task-o-matic/
├── config.json       # AI configuration
├── stack.json        # Cached stack detection (used by all AI operations)
├── mcp.json          # Context7 configuration
├── tasks/            # Task storage
├── prd/              # PRD storage
├── logs/             # Operation logs
└── docs/             # Documentation

Examples:

# Basic attach (auto-detect stack)
task-o-matic init attach

# With full analysis (TODOs, features, structure)
task-o-matic init attach --analyze

# Dry run to preview detection
task-o-matic init attach --dry-run

# Re-detect after stack changes
task-o-matic init attach --redetect

# With custom AI provider
task-o-matic init attach --ai-provider openrouter --ai-model anthropic/claude-3.5-sonnet

---

config

Manage task-o-matic configuration.

config get-ai-config

Get the current AI configuration.

task-o-matic config get-ai-config

config set-ai-provider

Set the AI provider and model.

task-o-matic config set-ai-provider <provider> [model]

Arguments:

• provider - AI provider (openrouter, anthropic, openai, custom URL)
• model - Model name (optional)

Examples:

task-o-matic config set-ai-provider openrouter xiaomi/mimo-v2-flash:free
task-o-matic config set-ai-provider anthropic claude-3-5-sonnet-20241022
task-o-matic config set-ai-provider custom https://api.example.com

config info

Get information about the current task-o-matic project.

task-o-matic config info

---

prd

Manage PRDs and generate tasks.

prd create

Generate PRD(s) from a product description.

task-o-matic prd create [options] <description>

Options:

prd generate

Generate a PRD from an existing codebase (reverse-engineering).

task-o-matic prd generate [options]

Options:

prd combine

Combine multiple PRD files into a master PRD.

task-o-matic prd combine [options]

Options:

prd parse

Parse a PRD file into structured tasks.

task-o-matic prd parse [options]

Options:

Examples:

# Basic parse
task-o-matic prd parse --file prd.md

# With streaming and reasoning
task-o-matic prd parse --file prd.md --stream --ai-reasoning 4000

# Multiple models
task-o-matic prd parse --file prd.md --ai openrouter:model1 openrouter:model2 --combine-ai openrouter:combine-model

prd rework

Rework a PRD based on user feedback.

task-o-matic prd rework [options]

Options:

prd question

Generate clarifying questions for a PRD.

task-o-matic prd question [options]

Options:

prd refine

Refine PRD by answering clarifying questions.

task-o-matic prd refine [options]

Options:

Interactive flow: 1. AI generates clarifying questions 2. User answers each question 3. AI refines PRD based on answers

prd get-stack

Suggest optimal technology stack based on PRD analysis.

task-o-matic prd get-stack [options]

Options:

---

tasks

Manage tasks.

tasks list

List all tasks.

task-o-matic tasks list [options]

Options:

tasks create

Create a new task with AI enhancement using Context7.

task-o-matic tasks create [options]

Options:

Examples:

# Manual creation
task-o-matic tasks create --title "Add auth" --content "Implement OAuth2"

# With AI enhancement
task-o-matic tasks create --title "Add auth" --ai-enhance --stream

tasks show

Show detailed information about a task.

task-o-matic tasks show [options]

Options:

tasks update

Update an existing task.

task-o-matic tasks update [options]

Options:

tasks delete

Delete a task.

task-o-matic tasks delete [options]

Options:

tasks status

Set task status.

task-o-matic tasks status [options]

Options:

Examples:

task-o-matic tasks status --task-id 1 --status in-progress
task-o-matic tasks status --task-id 1 --status completed

tasks add-tags

Add tags to a task.

task-o-matic tasks add-tags [options]

Options:

tasks remove-tags

Remove tags from a task.

task-o-matic tasks remove-tags [options]

Options:

tasks plan

Create detailed implementation plan for a task or subtask.

task-o-matic tasks plan [options]

Options:

tasks get-plan

View existing implementation plan for a task or subtask.

task-o-matic tasks get-plan [options]

Options:

tasks list-plan

List all available implementation plans.

task-o-matic tasks list-plan

tasks delete-plan

Delete implementation plan for a task.

task-o-matic tasks delete-plan [options]

Options:

tasks set-plan

Set implementation plan for a task.

task-o-matic tasks set-plan [options]

Options:

tasks enhance

Enhance an existing task with AI using Context7 documentation.

task-o-matic tasks enhance [options]

Options:

Examples:

# Enhance specific task
task-o-matic tasks enhance --task-id 1 --stream

# Enhance all todo tasks
task-o-matic tasks enhance --all --status todo --stream

# Dry run first
task-o-matic tasks enhance --all --dry

tasks split

Split a task into smaller subtasks using AI.

task-o-matic tasks split [options]

Options:

Examples:

# Split specific task
task-o-matic tasks split --task-id 1 --stream

# Split all tasks
task-o-matic tasks split --all --stream --reasoning 4000

# Dry run
task-o-matic tasks split --all --dry

tasks document

Analyze and fetch documentation for a task using AI with Context7.

task-o-matic tasks document [options]

Options:

tasks get-documentation

Get existing documentation for a task.

task-o-matic tasks get-documentation [options]

Options:

tasks add-documentation

Add documentation to a task from a file.

task-o-matic tasks add-documentation [options]

Options:

tasks execute

Execute a task using an external coding assistant.

task-o-matic tasks execute [options]

Options:

tasks execute-loop

Execute multiple tasks in a loop with retry logic and verification.

task-o-matic tasks execute-loop [options]

Options:

Examples:

# Execute all todo tasks
task-o-matic tasks execute-loop --status todo

# With verification
task-o-matic tasks execute-loop --verify "bun run test" --verify "bun run type-check"

# With planning and review
task-o-matic tasks execute-loop --plan --review-plan --review

# Progressive model escalation
task-o-matic tasks execute-loop --try-models "gpt-4o-mini,gpt-4o,claude:sonnet-4"

tasks subtasks

List subtasks for a task.

task-o-matic tasks subtasks [options]

Options:

tasks tree

Display hierarchical task tree.

task-o-matic tasks tree [options]

Options:

tasks get-next

Get the next task to work on (defaults to hierarchical order).

task-o-matic tasks get-next [options]

Options:

---

workflow

Interactive workflow for complete project setup and task management.

task-o-matic workflow [options]

Options:

---

prompt

Build AI service prompts with variable replacement for external tools.

task-o-matic prompt [options] [name]

Arguments:

• name - Prompt name

Options:

---

install

Install task-o-matic documentation and agent guides into current project.

task-o-matic install [options] <target>

Arguments:

• target - Installation target

Options:

---

Global Options

These options can be used with any command:

---

Environment Variables