@leeovery/claude-technical-workflows 2.1.7 → 2.1.9

package/README.md

@@ -265,14 +265,6 @@ agents/
 ├── planning-task-author.md          # Write full task detail
 └── planning-dependency-grapher.md   # Analyze task dependencies and priorities
 
-scripts/                             # Helper scripts for skills
-├── migrate.sh                       # Migration orchestrator
-├── discovery-for-discussion.sh      # Discovery for discussion skill
-├── discovery-for-specification.sh   # Discovery for specification skill
-├── discovery-for-planning.sh        # Discovery for planning skill
-├── discovery-for-implementation-and-review.sh  # Discovery for impl/review
-└── migrations/                      # Individual migration scripts (numbered)
-
 tests/
 └── scripts/                         # Shell script tests for discovery and migrations
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.1.7",
+  "version": "2.1.9",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",
@@ -12,7 +12,7 @@
   "scripts": {
     "postinstall": "claude-manager add",
     "preuninstall": "npx --yes --package=@leeovery/claude-manager claude-manager remove",
-    "test:scripts:discovery": "bash tests/scripts/test-discovery-for-discussion.sh && bash tests/scripts/test-discovery-for-specification.sh && bash tests/scripts/test-discovery-for-planning.sh && bash tests/scripts/test-discovery-for-implementation-and-review.sh",
+    "test:scripts:discovery": "bash tests/scripts/test-discovery-for-discussion.sh && bash tests/scripts/test-discovery-for-specification.sh && bash tests/scripts/test-discovery-for-planning.sh && bash tests/scripts/test-discovery-for-implementation.sh && bash tests/scripts/test-discovery-for-review.sh",
     "test:scripts:migration": "bash tests/scripts/test-migration-001.sh && bash tests/scripts/test-migration-002.sh && bash tests/scripts/test-migration-003.sh"
   },
   "dependencies": {
@@ -22,7 +22,6 @@
     "skills",
     "commands",
     "agents",
-    "hooks",
-    "scripts"
+    "hooks"
   ]
 }

package/skills/migrate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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(../../scripts/migrate.sh)
+allowed-tools: Bash(./scripts/migrate.sh)
 ---
 
 # Migrate
@@ -13,7 +13,7 @@ Keeps your workflow files up to date with how the system is designed to work. Ru
 Run the migration script:
 
 ```bash
-../../scripts/migrate.sh
+./scripts/migrate.sh
 ```
 
 ### If files were updated

package/skills/start-discussion/SKILL.md

@@ -2,7 +2,7 @@
 name: start-discussion
 description: "Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill."
 disable-model-invocation: true
-allowed-tools: Bash(../../scripts/discovery-for-discussion.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md)
+allowed-tools: Bash(.claude/skills/start-discussion/scripts/discovery.sh), Bash(./scripts/discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md)
 ---
 
 Invoke the **technical-discussion** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-discussion/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-../../scripts/discovery-for-discussion.sh
+./scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `research` section:**
 - `exists` - whether research files exist

package/skills/start-implementation/SKILL.md

@@ -2,7 +2,7 @@
 name: start-implementation
 description: "Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill."
 disable-model-invocation: true
-allowed-tools: Bash(../../scripts/discovery-for-implementation-and-review.sh)
+allowed-tools: Bash(.claude/skills/start-implementation/scripts/discovery.sh), Bash(./scripts/discovery.sh)
 ---
 
 Invoke the **technical-implementation** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-implementation/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-../../scripts/discovery-for-implementation-and-review.sh
+./scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `plans` section:**
 - `exists` - whether any plans exist

package/{scripts/discovery-for-implementation-and-review.sh → skills/start-implementation/scripts/discovery.sh}

@@ -1,8 +1,8 @@
 #!/bin/bash
 #
-# Discovers the current state of plans for /start-implementation and /start-review commands.
+# Discovers the current state of plans for /start-implementation command.
 #
-# Outputs structured YAML that the commands can consume directly.
+# Outputs structured YAML that the command can consume directly.
 #
 
 set -eo pipefail

package/skills/start-planning/SKILL.md

@@ -2,7 +2,7 @@
 name: start-planning
 description: "Start a planning session from an existing specification. Discovers available specifications, gathers context, and invokes the technical-planning skill."
 disable-model-invocation: true
