@leeovery/claude-technical-workflows 2.1.30 → 2.1.32

package/skills/link-dependencies/SKILL.md

@@ -2,6 +2,12 @@
 name: link-dependencies
 description: "Scan all plans and wire up cross-topic dependencies. Finds unresolved external dependencies, matches them to tasks in other plans, and updates both the plan index and output format."
 disable-model-invocation: true
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
 ---
 
 Link cross-topic dependencies across all existing plans.

package/skills/start-discussion/SKILL.md

@@ -2,7 +2,13 @@
 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 docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md)
+allowed-tools: Bash(.claude/skills/start-discussion/scripts/discovery.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
 ---
 
 Invoke the **technical-discussion** skill for this conversation.
@@ -162,5 +168,20 @@ Load **[gather-context.md](references/gather-context.md)** and follow its instru
 
 ## Step 7: Invoke the Skill
 
+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" \
+  "docs/workflow/discussion/{topic}.md"
+```
+
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.
 

package/skills/start-feature/SKILL.md

@@ -1,82 +1,144 @@
 ---
 name: start-feature
-description: "Start a feature specification directly, skipping formal discussion documentation. For adding features to existing projects where you already know what you're building."
+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 docs/workflow/discussion/), Bash(.claude/hooks/workflows/write-session-state.sh)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
 ---
 
-Invoke the **technical-specification** skill for this conversation with inline feature context.
+Start a new feature and route it through the pipeline: Discussion → Specification → Planning → Implementation.
+
+> **⚠️ 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.
 
 ## Instructions
 
 Follow these steps EXACTLY as written. Do not skip steps or combine them.
 
-This skill is for **feature mode** - a streamlined path to specification when you already know what you're building and don't need formal discussion documentation.
+**CRITICAL**: This guidance is mandatory.
+
+- After each user interaction, STOP and wait for their response before proceeding
+- Never assume or anticipate user choices
+- Even if the user's initial prompt seems to answer a question, still confirm with them at the appropriate step
+- 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 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 `docs/workflow/discussion/` for recently modified files via `git log --oneline -5`.
+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)
+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
 
-Ask the user these questions (can be combined into one prompt):
+Load **[gather-feature-context.md](references/gather-feature-context.md)** and follow its instructions.
 
-1. **What feature are you adding?**
-   - Brief description of what you're building
+→ Proceed to **Step 2**.
 
-2. **What's the scope?**
-   - Core functionality to implement
-   - Edge cases you're already aware of
+---
 
-3. **Any constraints or integration points?**
-   - How this integrates with existing code
-   - Technical decisions already made
-   - Conventions to follow
+## Step 2: Topic Name and Conflict Check
 
-**Note**: If the user has already provided this context in their initial message, don't ask again - acknowledge what they've shared and proceed.
+Based on the feature description, suggest a topic name:
 
-## Step 2: Suggest a Topic Name
+> *Output the next fenced block as a code block:*
 
-Based on the feature description, suggest a topic name for the specification file:
+```
+Suggested topic name: {suggested-topic:(kebabcase)}
 
+This will create: docs/workflow/discussion/{suggested-topic}.md
 ```
-Based on what you've described, I'd suggest the topic name: {suggested-topic}
 
-This will create: docs/workflow/specification/{suggested-topic}/specification.md
+> *Output the next fenced block as markdown (not a code block):*
 
+```
+· · · · · · · · · · · ·
 Is this name okay, or would you prefer something else?
+· · · · · · · · · · · ·
 ```
 
-## Step 3: Check for Existing Specifications
+**STOP.** Wait for user response.
 
-Look in `docs/workflow/specification/` for naming conflicts:
+Once the topic name is confirmed, check for naming conflicts:
 
 ```bash
-ls docs/workflow/specification/
+ls docs/workflow/discussion/
 ```
 
-If a specification with the same name exists, inform the user and ask how to proceed:
-- Append to existing specification
-- Choose a different name
-- Replace existing specification
+If a discussion with the same name exists, inform the user:
 
-## Step 4: Invoke Specification Skill
+> *Output the next fenced block as markdown (not a code block):*
 
-Pass the gathered context to the [technical-specification](../technical-specification/SKILL.md) skill:
+```
+· · · · · · · · · · · ·
+A discussion named "{topic}" already exists.
 
+- **`r`/`resume`** — Resume the existing discussion
+- **`n`/`new`** — Choose a different name
+· · · · · · · · · · · ·
 ```
-Feature specification for: {topic}
 
-## Feature Context (from user)
+**STOP.** Wait for user response.
 
-{paste the gathered feature description, scope, and constraints}
+If resuming, check the discussion status. If concluded → skip to Step 4. If in-progress → proceed to Step 3.
+
+→ Proceed to **Step 3**.
 
 ---
 
-Begin specification building using the technical-specification skill.
+## Step 3: Invoke Discussion
+
+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 and continue the feature pipeline if the conversation is compacted.
+```
 
-This is feature mode - there is no discussion document to reference.
-Work from the inline context provided above.
+```bash
+.claude/hooks/workflows/write-session-state.sh \
+  "{topic}" \
+  "skills/technical-discussion/SKILL.md" \
+  "docs/workflow/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}'."
 ```
 
-## Notes
+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.
+
+---
+
+## Step 4: Phase Bridge
+
+Load **[phase-bridge.md](references/phase-bridge.md)** and follow its instructions.
 
-- The specification skill contains instructions for synthesizing the inline context, presenting it for validation, and building the specification
-- Output is a standard specification file at `docs/workflow/specification/{topic}/specification.md`
-- From there, the user can proceed to `/start-planning` as normal
-- This path skips formal discussion documentation - use the full workflow for complex features that need debate captured
+The bridge will enter plan mode with instructions to invoke continue-feature for the topic in the next session.

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

@@ -0,0 +1,60 @@
+# Gather Feature Context
+
+*Reference for **[start-feature](../SKILL.md)***
+
+---
+
+Gather context about the feature through a structured interview. Ask questions one at a time with STOP gates between each.
+
+**Note**: If the user has already provided context in their initial message, acknowledge what they've shared and skip questions that are already answered. Only ask what's missing.
+
+## Question 1: What are you building?
+
+> *Output the next fenced block as a code block:*
+
+```
+What feature are you adding?
+
+- Brief description of what you're building
+- What problem does it solve?
+```
+
+**STOP.** Wait for user response.
+
+## Question 2: What's the scope?
+
+> *Output the next fenced block as a code block:*
+
+```
+What's the scope?
+
+- Core functionality to implement
+- Known edge cases or constraints
+- What's explicitly out of scope?
+```
+
+**STOP.** Wait for user response.
+
+## Question 3: Integration and constraints
+
+> *Output the next fenced block as a code block:*
+
+```
+Any constraints or integration points?
+
+- How does this integrate with existing code?
+- Technical decisions already made
+- Conventions or patterns to follow
+- External dependencies or APIs
+```
+
+**STOP.** Wait for user response.
+
+## Compile Context
+
+After gathering answers, compile the feature context into a structured summary that will be passed to the discussion skill. Do not output the summary — it will be used in the next step.
+
+The compiled context should capture:
+- **Feature**: What is being built and why
+- **Scope**: Core functionality, edge cases, out-of-scope
+- **Constraints**: Integration points, decisions, conventions

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

@@ -0,0 +1,24 @@
+# Invoke Discussion
+
+*Reference for **[start-feature](../SKILL.md)***
+
+---
+
+Invoke the discussion skill with the gathered feature context.
+
+## Handoff
+
+Invoke the [technical-discussion](../../technical-discussion/SKILL.md) skill:
+
+```
+Technical discussion for: {topic}
+
+{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.
+
+Invoke the technical-discussion skill.
+```

package/skills/start-feature/references/phase-bridge.md

@@ -0,0 +1,37 @@
+# Phase Bridge
+
+*Reference for **[start-feature](../SKILL.md)***
+
+---
+
+The phase bridge clears context between the discussion phase and the rest of the pipeline. This is necessary because discussion can consume significant context, and starting fresh prevents degradation.
+
+## Enter Plan Mode
+
+Enter plan mode and write the following plan:
+
+```
+# Continue Feature: {topic}
+
+The discussion for "{topic}" has concluded. The next session should
+continue the feature pipeline from specification onwards.
+
+## Instructions
+
+1. Invoke the `/continue-feature` skill for topic "{topic}"
+2. The skill will detect that a concluded discussion exists and route to specification
+
+## Context
+
+- Topic: {topic}
+- Completed phase: discussion
+- Expected next phase: specification
+- Discussion: docs/workflow/discussion/{topic}.md
+
+## How to proceed
+
+Clear context and continue. Claude will invoke continue-feature
+with the topic above and route to the specification phase automatically.
+```
+
+Exit plan mode. The user will approve and clear context, and the fresh session will pick up with continue-feature routing to specification.

package/skills/start-implementation/SKILL.md

@@ -2,7 +2,13 @@
 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)
