Skip to content

README.md

Latest commit

 

History

History
1157 lines (848 loc) · 31.4 KB

README.md

File metadata and controls

1157 lines (848 loc) · 31.4 KB
Raw

Simple Task Master (STM)

npm version Node.js CI License: MIT

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

Installation

Global Installation (Recommended)

npm install -g simple-task-master

Using npx (No Installation)

npx simple-task-master init

Basic Usage

  1. Initialize a new task repository:

    stm init

  2. Add your first task:

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

  3. List all tasks:

    stm list

  4. View a specific task:

    stm show 1

  5. Update task status:

    stm update 1 --status=in-progress

📝 Task Structure

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

Section Purposes

  • 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

Example Task Structure

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

stm init

Initialize STM repository in the current directory.

# 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 <path>: Custom directory for storing task files (default: .simple-task-master/tasks/)

stm add <title>

Add a new task with the specified title.

# 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 <tags>: Comma-separated list of tags
  • --priority, -p <priority>: Task priority (low, medium, high)
  • --description, -d <description>: Task description
  • --due-date <date>: Due date (YYYY-MM-DD format)
  • --status, -s <status>: Initial status (pending, in-progress, done)

stm list

List tasks with optional filtering and formatting.

# 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 <status>: Filter by status (pending, in-progress, done)
  • --tags, -t <tags>: Filter by comma-separated tags
  • --search <query>: Search in task titles and descriptions

Output Options:

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

stm show <id>

Display detailed information about a specific task.

# Show task by ID
stm show 1

# Show with different formats
stm show 1 --format=json
stm show 1 --format=yaml

Options:

  • --format, -f <format>: Output format (default, json, yaml)

stm update <id>

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

Basic Property Updates

# 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

# 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

# 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

# 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

# Open task in editor when no changes specified
stm update 42

# Disable editor fallback
stm update 42 --no-editor

Combined Usage Examples

# 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 <title>: Update task title
  • --desc, -d <text>: Update description section (use - for stdin)
  • --details <text>: Update details section (use - for stdin)
  • --validation <text>: Update validation section (use - for stdin)
  • --status, -s <status>: Update status (pending, in-progress, done)
  • --tags <tags>: Set task tags (comma-separated)
  • --deps <dependencies>: Set task dependencies (comma-separated IDs)
  • --no-editor: Disable editor fallback when no changes are specified

Assignment Syntax:

  • key=value: Set field value
  • key+=value: Add to array fields (tags, dependencies)
  • key-=value: Remove from array fields (tags, dependencies)

Valid Fields for Assignments:

  • title: Task title
  • content: Full task content (markdown body)
  • status: Task status (pending, in-progress, done)
  • tags: Task tags (comma-separated for arrays)
  • dependencies: Task dependencies (comma-separated IDs)
  • desc: Description section content
  • details: Details section content
  • validation: Validation section content
  • Any custom field: You can add custom metadata fields for external tool integration

stm grep <pattern>

Search for tasks using regular expressions.

# Search in task content
stm grep "authentication"

# Case-insensitive search
stm grep -i "API"

# Search in specific fields
stm grep --field=title "user"
stm grep --field=description "implement"

# Different output formats
stm grep "bug" --format=json
stm grep "feature" --format=table

Options:

  • --case-insensitive, -i: Case-insensitive search
  • --field <field>: Search in specific field (title, description, tags)
  • --format, -f <format>: Output format (default, json, table)

stm export

Export tasks to various formats for reporting and analysis.

# Export all tasks to JSON
stm export --format=json > tasks.json

# Export to CSV
stm export --format=csv > tasks.csv

# Export filtered tasks
stm export --status=done --format=json > completed-tasks.json

# Export with specific fields
stm export --format=csv --fields=id,title,status,tags

Options:

  • --format, -f <format>: Export format (json, csv, md)
  • --status, -s <status>: Filter by status
  • --tags, -t <tags>: Filter by tags
  • --fields <fields>: Comma-separated fields to include in export

stm delete <id>

Delete a task permanently.

# Delete a task
stm delete 123

# Force delete (bypass dependency checks)
stm delete 123 --force

Note: Deletion is permanent. Tasks that depend on the deleted task may become invalid unless --force is used.

Options:

  • --force, -f: Force deletion even if other tasks depend on this task

stm config

View and modify Simple Task Master configuration settings.

# View all configuration
stm config --list

# Get specific configuration value
stm config --get tasksDir
stm config --get lockTimeoutMs
stm config --get maxTaskSizeBytes

