Planning

@alphacro/agent-planning

Package: packages/agent-planning

Task DAG plugin: tasks, dependencies, and task-scoped tool decoration.

Overview

@alphacro/agent-planning: lifts the variants-editor task DAG into a self-contained Plugin. Composing this plugin contributes:

• 7 task tools (list/get_next/upsert/complete/cancel + dependency upsert/delete).
• A planning-only PlanningStore (state + event log) the host subscribes to for broadcast.
• 4 hooks: DecorateToolSchema adds task_ids to every non-planning tool while tasks are active; PreToolUse validates task_ids and auto-starts pending tasks on first reference; PostToolUse rolls up task.progress; UserPromptSubmit surfaces the active task list to the model as a context decoration (not a system-prompt fragment — the module is still named decorate-system-prompt.ts for historical reasons).
• 4 RPC methods so the SPA can drive the same store.

The plugin is Layer-2 portable: no Cloudflare types, no SDK coupling beyond @alphacro/agent-core / @alphacro/agent-tools.

Contributions

Contribution	Declared
Tools	✅
Hooks	✅
Sub-agents	❌
Slash commands	❌
HTTP routes	❌
RPC methods	✅
Workflows	❌
Permissions	❌
Tool cards	❌
State slice	✅
Reducer	✅
Session start handler	❌
Session end handler	❌
Startup phase	❌
Dependencies	❌

Tools

• cancel_task
• complete_task
• delete_task_dependency
• get_next_tasks
• list_tasks
• upsert_task_dependency
• upsert_task

Hooks

• DecorateToolSchema
• PreToolUse
• PostToolUse
• DecorateSystemPrompt

Package README

Defines the Task data structure and the planning reducer used by the agent runtime. This package is the single source of truth for what the agent will do and which requirements each task addresses.

Key concepts

• A Task is the agent’s work item. It points back to the Requirements it fulfils via requirementIds, creating a durable link between work and intent.
• Every tool call the agent makes is tagged with task IDs, creating a traceable trail of work — you can always answer “which task caused this side effect?”
• Tasks are managed by a reducer (reducer.ts) and exposed to the UI via hooks.

How Tasks relate to Requirements

Requirement  ←──  requirementIds  ──  Task
    "what it should do"                 "what the agent will do"

A Task says “I’m going to do X in order to satisfy Requirement Y.” Multiple Tasks can address the same Requirement, and a single Task may address multiple Requirements.

Data structures (summary)

Type	Purpose
Task	Work item with requirementIds linking back to requirements
PlanningState	The full task store managed by the reducer

See src/state.ts for the full type definitions.

Source

• Plugin factory: packages/agent-planning/src/plugin.ts