@leeovery/claude-technical-workflows 2.1.42 → 2.2.0

package/skills/start-discussion/SKILL.md

@@ -1,8 +1,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(.claude/skills/start-discussion/scripts/discovery.sh), Bash(mkdir -p .workflows/.state), Bash(rm .workflows/.state/research-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/start-discussion/scripts/discovery.sh), Bash(mkdir -p .workflows/.state), Bash(rm .workflows/.state/research-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh), Bash(ls .workflows/discussion/)
 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**.
 
 ---
 
@@ -94,94 +97,96 @@ Parse the discovery output to understand:
 **From `state` section:**
 - `scenario` - one of: `"fresh"`, `"research_only"`, `"discussions_only"`, `"research_and_discussions"`
 
-**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 "research_only" or "research_and_discussions"
+#### If work_type and topic are both provided
 
-Research exists and may need analysis.
+→ Proceed to **Step 3** (Validate Topic).
 
-→ Proceed to **Step 3**.
+#### If work_type is provided without topic
 
-#### If scenario is "discussions_only"
+Store work_type for the handoff.
 
-No research exists, but discussions do. Skip research analysis.
+→ Proceed to **Step 4** (Route Based on Scenario).
 
-→ Proceed to **Step 4**.
+#### If neither is provided
 
-#### If scenario is "fresh"
+→ Proceed to **Step 4** (Route Based on Scenario).
 
-No research or discussions exist yet.
+---
 
-```
-Starting fresh - no prior research or discussions found.
+## Step 3: Validate Topic
 
-What topic would you like to discuss?
-```
+Load **[validate-topic.md](references/validate-topic.md)** and follow its instructions as written.
 
-**STOP.** Wait for user response.
+#### If resume
 
-When user responds, proceed with their topic.
+→ Proceed to **Step 8**.
 
-→ Proceed to **Step 6**.
+#### If no collision
+
+→ Proceed to **Step 8**.
 
 ---
 
-## Step 3: Research Analysis
+## Step 4: Route Based on Scenario
 
-Load **[research-analysis.md](references/research-analysis.md)** and follow its instructions as written.
+Load **[route-scenario.md](references/route-scenario.md)** and follow its instructions as written.
 
-→ Proceed to **Step 4**.
+#### If research exists
 
----
+→ Proceed to **Step 5**.
 
-## Step 4: Present Options
+#### If discussions only
 
-Load **[display-options.md](references/display-options.md)** and follow its instructions as written.
+→ Proceed to **Step 6**.
 
-→ Proceed to **Step 5**.
+#### If fresh
+
+→ Proceed to **Step 8**.
 
 ---
 
-## Step 5: Handle Selection
+## Step 5: Research Analysis
 
-Load **[handle-selection.md](references/handle-selection.md)** and follow its instructions as written.
+Load **[research-analysis.md](references/research-analysis.md)** and follow its instructions as written.
 
 → Proceed to **Step 6**.
 
 ---
 
-## Step 6: Gather Context
+## Step 6: Present Options
 
-Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written.
+Load **[display-options.md](references/display-options.md)** and follow its instructions as written.
 
 → Proceed to **Step 7**.
 
 ---
 
-## Step 7: Invoke the Skill
+## Step 7: Handle Selection
 
-Before invoking the processing skill, save a session bookmark.
+Load **[handle-selection.md](references/handle-selection.md)** and follow its instructions as written.
 
-> *Output the next fenced block as a code block:*
+→ Proceed to **Step 8**.
 
-```
-Saving session state so Claude can pick up where it left off if the conversation is compacted.
-```
+---
 
-```bash
-.claude/hooks/workflows/write-session-state.sh \
-  "{topic}" \
-  "skills/technical-discussion/SKILL.md" \
-  ".workflows/discussion/{topic}.md"
-```
+## Step 8: Gather Context
 
-Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.
+Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written.
 
+→ Proceed to **Step 9**.
+
+---
+
+## Step 9: Invoke the Skill
+
+Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-discussion/references/gather-context.md

@@ -4,28 +4,72 @@
 
 ---
 
-Route based on the chosen path from earlier steps.
+Route based on the `source` variable set in earlier steps.
 
-#### If starting from research
+#### If source is "bridge"
 
