release: plugin v2.7.1 — planning hook and output style refinements (#88)

* feat(plugin): add tiered execution model (Direct/Delegated/Parallel)

Output style now classifies work into three tiers with proportional
process. Direct tier (1-2 files, known fix) implements inline — no
subagent dispatch, no plan mode, no separate review. Delegated and
Parallel tiers preserve the full pipeline.

Changes:
- workflow-orchestrator.md: tier classification section, conditional
  principles, Direct Tier Workflow section, frontmatter added, removed
  project-specific references (session-retrospective, quick-fix schema,
  gradlew), removed redundant delegation templates
- implement skill: tier-conditional Steps 1/3/4/5, two-dimensional
  classification (tier + interaction mode), resume-with-tier-awareness
- pre-plan.mjs: Direct tier safety net message

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(plugin): trim workflow-orchestrator to universally valuable content

Remove project-specific details, redundant templates, and niche
operational guidance. Condense worktree dispatch to 4 universal
principles, session tasks to one line, completion format to inline.
Drop schema tag row, delegation metadata section, return format
templates, and guidancePointer rendering convention.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore(plugin): minor cleanup — schema context in implement skill, analyst zone updates

- Implement skill: add schema context to session-tracking note reference
- Workflow-analyst Zone 2: add Delegation Metadata section, tier-aware
  Parallel Dispatch reference
- Workflow-analyst Zone 3: replace stale manifest monitoring with tier
  classification monitoring, connect analysis layer to /session-retrospective

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor(plugin): strengthen planning hooks and enforce WHAT/HOW separation

Planning hooks now use imperative gate language (PREREQUISITE/MUST/NEXT STEP)
instead of suggestive phrasing that lost attention competition with plan mode.
Output style trimmed to WHAT-level principles — procedural HOW detail moved to
skills where it belongs. Worktree Dispatch section removed (prescriptive technique,
not a principle). Skills get explicit handoff sections for clean control flow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* release: bump to v2.5.0 — plugin v2.7.1

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jpicklyk

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "task-orchestrator",
-      "version": "2.7.0",
+      "version": "2.7.1",
       "description": "Skills, hooks, and workflows for MCP Task Orchestrator. Schema-aware context, note-driven workflow, and session hooks.",
       "author": {
         "name": "Jeff Picklyk",

CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0] - 2026-03-30 (Plugin v2.7.1)
+
+### Changed
+- Strengthened planning hook language — pre-plan and post-plan hooks now use imperative gate framing (PREREQUISITE/MUST) instead of suggestive phrasing that was deprioritized by plan mode
+- Enforced WHAT/HOW separation — output style trimmed to principle-level statements, procedural detail lives in skills
+- Added explicit handoff sections to pre-plan and post-plan workflow skills for clean control flow between hook, skill, and plan mode
+- Bumped plugin version to 2.7.1 (planning hook and output style refinements)
+
+---
+
 ## [2.5.0] - 2026-03-25 (Plugin v2.7.0)
 
 ### Added

claude-plugins/CLAUDE.md

@@ -10,7 +10,7 @@ removing and re-adding the marketplace in Claude Code. No version bump is needed
 
 | Plugin | Directory | Current Version |
 |--------|-----------|-----------------|
-| `task-orchestrator` | `claude-plugins/task-orchestrator/` | `2.7.0` |
+| `task-orchestrator` | `claude-plugins/task-orchestrator/` | `2.7.1` |
 
 > Updated automatically by `/prepare-release`. Do not bump manually.
 

claude-plugins/task-orchestrator/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "task-orchestrator",
-  "version": "2.7.0",
+  "version": "2.7.1",
   "description": "Claude Code integration for MCP Task Orchestrator — schema-aware context, note-driven workflow",
   "skills": "./skills",
   "hooks": "./hooks/hooks-config.json",

claude-plugins/task-orchestrator/hooks/post-plan.mjs

@@ -3,9 +3,11 @@
 const output = {
   hookSpecificOutput: {
     hookEventName: "PostToolUse",
-    additionalContext: `## Plan Approved — MCP Task Orchestrator
+    additionalContext: `## NEXT STEP — Required before implementation
 
-Invoke the \`task-orchestrator:post-plan-workflow\` skill for the full post-approval workflow. It covers materialization, implementation dispatch, and verification.`
+The plan has been approved. You MUST invoke the \`task-orchestrator:post-plan-workflow\` skill NOW to materialize MCP items and dispatch implementation.
+
+Do not begin any implementation work until this completes.`
   }
 };
 process.stdout.write(JSON.stringify(output));

claude-plugins/task-orchestrator/hooks/pre-plan.mjs

@@ -3,11 +3,11 @@
 const output = {
   hookSpecificOutput: {
     hookEventName: "PreToolUse",
-    additionalContext: `## Planning Mode — MCP Task Orchestrator
+    additionalContext: `## PREREQUISITE — Complete before exploring or planning
 
-Invoke the \`task-orchestrator:pre-plan-workflow\` skill for the full planning workflow. It will guide you through checking existing MCP state to set the definition floor before writing your plan.
+You MUST invoke the \`task-orchestrator:pre-plan-workflow\` skill BEFORE starting any codebase exploration or plan writing.
 
-Note: If the work is Direct tier (1-2 files, known fix, no migration), you should not be in plan mode. Consider exiting plan mode and implementing directly.`
+Do this now. Do not begin exploring, reading code, or drafting your plan until this prerequisite completes.`
   }
 };
 process.stdout.write(JSON.stringify(output));

claude-plugins/task-orchestrator/output-styles/workflow-orchestrator.md

@@ -54,7 +54,7 @@ Before starting any work, classify it into one of three execution tiers. This de
 1. **Delegate by default** — for Delegated and Parallel tier work, delegate coding to subagents. For Direct tier work (1-2 files, known fix, no migration), implement, test, and review inline
 2. **Plan proportionally** — use `EnterPlanMode` for Delegated tier when scope needs clarification and always for Parallel tier. Direct tier skips plan mode
 3. **Materialize before implement** — all MCP work items must exist before dispatching agents
-4. **Agent-owned phases** — implementation agents call `advance_item(start)` to enter work (queue→work) and again to advance to review (work→review) before returning; the orchestrator dispatches review agents only after the item is already in review; the orchestrator performs the final terminal transition (review→terminal) after the review verdict; `advance_item` self-reports missing gates on failure
+4. **Agent-owned phases** — implementation agents own their work-phase transitions (queue→work→review). The orchestrator owns review dispatch and terminal transitions (review→terminal). Skills define the specific sequencing
 5. **Atomic creation** — use `create_work_tree` for hierarchy; avoid multi-call sequences
 6. **Include UUID in every delegation** — subagents must reference their MCP item UUID
 7. **Always know current state** — query MCP before making decisions
@@ -74,7 +74,7 @@ Direct tier work does not use the delegation table — the orchestrator implemen
 
 **Rule: Never make 3+ MCP write calls in a single turn.** Parallelized reads (e.g., `get_context` + `query_items overview`) are fine and encouraged. Use the Agent tool with `model: "haiku"` to delegate bulk MCP write work (multiple item/dependency/note creates) and keep the orchestrator context clean.
 
-Every delegation prompt must include: entity IDs, exact tool operations, expected return format, and full context (subagents start fresh with no ambient context).
+Delegation prompts must include entity IDs and full context — subagents start fresh with no ambient context.
 
 ## Action Items
 
@@ -88,24 +88,7 @@ Every delegation prompt must include: entity IDs, exact tool operations, expecte
 
 ## Direct Tier Workflow
 
-When work is classified as Direct tier:
-
-1. **Advance immediately** — `advance_item(trigger="start")` from queue to work. If the item's schema has no queue-phase required notes, the gate passes without filling anything.
-2. **Implement directly** — edit the files, run tests. No subagent dispatch.
-3. **Fill session-tracking note** — brief summary of what changed and test results.
-4. **Inline review** — read the diff, verify correctness, confirm tests pass. No separate review agent.
-5. **Advance to terminal** — `advance_item` through review to terminal.
-
-This path exists because delegation overhead (cold-start context, return parsing, review agent dispatch) exceeds the risk being mitigated for 1-2 file changes with known fixes.
-
-## Worktree Dispatch
-
-When dispatching agents with `isolation: "worktree"`:
-
-- Verify tasks are independent — no dependency edges between items dispatched in parallel
-- Capture **worktree path** and **branch name** from each Agent return — these are needed for review and merge
-- Review agents must operate **in the worktree**, not the main working directory — include the worktree path, branch, and changed files in the review prompt
-- Spot-check diffs after agents return: `git -C <worktree-path> diff main --stat`
+Direct tier work skips delegation overhead entirely — the orchestrator advances, implements, reviews, and completes inline. No subagent dispatch, no plan mode, no separate review agent.
 
 ## Visual Conventions
 

claude-plugins/task-orchestrator/skills/post-plan-workflow/SKILL.md

@@ -43,3 +43,7 @@ After all agents complete:
 2. Run `get_context()` health check to see what completed, what stalled, and what needs attention
 3. Review any stalled items — check which notes are missing with `get_context(itemId=...)`
 4. Address blockers or incomplete work as needed
+
+## Workflow Complete
+
+The post-plan workflow is done. Report the final status to the user — what completed, what needs attention, and any items still in progress.

claude-plugins/task-orchestrator/skills/pre-plan-workflow/SKILL.md

@@ -56,6 +56,8 @@ Structure the plan knowing it will be materialized into MCP items after approval
 - 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
 
-## After Plan Approval
+## 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.