task-system

name	task-system
description	File-backed task management with dependencies and parallel execution. Use for complex work with 3+ interdependent tasks.
context	fork
globs	[]
alwaysApply	false

Task System — File-Backed Task Management

Use this skill for complex work with multiple interdependent tasks. Tasks are stored as JSON files, survive session restarts, and support automatic parallel execution based on dependency graphs.

---

When to Use

Scenario	Use
1-2 simple tasks	TodoWrite
3+ tasks with dependencies	Task System
Tasks need to survive restart	Task System
Parallel execution needed	Task System
Multiple agents collaborating	Task System

---

Task Schema

{
  "id": "T-001",
  "subject": "Build frontend",
  "description": "Implement ReviewCard component with mocked data",
  "status": "pending",
  "activeForm": "Building ReviewCard component",
  "blockedBy": [],
  "blocks": ["T-003"],
  "owner": "Aphrodite",
  "metadata": {},
  "threadID": "session-abc",
  "timeout_ms": 180000,
  "retry_policy": { "count": 3, "backoff": "exponential" },
  "fallback_agent": "talos",
  "partial_ok": false,
  "session_id": null,
  "session_resume": null
}

Field	Type	Required	Description
id	string	Yes	Auto-generated: T-{sequential}
subject	string	Yes	Imperative: "Run tests", "Build component"
description	string	Yes	Detailed description of the task
status	enum	Yes	pending, in_progress, completed, deleted
activeForm	string	No	Present continuous: "Running tests"
blockedBy	string[]	Yes	Task IDs that must complete first
blocks	string[]	Yes	Task IDs that this task blocks
owner	string	No	Agent name responsible
metadata	object	No	Additional context
threadID	string	Yes	Session ID (auto-set)
timeout_ms	integer	No	Timeout in milliseconds for this task (default: 120000 = 2min). 0 = no timeout
retry_policy	object	No	{ count: number, backoff: "exponential"|"fixed" }. Default: { count: 3, backoff: "exponential" }
fallback_agent	string	No	Agent name to use if all retries fail. Default: null (escalate to Zeus)
partial_ok	boolean	No	If true, partial results are acceptable on timeout. Default: false
session_id	string	No	Alias of the session running this task (e.g. "hermes-1"). Set automatically
session_resume	string	No	Session alias to resume instead of starting fresh (e.g. "hermes-1")

---

Storage

Tasks are stored as JSON files:

.pantheon/tasks/
├── T-001.json
├── T-002.json
├── T-003.json
└── ...

Persistence: Tasks survive session restarts. Delete manually when feature is merged.

---

Dependency Graph & Parallel Execution

Tasks with empty blockedBy run in parallel. Dependent tasks wait until blockers complete.

[Build Frontend]    ──┐
                      ├──→ [Integration Tests] ──→ [Deploy]
[Build Backend]     ──┘

Execution flow:

1. T-001 (blockedBy: []) → runs immediately
2. T-002 (blockedBy: []) → runs immediately (parallel with T-001)
3. T-003 (blockedBy: [T-001, T-002]) → waits for both
4. When T-001 + T-002 complete → T-003 unblocks automatically
5. T-004 (blockedBy: [T-003]) → waits for T-003

---

Task Lifecycle

Create

TaskCreate({
  subject: "Build frontend",
  description: "Implement ReviewCard with mocked data",
  blockedBy: [],
  blocks: ["T-003"],
  owner: "Aphrodite"
})
→ Returns: { id: "T-001", ... }

Update

TaskUpdate({
  id: "T-001",
  status: "in_progress",
  activeForm: "Building ReviewCard component"
})

List

TaskList()
→ Returns all active tasks with status:
  T-001 [in_progress] Build frontend        blockedBy: []
  T-002 [pending]     Build backend         blockedBy: []
  T-003 [pending]     Integration tests     blockedBy: [T-001, T-002]

Get

TaskGet({ id: "T-001" })
→ Returns full task object

---

Difference from TodoWrite

Feature	TodoWrite	Task System
Storage	Session memory	File system (.pantheon/tasks/)
Persistence	Lost on close	Survives restart
Dependencies	None	Full support (blockedBy)
Parallel execution	Manual	Automatic optimization
Multi-agent	Single agent	Multiple agents with owners
Best for	Simple sequential work	Complex interdependent work

---

Timeout & Retry

Every task can have timeout and retry policies:

{
  "timeout_ms": 180000,
  "retry_policy": { "count": 3, "backoff": "exponential" },
  "fallback_agent": "talos"
}

How it works:

1. Task starts → timeout timer begins
2. If timeout expires → retry with backoff:
   • Exponential: 5s, 15s, 45s (multiply by 3 each retry)
   • Fixed: 10s, 10s, 10s (constant delay)
3. If all retries fail → use fallback_agent if configured
4. If no fallback → escalate to Zeus (user decision)

Partial results (partial_ok: true):

If a task times out but partial_ok is true, Zeus can use whatever results were produced and re-delegate the remaining scope.

---

Session Reuse

Tasks can resume previous sessions to avoid re-reading context:

{
  "session_resume": "hermes-1",
  "session_id": "hermes-2"
}

• session_id — set automatically when a task starts (alias: {agent}-{N})
• session_resume — set manually to continue from a previous session

Session aliases are tracked in-memory by Zeus during a session. Stale references auto-clean.

---

Example: Full Workflow

Zeus creates tasks for "Add Product Reviews":

TaskCreate({ subject: "Create reviews schema", owner: "Demeter" })
→ T-001

TaskCreate({ subject: "Implement POST /reviews", owner: "Hermes", blockedBy: ["T-001"] })
→ T-002

TaskCreate({ subject: "Implement GET /reviews", owner: "Hermes", blockedBy: ["T-001"] })
→ T-003

TaskCreate({ subject: "Build ReviewCard component", owner: "Aphrodite", blockedBy: ["T-001"] })
→ T-004

TaskCreate({ subject: "Integration tests", owner: "Hermes", blockedBy: ["T-002", "T-003", "T-004"] })
→ T-005

TaskList():
  T-001 [pending] Create reviews schema    blockedBy: []
  T-002 [pending] Implement POST /reviews  blockedBy: [T-001]
  T-003 [pending] Implement GET /reviews   blockedBy: [T-001]
  T-004 [pending] Build ReviewCard         blockedBy: [T-001]
  T-005 [pending] Integration tests        blockedBy: [T-002, T-003, T-004]

Execution:
  → T-001 runs (no blockers)
  → T-001 completes
  → T-002, T-003, T-004 unblock → run in parallel
  → All three complete
  → T-005 unblocks → runs
  → T-005 completes → all done

---

Wisdom Accumulation Integration

When a task completes, extract learnings and pass to the next task:

T-001 complete → extract learnings → store in learnings.md
T-002 starts → inject learnings.md → avoids repeating T-001 mistakes

---

Cleanup

After the feature is merged:

rm -rf .pantheon/tasks/T-*.json
rm -rf .pantheon/learnings/<feature>/

Tasks are temporary — they exist only for the duration of the feature implementation.