-→ Load **[gather-context-research.md](gather-context-research.md)** and follow its instructions.
+Bridge mode: topic and work_type were provided by the caller.
+
+Check if research exists for this topic. Read `.workflows/research/{topic}.md` and look for a `> **Discussion-ready**:` marker.
+
+**If research exists with a discussion-ready marker:**
+
+> *Output the next fenced block as a code block:*
+
+```
+Starting discussion: {topic:(titlecase)}
+Work type: {work_type}
+
+Research context:
+{discussion-ready summary extracted from research file}
+
+Anything to add or adjust before we begin, or "go" to proceed:
+```
+
+**STOP.** Wait for user response.
+
+Set source="research-bridge".
+
+→ Return to **[the skill](../SKILL.md)**.
+
+**Otherwise:**
+
+> *Output the next fenced block as a code block:*
+
+```
+Starting discussion: {topic:(titlecase)}
+Work type: {work_type}
+
+What would you like to discuss? Provide some initial context:
+- What's the problem or opportunity?
+- What prompted this?
+- Any initial thoughts or constraints?
+```
+
+**STOP.** Wait for user response.
+
+→ Return to **[the skill](../SKILL.md)**.
+
+#### If source is "research"
+
+Load **[gather-context-research.md](gather-context-research.md)** and follow its instructions.
 
 **STOP.** Wait for user response.
 
-→ Proceed to **Step 7** with the gathered context.
+→ Return to **[the skill](../SKILL.md)**.
 
-#### If starting fresh topic
+#### If source is "fresh"
 
-→ Load **[gather-context-fresh.md](gather-context-fresh.md)** and follow its instructions.
+Load **[gather-context-fresh.md](gather-context-fresh.md)** and follow its instructions.
 
 **STOP.** Wait for user response.
 
-→ Proceed to **Step 7** with the gathered context.
+→ Return to **[the skill](../SKILL.md)**.
 
-#### If continuing existing discussion
+#### If source is "continue"
 
-→ Load **[gather-context-continue.md](gather-context-continue.md)** and follow its instructions.
+Load **[gather-context-continue.md](gather-context-continue.md)** and follow its instructions.
 
 **STOP.** Wait for user response.
 
-→ Proceed to **Step 7** with the gathered context.
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-discussion/references/handle-selection.md

@@ -10,9 +10,12 @@ Route based on the user's choice from the options display.
 
 User chose to start from research (e.g., "research 1", "1", "from research", or a topic name).
 
+Set source="research".
+
 **If user specified a topic inline** (e.g., "research 2", "2", or topic name):
 - Identify the selected topic from the numbered list
-- Control returns to the backbone
+
+→ Return to **[the skill](../SKILL.md)**.
 
 **If user just said "from research" without specifying:**
 
@@ -28,9 +31,12 @@ Which research topic would you like to discuss? (Enter a number or topic name)
 
 User chose to continue a discussion (e.g., "continue auth-flow" or "continue discussion").
 
+Set source="continue".
+
 **If user specified a discussion inline** (e.g., "continue auth-flow"):
 - Identify the selected discussion from the list
-- Control returns to the backbone
+
+→ Return to **[the skill](../SKILL.md)**.
 
 **If user just said "continue discussion" without specifying:**
 
@@ -44,7 +50,11 @@ Which discussion would you like to continue?
 
 #### If user chose "Fresh topic"
 
-User wants to start a fresh discussion. Control returns to the backbone.
+User wants to start a fresh discussion.
+
+Set source="fresh".
+
+→ Return to **[the skill](../SKILL.md)**.
 
 #### If user chose "refresh"
 
@@ -59,4 +69,4 @@ Delete the cache file:
 rm .workflows/.state/research-analysis.md
 ```
 
-→ Return to **Step 3** to re-analyze.
+→ Proceed to **[Step 5](../SKILL.md)** to re-analyze.

package/skills/start-discussion/references/invoke-skill.md

@@ -4,13 +4,38 @@
 
 ---
 
+Before invoking the processing skill, save a session bookmark.
+
+> *Output the next fenced block as a code block:*
+
+```
+Saving session state so Claude can pick up where it left off if the conversation is compacted.
+```
+
+```bash
+.claude/hooks/workflows/write-session-state.sh \
+  "{topic}" \
+  "skills/technical-discussion/SKILL.md" \
+  ".workflows/discussion/{topic}.md"
+```
+
 This skill's purpose is now fulfilled.
 
 Invoke the [technical-discussion](../../technical-discussion/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.
 
-**Example handoff (from research):**
+---
+
+## Handoff
+
+Construct the handoff based on how this discussion was initiated.
+
+#### If source is "research"
+
+**If work_type is available** (from Step 2), add the Work type line:
+
 ```
 Discussion session for: {topic}
+Work type: {work_type}
 Output: .workflows/discussion/{topic}.md
 
 Research reference:
