name: create-taskplane-task version: 1.3.0 description: Creates structured Taskplane task packets (PROMPT.md, STATUS.md) for autonomous agent execution via the task-orchestrator extension (/orch). Use when asked to "create a task", "create a taskplane task", "stage a task", "prepare a task for execution", "write a PROMPT.md", "set up work for the agent", "queue a task", or whenever the user wants to define work that will be executed autonomously by another agent instance.

Create Taskplane Task

Creates structured task packets (PROMPT.md + STATUS.md) for autonomous execution via the task-orchestrator extension (/orch). The orchestrator handles the execution loop, fresh-context management, cross-model reviews, wave scheduling, and live dashboard — so PROMPT.md stays focused on WHAT to do, not HOW to execute.

Architecture

create-taskplane-task skill       → Creates PROMPT.md + STATUS.md
task-orchestrator extension      → Executes tasks (single or batch)
  ├─ task-worker.md agent        → Worker system prompt (checkpoint discipline, resume logic)
  ├─ task-reviewer.md agent      → Reviewer system prompt (review formats, criteria)
  └─ taskplane-config.json       → Project-specific settings, paths, standards

The skill only creates files. All execution behavior lives in the orchestrator and the current execution engine (orchestrator + agent-host, direct process hosting, no TMUX).

Prerequisites

If `.pi/taskplane-config.json` does not exist (and .pi/task-runner.yaml is also absent), the project has not been initialized. Tell the user to run taskplane init first — the skill cannot create tasks without knowing where task areas live.

Configuration

Read `.pi/taskplane-config.json` first (JSON, canonical). Fall back to .pi/task-runner.yaml only if the JSON config does not exist. Use canonical JSON keys when documenting behavior; YAML keys are compatibility aliases.

Primary keys to read:

• taskRunner.taskAreas (legacy alias: task_areas) — folder paths, prefixes, CONTEXT.md locations per area
• taskRunner.referenceDocs (legacy alias: reference_docs) — available Tier 3 docs for "Context to Read First"
• taskRunner.standards — project coding rules and standards docs
• taskRunner.testing.commands — how to run tests
• taskRunner.selfDocTargets (legacy alias: self_doc_targets) — where agents log discoveries
• taskRunner.protectedDocs (legacy alias: protected_docs) — docs requiring user approval to modify
• taskRunner.neverLoad (legacy alias: never_load) — docs to exclude from task execution context

Task Creation Workflow

Step 1: Determine Location & Next ID

The user will rarely specify which area to use — figure it out from context.

When there's only one area (typical for new projects), use it directly.

When there are multiple areas, match the task to the right area:

1. Read the project config (taskplane-config.json or task-runner.yaml) → taskRunner.taskAreas (or task_areas in fallback YAML) to get all areas
2. Read each area's CONTEXT.md — the "Current State" section describes what

that area owns (its domain, services, file scope)

1. Match the task description to the area whose scope best fits:

• A task about PTO accrual → time-off area
• A task about the orchestrator itself → task-system area
• A task about login flows → identity-access area

1. If ambiguous (task spans multiple areas), prefer the area that owns the

primary file being modified, or ask the user

After selecting the area:

1. Read that area's CONTEXT.md and find the Next Task ID counter
2. Use that ID for the new task
3. Increment the counter in the same CONTEXT.md edit

Note: Task area structures evolve over time. A new project starts with a single taskplane-tasks/ folder and one area. As the project grows, users add domains and platform areas in the config. The skill adapts — it always reads the config to discover what areas exist rather than assuming a layout.

Step 2: Assess Complexity & Size

You MUST explicitly score and assign review level before creating PROMPT.md.

Quick reference (full rubric in Complexity Assessment):

• Score each dimension 0-2: Blast radius, Pattern novelty, Security, Reversibility
• Sum → Level: 0-1→L0 (None), 2-3→L1 (Plan), 4-5→L2 (Plan+Code), 6-8→L3 (Full)
• Size: S (<2h), M (2-4h), L (4-8h), XL (8h+ → must split)

Do not default to Review Level 0. Level 0 is only appropriate for trivial changes (doc updates, config, boilerplate). Most M-sized tasks score ≥2 and require at least Level 1.

Step 3: Create Task Folder

