henrylach/taskplane/create-taskplane-task

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: