Tasks

Tasks are pre-written instruction sets that can be reused across projects. Papagai supports both built-in tasks and custom user tasks.

Task Structure

Tasks are markdown files with YAML frontmatter:

---
description: A short description of what this task does
tools: Bash(git:*), Read, Write, Edit  # Optional: tool restrictions
---

# Task Instructions

You are an expert programmer. Please analyze this codebase and...

The description field is required and is shown in the task list.

Built-in Tasks

Papagai ships with several useful tasks in papagai/tasks/:

Python Tasks

Located in papagai/tasks/python/:

update-to-3.9: Update Python codebase to use Python 3.9+ features
Other Python modernization tasks

C Tasks

Located in papagai/tasks/c/:

modernize: Modernize C code to C11 standards

Meson Tasks

Located in papagai/tasks/meson/:

Build system related tasks

To see all available built-in tasks:

$ papagai task --list

Custom User Tasks

Create your own tasks in $XDG_CONFIG_HOME/papagai/tasks/:

$ mkdir -p ~/.config/papagai/tasks/myproject
$ cat > ~/.config/papagai/tasks/myproject/refactor.md << 'EOF'
---
description: Refactor myproject using modern patterns
---

You are an expert in software architecture. Please:

1. Analyze the current codebase structure
2. Identify areas for improvement
3. Apply modern design patterns
4. Ensure all tests pass after refactoring
EOF

Run your custom task:

$ papagai task myproject/refactor

Task Organization

Tasks can be organized in subdirectories for better organization:

~/.config/papagai/tasks/
├── python/
│   ├── django-upgrade.md
│   └── async-refactor.md
├── javascript/
│   ├── react-modernize.md
│   └── typescript-convert.md
└── general/
    ├── add-tests.md
    └── improve-docs.md

Reference tasks using the directory path:

$ papagai task python/django-upgrade
$ papagai task javascript/typescript-convert

Variable Substitution

Tasks support variable substitution for dynamic content:

Available Variables

{BRANCH} - The original branch name (before creating the worktree)
{WORKTREE_BRANCH} - The worktree branch name (e.g., papagai/main-20251112-1030-7be3946e)

Example Usage

---
description: Create a PR for changes
---

Create a pull request from branch {WORKTREE_BRANCH} to {BRANCH}.

Use the following PR template:
- Base branch: {BRANCH}
- Working branch: {WORKTREE_BRANCH}

Tool Restrictions

Limit which tools Claude can use in a task:

---
description: Update dependencies only
tools:
  - Bash(uv :*)
  - Bash(pip :*)
  - Edit(./**/pyproject.toml)
  - Read
---

Update all Python dependencies to their latest compatible versions.

This ensures Claude can only:

Run uv and pip commands
Edit pyproject.toml files
Read files for information

Best Practices

Writing Effective Tasks

Be Specific: Clear, detailed instructions produce better results
Include Context: Explain why the task matters and what the expected outcome is
Set Boundaries: Use tool restrictions to prevent unintended changes
Test First: Run tasks on a test repository before using on production code
Version Control: Keep your task library in git for versioning and sharing

Task Complexity

Tasks can range from simple to complex:

Simple Task (single focus):

---
description: Add type hints to Python functions
---

Add type hints to all function signatures in the codebase.

Complex Task (multi-step):

---
description: Comprehensive code modernization
---

Modernize this codebase by:

1. Updating to Python 3.12 features (match statements, type hints, etc.)
2. Replacing deprecated APIs with modern equivalents
3. Improving error handling with exception groups
4. Adding comprehensive docstrings
5. Ensuring all tests pass

Example Task Library

Here’s a complete example of a useful task:

---
description: Add comprehensive logging to Python codebase
tools:
  - Bash(git:*)
  - Read
  - Edit(./**/*.py)
  - Write(./**/*.py)
---

# Add Comprehensive Logging

You are an expert Python developer. Add comprehensive logging to this codebase:

## Requirements

1. Import logging at the top of each module that needs it
2. Create module-level loggers: `logger = logging.getLogger(__name__)`
3. Add appropriate log levels:
   - DEBUG: Detailed diagnostic information
   - INFO: Confirmation of expected behavior
   - WARNING: Unexpected events that don't prevent operation
   - ERROR: Serious problems that prevent some functionality
   - CRITICAL: System failure

4. Log at key points:
   - Function entry/exit for complex functions
   - Error conditions with context
   - Important state changes
   - External API calls

5. Include relevant context in log messages
6. Use structured logging where appropriate

## Do Not

- Don't add logging to test files
- Don't log sensitive information (passwords, tokens, etc.)
- Don't use print() statements - convert existing ones to logging

## Testing

After adding logging, run the test suite to ensure nothing broke.