### Local Installation and Help

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Instructions for installing TaskWerk globally via npm and accessing its help documentation.

```bash
npm install -g taskwerk
task --help
```

--------------------------------

### Using System Prompts for Context

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Shows how to provide system-level instructions or context to the LLM using the `--system` flag. This helps guide the AI's persona and behavior.

```bash
taskwerk llm "Review this code" --system "You are a senior software engineer"
```

```bash
taskwerk llm "Analyze this algorithm" --system "You are a computer science professor"
```

--------------------------------

### Taskwerk CLI Help Example

Source: https://github.com/taisoai/taskwerk/blob/main/docs/v0.7.0-plan.md

Demonstrates the expected output format for Taskwerk's help command, including usage, options, and practical examples for adding tasks with descriptions and priorities.

```APIDOC
twrk addtask --help
Usage: taskwerk addtask [options] <name>

Add a new task

Options:
  -d, --description <desc>  Task description
  -p, --priority <level>    Priority (low, medium, high, critical)
  -a, --assignee <name>     Assign to someone

Examples:
  $ twrk addtask "Fix login bug"
  $ twrk addtask "Update docs" -p high -a @john
  $ twrk addtask "Refactor API" -d "Clean up REST endpoints"
```

--------------------------------

### Taskwerk CLI Installation and Initialization

Source: https://github.com/taisoai/taskwerk/blob/main/README.md

This snippet demonstrates how to install the taskwerk command-line interface globally using npm and then initialize a new project or task. It covers the basic steps to get started with the tool for intelligent task management.

```bash
npm install -g taskwerk
taskwerk init
taskwerk ask "What should I build today?"

```

--------------------------------

### Advanced LLM Workflows

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Presents advanced examples combining `taskwerk llm` with other tools and commands for tasks like code review, commit message generation, documentation, and test case creation.

```bash
git diff | taskwerk llm "Review this code change" --system "Focus on security issues"
```

```bash
git diff --staged | taskwerk llm "Generate a commit message for these changes"
```

```bash
taskwerk export --format json | taskwerk llm "Identify bottlenecks in this project"
```

```bash
cat src/api.js | taskwerk llm "Generate API documentation in markdown"
```

```bash
cat src/function.js | taskwerk llm "Generate unit tests for this function"
```

```bash
taskwerk llm "Translate to Spanish: {text}" --params text="Hello, how are you?"
```

```bash
cat email-template.txt | taskwerk llm --params name="John" subject="Project Update"
```

--------------------------------

### Taskwerk Ask Command Examples

Source: https://github.com/taisoai/taskwerk/blob/main/dev/v0.6-ai-implementation-plan.md

Demonstrates task-aware and analytical queries using the 'taskwerk ask' command.

```APIDOC
taskwerk ask "<query>"
  Performs task-aware or analytical queries against the Taskwerk system.

  Examples:
    # Task-aware queries:
    taskwerk ask "What tasks are blocked?"
    taskwerk ask "Summarize this week's progress"
    taskwerk ask "Which tasks have no assignee?"

    # Analysis queries:
    taskwerk ask "What's the critical path for PROJECT-001?"
    taskwerk ask "Estimate completion time for all in-progress tasks"
```

--------------------------------

### Basic LLM Prompt

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Demonstrates sending a simple, direct prompt to the LLM. This is the most basic way to interact with the command.

```bash
taskwerk llm "What is the capital of France?"
```

```bash
taskwerk llm What is the meaning of life?
```

--------------------------------

### Table Formatting Example

Source: https://github.com/taisoai/taskwerk/blob/main/docs/v0.7.0-plan.md

An example demonstrating how task data can be formatted into a human-readable table, suitable for markdown or terminal display.

```text
ID        Status    Priority  Task                          Created     Assignee
--------- --------- --------- ----------------------------- ----------- --------
TASK-001  ⏳ Todo   🟡 Med    Fix login bug                2025-07-15  @john
TASK-002  🔄 Prog   🔴 High   Update API documentation     2025-07-14  @jane
TASK-003  ✅ Done   🟡 Med    Setup CI/CD pipeline         2025-07-13  @bob
```

--------------------------------

### AI Configuration and Testing

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Provides commands for checking the AI configuration, testing the connection to the configured AI provider, and choosing an AI provider if none is set.

```bash
taskwerk aiconfig --show
```

```bash
taskwerk aiconfig --test
```

```bash
taskwerk aiconfig --choose
```

--------------------------------

### Combining LLM with Other Taskwerk Commands

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Illustrates how to pipe the output of other `taskwerk` commands into the `llm` command for analysis, summarization, or further processing, and how to import LLM-generated content.

```bash
taskwerk list --status done --format json | taskwerk llm "Write a progress report"
```

```bash
taskwerk llm "Create 5 subtasks for: implement user authentication" --raw | taskwerk import -
```

```bash
taskwerk export --format json --with-metadata | taskwerk llm "Identify critical path"
```

--------------------------------

### Continuous Integration Pipeline

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Commands to execute in CI/CD pipelines for a clean installation and full validation of the project before deployment.

