@leeovery/claude-technical-workflows 2.1.42 → 2.2.0

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

@@ -0,0 +1,159 @@
+# Display Plans
+
+*Reference for **[start-implementation](../SKILL.md)***
+
+---
+
+Present all discovered plans. Classify each plan into one of three categories based on its state.
+
+**Classification logic:**
+
+A plan is **Implementable** if:
+- It has `status: concluded` AND all deps are satisfied (`deps_satisfied: true` or no deps) AND no tracking file or tracking `status: not-started`, OR
+- It has an implementation tracking file with `status: in-progress`
+
+A plan is **Implemented** if:
+- It has an implementation tracking file with `status: completed`
+
+A plan is **Not implementable** if:
+- It has `status: concluded` but deps are NOT satisfied (blocking deps exist)
+- It has `status: planning` or other non-concluded status
+- It has unresolved deps (`has_unresolved_deps: true`)
+
+**Present the full state:**
+
+Show implementable and implemented plans as numbered tree items.
+
+> *Output the next fenced block as a code block:*
+
+```
+Implementation Overview
+
+{N} plans found. {M} implementations in progress.
+
+1. {topic:(titlecase)}
+   └─ Plan: {plan_status:[concluded]} ({format})
+   └─ Implementation: @if(has_implementation) {impl_status:[in-progress|completed]} @else (not started) @endif
+
+2. ...
+```
+
+**Tree rules:**
+
+Implementable:
+- Implementation `status: in-progress` → `Implementation: in-progress (Phase N, Task M)`
+- Concluded plan, deps met, not started → `Implementation: (not started)`
+
+Implemented:
+- Implementation `status: completed` → `Implementation: completed`
+
+**Ordering:**
+1. Implementable first: in-progress, then new (foundational before dependent)
+2. Implemented next: completed
+3. Not implementable last (separate block below)
+
+Numbering is sequential across Implementable and Implemented. Omit any section entirely if it has no entries.
+
+**If non-implementable plans exist**, show them in a separate code block:
+
+> *Output the next fenced block as a code block:*
+
+```
+Plans not ready for implementation:
+These plans are either still in progress or have unresolved
+dependencies that must be addressed first.
+
+  • advanced-features (blocked by core-features:core-2-3)
+  • reporting (in-progress)
+```
+
+> *Output the next fenced block as a code block:*
+
+```
+If a blocked dependency has been resolved outside this workflow,
+name the plan and the dependency to unblock it.
+```
+
+**Key/Legend** — show only statuses that appear in the current display. No `---` separator before this section.
+
+> *Output the next fenced block as a code block:*
+
+```
+Key:
+
+  Implementation status:
+    in-progress — work is ongoing
+    completed   — all tasks implemented
+
+  Blocking reason:
+    blocked     — depends on another plan's task
+    in-progress — plan not yet concluded
+```
+
+---
+
+## Selection
+
+**If single implementable plan and no implemented plans (auto-select):**
+
+> *Output the next fenced block as a code block:*
+
+```
+Automatically proceeding with "{topic:(titlecase)}".
+```
+
+→ Return to **[the skill](../SKILL.md)**.
+
+**If nothing selectable (no implementable or implemented):**
+
+Show "not ready" block only (with unblock hint above).
+
+> *Output the next fenced block as a code block:*
+
+```
+Implementation Overview
+
+No implementable plans found.
+
+Complete blocking dependencies first, or finish plans still
+in progress with /start-planning. Then re-run /start-implementation.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+**If multiple selectable plans (or implemented plans exist):**
+
+The verb in the menu depends on the implementation state:
+- Implementation in-progress → **Continue**
+- Not yet started → **Start**
+- Completed → **Re-review**
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+1. Continue "Billing" — in-progress (Phase 2, Task 3)
+2. Start "Core Features" — not yet started
+3. Re-review "User Auth" — completed
+
+Select an option (enter number):
+· · · · · · · · · · · ·
+```
+
+Recreate with actual topics and states from discovery.
+
+**STOP.** Wait for user response.
+
+---
+
+## Unblock Request
+
+#### If the user requests an unblock
+
+1. Identify the plan and the specific dependency
+2. Confirm with the user which dependency to mark as satisfied
+3. Update the plan's `external_dependencies` frontmatter: set `state` to `satisfied_externally`
+4. Commit the change
+5. Re-run classification and re-present this display
+
+→ Return to **[the skill](../SKILL.md)** with selected topic.

package/skills/start-implementation/references/environment-check.md

@@ -0,0 +1,45 @@
+# Check Environment
+
+*Reference for **[start-implementation](../SKILL.md)***
+
+---
+
+> **IMPORTANT**: This step is for **information gathering only**. Do NOT execute any setup commands at this stage. The processing skill contains instructions for handling environment setup.
+
+Use the `environment` section from the discovery output:
+
+#### If setup_file_exists is true and requires_setup is false
+
+> *Output the next fenced block as a code block:*
+
+```
+Environment: No special setup required.
+```
+
+→ Return to **[the skill](../SKILL.md)**.
+
+#### If setup_file_exists is true and requires_setup is true
+
+> *Output the next fenced block as a code block:*
+
+```
+Environment setup file found: .workflows/environment-setup.md
+```
+
+→ Return to **[the skill](../SKILL.md)**.
+
+#### If setup_file_exists is false or requires_setup is unknown
+
+> *Output the next fenced block as a code block:*
+
+```
+Are there any environment setup instructions I should follow before implementation?
+(Or "none" if no special setup is needed)
+```
+
+**STOP.** Wait for user response.
+
+- If the user provides instructions, save them to `.workflows/environment-setup.md`, commit and push
+- If the user says no/none, create `.workflows/environment-setup.md` with "No special setup required." and commit
+
+→ Return to **[the skill](../SKILL.md)**.

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

