@leeovery/claude-technical-workflows 2.1.41 → 2.2.0

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

@@ -12,13 +12,17 @@ Invoke the [technical-discussion](../../technical-discussion/SKILL.md) skill:
 
 ```
 Technical discussion for: {topic}
+Work type: feature
 
 {compiled feature context from gather-feature-context}
 
-PIPELINE CONTINUATION — When this discussion concludes (status: concluded),
-you MUST return to the start-feature skill and execute Step 4 (Phase Bridge).
-Load: skills/start-feature/references/phase-bridge.md
-Do not end the session after the discussion — the feature pipeline continues.
+The discussion frontmatter should include:
+- topic: {topic}
+- status: in-progress
+- work_type: feature
+- date: {today}
 
 Invoke the technical-discussion skill.
 ```
+
+When the discussion concludes, the processing skill will detect `work_type: feature` in the artifact and invoke workflow:bridge automatically.

package/skills/start-feature/references/invoke-research.md

@@ -0,0 +1,29 @@
+# Invoke Research
+
+*Reference for **[start-feature](../SKILL.md)***
+
+---
+
+Invoke the [technical-research](../../technical-research/SKILL.md) skill for feature research.
+
+```
+Research session for: {topic}
+Work type: feature
+
+Initial context from feature interview:
+{compiled feature context from gather-feature-context}
+
+Uncertainties to explore:
+{list of uncertainties identified in research-gating}
+
+Create research file: .workflows/research/{topic}.md
+
+The research frontmatter should include:
+- topic: {topic}
+- work_type: feature
+- date: {today}
+
+Invoke the technical-research skill.
+```
+
+When a research topic is parked as discussion-ready, the processing skill will offer pipeline continuation via workflow:bridge.

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

@@ -0,0 +1,35 @@
+# Invoke Processing Skill
+
+*Reference for **[start-feature](../SKILL.md)***
+
+---
+
+Save a session bookmark for compaction recovery, then invoke the appropriate processing skill.
+
+> *Output the next fenced block as a code block:*
+
+```
+Saving session state for compaction recovery.
+```
+
+#### If phase is research
+
+```bash
+.claude/hooks/workflows/write-session-state.sh \
+  "{topic}" \
+  "skills/technical-research/SKILL.md" \
+  ".workflows/research/{topic}.md"
+```
+
+→ Load **[invoke-research.md](invoke-research.md)** and follow its instructions.
+
+#### If phase is discussion
+
+```bash
+.claude/hooks/workflows/write-session-state.sh \
+  "{topic}" \
+  "skills/technical-discussion/SKILL.md" \
+  ".workflows/discussion/{topic}.md"
+```
+
+→ Load **[invoke-discussion.md](invoke-discussion.md)** and follow its instructions.

package/skills/start-feature/references/research-gating.md

@@ -0,0 +1,65 @@
+# Research Gating
+
+*Reference for **[start-feature](../SKILL.md)***
+
+---
+
+Assess whether the feature has open questions that warrant research before discussion.
+
+## Assess Uncertainties
+
+Based on the gathered context, evaluate if there are significant unknowns:
+
+- **Technical unknowns**: Unfamiliar APIs, libraries, or patterns
+- **Design unknowns**: Multiple viable approaches, unclear tradeoffs
+- **Integration unknowns**: How existing systems will interact
+- **Scope unknowns**: Requirements that need exploration
+
+## Present Assessment
+
+#### If significant uncertainties exist
+
+> *Output the next fenced block as a code block:*
+
+```
+Research Assessment
+
+Based on your description, there are open questions that might benefit from research:
+
+• {uncertainty_1}
+• {uncertainty_2}
+• ...
+
+Research helps explore options and tradeoffs before committing to decisions in discussion.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+Would you like to explore these in research first?
+
+- **`y`/`yes`** — Start with research, then continue to discussion
+- **`n`/`no`** — Proceed directly to discussion
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If no significant uncertainties
+
+Skip this step silently and proceed to discussion. Do not ask about research if the feature scope is clear.
+
+## Route Based on Response
+
+#### If user chooses research
+
+Set phase="research".
+
+→ Return to **[the skill](../SKILL.md)**.
+
+#### If user declines research (or no uncertainties)
+
+Set phase="discussion".
+
+→ Return to **[the skill](../SKILL.md)**.

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

@@ -0,0 +1,61 @@
+# Topic Name and Conflict Check
+
+*Reference for **[start-feature](../SKILL.md)***
+
+---
+
+Based on the feature description, suggest a topic name:
+
+> *Output the next fenced block as a code block:*
+
+```
+Suggested topic name: {suggested-topic:(kebabcase)}
+
+This will create: .workflows/discussion/{suggested-topic}.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/discussion/
+```
+
+#### If a discussion with the same name exists
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+A discussion named "{topic}" already exists.
+
+- **`r`/`resume`** — Resume the existing discussion
+- **`n`/`new`** — Choose a different name
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+#### If resuming
+
+Check the discussion status. If in-progress:
+
+Set phase="discussion".
+
+→ Return to **[the skill](../SKILL.md)** for **Step 4**.
+
+#### If no conflict
+
+→ Return to **[the skill](../SKILL.md)**.

package/skills/start-implementation/SKILL.md

@@ -1,8 +1,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(.claude/skills/start-implementation/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh)
+allowed-tools: Bash(.claude/skills/start-implementation/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh), Bash(ls .workflows/planning/)
 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**.
 
 ---
 
@@ -100,329 +103,72 @@ Parse the discovery output to understand:
 - `plans_in_progress_count` - implementations in progress
 - `plans_completed_count` - implementations completed
 
-**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
-
-Use `state.scenario` from the discovery output to determine the path:
-
-#### If scenario is "no_plans"
+## Step 2: Determine Mode
 
-No plans exist yet.
+Check for arguments: work_type = `$0`, topic = `$1`
 
-> *Output the next fenced block as a code block:*
+#### If work_type and topic are both provided
 
-```
-Implementation Overview
-
-No plans found in .workflows/planning/
+→ Proceed to **Step 3**.
 
-The implementation phase requires a plan.
-Run /start-planning first to create a plan from a specification.
-```
+#### If work_type is provided without topic
 
-**STOP.** Do not proceed — terminal condition.
+Store work_type for the handoff.
 
-#### If scenario is "single_plan" or "multiple_plans"
+→ Proceed to **Step 4**.
 
-Plans exist.
+#### If neither is provided
 
-→ Proceed to **Step 3** to present options.
+→ Proceed to **Step 4**.
 
 ---
 
-## Step 3: Present Plans and Select
-
-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
-```
-
-**Then prompt based on what's actionable:**
-
-**If single implementable plan and no implemented plans (auto-select):**
-
-> *Output the next fenced block as a code block:*
-
-```
-Automatically proceeding with "{topic:(titlecase)}".
-```
-
-→ Proceed directly to **Step 4**.
-
-**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.
-
-**Otherwise (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):*
+## Step 3: Validate Plan
 