```bash
# Complete validation pipeline
npm ci                    # Clean install
npm run make-release-dry-run  # Full validation
```

--------------------------------

### Including Task Context

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Demonstrates how to include the current task context or workload analysis when prompting the LLM using the `--context-tasks` flag.

```bash
taskwerk llm "What should I work on next?" --context-tasks
```

```bash
taskwerk llm "Analyze my current workload" --context-tasks
```

--------------------------------

### Build and Run Taskwerk Project

Source: https://github.com/taisoai/taskwerk/blob/main/README.md

Instructions for cloning the taskwerk repository, installing dependencies, running tests, and building the project for development or production.

```bash
git clone https://github.com/TaisoAI/taskwerk.git
cd taskwerk
npm install
npm test
npm run dev -- list
npm run build
```

--------------------------------

### Reading Prompt from File

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Demonstrates using the `--file` option to provide a prompt that is stored in a text file. This is ideal for longer or more complex prompts.

```bash
taskwerk llm --file long-prompt.txt
```

--------------------------------

### Taskwerk Agent Mode Examples

Source: https://github.com/taisoai/taskwerk/blob/main/dev/v0.6-ai-implementation-plan.md

Illustrates potential usage scenarios for an interactive 'taskwerk agent' mode for planning, execution, and review.

```APIDOC
taskwerk agent <mode> [arguments]
  Interacts with an AI agent for various workflow assistance.

  Modes:
    plan <task_description>
      Initiates interactive planning for a given task.
      Example: taskwerk agent plan "Implement user authentication"

    work <task_id>
      Provides task execution assistance for a specific task.
      Example: taskwerk agent work TASK-001

    review [--branch <branch_name>]
      Enters a review mode, potentially analyzing code branches.
      Example: taskwerk agent review --branch feature/auth
```

--------------------------------

### Install Taskwerk CLI

Source: https://github.com/taisoai/taskwerk/blob/main/README.md

Install the Taskwerk CLI globally using npm or run it directly with npx without installation.

```bash
# Install globally via npm
npm install -g taskwerk

# Or use npx (no installation required)
npx taskwerk init
```

--------------------------------

### Verify Node.js Version

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Command to check the currently installed Node.js version, essential for ensuring environment compatibility.

```bash
node --version
```

--------------------------------

### Parameter Substitution in Prompts

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Explains how to use placeholder variables within prompts and provide their values using the `--params` flag. This allows for dynamic and reusable prompt templates.

```bash
taskwerk llm "Explain {topic} in simple terms" --params topic="machine learning"
```

```bash
taskwerk llm "Compare {lang1} and {lang2}" --params lang1=Python lang2=JavaScript
```

```bash
taskwerk llm "Review this {type}" --params type="pull request"
```

--------------------------------

### taskwerk Minified Build Details

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Details the process and characteristics of creating the minified, single-file bundle for taskwerk using ESBuild.

```APIDOC
Minified Build (`npm run build:minified`):
  - Creates an optimized, single-file bundle located at `dist/taskwerk.min.js`.
  - Bundling Technology: Utilizes ESBuild for efficient dependency bundling.
  - Minification: Applies code minification to reduce file size.
  - Target Platform: Designed for Node.js version 18 and above.
  - Module Format: Outputs code in ES modules format.
  - Shebang: Includes `#!/usr/bin/env node` to allow direct execution from the command line.
  - Permissions: Sets executable permissions (755) on the generated file.

  Characteristics:
    - Size: Approximately 107KB.
    - Executable Usage Example: `./dist/taskwerk.min.js --help`
    - Portability: Can be run directly without requiring an active npm installation or project context.
```

--------------------------------

### Piping Input to LLM

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Shows how to pipe the output of other commands or file content as input to the `taskwerk llm` command. This enables chaining operations and processing file content.

```bash
echo "Explain quantum computing" | taskwerk llm
```

```bash
cat prompt.txt | taskwerk llm
```

--------------------------------

### Overriding Provider and Model

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Demonstrates how to specify a particular AI provider or model for the LLM command using `--provider` and `--model` flags, overriding the default configuration.

```bash
taskwerk llm "Hello" --provider openai
```

```bash
taskwerk llm "Complex question" --model gpt-4
```

```bash
taskwerk llm "Test" --provider anthropic --model claude-3-opus-20240229
```

--------------------------------

### Piping LLM Output

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Illustrates how to redirect the output of the `taskwerk llm` command to other commands or files. This is useful for saving results or further processing LLM responses.

```bash
taskwerk llm "Write a haiku about coding" > haiku.txt
```

```bash
taskwerk list --format json | taskwerk llm "Summarize these tasks"
```

--------------------------------

### Install Pre-commit Hook

Source: https://github.com/taisoai/taskwerk/blob/main/CONTRIBUTING.md

Installs a pre-commit hook to automatically format code before each commit, ensuring consistency and adherence to project standards.

```bash
ln -s ../../scripts/pre-commit.sh .git/hooks/pre-commit
```

--------------------------------

### Controlling LLM Creativity with Temperature

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Explains how to adjust the `--temperature` parameter to control the randomness and creativity of the LLM's responses, from focused to highly creative outputs.

```bash
taskwerk llm "Write a story" --temperature 1.5
```

```bash
taskwerk llm "Calculate the sum" --temperature 0.2
```

--------------------------------

### Manual Validation Steps

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Manual steps to validate code quality, test coverage, build artifacts, and functional aspects of the application.

```bash
# Code Quality
npm run lint
npm run format:check

