@leeovery/claude-technical-workflows 2.1.18 → 2.1.20

package/skills/start-specification/references/display-single-grouped.md

@@ -0,0 +1,69 @@
+# Display: Single Discussion — Grouped Spec
+
+*Reference for **[display-single.md](display-single.md)***
+
+---
+
+This discussion is covered by a specification with multiple sources.
+
+Use the spec for display. Show the spec name as the title. Show ALL the spec's sources (not just this discussion) with their statuses:
+- `incorporated` + `discussion_status: concluded` or `not-found` → `(extracted)`
+- `incorporated` + `discussion_status: other` (e.g. `in-progress`) → `(extracted, reopened)`
+- `pending` → `(pending)`
+
+Extraction count: X = sources with `status: incorporated`, Y = total source count from the spec's `sources` array.
+
+## Display
+
+```
+Specification Overview
+
+Single concluded discussion found with existing multi-source specification.
+
+1. {Spec Title Case Name}
+    └─ Spec: {spec_status} ({X} of {Y} sources extracted)
+    └─ Discussions:
+       ├─ {source-name} (extracted)
+       └─ {source-name} (extracted, reopened)
+```
+
+Indentation: `└─` starts at column 4 (under the name text, not the number). Discussion entries start at column 7.
+
+### If in-progress discussions exist
+
+```
+Discussions not ready for specification:
+These discussions are still in progress and must be concluded
+before they can be included in a specification.
+  · {discussion-name} (in-progress)
+```
+
+### Key/Legend
+
+Show only the statuses that appear in the current display. No `---` separator before this section.
+
+```
+Key:
+
+  Discussion status:
+    extracted — content has been incorporated into the specification
+    pending   — listed as source but content not yet extracted
+    reopened  — was extracted but discussion has regressed to in-progress
+
+  Spec status:
+    in-progress — specification work is ongoing
+    concluded   — specification is complete
+```
+
+## After Display
+
+```
+Automatically proceeding with "{Spec Title Case Name}".
+```
+
+Auto-proceed uses the spec name. Verb rule:
+- Spec is `in-progress` → **"Continuing"**
+- Spec is `concluded` with pending sources → **"Continuing"**
+- Spec is `concluded` with all sources extracted → **"Refining"**
+
+→ Load **[confirm-and-handoff.md](confirm-and-handoff.md)** and follow its instructions.

package/skills/start-specification/references/display-single-has-spec.md

@@ -0,0 +1,60 @@
+# Display: Single Discussion — Has Spec
+
+*Reference for **[display-single.md](display-single.md)***
+
+---
+
+An individual specification exists for this discussion.
+
+Determine extraction count: check the spec's `sources` array from discovery. Count how many have `status: incorporated` vs total.
+
+## Display
+
+```
+Specification Overview
+
+Single concluded discussion found with existing specification.
+
+1. {Title Case Name}
+    └─ Spec: {spec_status} ({X} of {Y} sources extracted)
+    └─ Discussions:
+       └─ {discussion-name} (extracted)
+```
+
+Indentation: `└─` starts at column 4 (under the name text, not the number). Discussion entries start at column 7.
+
+### If in-progress discussions exist
+
+```
+Discussions not ready for specification:
+These discussions are still in progress and must be concluded
+before they can be included in a specification.
+  · {discussion-name} (in-progress)
+```
+
+### Key/Legend
+
+No `---` separator before this section.
+
+```
+Key:
+
+  Discussion status:
+    extracted — content has been incorporated into the specification
+
+  Spec status:
+    {spec_status} — {in-progress: "specification work is ongoing" | concluded: "specification is complete"}
+```
+
+## After Display
+
+```
+Automatically proceeding with "{Title Case Name}".
+```
+
+Auto-proceed. Verb rule:
+- Spec is `in-progress` → **"Continuing"**
+- Spec is `concluded` with pending sources → **"Continuing"**
+- Spec is `concluded` with all sources extracted → **"Refining"**
+
+→ Load **[confirm-and-handoff.md](confirm-and-handoff.md)** and follow its instructions.

package/skills/start-specification/references/display-single-no-spec.md

