home / skills / mkalhitti-cloud / universal-or-strategy / universal-tasks

universal-tasks skill

safe

/.agent/skills/universal-tasks

This skill orchestrates persistent, dependency-aware tasks across sessions to coordinate multi-agent work and track progress.

npx playbooks add skill mkalhitti-cloud/universal-or-strategy --skill universal-tasks

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

2.9 KB

---
name: universal-tasks
description: Orchestrates complex, long-running projects across multiple sessions or sub-agents using the "Task" primitive. Replaces simple Todos with persistent, dependency-aware Tasks stored in the file system. Use when coordinating architectural changes, multi-step migrations, or any work requiring multi-agent collaboration and state persistence.
---

# Universal Tasks Skill

## Purpose
"Unhobble" agents by providing a persistent, dependency-aware Task system. This skill allows agents to track progress across context windows, sessions, and different models (Opus, Sonnet, Flash) while respecting project hierarchy and technical blockers.

## Core Primitive: The Task
A **Task** is more than a Todo. It contains:
- **ID**: Unique identifier (e.g., `V9_001`).
- **Status**: `pending`, `in_progress`, `completed`, `blocked`.
- **Dependencies**: IDs of tasks that MUST be completed before this one starts.
- **Blockers**: External conditions (e.g., `market_closed`).
- **Assigned Model**: The best AI for the job (Opus for logic, Flash for I/O).

## Workflow: Multi-Session Collaboration

### 1. Initialization
When starting a project or a new session, read the **Task List**:
- Default location: `.agent/TASKS/MASTER_TASKS.json`
- Env Var: `CLAUDE_CODE_TASK_LIST_ID` (if set, use that specific list).

### 2. Validation (MANDATORY)
Before starting ANY task, validate its dependencies and ownership using the bundled script:
```bash
python .agent/skills/universal-tasks/scripts/validate_task.py <TASK_ID> [AGENT_ID]
```

### 3. Discovery & Claiming
Agents must follow the [Discovery Protocol](references/discovery_protocol.md) to claim tasks atomically. This prevents duplicate work.
```bash
python .agent/skills/universal-tasks/scripts/sync_tasks.py <TASK_ID> in_progress <AGENT_ID>
```

### 4. Synchronization
When status changes, sync the update to ensure other agents/sessions see it. The system uses `.lock` files to prevent race conditions during concurrent writes.
```bash
python .agent/skills/universal-tasks/scripts/sync_tasks.py <TASK_ID> <STATUS> [AGENT_ID]
```

## Guidelines for Agents
- **Don't skip dependencies**: The task system is designed to prevent "race conditions" where an agent implements code before the architecture is ready.
- **Escalate appropriately**: If a `pending` task is assigned to `opus_4.5`, don't attempt it with `gemini_flash` if it involves complex reasoning.
- **Update on completion**: Always sync status to `completed` immediately upon verification.

## Implementation Details
- **Schema**: See [TASKS_SCHEMA.md](references/tasks_schema.md) for JSON structure.
- **Storage**: Tasks are stored in the project's `.agent/TASKS` directory (locally) or `~/.claude/tasks` (globally).

---

## Related Skills
- [delegation-bridge](../delegation-bridge/SKILL.md) - For cost-efficient file ops and deployment.
- [antigravity-core](../antigravity-core/SKILL.md) - For collaboration protocols.

Overview

This skill orchestrates complex, long-running projects across multiple sessions and sub-agents using a persistent, dependency-aware Task primitive. It replaces ephemeral todos with filesystem-backed Tasks that track status, dependencies, blockers, and the best-assigned model for each piece of work. Use it to coordinate multi-agent collaboration while preserving state across model context windows and sessions.

How this skill works

Tasks are JSON records stored under the agent task directory and include ID, status, dependency list, blockers, and assigned model. Agents validate dependencies before claiming work, claim tasks atomically via a discovery protocol, and synchronize status updates using lock files to avoid race conditions. A small set of scripts enforces validation, claiming, and sync operations so multiple agents can collaborate reliably.

When to use it

Coordinating architectural changes that span multiple commits and sessions.
Running multi-step data or database migrations that must follow a strict order.
Orchestrating multi-agent feature development where tasks depend on each other.
Maintaining long-running experiments or simulations that outlive a single model context.
Enforcing model-specific assignments when tasks require particular reasoning or I/O strengths.

Best practices

Always run dependency validation before attempting a task to avoid races and incorrect assumptions.
Claim tasks atomically using the discovery/claim script to prevent duplicate work.
Respect the assigned model: escalate or reassign rather than attempting unsuitable models.
Sync status immediately on verification to keep all agents in agreement.
Store the canonical task list in the configured task directory and back it up with project versioning.

Example use cases

A phased migration where schema changes must complete before ingestion code is updated.
Breaking a large refactor into dependent Tasks, each assigned to the model best suited for design or implementation.
Coordinating trading-strategy adjustments where market-open/closed blockers prevent execution.
Delegating environment setup, tests, and deployment steps across sub-agents with clear dependencies.
Tracking long-running research experiments that require human review between stages.

FAQ

Where are Tasks stored by default?

Tasks are stored in the project task directory by default; a typical location is .agent/TASKS/MASTER_TASKS.json, with an option to use a custom list via an environment variable.

What should I do if a task is blocked by an external condition?

Record the external condition as a blocker on the Task, leave status as blocked, and update status when the blocker clears so dependent tasks can proceed.