Task Management

Branch-based task lifecycle commands for isolated, auditable development workflows aligned with arxiv:2602.20478.

Why Branch-Based Isolation?

CCO implements task isolation using git branches, following the workflow architecture described in arxiv:2602.20478. Each task runs in an isolated branch, providing:

Benefits of Branch Isolation

  • Clean state - Each task starts from a known-good main branch state
  • Atomic commits - Complete task or abandon without half-finished changes
  • Parallel tasks - Work on multiple tasks simultaneously in different branches
  • Easy rollback - Abandon simply deletes the branch; finish merges cleanly
  • Memory integration - Task metadata stored in AOMA for long-term tracking
ℹ️

Branch names follow the pattern: task/<slugified-description>-<timestamp>

cco tasks start

Create an isolated task branch and register it in AOMA memory.

Parameters

Parameter Type Description
description required Human-readable task description
--repo optional Repository path (defaults to current directory)
--json optional Output results as JSON

Behavior

  • Creates a git branch named task/<slugified-description>-<timestamp>
  • Stores task metadata in AOMA memory:
    • description - The task description
    • branch - The created branch name
    • status - Set to active
    • created_at - ISO timestamp
  • Switches to the new branch

Example

bash 
# Start a new task for user authentication
cco tasks start "Add user authentication"

# Start a task in a specific repository
cco tasks start "Fix login bug" --repo /path/to/project

# Get JSON output for scripting
cco tasks start "Add payment integration" --repo /path/to/project --json

cco tasks finish

Complete an active task: commit changes, merge to main, update memory, clean up branch.

Parameters

Parameter Type Description
description optional Task description to match (if omitted, uses current branch)
--repo optional Repository path (defaults to current directory)
--json optional Output results as JSON

Behavior

  • Finds the current task branch or matches by description
  • Commits all changes with a descriptive message
  • Merges the branch to main (or master)
  • Updates AOMA memory: sets status to completed
  • Deletes the task branch

Example

bash 
# Finish the current task (commits, merges, cleans up)
cco tasks finish

# Finish a specific task by description
cco tasks finish "Add user authentication"

# Finish with JSON output
cco tasks finish "Add payment integration" --repo /path/to/project --json

cco tasks abandon

Abandon an active task: create a tag, switch to main, delete branch, update memory.

Parameters

Parameter Type Description
--repo optional Repository path (defaults to current directory)
--json optional Output results as JSON

Behavior

  • Creates a git tag: abandoned/<task-id>-<timestamp>
  • Switches to main (or master)
  • Deletes the task branch (changes are preserved in the tag)
  • Updates AOMA memory: sets status to abandoned
⚠️

Abandoning a task does not lose your changes - they are preserved in the abandoned tag for future reference.

Example

bash 
# Abandon the current task
cco tasks abandon

# Abandon with JSON output
cco tasks abandon --repo /path/to/project --json

cco tasks list

List all active task branches from AOMA memory.

Parameters

Parameter Type Description
--json optional Output results as JSON

Output

Displays a table with the following columns:

Column Description
TASK_ID Unique identifier from AOMA memory
DESCRIPTION Human-readable task description
CREATED_AT ISO timestamp when task was started
BRANCH_NAME Git branch name for the task

Example

bash 
# List all active tasks
cco tasks list

# Get JSON output for scripting
cco tasks list --json

Task Lifecycle Workflow

Complete Workflow Example

bash 
# 1. Start a new task
$ cco tasks start "Add user authentication"
Created branch: task/add-user-authentication-20260508t143052z
Task registered in memory with ID: 42

# 2. Do work on the task (make changes, run cco task, etc.)
$ cco task --repo . --task "Implement auth module"

# 3. Finish when complete
$ cco tasks finish
Branch merged to main
Task status updated to: completed
Branch task/add-user-authentication-20260508t143052z deleted

# Alternative: Abandon if task is no longer needed
$ cco tasks abandon
Tagged abandoned changes as: abandoned/42-20260508t150123z
Switched to main
Branch deleted
↑↓ Navigate Enter Select Esc Close