aura-industry/auramaxx/task-lifecycle

Task Lifecycle — Agent PM System

Manage the task pipeline. All commands use $TASKCTL from the project root.

TASKCTL="node --import tsx scripts/taskctl.ts"

How It Works

Agents work in isolated task folders — never touching source code directly. Changes flow through automated validation and human approval before landing in the codebase.

QUEUED ──→ IN_PROGRESS ──→ REVIEW ──→ DONE
               │               │
          (gate fail)    (reject/test fail)
               │               │
               ▼               ▼
           QUEUED ◄────────────┘   (attempts < 3, retry)
           FROZEN ◄────────────┘   (attempts >= 3, human intervenes)

Pipeline Flow

1. Provision — Task transitions to IN_PROGRESS, system copies allowed files into {project_root}/tasks/task-{id}/changes/ and creates /new/
2. Agent works — Modifies files in the task folder only, within spec constraints
3. Gate check — Validates against allowlists, line limits, forbidden paths, dependency rules
4. Review — Human reviews via dashboard or CLI preview
5. Swap — Git savepoint → copy to source → run tests → commit or rollback
6. Conflict resolution — After swap, other tasks touching same files get invalidated and requeued

Statuses

Task Folder Rules

{project_root}/tasks/task-{id}/
  /changes/     ← copies of allowed source files to modify
  /new/         ← new files the agent creates

Agents MUST:

• Only modify files in changes/ that are listed in allowed_modify
• Only create files in new/ matching allowed_create patterns
• Stay under max_lines_changed (default: 200)

Agents MUST NOT:

• Touch source code directly
• Modify files outside allowed_modify
• Touch forbidden paths (global or per-project)
• Add dependencies unless can_add_dependencies is true

Task Spec Fields

Gate Check

Automated validation that runs before a task reaches REVIEW. Auto-rejects if:

1. Modified file not in allowed_modify
2. Created file not matching allowed_create patterns
3. File matches forbidden globs (global + per-project merged)
4. Lines changed exceeds max_lines_changed
5. package.json/lock file changed and can_add_dependencies is false

$TASKCTL gate-check --task N [--json]     # Exit 0 = pass, Exit 2 = fail

API: POST /api/tasks/{N}/gate-check → { ok, passed, violations[], filesChanged[], filesCreated[], linesChanged }

Circuit Breaker

On rejection (gate fail, test failure, human reject):

• attempts increments by 1, last_error records reason
• attempts < 3 → QUEUED (agent retries)
• attempts >= 3 → FROZEN (human must investigate)

Frozen tasks require human intervention: rewrite spec + reset attempts, or kill.

Swap

Applies an approved REVIEW task into the source tree:

1. Creates git savepoint
2. Copies changes/ files into source
3. Copies new/ files into project
4. Runs test command (per-project test_command config, 120s timeout)
5. Tests pass → commit, release file locks, archive task folder → DONE
6. Tests fail → rollback to savepoint, circuit breaker handles retry/freeze

$TASKCTL swap --task N [--json]            # Execute swap
$TASKCTL swap --task N --dry-run [--json]  # Preview without committing

API: POST /api/tasks/{N}/swap (body: { dryRun?: boolean }) → 200 success, 422 test failure, 409 not in REVIEW

File Locks

Tracks file ownership across concurrent tasks. First task to swap wins — conflicting tasks get invalidated and requeued.

• Acquire — Atomic all-or-nothing; returns conflicts if file already locked
• Release — Marks locks as released after swap
• Invalidate — After swap, other tasks on same files get requeued via circuit breaker

$TASKCTL file-locks --task N [--json]       # List active locks
$TASKCTL file-conflicts --task N [--json]   # Check for overlapping locks

API: GET /api/tasks/{N}/file-locks, GET /api/tasks/{N}/file-conflicts

Preview

Temporarily copy task files into source for visual review. One preview at a time. No git operations — clean restore guaranteed.

$TASKCTL preview-start --task N [--json]   # Copy task files to source
$TASKCTL preview-stop [--json]             # Restore source to original state

Context Builder

Assembles the agent prompt when a task starts. Total must stay under 4000 lines.

Assembly order:

1. Framing — Per-project project_framing config + task description + allowed files
2. ARCHITECTURE.md — Truncated to 100 lines
3. Modified files — Full content from task folder
4. Adjacent interfaces — Export signatures from related files
5. Similar feature example — From completed task with same module (optional)

Truncation order if over limit: example first, then adjacent interfaces.

CLI Reference

Quick Workflow

# Pick next task, claim it, and start
$TASKCTL pick-and-claim --owner my-agent [--tag TAG] [--json]
$TASKCTL update-task-status --task N --owner my-agent --status IN_PROGRESS [--json]
 
# Or use the shortcut
$TASKCTL next --owner my-agent [--json]
 
# When done
$TASKCTL done --task N --owner my-agent [--json]
 
# Approve a REVIEW task (swap + cascade-unblock)
$TASKCTL approve --task N [--json]
 
# On failure
$TASKCTL fail --task N --owner my-agent --error "reason" [--json]

Task Management

# List and view
$TASKCTL list-tasks [--status S] [--tag TAG] [--json]
$TASKCTL show-task --task N [--json]
$TASKCTL my-tasks --owner O [--json]
$TASKCTL stats [--json]
 
# Create and edit
$TASKCTL create-task --title "..." --slug "..." [--priority P0|P1|P2] [--json]
$TASKCTL quick-create --title "..." [--json]
$TASKCTL update-task --task N --title "..." [--json]
 
# Status transitions
$TASKCTL update-task-status --task N --owner O --status S [--json]
$TASKCTL pick-task [--tag TAG] [--json]
$TASKCTL pick-and-claim [--tag TAG] --owner O [--json]
$TASKCTL claim-lock --task N --owner O [--json]
$TASKCTL release-lock --task N --owner O [--json]
$TASKCTL reap-stale-locks [--json]
 
# Tags
$TASKCTL add-tag --task N --tag T [--json]
$TASKCTL remove-tag --task N --tag T [--json]
$TASKCTL list-tags [--task N] [--json]
 
# Dependencies
$TASKCTL add-dep --task N --depends-on M [--json]
$TASKCTL remove-dep --task N --depends-on M [--json]
$TASKCTL list-deps --task N [--json]
 
# Hierarchy
$TASKCTL set-parent --task N --parent M [--json]
$TASKCTL remove-parent --task N [--json]
$TASKCTL list-subtasks --task N [--json]
 
# Comments
$TASKCTL comment --task N --author A --body "..." [--json]
$TASKCTL list-comments --task N [--json]
 
# Config (global)
$TASKCTL config-get --key K [--json]
$TASKCTL config-set --key K --value V [--json]
$TASKCTL config-list [--json]
 
# Templates
$TASKCTL list-templates [--json]
$TASKCTL show-template --name N [--json]

Pipeline Commands

# Gate check
$TASKCTL gate-check --task N [--json]
 
# Swap
$TASKCTL swap --task N [--dry-run] [--json]
 
# Approve (swap + cascade-unblock dependents)
$TASKCTL approve --task N [--json]
 
# File locks
$TASKCTL file-locks --task N [--json]
$TASKCTL file-conflicts --task N [--json]
 
# Preview
$TASKCTL preview-start --task N [--json]
$TASKCTL preview-stop [--json]
 
# Backlog
$TASKCTL backlog-status [--json]

Config

Config is layered: per-task spec > per-project config > global config. Per-project can only further restrict, never loosen global rules.

Global Config

Set once, applies to all projects.

Per-Project Config

Stored in project_config table. Overrides global for tasks scoped to that project. Falls back to global when unset.

# Set per-project config
$TASKCTL config-set --project P --key test_command --value "npm test"
$TASKCTL config-set --project P --key global_forbidden --value '["core/*","migrations/*"]'
 
# View merged config for a project
$TASKCTL config-list --project P

Adding a New Project

# Register project
$TASKCTL create-project --name "my-app" --root /path/to/my-app
 
# Set project-specific config
$TASKCTL config-set --project 1 --key test_command --value "npm test"
$TASKCTL config-set --project 1 --key global_forbidden --value '["core/*","db/migrations/*"]'
$TASKCTL config-set --project 1 --key project_framing --value "You are modifying a React dashboard app."

API Endpoints

Services Reference

Full spec: public/agent-project-management.md