release: v2.1.0 — guidance fields, 6 new skills, plugin quality fixes (#42)

* feat: surface guidance field across all MCP tools, plugin, and docs (#42)

Fix guidancePointer to track first unfilled required note instead of
always returning the first schema entry. Add guidance to expectedNotes
in manage_items and create_work_tree responses. Add structured
missingNotes array to advance_item gate errors. Update workflow guide
with guidance sections, agent integration patterns, and field comparison
table. Update plugin pipeline (output style, hook, 5 skills) to instruct
agents to consult and embed guidance. Clarify agent lifecycle ownership
in post-plan-workflow — agents self-transition, orchestrator verifies
via dependency gating. Plugin version 2.3.7.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(plugin): rename output style, remove internal version references

Rename current-analyst.md to workflow-orchestrator.md. Remove "Current
(v3)" references from output style title, plugin description, and
marketplace listing. Drop hardcoded tool count from heading. Remove
stale "v3" tag from marketplace. Plugin version 2.3.8.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix(plugin): address 20 skill quality issues from validation audit

Fix 5 high, 7 medium, and 8 low-severity issues across 9 plugin skills:
- quick-start: remove count constraint, replace hook jargon, clarify UUID, reduce duplication
- create-item: clarify config read mechanism, soften option count, note optional fields
- batch-complete: add batch guidance for large lists, fix duplicate table rows, reframe FAQ
- pre-plan-workflow: add trigger context, MCP fallback block, remove schema repetition
- post-plan-workflow: add trigger context, partial failure recovery, specific resolution guidance
- status-progression: add trigger rationale, note guidancePointer limitation
- manage-schemas: add missing schema guard for EDIT/DELETE routes
- work-summary: extract childCounts caveat into callout block
- dependency-manager: replace rigid template with flexible guidance

Also adds delegation warning to claude-plugins/CLAUDE.md to prevent
subagents from independently bumping version files during parallel edits.

Bump plugin version to 2.3.9.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* release: bump to v2.1.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: jpicklyk

.claude-plugin/marketplace.json

@@ -10,8 +10,8 @@
   "plugins": [
     {
       "name": "task-orchestrator",
-      "version": "2.3.5",
-      "description": "Skills, hooks, and workflows for MCP Task Orchestrator (v3). Schema-aware context, note-driven workflow, and thin session hooks.",
+      "version": "2.3.9",
+      "description": "Skills, hooks, and workflows for MCP Task Orchestrator. Schema-aware context, note-driven workflow, and session hooks.",
       "author": {
         "name": "Jeff Picklyk",
         "url": "https://github.com/jpicklyk"
@@ -21,7 +21,7 @@
       "license": "MIT",
       "keywords": ["task-management", "project-management", "workflow", "mcp", "ai-orchestration"],
       "category": "productivity",
-      "tags": ["tasks", "features", "projects", "dependencies", "workflows", "v3"],
+      "tags": ["tasks", "features", "projects", "dependencies", "workflows"],
       "source": "./claude-plugins/task-orchestrator",
       "strict": true
     }

CHANGELOG.md

@@ -5,6 +5,23 @@ 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.1.0] - 2026-03-04
+
+### Added
+- Added `guidancePointer` and `expectedNotes` to `advance_item`, `create_work_tree`, `manage_items`, and `get_context` responses — agents see exactly which notes need filling and get human-readable guidance at each gate transition
+- Added 6 new plugin skills: `batch-complete`, `dependency-manager`, `manage-schemas`, `quick-start`, `status-progression`, and `create-item` — covering bulk operations, dependency visualization, schema management, onboarding, and workflow navigation
+- Added `pre-plan-workflow` and `post-plan-workflow` internal skills with automatic hook injection — plan mode now checks existing MCP state and materializes items after approval without manual steps
+
+### Changed
+- Renamed output style from `current-analyst` to `workflow-orchestrator` to better reflect its orchestration focus
+- Overhauled plugin hooks (`pre-plan`, `post-plan`, `subagent-start`) for schema-aware context injection
+- Improved quick-start and workflow guide documentation with end-to-end examples
+
+### Fixed
+- Fixed 20 skill quality issues across 9 skills (contradictions, jargon, missing guards, unclear guidance)
+
+---
+
 ## [2.0.3] - 2026-02-19
 
 ### Added

claude-plugins/CLAUDE.md

@@ -1,6 +1,6 @@
 # claude-plugins/ — Version Bump Requirement
 
-**Any change to plugin content in this directory requires a version bump.**
+**Any change to plugin content in this directory requires a version bump.** However, the version bump should be done **once**, after all content changes are complete — not by each individual edit or subagent.
 
 Claude Code caches plugin content (skills, hooks, output styles, scripts) keyed by version number.
 Without a version bump, Claude Code will continue serving the old cached copy — changes will not
@@ -37,10 +37,14 @@ Use semantic versioning (`major.minor.patch`):
 
 | Plugin | Directory | Current Version |
 |--------|-----------|-----------------|
-| `task-orchestrator` | `claude-plugins/task-orchestrator/` | `2.3.5` |
+| `task-orchestrator` | `claude-plugins/task-orchestrator/` | `2.3.9` |
 
 > Update this table when versions change.
 
+## Delegation Warning
+
+When multiple subagents edit plugin files in parallel, **only the orchestrator (or a single designated agent) should bump versions.** Subagents editing individual skill files must NOT independently bump version files — this causes cascading increments (e.g., 2.3.8 → 9 → 10 → 11) that must be corrected afterward. The orchestrator bumps once after all edits land.
+
 ## After Bumping
 
 Re-add the marketplace in Claude Code to pull the updated cache:

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

@@ -1,7 +1,7 @@
 {
   "name": "task-orchestrator",
-  "version": "2.3.5",
-  "description": "Claude Code integration for Current (v3) MCP Task Orchestrator — thin hooks, schema-aware context, note-driven workflow",
+  "version": "2.3.9",
+  "description": "Claude Code integration for MCP Task Orchestrator — schema-aware context, note-driven workflow",
   "skills": "./skills",
   "hooks": "./hooks/hooks-config.json",
   "outputStyles": "./output-styles"

claude-plugins/task-orchestrator/hooks/subagent-start.mjs

@@ -8,8 +8,9 @@ const output = {
 **Required actions for implementation agents:**
 1. Call \`advance_item(trigger="start")\` on your assigned item UUID at the beginning
 2. Do the work
-3. Fill any required notes with \`manage_notes(operation="upsert")\`
-4. Call \`advance_item(trigger="complete")\` when done (gate enforcement will verify notes)
+3. **Guidance-aware note authoring:** Before filling any required note, call \`get_context(itemId=<your-item-UUID>)\` to check \`guidancePointer\`. If non-null, use it as authoring instructions for note content — it tells you exactly what the schema author expects in the note.
+4. Fill any required notes with \`manage_notes(operation="upsert")\`
+5. Call \`advance_item(trigger="complete")\` when done (gate enforcement will verify notes)
 
 **Returning results:** Report files changed (with line counts), test results, and any blockers. Do not echo back the task description.`
   }

…strator/output-styles/current-analyst.md …r/output-styles/workflow-orchestrator.mdclaude-plugins/task-orchestrator/output-styles/current-analyst.md renamed to claude-plugins/task-orchestrator/output-styles/workflow-orchestrator.md claude-plugins/task-orchestrator/output-styles/current-analyst.md renamed to claude-plugins/task-orchestrator/output-styles/workflow-orchestrator.md

@@ -1,12 +1,12 @@
-# Current (v3) Task Orchestrator — Analyst Mode
+# Task Orchestrator — Workflow Orchestrator
 
-You are a workflow orchestrator for the Current (v3) MCP Task Orchestrator. You plan, delegate, track, and report. Implementation is performed by subagents.
+You are a workflow orchestrator for the MCP Task Orchestrator. You plan, delegate, track, and report. Implementation is performed by subagents.
 
 ## Session Start
 
 **First action every session:** invoke `/work-summary` before responding to the user.
 
-## Core Tools (13)
+## Core Tools
 
 **Hierarchy & CRUD**
 - `manage_items` — create, update, delete work items (supports `recursive: true` on delete)
@@ -35,6 +35,7 @@ When creating items with tags that match a configured schema, `manage_items(crea
 
 ```
 manage_items(create) → check expectedNotes
+  → get_context(itemId=...)          ← check `guidancePointer` for authoring instructions
   → manage_notes(upsert) for each required queue note
   → advance_item(trigger="start")   ← gate enforced
 ```
@@ -74,6 +75,8 @@ Set via the `model` parameter on the Task tool. Default inherits orchestrator mo
 
 **Return format discipline:** Every delegation prompt must specify exact return format. Default: "Return a markdown table of [id (8-char), full UUID, title, status]. Do not restate the task."
 
+When delegating note-filling work to subagents, embed `guidancePointer` from `get_context` in the delegation prompt. This tells the subagent exactly how to author note content.
+
 ## Action Items
 
 **Use `/task-orchestrator:create-item`** when logging any persistent work item during a session — it handles container anchoring, tag inference, and note pre-population automatically. Invoke proactively when the conversation surfaces a bug, feature idea, tech debt item, or observation worth tracking.
@@ -91,3 +94,12 @@ Status symbols: `✓` terminal · `◉` work/review · `⊘` blocked · `○` qu
 Append a `◆ Analysis` block to every response involving MCP calls or subagent dispatches:
 - **Lightweight** (1–3 calls, no agents): one line — `◆ Analysis — N MCP calls | clean`
 - **Full** (4+ calls or delegation): sections for MCP efficiency, return payload, friction points, observations logged
+
+**Friction pattern monitoring:**
+
+| Pattern | Symptom | Resolution |
+|---------|---------|------------|
+| `guidance` ignored | Subagent fills notes without consulting `guidancePointer` | Call `get_context(itemId=...)` first; embed `guidancePointer` in delegation prompt |
+
+**Rendering conventions:**
+`guidancePointer` values render as blockquotes in dashboards: `> "List functional requirements as bullet points..."`

claude-plugins/task-orchestrator/skills/batch-complete/SKILL.md

@@ -58,7 +58,7 @@ Parse the child counts by role and present a preview table:
   ✓ terminal: 2 items (already done — will be skipped)
 ```
 
-**For `itemIds` path** (no root item): call `query_items(operation="get", id="<uuid>")` on each item and build the same role-grouped preview table from the individual results.
+**For `itemIds` path** (no root item): call `query_items(operation="get", id="<uuid>")` on each item and build the same role-grouped preview table from the individual results. For large lists (10+ items), use `query_items(operation="search")` with filters instead of individual get calls.
 
 **If any items are in `work` or `review`**, warn the user that active work will be force-completed (gate checks still apply). Use `AskUserQuestion` with three options:
 
@@ -102,6 +102,8 @@ Then offer three options via `AskUserQuestion`:
   3. Proceed anyway — gated items will be skipped, others will complete
 ```
 
+Call `get_context(itemId=...)` to retrieve `guidancePointer` for items with missing notes. Use the guidance as authoring instructions before filling.
+
 Wait for the user's choice. If they choose option 2, switch to `trigger="cancel"` for the execution step.
 
 ---
@@ -217,11 +219,9 @@ Solution: Verify the UUID with `query_items(operation="get", id="<uuid>")`. If n
 
 ---
 
-**Problem: All items reported as skipped with "already terminal"**
-
-Cause: The items are already in terminal role — they were completed or cancelled in a prior run.
+**FAQ: All items reported as skipped with "already terminal"**
 
-Solution: This is not an error. Terminal items are intentionally skipped. If the summary shows all items skipped with "already terminal", the workstream is already closed. No further action is needed.
+This is expected behavior, not an error. Items already in terminal role are intentionally skipped — they were completed or cancelled in a prior run. If the summary shows all items skipped with "already terminal", the workstream is already closed. No further action is needed.
 
 ---
 
@@ -234,10 +234,10 @@ All items are ready; notes are filled; clean completion with no skips.
 **Step 2 preview shows:**
 ```
 ◆ Impact Preview — "Payment Integration"
-  ○ queue:    0 items
+  ○ queue:    3 items (will be completed)
   ◉ work:     0 items
+  ◉ review:   0 items
   ✓ terminal: 1 item  (already done — will be skipped)
-  ○ queue:    3 items (will be completed)
 ```
 
 No active items — no warning needed. Gate check shows all required notes filled. Proceed directly.

claude-plugins/task-orchestrator/skills/create-item/SKILL.md

@@ -18,7 +18,7 @@ Determine from context (or from `$ARGUMENTS` if provided):
 - **Priority** — high / medium / low (default: medium)
 - **Scope** — single item, or feature with 2+ clear distinct subtasks?
 
-If title or type cannot be inferred with confidence, use `AskUserQuestion` with 2–3 concrete options. Do not ask open-ended questions.
+If title or type cannot be inferred with confidence, use `AskUserQuestion` with concrete options. Do not ask open-ended questions.
 
 ---
 
@@ -73,7 +73,7 @@ Empty (no project root exists):
 
 ## Step 4 — Apply tags via schema discovery
 
-Read `.taskorchestrator/config.yaml` to discover available note schemas. Each schema key is a tag that activates gate enforcement when applied to an item.
+Read `.taskorchestrator/config.yaml` to discover available note schemas (this is a file read, not an MCP call). In Docker, the path is resolved via the `AGENT_CONFIG_DIR` env var. Each schema key is a tag that activates gate enforcement when applied to an item.
 
 **Infer the best schema match from context:**
 
@@ -104,6 +104,7 @@ manage_items(operation="create", items=[{
   priority: "<inferred priority>",
   tags: "<tags or omit>",
   parentId: "<category container UUID>"
+  // Additional fields like `complexity` are optional — omit if not relevant
 }])
 ```
 
@@ -124,6 +125,7 @@ Default to single item when scope is unclear. Use `create_work_tree` only when t
 
 Check `expectedNotes` in the create response. For each note where `required: true` and `role: "queue"`:
 - Extract relevant content from the conversation
+- Check each `expectedNotes` entry for a `guidance` field — use it as the authoring instruction for note content. Guidance takes precedence over free-form inference.
 - Upsert: `manage_notes(operation="upsert", notes=[{itemId, key, role, body}])`
 - If conversation content is too sparse for a meaningful note body, leave it — do not fabricate content
 

claude-plugins/task-orchestrator/skills/dependency-manager/SKILL.md

@@ -107,16 +107,14 @@ Many items that all block one item → fan-in pattern
 | `fan-out` | `source=A`, `targets=[B, C, D]` | One item blocks many |
 | `fan-in` | `sources=[A, B, C]`, `target=D` | Many items block one |
 
-Before creating, confirm intent with the user:
+Confirm the derived edges with the user before creating. Show them what you're about to create in a readable way, for example:
 
 ```
-◆ About to create:
-  A → BLOCKS → B
-  B → BLOCKS → C
-  C → BLOCKS → D
-  Proceed?
+About to create: A → B → C → D as a linear chain. Proceed?
 ```
 
+Adjust the format to fit the actual pattern (single edge, fan-out, fan-in, etc.).
+
 Then call `manage_dependencies(operation="create")` with the selected pattern:
 
 ```

claude-plugins/task-orchestrator/skills/manage-schemas/SKILL.md

@@ -70,12 +70,16 @@ If the user specified a schema name, show that schema's full detail: each note w
 
 Read current config, display the target schema, ask what to change (add note, remove note, toggle required, change description/guidance, rename key), apply changes, write back.
 
+If the target schema is not found in config.yaml, inform the user and offer to CREATE instead.
+
 For detailed workflow, see `references/edit-workflow.md` in this skill folder.
 
 ### DELETE — Remove a Schema
 
 Read current config, confirm the schema name, warn about orphaned notes on existing items, remove the key, write back.
 
+If the target schema is not found in config.yaml, inform the user and offer to CREATE instead.
+
 For detailed workflow, see `references/delete-workflow.md` in this skill folder.
 
 ### VALIDATE — Check Config Integrity