@leeovery/claude-technical-workflows 2.1.42 → 2.2.1

package/README.md

@@ -134,7 +134,7 @@ Discussion ──▶ Specification ──▶ Planning ──▶ Implementation
 
 **How it works:** After each phase completes, a plan mode bridge clears context and advances to the next phase automatically. You approve each transition with "clear context and continue" — this keeps each phase in a clean context window.
 
-If a session is interrupted, run `/continue-feature` to pick up where you left off. It reads artifact state to determine the next phase.
+If a session is interrupted, run `/workflow-start` to pick up where you left off. It discovers artifact state and routes to the next phase.
 
 ### Under the Hood
 
@@ -233,29 +233,30 @@ skills/
 ├── # Processing skills (model-invocable)
 ├── technical-research/              # Explore and validate ideas
 ├── technical-discussion/            # Document discussions
+├── technical-investigation/         # Investigate bugs (bugfix pipeline)
 ├── technical-specification/         # Build validated specifications
 ├── technical-planning/              # Create implementation plans
 ├── technical-implementation/        # Execute via TDD
 ├── technical-review/                # Validate against artefacts
 │
+├── # Unified entry points
+├── workflow-start/                  # Discovers state, routes by work type
+├── workflow-bridge/                 # Pipeline continuation — next phase routing
+│
 ├── # Entry-point skills (user-invocable)
 ├── migrate/                         # Keep workflow files in sync with system design
 ├── start-feature/                   # Pipeline: discussion → spec → plan → impl → review
-├── continue-feature/                # Pipeline: route feature to next phase
+├── start-bugfix/                    # Pipeline: investigation → spec → plan → impl → review
 ├── link-dependencies/               # Standalone: wire cross-topic deps
 ├── start-research/                  # Begin research
 ├── start-discussion/                # Begin discussions
+├── start-investigation/             # Begin investigation (bugfix)
 ├── start-specification/             # Begin specification
 ├── start-planning/                  # Begin planning
 ├── start-implementation/            # Begin implementation
 ├── start-review/                    # Begin review
 ├── status/                          # Show workflow status
-├── view-plan/                       # View plan tasks
-│
-├── # Bridge skills (model-invocable — pipeline pre-flight)
-├── begin-planning/                  # Pre-flight for planning in pipeline
-├── begin-implementation/            # Pre-flight for implementation in pipeline
-└── begin-review/                    # Pre-flight for review in pipeline
+└── view-plan/                       # View plan tasks
 
 agents/
 ├── review-task-verifier.md           # Verifies single task implementation for review
@@ -322,7 +323,7 @@ Independent skills that gather inputs flexibly (inline context, files, or prompt
 | Skill                                                   | Description                                                                                                                                 |
 |---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
 | [**/start-feature**](skills/start-feature/)              | Start a new feature through the full pipeline. Gathers context, creates a discussion, then bridges through specification → planning → implementation → review. |
-| [**/continue-feature**](skills/continue-feature/)        | Continue a feature through its next pipeline phase. Routes automatically based on artifact state. Used manually or from plan mode bridges.  |
+| [**/start-bugfix**](skills/start-bugfix/)                | Start a bugfix through the pipeline. Gathers bug context, creates an investigation, then bridges through specification → planning → implementation → review. |
 | [**/link-dependencies**](skills/link-dependencies/)      | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
 
 ### Creating Custom Skills

package/hooks/workflows/compact-recovery.sh

@@ -32,18 +32,6 @@ topic=$(grep '^topic:' "$SESSION_FILE" | awk '{print $2}')
 skill=$(grep '^skill:' "$SESSION_FILE" | awk '{print $2}')
 artifact=$(grep '^artifact:' "$SESSION_FILE" | awk '{print $2}')
 
-# Check for pipeline section
-has_pipeline=false
-if grep -q '^pipeline:' "$SESSION_FILE"; then
-  has_pipeline=true
-  # Extract after_conclude content (indented block after "after_conclude: |")
-  pipeline_content=$(awk '
-    /^  after_conclude:/ { capture=1; next }
-    capture && /^[^ ]/ { exit }
-    capture && /^    / { sub(/^    /, ""); print }
-  ' "$SESSION_FILE")
-fi
-
 # Build additionalContext
 context="CONTEXT COMPACTION — SESSION RECOVERY
 
@@ -59,18 +47,10 @@ Skill: ${skill}
 3. Re-read the artifact: ${artifact}
 4. Continue working until the skill reaches its natural conclusion
 
-The files on disk are authoritative — not the conversation summary."
-
-if [ "$has_pipeline" = true ] && [ -n "$pipeline_content" ]; then
-  context="${context}
+The files on disk are authoritative — not the conversation summary.
 
-─── AFTER CONCLUSION ONLY ───
-
-${pipeline_content}
-
-Do NOT enter plan mode or invoke continue-feature until the current
-phase is complete. Finish the current phase first."
-fi
+When the processing skill concludes, it will invoke workflow-bridge automatically
+if the artifact has a work_type set. Do not manually handle pipeline continuation."
 
 # Escape context for JSON output
 json_context=$(printf '%s' "$context" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/' | tr -d '\n')

package/hooks/workflows/write-session-state.sh

@@ -6,7 +6,7 @@
 # compaction recovery.
 #
 # Usage:
-#   write-session-state.sh "<topic>" "<skill-path>" "<artifact-path>" [--pipeline "<after-conclude instructions>"]
+#   write-session-state.sh "<topic>" "<skill-path>" "<artifact-path>"
 #
 # Requires CLAUDE_SESSION_ID in environment (set by session-env.sh).
 #
@@ -26,41 +26,17 @@ fi
 topic="$1"
 skill="$2"
 artifact="$3"
-pipeline_content=""
-
-# Parse optional --pipeline flag
-shift 3 || true
-while [ $# -gt 0 ]; do
-  case "$1" in
-    --pipeline)
-      pipeline_content="$2"
-      shift 2
-      ;;
-    *)
-      shift
-      ;;
-  esac
-done
 
 SESSIONS_DIR="$PROJECT_DIR/.workflows/.cache/sessions"
 mkdir -p "$SESSIONS_DIR"
 
 SESSION_FILE="$SESSIONS_DIR/${CLAUDE_SESSION_ID}.yaml"
 
-# Write base fields
+# Write session state
 cat > "$SESSION_FILE" <<EOF
 topic: ${topic}
 skill: ${skill}
 artifact: ${artifact}
 EOF
 
-# Append pipeline section if provided
-if [ -n "$pipeline_content" ]; then
-  cat >> "$SESSION_FILE" <<EOF
-pipeline:
-  after_conclude: |
-$(echo "$pipeline_content" | sed 's/^/    /')
-EOF
-fi
-
 exit 0

package/package.json

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

package/skills/link-dependencies/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: link-dependencies
-description: "Scan all plans and wire up cross-topic dependencies. Finds unresolved external dependencies, matches them to tasks in other plans, and updates both the plan index and output format."
 disable-model-invocation: true
 hooks:
   PreToolUse:

package/skills/migrate/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: migrate
-description: "Run migrations to keep workflow files in sync with the current system design. This skill is mandatory before running any workflow skill."
 allowed-tools: Bash(.claude/skills/migrate/scripts/migrate.sh)
 ---
 

package/skills/migrate/scripts/migrations/013-discussion-work-type.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+#
+# 013-discussion-work-type.sh
+#
+# Adds work_type: greenfield to discussion documents that don't have the field.
+#
+# Existing discussions without work_type are assumed to be greenfield work.
+# New discussions will have work_type set by the skill that creates them.
+#
+# This script is sourced by migrate.sh and has access to:
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="013"
+DISC_DIR=".workflows/discussion"
+
+# Skip if no discussion directory
+if [ ! -d "$DISC_DIR" ]; then
+    return 0
+fi
+
+# Helper: Extract frontmatter safely (between first pair of --- delimiters)
+extract_frontmatter() {
+    local file="$1"
+    awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null
+}
+
+# Helper: Extract content after frontmatter (preserving all body ---)
+extract_content() {
+    local file="$1"
+    awk '/^---$/ && c<2 {c++; next} c>=2 {print}' "$file" 2>/dev/null
+}
+
+# Process each discussion file
+for file in "$DISC_DIR"/*.md; do
+    [ -f "$file" ] || continue
+
+    # Check if file has YAML frontmatter
+    if ! head -1 "$file" 2>/dev/null | grep -q "^---$"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if work_type already exists
+    frontmatter=$(extract_frontmatter "$file")
+    if echo "$frontmatter" | grep -q "^work_type:"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Add work_type: greenfield after status field
+    content=$(extract_content "$file")
+
+    # Build new frontmatter with work_type after status
+    new_frontmatter=$(echo "$frontmatter" | awk '
+        /^status:/ { print; print "work_type: greenfield"; next }
+        { print }
+    ')
+
+    # If status wasn't found, add work_type at the end
+    if ! echo "$new_frontmatter" | grep -q "^work_type:"; then
+        new_frontmatter="$frontmatter
+work_type: greenfield"
+    fi
+
+    # Write updated file
+    {
+        echo "---"
+        echo "$new_frontmatter"
+        echo "---"
+        echo "$content"
+    } > "$file"
+
+    report_update "$file" "added work_type: greenfield"
+done

package/skills/migrate/scripts/migrations/014-specification-work-type.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+#
+# 014-specification-work-type.sh
+#
+# Adds work_type: greenfield to specification documents that don't have the field.
+#
+# Existing specifications without work_type are assumed to be greenfield work.
+# New specifications will have work_type set by the skill that creates them.
+#
+# This script is sourced by migrate.sh and has access to:
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="014"
+SPEC_DIR=".workflows/specification"
+
+# Skip if no specification directory
+if [ ! -d "$SPEC_DIR" ]; then
+    return 0
+fi
+
+# Helper: Extract frontmatter safely (between first pair of --- delimiters)
+extract_frontmatter() {
+    local file="$1"
+    awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null
+}
+
+# Helper: Extract content after frontmatter (preserving all body ---)
+extract_content() {
+    local file="$1"
+    awk '/^---$/ && c<2 {c++; next} c>=2 {print}' "$file" 2>/dev/null
+}
+
+# Process each specification file
+for file in "$SPEC_DIR"/*/specification.md; do
+    [ -f "$file" ] || continue
+
+    # Check if file has YAML frontmatter
+    if ! head -1 "$file" 2>/dev/null | grep -q "^---$"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if work_type already exists
+    frontmatter=$(extract_frontmatter "$file")
+    if echo "$frontmatter" | grep -q "^work_type:"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Add work_type: greenfield after type field
+    content=$(extract_content "$file")
+
+    # Build new frontmatter with work_type after type
+    new_frontmatter=$(echo "$frontmatter" | awk '
+        /^type:/ { print; print "work_type: greenfield"; next }
+        { print }
+    ')
+
+    # If type wasn't found, add work_type at the end
+    if ! echo "$new_frontmatter" | grep -q "^work_type:"; then
+        new_frontmatter="$frontmatter
+work_type: greenfield"
+    fi
+
+    # Write updated file
+    {
+        echo "---"
+        echo "$new_frontmatter"
+        echo "---"
+        echo "$content"
+    } > "$file"
+
+    report_update "$file" "added work_type: greenfield"
+done

package/skills/migrate/scripts/migrations/015-plan-work-type.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+#
+# 015-plan-work-type.sh
+#
+# Adds work_type: greenfield to plan documents that don't have the field.
+#
+# Existing plans without work_type are assumed to be greenfield work.
+# New plans will have work_type set by the skill that creates them.
+#
+# This script is sourced by migrate.sh and has access to:
+#   - report_update "filepath" "description"
+#   - report_skip "filepath"
+#
+
+MIGRATION_ID="015"
+PLAN_DIR=".workflows/planning"
+
+# Skip if no planning directory
+if [ ! -d "$PLAN_DIR" ]; then
+    return 0
+fi
+
+# Helper: Extract frontmatter safely (between first pair of --- delimiters)
+extract_frontmatter() {
+    local file="$1"
+    awk 'BEGIN{c=0} /^---$/{c++; if(c==2) exit; next} c==1{print}' "$file" 2>/dev/null
+}
+
+# Helper: Extract content after frontmatter (preserving all body ---)
+extract_content() {
+    local file="$1"
+    awk '/^---$/ && c<2 {c++; next} c>=2 {print}' "$file" 2>/dev/null
+}
+
+# Process each plan file
+for file in "$PLAN_DIR"/*/plan.md; do
+    [ -f "$file" ] || continue
+
+    # Check if file has YAML frontmatter
+    if ! head -1 "$file" 2>/dev/null | grep -q "^---$"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Check if work_type already exists
+    frontmatter=$(extract_frontmatter "$file")
+    if echo "$frontmatter" | grep -q "^work_type:"; then
+        report_skip "$file"
+        continue
+    fi
+
+    # Add work_type: greenfield after status field
+    content=$(extract_content "$file")
+
+    # Build new frontmatter with work_type after status
+    new_frontmatter=$(echo "$frontmatter" | awk '
+        /^status:/ { print; print "work_type: greenfield"; next }
+        { print }
+    ')
+
+    # If status wasn't found, add work_type at the end
+    if ! echo "$new_frontmatter" | grep -q "^work_type:"; then
+        new_frontmatter="$frontmatter
+work_type: greenfield"
+    fi
+
+    # Write updated file
+    {
+        echo "---"
+        echo "$new_frontmatter"
+        echo "---"
+        echo "$content"
+    } > "$file"
+
+    report_update "$file" "added work_type: greenfield"
+done

package/skills/start-bugfix/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: start-bugfix
+disable-model-invocation: true
+allowed-tools: Bash(ls .workflows/investigation/), Bash(.claude/hooks/workflows/write-session-state.sh)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
+---
+
+Start a new bugfix and route it through the pipeline: Investigation → Specification → Planning → Implementation → Review.
+
+> **ZERO OUTPUT RULE**: Do not narrate your processing. Produce no output until a step or reference file explicitly specifies display content. No "proceeding with...", no discovery summaries, no routing decisions, no transition text. Your first output must be content explicitly called for by the instructions.
+
+## Instructions
+
+Follow these steps EXACTLY as written. Do not skip steps or combine them.
+
+**CRITICAL**: This guidance is mandatory.
+
+- After each user interaction, STOP and wait for their response before proceeding
+- Never assume or anticipate user choices
+- Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
+- Complete each step fully before moving to the next
+
+---
+
+## Resuming After Context Refresh
+
+Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:
+
+1. **Re-read this skill file completely.** Do not rely on your summary of it.
+2. **Identify the topic.** Check conversation history for the topic name. If unknown, check `.workflows/investigation/` for recently modified directories via `git log --oneline -5`.
+3. **Determine current step from artifacts:**
+   - No investigation file exists → resume at **Step 1**
+   - Investigation exists with `status: in-progress` → resume at **Step 3** (re-invoke technical-investigation)
+   - Investigation exists with `status: concluded` → already handled by processing skill's bridge invocation
+4. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
+## Step 0: Run Migrations
+
+**This step is mandatory. You must complete it before proceeding.**
+
+Invoke the `/migrate` skill and assess its output.
+
+#### If files were updated
+
+**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**.
+
+---
+
+## Step 1: Gather Bug Context
+
+Load **[gather-bug-context.md](references/gather-bug-context.md)** and follow its instructions.
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Topic Name and Conflict Check
+
+Load **[topic-name-check.md](references/topic-name-check.md)** and follow its instructions.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Invoke Investigation
+
+Load **[invoke-investigation.md](references/invoke-investigation.md)** and follow its instructions.

package/skills/start-bugfix/references/gather-bug-context.md

@@ -0,0 +1,75 @@
+# Gather Bug Context
+
+*Reference for **[start-bugfix](../SKILL.md)***
+
+---
+
+Gather context about the bug through a structured interview. Ask questions one at a time with STOP gates between each.
+
+**Note**: If the user has already provided context in their initial message, acknowledge what they've shared and skip questions that are already answered. Only ask what's missing.
+
+## Question 1: What's broken?
+
+> *Output the next fenced block as a code block:*
+
+```
+Starting new bugfix investigation.
+
+What's broken?
+
+- Expected behavior vs actual behavior
+- Error messages, if any
+```
+
+**STOP.** Wait for user response.
+
+## Question 2: How does it manifest?
+
+> *Output the next fenced block as a code block:*
+
+```
+How is the bug manifesting?
+
+- Where does it surface? (UI, API, logs, data)
+- How often? (always, intermittent, specific conditions)
+```
+
+**STOP.** Wait for user response.
+
+## Question 3: Reproduction
+
+> *Output the next fenced block as a code block:*
+
+```
+Can you reproduce it?
+
+- Steps to trigger the bug
+- Environment or conditions where it occurs
+(Or "unknown" if not yet reproducible)
+```
+
+**STOP.** Wait for user response.
+
+## Question 4: Hypotheses
+
+> *Output the next fenced block as a code block:*
+
+```
+Any initial hypotheses about the cause?
+
+- Suspected area of code or component
+- Recent changes that might be related
+(Or "none" if no suspicion yet)
+```
+
+**STOP.** Wait for user response.
+
+## Compile Context
+
+After gathering answers, compile the bug context into a structured summary that will be passed to the investigation skill. Do not output the summary — it will be used in the next step.
+
+The compiled context should capture:
+- **Problem**: Expected vs actual behavior
+- **Manifestation**: How and where the bug surfaces
+- **Reproduction**: Steps to trigger, if known
+- **Initial hypothesis**: User's suspicion about cause

package/skills/start-bugfix/references/invoke-investigation.md

@@ -0,0 +1,46 @@
+# Invoke Investigation
+
+*Reference for **[start-bugfix](../SKILL.md)***
+
+---
+
+Save a session bookmark for compaction recovery, then invoke the processing skill.
+
+> *Output the next fenced block as a code block:*
+
+```
+Saving session state for compaction recovery.
+```
+
+```bash
+.claude/hooks/workflows/write-session-state.sh \
+  "{topic}" \
+  "skills/technical-investigation/SKILL.md" \
+  ".workflows/investigation/{topic}/investigation.md"
+```
+
+## Handoff
+
+Invoke the [technical-investigation](../../technical-investigation/SKILL.md) skill:
+
+```
+Investigation session for: {topic}
+Work type: bugfix
+Initial bug context:
+- Problem: {problem description from gather-bug-context}
+- Manifestation: {how it surfaces}
+- Reproduction: {steps if provided, otherwise "unknown"}
+- Initial hypothesis: {user's suspicion if any}
+
+Create investigation file: .workflows/investigation/{topic}/investigation.md
+
+The investigation frontmatter should include:
+- topic: {topic}
+- status: in-progress
+- work_type: bugfix
+- date: {today}
+
+Invoke the technical-investigation skill.
+```
+
+When the investigation concludes, the processing skill will detect `work_type: bugfix` in the artifact and invoke workflow-bridge automatically.

package/skills/start-bugfix/references/topic-name-check.md

@@ -0,0 +1,59 @@
+# Topic Name and Conflict Check
+
+*Reference for **[start-bugfix](../SKILL.md)***
+
+---
+
+Based on the bug description, suggest a topic name:
+
+> *Output the next fenced block as a code block:*
+
+```
+Suggested topic name: {suggested-topic:(kebabcase)}
+
+This will create: .workflows/investigation/{suggested-topic}/investigation.md
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+Is this name okay?
+
+- **`y`/`yes`** — Use this name
+- **`s`/`something else`** — Suggest a different name
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+Once the topic name is confirmed, check for naming conflicts:
+
+```bash
+ls .workflows/investigation/
+```
+
+#### If an investigation with the same name exists
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+An investigation named "{topic}" already exists.
+
+- **`r`/`resume`** — Resume the existing investigation
+- **`n`/`new`** — Choose a different name
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If resuming
+
+Check the investigation status. If in-progress:
+
+→ Return to **[the skill](../SKILL.md)** for **Step 3**.
+
+#### If no conflict
+
+→ Return to **[the skill](../SKILL.md)**.