php-agentic/changelog/2026/jan/agentic-tasks-readme.md

Agentic Task System

MCP-powered workspace for persistent work plans that survive context limits and enable multi-agent collaboration.

Why this exists

• Context persistence - Work plans persist across Claude sessions, surviving context window limits
• Multi-agent collaboration - Handoff support between different agents with shared state
• Checkpoint verification - Phase gates ensure work is complete before progressing
• Structured planning - Break complex tasks into phases with dependencies

Location

app/Models/Agent/AgentPlan.php
app/Models/Agent/AgentPhase.php
app/Models/Agent/AgentSession.php
app/Models/Agent/WorkspaceState.php
app/Console/Commands/Agent/McpAgentServerCommand.php

Basic usage

# Create a new plan
php artisan plan:create my-feature --title="Implement Feature X"

# Import from markdown
php artisan plan:create my-plan --import=PLAN.md --activate

# List all plans
php artisan plan:list
php artisan plan:list --status=active

# Show plan details
php artisan plan:show my-plan
php artisan plan:show my-plan --markdown

# Check phase completion (checkpoint)
php artisan plan:check my-plan
php artisan plan:check my-plan 1  # Check specific phase

# Manage phases
php artisan plan:phase my-plan 1 --status=in_progress
php artisan plan:phase my-plan 1 --add-task="Complete the migration"
php artisan plan:phase my-plan 1 --complete-task=0

Key methods

AgentPlan

use Mod\Agentic\Models\AgentPlan;

// Create a plan
$plan = AgentPlan::create([
    'slug' => 'my-feature',
    'title' => 'Implement Feature X',
    'status' => AgentPlan::STATUS_ACTIVE,
]);

// Get current phase
$phase = $plan->getCurrentPhase();
// Returns: AgentPhase or null

// Check completion
$plan->checkAllPhasesComplete();
// Returns: bool

AgentPhase

use Mod\Agentic\Models\AgentPhase;

// Start a phase
$phase->start();
// Returns: self (status changed to in_progress)

// Complete a phase (with transaction protection)
$phase->complete();
// Returns: self (status changed to completed, plan auto-completes if all done)

// Check if phase can start (dependencies met)
$phase->canStart();
// Returns: bool

WorkspaceState

use Mod\Agentic\Models\WorkspaceState;

// Store shared state
WorkspaceState::setValue($plan, 'api_findings', ['endpoints' => 12]);

// Retrieve state
$value = WorkspaceState::getValue($plan, 'api_findings');
// Returns: array or null

Example: Checkpoint pattern

The checkpoint pattern ensures agents verify previous work before progressing:

Agent: "Starting Phase 3"
    ↓
MCP: phase_check(plan_slug, phase=2)
    ↓
Returns: {
  "complete": false,
  "remaining_tasks": ["Task 2.4", "Task 2.5"],
  "message": "Phase 2 not complete. 2 tasks remaining."
}
    ↓
Agent: "Completing remaining Phase 2 tasks first..."

Configuration

MCP server configuration for Claude Code:

{
  "mcpServers": {
    "hosthub-agent": {
      "command": "php",
      "args": ["artisan", "mcp:agent-server"],
      "cwd": "/path/to/host.uk.com"
    }
  }
}

How it works

1. Plan created with phases (via CLI or MCP)
2. Agent starts session and binds to plan
3. Agent works through phases, logging actions
4. Checkpoint verification before phase transitions
5. Workspace state shared between agents
6. Handoff notes preserved for context continuity

MCP Tools

Tool	Purpose
plan_create	Create new plan with phases
plan_get	Get plan by slug with all phases
plan_list	List plans (optionally filtered)
plan_update	Update plan status/metadata
phase_update	Update phase status
phase_check	Verify phase completion
task_add	Add task to a phase
task_complete	Mark task done
session_start	Begin agent session
session_log	Log action to session
session_artifact	Log file artifact
session_handoff	Prepare for agent handoff
session_resume	Resume from previous session
session_complete	Mark session completed
state_set	Store workspace state
state_get	Retrieve workspace state
state_list	List all state keys
state_delete	Delete state key

MCP Resources

URI	Purpose
hosthub://plans	List of all work plans
hosthub://plans/{slug}	Full plan as markdown
hosthub://plans/{slug}/phase/{n}	Phase tasks as checklist
hosthub://state/{plan}/{key}	Specific state value
hosthub://sessions/{id}	Session handoff context

Related services

• Task model - Simple task tracking (different purpose)
• ContentTask model - Content generation tasks

See also: doc/dev-feat-docs/agentic-tasks/PORTING_PLAN.md for implementation details.