task-manager

Files (1)

• SKILL.md

SKILL.md (first lines)

# Task Manager — Persistent Task Orchestration

This skill introduces a **task management system** backed by `js-doc-store-server` that integrates with the subagent framework. Tasks are persistent objects that can be assigned to specific agents, executed in isolation, and tracked across sessions.

## Problem It Solves

| Problem | Solution |
|---------|----------|
| Ad-hoc subagent calls get lost | Tasks persist in `tasks` table |
| No visibility of what was delegated | Task list shows status, agent, result |
| No retry mechanism | Failed tasks can be re-executed |
| No batching | Parent/child tasks for complex workflows |
| No cross-session continuity | Server storage survives pi restarts |

## Schema

Table: `tasks`

| Field | Type | Description |
|-------|------|-------------|
| `id` | text | Unique task identifier |
| `title` | text | Short name |
| `description` | text | Detailed instructions |
| `status` | text | pending / in_progress / completed / failed / cancelled |
| `priority` | text | low / medium / high / critical |
| `agent` | text | Subagent name (scout, planner, worker, etc.) |
| `agent_scope` | text | user / project / both |
| `input` | text | Context/data passed to agent |
| `output` | text | Result from agent execution |
| `tags` | text | Comma-separated labels |
| `parent_id` | text | For subtasks |
| `conversation_id` | text | Link to persistent messages |
| `error_message` | text | If execution failed |
| `attempts` | number | Execution retries |
| `created_at` | text | ISO timestamp |
| `started_at` | text | ISO timestamp |
| `completed_at` | text | ISO timestamp |

## Tool: `task_manager`

```typescript
task_manager({
  action: "create",           // create | list | get | update | assign | execute | delete
  title: "Add auth middleware",
  description: "Implement JWT validation...",
  priority: "high",
  agent: "worker",
  input: "Current auth.ts is empty, see repo structure...",
  tags: "auth,security,sprint-3",
  parent_id: "task-parent-001"
})
```

### Actions

| Action | Required params | Description |
|--------|----------------|-------------|
| `create` | `title` | Creates pending task, returns ID |
| `list` | — | Lists tasks with optional filters |
| `get` | `id` | Full task details |
| `update` | `id` + fields | Modify title, status, output, etc. |
| `assign` | `id` + `agent` | Bind agent, validates agent exists |
| `execute` | `id` | Spawns subagent, saves result, updates status |
| `delete` | `id` | Remove task |

### Execute flow

```
task_manager({ action: "execute", id: "task-xxx" })
         │
         ├──► 1. Load task from server
         │         ├──► If no agent assigned → error
         │         └──► If task not found → error
         │
         ├──► 2. Resolve agent definition
         │         ├──► Try server table "agents"
         │         └──► Fallback to ~/.pi/agent/agents/*.md
         │
         ├──► 3. Spawn pi --mode json
         │         ├──► Agent markdown as system prompt
         │         └──► Task description + input as user prompt
         │
         ├──► 4. Capture JSONL output
         │         └──► Extract assistant text block
         │
         └──► 5. Update task in server
                   ├──► success → status: completed, output: text
                   └──► failure → status: failed, error_message: stderr
```

## Quick Workflow Examples

### Single task

```typescript
// 1. Create
const t = await task_manager({
  action: "create",
  title: "Refactor database connection",
  description: "Move DB config to environment variables",
  priority: "high",
  tags: "refactor,database"
});

// 2. Assign
await task_manager({ action: "assign", id: t.id, agent: "worker" });

// 3. Execute
await task_manager({ action: "execute", id: t.id });

// 4. Review result
await task_manager({ action: "get", id: t.id });
```

### Chain workflow via parent/child

```typescript
// Parent: plan
const plan = await task_manager({ action: "create", title: "Plan OAuth integration", agent: "planner" });

From MauricioPerera/pi-extension-data-architect, MIT.

More from MauricioPerera/pi-extension-data-architect