@@ -20,10 +45,53 @@ Summary: {the 1-2 sentence summary from the research analysis}
 Invoke the technical-discussion skill.
 ```
 
-**Example handoff (continuing or fresh):**
+#### If source is "research-bridge"
+
+```
+Discussion session for: {topic}
+Work type: {work_type}
+Research source: .workflows/research/{topic}.md
+Output: .workflows/discussion/{topic}.md
+
+Research reference:
+Source: .workflows/research/{topic}.md
+Summary: {the discussion-ready summary from the research file}
+
+Invoke the technical-discussion skill.
+```
+
+#### If source is "continue"
+
+Read work_type from the existing discussion frontmatter.
+
+```
+Discussion session for: {topic}
+Work type: {work_type}
+Source: existing discussion
+Output: .workflows/discussion/{topic}.md
+
+Invoke the technical-discussion skill.
+```
+
+#### If source is "fresh"
+
+**If work_type is available** (from Step 2), add the Work type line:
+
+```
+Discussion session for: {topic}
+Work type: {work_type}
+Source: fresh
+Output: .workflows/discussion/{topic}.md
+
+Invoke the technical-discussion skill.
+```
+
+#### If source is "bridge"
+
 ```
 Discussion session for: {topic}
-Source: {existing discussion | fresh}
+Work type: {work_type}
+Source: fresh
 Output: .workflows/discussion/{topic}.md
 
 Invoke the technical-discussion skill.

package/skills/start-discussion/references/research-analysis.md

@@ -70,3 +70,5 @@ research_files:
 ```
 
 **Cross-reference**: For each topic, note if a discussion already exists (from `discussions.files` in discovery).
+
+→ Return to **[the skill](../SKILL.md)**.

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

@@ -0,0 +1,39 @@
+# Route Based on Scenario
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+Use `state.scenario` from the discovery output to determine the path.
+
+#### If scenario is "research_only" or "research_and_discussions"
+
+Research exists and may need analysis.
+
+→ Return to **[the skill](../SKILL.md)** for **Step 5**.
+
+#### If scenario is "discussions_only"
+
+No research exists, but discussions do. Skip research analysis.
+
+→ Return to **[the skill](../SKILL.md)** for **Step 6**.
+
+#### If scenario is "fresh"
+
+No research or discussions exist yet.
+
+Set source="fresh".
+
+> *Output the next fenced block as a code block:*
+
+```
+Starting fresh - no prior research or discussions found.
+
+What topic would you like to discuss?
+```
+
+**STOP.** Wait for user response.
+
+When user responds, proceed with their topic.
+
+→ Return to **[the skill](../SKILL.md)** for **Step 8**.

package/skills/start-discussion/references/validate-topic.md

@@ -0,0 +1,46 @@
+# Validate Topic
+
+*Reference for **[start-discussion](../SKILL.md)***
+
+---
+
+Check if discussion already exists for this topic.
+
+```bash
+ls .workflows/discussion/
+```
+
+#### If discussion exists for this topic
+
+Read `.workflows/discussion/{topic}.md` frontmatter to check status.
+
+#### If status is "in-progress"
+
+> *Output the next fenced block as a code block:*
+
+```
+Resuming discussion: {topic:(titlecase)}
+```
+
+Set source="continue".
+
+→ Return to **[the skill](../SKILL.md)** for **Step 8**.
+
+#### If status is "concluded"
+
+> *Output the next fenced block as a code block:*
+
+```
+Discussion Concluded
+
+The discussion for "{topic:(titlecase)}" has already concluded.
+Run /start-specification to continue to spec.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If no collision
+
+Set source="bridge".
+
+→ Return to **[the skill](../SKILL.md)**.

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

@@ -83,9 +83,12 @@ if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ];
         status=$(extract_field "$file" "status")
         status=${status:-"unknown"}
         date=$(extract_field "$file" "date")
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
 
         echo "    - name: \"$name\""
         echo "      status: \"$status\""
+        echo "      work_type: \"$work_type\""
         if [ -n "$date" ]; then
             echo "      date: \"$date\""
         fi

package/skills/start-feature/SKILL.md

@@ -1,8 +1,7 @@
 ---
 name: start-feature
-description: "Start a new feature through the full pipeline. Gathers context via structured interview, creates a discussion, then bridges to continue-feature for specification, planning, and implementation."
 disable-model-invocation: true
-allowed-tools: Bash(ls .workflows/discussion/), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(ls .workflows/discussion/), Bash(ls .workflows/research/), Bash(.claude/hooks/workflows/write-session-state.sh)
 hooks:
   PreToolUse:
     - hooks:
@@ -11,7 +10,9 @@ hooks:
           once: true
 ---
 
-Start a new feature and route it through the pipeline: Discussion → Specification → Planning → Implementation.
+Start a new feature and route it through the pipeline: (Research) → Discussion → Specification → Planning → Implementation → Review.
+
+Research is optional — offered when significant uncertainties exist.
 
 > **⚠️ 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.
 
