@leeovery/claude-technical-workflows 2.1.41 → 2.2.0

package/skills/start-review/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: start-review
-description: "Start a review session from an existing plan and implementation. Discovers available plans, validates implementation exists, and invokes the technical-review skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/skills/start-review/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/start-review/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh), Bash(ls .workflows/planning/), Bash(ls .workflows/implementation/)
 hooks:
   PreToolUse:
     - hooks:
@@ -52,9 +51,13 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 Invoke the `/migrate` skill and assess its output.
 
-**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+#### If files were updated
 
-**If no updates needed**: Proceed to Step 1.
+**STOP.** Wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding.
+
+#### If no updates needed
+
+→ Proceed to **Step 1**.
 
 ---
 
@@ -88,99 +91,68 @@ Parse the discovery output to understand:
 - `reviewed_plan_count` - plans that have been reviewed
 - `all_reviewed` - whether all implemented plans have reviews
 
-**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.
+**IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state.
 
 → Proceed to **Step 2**.
 
 ---
 
-## Step 2: Route Based on Scenario
+## Step 2: Determine Mode
 
-Use `state.scenario` from the discovery output to determine the path:
+Check for arguments: work_type = `$0`, topic = `$1`
 
-#### If scenario is "no_plans"
+#### If work_type and topic are both provided
 
-No plans exist yet.
+→ Proceed to **Step 3**.
 
-> *Output the next fenced block as a code block:*
-
-```
-Review Overview
-
-No plans found in .workflows/planning/
-
-The review phase requires a completed implementation based on a plan.
-Run /start-planning first to create a plan, then /start-implementation
-to build it.
-```
-
-**STOP.** Do not proceed — terminal condition.
-
-#### If all_reviewed is true
-
-All implemented plans have been reviewed.
-
-> *Output the next fenced block as a code block:*
-
-```
-Review Overview
+#### If work_type is provided without topic
 
-All {N} implemented plans have been reviewed.
+Store work_type for the handoff.
 
-1. {topic:(titlecase)}
-   └─ Review: x{review_count} — r{latest_review_version} ({latest_review_verdict})
-   └─ Synthesis: @if(has_synthesis) completed @else pending @endif
+→ Proceed to **Step 4**.
 
-2. ...
-```
+#### If neither is provided
 
-> *Output the next fenced block as markdown (not a code block):*
+→ Proceed to **Step 4**.
 
-```
-· · · · · · · · · · · ·
-All plans have been reviewed.
+---
 
-- **`a`/`analysis`** — Synthesize findings from existing reviews into tasks
-- **`r`/`re-review`** — Re-review a plan (creates new review version)
+## Step 3: Validate Plan and Implementation
 
-Select an option:
-· · · · · · · · · · · ·
-```
+Load **[validate-artifacts.md](references/validate-artifacts.md)** and follow its instructions as written.
 
-**STOP.** Wait for user response.
+→ Proceed to **Step 5**.
 
-#### If analysis
+---
 
-→ Proceed to **Step 4** with scope set to "analysis".
+## Step 4: Route Based on Scenario
 
-#### If re-review
+Load **[route-scenario.md](references/route-scenario.md)** and follow its instructions as written.
 
-→ Proceed to **Step 3**, incrementing the review version for the selected plan.
+---
 
-#### If scenario is "single_plan" or "multiple_plans"
+## Step 5: Determine Review Version
 
-Plans exist (some may have reviews, some may not).
+Load **[determine-review-version.md](references/determine-review-version.md)** and follow its instructions as written.
 
-→ Proceed to **Step 3** to present options.
+→ Proceed to **Step 8**.
 
 ---
 
-## Step 3: Display Plans
+## Step 6: Display Plans
 
 Load **[display-plans.md](references/display-plans.md)** and follow its instructions as written.
 
-→ Proceed to **Step 4**.
-
 ---
 
-## Step 4: Select Plans
+## Step 7: Select Plans
 
 Load **[select-plans.md](references/select-plans.md)** and follow its instructions as written.
 
-→ Proceed to **Step 5**.
+→ Proceed to **Step 8**.
 
 ---
 
-## Step 5: Invoke the Skill
+## Step 8: Invoke the Skill
 
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-review/references/determine-review-version.md

@@ -0,0 +1,24 @@
+# Determine Review Version
+
+*Reference for **[start-review](../SKILL.md)***
+
+---
+
+Check if reviews already exist for this topic from the discovery output.
+
+**If no reviews exist:**
+
+Set review_version = 1.
+
+**If reviews exist:**
+
+Find the latest review version for this topic.
+Set review_version = latest_version + 1.
+
+> *Output the next fenced block as a code block:*
+
+```
+Starting review r{review_version} for "{topic:(titlecase)}".
+```
+
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-review/references/display-plans.md

@@ -87,7 +87,7 @@ Automatically proceeding with "{topic:(titlecase)}".
 Scope: single
 ```
 
-→ Proceed directly to **Step 5**.
+→ Return to **[the skill](../SKILL.md)** for **Step 8**.
 
 #### If multiple reviewable plans
 
@@ -108,4 +108,4 @@ Select an option:
 
 **STOP.** Wait for user response.
 
-→ Based on user choice, proceed to **Step 4**.
+→ Return to **[the skill](../SKILL.md)** for **Step 7**.

package/skills/start-review/references/route-scenario.md

@@ -0,0 +1,74 @@
+# Route Based on Scenario
+
+*Reference for **[start-review](../SKILL.md)***
+
+---
+
+Discovery mode — use the discovery output from Step 1.
+
+Use `state.scenario` from the discovery output to determine the path:
+
+#### If scenario is "no_plans"
+
+No plans exist yet.
+
+> *Output the next fenced block as a code block:*
+
+```
+Review Overview
+
+No plans found in .workflows/planning/
+
+The review phase requires a completed implementation based on a plan.
+Run /start-planning first to create a plan, then /start-implementation
+to build it.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If all_reviewed is true
+
+All implemented plans have been reviewed.
+
+> *Output the next fenced block as a code block:*
+
+```
+Review Overview
+
+All {N} implemented plans have been reviewed.
+
+1. {topic:(titlecase)}
+   └─ Review: x{review_count} — r{latest_review_version} ({latest_review_verdict})
+   └─ Synthesis: @if(has_synthesis) completed @else pending @endif
+
+2. ...
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+All plans have been reviewed.
+
+- **`a`/`analysis`** — Synthesize findings from existing reviews into tasks
+- **`r`/`re-review`** — Re-review a plan (creates new review version)
+
+Select an option:
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+**If analysis:**
+
+→ Return to **[the skill](../SKILL.md)** for **Step 8**.
+
+**If re-review:**
+
+→ Return to **[the skill](../SKILL.md)** for **Step 6**.
+
+#### If scenario is "single_plan" or "multiple_plans"
+
+Plans exist (some may have reviews, some may not).
+
+→ Return to **[the skill](../SKILL.md)** for **Step 6**.

package/skills/start-review/references/select-plans.md

@@ -4,7 +4,7 @@
 
 ---
 
-This step only applies for `single`, `multi`, or `all` scope chosen in Step 3.
+This step only applies for `single`, `multi`, or `all` scope chosen in Step 6.
 
 #### If scope is "analysis"
 
@@ -29,17 +29,19 @@ Select an option:
 
 If `select`, present numbered list of reviewed plans for the user to choose from (comma-separated numbers).
 
+→ Return to **[the skill](../SKILL.md)**.
+
 #### If single review exists
 
 Automatically proceed with the only available review.
 
-→ Proceed to **Step 5**.
+→ Return to **[the skill](../SKILL.md)**.
 
 #### If scope is "all"
 
 All reviewable plans are included. No selection needed. Each plan will be reviewed independently.
 
-→ Proceed directly to **Step 5**.
+→ Return to **[the skill](../SKILL.md)**.
 
 #### If scope is "single"
 
@@ -47,13 +49,13 @@ All reviewable plans are included. No selection needed. Each plan will be review
 
 ```
 · · · · · · · · · · · ·
-Which plan would you like to review? (Enter a number from Step 3)
+Which plan would you like to review? (Enter a number from Step 6)
 · · · · · · · · · · · ·
 ```
 
 **STOP.** Wait for user response.
 
-→ Proceed to **Step 5**.
+→ Return to **[the skill](../SKILL.md)**.
 
 #### If scope is "multi"
 
@@ -67,4 +69,4 @@ Which plans to include? (Enter numbers separated by commas, e.g. 1,3)
 
 **STOP.** Wait for user response.
 
-→ Proceed to **Step 5**.
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-review/references/validate-artifacts.md

@@ -0,0 +1,63 @@
+# Validate Plan and Implementation
+
+*Reference for **[start-review](../SKILL.md)***
+
+---
+
+Check if plan and implementation exist and are ready.
+
+```bash
+ls .workflows/planning/
+ls .workflows/implementation/
+```
+
+Read `.workflows/planning/{topic}/plan.md` frontmatter.
+
+#### If plan doesn't exist
+
+> *Output the next fenced block as a code block:*
+
+```
+Plan Missing
+
+No plan found for "{topic:(titlecase)}".
+
+A concluded plan and implementation are required for review.
+Run /start-planning {work_type} {topic} to create one.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+Read `.workflows/implementation/{topic}/tracking.md` frontmatter.
+
+#### If implementation tracking doesn't exist
+
+> *Output the next fenced block as a code block:*
+
+```
+Implementation Missing
+
+No implementation found for "{topic:(titlecase)}".
+
+A completed implementation is required for review.
+Run /start-implementation {work_type} {topic} to start one.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If implementation status is not "completed"
+
+> *Output the next fenced block as a code block:*
+
+```
+Implementation Not Complete
+
+The implementation for "{topic:(titlecase)}" is not yet completed.
+Run /start-implementation {work_type} {topic} to continue.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If plan and implementation are both ready
+
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-review/scripts/discovery.sh

@@ -69,6 +69,8 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         specification=$(extract_field "$file" "specification")
         specification=${specification:-"${name}/specification.md"}
         plan_id=$(extract_field "$file" "plan_id")
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
 
         # Check if linked specification exists
         spec_exists="false"
@@ -107,6 +109,7 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         echo "    - name: \"$name\""
         echo "      topic: \"$topic\""
         echo "      status: \"$status\""
+        echo "      work_type: \"$work_type\""
         echo "      date: \"$date\""
         echo "      format: \"$format\""
         echo "      specification: \"$specification\""

package/skills/start-specification/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: start-specification
-description: "Start a specification session from concluded discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/skills/start-specification/scripts/discovery.sh), Bash(mkdir -p .workflows/.state), Bash(rm .workflows/.state/discussion-consolidation-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/start-specification/scripts/discovery.sh), Bash(mkdir -p .workflows/.state), Bash(rm .workflows/.state/discussion-consolidation-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh), Bash(ls .workflows/discussion/), Bash(ls .workflows/investigation/)
 hooks:
   PreToolUse:
     - hooks:
@@ -52,9 +51,13 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 
 Invoke the `/migrate` skill and assess its output.
 
-**If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
+#### If files were updated
 
-**If no updates needed**: Proceed to Step 1.
+**STOP.** Wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding.
+
+#### If no updates needed
+
+→ Proceed to **Step 1**.
 
 ---
 
@@ -80,41 +83,62 @@ Parse the discovery output to understand:
 
 **From `current_state`:** `concluded_count`, `spec_count`, `has_discussions`, `has_concluded`, `has_specs`, and other counts/booleans for routing.
 
-**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.
+**IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state.
 
 → Proceed to **Step 2**.
 
 ---
 
-## Step 2: Check Prerequisites
-
-#### If has_discussions is false or has_concluded is false
+## Step 2: Determine Mode
 
-→ Load **[display-blocks.md](references/display-blocks.md)** and follow its instructions. **STOP.**
+Check for arguments: work_type = `$0`, topic = `$1`
 
-#### Otherwise
+#### If work_type and topic are both provided
 
 → Proceed to **Step 3**.
 
+#### If work_type is provided without topic
+
+Store work_type for the handoff.
+
+→ Proceed to **Step 6**.
+
+#### If neither is provided
+
+→ Proceed to **Step 6**.
+
+---
+
+## Step 3: Validate Source Material
+
+Load **[validate-source.md](references/validate-source.md)** and follow its instructions as written.
+
+→ Proceed to **Step 4**.
+
 ---
 
-## Step 3: Route
+## Step 4: Check Existing Specification
 
-Based on discovery state, load exactly ONE reference file:
+Load **[check-existing-spec.md](references/check-existing-spec.md)** and follow its instructions as written.
 
-#### If concluded_count == 1
+→ Proceed to **Step 5**.
 
-→ Load **[display-single.md](references/display-single.md)** and follow its instructions.
+---
 
-#### If cache status is "valid"
+## Step 5: Invoke the Skill (Bridge Mode)
 
-→ Load **[display-groupings.md](references/display-groupings.md)** and follow its instructions.
+Load **[invoke-skill-bridge.md](references/invoke-skill-bridge.md)** and follow its instructions as written.
 
-#### If spec_count == 0 and cache is "none" or "stale"
+---
+
+## Step 6: Check Prerequisites
 
-→ Load **[display-analyze.md](references/display-analyze.md)** and follow its instructions.
+Load **[check-prerequisites.md](references/check-prerequisites.md)** and follow its instructions as written.
 
-#### Otherwise
+→ Proceed to **Step 7**.
+
+---
 
-→ Load **[display-specs-menu.md](references/display-specs-menu.md)** and follow its instructions.
+## Step 7: Route Based on State
 
+Load **[route-scenario.md](references/route-scenario.md)** and follow its instructions as written.

package/skills/start-specification/references/check-existing-spec.md

@@ -0,0 +1,57 @@
+# Check Existing Specification
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Check if a specification already exists for this topic.
+
+Read `.workflows/specification/{topic}/specification.md` if it exists.
+
+#### If specification doesn't exist
+
+→ Return to **[the skill](../SKILL.md)** with verb="Creating".
+
+#### If specification exists with status "in-progress"
+
+> *Output the next fenced block as a code block:*
+
+```
+Specification In Progress
+
+A specification for "{topic:(titlecase)}" already exists and is in progress.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`r`/`resume`** — Resume the existing specification
+- **`s`/`start-fresh`** — Archive and start fresh
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If resume
+
+→ Return to **[the skill](../SKILL.md)** with verb="Continuing".
+
+#### If start-fresh
+
+Archive the existing spec.
+
+→ Return to **[the skill](../SKILL.md)** with verb="Creating".
+
+#### If specification exists with status "concluded"
+
+> *Output the next fenced block as a code block:*
+
+```
+Specification Concluded
+
+The specification for "{topic:(titlecase)}" has already concluded.
+Run /start-planning {work_type} {topic} to continue to planning.
+```
+
+**STOP.** Do not proceed — terminal condition.

package/skills/start-specification/references/check-prerequisites.md

@@ -0,0 +1,15 @@
+# Check Prerequisites
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Discovery mode — use the discovery output from Step 1 to check prerequisites.
+
+#### If has_discussions is false or has_concluded is false
+
+→ Load **[display-blocks.md](display-blocks.md)** and follow its instructions.
+
+#### Otherwise
+
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-specification/references/handoffs/continue-concluded.md

@@ -23,8 +23,11 @@ Saving session state so Claude can pick up where it left off if the conversation
 
 This skill's purpose is now fulfilled. Invoke the [technical-specification](../../../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded — it contains the instructions for how to proceed.
 
+Determine work_type: use the value from Step 2 if available. Otherwise, read work_type from the source discussion(s) frontmatter.
+
 ```
 Specification session for: {Title Case Name}
+Work type: {work_type}
 
 Continuing existing: .workflows/specification/{kebab-case-name}/specification.md (concluded)
 

package/skills/start-specification/references/handoffs/continue.md

@@ -23,8 +23,11 @@ Saving session state so Claude can pick up where it left off if the conversation
 
 This skill's purpose is now fulfilled. Invoke the [technical-specification](../../../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded — it contains the instructions for how to proceed.
 
+Determine work_type: use the value from Step 2 if available. Otherwise, read work_type from the source discussion(s) frontmatter.
+
 ```
 Specification session for: {Title Case Name}
+Work type: {work_type}
 
 Continuing existing: .workflows/specification/{kebab-case-name}/specification.md
 

package/skills/start-specification/references/handoffs/create-with-incorporation.md

@@ -21,8 +21,11 @@ Saving session state so Claude can pick up where it left off if the conversation
 
 This skill's purpose is now fulfilled. Invoke the [technical-specification](../../../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded — it contains the instructions for how to proceed.
 
+Determine work_type: use the value from Step 2 if available. Otherwise, read work_type from the source discussion(s) frontmatter.
+
 ```
 Specification session for: {Title Case Name}
+Work type: {work_type}
 
 Source discussions:
 - .workflows/discussion/{discussion-name}.md

package/skills/start-specification/references/handoffs/create.md

@@ -21,8 +21,11 @@ Saving session state so Claude can pick up where it left off if the conversation
 
 This skill's purpose is now fulfilled. Invoke the [technical-specification](../../../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded — it contains the instructions for how to proceed.
 
+Determine work_type: use the value from Step 2 if available. Otherwise, read work_type from the source discussion(s) frontmatter.
+
 ```
 Specification session for: {Title Case Name}
+Work type: {work_type}
 
 Sources:
 - .workflows/discussion/{discussion-name}.md

package/skills/start-specification/references/handoffs/unify-with-incorporation.md

@@ -21,8 +21,11 @@ Saving session state so Claude can pick up where it left off if the conversation
 
 This skill's purpose is now fulfilled. Invoke the [technical-specification](../../../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded — it contains the instructions for how to proceed.
 
+Determine work_type: use the value from Step 2 if available. Otherwise, read work_type from the source discussion(s) frontmatter.
+
 ```
 Specification session for: Unified
+Work type: {work_type}
 
 Source discussions:
 - .workflows/discussion/{discussion-name}.md

package/skills/start-specification/references/handoffs/unify.md

@@ -21,8 +21,11 @@ Saving session state so Claude can pick up where it left off if the conversation
 
 This skill's purpose is now fulfilled. Invoke the [technical-specification](../../../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded — it contains the instructions for how to proceed.
 
+Determine work_type: use the value from Step 2 if available. Otherwise, read work_type from the source discussion(s) frontmatter.
+
 ```
 Specification session for: Unified
+Work type: {work_type}
 
 Sources:
 - .workflows/discussion/{discussion-name}.md