# Test Coverage
npm test
# Verify: 171 tests passing, 0 failures

# Build Artifacts
npm run build:all
# Verify: dist/taskwerk.min.js created and executable

# Functional Testing
# Test the main CLI
node bin/taskwerk.js --help

# Test the minified bundle
node dist/taskwerk.min.js --help
./dist/taskwerk.min.js --version
```

--------------------------------

### taskwerk Project Structure

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Illustrates the directory layout of the taskwerk project, showing the organization of source code, tests, scripts, build artifacts, and documentation.

```text
taskwerk/
├── bin/                    # Executable scripts
│   └── taskwerk.js        # Main CLI entry point
├── src/                   # Source code
│   ├── commands/          # CLI commands
│   ├── core/             # Core functionality
│   ├── git/              # Git integration
│   ├── llm/              # LLM integration
│   └── utils/            # Utilities
├── tests/                # Test files
│   ├── commands/         # Command tests
│   ├── core/            # Core tests
│   ├── dist/            # Build artifact tests
│   ├── git/             # Git integration tests
│   └── utils/           # Utility tests
├── scripts/             # Build scripts
├── dist/                # Built artifacts (created during build)
│   └── taskwerk.min.js  # Minified bundle
└── docs/                # Documentation
```

--------------------------------

### Pre-Release Comprehensive Validation

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Performs a comprehensive validation process before a release, including linting, formatting checks, testing, and the full build process.

```bash
npm run make-release-dry-run
```

--------------------------------

### Limiting Response Length with Max Tokens

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Shows how to use the `--max-tokens` flag to limit the length of the LLM's response, which can help manage costs and ensure concise output.

```bash
taskwerk llm "Explain everything about AI" --max-tokens 100
```

--------------------------------

### Taskwerk Real-World Example

Source: https://github.com/taisoai/taskwerk/blob/main/README.md

Demonstrates a workflow for implementing a new feature using Taskwerk, including creating parent tasks, using AI agents for subtask generation, listing tasks by tag, and updating task status.

```bash
# Create a parent task for the feature
taskwerk add "Implement user authentication" -p high --tags feature,backend

# Use AI to help plan
taskwerk agent "Create subtasks for implementing user authentication with JWT"

# The agent creates subtasks for you:
# ✅ Created task TASK-123: Design authentication API endpoints
# ✅ Created task TASK-124: Implement JWT token generation  
# ✅ Created task TASK-125: Add password hashing with bcrypt
# ✅ Created task TASK-126: Create login/logout endpoints
# ✅ Created task TASK-127: Add authentication middleware
# ✅ Created task TASK-128: Write tests for auth flow

# Check your tasks by tag
taskwerk list --tag auth

# Get AI insights
taskwerk ask "Show me the auth tasks ordered by dependency"

# Start working on a task
taskwerk update TASK-124 --status in-progress

# Add notes as you work
taskwerk update TASK-124 --note "Using RS256 algorithm for better security"

# Complete a task
taskwerk update TASK-124 --status done
```

--------------------------------

### Taskwerk LLM Command Implementation

Source: https://github.com/taisoai/taskwerk/blob/main/dev/v0.6-ai-implementation-plan.md

JavaScript code snippet demonstrating the setup of the 'taskwerk llm' command using a CLI argument parsing library.

```javascript
import { Command } from 'commander';

export function llmCommand() {
  const llm = new Command('llm');
  
  llm
    .description('Send a prompt directly to the configured LLM')
    .argument('[prompt]', 'The prompt to send')
    .option('-f, --file <path>', 'Read prompt from file')
    .option('-p, --params <key=value...>', 'Parameters for prompt substitution')
    .option('--provider <name>', 'Override provider for this request')
    .option('--model <name>', 'Override model for this request')
    .option('-s, --system <prompt>', 'System prompt')
    .option('--temperature <num>', 'Override temperature (0-2)')
    .option('--max-tokens <num>', 'Override max tokens')
    .option('--context-tasks', 'Include current tasks as context')
    .option('--no-stream', 'Disable streaming output')
    .action(async (prompt, options) => {
      // Implementation logic for handling LLM requests goes here
      console.log('Prompt:', prompt);
      console.log('Options:', options);
    });
    
  return llm;
}
```

--------------------------------

### taskwerk Testing Commands

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Provides commands for executing the test suite, including running all tests, verbose output, specific file execution, and watch mode.

```APIDOC
Running Tests:
  npm test
    - Executes the entire test suite as defined by the project's test runner configuration.

  node --test tests/**/*.test.js --reporter=spec
    - Runs all test files matching the pattern 'tests/**/*.test.js' with the 'spec' reporter for detailed output.
    - Parameters:
      - tests/**/*.test.js: Path pattern to discover test files.
      - --reporter=spec: Specifies the output reporter for test results.

  node --test tests/commands/llmconfig.test.js
    - Executes a specific test file, 'tests/commands/llmconfig.test.js'.
    - Parameters:
      - tests/commands/llmconfig.test.js: Path to the specific test file to run.

  npm run test:watch
    - Starts the test runner in watch mode. Tests are automatically re-executed when source files are modified.
    - This command leverages the Node.js built-in test runner's watch functionality.
