aura-industry/skills/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

| Status | Meaning | |--------|---------| | OPEN | Created, not yet queued for agents | | QUEUED | Ready for agent pickup | | IN_PROGRESS | Agent working in task folder | | REVIEW | Gate check passed, awaiting human approval | | DONE | Approved, swapped into source, archived | | FROZEN | 3+ failures, needs human investigation | | HUMAN | Reserved for human-only work | | CANCELED | Abandoned or superseded |

---

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

| Field | Type | Purpose | |-------|------|---------| | allowed_modify | JSON array | Files the agent may edit | | allowed_create | JSON array | Glob patterns for new files | | max_lines_changed | integer | Max total line diff | | can_add_dependencies | boolean | Allow package.json changes | | module | string | Module this task touches | | attempts | integer | Rejection count | | last_error | string | Last rejection reason |

---

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.

| Key | Default | Purpose | |-----|---------|---------| | global_forbidden | ["core/*"] | Glob patterns no agent may touch | | max_concurrent_tasks | 5 | Max tasks in IN_PROGRESS at once | | default_max_lines_changed | 200 | Default line limit per task | | default_can_add_dependencies | false | Default dependency policy |

Per-Project Config

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

| Key | Purpose | |-----|---------| | global_forbidden | Additional forbidden globs (merged with global) | | test_command | Test runner command (e.g. npx vitest run, npm test, pytest) | | project_framing | Context builder framing text for this project | | source_dir | Source directory name (default: src) | | dashboard_port | Dev server port for preview |

# 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

| Method | Endpoint | Purpose | |--------|----------|---------| | GET | /api/tasks | List tasks (query: status, q, limit, offset) | | GET | /api/tasks/pick | Pick next queued task | | POST | /api/tasks/create | Create task | | GET | /api/tasks/{N} | Task detail | | POST | /api/tasks/{N}/claim | Acquire lock | | POST | /api/tasks/{N}/release | Release lock | | POST | /api/tasks/{N}/transition | Transition status | | POST | /api/tasks/{N}/gate-check | Run gate check | | POST | /api/tasks/{N}/swap | Execute swap | | GET | /api/tasks/{N}/file-locks | List active file locks | | GET | /api/tasks/{N}/file-conflicts | Check file conflicts | | POST | /api/tasks/{N}/tags | Add tag | | DELETE | /api/tasks/{N}/tags | Remove tag | | GET | /api/tasks/{N}/comments | List comments | | POST | /api/tasks/{N}/comments | Add comment | | GET | /api/config | List global config | | POST | /api/config | Set global config |

---

Services Reference

| Service | File | Function | |---------|------|----------| | Task Folder | src/core/task-folder-service.ts | provisionTaskFolder(dbFile, taskNum) | | Gate Check | src/core/gate-check-service.ts | runGateCheck(dbFile, taskNum) | | Circuit Breaker | src/core/circuit-breaker.ts | handleRejection(dbFile, taskNum, reason) | | Swap | src/core/swap-service.ts | swapTaskIntoSrc(dbFile, taskNum, opts?) | | File Locks | src/core/file-lock-service.ts | acquireFileLocks(), releaseFileLocks(), invalidateConflicts() | | Preview | src/core/preview-service.ts | startPreview(dbFile, taskNum), stopPreview(dbFile) | | Context Builder | src/core/context-builder.ts | buildAgentContext(dbFile, taskNum) | | Global Config | src/core/global-config-service.ts | getConfig(), setConfig(), listConfig() | | Project Config | src/core/project-service.ts | getProjectConfig(), setProjectConfig(), listProjectConfig() |

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