@leeovery/claude-technical-workflows 2.0.50 → 2.0.52

package/commands/link-dependencies.md

@@ -65,13 +65,13 @@ Stop here.
 
 ## Step 3: Extract External Dependencies
 
-For each plan, find the External Dependencies section:
+For each plan, read the `external_dependencies` field from the frontmatter:
 
-1. **Read the External Dependencies section** from each plan index file
-2. **Categorize each dependency**:
-   - **Unresolved**: `- {topic}: {description}` (no arrow, no task ID)
-   - **Resolved**: `- {topic}: {description} → {task-id}` (has task ID)
-   - **Satisfied externally**: `- ~~{topic}: {description}~~ → satisfied externally`
+1. **Read `external_dependencies`** from each plan index file's frontmatter
+2. **Categorize each dependency** by its `state` field:
+   - **Unresolved**: `state: unresolved` (no task linked)
+   - **Resolved**: `state: resolved` (has `task_id`)
+   - **Satisfied externally**: `state: satisfied_externally`
 
 3. **Build a summary**:
 
@@ -84,7 +84,7 @@ Plan: authentication (format: {format})
 
 Plan: billing-system (format: {format})
   - authentication: User context (unresolved)
-  - ~~payment-gateway: Payment processing~~ → satisfied externally
+  - payment-gateway: Payment processing (satisfied externally)
 
 Plan: notifications (format: {format})
   - authentication: User lookup (unresolved)
@@ -111,8 +111,8 @@ For each unresolved dependency:
 
 For each resolved match:
 
-1. **Update the plan index file**:
-   - Change `- {topic}: {description}` to `- {topic}: {description} → {task-id}`
+1. **Update the plan index file's frontmatter**:
+   - Change the dependency's `state: unresolved` to `state: resolved` and add `task_id: {task-id}`
 
 2. **Create dependency in output format**:
    - Load `skills/technical-planning/references/output-formats/output-{format}.md`
@@ -123,7 +123,7 @@ For each resolved match:
 For each plan that was a dependency target (i.e., other plans depend on it):
 
 1. **Check reverse dependencies**: Are there other plans that should have this wired up?
-2. **Offer to update**: "Plan X depends on tasks you just linked. Update its External Dependencies section?"
+2. **Offer to update**: "Plan X depends on tasks you just linked. Update its `external_dependencies` frontmatter?"
 
 ## Step 7: Report Results
 

package/commands/workflow/start-implementation.md

@@ -61,14 +61,30 @@ This outputs structured YAML. Parse it to understand:
 **From `plans` section:**
 - `exists` - whether any plans exist
 - `files` - list of plans with: name, topic, status, date, format, specification, specification_exists, plan_id (if present)
+- Per plan `external_deps` - array of dependencies with topic, state, task_id
+- Per plan `has_unresolved_deps` - whether plan has unresolved dependencies
+- Per plan `unresolved_dep_count` - count of unresolved dependencies
 - `count` - total number of plans
 
+**From `implementation` section:**
+- `exists` - whether any implementation tracking files exist
+- `files` - list of tracking files with: topic, status, current_phase, completed_phases, completed_tasks
+
+**From `dependency_resolution` section:**
+- Per plan `deps_satisfied` - whether all resolved deps have their tasks completed
+- Per plan `deps_blocking` - list of deps not yet satisfied with reason
+
 **From `environment` section:**
 - `setup_file_exists` - whether environment-setup.md exists
 - `requires_setup` - true, false, or unknown
 
 **From `state` section:**
 - `scenario` - one of: `"no_plans"`, `"single_plan"`, `"multiple_plans"`
+- `plans_concluded_count` - plans with status concluded
+- `plans_with_unresolved_deps` - plans with unresolved external deps
+- `plans_ready_count` - concluded plans with all deps satisfied
+- `plans_in_progress_count` - implementations in progress
+- `plans_completed_count` - implementations completed
 
 **IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state - the script provides everything needed.
 
@@ -102,66 +118,137 @@ Plans exist.
 
 ## Step 3: Present Plans and Select
 
