Phase Plan Skill

Role: Domain-agnostic workflow skill for transforming solution outline deliverables into optimized, executable tasks. Loaded by pm-workflow:task-plan-agent.

Key Pattern: Reads deliverables with metadata and profiles list from solution_outline.md, creates one task per deliverable per profile (1:N mapping), resolves skills from architecture based on module + profile, creates tasks with explicit skill lists. No aggregation - each deliverable maps to exactly one task per profile.

Contract Compliance

MANDATORY: All tasks MUST follow the structure defined in the central contracts:

Contract	Location	Purpose
Task Contract	`pm-workflow:manage-tasks/standards/task-contract.md`	Required task structure and optimization workflow

CRITICAL - Steps Field:

•The steps field MUST contain file paths from the deliverable's Affected files section
•Steps must NOT be descriptive text (e.g., "Update AuthController.java" is INVALID)
•Validation rejects tasks with non-file-path steps

Input

Parameter	Type	Required	Description
`plan_id`	string	Yes	Plan identifier

Output

toon

status: success | error
plan_id: {echo}
summary:
  deliverables_processed: N
  tasks_created: M
  parallelizable_groups: N
tasks_created[M]: {number, title, deliverable, depends_on}
execution_order: {parallel groups}
message: {error message if status=error}

Workflow

Step 1: Load All Deliverables

Read the solution document to get all deliverables with metadata:

bash

python3 .plan/execute-script.py pm-workflow:manage-solution-outline:manage-solution-outline \
  list-deliverables \
  --plan-id {plan_id}

For each deliverable, extract:

•metadata.change_type, metadata.execution_mode
•metadata.domain (single value)
•metadata.module (module name from architecture)
•metadata.depends
•profiles (list: implementation, module_testing)
•affected_files
•verification

Step 2: Build Dependency Graph

Parse depends field for each deliverable:

•Identify independent deliverables (depends: none)
•Identify dependency chains
•Detect cycles (INVALID - reject with error)

Step 3: Create Tasks from Profiles (1:N Mapping)

For each deliverable, create one task per profile in its profiles list:

code

For each deliverable D:
  1. Query architecture: module --name {D.module}
  For each profile P in D.profiles:
    2. Extract skills: module.skills_by_profile.{P}
       - Load all `defaults` directly into task.skills
       - For each `optional`, evaluate its `description` against deliverable context
       - Include optionals whose descriptions match the task requirements
    3. Create task with profile P and resolved skills
    4. If P = module_testing, add depends on implementation task

Query architecture:

bash

python3 .plan/execute-script.py plan-marshall:analyze-project-architecture:architecture \
  module --name {deliverable.module} \
  --trace-plan-id {plan_id}

Skills Resolution (new defaults/optionals structure):

The architecture returns skills in structured format:

toon

skills_by_profile:
  implementation:
    defaults[1]{skill,description}:
      - pm-plugin-development:plugin-architecture,"Architecture principles..."
    optionals[2]{skill,description}:
      - pm-plugin-development:plugin-script-architecture,"Script development standards..."
      - plan-marshall:ref-toon-format,"TOON format knowledge for output specifications - use when migrating to/from TOON"

Resolution Logic:

•Load ALL defaults directly into task.skills (always required)
•
For EACH optional, match its description against deliverable context:
- •Deliverable title
- •Change type (feature, fix, refactor, etc.)
- •Affected files and their types
- •Deliverable description
•Include optional if description indicates relevance to the task
•Log reasoning for each optional skill decision

Example Reasoning (for JSON→TOON migration task):

code

Optional: plan-marshall:ref-toon-format
Description: "TOON format knowledge for output specifications - use when migrating to/from TOON"
Deliverable: "Migrate JSON outputs to TOON format"
Match: YES - description mentions "migrating to/from TOON", deliverable is TOON migration
→ INCLUDE

Optional: pm-plugin-development:plugin-script-architecture
Description: "Script development standards covering implementation patterns, testing, and output contracts"
Deliverable: "Migrate JSON outputs to TOON format"
Match: YES - this is a script output change, needs output contract standards
→ INCLUDE

1:N Task Creation Flow:

code

solution_outline.md                        TASK-*.toon (created by task-plan)
┌────────────────────────────┐             ┌────────────────────────────┐
│ **Metadata:**              │             │ TASK-001-IMPL              │
│ - domain: java             │             │ profile: implementation    │
│ - module: auth-service     │  ───────►   │ skills: [java-core,        │
│                            │  (1:N)      │          java-cdi]         │
│ **Profiles:**              │             ├────────────────────────────┤
│ - implementation           │  ───────►   │ TASK-002-TEST              │
│ - module_testing           │             │ profile: module_testing    │
│                            │             │ skills: [java-core,        │
└────────────────────────────┘             │          junit-core]       │
                                           │ depends: TASK-001-IMPL     │
                                           └────────────────────────────┘