@@ -0,0 +1,55 @@
+# Display: Single Discussion — No Spec
+
+*Reference for **[display-single.md](display-single.md)***
+
+---
+
+No specification exists for this discussion.
+
+## Display
+
+```
+Specification Overview
+
+Single concluded discussion found.
+
+1. {Title Case Name}
+    └─ Spec: none
+    └─ Discussions:
+       └─ {discussion-name} (ready)
+```
+
+Indentation: `└─` starts at column 4 (under the name text, not the number). Discussion entries start at column 7.
+
+### If in-progress discussions exist
+
+```
+Discussions not ready for specification:
+These discussions are still in progress and must be concluded
+before they can be included in a specification.
+  · {discussion-name} (in-progress)
+```
+
+### Key/Legend
+
+No `---` separator before this section.
+
+```
+Key:
+
+  Discussion status:
+    ready — concluded and available to be specified
+
+  Spec status:
+    none — no specification file exists yet
+```
+
+## After Display
+
+```
+Automatically proceeding with "{Title Case Name}".
+```
+
+Auto-proceed with verb **"Creating"**.
+
+→ Load **[confirm-and-handoff.md](confirm-and-handoff.md)** and follow its instructions.

package/skills/start-specification/references/display-single.md

@@ -0,0 +1,25 @@
+# Display: Single Discussion
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Auto-proceed path — only one concluded discussion exists, so no selection menu is needed.
+
+Convert discussion filename to title case (`auth-flow` → `Auth Flow`).
+
+## Route by Spec Coverage
+
+Check if a spec covers this discussion — either by name match (`has_individual_spec`) or by listing it in a spec's `sources` array.
+
+#### If a spec covers this discussion and has a single source
+
+→ Load **[display-single-has-spec.md](display-single-has-spec.md)** and follow its instructions.
+
+#### If a spec covers this discussion and has multiple sources
+
+→ Load **[display-single-grouped.md](display-single-grouped.md)** and follow its instructions.
+
+#### Otherwise
+
+→ Load **[display-single-no-spec.md](display-single-no-spec.md)** and follow its instructions.

package/skills/start-specification/references/display-specs-menu.md

@@ -0,0 +1,134 @@
+# Display: Specs Menu
+
+*Reference for **[start-specification](../SKILL.md)***
+
+---
+
+Shows when multiple concluded discussions exist, specifications exist, and cache is none or stale. Displays existing specs from discovery frontmatter (NOT from cache), lists unassigned discussions, and offers analysis or continue options.
+
+## A. Display
+
+```
+Specification Overview
+
+{N} concluded discussions found. {M} specifications exist.
+
+Existing specifications:
+```
+
+For each non-superseded specification from discovery output, display as nested tree:
+
+```
+1. {Spec Title Case Name}
+    └─ Spec: {status} ({X} of {Y} sources extracted)
+    └─ Discussions:
+       ├─ {source-name} (extracted)
+       └─ {source-name} (extracted)
+```
+
+Indentation: `└─` starts at column 4 (under the name text, not the number). Discussion entries start at column 7.
+
+Determine discussion status from the spec's `sources` array:
+- `incorporated` + `discussion_status: concluded` or `not-found` → `extracted`
+- `incorporated` + `discussion_status: other` (e.g. `in-progress`) → `extracted, reopened`
+- `pending` → `pending`
+
+Extraction count: X = sources with `status: incorporated`, Y = total source count from the spec's `sources` array.
+
+### Unassigned Discussions
+
+List concluded discussions that are not in any specification's `sources` array:
+
+```
+Concluded discussions not in a specification:
+  • {discussion-name}
+  • {discussion-name}
+```
+
+### If in-progress discussions exist
+
+```
+Discussions not ready for specification:
+These discussions are still in progress and must be concluded
+before they can be included in a specification.
+  · {discussion-name} (in-progress)
+```
+
+### Key/Legend
+
+Show only the statuses that appear in the current display. No `---` separator before this section.
+
+```
+Key:
+
+  Discussion status:
+    extracted — content has been incorporated into the specification
+    reopened  — was extracted but discussion has regressed to in-progress
+
+  Spec status:
+    in-progress — specification work is ongoing
+    concluded   — specification is complete
+```
+
+### Cache-Aware Message
+
+No `---` separator before these messages.
+
+#### If cache status is "none"
+
+```
+No grouping analysis exists.
+```
+
+#### If cache status is "stale"
+
+```
+A previous grouping analysis exists but is outdated — discussions
+have changed since it was created. Re-analysis is required.
+```
+
+→ Proceed to **B. Menu**.
+
+---
+
+## B. Menu
+
+List "Analyze for groupings (recommended)" first, then one entry per existing non-superseded specification. The verb depends on the spec's state:
+
+- Spec is `in-progress` → **Continue** "{Name}" — in-progress
+- Spec is `concluded` with pending sources → **Continue** "{Name}" — {N} source(s) pending extraction
+- Spec is `concluded` with no pending sources → **Refine** "{Name}" — concluded
+
+**Example assembled menu** (2 specs exist):
+
+```
+· · · · · · · · · · · ·
+1. Analyze for groupings (recommended)
+   `All discussions are analyzed for natural groupings. Existing`
+   `specification names are preserved. You can provide guidance`
+   `in the next step.`
+2. Continue "Auth Flow" — in-progress
+3. Refine "Data Model" — concluded
+
+Select an option (enter number):
+· · · · · · · · · · · ·
+```
+
+Menu descriptions are wrapped in backticks to visually distinguish them from the choice labels.
+
+**STOP.** Wait for user response.
+
+#### If user picks "Analyze for groupings"
+
+If cache is stale, delete it first:
+```bash
+rm docs/workflow/.cache/discussion-consolidation-analysis.md
+```
+
+→ Load **[analysis-flow.md](analysis-flow.md)** and follow its instructions.
+
+#### If user picks "Continue" or "Refine" for a spec
+
+The selected spec and its sources become the context for confirmation.
+
+→ Load **[confirm-and-handoff.md](confirm-and-handoff.md)** and follow its instructions.

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

