@stephen-lord/docs 1.0.0

package/dist/claude-code-settings/plugins/spec-kit-skill/skills/spec-kit-skill/helpers/detection-logic.md

@@ -0,0 +1,460 @@
+# Spec-Kit Detection Logic
+
+Comprehensive detection algorithms for determining project state and guiding users through the spec-kit workflow.
+
+## 1. CLI Installation Detection
+
+Check if the `specify` CLI is installed on the system.
+
+### Method 1: Command Check
+
+```bash
+if command -v specify &> /dev/null; then
+  echo "CLI installed via PATH"
+  specify --version
+  exit 0
+fi
+```
+
+### Method 2: Direct Path Check
+
+```bash
+if [ -x "$HOME/.local/bin/specify" ]; then
+  echo "CLI installed in ~/.local/bin"
+  "$HOME/.local/bin/specify" --version
+  exit 0
+fi
+```
+
+### Method 3: UV Tool Check
+
+```bash
+if command -v uv &> /dev/null; then
+  if uv tool list | grep -q "specify-cli"; then
+    echo "CLI installed via uv tool"
+    uv tool run specify --version
+    exit 0
+  fi
+fi
+```
+
+### Combined Detection Function
+
+```bash
+detect_cli() {
+  # Check command
+  if command -v specify &> /dev/null; then
+    echo "installed"
+    return 0
+  fi
+
+  # Check local bin
+  if [ -x "$HOME/.local/bin/specify" ]; then
+    echo "installed"
+    return 0
+  fi
+
+  # Check uv tool
+  if command -v uv &> /dev/null && uv tool list 2>/dev/null | grep -q "specify-cli"; then
+    echo "installed"
+    return 0
+  fi
+
+  echo "not_installed"
+  return 1
+}
+```
+
+### Installation Guidance
+
+If CLI not detected, guide user:
+
+```markdown
+The spec-kit CLI is not installed. To install:
+
+**Persistent installation (recommended):**
+```bash
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
+```
+
+**One-time usage:**
+```bash
+uvx --from git+https://github.com/github/spec-kit.git specify init .
+```
+
+**Requirements:**
+- Python 3.11+
+- Git
+- uv package manager (install from https://docs.astral.sh/uv/)
+```
+
+## 2. Project Initialization Detection
+
+Check if current project is initialized with spec-kit.
+
+### Primary Indicators
+
+```bash
+check_initialization() {
+  # Must have .specify directory
+  if [ ! -d ".specify" ]; then
+    echo "not_initialized"
+    return 1
+  fi
+
+  # Must have constitution
+  if [ ! -f ".specify/memory/constitution.md" ]; then
+    echo "partially_initialized"
+    return 2
+  fi
+
+  # Must have scripts
+  if [ ! -d ".specify/scripts/bash" ]; then
+    echo "partially_initialized"
+    return 2
+  fi
+
+  # Must have templates
+  if [ ! -d ".specify/templates" ]; then
+    echo "partially_initialized"
+    return 2
+  fi
+
+  echo "initialized"
+  return 0
+}
+```
+
+### Initialization Guidance
+
+If not initialized:
+
+```bash
+# Initialize in current directory
+specify init . --ai claude
+
+# Initialize new project
+specify init <project-name> --ai claude
+
+# Options:
+# --force: Overwrite non-empty directories
+# --no-git: Skip Git initialization
+# --script ps: Generate PowerShell scripts (Windows)
+```
+
+## 3. Feature Detection
+
+Identify existing features and latest feature.
+
+### List All Features
+
+```bash
+list_features() {
+  if [ ! -d ".specify/specs" ]; then
+    echo "No features found"
+    return 1
+  fi
+
+  # List numbered feature directories
+  ls -d .specify/specs/[0-9]* 2>/dev/null | sort -V
+}
+```
+
+### Get Latest Feature
+
+```bash
+get_latest_feature() {
+  LATEST=$(ls -d .specify/specs/[0-9]* 2>/dev/null | sort -V | tail -1)
+
+  if [ -z "$LATEST" ]; then
+    echo "No features found"
+    return 1
+  fi
+
+  echo "$LATEST"
+  return 0
+}
+```
+
+### Extract Feature Name
+
+```bash
+get_feature_name() {
+  FEATURE_DIR="$1"
+
+  # Extract from directory name (e.g., 001-feature-name -> feature-name)
+  basename "$FEATURE_DIR" | sed 's/^[0-9]\{3\}-//'
+}
+```
+
+### Extract Feature Number
+
+```bash
+get_feature_number() {
+  FEATURE_DIR="$1"
+
+  # Extract number (e.g., 001-feature-name -> 001)
+  basename "$FEATURE_DIR" | grep -o '^[0-9]\{3\}'
+}
+```
+
+## 4. Phase Detection
+
+Determine current phase of development for a feature.
+
+### Comprehensive Phase Detection
+
+```bash
+detect_phase() {
+  FEATURE_DIR="$1"
+
+  # Phase 1: Constitution
+  if [ ! -f ".specify/memory/constitution.md" ]; then
+    echo "constitution"
+    return 0
+  fi
+
+  # Phase 2: Specify
+  if [ ! -d "$FEATURE_DIR" ] || [ ! -f "$FEATURE_DIR/spec.md" ]; then
+    echo "specify"
+    return 0
+  fi
+
+  # Phase 3: Clarify
+  # Check if spec has clarifications section
+  if ! grep -q "## Clarifications" "$FEATURE_DIR/spec.md" 2>/dev/null; then
+    echo "clarify"
+    return 0
+  fi
+
+  # Phase 4: Plan
+  if [ ! -f "$FEATURE_DIR/plan.md" ]; then
+    echo "plan"
+    return 0
+  fi
+
+  # Phase 5: Tasks
+  if [ ! -f "$FEATURE_DIR/tasks.md" ]; then
+    echo "tasks"
+    return 0
+  fi
+
+  # Phase 6/7: Analyze or Implement
+  # Check if there are uncompleted tasks
+  if grep -q "\\- \\[ \\]" "$FEATURE_DIR/tasks.md" 2>/dev/null; then
+    echo "implement"
+    return 0
+  fi
+
+  # All tasks complete
+  echo "complete"
+  return 0
+}
+```
+
+### Phase-Specific Checks
+
+#### Check Constitution Exists
+
+```bash
+has_constitution() {
+  [ -f ".specify/memory/constitution.md" ]
+}
+```
+
+#### Check Specification Exists
+
+```bash
+has_specification() {
+  FEATURE_DIR="$1"
+  [ -f "$FEATURE_DIR/spec.md" ]
+}
+```
+
+#### Check Clarifications Present
+
+```bash
+has_clarifications() {
+  FEATURE_DIR="$1"
+  grep -q "## Clarifications" "$FEATURE_DIR/spec.md" 2>/dev/null
+}
+```
+
+#### Check Plan Exists
+
+```bash
+has_plan() {
+  FEATURE_DIR="$1"
+  [ -f "$FEATURE_DIR/plan.md" ]
+}
+```
+
+#### Check Tasks Exist
+
+```bash
+has_tasks() {
+  FEATURE_DIR="$1"
+  [ -f "$FEATURE_DIR/tasks.md" ]
+}
+```
+
+#### Get Incomplete Tasks
+
+```bash
+get_incomplete_tasks() {
+  FEATURE_DIR="$1"
+
+  if [ ! -f "$FEATURE_DIR/tasks.md" ]; then
+    return 1
+  fi
+
+  # Find uncompleted tasks (- [ ])
+  grep -n "\\- \\[ \\]" "$FEATURE_DIR/tasks.md"
+}
+```
+
+#### Get Completed Tasks Count
+
+```bash
+count_completed_tasks() {
+  FEATURE_DIR="$1"
+
+  if [ ! -f "$FEATURE_DIR/tasks.md" ]; then
+    echo "0"
+    return
+  fi
+
+  # Count completed tasks (- [x])
+  grep -c "\\- \\[x\\]" "$FEATURE_DIR/tasks.md" 2>/dev/null || echo "0"
+}
+```
+
+#### Get Total Tasks Count
+
+```bash
+count_total_tasks() {
+  FEATURE_DIR="$1"
+
+  if [ ! -f "$FEATURE_DIR/tasks.md" ]; then
+    echo "0"
+    return
+  fi
+
+  # Count all tasks (- [ ] or - [x])
+  grep -c "\\- \\[" "$FEATURE_DIR/tasks.md" 2>/dev/null || echo "0"
+}
+```
+
+## 5. Complete Status Report
+
+Generate comprehensive status report:
+
+```bash
+generate_status_report() {
+  echo "=== Spec-Kit Status Report ==="
+  echo
+
+  # CLI Status
+  echo "CLI Installation:"
+  CLI_STATUS=$(detect_cli)
+  echo "  Status: $CLI_STATUS"
+  if [ "$CLI_STATUS" = "installed" ]; then
+    specify --version 2>/dev/null | sed 's/^/  /'
+  fi
+  echo
+
+  # Project Status
+  echo "Project Initialization:"
+  INIT_STATUS=$(check_initialization)
+  echo "  Status: $INIT_STATUS"
+  echo
+
+  # Constitution Status
+  if has_constitution; then
+    echo "Constitution: ✓ Present"
+  else
+    echo "Constitution: ✗ Missing (run Phase 1)"
+  fi
+  echo
+
+  # Features
+  echo "Features:"
+  FEATURES=$(list_features)
+  if [ -z "$FEATURES" ]; then
+    echo "  No features found"
+  else
+    echo "$FEATURES" | while read -r FEATURE; do
+      FEATURE_NAME=$(get_feature_name "$FEATURE")
+      FEATURE_NUM=$(get_feature_number "$FEATURE")
+      PHASE=$(detect_phase "$FEATURE")
+
+      echo "  [$FEATURE_NUM] $FEATURE_NAME"
+      echo "      Phase: $PHASE"
+
+      if [ "$PHASE" = "implement" ] || [ "$PHASE" = "complete" ]; then
+        COMPLETED=$(count_completed_tasks "$FEATURE")
+        TOTAL=$(count_total_tasks "$FEATURE")
+        echo "      Tasks: $COMPLETED/$TOTAL completed"
+      fi
+    done
+  fi
+  echo
+
+  # Current Phase Guidance
+  LATEST=$(get_latest_feature)
+  if [ -n "$LATEST" ]; then
+    CURRENT_PHASE=$(detect_phase "$LATEST")
+    echo "Next Action: Phase $CURRENT_PHASE"
+  elif has_constitution; then
+    echo "Next Action: Create first feature (Phase 2: specify)"
+  else
+    echo "Next Action: Create constitution (Phase 1)"
+  fi
+}
+```
+
+## Usage Examples
+
+### Check and Guide User
+
+```bash
+# Detect state and provide guidance
+CLI_STATUS=$(detect_cli)
+
+if [ "$CLI_STATUS" = "not_installed" ]; then
+  echo "Please install spec-kit CLI first:"
+  echo "uv tool install specify-cli --from git+https://github.com/github/spec-kit.git"
+  exit 1
+fi
+
+INIT_STATUS=$(check_initialization)
+
+if [ "$INIT_STATUS" != "initialized" ]; then
+  echo "Please initialize project:"
+  echo "specify init . --ai claude"
+  exit 1
+fi
+
+# Generate status report
+generate_status_report
+```
+
+### Determine Next Action
+
+```bash
+# Automatically determine what to do next
+LATEST=$(get_latest_feature)
+
+if [ -z "$LATEST" ]; then
+  if has_constitution; then
+    echo "Ready to create first feature"
+    echo "Run: .specify/scripts/bash/create-new-feature.sh --json 'feature-name'"
+  else
+    echo "Need to create constitution first"
+  fi
+else
+  PHASE=$(detect_phase "$LATEST")
+  echo "Current phase: $PHASE"
+  echo "Continue with phase $PHASE for feature: $(get_feature_name "$LATEST")"
+fi
+```

package/dist/claude-code-settings/plugins/spec-kit-skill/skills/spec-kit-skill/scripts/detect-phase.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+
+# Spec-Kit Phase Detection Script
+# Determines the current phase of a spec-kit feature
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Function to detect CLI installation
+detect_cli() {
+  if command -v specify &> /dev/null; then
+    return 0
+  fi
+
+  if [ -x "$HOME/.local/bin/specify" ]; then
+    return 0
+  fi
+
+  return 1
+}
+
+# Function to check project initialization
+check_initialization() {
+  if [ ! -d ".specify" ]; then
+    return 1
+  fi
+
+  if [ ! -f ".specify/memory/constitution.md" ]; then
+    return 2
+  fi
+
+  return 0
+}
+
+# Function to get latest feature
+get_latest_feature() {
+  ls -d .specify/specs/[0-9]* 2>/dev/null | sort -V | tail -1
+}
+
+# Function to detect phase for a feature
+detect_phase() {
+  local feature_dir="$1"
+
+  # Phase 1: Constitution
+  if [ ! -f ".specify/memory/constitution.md" ]; then
+    echo "constitution"
+    return 0
+  fi
+
+  # Phase 2: Specify
+  if [ ! -d "$feature_dir" ] || [ ! -f "$feature_dir/spec.md" ]; then
+    echo "specify"
+    return 0
+  fi
+
+  # Phase 3: Clarify
+  if ! grep -q "## Clarifications" "$feature_dir/spec.md" 2>/dev/null; then
+    echo "clarify"
+    return 0
+  fi
+
+  # Phase 4: Plan
+  if [ ! -f "$feature_dir/plan.md" ]; then
+    echo "plan"
+    return 0
+  fi
+
+  # Phase 5: Tasks
+  if [ ! -f "$feature_dir/tasks.md" ]; then
+    echo "tasks"
+    return 0
+  fi
+
+  # Phase 6/7: Analyze or Implement
+  if grep -q "\\- \\[ \\]" "$feature_dir/tasks.md" 2>/dev/null; then
+    echo "implement"
+    return 0
+  fi
+
+  echo "complete"
+  return 0
+}
+
+# Function to count tasks
+count_tasks() {
+  local feature_dir="$1"
+  local pattern="$2"
+
+  if [ ! -f "$feature_dir/tasks.md" ]; then
+    echo "0"
+    return
+  fi
+
+  grep -c "$pattern" "$feature_dir/tasks.md" 2>/dev/null || echo "0"
+}
+
+# Function to generate status report
+generate_report() {
+  echo -e "${BLUE}=== Spec-Kit Status ===${NC}"
+  echo
+
+  # CLI Check
+  if detect_cli; then
+    echo -e "${GREEN}✓${NC} CLI installed"
+    if command -v specify &> /dev/null; then
+      specify --version 2>/dev/null | sed 's/^/  /'
+    fi
+  else
+    echo -e "${RED}✗${NC} CLI not installed"
+    echo -e "  ${YELLOW}Install:${NC} uv tool install specify-cli --from git+https://github.com/github/spec-kit.git"
+  fi
+  echo
+
+  # Initialization Check
+  if check_initialization; then
+    echo -e "${GREEN}✓${NC} Project initialized"
+  else
+    echo -e "${RED}✗${NC} Project not initialized"
+    echo -e "  ${YELLOW}Initialize:${NC} specify init . --ai claude"
+    return 1
+  fi
+  echo
+
+  # Constitution Check
+  if [ -f ".specify/memory/constitution.md" ]; then
+    echo -e "${GREEN}✓${NC} Constitution present"
+  else
+    echo -e "${YELLOW}⚠${NC} Constitution missing"
+    echo -e "  ${YELLOW}Next:${NC} Create constitution (Phase 1)"
+    return 0
+  fi
+  echo
+
+  # Features
+  local features
+  features=$(ls -d .specify/specs/[0-9]* 2>/dev/null | sort -V || echo "")
+
+  if [ -z "$features" ]; then
+    echo -e "${YELLOW}No features found${NC}"
+    echo -e "  ${YELLOW}Next:${NC} Create first feature"
+    echo -e "  ${BLUE}Command:${NC} .specify/scripts/bash/create-new-feature.sh --json 'feature-name'"
+    return 0
+  fi
+
+  echo -e "${BLUE}Features:${NC}"
+  echo "$features" | while read -r feature; do
+    local feature_name
+    feature_name=$(basename "$feature" | sed 's/^[0-9]\{3\}-//')
+    local feature_num
+    feature_num=$(basename "$feature" | grep -o '^[0-9]\{3\}')
+    local phase
+    phase=$(detect_phase "$feature")
+
+    echo -e "  ${GREEN}[$feature_num]${NC} $feature_name"
+    echo -e "      Phase: ${YELLOW}$phase${NC}"
+
+    if [ "$phase" = "implement" ] || [ "$phase" = "complete" ]; then
+      local completed
+      completed=$(count_tasks "$feature" "\\- \\[x\\]")
+      local total
+      total=$(count_tasks "$feature" "\\- \\[")
+      local percentage=0
+      if [ "$total" -gt 0 ]; then
+        percentage=$((completed * 100 / total))
+      fi
+      echo -e "      Tasks: ${GREEN}$completed${NC}/${BLUE}$total${NC} ($percentage%)"
+    fi
+  done
+  echo
+
+  # Next Action
+  local latest
+  latest=$(get_latest_feature)
+  if [ -n "$latest" ]; then
+    local current_phase
+    current_phase=$(detect_phase "$latest")
+    local feature_name
+    feature_name=$(basename "$latest" | sed 's/^[0-9]\{3\}-//')
+    echo -e "${BLUE}Next Action:${NC} Continue with ${YELLOW}$current_phase${NC} phase for feature '${GREEN}$feature_name${NC}'"
+  fi
+}
+
+# Main execution
+main() {
+  local json_output=false
+  local feature_dir=""
+
+  # Parse arguments
+  while [[ $# -gt 0 ]]; do
+    case $1 in
+      --json)
+        json_output=true
+        shift
+        ;;
+      --feature)
+        feature_dir="$2"
+        shift 2
+        ;;
+      --help|-h)
+        echo "Usage: $0 [OPTIONS]"
+        echo
+        echo "Options:"
+        echo "  --json            Output in JSON format"
+        echo "  --feature DIR     Check specific feature directory"
+        echo "  --help, -h        Show this help message"
+        exit 0
+        ;;
+      *)
+        echo "Unknown option: $1"
+        exit 1
+        ;;
+    esac
+  done
+
+  # If feature specified, just detect its phase
+  if [ -n "$feature_dir" ]; then
+    local phase
+    phase=$(detect_phase "$feature_dir")
+
+    if [ "$json_output" = true ]; then
+      echo "{\"phase\": \"$phase\", \"feature_dir\": \"$feature_dir\"}"
+    else
+      echo "$phase"
+    fi
+    exit 0
+  fi
+
+  # Otherwise, generate full report
+  if [ "$json_output" = true ]; then
+    # JSON output
+    local cli_installed="false"
+    detect_cli && cli_installed="true"
+
+    local project_initialized="false"
+    check_initialization && project_initialized="true"
+
+    local latest
+    latest=$(get_latest_feature)
+    local current_phase="none"
+    if [ -n "$latest" ]; then
+      current_phase=$(detect_phase "$latest")
+    fi
+
+    echo "{"
+    echo "  \"cli_installed\": $cli_installed,"
+    echo "  \"project_initialized\": $project_initialized,"
+    echo "  \"latest_feature\": \"$latest\","
+    echo "  \"current_phase\": \"$current_phase\""
+    echo "}"
+  else
+    # Human-readable output
+    generate_report
+  fi
+}
+
+# Run main function
+main "$@"