contextia task

contextia task manages the lifecycle of work items. Tasks represent discrete units of work (features, bugs, explorations) that link to specs and drive context assembly. A task progresses through three statuses: created, active, and completed.

Synopsis

contextia task [SUBCOMMAND] [OPTIONS]

When no subcommand is given, contextia task defaults to show if an ID is provided, or list if no arguments are given.

Subcommands

task show

Display a single task. This is the default subcommand when an ID is provided.

contextia task show <task-id> [OPTIONS]
contextia task <task-id>                  # shorthand

Option	Short	Description
--depth <level>	-d	Detail level: meta, summary, full (default: full)
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json

$ contextia task TASK-007
TASK-007: Implement OAuth login
  kind:    feature
  status:  active
  specs:   SPEC-AUTH-001
  created: 2026-02-28

  ## Objective
  Implement OAuth 2.0 with PKCE for user authentication.

  ## Plan
  1. Set up OAuth client configuration
  2. Implement token exchange flow
  3. Add PKCE challenge generation
  4. Wire up auth middleware

task list

List all tasks, optionally filtered by status or kind.

contextia task list [OPTIONS]

Option	Short	Description
--status <status>	-s	Filter: created, active, completed
--kind <kind>	-k	Filter: feature, bug, exploration
--format <fmt>	-f	Output format: human, json, context
--json	-j	Shorthand for --format json

$ contextia task list
  ID        Title                   Kind         Status     Created
  TASK-007  Implement OAuth login   feature      active     2026-02-28
  TASK-012  Add rate limiting       feature      created    2026-03-01
  TASK-013  Fix login timeout       bug          created    2026-03-02

  3 tasks found

$ contextia task list --status active
  ID        Title                   Kind         Status     Created
  TASK-007  Implement OAuth login   feature      active     2026-02-28

  1 task found

task activate

Transition a task from created to active. Only one task should be active at a time (the command warns but does not prevent multiple active tasks).

contextia task activate <task-id>

$ contextia task activate TASK-012
Activated TASK-012: Add rate limiting
  status: created -> active

  Warning: TASK-007 is also active. Consider completing it first.

Activation creates the session log directory for the task:

.contextia/work/tasks/TASK-012.md          # status updated to "active"
.contextia/work/logs/TASK-012/             # session log directory created

task complete

Transition a task from active to completed. Optionally closes any open session log.

contextia task complete <task-id>

Option	Description
--close-log	Close the current session log with a final entry

$ contextia task complete TASK-007
Completed TASK-007: Implement OAuth login
  status: active -> completed

$ contextia task complete TASK-012 --close-log
Completed TASK-012: Add rate limiting
  status: active -> completed
  Closed session log: .contextia/work/logs/TASK-012/session-003.md

Task lifecycle

created ──activate──> active ──complete──> completed

• created: The task exists but work has not started. No session logs.
• active: Work is in progress. Session logs are written here.
• completed: Work is finished. Session logs are preserved for reference.

Status changes are recorded in the task’s YAML frontmatter:

---
id: TASK-007
title: Implement OAuth login
kind: feature
status: completed
specs:
  - SPEC-AUTH-001
created: 2026-02-28
completed: 2026-03-02
---

Examples

Quick task overview (JSON, for scripting):

$ contextia task list --json
[
  {
    "id": "TASK-007",
    "title": "Implement OAuth login",
    "kind": "feature",
    "status": "active",
    "specs": ["SPEC-AUTH-001"],
    "created": "2026-02-28"
  }
]

Context format for agents:

$ contextia task list --format context
[TASK-007] Implement OAuth login (feature, active) specs:SPEC-AUTH-001
[TASK-012] Add rate limiting (feature, created) specs:SPEC-API-005
[TASK-013] Fix login timeout (bug, created) specs:SPEC-AUTH-001

Behavior

• Status transitions are validated: you cannot activate a completed task or complete a created task.
• The complete subcommand adds a completed date to the frontmatter.
• Task files are never moved or deleted by status changes. Status lives in YAML frontmatter.
• If no subcommand is given and no ID is provided, task list is executed by default.