{area.path}/{PREFIX-###-slug}/

Step 4: Create PROMPT.md

Use the template in references/prompt-template.md.

Step 5: Create STATUS.md

Use the STATUS.md template in references/prompt-template.md. (If omitted, the execution engine can auto-generate it from PROMPT.md.)

Step 6: Update Tracking

• CONTEXT.md — Increment Next Task ID (done in Step 1)

Step 7: Report Launch Command

/orch {area.path}/{PREFIX-###-slug}/PROMPT.md

For batch execution of multiple tasks: /orch all

Complexity Assessment

Evaluate the task to determine cross-model review level.

Review Levels

Scoring (0-2 per dimension, sum for level)

• Score 0-1 → Level 0 · Score 2-3 → Level 1 · Score 4-5 → Level 2 · Score 6-8 → Level 3

Per-Step Override

Individual steps can override the task-level review:

### Step 3: Add RBAC middleware
> **Review override: code review** — This step touches authorization.

Per-Step Reviews vs. Consolidated Reviews (Checkpoint Markers)

A second axis sits alongside the Review Level: how many reviews fire for a given level. PROMPT authors should make this choice deliberately.

Default — per-step reviews: at Review Level ≥ 1, the worker fires a plan review BEFORE each implementation step and (at Level ≥ 2) a code review AFTER. A 5-implementation-step Level 2 task therefore fires ~5 plan + ~5 code = ~10 reviews. This is the right default for tasks where each step is an independent piece of work (e.g., a multi-cluster polish bundle, a multi-feature sprint).

Opt-in — consolidated via checkpoint markers: a PROMPT can include **Plan-review checkpoint** or **Code review checkpoint** markers in specific steps. The worker treats those markers as instructions to fire the corresponding review at that step only, instead of per-step. A single-deliverable task that decomposes into 1 design step + 3 mechanical implementation steps + 1 verify-everything step might mark the design step as the plan checkpoint and the verify step as the code checkpoint, for a total of 2 reviews instead of ~8.

When to use which:

• Per-step (default): independent multi-feature work, polish bundles,

refactor sweeps. Per-cluster review feedback is more useful than a consolidated review across unrelated changes.

• Consolidated (checkpoint markers): single-deliverable tasks where

the steps are mechanical applications of one design decision. TP-186 (the review_step death-spiral fix) is a real example: 1 prompt-design deliverable + 3 mechanical implementation steps + 1 code-review- everything step → 2 reviews total instead of ~8.

How to choose at PROMPT-authoring time: ask "would the reviewer benefit from seeing each step in isolation, or only the whole picture?" If each step touches a different concern, per-step. If every step is the same change applied to a different file, consolidate.

Task Sizing

Rule of thumb: More than ~3 major implementation steps → split it.

Tiered Context Loading

PROMPT.md tells the worker what to load. Less is better.

Populate "Context to Read First" in PROMPT.md using docs from the project config → taskRunner.referenceDocs (legacy YAML: reference_docs). List only what the task actually needs.

Docs listed in config → taskRunner.neverLoad (legacy YAML: never_load) must NOT appear in any task.

STATUS.md Hydration

STATUS.md is the worker's ONLY memory between iterations. It needs enough structure so progress survives when an iteration ends mid-step — but not so much structure that it becomes a rigid script the worker follows mechanically.

Philosophy: Adaptive Planning, Not Exhaustive Scripting

Hydration exists because workers discover things at runtime they couldn't know upfront: the actual function signatures, the edge cases that emerge from reading source, the reviewer feedback that reshapes approach. The goal is adaptability in the face of unknowns — not granularity for its own sake.

The right level of detail depends on predictability:

Anti-pattern to avoid: Creating 15+ micro-checkboxes that spell out every function name, parameter, and assertion before the worker has even read the source code. This wastes task-creation time, produces items that frequently need revision anyway, and turns the worker into a checkbox-follower instead of a problem-solver.

Task Creator Responsibilities

Match STATUS.md to PROMPT.md granularity — no more, no less. PROMPT.md steps should express outcomes the worker needs to achieve, not dictate how to achieve them.

Good granularity examples:

Over-hydrated examples (avoid):

Use `⚠️ Hydrate` markers for steps that genuinely depend on runtime discoveries — where the task creator cannot know the items upfront:

### Step 2: Handle migration
**Status:** ⬜ Not Started
> ⚠️ Hydrate: Expand based on schema gaps identified in Step 1
 
-[ ] Implement v1→v2 compatibility (details depend on Step 1 findings)

When to use markers vs. pre-hydration:

Worker Hydration at Runtime

Workers may expand checkboxes when entering a step — but should apply the same principle: add checkboxes for distinct outcomes discovered during exploration, not for every individual code change. The worker agent has hydration rules (commit-before-implement, REVISE-triggered expansion). The goal is a useful resumability checkpoint, not a line-by-line implementation journal.

Constraint: No New Steps at Runtime

Workers MUST NOT add, remove, or renumber steps during execution. The execution engine parses the step list from PROMPT.md once at launch and iterates that fixed list. Steps added to STATUS.md at runtime will appear in the dashboard but silently never execute.

Hydration expands checkboxes within existing steps only. If a worker discovers work that doesn't fit any step, it should add sub-checkboxes to the closest existing step and log the overflow in the STATUS.md Discoveries table.

Task creators: ensure PROMPT.md has all necessary steps upfront. If a task's scope might expand during execution, prefer fewer broad steps (the worker will hydrate them) over many narrow steps that might need restructuring.

PROMPT.md Amendment Policy

The template includes an ## Amendments placeholder at the bottom of PROMPT.md. Original content above the --- divider is immutable — workers use that section only for issues like missing prerequisites or contradictory instructions, not scope expansion or style preferences.

Dependencies Format

The orchestrator machine-parses this section using regex — stick to the exact patterns below. Non-standard formatting (e.g., missing bold markers, inline prose without a task ID pattern) may cause silent dependency misses or PARSE_MALFORMED errors at batch time.

## Dependencies
 
-**Task:** TO-014 (PTO policy engine must exist)
-**Task:** employee-management/EM-003 (area-qualified when ID may be ambiguous)
-**External:** All backend services running (ports 8080-8085)
-**None**

Notes:

• Use unqualified TASK-ID when globally unique
• Use area-name/TASK-ID for cross-area clarity or when orchestrator reports DEP_AMBIGUOUS

Checklist (Definition of Ready)

Verify every task against this before reporting the launch command:

• [ ] Next Task ID read from CONTEXT.md and incremented
• [ ] Folder created at correct taskRunner.taskAreas path (or fallback YAML task_areas) with name {PREFIX}-{###}-{slug}
• [ ] Complexity assessed, review level assigned (0-3)
• [ ] Size assessed (S/M/L) — split if XL
• [ ] PROMPT.md created from template with all required sections:
• [ ] ## Mission with what AND why
• [ ] ## Dependencies section
• [ ] ## Context to Read First lists only needed Tier 3 docs
• [ ] ## File Scope lists files/dirs the task will touch
• [ ] Each step has checkboxes with verifiable outcomes
• [ ] Explicit testing step with full-suite command (per-step targeted tests are in the worker prompt)
• [ ] ## Do NOT guardrails
• [ ] "Must Update" and "Check If Affected" doc lists
• [ ] ## Git Commit Convention section (from template)
• [ ] ## Amendments placeholder at bottom
• [ ] STATUS.md created with matching step structure
• [ ] Checkboxes match PROMPT.md granularity (1:1 where items are known)
• [ ] ⚠️ Hydrate markers for discovery-dependent steps
• [ ] Launch command reported: /orch {path}/PROMPT.md

Git Commit Convention

The prompt template includes a ## Git Commit Convention section. Workers commit at step boundaries (not after every checkbox) to keep git history meaningful. Hydration commits are the exception — STATUS.md expansions are committed immediately to preserve the plan for crash recovery. Always include the task ID prefix — without it, there's no way to trace commits back to the task that produced them (git log --grep="PM-004" only works if the prefix is there).

Orchestrator Awareness

Tasks are often executed in parallel batches by the task-orchestrator extension, not just as one-off single-task runs. Two fields in PROMPT.md become load-bearing in batch mode:

• `## Dependencies` — determines wave ordering. Tasks with unmet deps are

deferred to later waves. Incorrect or missing deps cause parallel execution of tasks that should be serial, leading to merge conflicts or stale reads.

• `## File Scope` — determines lane affinity. Tasks with overlapping file

scope are assigned to the same lane (serial) to avoid merge conflicts. Without file scope, the orchestrator distributes tasks randomly across lanes.

When creating multiple tasks for a batch, think about which tasks touch the same files and make sure their file scopes reflect that.

Multi-Repo Segment Markers

When a task spans multiple repos (e.g., shared-libs + web-client), the skill must generate segment markers inside each step so the orchestrator can route checkboxes to the correct repo's worker.

Workflow

1. Read workspace config to identify available repos and their roles
2. Analyze the task description and file scope — determine which repos are involved
3. Group work into steps by logical goal, with segments per repo within each step
4. Write PROMPT.md with #### Segment: <repoId> markers in every step
5. Write STATUS.md with matching structure

Marker Format

Within each step, use level-4 headings to separate work by repo:

### Step 1: Create utilities and API client
 
#### Segment: shared-libs
 
-[ ] Create string utility module
-[ ] Export from package index
 
#### Segment: web-client
 
-[ ] Add API client wrapper
-[ ] Wire into app initialization

Ordering Rules

Order steps so that dependencies flow correctly:

1. Shared/common work → early steps (e.g., shared libraries, schemas)
2. Per-repo implementation → middle steps (consumers of shared work)
3. Integration/documentation → final steps (always in the packet repo)

The final documentation/delivery step always uses #### Segment: <packet-repo> where <packet-repo> is the repo that contains the task's PROMPT.md.

Guidelines

• Always write explicit markers. Never rely on the engine's single-segment

fallback for multi-repo tasks. Every step must have at least one #### Segment: <repoId> marker.

• Max 10 segments per task. Tasks spanning more repos should be split into

separate tasks with dependencies.

• Single-repo tasks do not need segment markers. The engine's fallback

handles them correctly. Only add markers when file scope spans multiple repos.

• When pre-decomposition isn't possible (e.g., the worker must discover

which repos are affected), include guidance about using request_segment_expansion for dynamic expansion at runtime.

Preventing Empty Completions

Workers can shortcut tasks by observing that existing code "already satisfies" requirements and checking off items without implementing anything. This is the most dangerous failure mode — it produces false completions that waste the entire pipeline.

Defense: Make deliverables concrete and verifiable.

Rules for task creators:

• Every implementation step MUST name specific files to create or modify
• "Add X" means "write new code that doesn't exist yet" — if it might already exist, say "verify X exists and add tests, or implement if missing"
• Include at least one NEW test file per task — workers can't shortcut test creation
• Each step's artifacts list must include at least one source file (not just STATUS.md)

The worker's self-check reads what you write here

Before every code review the worker must write a ### Self-check (Step N) table into STATUS.md (review_step refuses without it) with one row per step outcome, per Step 0 design decision the step implements, and per ## Completion Criteria item the step touches — each with file:line evidence. Two consequences for task creators:

• Do NOT pre-seed `### Self-check` sections in STATUS.md. The runtime

requires the section to be written after the step's last checked box and to contain evidence rows; an empty or early-placed section is refused.

• Make `## Completion Criteria` concrete. The template's defaults ("all

steps complete / tests passing / docs updated") give the self-check nothing to verify. Add the task-specific, checkable outcomes ("review_step refuses when the section is missing", "resume refuses a .DONE over a REVISE") — these become rows the worker must produce evidence for, and the reviewer verifies that evidence instead of re-deriving the review. For Review Level ≥ 2 tasks, a Step 0/1 that records design decisions in a STATUS table pays for itself the same way.

Key Principles

• Documentation in every task. Without "Must Update" and "Check If Affected"

lists, docs drift from reality and future tasks work from stale context.

• Testing step required. Workers can't distinguish pre-existing failures from

regressions they caused — every task needs a clean test pass to stay unblocked. The Testing & Verification step runs the full test suite as a quality gate. Implementation steps should use targeted tests (e.g., --changed or specific test files) for fast feedback — the worker prompt handles this.

• Self-contained PROMPT.md. The worker starts with a fresh context and no

memory of the conversation that created the task. Everything it needs to begin must be in PROMPT.md and the referenced docs.