```

--------------------------------

### Taskwerk Config Command

Source: https://github.com/taisoai/taskwerk/blob/main/docs/cli-reference.md

Manage Taskwerk configuration settings. Allows getting, setting, and listing configuration values.

```bash
taskwerk config

# Options:
# --get <key>    - Get a config value
# --set <key=value> - Set a config value
# --list         - List all config
```

--------------------------------

### Reinstall Dependencies

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Removes existing node_modules and package-lock.json files and then reinstalls all project dependencies to resolve potential issues.

```bash
rm -rf node_modules package-lock.json
npm install
```

--------------------------------

### taskwerk NPM Scripts

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Lists the available npm scripts for development, building, code quality checks, testing, and maintenance within the taskwerk project.

```APIDOC
Development Commands:
  npm start
    - Run taskwerk CLI directly.
  npm run dev
    - Alias for 'npm start' (development mode).

Build Commands:
  npm run build
    - Performs a full build: linting, formatting check, tests, and creates a minified bundle.
  npm run build:minified
    - Builds only the minified bundle for Node.js 18+.
  npm run build:all
    - Executes both 'npm run build' and 'npm run build:minified'.
  npm run make-release-dry-run
    - Runs comprehensive pre-release validation checks.

Code Quality Commands:
  npm run lint
    - Executes ESLint on src/, tests/, and bin/ directories.
  npm run lint:fix
    - Runs ESLint with auto-fixing capabilities.
  npm run format
    - Formats code using Prettier.
  npm run format:check
    - Checks if the code adheres to Prettier formatting standards.

Test Commands:
  npm test
    - Runs the complete test suite using the custom test runner.
  npm run test:watch
    - Runs tests in watch mode, automatically re-running on file changes.

Maintenance Commands:
  npm run clean
    - Removes build artifacts and temporary files.
  npm run prepack
    - Performs pre-publish validation (lint + format + test).
  npm prepublishOnly
    - Executes 'npm run prepack' before publishing to npm.
```

--------------------------------

### taskwerk Repository Structure

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Overview of the directory structure for the taskwerk project, outlining the placement of source code, tests, examples, documentation, and configuration files.

```APIDOC
taskwerk Repository Structure:
  taskwerk/
  ├── src/          # CLI command implementations, Task management logic, Git integration utilities, Helper functions
  ├── tests/        # Test suite
  ├── examples/     # Example workflows
  ├── docs/         # Documentation
  └── package.json  # NPX-ready configuration
```

--------------------------------

### Check Formatting Issues

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Runs the formatting check to identify files that do not adhere to the defined code style, without making any changes.

```bash
npm run format:check
```

--------------------------------

### Publish Package to npm (npm)

Source: https://github.com/taisoai/taskwerk/blob/main/scripts/release-checklist.md

Publishes the project's package to the npm registry. This command is typically run after a successful build and version bump, making the new version available for installation.

```bash
npm publish
```

--------------------------------

### Daily Development Workflow Commands

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

A sequence of commands demonstrating a typical daily development workflow, including checking ready tasks, summarizing completed work, starting new tasks with Git integration, tracking files, adding notes, and completing tasks with auto-commit.

```bash
# Morning: Check what's ready to work on
task ready --assignee @me
task summary --completed --since yesterday

# Start work with automatic Git integration
task start TASK-005  # Creates branch, updates status, starts tracking

# During work: Track files and add context
task track src/auth/ tests/auth/
task note TASK-005 "Implementing rate limiting with Redis backend"

# Complete with validation and smart commit
task complete TASK-005 --auto-commit
# Runs tests, generates commit with task context, updates dependencies
```

--------------------------------

### TaskWerk Configuration File

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Example of the `.taskrc.json` file used to configure TaskWerk settings, including task file locations, auto-commit behavior, default priorities, and custom task categories.

```json
{
  "tasksFile": "tasks.md",
  "completedFile": "tasks_completed.md",
  "autoCommit": false,
  "autoCreateBranch": true,
  "defaultPriority": "medium",
  "categories": {
    "bugs": "🐛 Bug Fixes",
    "features": "✨ Features", 
    "docs": "📚 Documentation",
    "refactor": "♻️ Refactoring",
    "test": "🧪 Testing"
  }
}
```

--------------------------------

### Auto-format Files

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Executes the formatting script to automatically apply code style rules (e.g., Prettier) to all relevant files, ensuring consistent formatting.

```bash
npm run format
```

--------------------------------

### Configure AI/LLM Settings (`twrk aiconfig`)

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-v0.6x-cli-ref.md

Manage AI and LLM configurations using the `twrk aiconfig` command. Supports setting, getting, listing, and testing AI connections.

```bash
twrk aiconfig [options]

Options:
  --set <key=value>   Set AI configuration
  --get <key>         Get AI configuration
  --list              List all AI settings
  --test              Test AI connection

Examples:
  twrk aiconfig --list
  twrk aiconfig --set provider openai
  twrk aiconfig --set openai.api_key "sk-..."
  twrk aiconfig --test
```

--------------------------------

### Git Integration Commands

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Utilities for managing Git workflows directly from TaskWerk, including branch creation, smart commits, and Git hook installation.

```APIDOC
Git Integration Commands:

  task branch <task-id>
    - Creates a Git feature branch associated with a specific task.
    - Parameters:
      - <task-id>: The task ID to base the branch name on.

  task commit --task <task-id> [--message <custom-message>]
    - Generates a Git commit message that includes task context.
    - Parameters:
      - --task: The task ID to associate the commit with.
      - --message: An optional custom message to prepend or append.

  task git hooks install
    - Installs necessary Git hooks to automate workflows based on TaskWerk task status.
```

--------------------------------

### Controlling LLM Output Modes

Source: https://github.com/taisoai/taskwerk/blob/main/docs/llm-examples.md

Illustrates different output modes: `--no-stream` to disable response streaming, `--raw` for unformatted output, and `--quiet` to suppress statistics.

```bash
taskwerk llm "Long question" --no-stream
```

```bash
taskwerk llm "Generate JSON" --raw > data.json
```

```bash
taskwerk llm "Quick question" --quiet
```

--------------------------------

### Task Session Configuration (.task-session.json)

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Configuration file for tracking task sessions, including current task, start time, branch, agent, base branch, modified files, and last activity.

```json
{
  "currentTask": "TASK-001",
  "startedAt": "2024-12-15T14:30:00Z",
  "branch": "feature/auth-timeout-fix",
  "agent": "Claude Code",
  "baseBranch": "main",
  "filesModified": [
    "auth/session-manager.js",
    "config/auth-config.js"
  ],
  "lastActivity": "2024-12-15T15:45:00Z"
}
```

--------------------------------

### Agent Collaboration Workflow Commands

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Commands illustrating an agent collaboration workflow, where an agent requests context, starts and completes tasks, provides notes and learned insights, and a human reviews the agent's work history.

```bash
# Agent requests context for new work
task summary --agent-context TASK-007
# Gets: task details, dependencies, related files, implementation hints

# Agent works and learns
task start TASK-007 --agent "claude-3"
task complete TASK-007 --agent "claude-3" \
  --note "Added indexes on user_id and created_at, implemented Redis caching" \
  --learned "Database optimization pattern for time-series queries"

# Human reviews agent work
task timeline TASK-007  # See complete history of agent's work
```

--------------------------------

### Run Tests with Verbose Output

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Runs tests using Node.js's built-in test runner, specifying a reporter for more detailed output, which is helpful for diagnosing test failures.

```bash
node --test tests/**/*.test.js --reporter=spec
```

--------------------------------

### New Taskwerk Command Structure

Source: https://github.com/taisoai/taskwerk/blob/main/docs/v0.7.0-plan.md

Proposes a streamlined command structure for Taskwerk, moving task-related operations to root-level commands for improved discoverability and reduced verbosity. Includes examples for adding, listing, showing, updating, deleting, and changing task status.

```bash
# Root-level task commands:
twrk addtask "New task"      # Add a new task
twrk listtask                # List all tasks
twrk showtask TASK-001       # Show task details
twrk updatetask TASK-001     # Update a task
twrk deletetask TASK-001     # Delete a task
twrk statustask TASK-001 done # Change task status

# Quick status changes:
twrk done TASK-001           # Mark as done
twrk start TASK-001          # Mark as in-progress
twrk block TASK-001          # Mark as blocked
```

--------------------------------

### TaskWerk Initialization and Configuration

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Initializes a new TaskWerk project, setting up the database and configuration files. Also shows how to integrate TaskWerk into project scripts.

```bash
# Initialize TaskWerk v3 with SQLite backend
npx taskwerk init

# Creates:
# - taskwerk.db (SQLite database - source of truth)
# - tasks/taskwerk-rules.md (workflow rules for humans & agents)
# - .gitignore entries for session files

# Create alias for convenience
alias task="npx taskwerk"

```

```json
# Add to package.json scripts
{
  "scripts": {
    "task": "npx taskwerk"
  }
}

```

```bash
# Usage via npm script
npm run task add "Refactor auth module"

```

--------------------------------

### Taskwerk CLI Project Initialization and Configuration

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-v0.6x-cli-ref.md

Documentation for commands related to initializing Taskwerk projects and managing CLI configuration settings.

```APIDOC
Project Initialization & Configuration:

init:
  Usage: twrk init [options]
  Description: Initializes Taskwerk in the current directory or a specified location.
  Options:
    --dir <path>        Directory for task data (default: .taskwerk)
    --force             Overwrite existing installation
    --migrate           Migrate existing task files
  Examples:
    twrk init                              # Initialize in .taskwerk
    twrk init --dir ~/tasks                # Custom directory
    twrk init --force                      # Reinitialize
    twrk init --migrate                    # Import existing tasks
  Creates:
    - <dir>/taskwerk.db - SQLite database
    - <dir>/.twconfig - Configuration file
    - <dir>/taskwerk-rules.md - Workflow rules

status:
  Usage: twrk status [options]
  Description: Shows a quick project/session summary.
  Options:
    --detailed          Show more information
    --json              Output as JSON
  Example Output:
    Project: my-app
    Tasks: 42 total (5 active, 2 blocked, 35 completed)
    Current session: 2h 15m
    Active branch: feature/TASK-023-auth-refactor

config:
  Usage: twrk config [options]
  Description: Shows or modifies CLI configuration.
  Options:
    --set <key=value>   Set configuration value
    --get <key>         Get configuration value
    --list              List all settings
    --edit              Open config in editor
  Examples:
    twrk config --list
    twrk config --get user.name
    twrk config --set user.name "John Doe"
    twrk config --set editor vim
```

--------------------------------

### Taskwerk Minified Bundle Artifact

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Details about the generated minified JavaScript bundle, including its location, size, and characteristics.

```javascript
dist/
└── taskwerk.min.js    # ~107KB minified executable bundle

# The minified bundle:
# - Contains all TaskWerk functionality
# - Can run standalone without npm installation  
# - Platform-agnostic (works wherever Node.js runs)
# - Includes proper shebang for direct execution
```

--------------------------------

### Taskwerk AI Configuration Commands

Source: https://github.com/taisoai/taskwerk/blob/main/dev/v0.6-ai-implementation-plan.md

Manages AI provider settings, model selection, and connection testing via the taskwerk CLI.

```APIDOC
taskwerk aiconfig --set provider.key "value"
  Sets a specific configuration value for an AI provider.
  Parameters:
    provider.key: The configuration path (e.g., "anthropic.api_key")
    value: The value to set for the configuration key.

taskwerk aiconfig --list-providers
  Lists all available AI providers configured in Taskwerk.

taskwerk aiconfig --choose
  Initiates an interactive session to select the current AI provider and model.

taskwerk aiconfig --test
  Tests the connection to the currently configured AI provider.

taskwerk aiconfig --show
  Displays the current AI configuration settings.
```

--------------------------------

### Taskwerk CLI Meta and Utility Commands

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-v0.6x-cli-ref.md

Documentation for meta and utility commands like 'about' and 'help', detailing their purpose and usage.

```APIDOC
Meta/Utility Commands:

about:
  Usage: twrk about
  Description: Prints Taskwerk ASCII art, version, repository info, and basic help.
  Example Output:
    ╔════════════════════════════════════════╗
    ║           TASKWERK v0.6.0              ║
    ║   Git-aware task management for devs   ║
    ╚════════════════════════════════════════╝
    
    Version: 0.6.0
    Repo: https://github.com/deftio/taskwerk
    License: MIT
    Run 'twrk help' for commands

help:
  Usage: twrk help [command]
  Description: Shows general help or detailed help for a specific command.
  Examples:
    twrk help                    # General help
    twrk help task               # Task command help
    twrk help task add           # Specific subcommand help
```

--------------------------------

### Taskwerk Init Command

Source: https://github.com/taisoai/taskwerk/blob/main/docs/cli-reference.md

Initialize a new Taskwerk project in the current directory.

```bash
taskwerk init
```

--------------------------------

### Taskwerk LLM Command

Source: https://github.com/taisoai/taskwerk/blob/main/dev/v0.6-ai-implementation-plan.md

Allows direct interaction with configured LLMs, supporting prompts, parameter substitution, and provider overrides.

```APIDOC
taskwerk llm "<prompt>" [options]
  Sends a prompt directly to the configured LLM.

  Parameters:
    <prompt>: The text prompt to send to the LLM.

  Options:
    -f, --file <path>
      Read the prompt content from the specified file.
    -p, --params <key=value...>
      Provide key-value pairs for prompt parameter substitution (e.g., "topic=AI").
    --provider <name>
      Override the default LLM provider for this specific request.
    --model <name>
      Override the default LLM model for this specific request.
    -s, --system <prompt>
      Provide a system prompt to guide the LLM's behavior.
    --temperature <num>
      Override the default temperature setting (0.0 to 2.0).
    --max-tokens <num>
      Override the default maximum tokens for the response.
    --context-tasks
      Include current tasks as context for the LLM prompt.
    --no-stream
      Disable streaming output for the LLM response.

  Examples:
    # Basic usage:
    taskwerk llm "What is the meaning of life?"

    # With parameter substitution:
    taskwerk llm "Explain {topic}" --params topic="quantum computing"

    # Override provider and model:
    taskwerk llm "Hello" --provider openai --model gpt-4

    # Using a system prompt:
    taskwerk llm "Review this code" --system "You are a code reviewer"

    # Reading prompt from a file:
    taskwerk llm --file prompt.txt

    # Including context tasks:
    taskwerk llm "Summarize these tasks" --context-tasks