-```
-· · · · · · · · · · · ·
-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.
+Load **[validate-plan.md](references/validate-plan.md)** and follow its instructions as written.
 
-**STOP.** Wait for user response.
-
-#### 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 Step 3
-
-→ Based on user choice, proceed to **Step 4**.
+→ Proceed to **Step 6**.
 
 ---
 
-## Step 4: Check External Dependencies
-
-**This step is a confirmation gate.** Dependencies have been pre-analyzed by the discovery script.
-
-After the plan is selected:
-
-1. **Check the plan's `external_deps` and `dependency_resolution`** from the discovery output
-
-#### If all deps satisfied (or no deps)
-
-> *Output the next fenced block as a code block:*
-
-```
-External dependencies satisfied.
-```
-
-→ Proceed to **Step 5**.
-
-#### If any deps are blocking
-
-This should not normally happen for plans classified as "Implementable" in Step 3. However, as an escape hatch:
-
-> *Output the next fenced block as a code block:*
-
-```
-Missing Dependencies
-
-Unresolved (not yet planned):
-  • {topic}: {description}
-    No plan exists. Create with /start-planning or mark as
-    satisfied externally.
-
-Incomplete (planned but not implemented):
-  • {topic}: {plan}:{task-id} not yet completed
-    This task must be completed first.
-```
-
-> *Output the next fenced block as markdown (not a code block):*
-
-```
-· · · · · · · · · · · ·
-- **`i`/`implement`** — Implement the blocking dependencies first
-- **`l`/`link`** — Run /link-dependencies to wire up recently completed plans
-- **`s`/`satisfied`** — Mark a dependency as satisfied externally
-· · · · · · · · · · · ·
-```
-
-**STOP.** Wait for user response.
+## Step 4: Route Based on Scenario
 
-#### Escape Hatch
-
-If the user says a dependency has been implemented outside the workflow:
-
-1. Ask which dependency to mark as satisfied
-2. Update the plan frontmatter: Change the dependency's `state` to `satisfied_externally`
-3. Commit the change
-4. Re-check dependencies
+Load **[route-scenario.md](references/route-scenario.md)** and follow its instructions.
 
 → Proceed to **Step 5**.
 
 ---
 
-## Step 5: Check Environment Setup
-
-> **IMPORTANT**: This step is for **information gathering only**. Do NOT execute any setup commands at this stage. The skill contains instructions for handling environment setup.
-
-Use the `environment` section from the discovery output:
-
-**If `setup_file_exists: true` and `requires_setup: false`:**
-
-> *Output the next fenced block as a code block:*
-
-```
-Environment: No special setup required.
-```
-→ Proceed to **Step 6**.
-
-**If `setup_file_exists: true` and `requires_setup: true`:**
-
-> *Output the next fenced block as a code block:*
-
-```
-Environment setup file found: .workflows/environment-setup.md
-```
-→ Proceed to **Step 6**.
+## Step 5: Present Plans and Select
 
-**If `setup_file_exists: false` or `requires_setup: unknown`:**
+Load **[display-plans.md](references/display-plans.md)** and follow its instructions as written.
 
-> *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
-
-→ Proceed to **Step 6**.
+→ Proceed to **Step 6** with selected topic.
 
 ---
 
-## Step 6: Invoke the Skill
+## Step 6: Check Dependencies
 
-Before invoking the processing skill, save a session bookmark.
+Load **[check-dependencies.md](references/check-dependencies.md)** and follow its instructions as written.
 
-> *Output the next fenced block as a code block:*
+→ Proceed to **Step 7**.
 
-```
-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"
-```
+## Step 7: Check Environment
 
-After completing the steps above, this skill's purpose is fulfilled.
+Load **[environment-check.md](references/environment-check.md)** and follow its instructions as written.
 
-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.
+→ Proceed to **Step 8**.
 
-**Example 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}
+## Step 8: Invoke the Skill
 
-Invoke the technical-implementation skill.
-```
+Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

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

@@ -0,0 +1,65 @@
+# Check Dependencies
+
+*Reference for **[start-implementation](../SKILL.md)***
+
+---
+
+**This step is a confirmation gate.** Dependencies have been pre-analyzed by the discovery script.
+
+After the plan is selected:
+
+1. **Check the plan's `external_deps` and `dependency_resolution`** from the discovery output
+
+#### If all deps satisfied (or no deps)
+
+> *Output the next fenced block as a code block:*
+
+```
+External dependencies satisfied.
+```
+
+→ Return to **[the skill](../SKILL.md)**.
+
+#### If any deps are blocking
+
+This should not normally happen for plans classified as "Implementable" in display-plans.md. However, as an escape hatch:
+
+> *Output the next fenced block as a code block:*
+
+```
+Missing Dependencies
+
+Unresolved (not yet planned):
+  • {topic}: {description}
+    No plan exists. Create with /start-planning or mark as
+    satisfied externally.
+
+Incomplete (planned but not implemented):
+  • {topic}: {plan}:{task-id} not yet completed
+    This task must be completed first.
+```
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+- **`i`/`implement`** — Implement the blocking dependencies first
+- **`l`/`link`** — Run /link-dependencies to wire up recently completed plans
+- **`s`/`satisfied`** — Mark a dependency as satisfied externally
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+---
+
+## Escape Hatch
+
+If the user says a dependency has been implemented outside the workflow:
+
+1. Ask which dependency to mark as satisfied
+2. Update the plan frontmatter: Change the dependency's `state` to `satisfied_externally`
+3. Commit the change
+4. Re-check dependencies
+
+→ Return to **[the skill](../SKILL.md)**.