@@ -0,0 +1,42 @@
+# Invoke the Skill
+
+*Reference for **[start-implementation](../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-implementation/SKILL.md" \
+  ".workflows/implementation/{topic}/tracking.md"
+```
+
+After completing the steps above, this skill's purpose is fulfilled.
+
+Invoke the [technical-implementation](../../technical-implementation/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
+
+```
+Implementation session for: {topic}
+Plan: .workflows/planning/{topic}/plan.md
+Format: {format}
+Plan ID: {plan_id} (if applicable)
+Specification: {specification} (exists: {true|false})
+Implementation tracking: {exists | new} (status: {in-progress | not-started | completed})
+
+Dependencies: {All satisfied | List any notes}
+Environment: {Setup required | No special setup required}
+
+Invoke the technical-implementation skill.
+```

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

@@ -0,0 +1,32 @@
+# Route Based on Scenario
+
+*Reference for **[start-implementation](../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:*
+
+```
+Implementation Overview
+
+No plans found in .workflows/planning/
+
+The implementation phase requires a plan.
+Run /start-planning first to create a plan from a specification.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If scenario is "single_plan" or "multiple_plans"
+
+Plans exist.
+
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-implementation/references/validate-plan.md

@@ -0,0 +1,45 @@
+# Validate Plan
+
+*Reference for **[start-implementation](../SKILL.md)***
+
+---
+
+Check if plan exists and is ready.
+
+```bash
+ls .workflows/planning/
+```
+
+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 is required for implementation.
+Run /start-planning {work_type} {topic} to create one.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If plan exists but status is not "concluded"
+
+> *Output the next fenced block as a code block:*
+
+```
+Plan Not Concluded
+
+The plan for "{topic:(titlecase)}" is not yet concluded.
+Run /start-planning {work_type} {topic} to continue.
+```
+
+**STOP.** Do not proceed — terminal condition.
+
+#### If plan exists and status is "concluded"
+
+→ Return to **[the skill](../SKILL.md)**.

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

@@ -177,6 +177,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"}
 
         # Track plan data
         plan_names+=("$name")
@@ -196,6 +198,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-investigation/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: start-investigation
+disable-model-invocation: true
+allowed-tools: Bash(.claude/skills/start-investigation/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh), Bash(ls .workflows/investigation/)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
+---
+
+Invoke the **technical-investigation** skill for this conversation.
+
+> **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.
+
+## Workflow Context
+
+This is **Phase 1** of the bugfix pipeline:
+
+| Phase              | Focus                                              | You    |
+|--------------------|----------------------------------------------------|--------|
+| **Investigation**  | Symptom gathering + code analysis → root cause     | ◀ HERE |
+| 2. Specification   | REFINE - validate into fix specification           |        |
+| 3. Planning        | HOW - phases, tasks, acceptance criteria           |        |
+| 4. Implementation  | DOING - tests first, then code                     |        |
+| 5. Review          | VALIDATING - check work against artifacts          |        |
+
+**Stay in your lane**: Investigate the bug — gather symptoms, trace code, find root cause. Don't jump to fixing or implementing. This is the time for deep analysis.
+
+---
+
+## 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
+- Complete each step fully before moving to the next
+
+---
+
+## 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: Discovery State
+
+!`.claude/skills/start-investigation/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
+.claude/skills/start-investigation/scripts/discovery.sh
+```
+
+Parse the discovery output to understand:
+
+**From `investigations` section:**
+- `exists` - whether investigation files exist
+- `files` - each investigation's topic, status, and date
+- `counts.in_progress` and `counts.concluded` - totals for routing
+
+**From `state` section:**
+- `scenario` - one of: `"fresh"`, `"has_investigations"`
+
+**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: Determine Mode
+
+Check for arguments: work_type = `$0`, topic = `$1`
+
+Investigation is always bugfix work_type. If work_type is provided, it should be `bugfix`.
+
+#### If work_type and topic are both provided
+
+→ Proceed to **Step 3** (Validate Investigation).
+
+#### If work_type is provided without topic
+
+→ Proceed to **Step 4** (Route Based on Scenario).
+
+#### If neither is provided
+
+→ Proceed to **Step 4** (Route Based on Scenario).
+
+---
+
+## Step 3: Validate Investigation
+
+Load **[validate-investigation.md](references/validate-investigation.md)** and follow its instructions as written.
+
+#### If resume
+
+→ Proceed to **Step 6**.
+
+#### If no collision
+
+→ Proceed to **Step 5**.
+
+---
+
+## Step 4: Route Based on Scenario
+
+Load **[route-scenario.md](references/route-scenario.md)** and follow its instructions as written.
+
+#### If resuming
+
+→ Proceed to **Step 6**.
+
+#### If new or fresh
+
+→ Proceed to **Step 5**.
+
+---
+
+## Step 5: Gather Bug Context
+
+Load **[gather-context.md](references/gather-context.md)** and follow its instructions as written.
+
+→ Proceed to **Step 6**.
+
+---
+
+## Step 6: Invoke the Skill
+
+Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-investigation/references/gather-context-fresh.md

@@ -0,0 +1,72 @@
+# Gather Bug Context (Fresh)
+
+*Reference for **[start-investigation](../SKILL.md)***
+
+---
+
+> *Output the next fenced block as a code block:*
+
+```
+Starting new investigation.
+
+What bug are you investigating? Please provide:
+- A short identifier/name for tracking (e.g., "login-timeout-bug")
+- What's broken (expected vs actual behavior)
+- Any initial context (error messages, how it manifests)
+```
+
+**STOP.** Wait for user response.
+
+---
+
+If the user didn't provide a clear topic name, suggest one based on the bug description:
+
+> *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 in the discovery output.
+
+If an investigation with the same name exists, inform the user:
+
+> *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
+
+Set source="continue".
+
+Check the investigation status. If concluded → suggest `/start-specification bugfix {topic}`. If in-progress:
+
+→ Return to **[the skill](../SKILL.md)** for **Step 6**.
+
+#### If no conflict
+
+→ Return to **[the skill](../SKILL.md)**.

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

@@ -0,0 +1,31 @@
+# Gather Bug Context
+
+*Reference for **[start-investigation](../SKILL.md)***
+
+---
+
+Route based on the `source` variable set in earlier steps.
+
+#### If source is "bridge"
+
+Bridge mode: topic and work_type were provided by the caller.
+
+> *Output the next fenced block as a code block:*
+
+```
+Starting investigation: {topic:(titlecase)}
+
+What bug are you investigating? Please provide:
+- What's broken (expected vs actual behavior)
+- Any initial context (error messages, how it manifests)
+```
+
+**STOP.** Wait for user response.
+
+→ Return to **[the skill](../SKILL.md)**.
+
+#### If source is "fresh"
+
+Load **[gather-context-fresh.md](gather-context-fresh.md)** and follow its instructions.
+
+→ Return to **[the skill](../SKILL.md)**.

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

@@ -0,0 +1,54 @@
+# Invoke the Skill
+
+*Reference for **[start-investigation](../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-investigation/SKILL.md" \
+  ".workflows/investigation/{topic}/investigation.md"
+```
+
+This skill's purpose is now fulfilled.
+
+Invoke the [technical-investigation](../../technical-investigation/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 how this investigation was initiated.
+
+#### If source is "fresh" or "bridge"
+
+```
+Investigation session for: {topic}
+Output: .workflows/investigation/{topic}/investigation.md
+
+Bug context:
+- Expected behavior: {from user's description}
+- Actual behavior: {from user's description}
+- Initial context: {error messages, reproduction steps, etc.}
+
+Invoke the technical-investigation skill.
+```
+
+#### If source is "continue"
+
+```
+Investigation session for: {topic}
+Source: existing investigation
+Output: .workflows/investigation/{topic}/investigation.md
+
+Invoke the technical-investigation skill.
+```