@leeovery/claude-technical-workflows 2.1.31 → 2.1.32

package/README.md

@@ -64,8 +64,8 @@ Pick your entry point based on where you are:
 - **Know what you're building?** → Start with `/start-discussion`
   You've moved past exploration and want to capture architecture decisions, edge cases, and rationale for specific topics.
 
-- **Clear feature, ready to spec?** → Use `/start-feature`
-  You already know the what and why. Jump straight to building a specification from inline context — no prior documents needed.
+- **Clear feature, ready to build?** → Use `/start-feature`
+  You know what you're building. Start-feature gathers context, creates a discussion, then pipelines through specification → planning → implementation automatically via plan mode bridges.
 
 **Why research is the recommended default:** When you move from research to discussion, the discussion skill analyses your research document and automatically breaks it into focused discussion topics. Skip research and you manage topic structure yourself.
 
@@ -121,10 +121,35 @@ Not every task needs the full workflow. These skills gather inputs flexibly and
 | `/start-feature` | Create a spec directly from inline context (skip research/discussion) |
 | `/link-dependencies` | Wire cross-topic dependencies across plans |
 
+### Feature Pipeline
+
+`/start-feature` chains the full workflow into an automated pipeline:
+
+```
+/start-feature
+    │
+    ▼
+Discussion ──▶ Specification ──▶ Planning ──▶ Implementation
+```
+
+**How it works:** After each phase completes, a plan mode bridge clears context and advances to the next phase automatically. You approve each transition with "clear context and continue" — this keeps each phase in a clean context window.
+
+If a session is interrupted, run `/continue-feature` to pick up where you left off. It reads artifact state to determine the next phase.
+
 ### Under the Hood
 
 Skills are organised in two tiers. **Entry-point skills** (`/start-*`, `/status`, etc.) gather context from files, prompts, or inline input. **Processing skills** (`technical-*`) receive those inputs and do the work — they don't know or care where inputs came from. This separation means the same processing skill can be invoked from different entry points: `/start-specification` and `/start-feature` both feed `technical-specification` with different inputs. You can create custom entry-point skills that feed processing skills in new ways.
 
+### Compaction Recovery
+
+Long-running skills can hit context compaction, where Claude's conversation is summarized and procedural detail is lost. The hook system provides automatic recovery:
+
+- **Project-level hooks** installed in `.claude/settings.json` persist through compaction events
+- On compaction, the recovery hook reads session state from disk and injects authoritative context — the skill to re-read, the artifact to resume, and pipeline instructions
+- On first run, a bootstrap hook detects missing configuration and installs it automatically (requires one Claude restart)
+
+Session state is ephemeral (gitignored, cleaned up on session end) and per-session — multiple concurrent sessions don't interfere.
+
 ### Workflow Skills
 
 | Phase          | Skill                   |
@@ -226,7 +251,8 @@ skills/
 │
 ├── # Entry-point skills (user-invocable)
 ├── migrate/                         # Keep workflow files in sync with system design
-├── start-feature/                   # Standalone: spec from inline context
+├── start-feature/                   # Pipeline: discussion → spec → plan → impl
+├── continue-feature/                # Pipeline: route feature to next phase
 ├── link-dependencies/               # Standalone: wire cross-topic deps
 ├── start-research/                  # Begin research
 ├── start-discussion/                # Begin discussions
@@ -235,7 +261,11 @@ skills/
 ├── start-implementation/            # Begin implementation
 ├── start-review/                    # Begin review
 ├── status/                          # Show workflow status
-└── view-plan/                       # View plan tasks
+├── view-plan/                       # View plan tasks
+│
+├── # Bridge skills (model-invocable — pipeline pre-flight)
+├── begin-planning/                  # Pre-flight for planning in pipeline
+└── begin-implementation/            # Pre-flight for implementation in pipeline
 
 agents/
 ├── review-task-verifier.md           # Verifies single task implementation for review
