managing-task-lifecycle

Decision Tree: Which Command to Use?

Is Trello connected? (check: bpsai-pair trello status)
│
├── YES → Use `ttask` commands (primary)
│   ├── Start:    bpsai-pair ttask start TRELLO-XX
│   ├── Complete: bpsai-pair ttask done TRELLO-XX --summary "..." --list "Deployed/Done"
│   └── Block:    bpsai-pair ttask block TRELLO-XX --reason "..."
│
└── NO → Use `task update` commands
    ├── Start:    bpsai-pair task update TASK-XXX --status in_progress
    ├── Complete: bpsai-pair task update TASK-XXX --status done
    └── Block:    bpsai-pair task update TASK-XXX --status blocked

Rule of thumb: If you see TRELLO-XX IDs, use ttask. If you only have TASK-XXX IDs, use task update.

CRITICAL: Always Use CLI Commands

Task state changes MUST go through the CLI to trigger hooks (Trello sync, timers, state updates).

Never just edit task files or say "marking as done" - run the command.

Automatic Hooks

When you change task status via CLI, these hooks fire automatically:

On task update --status in_progress:

• start_timer - Begins time tracking
• sync_trello - Moves card to "In Progress"
• update_state - Updates state.md current focus

On task update --status done:

• stop_timer - Stops timer, records duration
• record_metrics - Records token usage and costs
• record_velocity - Tracks sprint velocity
• sync_trello - Moves card to "Deployed/Done"
• update_state - Updates state.md
• check_unblocked - Identifies newly unblocked tasks

On task update --status blocked:

• sync_trello - Moves card to "Issues/Tech Debt"
• update_state - Updates state.md

You don't need to manually update Trello, start/stop timers, or refresh state.md - hooks handle it.

Starting a Task

bpsai-pair task update TASK-XXX --status in_progress

This will:

• Update task file status
• Move Trello card to "In Progress" list
• Start timer (when implemented)
• Update state.md current focus

During Work (Progress Updates)

bpsai-pair ttask comment TASK-XXX "Completed API endpoints, starting tests"

This adds a comment to the Trello card without changing status. Use for:

• Milestone updates
• Noting decisions
• Progress visibility for team

Completing a Task

For Trello Projects (Recommended)

Use ttask done - it handles everything in one command:

bpsai-pair ttask done TRELLO-XX --summary "What was accomplished" --list "Deployed/Done"

This single command will:

• ✓ Move Trello card to "Deployed/Done" list
• ✓ Auto-check ALL acceptance criteria items
• ✓ Add completion summary to card
• ✓ Update local task file status
• ✓ Trigger all completion hooks (timer, metrics, state.md)

You do NOT need to also run task update --status done - ttask done handles it.

For Non-Trello Projects

Use task update:

bpsai-pair task update TASK-XXX --status done

This will:

• Update task file status
• Trigger completion hooks (timer, metrics, state.md)

Common Mistakes

| Mistake | Why It's Wrong | Correct Approach | |---------|---------------|------------------| | Using only task update on Trello projects | Doesn't check AC on Trello card | Use ttask done instead | | Using both commands on Trello projects | Unnecessary duplication | Just use ttask done | | Using ttask on non-Trello projects | Commands won't work | Use task update |

Quick Reference

Local Task Commands (task)

Use these for status changes - they trigger all hooks.

| Action | Command | |--------|---------| | Start task | bpsai-pair task update TASK-XXX --status in_progress | | Complete task | bpsai-pair task update TASK-XXX --status done | | Block task | bpsai-pair task update TASK-XXX --status blocked | | Show next task | bpsai-pair task next | | Auto-assign next | bpsai-pair task auto-next | | List all tasks | bpsai-pair task list | | Show task details | bpsai-pair task show TASK-XXX |

Trello Card Commands (ttask)

Use these for direct Trello operations.

| Action | Command | |--------|---------| | List Trello cards | bpsai-pair ttask list | | Show card details | bpsai-pair ttask show TRELLO-XX | | Start card | bpsai-pair ttask start TRELLO-XX | | Complete card | bpsai-pair ttask done TRELLO-XX --summary "..." --list "Deployed/Done" | | Check acceptance item | bpsai-pair ttask check TRELLO-XX "item text" | | Add progress comment | bpsai-pair ttask comment TRELLO-XX "message" | | Block card | bpsai-pair ttask block TRELLO-XX --reason "why" | | Move card to list | bpsai-pair ttask move TRELLO-XX "List Name" |

When to Use task vs ttask

For Trello-connected projects (preferred):

| Scenario | Command | |----------|---------| | Starting a task | ttask start TRELLO-XX | | Progress updates | ttask comment TRELLO-XX "message" | | Completing a task | ttask done TRELLO-XX --summary "..." --list "Deployed/Done" | | Blocking a task | ttask block TRELLO-XX --reason "..." |

For non-Trello projects:

| Scenario | Command | |----------|---------| | Starting a task | task update TASK-XXX --status in_progress | | Completing a task | task update TASK-XXX --status done | | Blocking a task | task update TASK-XXX --status blocked |

Key insight: ttask commands handle both Trello AND local state. You don't need to run task update after ttask done - it handles everything.

Task Status Values

| Status | Meaning | Trello List | |--------|---------|-------------| | pending | Not started | Backlog / Planned | | in_progress | Currently working | In Progress | | blocked | Waiting on something | Issues / Blocked | | review | Ready for review | Review | | done | Completed | Deployed / Done |

Workflow Checklist

When Starting a Task

1. Run: bpsai-pair task update TASK-XXX --status in_progress
2. Verify Trello card moved
3. Read the task file for implementation plan
4. Begin work

During Work

1. Add progress comments: bpsai-pair ttask comment TASK-XXX "status update"
2. Commit frequently with task ID in message

When Completing a Task

For Trello projects:

1. Ensure tests pass: pytest -v
2. Find card ID: bpsai-pair ttask list
3. Complete: bpsai-pair ttask done TRELLO-XX --summary "..." --list "Deployed/Done"
4. Update state.md with what was done
5. Commit changes with task ID in message

For non-Trello projects:

1. Ensure tests pass: pytest -v
2. Complete: bpsai-pair task update TASK-XXX --status done
3. Update state.md with what was done
4. Commit changes with task ID in message

Validation Scripts

Use these scripts to validate before completion:

Validate Task File Format

python .claude/skills/managing-task-lifecycle/scripts/validate_task_status.py TASK-XXX

Checks: frontmatter, required fields, valid status, acceptance criteria section.

Check Completion Readiness

python .claude/skills/managing-task-lifecycle/scripts/check_completion.py TASK-XXX

Runs: task file validation, tests, linting, git status.

Validation loop: Run → fix issues → re-run until all checks pass.

Trello Sync Commands

# Check Trello connection status
bpsai-pair trello status

# Sync plan to Trello (creates/updates cards)
bpsai-pair plan sync-trello PLAN-ID

# Force refresh from Trello
bpsai-pair trello refresh

Full CLI Reference

See reference/all-cli-commands.md for complete command documentation.