Log skill resolution (for each task created):

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  work {plan_id} INFO "[SKILL] (pm-workflow:phase-4-plan) Resolved skills for TASK-{N} from {module}.{profile}: defaults=[{defaults}] optionals_selected=[{optionals}]"

Step 4: Create Tasks

For each deliverable, create tasks using heredoc (one task per profile):

bash

python3 .plan/execute-script.py pm-workflow:manage-tasks:manage-tasks add \
  --plan-id {plan_id} <<'EOF'
title: {task title from deliverable}
deliverable: {deliverable_number}
domain: {domain from deliverable}
profile: {profile from deliverable}
phase: 5-execute
description: |
  {combined description}

steps:
  - {file1}
  - {file2}
  - {file3}

depends_on: TASK-1, TASK-2

skills:
  - {skill1 from architecture}
  - {skill2 from architecture}

verification:
  commands:
    - {cmd1}
  criteria: {criteria}
EOF

MANDATORY - Log each task creation:

bash

python3 .plan/execute-script.py plan-marshall:manage-logging:manage-log \
  work {plan_id} INFO "[ARTIFACT] (pm-workflow:phase-4-plan) Created TASK-{N}: {title}"

Key Fields:

•domain: Single domain from deliverable
•profile: implementation or module_testing (determines workflow skill at execution)
•skills: Domain skills only (system skills loaded by agent)
•steps: File paths from Affected files (NOT descriptive text)

Step 5: Determine Execution Order

Compute parallel execution groups:

toon

execution_order:
  parallel_group_1: [TASK-1, TASK-3]    # No dependencies
  parallel_group_2: [TASK-2, TASK-4]    # Both depend on group 1
  parallel_group_3: [TASK-5]            # Depends on group 2

Parallelism rules:

•Tasks with no depends_on go in first group
•Tasks depending on same prior tasks can run in parallel
•Sequential dependencies remain sequential

Step 6: Record Issues as Lessons

On ambiguous deliverable or planning issues:

bash

python3 .plan/execute-script.py plan-marshall:manage-lessons:manage-lesson add \
  --component "pm-workflow:phase-4-plan" \
  --category improvement \
  --title "{issue summary}" \
  --detail "{context and resolution approach}"

Valid categories: bug, improvement, anti-pattern

Step 7: Return Results

Output:

toon

status: success
plan_id: {plan_id}

summary:
  deliverables_processed: {N}
  tasks_created: {M}
  parallelizable_groups: {count of independent task groups}

tasks_created[M]{number,title,deliverable,depends_on}:
1,Implement UserService,1,none
2,Test UserService,1,TASK-1
3,Implement UserRepository,2,none
4,Test UserRepository,2,TASK-3

execution_order:
  parallel_group_1: [TASK-1, TASK-3]
  parallel_group_2: [TASK-2, TASK-4]

lessons_recorded: {count}

Skill Resolution Guidelines

Skills are resolved from architecture based on module + profile:

Scenario	Behavior
Single profile	Query `architecture.module --name {module}`, extract `skills_by_profile.{profile}`
Multiple profiles	Create one task per profile, each with its own resolved skills
Module not in architecture	Error - module must exist in project architecture
Profile not in module	Error - profile must exist in `module.skills_by_profile`

Error Handling

Circular Dependencies

If deliverable dependencies form a cycle:

•Error: "Circular dependency detected: D1 -> D2 -> D1"
•Do NOT create tasks

Module Not in Architecture

If deliverable.module is not found in architecture:

•Error: "Module '{module}' not found in architecture - run architecture discovery"
•Record as lesson learned

Profile Not in Module

If a profile from deliverable.profiles is not in module.skills_by_profile:

•Error: "Profile '{profile}' not found in {module}.skills_by_profile"
•Record as lesson learned

Ambiguous Deliverable

If deliverable metadata incomplete:

•Generate task with defaults
•Add lesson-learned for future reference
•Note ambiguity in task description

Integration

Invoked by: pm-workflow:task-plan-agent (thin agent)

Script Notations (use EXACTLY as shown):

•pm-workflow:manage-solution-outline:manage-solution-outline - Read deliverables (list-deliverables, read)
•plan-marshall:analyze-project-architecture:architecture - Resolve skills (module --name {module})
•pm-workflow:manage-tasks:manage-tasks - Create tasks (add --plan-id X <<'EOF' ... EOF)
•plan-marshall:manage-lessons:manage-lesson - Record lessons on issues (add)

Consumed By:

•pm-workflow:task-execute-agent - Reads tasks and executes them