Task Patterns (tp)

Lightning-fast task management for AI-human collaborative development

Task Patterns is a CLI tool that brings joy to task management. Built for developers who work with AI assistants, it provides instant task capture, smart context switching, and celebration of progress—all from your terminal.

✨ Why Task Patterns?

Working with AI on code? You need a task system that:

• Captures tasks instantly - No context switching, no browser tabs
• Shows what matters - Your current work, not everything
• Celebrates progress - Because shipping code should feel good
• Works anywhere - Local configs follow your projects

🚀 Quick Start

# Install globally
npm install -g @pattern-stack/task-patterns

# Or clone and link
git clone https://github.com/pattern-stack/task-patterns.git
cd task-patterns
npm install && npm link

# Configure (one-time)
export LINEAR_API_KEY=lin_api_xxx  # Add to ~/.zshrc or ~/.bashrc
tp config init                     # Initialize local project config

🎯 Core Commands

# What am I working on?
tp context              # Shows your current sprint at a glance

# Capture a task (stay in flow)
tp add "Fix auth bug"   # Creates task instantly

# Work on something
tp working TASK-19      # Marks as in progress
tp done TASK-19         # Complete with celebration! 🎉

# Get details when needed
tp show TASK-19         # Full issue details
tp update TASK-19 --status "In Review"

# Manage labels
tp update TASK-19 --add-labels "Bug,Refactor"
tp update TASK-19 --list-labels    # See available labels

🏗️ Configuration

Task Patterns uses a hierarchical configuration system:

Project Config (.tp/config.json)

Each project can have its own settings:

tp config init                    # Create .tp/config.json
tp config teams TASK TECH         # Set team filters for this project
tp config set defaultTeam TASK    # Set default team for new tasks

Global Config (~/.task-pattern/config.json)

User preferences that apply everywhere:

tp config set --global backend linear  # Choose task backend

Environment Variables

LINEAR_API_KEY=lin_api_xxx       # Required for Linear
LINEAR_WORKSPACE_ID=xxx           # Optional workspace

Priority: Local project → Global user → Environment variables

🎨 Smart Features

Team Filtering

Focus on what's relevant:

tp config teams TASK TECH    # Only see TASK and TECH team issues
tp context                   # Now shows filtered view

Interactive Configuration

No more remembering flags:

tp config set defaultTeam TASK
# Prompts: "Save to project or global config?"
# Choose with arrow keys - easy!

Project-Aware

Your settings follow your code:

cd ~/projects/auth-service
tp config init && tp config teams AUTH
# This project now only shows AUTH team tasks

cd ~/projects/frontend
tp config init && tp config teams FE
# This project only shows FE team tasks

Label Management

Smart label assignment with fuzzy matching:

# See available labels
tp update TASK-19 --list-labels

# Add labels (by name or ID)
tp update TASK-19 --add-labels "Bug,Refactor"

# Remove labels
tp update TASK-19 --remove-labels "Testing"

# Replace all labels
tp update TASK-19 --set-labels "Task,CLI,Features"

# Typo? Get suggestions!
tp update TASK-19 --add-labels "Bugg"
# ✗ Label not found: Bugg
#   Did you mean: Bug

Label Groups: Linear uses exclusive label groups - you can only have one label per group on an issue. See docs/LINEAR_LABEL_GROUPS.md for details.

📁 Architecture

Built with Atomic Architecture for maintainability:

src/
├── atoms/       # Foundation (config, client, types)
├── features/    # Service layer (Linear SDK wrapper)
├── molecules/   # Business logic (entities, workflows)
└── organisms/   # User interfaces (CLI commands)

Key Files:

• bin/tp.js - CLI entry point
• src/organisms/cli/index.ts - Command definitions
• src/atoms/config/ - Configuration system
• .tp/config.json - Your project settings

🔌 Extensibility

Current Backend

• ✅ Linear - Full support with GraphQL API

Planned Backends

• 🚧 GitHub Issues
• 🚧 Jira
• 🚧 Custom APIs

The architecture supports any backend through consistent interfaces.

🧪 Development

# Setup
npm install
npm run build

# Development
npm run dev             # Watch mode
npm test               # Run tests
npm run verify         # Full check (lint, type, test)

# Testing
npm run test:watch     # TDD mode
npm run test:coverage  # Coverage report

Using tp While Developing

npm link               # Link globally
tp context            # Use anywhere

# Or run directly
npm run cli context   # Without global install

📚 Documentation

• CLAUDE.md - AI assistant instructions
• docs/ - Architecture, testing, and technical documentation
• .claude/tickets/ - Development tickets

🤝 Contributing

We welcome contributions! Please:

1. Use tp to track your work
2. Follow TDD practices (see .claude/tickets/TDD-GUIDELINES.md)
3. Run npm run verify before committing
4. Tag commits with issue numbers (e.g., [TASK-19])

📜 License

MIT

Built with ❤️ for developers who ship with AI