@@ -28,120 +29,63 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them.
 
 ---
 
-## 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 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 no updates needed**: Proceed to Step 1.
-
----
-
 ## 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. The full process, steps, and rules must be reloaded.
-2. **Identify the topic.** Check conversation history for the topic name. If unknown, check `.workflows/discussion/` for recently modified files via `git log --oneline -5`.
+2. **Identify the topic.** Check conversation history for the topic name. If unknown, check `.workflows/discussion/` or `.workflows/research/` for recently modified files.
 3. **Determine current step from artifacts:**
-   - No discussion file exists → resume at **Step 1**
-   - Discussion exists with `status: in-progress` → resume at **Step 3** (re-invoke technical-discussion)
-   - Discussion exists with `status: concluded` → resume at **Step 4** (phase bridge)
+   - No research or discussion file exists → resume at **Step 1**
+   - Research file exists, no discussion → resume at **Step 4** (re-invoke technical-research)
+   - Discussion exists with `status: in-progress` → resume at **Step 4** (re-invoke technical-discussion)
+   - Discussion 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 1: Gather Feature Context
-
-Load **[gather-feature-context.md](references/gather-feature-context.md)** and follow its instructions.
-
-→ Proceed to **Step 2**.
-
----
-
-## Step 2: Topic Name and Conflict Check
-
-Based on the feature description, suggest a topic name:
-
-> *Output the next fenced block as a code block:*
-
-```
-Suggested topic name: {suggested-topic:(kebabcase)}
+## Step 0: Run Migrations
 
-This will create: .workflows/discussion/{suggested-topic}.md
-```
+**This step is mandatory. You must complete it before proceeding.**
 
-> *Output the next fenced block as markdown (not a code block):*
+Invoke the `/migrate` skill and assess its output.
 
-```
-· · · · · · · · · · · ·
-Is this name okay?
+#### If files were updated
 
-- **`y`/`yes`** — Use this name
-- **`s`/`something else`** — Suggest a different name
-· · · · · · · · · · · ·
-```
+**STOP.** Wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding.
 
-**STOP.** Wait for user response.
+#### If no updates needed
 
-Once the topic name is confirmed, check for naming conflicts:
+→ Proceed to **Step 1**.
 
-```bash
-ls .workflows/discussion/
-```
+---
 
-If a discussion with the same name exists, inform the user:
+## Step 1: Gather Feature Context
 
-> *Output the next fenced block as markdown (not a code block):*
+Load **[gather-feature-context.md](references/gather-feature-context.md)** and follow its instructions.
 
-```
-· · · · · · · · · · · ·
-A discussion named "{topic}" already exists.
+→ Proceed to **Step 2**.
 
-- **`r`/`resume`** — Resume the existing discussion
-- **`n`/`new`** — Choose a different name
-· · · · · · · · · · · ·
-```
+---
 
-**STOP.** Wait for user response.
+## Step 2: Topic Name and Conflict Check
 
-If resuming, check the discussion status. If concluded → skip to Step 4. If in-progress → proceed to Step 3.
+Load **[topic-name-check.md](references/topic-name-check.md)** and follow its instructions.
 
 → Proceed to **Step 3**.
 
 ---
 
-## Step 3: Invoke Discussion
-
-Before invoking the processing skill, save a session bookmark.
+## Step 3: Research Gating
 
-> *Output the next fenced block as a code block:*
+Load **[research-gating.md](references/research-gating.md)** and follow its instructions.
 
-```
-Saving session state so Claude can pick up where it left off and continue the feature pipeline if the conversation is compacted.
-```
-
-```bash
-.claude/hooks/workflows/write-session-state.sh \
-  "{topic}" \
-  "skills/technical-discussion/SKILL.md" \
-  ".workflows/discussion/{topic}.md" \
-  --pipeline "This session is part of the feature pipeline. After the discussion concludes, load and follow the phase bridge at skills/start-feature/references/phase-bridge.md for topic '{topic}'."
-```
-
-Load **[invoke-discussion.md](references/invoke-discussion.md)** and follow its instructions.
-
-**CRITICAL**: When the discussion concludes (status becomes "concluded"), you MUST proceed to **Step 4** below. Do not end the session — the feature pipeline continues to specification via the phase bridge.
+→ Proceed to **Step 4**.
 
 ---
 
-## Step 4: Phase Bridge
-
-Load **[phase-bridge.md](references/phase-bridge.md)** and follow its instructions.
+## Step 4: Invoke Processing Skill
 
-The bridge will enter plan mode with instructions to invoke continue-feature for the topic in the next session.
+Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions.