AI agent skill · by @jpicklyk

Pre Plan Workflow

Internal, hook-triggered: gathers existing MCP items and schema gate requirements to set the definition floor before planning.

Archived 2026-10-23 · Source updated 2026-09-16 · License: MIT. Check the original repository for the latest version.

SKILL.md instructions

# Pre-Plan Workflow — Definition Floor

When entering plan mode, use the MCP to set the **definition floor** before writing your plan.

The definition floor is the baseline of existing work, documentation requirements, and gate constraints that the plan must account for.

**If MCP is unreachable:** Proceed with planning based on conversation context. Note in the plan that MCP state could not be verified — existing work may overlap. Re-check after MCP reconnects.

## Step 1: Check Existing MCP State

Resolve the project rootId first: check session context for a rootId injected by the SessionStart hook, or read `.taskorchestrator/config.yaml`'s top-level `project.rootId` (a file read, not an MCP call).

Call the health check to see what's already tracked:

```
get_context()
```

When a rootId is known, pass it to scope the check to this project: `get_context(ancestorId="<rootId>")`. When no rootId is known, call unscoped exactly as shown — this is the same behavior as before project scoping existed.

**If active or stalled items exist:**
- Identify items related to the current request — avoid planning work that duplicates what's already tracked
- For each relevant active item, call `get_context(itemId=...)` to inspect:
  - **Note schema** — which notes are expected for this item's tags
  - **Gate status** — which required notes are filled vs. missing, and whether the item can advance
  - **Guidance key** — `guidanceKey` names the first unfilled required note; resolve its authoring guidance via `query_items(operation="schema", itemId=...)`

**If no items exist (clean slate):**
- The definition floor is simply "no existing MCP state to account for"
- Proceed with planning, but still check Step 2 for schema awareness

## Step 2: Discover Note Schema Requirements

Read `.taskorchestrator/config.yaml` in the project root (this is a file read, not an MCP call):

- If the file exists, list the discovered schemas and their required notes per phase
- Schemas are defined under `work_item_schemas:` (preferred) or `note_schemas:` (legacy)
- Each schema key (e.g., `feature-implementation`, `bug-fix`) is a **type identifier** — set it as the item's `type` field to activate gate enforcement. Tags can be used for additional categorization but are no longer the primary schema activator.
- Required queue-phase notes define what documentation must exist before work starts
- Required work-phase notes define what must be captured during implementation
- Use `guidanceKey` from `get_context(itemId=...)`, resolved via `query_items(operation="schema", itemId=...)`, to understand how to author each note

If no config file exists, the project has no note schemas — items will be schema-free with no gate enforcement. Proceed with planning normally.

**Minimal config example:**

```yaml
work_item_schemas:
  feature-task:
    notes:
      - key: task-scope
        role: queue
        required: true
      - key: implementation-notes
        role: work
        required: true
```

**Use schemas to inform the plan:** When a schema applies, each planned task should:
- Note which schema type will be applied at materialization (e.g., `type: "feature-task"`)
- Account for required notes — plan sections should naturally produce content that maps to required note keys
- Respect dependency ordering — which tasks block others (these become `BLOCKS` edges)

## Step 3: Plan with MCP Awareness

Structure the plan knowing it will be materialized into MCP items after approval:

- Each planned task should map to **one work item** with clear boundaries — a single unit of work a subagent can own
- Account for **dependency ordering** — which tasks block others (these become `BLOCKS` edges)
- Consider the **hierarchy** — a root container item with child task items is the standard pattern

## Continue with Plan Mode

The prerequisite is complete. Now proceed with plan mode's normal workflow — explore the codebase, understand existing patterns, and design your implementation approach. Use the definition floor from Steps 1-3 to inform your plan.

Once the plan is approved, the post-plan hook will guide you through materialization and implementation dispatch. Do not materialize before approval.