Plugin Task Plan Skill

Role: Domain planning skill for plugin development tasks. Transforms solution outline deliverables into optimized, executable tasks that delegate to existing skills for implementation.

Key Pattern: Skill delegation with optimization - reads deliverables with metadata from solution_outline.md, applies aggregation/split analysis, creates tasks with delegation blocks and dependencies.

Contract Compliance

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

Contract	Location	Purpose
Task Contract	plan-marshall:manage-tasks/standards/task-contract.md	Task structure and optimization workflow

Non-compliant tasks will be rejected by validation.

CRITICAL: The steps field MUST contain file paths the parent deliverable declares — under Affected files:, or under the Files expected to mutate: / Files to survey: pair a survey-scope deliverable declares instead:

# CORRECT - file paths from deliverable
steps:
  - marketplace/bundles/plan-marshall/agents/execution-context.md
  - marketplace/bundles/plan-marshall/skills/phase-3-outline/SKILL.md

# WRONG - descriptive text (violates contract)
steps[2]{number,target,status}:
1,Convert execution-context outputs,pending
2,Convert phase-3-outline skill outputs,pending

The steps field lists FILES TO MODIFY, not progress tracking entries.

Operation: plan

Input:

Parameter	Type	Required	Description
plan_id	string	Yes	Plan identifier
deliverable_number	number	No	Single deliverable number (omit to process all deliverables)

Process:

Step 1: Load All Deliverables

Read the solution document to get all deliverables with metadata:

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

For each deliverable, extract:

• metadata.change_type, metadata.execution_mode, metadata.domain
• metadata.suggested_skill, metadata.suggested_workflow
• metadata.context_skills, metadata.depends
• 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)

Step 3: Analyze for Aggregation

For each pair of deliverables, check if they can be aggregated:

• Same change_type?
• Same suggested_skill?
• Same execution_mode (must be automated)?
• Combined file count < 10?
• NO dependency between them? (CRITICAL - cannot aggregate if one depends on other)

Step 4: Analyze for Splits

For each deliverable, check for split requirements:

• execution_mode: mixed → MUST split
• Different concerns within → SHOULD split
• File count > 15 → CONSIDER splitting

Step 5: Log Optimization Decisions (REQUIRED)

After analyzing each deliverable or deliverable pair, log the decision:

# If aggregating deliverables
python3 .plan/execute-script.py plan-marshall:manage-logging:manage-logging \
  work --plan-id {plan_id} --level INFO --message "[OPTIMIZATION] (pm-plugin-development:plugin-task-plan) Aggregating D{N}+D{M}: same skill ({skill}), no inter-dependency"

# If keeping deliverable separate
python3 .plan/execute-script.py plan-marshall:manage-logging:manage-logging \
  work --plan-id {plan_id} --level INFO --message "[OPTIMIZATION] (pm-plugin-development:plugin-task-plan) Keeping D{N} separate: {reason}"

# If splitting deliverable
python3 .plan/execute-script.py plan-marshall:manage-logging:manage-logging \
  work --plan-id {plan_id} --level INFO --message "[OPTIMIZATION] (pm-plugin-development:plugin-task-plan) Splitting D{N}: execution_mode=mixed"

This logging is REQUIRED for audit trail and debugging.

Step 6: Create Optimized Tasks

For aggregated deliverables or single deliverables, create tasks using the three-step path-allocate flow: (1) prepare-add allocates a scratch TOON file under <plan>/work/pending-tasks/, (2) the skill writes the task definition to that path with the Write tool, (3) commit-add validates and creates TASK-NNN.json. No multi-line content crosses the shell boundary.

CRITICAL: The steps field MUST contain file paths copied from the deliverable's declared file surface — under Affected files:, or under the Files expected to mutate: / Files to survey: pair a survey-scope deliverable declares instead.

# Step 1: allocate a scratch path
python3 .plan/execute-script.py plan-marshall:manage-tasks:manage-tasks \
  prepare-add --plan-id {plan_id}
# → returns {path: /abs/.../work/pending-tasks/default.toon}

# Step 2: Write tool writes the TOON task definition to the returned path, e.g.:
#   title: {Action Verb} {Target}: {Scope}
#   deliverable: {n}
#   domain: plan-marshall-plugin-dev
#   phase: 5-execute
#   description: {combined description}
#   steps:
#     - marketplace/bundles/{bundle}/agents/{file1}.md
#     - marketplace/bundles/{bundle}/agents/{file2}.md
#   depends_on: {TASK-N | none}
#   delegation:
#     skill: {suggested_skill}
#     workflow: {suggested_workflow}
#     context_skills: {context_skills - MUST include even if empty []}
#   verification:
#     commands:
#       - {verification.command}
#     criteria: {verification.criteria}

# Step 3: commit — validates the file and creates TASK-NNN.json
python3 .plan/execute-script.py plan-marshall:manage-tasks:manage-tasks \
  commit-add --plan-id {plan_id}

Field mapping from deliverable to task:

Deliverable Field	Task Field	Required
Affected files: list (or the Files expected to mutate: / Files to survey: pair)	steps: list (copy file paths directly)	Yes
metadata.suggested_skill	delegation.skill	Yes
metadata.suggested_workflow	delegation.workflow	Yes
metadata.context_skills	delegation.context_skills	Yes (even if empty [])
metadata.depends	Used to compute depends_on	Yes
Verification.Command	verification.commands	Yes
Verification.Criteria	verification.criteria	Yes

CRITICAL: The context_skills field MUST always be included in the delegation block, even when empty. Tasks without this field violate the task-contract and will fail validation.

Example with real paths:

# Step 1: allocate
python3 .plan/execute-script.py plan-marshall:manage-tasks:manage-tasks \
  prepare-add --plan-id migrate-json-to-toon

# Step 2: Write tool writes the following TOON body to the returned path:
#   title: Migrate plan-marshall Agents to TOON Format
#   deliverable: 2
#   domain: plan-marshall-plugin-dev
#   phase: 5-execute
#   description: Convert all JSON output blocks to TOON format in plan-marshall phase components.
#   steps:
#     - marketplace/bundles/plan-marshall/agents/execution-context.md
#     - marketplace/bundles/plan-marshall/skills/phase-3-outline/SKILL.md
#     - marketplace/bundles/plan-marshall/skills/phase-4-plan/SKILL.md
#     - marketplace/bundles/plan-marshall/skills/phase-5-execute/SKILL.md
#   depends_on: TASK-1
#   delegation:
#     skill: pm-plugin-development:plugin-maintain
#     workflow: update-component
#     context_skills: []
#   verification:
#     commands:
#       - python3 .plan/execute-script.py plan-marshall:manage-architecture:architecture search --content --pattern '^\x60\x60\x60json'
#     criteria: count is 0 over clean coverage (client-api.md § search, "Complete-coverage rule")

# Step 3: commit
python3 .plan/execute-script.py plan-marshall:manage-tasks:manage-tasks \
  commit-add --plan-id migrate-json-to-toon

The fence in that verification pattern is written as the regex escape \x60, not as a literal backtick, and the call therefore drops --literal. This is deliberate and MUST be preserved: the R1 shell-construct rule scans a substitution view that masks single-quoted spans ONLY — a backtick stays live inside double quotes and in unquoted context — so a literal backtick would make the command's R1 verdict depend on how the --pattern argument happens to be quoted (inside this command's single quotes it would be inert data; under any other quoting it would fire the backtick substitution check). The escaped form keeps the command string free of the backtick character in every quoting context, so the verdict cannot change with the quoting. Because --literal is dropped, the pattern stays in regex mode and the ^ anchor is per line (re.MULTILINE), so the pattern reaches a fence opening any line of the file. See manage-architecture/standards/client-api.md § search.

Step 7: Record Issues as Lessons

On ambiguous deliverable or planning issues, first run the canonical three-gate lesson-creation policy in marketplace/bundles/plan-marshall/skills/manage-lessons/standards/lesson-creation-policy.md — Gate 1 (dedup), Gate 2 (active-plan check), Gate 3 (create). The two-step path-allocate flow below is Gate 3, reached only when Gates 1 and 2 both clear; when Gate 1 returns merge_into / already_closed or Gate 2 finds a covering active plan, extend the existing lesson or fold into the plan instead of allocating a new one. Do not restate the gate mechanics — follow the standard.

When the gates clear, follow the two-step path-allocate flow:

1. Allocate a lesson file and capture the returned path:

python3 .plan/execute-script.py plan-marshall:manage-lessons:manage-lessons add \
  --component "pm-plugin-development:plugin-task-plan" \
  --category improvement \
  --title "{issue summary}"