+allowed-tools: Bash(.claude/skills/start-implementation/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
 ---
 
 Invoke the **technical-implementation** skill for this conversation.
@@ -387,6 +393,21 @@ Are there any environment setup instructions I should follow before implementati
 
 ## Step 6: Invoke the Skill
 
+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" \
+  "docs/workflow/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.

package/skills/start-planning/SKILL.md

@@ -2,7 +2,13 @@
 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(.claude/skills/start-planning/scripts/discovery.sh)
+allowed-tools: Bash(.claude/skills/start-planning/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
 ---
 
 Invoke the **technical-planning** skill for this conversation.
@@ -177,4 +183,19 @@ Load **[cross-cutting-context.md](references/cross-cutting-context.md)** and fol
 
 ## Step 7: Invoke the Skill
 
+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-planning/SKILL.md" \
+  "docs/workflow/planning/{topic}/plan.md"
+```
+
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-research/SKILL.md

@@ -2,6 +2,13 @@
 name: start-research
 description: "Start a research exploration using the technical-research skill. For early-stage ideas, feasibility checks, and broad exploration before formal discussion."
 disable-model-invocation: true
+allowed-tools: Bash(.claude/hooks/workflows/write-session-state.sh)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
 ---
 
 Invoke the **technical-research** skill for this conversation.
@@ -43,7 +50,7 @@ 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.
+**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.
 
@@ -59,4 +66,19 @@ Load **[gather-context.md](references/gather-context.md)** and follow its instru
 
 ## Step 2: Invoke the Skill
 
+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-research/SKILL.md" \
+  "docs/workflow/research/{topic}.md"
+```
+
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-review/SKILL.md

@@ -2,7 +2,13 @@
 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(.claude/skills/start-review/scripts/discovery.sh)
+allowed-tools: Bash(.claude/skills/start-review/scripts/discovery.sh), Bash(.claude/hooks/workflows/write-session-state.sh)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
 ---
 
 Invoke the **technical-review** skill for this conversation.
@@ -130,4 +136,19 @@ Load **[select-plans.md](references/select-plans.md)** and follow its instructio
 
 ## Step 5: Invoke the Skill
 
+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-review/SKILL.md" \
+  "docs/workflow/review/{topic}.md"
+```
+
 Load **[invoke-skill.md](references/invoke-skill.md)** and follow its instructions as written.

package/skills/start-specification/SKILL.md

@@ -2,7 +2,13 @@
 name: start-specification
 description: "Start a specification session from concluded discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/skills/start-specification/scripts/discovery.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(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md), Bash(.claude/hooks/workflows/write-session-state.sh)
+hooks:
+  PreToolUse:
+    - hooks:
+        - type: command
+          command: "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/system-check.sh"
+          once: true
 ---
 
 Invoke the **technical-specification** skill for this conversation.
@@ -46,7 +52,7 @@ 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.
+**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.
 

package/skills/start-specification/references/handoffs/continue-concluded.md

@@ -6,6 +6,21 @@
 
 Before invoking the skill, reset `finding_gate_mode` to `gated` in the specification frontmatter if present. Commit if changed: `spec({topic}): reset gate mode`
 
+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" \
+  "docs/workflow/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.
 
 ```

package/skills/start-specification/references/handoffs/continue.md

@@ -6,6 +6,21 @@
 
 Before invoking the skill, reset `finding_gate_mode` to `gated` in the specification frontmatter if present. Commit if changed: `spec({topic}): reset gate mode`
 
+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" \
+  "docs/workflow/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.
 
 ```

package/skills/start-specification/references/handoffs/create-with-incorporation.md

@@ -4,6 +4,21 @@
 
 ---
 
+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" \
+  "docs/workflow/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.
 
 ```

package/skills/start-specification/references/handoffs/create.md

@@ -4,6 +4,21 @@
 
 ---
 
+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" \
+  "docs/workflow/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.
 
 ```

package/skills/start-specification/references/handoffs/unify-with-incorporation.md

@@ -4,6 +4,21 @@
 
 ---
 
+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 \
+  "unified" \
+  "skills/technical-specification/SKILL.md" \
+  "docs/workflow/specification/unified/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.
 
 ```