-Present all discovered plans to help the user make an informed choice.
+Present all discovered plans using the icon system below. Classify each plan into one of three sections based on its state.
+
+**Classification logic:**
+
+A plan is **Implementable** if:
+- It has `status: concluded` AND all deps are satisfied (`deps_satisfied: true` or no deps) AND no tracking file or tracking `status: not-started`, OR
+- It has an implementation tracking file with `status: in-progress`
+
+A plan is **Implemented** if:
+- It has an implementation tracking file with `status: completed`
+
+A plan is **Not implementable** if:
+- It has `status: concluded` but deps are NOT satisfied (blocking deps exist)
+- It has `status: planning` or other non-concluded status
+- It has unresolved deps (`has_unresolved_deps: true`)
 
 **Present the full state:**
 
 ```
-Available Plans:
+Implementation Phase
+
+Implementable:
+  1. ▶ billing - continue [Phase 2, Task 3]
+  2. + core-features - start
 
-  1. {topic-1} (in-progress) - format: {format}
-  2. {topic-2} (concluded) - format: {format}
-  3. {topic-3} (in-progress) - format: {format}
+Implemented:
+  3. > user-auth
 
-Which plan would you like to implement? (Enter a number or name)
+Not implementable:
+  · advanced-features [blocked: core-features task core-2-3 not completed]
+  · reporting [planning]
 ```
 
-**Legend:**
-- `in-progress` = implementation ongoing or not started
-- `concluded` = implementation complete (can still be selected for review/continuation)
+**Formatting rules:**
+
+Implementable (numbered, selectable):
+- **`▶`** — implementation `status: in-progress`, show current position `[Phase N, Task M]`
+- **`+`** — concluded plan, deps met, no tracking file or tracking `status: not-started`
+
+Implemented (numbered, selectable):
+- **`>`** — implementation `status: completed`
+
+Not implementable (not numbered, not selectable):
+- **`·`** — blocked or plan not concluded
+- `[blocked: {topic} task {id} not completed]` — resolved dep, task not done
+- `[blocked: unresolved dep on {topic}]` — no task linked
+- `[planning]` — plan status is not `concluded`
+
+**Ordering:**
+1. Implementable first: `▶` in-progress, then `+` new (foundational before dependent)
+2. Implemented next: `>` completed
+3. Not implementable last
+
+Numbering is sequential across Implementable and Implemented. Omit any section entirely if it has no entries.
+
+**If Not implementable section is shown**, append after the presentation:
 
-**If single plan exists (auto-select):**
 ```
-Auto-selecting: {topic} (only available plan)
+If a blocked dependency has been resolved outside this workflow, name the plan and the dependency to unblock it.
+```
+
+**Then prompt based on what's actionable:**
+
+**If single implementable plan and no implemented plans (auto-select):**
+```
+Auto-selecting: {topic} (only implementable plan)
 ```
 → Proceed directly to **Step 4**.
 
-**If multiple plans exist:**
+**If nothing selectable (no implementable or implemented):**
+Show Not implementable section only (with unblock hint above).
+
+```
+No implementable plans.
+
+To proceed:
+- Complete blocking dependencies first
+- Or finish plans still in progress with /start-planning
+```
 
 **STOP.** Wait for user response.
 
+**Otherwise (multiple selectable plans, or implemented plans exist):**
+```
+Select a plan (enter number):
+```
+
+**STOP.** Wait for user response.
+
+#### If the user requests an unblock
+
+1. Identify the plan and the specific dependency
+2. Confirm with the user which dependency to mark as satisfied
+3. Update the plan's `external_dependencies` frontmatter: set `state` to `satisfied_externally`
+4. Commit the change
+5. Re-run classification and re-present Step 3
+
 → Based on user choice, proceed to **Step 4**.
 
 ---
 
 ## Step 4: Check External Dependencies
 
-**This step is a gate.** Implementation cannot proceed if dependencies are not satisfied.
-
-See **[dependencies.md](../../skills/technical-planning/references/dependencies.md)** for dependency format and states.
+**This step is a confirmation gate.** Dependencies have been pre-analyzed by the discovery script.
 
 After the plan is selected:
 
-1. **Read the External Dependencies section** from the plan file
-2. **Check each dependency** according to its state:
-   - **Unresolved**: Block
-   - **Resolved**: Check if task is complete (load output format reference, follow "Querying Dependencies" section)
-   - **Satisfied externally**: Proceed
+1. **Check the plan's `external_deps` and `dependency_resolution`** from the discovery output
+
+#### If all deps satisfied (or no deps)
+
+```
+External dependencies satisfied.
+```
+
+→ Proceed to **Step 5**.
 
-### Blocking Behavior
+#### If any deps are blocking
 
-If ANY dependency is unresolved or incomplete, **stop and present**:
+This should not normally happen for plans classified as "Implementable" in Step 3. However, as an escape hatch:
 
 ```
-⚠️ Implementation blocked. Missing dependencies:
+Missing dependencies:
 
 UNRESOLVED (not yet planned):
-- billing-system: Invoice generation for order completion
-  → No plan exists for this topic. Create with /start-planning or mark as satisfied externally.
+- {topic}: {description}
+  -> No plan exists for this topic. Create with /start-planning or mark as satisfied externally.
 
 INCOMPLETE (planned but not implemented):
-- authentication: User context retrieval
-  → Status: in-progress. This task must be completed first.
+- {topic}: task {task_id} not yet completed
+  -> This task must be completed first.
 
 OPTIONS:
 1. Implement the blocking dependencies first
@@ -171,23 +258,15 @@ OPTIONS:
 
 **STOP.** Wait for user response.
 
-### Escape Hatch
+#### Escape Hatch
 
 If the user says a dependency has been implemented outside the workflow:
 
 1. Ask which dependency to mark as satisfied
-2. Update the plan file: Change `- {topic}: {description}` to `- ~~{topic}: {description}~~ → satisfied externally`
+2. Update the plan frontmatter: Change the dependency's `state` to `satisfied_externally`
 3. Commit the change
 4. Re-check dependencies
 
-### All Dependencies Satisfied
-
-If all dependencies are resolved and complete (or satisfied externally), proceed to Step 5.
-
-```
-✅ External dependencies satisfied.
-```
-
 → Proceed to **Step 5**.
 
 ---
@@ -227,32 +306,7 @@ Are there any environment setup instructions I should follow before implementati
 
 ---
 
-## Step 6: Ask About Scope
-
-Ask the user about implementation scope:
-
-```
-How would you like to proceed?
-
-1. Implement all phases - Work through the entire plan sequentially
-2. Implement specific phase - Focus on one phase (e.g., "Phase 1")
-3. Implement specific task - Focus on a single task
-4. Next available task - Auto-discover the next incomplete task
-
-Which approach?
-```
-
-**STOP.** Wait for user response.
-
-If they choose a specific phase or task, ask them to specify which one.
-
-> **Note:** Do NOT verify that the phase or task exists at this stage. Record the user's answer in the handoff context. Validation happens when the skill is invoked.
-
-→ Proceed to **Step 7**.
-
----
-
-## Step 7: Invoke the Skill
+## Step 6: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
@@ -265,9 +319,9 @@ Plan: docs/workflow/planning/{topic}.md
 Format: {format}
 Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})
-Scope: {all phases | Phase N | Task N.M | next-available}
+Implementation tracking: {exists | new} (status: {in-progress | not-started | completed})
 
-Dependencies: {All satisfied ✓ | List any notes}
+Dependencies: {All satisfied | List any notes}
 Environment: {Setup required | No special setup required}
 
 Invoke the technical-implementation skill.

package/commands/workflow/start-planning.md

@@ -70,6 +70,7 @@ This outputs structured YAML. Parse it to understand:
 **From `plans` section:**
 - `exists` - whether any plans exist
 - `files` - each plan's name, format, status, and plan_id (if present)
+- `common_format` - the output format if all existing plans share the same one; empty string otherwise
 
 **From `state` section:**
 - `scenario` - one of: `"no_specs"`, `"nothing_actionable"`, `"has_options"`
@@ -255,6 +256,7 @@ Planning session for: {topic}
 Specification: docs/workflow/specification/{topic}.md
 Additional context: {summary of user's answers from Step 5}
 Cross-cutting references: {list of applicable cross-cutting specs with brief summaries, or "none"}
+Recommended output format: {common_format from discovery if non-empty, otherwise "none"}
 
 Invoke the technical-planning skill.
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.50",
+  "version": "2.0.52",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",