```

--------------------------------

### Check Linting Errors

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Runs the linting process to identify code style and syntax violations without attempting to fix them, useful for code reviews.

```bash
npm run lint
```

--------------------------------

### Execute Release Script

Source: https://github.com/taisoai/taskwerk/blob/main/RELEASE_WORKFLOW.md

Commands to switch to the main branch, pull the latest changes, and execute the release script, which handles version bumping, building, tagging, and publishing.

```bash
# Switch to main
git checkout main
git pull

# Run make-release script
npm run make-release

# This will:
# - Bump version
# - Run build and tests
# - Create git tag
# - Push to GitHub
# - Create GitHub release
# - CI will auto-publish to npm
```

--------------------------------

### Create Feature Branch Workflow

Source: https://github.com/taisoai/taskwerk/blob/main/RELEASE_WORKFLOW.md

Steps to create a new feature branch from main, perform development, and push it to the remote repository.

```bash
git checkout -b feature/v0.7.x-improvements

# Do all development work here
# Run tests locally
npm test

# Push to feature branch
git push origin feature/v0.7.x-improvements
```

--------------------------------

### Auto-fix Linting Issues

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Executes the linting script to automatically fix common code style and syntax errors across the project, ensuring code consistency.

```bash
npm run lint:fix
```

--------------------------------

### Check Specific Failing Tests

Source: https://github.com/taisoai/taskwerk/blob/main/docs/BUILD.md

Executes the test suite and pipes the output to grep to identify specific failing tests and their surrounding context, aiding in debugging.

```bash
npm test 2>&1 | grep -A5 -B5 "not ok"
```

--------------------------------

### TaskWerk CLI Commands Reference

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

This section provides a consolidated reference for common TaskWerk CLI commands, detailing their purpose, parameters, and typical usage patterns. It covers task initiation, status updates, context management, and agent interactions.

```APIDOC
task
  - Main command for TaskWerk CLI.

task branch <TASK-ID>
  - Creates a new Git branch for a given task ID.
  - Example: `task branch TASK-001` creates `feature/task-001-fix-login-bug`.

task complete <TASK-ID> [--agent <AGENT_NAME>] [--note "<NOTE>"] [--learned "<INSIGHT>"] [--auto-commit]
  - Marks a task as completed.
  - Optional: Specify an agent name, add notes, record learned insights, or trigger an auto-commit.
  - Example: `task complete TASK-003 --agent "claude-3" --note "Implemented with error handling"`

task summary [--agent-context <TASK-ID>] [--completed] [--since <TIME_AGO>]
  - Provides a summary of tasks.
  - `--agent-context <TASK-ID>`: Generates context for an agent.
  - `--completed`: Shows completed tasks.
  - `--since <TIME_AGO>`: Filters tasks completed after a certain time (e.g., 'yesterday').
  - Example: `task summary --agent-context TASK-007`

task ask "<QUERY>"
  - Asks a natural language question about tasks.
  - Returns structured analysis.
  - Example: `task ask "What authentication tasks are currently blocked?"`

task start <TASK-ID> [--agent <AGENT_NAME>]
  - Starts work on a task, potentially assigning it to an agent.
  - Example: `task start TASK-005` or `task start TASK-007 --agent "claude-3"`

task track <FILE_PATH> [<FILE_PATH> ...]
  - Tracks specific files or directories related to the current task.
  - Example: `task track src/auth/ tests/auth/`

task note <TASK-ID> "<NOTE>"
  - Adds a textual note to a specific task.
  - Example: `task note TASK-005 "Implementing rate limiting with Redis backend"`

task ready [--assignee <ASSIGNEE>]
  - Lists tasks that are ready to be worked on.
  - `--assignee <ASSIGNEE>`: Filters by assignee (e.g., `@me`).
  - Example: `task ready --assignee @me`

task timeline <TASK-ID>
  - Displays the historical timeline of work for a specific task.
  - Example: `task timeline TASK-007`

Configuration:
  - TaskWerk uses a `.taskrc.json` file in the project root for configuration.
  - Key settings include `tasksFile`, `completedFile`, `autoCommit`, `autoCreateBranch`, `defaultPriority`, and `categories`.
```

--------------------------------

### Taskwerk Core Commands

Source: https://github.com/taisoai/taskwerk/blob/main/README.md

Basic commands for initializing Taskwerk, adding tasks with details, and listing tasks. Supports priorities, tags, and due dates.

```bash
# Initialize taskwerk in your project
taskwerk init

# Add your first task
taskwerk add "Set up development environment" -p high

# View your tasks
taskwerk list

