Deep Work: Long-Running Autonomous Projects

Deep Work is PocketPaw’s orchestration system for complex, multi-step projects. Describe what you want to build, and PocketPaw researches the domain, writes a product requirements document, breaks it into tasks with dependencies, assembles an agent team, and executes everything autonomously.

How It Works

Project Lifecycle

Planning Phases

The planner runs four sequential phases, each broadcasting progress events to the dashboard:

1. Research

Gathers domain knowledge before planning. Controlled by research_depth:

2. Product Requirements Document (PRD)

Generates a structured PRD with:

• Problem statement
• Scope (in/out)
• Functional requirements
• Non-goals
• Technical constraints

3. Task Breakdown

Decomposes the PRD into atomic tasks. Each task includes:

4. Team Assembly

Recommends the minimal set of AI agents needed. Each agent has a name, role, specialties, and backend. Agents are auto-assigned to tasks based on specialty overlap.

Dependency Scheduling

Tasks execute in dependency order using a topological sort (Kahn’s algorithm):

• Tasks with no blockers run first (concurrently)
• When a task completes, newly unblocked tasks dispatch automatically
• The scheduler validates the dependency graph for cycles and missing references before execution

Level 0: [t1, t2]        ← no dependencies, run in parallel
Level 1: [t3, t4]        ← depend only on level 0
Level 2: [t5]            ← depends on level 1

Task Types

Retry & Timeout

Tasks don’t just fail and stop — they fight through problems on their own.

Auto-Retry

Each task has a max_retries count (default: 1). When an agent task fails or times out, the executor checks whether retries remain. If so, it resets the task to ASSIGNED and re-dispatches it automatically. The retry_count field tracks how many attempts have been made.

Once retries are exhausted, the task moves to BLOCKED and waits for your attention. You can also manually retry any blocked task from the dashboard or API — manual retries bypass the max_retries limit.

Task Timeout

Set timeout_minutes on a task to enforce a hard execution time limit. The executor wraps the agent call in asyncio.wait_for — if the agent hasn’t finished within the window, it’s interrupted and treated the same as a failure (triggers retry if attempts remain, otherwise goes BLOCKED).

Leave timeout_minutes unset for tasks that genuinely need open-ended time, like deep research or large code generation.

Output Chaining

When an agent task completes, its full output is stored directly on the task.output field. Downstream tasks can reference this output as context — the executor builds each task’s prompt with deliverables from upstream dependencies already included.

This means later tasks in the dependency chain know what earlier tasks produced, without you having to wire anything up manually.

Cancellation

Cancel a running project when you need to pull the plug. Cancellation is a terminal state — once cancelled, the project can’t be resumed.

What happens when you cancel:

1. All currently executing tasks are stopped immediately
2. All pending and assigned tasks are marked SKIPPED
3. Tasks already completed keep their DONE status (work isn’t lost)
4. The project status changes to CANCELLED

You can’t cancel a project that’s already completed or already cancelled.

Usage

Starting a Project

User: Start a deep work project to build a REST API for a recipe management app
Agent: Starting Deep Work project... researching domain, writing PRD, decomposing tasks.

Or via the REST API:

curl -X POST http://localhost:8000/api/deep-work/start \
  -H "Content-Type: application/json" \
  -d '{"description": "Build a REST API for recipe management", "research_depth": "standard"}'

Reviewing the Plan

The dashboard shows:

• The generated PRD
• Task list with dependencies visualized as execution levels
• Estimated total time
• Recommended agent team

Controlling Execution

Skipping a task marks it as SKIPPED and unblocks dependents. Retrying resets a blocked task to ASSIGNED and re-dispatches it.

PawKit Templates

Deep Work projects can be packaged as PawKit templates — YAML configs that define a full Command Center with layout, automated workflows, user configuration, and bundled skills. The Deep Work engine becomes the “Project Orchestrator” Command Center, and domain experts can publish their own PawKits for others to install.

See Command Centers for the concept and PawKit Reference for the full YAML schema.

Project Directories

Each project gets a working directory at ~/pocketpaw-projects/{project_id}/. Agent tasks execute within this directory, and deliverables are saved there.

Recovery

If the server restarts during execution:

• Projects stuck in PLANNING are marked FAILED
• Projects in EXECUTING have their in-progress tasks reset and re-dispatched

WebSocket Events

The dashboard receives real-time updates:

Related