@@ -298,7 +328,8 @@ Independent skills that gather inputs flexibly (inline context, files, or prompt
 
 | Skill                                                   | Description                                                                                                                                 |
 |---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/start-feature**](skills/start-feature/)              | Create a specification directly from inline context. Invokes the specification skill without requiring a discussion document.              |
+| [**/start-feature**](skills/start-feature/)              | Start a new feature through the full pipeline. Gathers context, creates a discussion, then bridges through specification → planning → implementation. |
+| [**/continue-feature**](skills/continue-feature/)        | Continue a feature through its next pipeline phase. Routes automatically based on artifact state. Used manually or from plan mode bridges.  |
 | [**/link-dependencies**](skills/link-dependencies/)      | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
 
 ### Creating Custom Skills

package/hooks/workflows/compact-recovery.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+#
+# compact-recovery.sh
+#
+# SessionStart hook (compact).
+# Reads session_id from stdin, looks for saved session state,
+# and injects recovery context so the model can resume work.
+#
+
+# Resolve project directory
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$PROJECT_DIR" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  PROJECT_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+fi
+
+# Extract session_id from stdin JSON
+session_id=$(cat | grep -o '"session_id" *: *"[^"]*"' | sed 's/.*: *"//;s/"//')
+
+if [ -z "$session_id" ]; then
+  exit 0
+fi
+
+SESSION_FILE="$PROJECT_DIR/docs/workflow/.cache/sessions/${session_id}.yaml"
+
+if [ ! -f "$SESSION_FILE" ]; then
+  exit 0
+fi
+
+# Parse YAML fields (simple key: value format)
+topic=$(grep '^topic:' "$SESSION_FILE" | awk '{print $2}')
+skill=$(grep '^skill:' "$SESSION_FILE" | awk '{print $2}')
+artifact=$(grep '^artifact:' "$SESSION_FILE" | awk '{print $2}')
+
+# Check for pipeline section
+has_pipeline=false
+if grep -q '^pipeline:' "$SESSION_FILE"; then
+  has_pipeline=true
+  # Extract after_conclude content (indented block after "after_conclude: |")
+  pipeline_content=$(awk '
+    /^  after_conclude:/ { capture=1; next }
+    capture && /^[^ ]/ { exit }
+    capture && /^    / { sub(/^    /, ""); print }
+  ' "$SESSION_FILE")
+fi
+
+# Build additionalContext
+context="CONTEXT COMPACTION — SESSION RECOVERY
+
+Context was just compacted. Follow these instructions carefully.
+
+─── IMMEDIATE: Resume current work ───
+$([ -n "$topic" ] && echo "
+You are working on topic '${topic}'.")
+Skill: ${skill}
+
+1. Re-read that skill file completely
+2. Follow its 'Resuming After Context Refresh' section
+3. Re-read the artifact: ${artifact}
+4. Continue working until the skill reaches its natural conclusion
+
+The files on disk are authoritative — not the conversation summary."
+
+if [ "$has_pipeline" = true ] && [ -n "$pipeline_content" ]; then
+  context="${context}
+
+─── AFTER CONCLUSION ONLY ───
+
+${pipeline_content}
+
+Do NOT enter plan mode or invoke continue-feature until the current
+phase is complete. Finish the current phase first."
+fi
+
+# Escape context for JSON output
+json_context=$(printf '%s' "$context" | sed 's/\\/\\\\/g; s/"/\\"/g; s/$/\\n/' | tr -d '\n')
+json_context="\"${json_context%\\n}\""
+
+echo "{ \"hookSpecificOutput\": { \"hookEventName\": \"SessionStart\", \"additionalContext\": ${json_context} } }"
+
+exit 0

package/hooks/workflows/session-cleanup.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#
+# session-cleanup.sh
+#
+# SessionEnd hook.
+# Reads session_id from stdin JSON and removes the session state file if it exists.
+#
+
+# Resolve project directory
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$PROJECT_DIR" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  PROJECT_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+fi
+
+# Extract session_id from stdin JSON
+session_id=$(cat | grep -o '"session_id" *: *"[^"]*"' | sed 's/.*: *"//;s/"//')
+
+if [ -n "$session_id" ]; then
+  session_file="$PROJECT_DIR/docs/workflow/.cache/sessions/${session_id}.yaml"
+  if [ -f "$session_file" ]; then
+    rm -f "$session_file"
+  fi
+fi
+
+exit 0

package/hooks/workflows/session-env.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+#
+# session-env.sh
+#
+# SessionStart hook (startup|resume|clear).
+# Reads session_id from stdin JSON and writes it to CLAUDE_ENV_FILE
+# so entry-point skills can reference the session ID.
+#
+
+# Extract session_id from stdin JSON
+session_id=$(cat | grep -o '"session_id" *: *"[^"]*"' | sed 's/.*: *"//;s/"//')
+
+if [ -n "$session_id" ] && [ -n "$CLAUDE_ENV_FILE" ]; then
+  echo "export CLAUDE_SESSION_ID=${session_id}" > "$CLAUDE_ENV_FILE"
+fi
+
+exit 0

package/hooks/workflows/system-check.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+#
+# system-check.sh
+#
+# Bootstrap hook for workflow skills. Ensures project-level hooks
+# (compaction recovery, session tracking) are installed in
+# .claude/settings.json.
+#
+# Called as a PreToolUse hook from skill frontmatter.
+# Uses jq if available, falls back to node, then to manual instructions.
+#
+
+# Consume stdin (PreToolUse sends JSON — must be drained)
+cat > /dev/null 2>&1 || true
+
+# Resolve project directory
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$PROJECT_DIR" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  PROJECT_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+fi
+
+SETTINGS_FILE="$PROJECT_DIR/.claude/settings.json"
+
+# ─── Detection (grep only) ───
+
+has_our_hooks() {
+  [ -f "$SETTINGS_FILE" ] &&
+    grep -q "hooks/workflows/session-env.sh" "$SETTINGS_FILE" 2>/dev/null &&
+    grep -q "hooks/workflows/compact-recovery.sh" "$SETTINGS_FILE" 2>/dev/null &&
+    grep -q "hooks/workflows/session-cleanup.sh" "$SETTINGS_FILE" 2>/dev/null
+}
+
+if has_our_hooks; then
+  exit 0
+fi
+
+# ─── Hook JSON templates ───
+# $CLAUDE_PROJECT_DIR below is intentionally literal (expanded by Claude Code at runtime)
+# shellcheck disable=SC2016
+HOOKS_ONLY='{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/session-env.sh" }]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/compact-recovery.sh" }]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [{ "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/workflows/session-cleanup.sh" }]
+      }
+    ]
+  }
+}'
+
+# ─── Installation ───
+
+mkdir -p "$(dirname "$SETTINGS_FILE")"
+
+if [ ! -f "$SETTINGS_FILE" ] || [ ! -s "$SETTINGS_FILE" ]; then
+  # No file or empty — write fresh
+  printf '%s\n' "$HOOKS_ONLY" > "$SETTINGS_FILE"
+
+elif command -v jq >/dev/null 2>&1; then
+  # Merge using jq — append our entries to existing arrays
+  merged=$(jq \
+    --argjson ours "$HOOKS_ONLY" \
+    '
+      .hooks //= {} |
+      .hooks.SessionStart = ((.hooks.SessionStart // []) + $ours.hooks.SessionStart) |
+      .hooks.SessionEnd = ((.hooks.SessionEnd // []) + $ours.hooks.SessionEnd)
+    ' "$SETTINGS_FILE")
+  printf '%s\n' "$merged" > "$SETTINGS_FILE"
+
+elif command -v node >/dev/null 2>&1; then
+  # Merge using node
+  node -e "
+    const fs = require('fs');
+    const existing = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    const ours = JSON.parse(process.argv[2]);
+    existing.hooks = existing.hooks || {};
+    existing.hooks.SessionStart = (existing.hooks.SessionStart || []).concat(ours.hooks.SessionStart);
+    existing.hooks.SessionEnd = (existing.hooks.SessionEnd || []).concat(ours.hooks.SessionEnd);
+    fs.writeFileSync(process.argv[1], JSON.stringify(existing, null, 2) + '\n');
+  " "$SETTINGS_FILE" "$HOOKS_ONLY"
+
+else
+  # No tools available — write hooks to separate file with instructions
+  printf '%s\n' "$HOOKS_ONLY" > "${SETTINGS_FILE%.json}.workflow-hooks.json"
+  echo '{ "continue": false, "stopReason": "Your .claude/settings.json needs workflow hooks but neither jq nor node is available to merge automatically. The hooks have been written to .claude/settings.workflow-hooks.json — please merge the SessionStart and SessionEnd entries into your settings.json, then restart Claude Code." }'
+  exit 0
+fi
+
+echo '{ "continue": false, "stopReason": "Workflow hooks configured. Restart Claude Code to activate compaction recovery, then re-invoke your skill." }'
+exit 0

package/hooks/workflows/write-session-state.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+#
+# write-session-state.sh
+#
+# Helper script called by entry-point skills to save session state for
+# compaction recovery.
+#
+# Usage:
+#   write-session-state.sh "<topic>" "<skill-path>" "<artifact-path>" [--pipeline "<after-conclude instructions>"]
+#
+# Requires CLAUDE_SESSION_ID in environment (set by session-env.sh).
+#
+
+# Resolve project directory
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-}"
+if [ -z "$PROJECT_DIR" ]; then
+  SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  PROJECT_DIR="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+fi
+
+if [ -z "$CLAUDE_SESSION_ID" ]; then
+  # No session ID available — silently skip
+  exit 0
+fi
+
+topic="$1"
+skill="$2"
+artifact="$3"
+pipeline_content=""
+
+# Parse optional --pipeline flag
+shift 3 || true
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --pipeline)
+      pipeline_content="$2"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+SESSIONS_DIR="$PROJECT_DIR/docs/workflow/.cache/sessions"
+mkdir -p "$SESSIONS_DIR"
+
+SESSION_FILE="$SESSIONS_DIR/${CLAUDE_SESSION_ID}.yaml"
+
+# Write base fields
+cat > "$SESSION_FILE" <<EOF
+topic: ${topic}
+skill: ${skill}
+artifact: ${artifact}
+EOF
+
+# Append pipeline section if provided
+if [ -n "$pipeline_content" ]; then
+  cat >> "$SESSION_FILE" <<EOF
+pipeline:
+  after_conclude: |
+$(echo "$pipeline_content" | sed 's/^/    /')
+EOF
+fi
+
+exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.1.31",
+  "version": "2.1.32",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/begin-implementation/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: begin-implementation
+description: "Bridge skill for the feature pipeline. Runs pre-flight checks for implementation and invokes the technical-implementation skill. Called by continue-feature — not directly by users."
+user-invocable: false
+allowed-tools: Bash(.claude/skills/start-implementation/scripts/discovery.sh)
+---
+
+Invoke the **technical-implementation** skill for this conversation with pre-flight context.
+
+> **⚠️ 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 a **bridge** — it runs pre-flight checks for implementation and hands off to the processing skill. The topic has already been selected by the caller.
+
+**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 1: Run Discovery
+
+Execute the start-implementation discovery script to gather current state:
+
+```bash
+.claude/skills/start-implementation/scripts/discovery.sh
+```
+
+Parse the output to find the plan matching the provided topic. Extract:
+
+- **Plan details**: status, format, plan_id, specification, specification_exists
+- **External dependencies**: external_deps, has_unresolved_deps
+- **Dependency resolution**: deps_satisfied, deps_blocking
+- **Implementation tracking**: from `implementation.files` matching the topic
+- **Environment**: setup_file_exists, requires_setup
+
+If the plan is missing or not concluded, this is an error — report it and stop.
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Check External Dependencies
+
+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 3**.
+
+#### If any deps are blocking
+
+> *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
+- **`s`/`satisfied`** — Mark a dependency as satisfied externally
+- **`c`/`continue`** — Continue anyway (at your own risk)
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+If the user chooses `implement`, end here — suggest running `/start-implementation` for the blocking topic. If `satisfied`, update the plan frontmatter (`state: satisfied_externally`) and continue. If `continue`, proceed.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Check 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 4**.
+
+**If `setup_file_exists: true` and `requires_setup: true`:**
+
+> *Output the next fenced block as a code block:*
+
+```
+Environment setup file found: docs/workflow/environment-setup.md
+```
+
+→ Proceed to **Step 4**.
+
+**If `setup_file_exists: false` or `requires_setup: 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 `docs/workflow/environment-setup.md`, commit
+- If the user says no/none, create `docs/workflow/environment-setup.md` with "No special setup required." and commit
+
+→ Proceed to **Step 4**.
+
+---
+
+## Step 4: Invoke the Skill
+
+Determine the implementation tracking state:
+- If a tracking file exists for this topic → use its status
+- If no tracking file → status is "not-started"
+
+Construct the handoff and invoke the [technical-implementation](../technical-implementation/SKILL.md) skill:
+
+```
+Implementation session for: {topic}
+Plan: docs/workflow/planning/{topic}/plan.md
+Format: {format}
+Plan ID: {plan_id} (if applicable)
+Specification: docs/workflow/specification/{topic}/specification.md (exists: {true|false})
+Implementation tracking: {exists | new} (status: {status})
+Dependencies: {All satisfied | notes}
+Environment: {Setup required | No special setup required}
+
+Invoke the technical-implementation skill.
+```

package/skills/begin-planning/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: begin-planning
+description: "Bridge skill for the feature pipeline. Runs pre-flight checks for planning and invokes the technical-planning skill. Called by continue-feature — not directly by users."
+user-invocable: false
+allowed-tools: Bash(.claude/skills/start-planning/scripts/discovery.sh)
+---
+
+Invoke the **technical-planning** skill for this conversation with pre-flight context.
+
+> **⚠️ 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 a **bridge** — it runs pre-flight checks for planning and hands off to the processing skill. The topic has already been selected by the caller.
+
+**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 1: Run Discovery
+
+Execute the start-planning discovery script to gather current state:
+
+```bash
+.claude/skills/start-planning/scripts/discovery.sh
+```
+
+Parse the output to extract:
+
+- **Cross-cutting specifications** from `specifications.crosscutting` (name, status)
+- **Common format** from `plans.common_format`
+
+The topic was provided by the caller. Confirm the specification exists and is concluded:
+
+- Check `specifications.feature` for the topic
+- If the spec is missing or not concluded, this is an error — report it and stop
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Handle Cross-Cutting Context
+
+Load **[cross-cutting-context.md](../start-planning/references/cross-cutting-context.md)** and follow its instructions as written.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Gather Additional Context
+
+> *Output the next fenced block as markdown (not a code block):*
+
+```
+· · · · · · · · · · · ·
+Any additional context for planning?
+
+- **`c`/`continue`** — Continue with the specification as-is
+- Or provide additional context (priorities, constraints, new considerations)
+· · · · · · · · · · · ·
+```
+
+**STOP.** Wait for user response.
+
+→ Proceed to **Step 4**.
+
+---
+
+## Step 4: Invoke the Skill
+
+Construct the handoff and invoke the [technical-planning](../technical-planning/SKILL.md) skill:
+
+```
+Planning session for: {topic}
+Specification: docs/workflow/specification/{topic}/specification.md
+Additional context: {summary of user's answer from Step 3, or "none"}
+Cross-cutting references: {list of applicable cross-cutting specs with brief summaries, or "none"}
+Recommended output format: {common_format from discovery if non-empty, otherwise "none"}
+
+Invoke the technical-planning skill.
+```