# Add more tasks with details
taskwerk add "Write unit tests for auth module" -p medium --tags backend,testing
taskwerk add "Review PR #42" -p high --due tomorrow
```

--------------------------------

### taskwerk v3 Technology Stack

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Overview of the core technologies and frameworks used in taskwerk v3, including runtime, database, CLI, Git integration, query engine, and export system.

```APIDOC
taskwerk v3 Technology Stack:
  Runtime: Node.js 18+ (ES modules)
  Database: SQLite3 with WAL mode for performance
  CLI Framework: Commander.js with rich formatting
  Git Integration: Advanced git operations via child_process
  Query Engine: SQL-based with intelligent caching
  Export System: YAML/Markdown generation with templates
```

--------------------------------

### Context & Summary Generation

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Commands to generate AI-friendly context summaries for tasks, including filtering by completion status, time, author, and search terms.

```APIDOC
Context & Summary Commands:

  task summary <task-id> [--agent-context] [--completed] [--since <time>] [--author <user>]
    - Generates a summary for a task, optimized for AI agents or human review.
    - Parameters:
      - <task-id>: The task ID to summarize.
      - --agent-context: Generates a context specifically tailored for AI agents.
      - --completed: Includes only completed tasks in the summary.
      - --since: Filters tasks completed since a specific time (e.g., 'yesterday').
      - --author: Filters tasks by a specific author.

  task summary --search <query> [--include-history]
    - Generates a summary based on tasks matching a search query.
    - Parameters:
      - --search: The query string to find relevant tasks.
      - --include-history: Includes historical task data in the summary.
```

--------------------------------

### Task Management CLI Commands

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Core commands for creating, listing, and managing tasks with rich metadata like priority, assignee, estimates, categories, and dependencies. Supports advanced filtering and searching.

```APIDOC
Task Management Commands:

  task add <description> [--priority <high|medium|low>] [--assignee <user>] [--estimate <duration>] [--category <name>] [--depends <task-id>]
    - Adds a new task with specified details.
    - Parameters:
      - description: The main description of the task.
      - --priority: Sets the task's priority level.
      - --assignee: Assigns the task to a specific user or alias.
      - --estimate: Sets an estimated time for task completion (e.g., '3d', '1h').
      - --category: Assigns the task to a category.
      - --depends: Links this task as dependent on another task ID.

  task list [--priority <level>] [--assignee <user>] [--category <name>] [--status <status>]
    - Lists tasks, with options to filter by priority, assignee, category, or status.
    - Parameters:
      - --priority: Filter by priority level.
      - --assignee: Filter by assignee.
      - --category: Filter by category.
      - --status: Filter by task status (e.g., 'open', 'in-progress', 'completed').

  task ready
    - Shows tasks that are ready to start (i.e., have no unmet dependencies).

  task search <query> [--include-notes] [--include-history]
    - Searches tasks based on a query string.
    - Parameters:
      - <query>: The text to search for.
      - --include-notes: Include task notes in the search.
      - --include-history: Include historical task data in the search.
```

--------------------------------

### Agent Integration Commands

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Commands for interacting with AI agents, including generating context for specific tasks, asking natural language queries, and starting/completing tasks with agent assignments and notes.

```bash
# Agent gets focused context without token explosion
task summary --agent-context TASK-003
# Returns: task details, dependencies, related work, file context

# Natural language queries
task ask "What authentication tasks are currently blocked?"
# Returns: structured analysis of auth-related blockers

# Agent claims and works on tasks
task start TASK-003 --agent "claude-3"
task complete TASK-003 --agent "claude-3" --note "Implemented with error handling"
```

--------------------------------

### Workflow & Status Update Commands

Source: https://github.com/taisoai/taskwerk/blob/main/dev/taskwerk-overview.md

Commands to manage the lifecycle of a task, including starting, pausing, completing, and blocking tasks. These operations often integrate with Git.

```APIDOC
Workflow Operations:

  task start <task-id>
    - Marks a task as in progress and typically creates a Git branch for it.
    - Parameters:
      - <task-id>: The identifier of the task to start.

  task pause <task-id> [--reason <text>]
    - Pauses a task and allows tracking the reason for pausing.
    - Parameters:
      - <task-id>: The identifier of the task to pause.
      - --reason: A brief explanation for pausing the task.

  task complete <task-id>
    - Marks a task as completed, often triggering Git integration for commits and merges.
    - Parameters:
      - <task-id>: The identifier of the task to complete.

  task block <task-id> --reason <text>
    - Marks a task as blocked and provides a reason.
    - Parameters:
      - <task-id>: The identifier of the task to block.
      - --reason: The reason why the task is blocked.
```

--------------------------------

### Pre-Release Checklist and PR Creation

Source: https://github.com/taisoai/taskwerk/blob/main/RELEASE_WORKFLOW.md

Commands to ensure all checks pass on the feature branch and create a pull request to the main branch.

```bash
# On feature branch, ensure everything passes
npm run lint
npm run build
npm test

# Create PR to main
gh pr create --base main
```