2. Parse path from the output and write the lesson body (context + resolution approach, with ## sections as needed) directly to that path via the Write tool. This is the single supported API — there is no --detail inline form.

Valid categories: bug, improvement, anti-pattern

Step 8: Return Results

Output:

status: success
plan_id: {plan_id}

optimization_summary:
  deliverables_processed: {N}
  tasks_created: {M}
  aggregations: {count of deliverable groups}
  splits: {count of split deliverables}

tasks_created[M]{number,title,deliverables,depends_on}:
1,Create skill: java-logging-patterns,[1],none
2,Update plugin-maintain,[2 3],TASK-1
3,Refactor bundle structure,[4],none

lessons_recorded: {count}

---

Delegation Mapping

When creating tasks, map from deliverable metadata to stdin TOON fields:

Deliverable Metadata	TOON Field
domain	domain:
suggested_skill	delegation: skill:
suggested_workflow	delegation: workflow:
context_skills	delegation: context_skills: (merged from all aggregated deliverables)
affected_files	steps: (one per file)
verification.command	verification: commands: (may consolidate)
verification.criteria	verification: criteria:

Plugin-Specific Skill Mapping

Change Type	Component Type	Skill	Workflow
create	skill	pm-plugin-development:plugin-create	create-skill
create	command	pm-plugin-development:plugin-create	create-command
create	agent	pm-plugin-development:plugin-create	create-agent
create	bundle	pm-plugin-development:plugin-create	create-bundle
modify	any	pm-plugin-development:plugin-maintain	update-component
refactor	any	pm-plugin-development:plugin-maintain	refactor-structure
migrate	format	pm-plugin-development:plugin-maintain	update-component
delete	any	pm-plugin-development:plugin-maintain	remove-component

---

Task Generation Patterns

These patterns show how to create tasks for different operation types. Note that steps always contains FILE PATHS.

Create Component Task

Deliverable: "Create new {skill|command|agent} for {purpose}"

The steps field lists files that WILL BE CREATED:

title: Create skill: java-logging-patterns
steps:
  - marketplace/bundles/pm-dev-java/skills/java-logging-patterns/SKILL.md
delegation:
  skill: pm-plugin-development:plugin-create
  workflow: create-skill

Modify Component Task

Deliverable: "Update {component} to {change description}"

The steps field lists existing files to MODIFY:

title: Update plugin-maintain Skill
steps:
  - marketplace/bundles/pm-plugin-development/skills/plugin-maintain/SKILL.md
delegation:
  skill: pm-plugin-development:plugin-maintain
  workflow: update-component

Migrate Task (Multiple Files)

Deliverable: "Migrate {components} to {new format}"

The steps field lists ALL files to migrate (copied from the declared file surface — Affected files, or the survey-scope pair):

title: Migrate plan-marshall Phase Components to TOON Format
steps:
  - marketplace/bundles/plan-marshall/agents/execution-context.md
  - marketplace/bundles/plan-marshall/skills/phase-3-outline/SKILL.md
  - marketplace/bundles/plan-marshall/skills/phase-4-plan/SKILL.md
  - marketplace/bundles/plan-marshall/skills/phase-5-execute/SKILL.md
delegation:
  skill: pm-plugin-development:plugin-maintain
  workflow: update-component

Script Task (Special Case)

Scripts are created within skills. The steps lists the script file AND its test:

title: Create script: manage-references
steps:
  - marketplace/bundles/plan-marshall/skills/manage-references/scripts/manage-references.py
  - test/plan-marshall/manage-references/test_manage_references.py
delegation:
  skill: pm-plugin-development:plugin-create
  workflow: create-skill

---

Parameter Extraction

When analyzing deliverables, extract these parameters:

For Create Operations

Parameter	Source
bundle	Explicit in deliverable OR inferred from context
name	Explicit in deliverable OR derived from purpose
description	Extracted from deliverable body
type	Component-specific (agent type, skill type, etc.)

For Modify Operations

Parameter	Source
component_path	Explicit path OR resolve from component name
improvements	Description from deliverable body

---

Multi-Task Deliverables

Some deliverables require multiple tasks in sequence:

Skill with Scripts

TASK-1: Create skill structure
  - Delegate to: plugin-create → create-skill

TASK-2: Create script(s)
  - Create Python script in skill/scripts/
  - Add test file
  - Update SKILL.md

Command with New Skill

TASK-1: Create supporting skill
  - Delegate to: plugin-create → create-skill

TASK-2: Create command
  - Delegate to: plugin-create → create-command
  - Reference skill from TASK-1

---

Task Dependencies

When creating multiple tasks:

Dependency	Ordering
Scripts within skill	Create skill first, then scripts
Command referencing skill	Create skill first
Agent referencing skill	Create skill first
Refactor before create	Complete refactor first

---

Error Handling

Ambiguous Deliverable

If deliverable doesn't specify:

• Target bundle → Ask for clarification
• Component type → Infer from keywords or ask
• Operation type → Default to create unless "update/modify/fix" present

Missing Information

If deliverable lacks required parameters:

• Generate task with available info
• Note missing parameters in task description
• Record lesson for future reference

---

Integration

Caller: plan-marshall:execution-context (generic dispatcher, via workflow delegation)

Script Notations (use EXACTLY as shown):

• plan-marshall:manage-solution-outline:manage-solution-outline - Read solution and list deliverables (list-deliverables, read)
• plan-marshall:manage-tasks:manage-tasks - Create tasks via the three-step path-allocate flow (prepare-add → Write TOON → commit-add)
• plan-marshall:manage-lessons:manage-lessons - Record lessons on issues (add)
• plan-marshall:manage-logging:manage-logging - Log progress (work)

Skills Delegated To:

• pm-plugin-development:plugin-create - Component creation (handles validation and verification internally)
• pm-plugin-development:plugin-maintain - Component updates and refactoring (handles verification internally)

Contract Reference:

• plan-marshall:manage-tasks/standards/task-contract.md - Optimization workflow and decision tables