@@ -0,0 +1,24 @@
+# Handoff: Continue Concluded Specification
+
+*Reference for **[confirm-continue.md](../confirm-continue.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.
+
+```
+Specification session for: {Title Case Name}
+
+Continuing existing: docs/workflow/specification/{kebab-case-name}.md (concluded)
+
+New sources to extract:
+- docs/workflow/discussion/{new-discussion-name}.md
+
+Previously extracted (for reference):
+- docs/workflow/discussion/{existing-discussion-name}.md
+
+Context: This specification was previously concluded. New source discussions have been identified. Extract and incorporate their content while maintaining consistency with the existing specification.
+
+---
+Invoke the technical-specification skill.
+```

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

@@ -0,0 +1,22 @@
+# Handoff: Continue Specification
+
+*Reference for **[confirm-continue.md](../confirm-continue.md)** and **[confirm-refine.md](../confirm-refine.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.
+
+```
+Specification session for: {Title Case Name}
+
+Continuing existing: docs/workflow/specification/{kebab-case-name}.md
+
+Sources for reference:
+- docs/workflow/discussion/{discussion-name}.md
+- docs/workflow/discussion/{discussion-name}.md
+
+Context: This specification already exists. Review and refine it based on the source discussions.
+
+---
+Invoke the technical-specification skill.
+```

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

@@ -0,0 +1,30 @@
+# Handoff: Create With Incorporation
+
+*Reference for **[confirm-create.md](../confirm-create.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.
+
+```
+Specification session for: {Title Case Name}
+
+Source discussions:
+- docs/workflow/discussion/{discussion-name}.md
+- docs/workflow/discussion/{discussion-name}.md
+
+Existing specifications to incorporate:
+- docs/workflow/specification/{spec-name}.md (covers: {discussion-name} discussion)
+
+Output: docs/workflow/specification/{kebab-case-name}.md
+
+Context: This consolidates multiple sources. The existing {spec-name}.md specification should be incorporated - extract and adapt its content alongside the discussion material. The result should be a unified specification, not a simple merge.
+
+After the {kebab-case-name} specification is complete, mark the incorporated specs as superseded by updating their frontmatter:
+
+    status: superseded
+    superseded_by: {kebab-case-name}
+
+---
+Invoke the technical-specification skill.
+```

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

@@ -0,0 +1,20 @@
+# Handoff: Create Specification
+
+*Reference for **[confirm-create.md](../confirm-create.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.
+
+```
+Specification session for: {Title Case Name}
+
+Sources:
+- docs/workflow/discussion/{discussion-name}.md
+- docs/workflow/discussion/{discussion-name}.md
+
+Output: docs/workflow/specification/{kebab-case-name}.md
+
+---
+Invoke the technical-specification skill.
+```

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

@@ -0,0 +1,32 @@
+# Handoff: Unify With Incorporation
+
+*Reference for **[confirm-unify.md](../confirm-unify.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.
+
+```
+Specification session for: Unified
+
+Source discussions:
+- docs/workflow/discussion/{discussion-name}.md
+- docs/workflow/discussion/{discussion-name}.md
+...
+
+Existing specifications to incorporate:
+- docs/workflow/specification/{spec-name}.md
+- docs/workflow/specification/{spec-name}.md
+
+Output: docs/workflow/specification/unified.md
+
+Context: This consolidates all discussions into a single unified specification. The existing specifications should be incorporated - extract and adapt their content alongside the discussion material.
+
+After the unified specification is complete, mark the incorporated specs as superseded by updating their frontmatter:
+
+    status: superseded
+    superseded_by: unified
+
+---
+Invoke the technical-specification skill.
+```

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

@@ -0,0 +1,21 @@
+# Handoff: Unify All
+
+*Reference for **[confirm-unify.md](../confirm-unify.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.
+
+```
+Specification session for: Unified
+
+Sources:
+- docs/workflow/discussion/{discussion-name}.md
+- docs/workflow/discussion/{discussion-name}.md
+...
+
+Output: docs/workflow/specification/unified.md
+
+---
+Invoke the technical-specification skill.
+```

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

@@ -46,17 +46,35 @@ extract_array_field() {
 }
 
 # Helper: Extract sources with status from object format
-# Outputs YAML-formatted source entries with name and status
-# Usage: extract_sources_with_status <file>
+# Outputs YAML-formatted source entries with name, status, and discussion_status
+# Usage: extract_sources_with_status <file> [discussion_dir]
 #
 # Note: This only handles the object format. Legacy simple array format
 # is converted by migration 004 before discovery runs.
 extract_sources_with_status() {
     local file="$1"
+    local discussion_dir="$2"
     local in_sources=false
     local current_name=""
     local current_status=""
 
+    # Helper: output a single source entry with discussion_status lookup
+    _emit_source() {
+        local name="$1"
+        local status="$2"
+        echo "      - name: \"$name\""
+        echo "        status: \"$status\""
+        if [ -n "$discussion_dir" ]; then
+            if [ -f "$discussion_dir/${name}.md" ]; then
+                local disc_status
+                disc_status=$(extract_field "$discussion_dir/${name}.md" "status")
+                echo "        discussion_status: \"${disc_status:-unknown}\""
+            else
+                echo "        discussion_status: \"not-found\""
+            fi
+        fi
+    }
+
     # Read frontmatter and parse sources block
     while IFS= read -r line; do
         # Detect start of sources block
@@ -69,8 +87,7 @@ extract_sources_with_status() {
         if $in_sources && [[ "$line" =~ ^[a-z_]+: ]] && [[ ! "$line" =~ ^[[:space:]] ]]; then
             # Output last source if pending
             if [ -n "$current_name" ]; then
-                echo "      - name: \"$current_name\""
-                echo "        status: \"${current_status:-incorporated}\""
+                _emit_source "$current_name" "${current_status:-incorporated}"
             fi
             break
         fi
@@ -80,8 +97,7 @@ extract_sources_with_status() {
             if [[ "$line" =~ ^[[:space:]]*-[[:space:]]*name:[[:space:]]*(.+)$ ]]; then
                 # Output previous source if exists
                 if [ -n "$current_name" ]; then
-                    echo "      - name: \"$current_name\""
-                    echo "        status: \"${current_status:-incorporated}\""
+                    _emit_source "$current_name" "${current_status:-incorporated}"
                 fi
                 current_name="${BASH_REMATCH[1]}"
                 current_name=$(echo "$current_name" | sed 's/^"//' | sed 's/"$//' | xargs)
@@ -96,8 +112,7 @@ extract_sources_with_status() {
 
     # Output last source if pending (end of frontmatter)
     if [ -n "$current_name" ]; then
-        echo "      - name: \"$current_name\""
-        echo "        status: \"${current_status:-incorporated}\""
+        _emit_source "$current_name" "${current_status:-incorporated}"
     fi
 }
 
@@ -165,7 +180,7 @@ if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
         fi
 
         # Extract sources with status (handles both old and new format)
-        sources_output=$(extract_sources_with_status "$file")
+        sources_output=$(extract_sources_with_status "$file" "$DISCUSSION_DIR")
         if [ -n "$sources_output" ]; then
             echo "    sources:"
             echo "$sources_output"
@@ -249,17 +264,56 @@ if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ];
     current_checksum=$(cat "$DISCUSSION_DIR"/*.md 2>/dev/null | md5sum | cut -d' ' -f1)
     echo "  discussions_checksum: \"$current_checksum\""
 
-    # Count concluded discussions
+    # Count discussions by status
+    discussion_count=0
     concluded_count=0
+    in_progress_count=0
     for file in "$DISCUSSION_DIR"/*.md; do
         [ -f "$file" ] || continue
+        discussion_count=$((discussion_count + 1))
         status=$(extract_field "$file" "status")
         if [ "$status" = "concluded" ]; then
             concluded_count=$((concluded_count + 1))
+        elif [ "$status" = "in-progress" ]; then
+            in_progress_count=$((in_progress_count + 1))
         fi
     done
-    echo "  concluded_discussion_count: $concluded_count"
+    echo "  discussion_count: $discussion_count"
+    echo "  concluded_count: $concluded_count"
+    echo "  in_progress_count: $in_progress_count"
+
+    # Count non-superseded specifications
+    spec_count=0
+    if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
+        for file in "$SPEC_DIR"/*.md; do
+            [ -f "$file" ] || continue
+            spec_status=$(extract_field "$file" "status")
+            if [ "$spec_status" != "superseded" ]; then
+                spec_count=$((spec_count + 1))
+            fi
+        done
+    fi
+    echo "  spec_count: $spec_count"
+
+    # Boolean helpers
+    echo "  has_discussions: true"
+    if [ "$concluded_count" -gt 0 ]; then
+        echo "  has_concluded: true"
+    else
+        echo "  has_concluded: false"
+    fi
+    if [ "$spec_count" -gt 0 ]; then
+        echo "  has_specs: true"
+    else
+        echo "  has_specs: false"
+    fi
 else
     echo "  discussions_checksum: null"
-    echo "  concluded_discussion_count: 0"
+    echo "  discussion_count: 0"
+    echo "  concluded_count: 0"
+    echo "  in_progress_count: 0"
+    echo "  spec_count: 0"
+    echo "  has_discussions: false"
+    echo "  has_concluded: false"
+    echo "  has_specs: false"
 fi

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

@@ -22,21 +22,25 @@ 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`:
 
-> **Analysis cycle {N} — this is beyond the standard 3 cycles.**
+**Do NOT skip analysis autonomously.** This gate is an escape hatch for the user — not a signal to stop. The expected default is to continue running analysis until no issues are found. Present the choice and let the user decide.
+
+> **Analysis cycle {N}**
+>
+> Analysis has run {N-1} times so far. You can continue (recommended if issues were still found last cycle) or skip to completion.
 >
 > · · · · · · · · · · · ·
+> - **`p`/`proceed`** — Continue analysis *(default)*
 > - **`s`/`skip`** — Skip analysis, proceed to completion
-> - **`p`/`proceed`** — Run analysis anyway
 > · · · · · · · · · · · ·
 
-**STOP.** Wait for user choice.
+**STOP.** Wait for user choice. You MUST NOT choose on the user's behalf.
 
-- **`skip`**: → Return to the skill for **Step 8**.
 - **`proceed`**: → Continue to **B. Git Checkpoint**.
-
-→ If `analysis_cycle <= 3`, proceed to **B. Git Checkpoint**.
+- **`skip`**: → Return to the skill for **Step 8**.
 
 ---