How to Use PM-Agent for Task Orchestration

Coordinate multi-step projects using PM-Agent’s case management and task delegation capabilities.

Note: PM-Agent orchestration is implemented via just recipes. Use these for case management.

Quick Start (just recipes)

1
2
3
4
5
6
7
8

# Create a new case
just pm-case-create "Feature: User Authentication"

# List all cases
just pm-case-list

# Check case status
just pm-case-status case-2026-042

Prerequisites

Conceptual Workflow

1. Define a Case

Cases represent work with a clear desired outcome but flexible execution path:

1
2
3
4
5
6
7
8
9
10
11
12
13

# case-definition.yaml
case:
  title: "Feature Implementation: User Authentication"
  description: "Implement OAuth2 login flow"
  desiredOutcome: "Users can login via Google/GitHub"
  
  timeline:
    startDate: "2026-01-06"
    targetDate: "2026-01-15"
    
  semanticRefs:
    - conceptId: "sea:Feature"
    - conceptId: "domain:Authentication"

2. Break Down Tasks

Use vertical slicing to create atomic, delegatable tasks:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

tasks:
  - id: "task-101"
    name: "Research OAuth2 providers"
    agent: "research-agent"
    dependencies: []
    successCriteria:
      - "Provider comparison documented"
      - "Security considerations noted"

  - id: "task-102"
    name: "Create ADR for auth approach"
    agent: "doc-agent"
    dependencies: ["task-101"]
    
  - id: "task-103"
    name: "Implement OAuth2 flow"
    agent: "code-agent"
    dependencies: ["task-102"]

3. Execution Patterns

Sequential: Tasks run one after another

1
2
3

execution:
  strategy: "sequential"
  tasks: ["task-101", "task-102", "task-103"]

Parallel: Independent tasks run concurrently

1
2
3
4

execution:
  strategy: "parallel"
  maxConcurrency: 3
  tasks: ["task-101", "task-102"]

DAG: Respect dependency graph

1
2
3

execution:
  strategy: "dag"
  # task-103 waits for task-101 AND task-102

4. Track Progress

Monitor using CMMN stage transitions:

1

intake → planning → execution → verification → closure

Each task moves through:

1

pending → in_progress → blocked → completed

Manual Workflow (Current)

Until PM-Agent automation is implemented, use manual case management:

  1. Create case file: cases/case-2026-001.yaml
  2. Track in task.md: Use markdown checklists
  3. Update status: Edit case file as work progresses
  4. Use worktrees: just cycle-start for isolated work

Best Practices

  1. Atomic tasks - Break work into verifiable units
  2. Clear success criteria - Define measurable outcomes
  3. Minimal context - Only pass relevant files to sub-agents
  4. DAG over sequential - Use dependency graphs for parallelism