@leeovery/claude-technical-workflows 2.1.42 → 2.2.0

package/skills/start-specification/references/invoke-skill-bridge.md

@@ -0,0 +1,74 @@
+# Invoke the Skill (Bridge Mode)
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+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-specification/SKILL.md" \
+  ".workflows/specification/{topic}/specification.md"
+```
+
+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.
+
+---
+
+## Handoff
+
+Construct the handoff based on the work type and verb.
+
+#### If work_type is feature
+
+```
+Specification session for: {topic}
+Work type: {work_type}
+
+Source material:
+- Discussion: .workflows/discussion/{topic}.md
+
+Topic name: {topic}
+Action: {verb} specification
+
+The specification frontmatter should include:
+- topic: {topic}
+- status: in-progress
+- type: feature
+- work_type: {work_type}
+- date: {today}
+
+Invoke the technical-specification skill.
+```
+
+#### If work_type is bugfix
+
+```
+Specification session for: {topic}
+Work type: {work_type}
+
+Source material:
+- Investigation: .workflows/investigation/{topic}/investigation.md
+
+Topic name: {topic}
+Action: {verb} specification
+
+The specification frontmatter should include:
+- topic: {topic}
+- status: in-progress
+- type: feature
+- work_type: {work_type}
+- date: {today}
+
+Invoke the technical-specification skill.
+```

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

@@ -0,0 +1,23 @@
+# Route Based on State
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Based on discovery state, load exactly ONE reference file:
+
+#### If concluded_count == 1
+
+→ Load **[display-single.md](display-single.md)** and follow its instructions.
+
+#### If cache status is "valid"
+
+→ Load **[display-groupings.md](display-groupings.md)** and follow its instructions.
+
+#### If spec_count == 0 and cache is "none" or "stale"
+
+→ Load **[display-analyze.md](display-analyze.md)** and follow its instructions.
+
+#### Otherwise
+
+→ Load **[display-specs-menu.md](display-specs-menu.md)** and follow its instructions.

package/skills/start-specification/references/validate-source.md

@@ -0,0 +1,91 @@
+# Validate Source Material
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Check if source material exists and is ready.
+
+#### If work_type is feature
+
+Check if discussion exists and is concluded:
+
+```bash
+ls .workflows/discussion/
+```
+
+Read `.workflows/discussion/{topic}.md` frontmatter.
+
+**If discussion doesn't exist:**
+
+> *Output the next fenced block as a code block:*
+
+```
+Source Material Missing
+
+No discussion found for "{topic:(titlecase)}".
+
+A concluded discussion is required before specification.
+Run /start-discussion feature {topic} to start one.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+**If discussion exists but status is "in-progress":**
+
+> *Output the next fenced block as a code block:*
+
+```
+Discussion In Progress
+
+The discussion for "{topic:(titlecase)}" is not yet concluded.
+Run /start-discussion feature {topic} to continue.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+**If discussion exists and status is "concluded":**
+
+→ Return to **[the skill](../SKILL.md)**.
+
+#### If work_type is bugfix
+
+Check if investigation exists and is concluded:
+
+```bash
+ls .workflows/investigation/
+```
+
+Read `.workflows/investigation/{topic}/investigation.md` frontmatter.
+
+**If investigation doesn't exist:**
+
+> *Output the next fenced block as a code block:*
+
+```
+Source Material Missing
+
+No investigation found for "{topic:(titlecase)}".
+
+A concluded investigation is required before specification.
+Run /start-investigation bugfix {topic} to start one.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+**If investigation exists but status is "in-progress":**
+
+> *Output the next fenced block as a code block:*
+
+```
+Investigation In Progress
+
+The investigation for "{topic:(titlecase)}" is not yet concluded.
+Run /start-investigation bugfix {topic} to continue.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+**If investigation exists and status is "concluded":**
+
+→ Return to **[the skill](../SKILL.md)**.

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

@@ -133,6 +133,8 @@ if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ];
         name=$(basename "$file" .md)
         status=$(extract_field "$file" "status")
         status=${status:-"unknown"}
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
 
         # Check if this discussion has a corresponding individual spec
         has_individual_spec="false"
@@ -146,6 +148,7 @@ if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ];
 
         echo "  - name: \"$name\""
         echo "    status: \"$status\""
+        echo "    work_type: \"$work_type\""
         echo "    has_individual_spec: $has_individual_spec"
         if [ "$has_individual_spec" = "true" ]; then
             echo "    spec_status: \"$spec_status\""
@@ -169,11 +172,14 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
         name=$(basename "$(dirname "$file")")
         status=$(extract_field "$file" "status")
         status=${status:-"active"}
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
 
         superseded_by=$(extract_field "$file" "superseded_by")
 
         echo "  - name: \"$name\""
         echo "    status: \"$status\""
+        echo "    work_type: \"$work_type\""
 
         if [ -n "$superseded_by" ]; then
             echo "    superseded_by: \"$superseded_by\""

package/skills/status/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: status
-description: "Show workflow status - what exists, where you are, and what to do next."
 disable-model-invocation: true
 allowed-tools: Bash(.claude/skills/status/scripts/discovery.sh)
 hooks:
@@ -19,9 +18,13 @@ Show the current state of the workflow for this project.
 
 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**.
 
 ---
 

package/skills/status/scripts/discovery.sh

@@ -216,9 +216,12 @@ if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ];
         name=$(basename "$file" .md)
         status=$(extract_field "$file" "status")
         status=${status:-"unknown"}
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
 
         echo "    - name: \"$name\""
         echo "      status: \"$status\""
+        echo "      work_type: \"$work_type\""
 
         disc_count=$((disc_count + 1))
         [ "$status" = "concluded" ] && disc_concluded=$((disc_concluded + 1))
@@ -258,11 +261,14 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
         status=${status:-"in-progress"}
         spec_type=$(extract_field "$file" "type")
         spec_type=${spec_type:-"feature"}
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
         superseded_by=$(extract_field "$file" "superseded_by")
 
         echo "    - name: \"$name\""
         echo "      status: \"$status\""
         echo "      type: \"$spec_type\""
+        echo "      work_type: \"$work_type\""
         [ -n "$superseded_by" ] && echo "      superseded_by: \"$superseded_by\""
 
         # Sources
@@ -323,12 +329,15 @@ if [ -d "$PLAN_DIR" ] && [ -n "$(ls -A "$PLAN_DIR" 2>/dev/null)" ]; then
         status=${status:-"unknown"}
         format=$(extract_field "$file" "format")
         format=${format:-"unknown"}
+        work_type=$(extract_field "$file" "work_type")
+        work_type=${work_type:-"greenfield"}
         specification=$(extract_field "$file" "specification")
         specification=${specification:-"${name}/specification.md"}
 
         echo "    - name: \"$name\""
         echo "      status: \"$status\""
         echo "      format: \"$format\""
+        echo "      work_type: \"$work_type\""
         echo "      specification: \"$specification\""
 
         # External dependencies

package/skills/technical-discussion/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: technical-discussion
-description: "Document technical discussions as expert architect and meeting assistant. Capture context, decisions, edge cases, debates, and rationale without jumping to specification or implementation. Use when: (1) Users discuss/explore/debate architecture or design, (2) Working through edge cases before specification, (3) Need to document technical decisions and their rationale, (4) Capturing competing solutions and why choices were made. Creates documentation in .workflows/discussion/{topic}.md that can be used to build validated specifications."
 user-invocable: false
 ---
 
@@ -135,9 +134,21 @@ Incorporate the user's context into the discussion, commit, then re-present the
 
 1. Update frontmatter `status: concluded`
 2. Final commit
-3. Check for remaining in-progress discussions in `.workflows/discussion/`
+3. Check the artifact frontmatter for `work_type`
 
-**If other in-progress discussions exist:**
+**If work_type is set** (feature, bugfix, or greenfield):
+
+This discussion is part of a pipeline. Invoke the `/workflow:bridge` skill:
+
+```
+Pipeline bridge for: {topic}
+Work type: {work_type from artifact frontmatter}
+Completed phase: discussion
+
+Invoke the workflow:bridge skill to enter plan mode with continuation instructions.
+```
+
+**If work_type is not set and other in-progress discussions exist:**
 
 > *Output the next fenced block as a code block:*
 
@@ -151,7 +162,7 @@ Remaining in-progress discussions:
 To continue, clear your context and run /start-discussion to pick up the next topic.
 ```
 
-**If no in-progress discussions remain:**
+**If work_type is not set and no in-progress discussions remain:**
 
 > *Output the next fenced block as a code block:*
 

package/skills/technical-discussion/references/template.md

@@ -17,6 +17,7 @@ This is a single file per topic.
 topic: {topic-name}
 status: in-progress
 date: YYYY-MM-DD  # Use today's actual date
+research_source: {filename}.md  # Optional — only when handoff includes research source
 ---
 
 # Discussion: {Topic}
@@ -95,12 +96,19 @@ What we chose, why, the deciding factor, trade-offs accepted, confidence level.
 - [ ] Validate Y
 ```
 
+## Field Notes
+
+- `topic`: The discussion topic. Should match the filename (e.g., `auth-flow` for `auth-flow.md`).
+- `status`: Lifecycle state — `in-progress` or `concluded`.
+- `date`: Today's date when creating the document.
+- `research_source`: (optional) The research file this discussion originated from. Include only when the handoff provides a research source. Feature pipeline only — greenfield discussions may draw from multiple research files.
+
 ## Usage Notes
 
 **When creating**:
 1. Ensure discussion directory exists: `.workflows/discussion/`
 2. Create file: `{topic}.md`
-3. Fill frontmatter: topic, status, date
+3. Fill frontmatter: topic, status, date, and research_source if provided in handoff
 4. Start with context: why discussing?
 5. List questions: what needs deciding?
 

package/skills/technical-implementation/SKILL.md

@@ -1,6 +1,5 @@
 ---
 name: technical-implementation
-description: "Orchestrate implementation of plans using agent-based TDD workflow with per-task review and approval gate (auto mode available). Use when: (1) Implementing a plan from .workflows/planning/{topic}/plan.md, (2) User says 'implement', 'build', or 'code this' with a plan available, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Dispatches executor and reviewer agents per task, commits after review approval."
 user-invocable: false
 ---
 
@@ -333,4 +332,28 @@ Update the tracking file (`.workflows/implementation/{topic}/tracking.md`):
 
 Commit: `impl({topic}): complete implementation`
 
+**Check for pipeline continuation** — Read the plan file (`.workflows/planning/{topic}/plan.md`) and check for `work_type`
+
+**If work_type is set** (feature, bugfix, or greenfield):
+
+This implementation is part of a pipeline. Invoke the `/workflow:bridge` skill:
+
+```
+Pipeline bridge for: {topic}
+Work type: {work_type from plan frontmatter}
+Completed phase: implementation
+
+Invoke the workflow:bridge skill to enter plan mode with continuation instructions.
+```
+
+**If work_type is not set:**
+
+> *Output the next fenced block as a code block:*
+
+```
+Implementation completed: {topic}
+
+The implementation is ready for review. Run /start-review to begin.
+```
+
 

package/skills/technical-implementation/references/analysis-loop.md

@@ -22,7 +22,7 @@ F. Create tasks in plan → invoke-task-writer.md
 
 Increment `analysis_cycle` in the implementation tracking file.
 
-→ If `analysis_cycle <= 3`, proceed directly to **B. Git Checkpoint**.
+→ If `analysis_cycle <= 3`, proceed to **B. Git Checkpoint**.
 
 If `analysis_cycle > 3`:
 
@@ -43,8 +43,8 @@ Analysis has run {N-1} times so far. You can continue (recommended if issues wer
 
 **STOP.** Wait for user choice. You MUST NOT choose on the user's behalf.
 
-- **`proceed`**: → Continue to **B. Git Checkpoint**.
-- **`skip`**: → Return to the skill for **Step 8**.
+- **`proceed`**: → Proceed to **B. Git Checkpoint**.
+- **`skip`**: → Return to **[the skill](../SKILL.md)** for **Step 8**.
 
 ---
 
@@ -243,4 +243,4 @@ Commit all analysis and plan changes (staging file, plan tasks, Plan Index File,
 impl({topic}): add analysis phase {N} ({K} tasks)
 ```
 
-→ Return to the skill. New tasks are now in the plan.
+→ Return to **[the skill](../SKILL.md)**. New tasks are now in the plan.

package/skills/technical-implementation/references/task-loop.md

@@ -70,7 +70,7 @@ Task {id}: {Task Name} — {blocked/failed}
 
 #### If `stop`
 
-→ Return to the skill for **Step 7**.
+→ Return to **[the skill](../SKILL.md)** for **Step 7**.
 
 ---
 
@@ -211,4 +211,4 @@ This is the end of this iteration.
 All tasks complete. {M} tasks implemented.
 ```
 
-→ Return to the skill for **Step 7**.
+→ Return to **[the skill](../SKILL.md)** for **Step 7**.

package/skills/technical-investigation/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: technical-investigation
+user-invocable: false
+---
+
+# Technical Investigation
+
+Act as **expert debugger** tracing through code AND **documentation assistant** capturing findings. These are equally important — the investigation drives understanding, the documentation preserves it. Dig deep: trace code paths, challenge assumptions, explore related areas. Then capture what you found.
+
+## Purpose in the Workflow
+
+This skill is the first phase of the **bugfix pipeline**:
+Investigation → Specification → Planning → Implementation → Review
+
+Investigation combines:
+- **Symptom gathering**: What's broken, how it manifests, reproduction steps
+- **Code analysis**: Tracing paths, finding root cause, understanding blast radius
+
+The output becomes source material for a specification focused on the fix approach.
+
+### What This Skill Needs
+
+- **Topic** (required) - Bug identifier or short description
+- **Bug context** (optional) - Initial symptoms, error messages, reproduction steps
+- **Work type** - Always "bugfix" for investigation
+
+**Before proceeding**, confirm the required input is clear. If anything is missing or unclear, **STOP** and resolve with the user.
+
+#### If no topic provided
+
+> *Output the next fenced block as a code block:*
+
+```
+What bug would you like to investigate? Provide:
+- A short identifier or name for tracking
+- What's broken (expected vs actual behavior)
+- Any error messages or symptoms observed
+```
+
+**STOP.** Wait for user response.
+
+---
+
+## 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. **Read the investigation file** at `.workflows/investigation/{topic}/investigation.md` — this is your source of truth for what's been discovered.
+3. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
+4. **Announce your position** to the user before continuing: what you've found so far, what's still to investigate, 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.
+
+---
+
+## Investigation Process
+
+### Phase 1: Symptom Gathering
+
+Start by understanding the bug from the user's perspective:
+
+1. **Problem description**: What's the expected vs actual behavior?
+2. **Manifestation**: How is it surfacing? (errors, UI issues, data corruption)
+3. **Reproduction steps**: Can it be reproduced? What triggers it?
+4. **Environment**: Where does it occur? (production, staging, specific browsers)
+5. **Links**: Error tracking (Sentry), logs, support tickets
+6. **Impact**: How severe? How many users affected?
+7. **Initial hypotheses**: What does the user suspect?
+
+Document symptoms in the investigation file as you gather them.
+
+### Phase 2: Code Analysis
+
+With symptoms understood, trace through the code:
+
+1. **Reproduce the issue**: If possible, confirm the bug exists
+2. **Identify entry points**: Where does the problematic flow start?
+3. **Trace code paths**: Follow the execution through the codebase
+4. **Isolate root cause**: What specific code/condition causes the bug?
+5. **Assess blast radius**: What else might be affected by a fix?
+6. **Identify related code**: Are there similar patterns elsewhere?
+
+Document findings in the investigation file as you analyze.
+
+### Phase 3: Root Cause Analysis
+
+Synthesize findings into a clear root cause:
+
+1. **Root cause statement**: Clear, precise description of the bug's cause
+2. **Contributing factors**: What conditions enable the bug?
+3. **Why it wasn't caught**: Testing gaps, edge cases, etc.
+4. **Fix direction**: High-level approach (detailed in specification)
+
+---
+
+## What to Capture
+
+- **Symptom details**: Error messages, screenshots, logs
+- **Reproduction steps**: Precise steps to trigger the bug
+- **Code traces**: Which files/functions are involved
+- **Root cause**: The specific issue and why it occurs
+- **Blast radius**: What else might be affected
+- **Initial fix ideas**: Rough approaches to consider in specification
+
+**On length**: Investigations can vary widely. Capture what's needed to fully understand the bug. Don't summarize prematurely — document the trail.
+
+## Structure
+
+**Output**: `.workflows/investigation/{topic}/investigation.md`
+
+Use **[template.md](references/template.md)** for structure:
+
+```markdown
+---
+topic: {topic}
+status: in-progress
+work_type: bugfix
+date: {YYYY-MM-DD}
+---
+
+# Investigation: {Topic}
+
+## Symptoms
+
+### Problem Description
+{Expected vs actual behavior}
+
+### Manifestation
+{How the bug surfaces - errors, UI issues, etc.}
+
+### Reproduction Steps
+1. {Step}
+2. {Step}
+...
+
+### Environment
+{Where it occurs, conditions}
+
+### Impact
+{Severity, affected users}
+
+## Analysis
+
+### Code Trace
+{Entry points, code paths followed}
+
+### Root Cause
+{Clear statement of what causes the bug}
+
+### Contributing Factors
+{Conditions that enable the bug}
+
+### Blast Radius
+{What else might be affected}
+
+## Fix Direction
+
+### Proposed Approach
+{High-level fix direction for specification}
+
+### Alternatives Considered
+{Other approaches, why not chosen}
+
+### Testing Gaps
+{What testing should be added}
+```
+
+## Write to Disk and Commit Frequently
+
+The investigation file is your memory. Context compaction is lossy — what's not on disk is lost.
+
+**Write to the file at natural moments:**
+
+- Symptoms are gathered
+- A code path is traced
+- Root cause is identified
+- Each significant finding
+
+**After writing, git commit.** Commits let you track and recover after compaction. Don't batch — commit each time you write.
+
+**Create the file early.** After understanding the initial symptoms, create the investigation file with frontmatter and symptoms section.
+
+## Concluding an Investigation
+
+When the root cause is identified and documented:
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+Root cause identified. Ready to conclude?
+
+- **`y`/`yes`** — Conclude investigation and proceed to specification
+- **`m`/`more`** — Continue investigating (more analysis needed)
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If more
+
+Continue investigation. Ask what aspects need more analysis.
+
+#### If yes
+
+1. Update frontmatter `status: concluded`
+2. Final commit
+3. Display conclusion:
+
+> *Output the next fenced block as a code block:*
+
+```
+Investigation concluded: {topic}
+
+Root cause: {brief summary}
+Fix direction: {proposed approach}
+
+The investigation is ready for specification. The specification will
+detail the exact fix approach, acceptance criteria, and testing plan.
+```
+
+4. Check the investigation frontmatter for `work_type`
+
+**If work_type is set** (bugfix):
+
+This investigation is part of a pipeline. Invoke the `/workflow:bridge` skill:
+
+```
+Pipeline bridge for: {topic}
+Work type: bugfix
+Completed phase: investigation
+
+Invoke the workflow:bridge skill to enter plan mode with continuation instructions.
+```
+
+**If work_type is not set:**
+
+The session ends here. The investigation document can be used as input to `/start-specification`.