-allowed-tools: Bash(../../scripts/discovery-for-planning.sh)
+allowed-tools: Bash(.claude/skills/start-planning/scripts/discovery.sh), Bash(./scripts/discovery.sh)
 ---
 
 Invoke the **technical-planning** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-planning/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-../../scripts/discovery-for-planning.sh
+./scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `specifications` section:**
 - `exists` - whether any specifications exist

package/skills/start-research/SKILL.md

@@ -19,7 +19,7 @@ This is **Phase 1** of the six-phase workflow:
 | 5. Implementation | DOING - tests first, then code | |
 | 6. Review | VALIDATING - check work against artifacts | |
 
-**Stay in your lane**: Explore freely. This is the time for broad thinking, feasibility checks, and learning. Don't jump to formal discussions or specifications yet.
+**Stay in your lane**: Explore freely. This is the time for broad thinking, feasibility checks, and learning. Surface options and tradeoffs — don't make decisions. When a topic converges toward a conclusion, that's a signal it's ready for discussion phase, not a cue to start deciding. Park it and move on.
 
 ---
 

package/skills/start-review/SKILL.md

@@ -2,7 +2,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(../../scripts/discovery-for-implementation-and-review.sh)
+allowed-tools: Bash(.claude/skills/start-review/scripts/discovery.sh), Bash(./scripts/discovery.sh)
 ---
 
 Invoke the **technical-review** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-review/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-../../scripts/discovery-for-implementation-and-review.sh
+./scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `plans` section:**
 - `exists` - whether any plans exist

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

@@ -0,0 +1,114 @@
+#!/bin/bash
+#
+# Discovers the current state of plans for /start-review command.
+#
+# Outputs structured YAML that the command can consume directly.
+#
+
+set -eo pipefail
+
+PLAN_DIR="docs/workflow/planning"
+SPEC_DIR="docs/workflow/specification"
+
+# Helper: Extract a frontmatter field value from a file
+# Usage: extract_field <file> <field_name>
+extract_field() {
+    local file="$1"
+    local field="$2"
+    local value=""
+
+    # Extract from YAML frontmatter (file must start with ---)
+    if head -1 "$file" 2>/dev/null | grep -q "^---$"; then
+        value=$(sed -n '2,/^---$/p' "$file" 2>/dev/null | \
+            grep -i -m1 "^${field}:" | \
+            sed -E "s/^${field}:[[:space:]]*//i" || true)
+    fi
+
+    echo "$value"
+}
+
+# Helper: Extract frontmatter content (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
+}
+
+
+# Start YAML output
+echo "# Review Command State Discovery"
+echo "# Generated: $(date -Iseconds)"
+echo ""
+
+#
+# PLANS
+#
+echo "plans:"
+
+plan_count=0
+
+if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
+    echo "  exists: true"
+    echo "  files:"
+
+    for file in "$PLAN_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        topic=$(extract_field "$file" "topic")
+        topic=${topic:-"$name"}
+        status=$(extract_field "$file" "status")
+        status=${status:-"unknown"}
+        date=$(extract_field "$file" "date")
+        date=${date:-"unknown"}
+        format=$(extract_field "$file" "format")
+        format=${format:-"MISSING"}
+        specification=$(extract_field "$file" "specification")
+        specification=${specification:-"${name}.md"}
+        plan_id=$(extract_field "$file" "plan_id")
+
+        # Check if linked specification exists
+        spec_exists="false"
+        spec_file="$SPEC_DIR/$specification"
+        if [ -f "$spec_file" ]; then
+            spec_exists="true"
+        fi
+
+        echo "    - name: \"$name\""
+        echo "      topic: \"$topic\""
+        echo "      status: \"$status\""
+        echo "      date: \"$date\""
+        echo "      format: \"$format\""
+        echo "      specification: \"$specification\""
+        echo "      specification_exists: $spec_exists"
+        if [ -n "$plan_id" ]; then
+            echo "      plan_id: \"$plan_id\""
+        fi
+
+        plan_count=$((plan_count + 1))
+    done
+
+    echo "  count: $plan_count"
+else
+    echo "  exists: false"
+    echo "  files: []"
+    echo "  count: 0"
+fi
+
+echo ""
+
+#
+# WORKFLOW STATE SUMMARY
+#
+echo "state:"
+
+echo "  has_plans: $([ "$plan_count" -gt 0 ] && echo "true" || echo "false")"
+echo "  plan_count: $plan_count"
+
+# Determine workflow state for routing
+if [ "$plan_count" -eq 0 ]; then
+    echo "  scenario: \"no_plans\""
+elif [ "$plan_count" -eq 1 ]; then
+    echo "  scenario: \"single_plan\""
+else
+    echo "  scenario: \"multiple_plans\""
+fi

package/skills/start-specification/SKILL.md

@@ -2,7 +2,7 @@
 name: start-specification
 description: "Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill."
 disable-model-invocation: true
-allowed-tools: Bash(../../scripts/discovery-for-specification.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
+allowed-tools: Bash(.claude/skills/start-specification/scripts/discovery.sh), Bash(./scripts/discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
 ---
 
 Invoke the **technical-specification** skill for this conversation.
@@ -50,15 +50,19 @@ Invoke the `/migrate` skill and assess its output.
 
 ---
 
-## Step 1: Run Discovery Script
+## Step 1: Discovery State
 
-Run the discovery script to gather current state:
+!`.claude/skills/start-specification/scripts/discovery.sh`
+
+If the above shows a script invocation rather than YAML output, the dynamic content preprocessor did not run. Execute the script before continuing:
 
 ```bash
-../../scripts/discovery-for-specification.sh
+./scripts/discovery.sh
 ```
 
-This outputs structured YAML. Parse it to understand:
+If YAML content is already displayed, it has been run on your behalf.
+
+Parse the discovery output to understand:
 
 **From `discussions` array:**
 - Each discussion's name, status, and whether it has an individual specification

package/skills/technical-research/SKILL.md

@@ -65,6 +65,57 @@ Don't constrain yourself. Research goes wherever it needs to go.
 
 **Be honest**: If something seems flawed or risky, say so. Challenge assumptions.
 
+**Explore, don't decide**: Your job is to surface options, tradeoffs, and understanding — not to pick winners. Synthesis is welcome ("the tradeoffs are X, Y, Z"), conclusions are not ("therefore we should do Y"). Decisions belong in the discussion phase.
+
+## Convergence Awareness
+
+Research threads naturally converge. As you explore a topic, options narrow, tradeoffs clarify, and opinions start forming. This is healthy — but it's also a signal.
+
+### Recognizing convergence
+
+Watch for these signs that a thread is moving from exploration toward decision-making:
+
+- "We should..." or "The best approach is..." language (from you or the user)
+- Options narrowing to a clear frontrunner with well-understood tradeoffs
+- The same conclusion being reached from multiple angles
+- Discussion shifting from "what are the options?" to "which option?"
+- You or the user starting to advocate for a particular approach
+
+### What to do
+
+When you notice convergence, **flag it and give the user options**:
+
+> "This thread seems to be converging — we've explored {topic} enough that the tradeoffs are clear and it's approaching decision territory.
+>
+> - **`p`/`park`** — Mark as discussion-ready and move to another topic
+> - **`k`/`keep`** — Keep digging, there's more to understand
+> - **`s`/`something else`** — Your call"
+
+**Never decide for the user.** Even if the answer seems obvious, flag it and ask.
+
+### If the user parks it
+
+Document the convergence point in the research file using this marker:
+
+```markdown
+> **Discussion-ready**: {Brief summary of what was explored and why it's ready for decision-making. Key tradeoffs or options identified.}
+```
+
+Then continue with whatever's next — another topic, a different angle, or wrapping up the session.
+
+### If the user keeps digging
+
+Continue exploring. The convergence signal isn't a stop sign — it's an awareness check. The user might want to stress-test the emerging conclusion, explore edge cases, or understand the problem more deeply before moving on. That's valid research work.
+
+### Synthesis vs decision
+
+This distinction matters:
+
+- **Synthesis** (research): "There are three viable approaches. A is simplest but limited. B scales better but costs more. C is future-proof but complex."
+- **Decision** (discussion): "We should go with B because scaling matters more than simplicity for this project."
+
+Synthesis is your job. Decisions are not. Present the landscape, don't pick the destination.
+
 ## Questioning
 
 For structured questioning, use the interview reference (`references/interview.md`). Good research questions: