Simple Task Master (STM)


A powerful, lightweight command-line task management tool built for developers who prefer markdown files over complex project management systems. STM stores tasks as individual markdown files with YAML frontmatter, making them both human-readable and version control friendly.

✨ Features

- 📝 Markdown-based tasks: Each task is stored as a readable markdown file
- 🏷️ Flexible tagging system: Organize tasks with multiple tags
- 🔍 Powerful search: Find tasks by content, title, tags, or status
- 📊 Multiple output formats: JSON, table, CSV, or pretty-printed views
- 🔒 Safe concurrent access: Built-in file locking prevents data corruption
- ⚡ Fast performance: Optimized for handling thousands of tasks
- 🎯 Simple workflow: Initialize, add, list, update - that's it!
- 🔄 Export capabilities: Export tasks to various formats for reporting
- 🔧 Custom metadata fields: Add any custom fields for external tool integration
- ⚙️ Flexible configuration: Configurable task directories and runtime settings with reset capabilities

🚀 Quick Start

$3

#### Global Installation (Recommended)

``bash
npm install -g simple-task-master
`

#### Using npx (No Installation)

`bash
npx simple-task-master init
`

$3

1. Initialize a new task repository:

`bash
stm init
`

2. Add your first task:

`bash
stm add "Implement user authentication" --tags=backend,security --priority=high
`

3. List all tasks:

`bash
stm list
`

4. View a specific task:

`bash
stm show 1
`

5. Update task status:
`bash
stm update 1 --status=in-progress
`

📝 Task Structure

STM tasks use three main content sections to organize information clearly:

$3

- Description (--description): Why & What
- Problem context and background
- Solution overview and approach
- Acceptance criteria and definition of done

- Details (--details): How
- Implementation approach and technical design
- Architecture notes and design decisions
- Step-by-step implementation plan

- Validation (--validation): Quality Assurance
- Testing strategy and approach
- Verification steps and quality checks
- Manual testing procedures and checklists

$3

`markdown
---
id: 1
title: 'Implement user authentication'
status: 'pending'
---

Implement user authentication

Description

Problem: Users currently cannot securely access the application.

Solution: Implement JWT-based authentication with secure password handling.

Acceptance Criteria:
- [ ] Users can register with email/password
- [ ] Users can login and receive JWT tokens
- [ ] Protected routes require valid tokens
- [ ] Passwords are securely hashed

Details

Implementation approach:
- Use bcrypt for password hashing (salt rounds: 12)
- JWT tokens with 24-hour expiration
- Express middleware for route protection
- Database schema: users table with email, password_hash, created_at

Architecture:
- auth.ts: Core authentication logic
- middleware/auth.ts: Route protection
- routes/auth.ts: Login/register endpoints

Validation

Testing strategy:
- Unit tests for password hashing/verification
- Integration tests for auth endpoints
- E2E tests for complete login flow

Manual verification:
- [ ] Register new user via API
- [ ] Login returns valid JWT
- [ ] Protected routes reject invalid tokens
- [ ] Password reset flow works end-to-end
`

📖 Command Reference

$3

Initialize STM repository in the current directory.

`bash


Initialize with default settings

stm init

Initialize with custom task directory

stm init --tasks-dir ./my-tasks
`

Creates:

- .simple-task-master/ directory
- config.json configuration file
- tasks/ directory (or your custom directory)
- Updates .gitignore to exclude task files but include config

Options:

- --tasks-dir : Custom directory for storing task files (default: .simple-task-master/tasks/)

$3

Add a new task with the specified title.

`bash


Basic task

stm add "Fix login bug"

Task with tags and priority

stm add "Implement dashboard" --tags=frontend,ui --priority=high

Task with description

stm add "Update documentation" --description="Update API docs and examples"

Task with due date

stm add "Deploy to production" --due-date="2024-12-31"
`

Options:

- --tags, -t : Comma-separated list of tags
- --priority, -p : Task priority (low, medium, high)
- --description, -d : Task description
- --due-date : Due date (YYYY-MM-DD format)
- --status, -s : Initial status (pending, in-progress, done)

$3

List tasks with optional filtering and formatting.

`bash


List all tasks

stm list

Filter by status

stm list --status=pending
stm list --status=in-progress
stm list --status=done

Filter by tags

stm list --tags=frontend,ui
stm list --tags=backend

Search in task content

stm list --search="authentication"

Combine filters

stm list --status=pending --tags=backend --search="API"

Different output formats

stm list --format=json
stm list --format=csv
stm list --format=table
stm list --pretty # Enhanced pretty-printing
`

Filtering Options:

- --status, -s : Filter by status (pending, in-progress, done)
- --tags, -t : Filter by comma-separated tags
- --search : Search in task titles and descriptions

Output Options:

- --format, -f : Output format (json, table, csv)
- --pretty, -p: Enable pretty-printing with colors and formatting

$3

Display detailed information about a specific task.

`bash


Show task by ID

stm show 1

Show with different formats

stm show 1 --format=json
stm show 1 --format=yaml
`

Options:

- --format, -f : Output format (default, json, yaml)

$3

Update an existing task's properties with flexible options for metadata, content sections, and editor integration.

#### Basic Property Updates

`bash


Update status

stm update 1 --status=done

Update title

stm update 1 --title="New task title"

Update tags

stm update 1 --tags=urgent,backend,security
`

#### Section-Specific Updates

`bash


Update description section directly

stm update 42 --desc "Revised task description with new requirements"

Update details section with multi-line content

stm update 42 --details "## Implementation Notes
- Use TypeScript for type safety
- Add comprehensive error handling
- Include unit tests"

Update validation section

stm update 42 --validation "✓ All tests pass
✓ Code review completed
✓ Manual QA approved"
`

#### Stdin Input Support

`bash


Pipe content to description section

echo "New description from command output" | stm update 42 --desc -

Pipe test results to validation section

npm test | stm update 42 --validation -

Use complex piping with other tools

curl -s api.example.com/requirements | stm update 42 --details -

Multi-line input using heredoc

stm update 42 --validation - << 'EOF'
✓ Unit tests: 45/45 passing
✓ Integration tests: 12/12 passing
✓ Performance benchmarks within limits
✓ Security scan: no vulnerabilities
EOF
`

#### Key=Value Assignment Syntax

`bash


Basic assignments

stm update 42 status=done title="Completed feature implementation"

Content section assignments

stm update 42 desc="Updated description" details="New implementation details"

Array operations - adding tags

stm update 42 tags+=security,performance

Array operations - removing tags

stm update 42 tags-=deprecated,old

Multiple mixed operations

stm update 42 status=in-progress tags+=urgent desc="High priority update"
`

#### Editor Integration

`bash


Open task in editor when no changes specified

stm update 42

Disable editor fallback

stm update 42 --no-editor
`

#### Combined Usage Examples

`bash


Update metadata and add validation results

stm update 42 status=done --validation "✓ All tests pass
✓ Manual QA complete"

Update multiple sections with different input methods

stm update 42 --desc "Updated requirements" details="$(cat implementation-notes.md)"

Complex workflow with piped validation

npm run test:full | stm update 42 status=done --validation -

Batch update with assignment syntax

stm update 42 status=in-progress tags+=urgent,hotfix desc="Critical bug fix in progress"
`

Options:

- --title, -t