@leeovery/claude-technical-workflows 2.0.28 → 2.0.30

package/scripts/specification-discovery.sh

@@ -0,0 +1,210 @@
+#!/bin/bash
+#
+# discover-spec-state.sh
+#
+# Discovers the current state of discussions, specifications, and cache
+# for the workflow:start-specification command.
+#
+# Outputs structured YAML that the command can consume directly.
+#
+
+set -eo pipefail
+
+DISCUSSION_DIR="docs/workflow/discussion"
+SPEC_DIR="docs/workflow/specification"
+CACHE_FILE="docs/workflow/.cache/discussion-consolidation-analysis.md"
+
+# Helper: Extract a frontmatter field value from a file
+# Usage: extract_field <file> <field_name>
+extract_field() {
+    local file="$1"
+    local field="$2"
+    # Read until --- (end of frontmatter), find field, extract value
+    # Use grep -m1 and || true to handle no match gracefully
+    sed -n '/^---$/,/^---$/p' "$file" 2>/dev/null | \
+        grep -m1 "^${field}:" | \
+        sed "s/^${field}:[[:space:]]*//" || true
+}
+
+# Helper: Extract array field from frontmatter (returns space-separated values)
+# Usage: extract_array_field <file> <field_name>
+extract_array_field() {
+    local file="$1"
+    local field="$2"
+    local result
+    # Look for field followed by array items (- item), excluding --- delimiters
+    result=$(sed -n '/^---$/,/^---$/p' "$file" 2>/dev/null | \
+        grep -v "^---$" | \
+        sed -n "/^${field}:/,/^[a-z_]*:/p" | \
+        grep "^[[:space:]]*-" | \
+        sed 's/^[[:space:]]*-[[:space:]]*//' | \
+        tr '\n' ' ' | \
+        sed 's/[[:space:]]*$//' || true)
+    echo "$result"
+}
+
+# Start YAML output
+echo "# Specification Command State Discovery"
+echo "# Generated: $(date -Iseconds)"
+echo ""
+
+#
+# DISCUSSIONS
+#
+echo "discussions:"
+
+if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ]; then
+    for file in "$DISCUSSION_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        status=$(extract_field "$file" "status")
+        status=${status:-"unknown"}
+
+        # Check if this discussion has a corresponding individual spec
+        has_individual_spec="false"
+        if [ -f "$SPEC_DIR/${name}.md" ]; then
+            has_individual_spec="true"
+        fi
+
+        echo "  - name: \"$name\""
+        echo "    status: \"$status\""
+        echo "    has_individual_spec: $has_individual_spec"
+    done
+else
+    echo "  []  # No discussions found"
+fi
+
+echo ""
+
+#
+# SPECIFICATIONS
+#
+echo "specifications:"
+
+if [ -d "$SPEC_DIR" ] && [ -n "$(ls -A "$SPEC_DIR" 2>/dev/null)" ]; then
+    for file in "$SPEC_DIR"/*.md; do
+        [ -f "$file" ] || continue
+
+        name=$(basename "$file" .md)
+        status=$(extract_field "$file" "status")
+        status=${status:-"active"}
+
+        superseded_by=$(extract_field "$file" "superseded_by")
+        sources=$(extract_array_field "$file" "sources")
+
+        echo "  - name: \"$name\""
+        echo "    status: \"$status\""
+
+        if [ -n "$superseded_by" ]; then
+            echo "    superseded_by: \"$superseded_by\""
+        fi
+
+        if [ -n "$sources" ]; then
+            echo "    sources:"
+            for src in $sources; do
+                echo "      - \"$src\""
+            done
+        fi
+    done
+else
+    echo "  []  # No specifications found"
+fi
+
+echo ""
+
+#
+# CACHE STATE
+#
+echo "cache:"
+
+if [ -f "$CACHE_FILE" ]; then
+    echo "  exists: true"
+
+    cached_checksum=$(extract_field "$CACHE_FILE" "checksum")
+    cached_date=$(extract_field "$CACHE_FILE" "generated")
+
+    echo "  cached_checksum: \"${cached_checksum:-unknown}\""
+    echo "  cached_date: \"${cached_date:-unknown}\""
+
+    # Extract anchored names (groupings that have existing specs)
+    # These are the grouping names from the cache that have corresponding specs
+    echo "  anchored_names:"
+
+    # Parse the cache file for grouping names (### Name format)
+    # and check if a spec exists for each
+    anchored_found=false
+    while IFS= read -r grouping_name; do
+        # Clean the name (remove any trailing annotations, lowercase, spaces to hyphens)
+        clean_name=$(echo "$grouping_name" | sed 's/[[:space:]]*(.*)//' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+        if [ -f "$SPEC_DIR/${clean_name}.md" ]; then
+            echo "    - \"$clean_name\""
+            anchored_found=true
+        fi
+    done < <(grep "^### " "$CACHE_FILE" 2>/dev/null | sed 's/^### //' || true)
+
+    if [ "$anchored_found" = false ]; then
+        echo "    []  # No anchored names found"
+    fi
+else
+    echo "  exists: false"
+    echo "  cached_checksum: null"
+    echo "  cached_date: null"
+    echo "  anchored_names: []"
+fi
+
+echo ""
+
+#
+# CURRENT CHECKSUM
+#
+echo "current_state:"
+
+if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ]; then
+    # Compute checksum of all discussion files (deterministic via sorted glob)
+    current_checksum=$(cat "$DISCUSSION_DIR"/*.md 2>/dev/null | md5sum | cut -d' ' -f1)
+    echo "  discussions_checksum: \"$current_checksum\""
+
+    # Count concluded discussions
+    concluded_count=0
+    for file in "$DISCUSSION_DIR"/*.md; do
+        [ -f "$file" ] || continue
+        status=$(extract_field "$file" "status")
+        if [ "$status" = "concluded" ]; then
+            concluded_count=$((concluded_count + 1))
+        fi
+    done
+    echo "  concluded_discussion_count: $concluded_count"
+else
+    echo "  discussions_checksum: null"
+    echo "  concluded_discussion_count: 0"
+fi
+
+echo ""
+
+#
+# CHECKSUM COMPARISON
+#
+echo "cache_validity:"
+
+if [ -f "$CACHE_FILE" ]; then
+    cached_checksum=$(extract_field "$CACHE_FILE" "checksum")
+
+    if [ -d "$DISCUSSION_DIR" ] && [ -n "$(ls -A "$DISCUSSION_DIR" 2>/dev/null)" ]; then
+        current_checksum=$(cat "$DISCUSSION_DIR"/*.md 2>/dev/null | md5sum | cut -d' ' -f1)
+
+        if [ "$cached_checksum" = "$current_checksum" ]; then
+            echo "  is_valid: true"
+            echo "  reason: \"checksums match\""
+        else
+            echo "  is_valid: false"
+            echo "  reason: \"discussions have changed since cache was generated\""
+        fi
+    else
+        echo "  is_valid: false"
+        echo "  reason: \"no discussions to compare\""
+    fi
+else
+    echo "  is_valid: false"
+    echo "  reason: \"no cache exists\""
+fi

package/skills/technical-specification/SKILL.md

@@ -38,6 +38,18 @@ Either way: Transform unvalidated reference material into a specification that's
 
 **When complete**: User signs off on the specification.
 
+### Post-Completion: Handle Source Specifications
+
+If any of your sources were **existing specifications** (as opposed to discussions, research, or other reference material), these have now been consolidated into the new specification.
+
+After user signs off:
+1. Mark each source specification as superseded by updating its frontmatter:
+   ```yaml
+   status: superseded
+   superseded_by: {new-specification-name}
+   ```
+2. Inform the user which files were updated
+
 ## CRITICAL: You Do NOT Create or Update the Specification Autonomously
 
 **This is a collaborative, interactive process. You MUST wait for explicit user approval before writing ANYTHING to the specification file.**

package/commands/start-discussion.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-discussion instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-discussion` is deprecated.** Use `/workflow:start-discussion` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-discussion`...**
-
-Run the `/workflow:start-discussion` command now.

package/commands/start-implementation.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-implementation instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-implementation` is deprecated.** Use `/workflow:start-implementation` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-implementation`...**
-
-Run the `/workflow:start-implementation` command now.

package/commands/start-planning.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-planning instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-planning` is deprecated.** Use `/workflow:start-planning` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-planning`...**
-
-Run the `/workflow:start-planning` command now.

package/commands/start-research.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-research instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-research` is deprecated.** Use `/workflow:start-research` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-research`...**
-
-Run the `/workflow:start-research` command now.

package/commands/start-specification.md

@@ -1,15 +0,0 @@
----
-description: "[DEPRECATED] Use /workflow:start-specification instead"
----
-
-# Deprecated Command
-
-⚠️ **`/start-specification` is deprecated.** Use `/workflow:start-specification` instead.
-
-The command has been renamed to use the `workflow:` prefix to distinguish workflow commands from standalone commands.
-
----
-
-**Forwarding to `/workflow:start-specification`...**
-
-Run the `/workflow:start-specification` command now.

package/commands/workflow:start-specification.md

@@ -1,304 +0,0 @@
----
-description: Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill.
----
-
-Invoke the **technical-specification** skill for this conversation.
-
-## Workflow Context
-
-This is **Phase 3** of the six-phase workflow:
-
-| Phase | Focus | You |
-|-------|-------|-----|
-| 1. Research | EXPLORE - ideas, feasibility, market, business | |
-| 2. Discussion | WHAT and WHY - decisions, architecture, edge cases | |
-| **3. Specification** | REFINE - validate into standalone spec | ◀ HERE |
-| 4. Planning | HOW - phases, tasks, acceptance criteria | |
-| 5. Implementation | DOING - tests first, then code | |
-| 6. Review | VALIDATING - check work against artifacts | |
-
-**Stay in your lane**: Validate and refine discussion content into standalone specifications. Don't jump to planning, phases, tasks, or code. The specification is the "line in the sand" - everything after this has hard dependencies on it.
-
----
-
-## Instructions
-
-Follow these steps EXACTLY as written. Do not skip steps or combine them. Present output using the EXACT format shown in examples - do not simplify or alter the formatting.
-
-Before beginning, discover existing work and gather necessary information.
-
-## Important
-
-Use simple, individual commands. Never combine multiple operations into bash loops or one-liners. Execute commands one at a time.
-
-## Step 1: Discover Existing Work
-
-Scan the codebase for discussions and specifications:
-
-1. **Find discussions**: Look in `docs/workflow/discussion/`
-   - Run `ls docs/workflow/discussion/` to list discussion files
-   - Each file is named `{topic}.md`
-
-2. **Check discussion status**: For each discussion file
-   - Run `head -20 docs/workflow/discussion/{topic}.md` to read the frontmatter and extract the `status:` field
-   - Do NOT use bash loops - run separate `head` commands for each topic
-
-3. **Check for existing specifications**: Look in `docs/workflow/specification/`
-   - Identify discussions that don't have corresponding specifications
-
-4. **Check for cached consolidation analysis** (if multiple discussions):
-   - Check if `docs/workflow/.cache/discussion-consolidation-analysis.md` exists
-   - If it exists, read it to get the stored checksum from the frontmatter
-
-5. **Compute current discussions checksum** (if multiple concluded discussions):
-   - Run exactly: `cat docs/workflow/discussion/*.md 2>/dev/null | md5sum | cut -d' ' -f1`
-   - IMPORTANT: Use this exact command - glob expansion is alphabetically sorted by default
-   - Do NOT modify or "simplify" this command - checksum must be deterministic
-   - Store this value to compare with the cached checksum
-
-## Step 2: Check Prerequisites
-
-**If no discussions exist:**
-
-```
-No discussions found in docs/workflow/discussion/
-
-The specification phase requires a completed discussion. Please run /workflow:start-discussion first to document the technical decisions, edge cases, and rationale before creating a specification.
-```
-
-Stop here and wait for the user to acknowledge.
-
-## Step 3: Present Options
-
-Show what you found:
-
-```
-Discussions found:
-  {topic-1} - Concluded - ready for specification
-  {topic-2} - Exploring - not ready for specification
-  {topic-3} - Concluded - specification exists
-```
-
-**Important:** Only concluded discussions should proceed to specification. If a discussion is still exploring, advise the user to complete the discussion phase first.
-
-**If only ONE concluded discussion is ready:** Skip to Step 4 (single-source path).
-
-**If MORE THAN ONE concluded discussion is ready:** Proceed to Step 3A (consolidation assessment).
-
----
-
-## Step 3A: Consolidation Assessment (Multiple Discussions)
-
-When multiple concluded discussions exist, offer to assess how they should be organized into specifications.
-
-```
-You have {N} concluded discussions ready for specification.
-
-Would you like me to assess how these might be combined into specifications?
-
-1. **Yes, assess them** - I'll analyze all discussions for natural groupings
-2. **No, proceed individually** - Create specifications 1:1 with discussions
-
-Which approach?
-```
-
-**If user chooses individual:** Skip to Step 4 and ask which discussion to specify.
-
-**If user chooses assessment:** Proceed to Step 3A.1.
-
-### Step 3A.1: Gather Context for Analysis
-
-Before analyzing, ask:
-
-```
-Before I analyze the discussions, is there anything about your project structure or how these topics relate that would help me group them appropriately?
-```
-
-Wait for response.
-
-### Step 3A.2: Check Cache Validity
-
-Compare the current discussions checksum (computed in Step 1.5) with the cached checksum:
-
-**If cache exists AND checksums match:**
-```
-Using cached analysis
-
-Discussion documents unchanged since last analysis ({date from cache}).
-Loading previously identified groupings...
-
-To force a fresh analysis, enter: refresh
-```
-
-Then load the groupings from the cache file and skip to Step 3A.4 (Present Options).
-
-**If cache missing OR checksums differ:**
-```
-Analyzing discussions...
-```
-
-Proceed to Step 3A.3 (Full Analysis).
-
-### Step 3A.3: Full Analysis (when cache invalid)
-
-**This step is critical. You MUST read every concluded discussion document thoroughly.**
-
-For each concluded discussion:
-1. Read the ENTIRE document (not just frontmatter)
-2. Understand the decisions, systems, and concepts it defines
-3. Note dependencies on or references to other discussions
-4. Identify shared data structures, entities, or behaviors
-
-Then analyze coupling between discussions:
-- **Data coupling**: Discussions that define or depend on the same data structures
-- **Behavioral coupling**: Discussions where one's implementation requires another
-- **Conceptual coupling**: Discussions that address different facets of the same problem
-
-Group discussions that are tightly coupled - they should become a single specification because their decisions are inseparable.
-
-**Save to cache:**
-After analysis, ensure `.cache` directory exists: `mkdir -p docs/workflow/.cache`
-
-Create/update `docs/workflow/.cache/discussion-consolidation-analysis.md`:
-
-```markdown
----
-checksum: {computed_checksum}
-generated: {ISO date}
-discussion_files:
-  - {topic1}.md
-  - {topic2}.md
----
-
-# Discussion Consolidation Analysis
-
-## Recommended Groupings
-
-### {Suggested Specification Name}
-- **{topic-a}**: {why it belongs in this group}
-- **{topic-b}**: {why it belongs in this group}
-- **{topic-c}**: {why it belongs in this group}
-
-**Coupling**: {Brief explanation of what binds these together - shared data, dependencies, etc.}
-
-### {Another Specification Name}
-- **{topic-d}**: {why it belongs}
-- **{topic-e}**: {why it belongs}
-
-**Coupling**: {Brief explanation}
-
-## Independent Discussions
-- **{topic-f}**: {Why this stands alone - no strong coupling to others}
-
-## Analysis Notes
-{Any additional context about the relationships discovered}
-```
-
-### Step 3A.4: Present Options
-
-Present the analysis and options:
-
-**If using cached analysis:**
-```
-Cached analysis (discussions unchanged since {date})
-
-{Display the Recommended Groupings section from cache}
-
-How would you like to proceed?
-
-1. **Combine as recommended** - Create specifications per the groupings above
-2. **Combine differently** - Tell me your preferred groupings
-3. **Single specification** - Consolidate all discussions into one spec
-4. **Individual specifications** - Create 1:1 (I'll ask which to start with)
-
-(Or enter 'refresh' to re-analyze)
-```
-
-**If fresh analysis:**
-```
-Analysis complete (cached for future sessions)
-
-{Display the Recommended Groupings section}
-
-How would you like to proceed?
-
-1. **Combine as recommended** - Create specifications per the groupings above
-2. **Combine differently** - Tell me your preferred groupings
-3. **Single specification** - Consolidate all discussions into one spec
-4. **Individual specifications** - Create 1:1 (I'll ask which to start with)
-```
-
-Wait for user to choose.
-
-### Step 3A.5: Handle Choices
-
-**If "Combine as recommended":**
-- Confirm the first specification to create
-- Proceed to Step 4 with the grouped sources
-
-**If "Combine differently":**
-- Ask user to describe their preferred groupings
-- Confirm understanding
-- Proceed to Step 4 with user-specified sources
-
-**If "Single specification":**
-- Use "unified" as the specification name (output: `docs/workflow/specification/unified.md`)
-- Proceed to Step 4 with all discussions as sources
-
-**If "Individual specifications":**
-- Ask which discussion to specify first
-- Proceed to Step 4 with single source
-
-**If "refresh":**
-- Delete the cache file: `rm docs/workflow/.cache/discussion-consolidation-analysis.md`
-- Return to Step 3A.3 (Full Analysis)
-- Inform user: "Refreshing analysis..."
-
----
-
-## Step 4: Gather Additional Context
-
-Ask:
-- Any additional context or priorities to consider?
-- Any constraints or changes since the discussion(s) concluded?
-- Are there any existing partial plans or related documentation I should review?
-
-## Step 5: Invoke the Skill
-
-After completing the steps above, this command's purpose is fulfilled.
-
-Invoke the [technical-specification](../skills/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.
-
-**Example handoff (single source):**
-```
-Specification session for: {topic}
-Source: docs/workflow/discussion/{topic}.md
-Output: docs/workflow/specification/{topic}.md
-Additional context: {summary of user's answers from Step 4}
-
-Invoke the technical-specification skill.
-```
-
-**Example handoff (multiple sources):**
-```
-Specification session for: {specification-name}
-
-Sources:
-- docs/workflow/discussion/{topic-1}.md
-- docs/workflow/discussion/{topic-2}.md
-- docs/workflow/discussion/{topic-3}.md
-
-Output: docs/workflow/specification/{specification-name}.md
-Additional context: {summary of user's answers from Step 4}
-
-Invoke the technical-specification skill.
-```
-
----
-
-## Notes
-
-- Ask questions clearly and wait for responses before proceeding
-- The specification phase validates and refines discussion content into standalone documents
-- When multiple sources are provided, the skill will extract exhaustively from ALL of them
-- Attribution in the specification should trace content back to its source discussion(s)