# Change tasks directory
stm config --set tasksDir=docs/tasks

# Change lock timeout to 60 seconds
stm config --set lockTimeoutMs=60000

# Change max task size to 2MB
stm config --set maxTaskSizeBytes=2097152

# Reset individual configuration values to defaults
stm config --reset tasksDir
stm config --reset lockTimeoutMs

# Reset all configuration values to defaults
stm config --reset-all

Options:

  • --get <key>: Get a specific configuration value
  • --set <key=value>: Set a configuration value
  • --list: List all configuration values as JSON
  • --reset <key>: Reset a specific configuration value to its default
  • --reset-all: Reset all configuration values to defaults

Configuration Keys:

  • tasksDir: Directory where task files are stored (relative or absolute path)
  • lockTimeoutMs: Lock acquisition timeout in milliseconds (default: 30000)
  • maxTaskSizeBytes: Maximum task file size in bytes (default: 1048576)

Common Use Cases:

# Move tasks to a project-specific directory
stm config --set tasksDir=./project/tasks

# Increase timeout for slower systems
stm config --set lockTimeoutMs=60000

# Allow larger task files (e.g., 5MB)
stm config --set maxTaskSizeBytes=5242880

# Check current configuration
stm config --list

# Use in scripts
TASKS_DIR=$(stm config --get tasksDir)
echo "Tasks are stored in: $TASKS_DIR"

# Reset to defaults when switching projects
stm config --reset tasksDir        # Back to .simple-task-master/tasks
stm config --reset lockTimeoutMs   # Back to 30 seconds
stm config --reset-all             # Reset everything to defaults

⚙️ Configuration

STM stores its configuration in .simple-task-master/config.json. You can view and modify these settings using the config command or by editing the JSON file directly.

Using the Config Command

The config command provides a safe way to view and modify configuration without manually editing JSON:

# View current configuration
stm config --list

# Get a specific value
stm config --get tasksDir

# Change a setting
stm config --set lockTimeoutMs=45000

# Reset settings to defaults
stm config --reset tasksDir
stm config --reset-all

Configuration File Format

{
  "schema": 1,
  "lockTimeoutMs": 30000,
  "maxTaskSizeBytes": 1048576,
  "tasksDir": "./my-tasks"
}

Configuration Options

tasksDir (string)

Directory where task files are stored. Can be relative or absolute path.

  • Default: .simple-task-master/tasks/
  • Valid values: Any valid directory path within the project
  • Restrictions:
    • Cannot use system directories (/etc, /usr, etc.)
    • Cannot contain path traversal sequences (..)
    • Must be within the project directory if absolute

Examples:

# Use a project-specific directory
stm config --set tasksDir=./todos

# Use a nested structure
stm config --set tasksDir=./docs/project-tasks

# Check current value
stm config --get tasksDir

lockTimeoutMs (number)

Maximum time in milliseconds to wait for acquiring a file lock. Prevents indefinite waiting when another process is accessing task files.

  • Default: 30000 (30 seconds)
  • Valid values: Positive integer
  • Recommended range: 5000-120000 (5-120 seconds)

Examples:

# Increase for slower systems or network drives
stm config --set lockTimeoutMs=60000

# Decrease for faster failure detection
stm config --set lockTimeoutMs=10000

maxTaskSizeBytes (number)

Maximum allowed size for a single task file in bytes. Prevents excessive memory usage and ensures reasonable performance.

  • Default: 1048576 (1 MB)
  • Valid values: Positive integer
  • Recommended range: 10240-10485760 (10 KB - 10 MB)

Examples:

# Allow larger tasks (2 MB)
stm config --set maxTaskSizeBytes=2097152

# Allow very large tasks (5 MB)
stm config --set maxTaskSizeBytes=5242880

# Common sizes:
# 512 KB = 524288
# 1 MB   = 1048576 (default)
# 2 MB   = 2097152
# 5 MB   = 5242880
# 10 MB  = 10485760

Validation Rules

The config command validates all settings before saving:

  • tasksDir:

    • Must be a valid path format
    • Cannot contain system directory paths
    • Cannot use path traversal (../)
    • Shows warning if changing with existing tasks

  • lockTimeoutMs:

    • Must be a positive integer
    • Values below 1000 (1 second) are not recommended
    • Very high values may cause long waits

  • maxTaskSizeBytes:

    • Must be a positive integer
    • Values below 1024 (1 KB) are not practical
    • Consider system memory when setting high values

Custom Task Directory

By default, STM stores tasks in .simple-task-master/tasks/. However, you can configure a custom directory for task storage, which is useful for:

  • Organizing tasks in a project-specific location
  • Separating tasks from the STM configuration
  • Using existing directories for task management
  • Following your team's directory structure conventions

Setting Up a Custom Task Directory

Option 1: Initialize with a custom directory

# Use a relative path (recommended)
stm init --tasks-dir ./project-tasks

# Use a nested directory structure
stm init --tasks-dir ./docs/tasks

# Initialize in an existing directory
stm init --tasks-dir ./existing-tasks-folder

Option 2: Modify config.json after initialization

{
  "schema": 1,
  "lockTimeoutMs": 30000,
  "maxTaskSizeBytes": 1048576,
  "tasksDir": "./my-custom-tasks"
}

Examples

# Initialize with tasks in a 'todo' directory
stm init --tasks-dir ./todo

# Initialize with tasks in a documentation folder
stm init --tasks-dir ./docs/project-tasks

# Initialize with deeply nested structure
stm init --tasks-dir ./project/management/tasks

Important Considerations

  1. Relative vs Absolute Paths

    • Relative paths (recommended): Portable across different systems and users
    • Absolute paths: Must be within the project directory for security

  2. Git Integration

    • STM automatically updates .gitignore to exclude task files
    • The pattern added depends on your custom directory
    • Config file remains tracked for team synchronization

  3. Migration Guide

    If you have an existing STM workspace and want to move tasks to a custom directory:

    # 1. Move existing tasks to the new location
mv .simple-task-master/tasks ./my-tasks

# 2. Update config.json
# Add: "tasksDir": "./my-tasks"

# 3. Update .gitignore
# Replace: .simple-task-master/tasks/
# With: my-tasks/

  4. Limitations

    • Custom directories cannot be inside .simple-task-master/
    • System directories (/etc, /usr, etc.) are not allowed
    • Directory traversal sequences (..) in paths are blocked
    • Absolute paths must be within the current project

📁 File Structure

Default Structure:

project-root/
├── .simple-task-master/
│   ├── config.json          # STM configuration
│   ├── tasks/               # Default task files directory
│   │   ├── 1-task-title.md  # Individual task files
│   │   ├── 2-another-task.md
│   │   └── ...
│   └── lock                 # Lock file (temporary)
└── .gitignore               # Updated to exclude tasks/

With Custom Task Directory:

project-root/
├── .simple-task-master/
│   ├── config.json          # Contains "tasksDir": "./my-tasks"
│   └── lock                 # Lock file (temporary)
├── my-tasks/                # Custom task directory
│   ├── 1-task-title.md      # Individual task files
│   ├── 2-another-task.md
│   └── ...
└── .gitignore               # Updated to exclude my-tasks/

Task File Format

Each task is stored as a markdown file with YAML frontmatter:

---
id: 1
title: 'Implement user authentication'
status: 'pending'
priority: 'high'
tags:
  - backend
  - security
created: '2024-01-15T10:30:00.000Z'
updated: '2024-01-15T10:30:00.000Z'
dueDate: '2024-01-31'
# Custom fields (added by external tools or workflows)
external_id: 'JIRA-456'
sprint: '2024-Q1-Sprint-2'
story_points: 8
---

# Implement user authentication

## Description

Create a secure authentication system using JWT tokens.

## Requirements

- [ ] Password hashing with bcrypt
- [ ] JWT token generation
- [ ] Login/logout endpoints
- [ ] Password reset functionality

## Notes

Research industry best practices for session management.

💡 Usage Examples

Daily Workflow

# Start your day by checking pending tasks
stm list --status=pending --pretty

# Add a new urgent task
stm add "Fix critical production bug" --tags=urgent,bugfix --priority=high

# Start working on a task and add implementation notes
stm update 5 status=in-progress --details "Started debugging the authentication flow"

# Update progress with detailed validation checks
stm update 5 --validation - << 'EOF'
✓ Reproduced the issue locally
✓ Identified root cause in JWT validation
⏳ Working on fix implementation
EOF

# Complete the task with final validation
npm test | stm update 5 status=done --validation -

# Review completed work
stm list --status=done --format=table

Project Management

# Add feature tasks with tags
stm add "Design user dashboard" --tags=frontend,design --priority=medium
stm add "Implement user API" --tags=backend,api --priority=high
stm add "Write unit tests" --tags=testing --priority=medium

# Start working on API implementation with detailed plan
stm update 2 status=in-progress --details "## Implementation Plan
- Design REST endpoints
- Set up authentication middleware
- Implement CRUD operations
- Add input validation"

# Update progress with specific validation criteria
stm update 2 --validation "## Acceptance Criteria
- [ ] All endpoints documented in OpenAPI
- [ ] Authentication tests pass
- [ ] Error handling implemented
- [ ] Performance benchmarks met"

# Add urgent tag when priorities change
stm update 2 tags+=urgent

# Complete with comprehensive validation results
stm update 2 status=done --validation "## Final Validation
✓ All endpoints implemented and tested
✓ API documentation updated
✓ Security review completed
✓ Performance tests: avg 45ms response time
✓ Integration tests: 100% passing"

# Track frontend work
stm list --tags=frontend --pretty

# Export project status
stm export --format=csv > project-status.csv

Advanced Update Patterns

# Automated testing workflow with piped results
npm run test:unit | stm update 15 --validation -
npm run test:integration | stm update 15 --validation -

# Code review workflow
stm update 23 --desc "Feature implementation complete" --validation "✓ Code review requested"

# CI/CD integration - update from build results
if npm run build; then
  stm update 18 status=done --validation "✓ Build successful: $(date)"
else
  stm update 18 --validation "❌ Build failed: $(date)"
fi

# Multi-step task progression with section updates
stm update 31 status=in-progress --desc "Starting phase 1: Requirements gathering"
stm update 31 --details "$(cat requirements.md)"
stm update 31 --validation "✓ Requirements approved by stakeholders"

# Batch updates with assignment syntax
stm update 42 status=done tags+=completed,released desc="Feature deployed to production"

# Editor-based updates for complex content
stm update 55  # Opens editor for detailed content editing

# Dependency management with array operations
stm update 60 deps+=45,46  # Add dependencies
stm update 60 deps-=32     # Remove dependency

# Documentation sync from external sources
curl -s https://api.example.com/spec | stm update 67 --details -
cat design-notes.md | stm update 67 --desc -

Team Coordination

# Export tasks for team review
stm export --status=pending --format=json > pending-tasks.json

# Find tasks by keyword
stm grep "authentication" --format=table

# Track progress by status
echo "Pending: $(stm list --status=pending --format=json | jq length)"
echo "In Progress: $(stm list --status=in-progress --format=json | jq length)"
echo "Done: $(stm list --status=done --format=json | jq length)"

Configuration Management

# Check current configuration
stm config --list

# Adjust settings for your workflow
stm config --set tasksDir=./project-tasks
stm config --set maxTaskSizeBytes=2097152  # 2MB for detailed tasks

# Use configuration in scripts
TASK_DIR=$(stm config --get tasksDir)
MAX_SIZE=$(stm config --get maxTaskSizeBytes)
echo "Tasks stored in: $TASK_DIR (max size: $MAX_SIZE bytes)"

# Backup configuration before changes
stm config --list > config-backup.json

# Verify changes took effect
stm config --get tasksDir
ls -la $(stm config --get tasksDir)

Custom Metadata Fields

STM allows you to add custom metadata fields to tasks, enabling seamless integration with external tools and workflows:

# Add custom fields for external tool integration
stm update 42 external_id="JIRA-1234" priority="P1"

# Track AutoAgent execution metadata
stm update 56 agent_id="agent-123" execution_time="45s" success=true

# Add project management metadata
stm update 78 sprint="2024-Q1-Sprint-3" story_points=5 assignee="john.doe"

# Complex metadata with JSON values
stm update 90 metadata='{"tool":"vscode","extensions":["prettier","eslint"]}'

# View tasks with custom fields (shown in JSON output)
stm show 42 --format=json
# Output includes all fields, both core and custom

# Export with custom fields preserved
stm export --format=json > tasks-with-metadata.json

Custom fields are:

  • Preserved: Maintained through all operations (create, update, show, export)
  • Flexible: Accept any valid string value
  • Tool-friendly: Enable external tools to store their own metadata
  • Non-validated: STM doesn't validate custom field values (tools manage their own data)

🔧 Development

Prerequisites

  • Node.js >= 18.0.0
  • npm or yarn

Setup

# Clone the repository
git clone https://github.com/your-username/simple-task-master.git
cd simple-task-master

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

Available Scripts

  • npm run build - Compile TypeScript to JavaScript
  • npm run dev - Run in development mode with ts-node
  • npm test - Run all tests (excludes performance tests)
  • npm run test:all - Run ALL tests including performance
  • npm run test:unit - Run unit tests only
  • npm run test:integration - Run integration tests only
  • npm run test:e2e - Run end-to-end tests only
  • npm run test:performance - Run performance benchmarks (~3 min)
  • npm run test:coverage - Run tests with coverage report
  • npm run lint - Lint code with ESLint (includes formatting rules)
  • npm run lint:fix - Auto-fix linting and formatting issues
  • npm run typecheck - Type check with TypeScript

Testing

STM has comprehensive test coverage across three levels:

  1. Unit Tests: Test individual functions and classes
  2. Integration Tests: Test command interactions and file system operations
  3. E2E Tests: Test complete CLI workflows
# Run specific test suites
npm run test:unit
npm run test:integration
npm run test:e2e

# Run with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Project Structure

src/
├── cli.ts                 # Main CLI entry point
├── commands/              # Command implementations
│   ├── add.ts
│   ├── export.ts
│   ├── grep.ts
│   ├── init.ts
│   ├── list.ts
│   ├── show.ts
│   └── update.ts
├── lib/                   # Core library code
│   ├── constants.ts       # Application constants
│   ├── errors.ts          # Error classes
│   ├── lock-manager.ts    # File locking
│   ├── output.ts          # Output formatting
│   ├── schema.ts          # Validation schemas
│   ├── task-manager.ts    # Task CRUD operations
│   ├── types.ts           # Type definitions
│   └── utils.ts           # Utility functions
└── types/                 # TypeScript type definitions
    └── index.ts

📊 Performance

STM is optimized for performance with the following characteristics:

  • Task Loading: < 50ms for 1000+ tasks
  • Search Operations: < 100ms across 10,000+ tasks
  • File Operations: Atomic writes with proper locking
  • Memory Usage: ~10MB baseline, scales linearly with task count
  • Concurrent Safety: File-level locking prevents corruption

Limitations

  • Maximum task file size: 1MB (configurable)
  • Recommended maximum tasks: 50,000 per repository
  • Lock timeout: 30 seconds (configurable)
  • Node.js requirement: >= 18.0.0

📚 API Behavior for Custom Fields

STM's API allows custom metadata fields in task frontmatter, enabling external tools to extend tasks with their own data:

Field Validation Behavior

Core Fields (strictly validated):

  • id, title, status, created, updated: Required with specific types
  • tags, dependencies: Optional arrays with validation
  • priority, dueDate: Optional with format validation

Custom Fields (flexibly handled):

  • Any field name: Allowed except those containing newlines or control characters
  • Any value type: Stored as-is without validation
  • Preservation: Maintained through all operations (create, update, list, show, export)
  • No STM validation: External tools manage their own field semantics

Integration Guidelines

When integrating with STM:

  1. Choose unique field names: Prefix with your tool name (e.g., jira_id, github_issue)
  2. Handle your own validation: STM won't validate custom field values
  3. Use consistent formats: Maintain your data format across operations
  4. Document your fields: Let users know what custom fields your tool adds

Example Integration

// External tool adding custom metadata
const task = {
  title: 'Implement feature',
  status: 'pending',
  // Custom fields for integration
  jira_id: 'PROJ-123',
  github_pr: 456,
  ci_status: 'passing',
  metrics: {
    complexity: 'high',
    estimated_hours: 8
  }
};

// STM preserves all custom fields
const updated = await taskManager.create(task);
console.log(updated.jira_id); // 'PROJ-123'
console.log(updated.metrics); // { complexity: 'high', estimated_hours: 8 }

🔒 Security

STM implements several security measures:

  • Input validation: All user inputs are validated and sanitized
  • File path validation: Prevents directory traversal attacks
  • Safe file operations: Uses atomic writes to prevent corruption
  • No remote connections: All data stays local to your machine
  • Minimal dependencies: Reduces attack surface

🤝 Contributing

We welcome contributions! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes and add tests
  4. Ensure all tests pass: npm test
  5. Lint your code: npm run lint
  6. Commit your changes: git commit -m 'feat: add amazing feature'
  7. Push to the branch: git push origin feature/amazing-feature
  8. Open a Pull Request

Commit Convention

This project uses Conventional Commits:

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • style: Code style changes
  • refactor: Code refactoring
  • test: Test changes
  • chore: Build process or auxiliary tool changes

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋 Support

Made with ❤️ for developers who love the command line