codexspec 0.5.20__tar.gz → 0.6.0__tar.gz

{codexspec-0.5.20 → codexspec-0.6.0}/.gitignore

@@ -17,6 +17,9 @@
 .codexspec/memory/*
 !.codexspec/memory/constitution.md
 
+# Promotion content archive (local drafts, not meant for the repo)
+promotion-posts.md
+
 
 
 # Created by https://www.toptal.com/developers/gitignore/api/macos,windows,linux,python,powershell,git

{codexspec-0.5.20 → codexspec-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codexspec
-Version: 0.5.20
+Version: 0.6.0
 Summary: CodexSpec - A Spec-Driven Development (SDD) toolkit for Claude Code
 Project-URL: Homepage, https://github.com/Zts0hg/codexspec
 Project-URL: Repository, https://github.com/Zts0hg/codexspec
@@ -102,7 +102,7 @@ Why use CodexSpec on top of Claude Code? Here's the comparison:
 
 ```
 Traditional:  Idea → Code → Debug → Rewrite
-SDD:          Idea → Spec → Plan → Tasks → Code
+SDD:          Idea → Confirmed Requirements → Spec → Plan → Tasks → Code
 ```
 
 **Why use SDD?**
@@ -120,9 +120,9 @@ SDD:          Idea → Spec → Plan → Tasks → Code
 ### Core Workflow
 
 - **Constitution-Based Development** - Establish project principles that guide all decisions
-- **Two-Phase Specification** - Interactive clarification (`/specify`) followed by document generation (`/generate-spec`)
-- **Automatic Reviews** - Every artifact includes built-in quality checks
-- **TDD-Ready Tasks** - Task breakdowns enforce test-first methodology
+- **Persistent Requirement Capture** - `/specify` records confirmed discussion in `requirements.md` before document generation
+- **Automatic Reviews** - Every generated spec, plan, and task artifact includes built-in quality checks
+- **Traceable Tasks** - Task breakdowns preserve requirement and plan coverage, applying test-first only where required
 
 ### Human-AI Collaboration
 
@@ -160,14 +160,14 @@ CodexSpec is built on the belief that **effective AI-assisted development requir
 CodexSpec structures development into **reviewable checkpoints**:
 
 ```
-Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /implement
-                         │                  │                │
-                    Review spec        Review plan      Review tasks
-                         │                  │                │
-                      ✅ Human            ✅ Human          ✅ Human
+Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
+                                                   │                         │                            │
+                                              Review spec               Review plan                  Review tasks
 ```
 
-**Every artifact has a corresponding review command:**
+Confirmed requirements are the highest-priority feature authority. Derived artifacts carry explicit source links so conflicts can be traced back instead of silently propagated.
+
+**Every generated artifact has a corresponding review command:**
 
 - `spec.md` → `/codexspec:review-spec`
 - `plan.md` → `/codexspec:review-plan`
@@ -346,11 +346,9 @@ The config command will guide you through:
 CodexSpec breaks development into **reviewable checkpoints**:
 
 ```
-Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /implement
-                         │                  │                │
-                    Review spec        Review plan      Review tasks
-                         │                  │                │
-                      ✅ Human            ✅ Human          ✅ Human
+Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
+                                                   │                         │                            │
+                                              Review spec               Review plan                  Review tasks
 ```
 
 ### Workflow Steps
@@ -358,7 +356,7 @@ Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /i
 | Step                         | Command                      | Output                      | Human Check |
 | ---------------------------- | ---------------------------- | --------------------------- | ----------- |
 | 1. Project Principles        | `/codexspec:constitution`    | `constitution.md`           | ✅           |
-| 2. Requirement Clarification | `/codexspec:specify`         | None (interactive dialogue) | ✅           |
+| 2. Requirement Clarification | `/codexspec:specify`         | `requirements.md`           | ✅           |
 | 3. Generate Spec             | `/codexspec:generate-spec`   | `spec.md` + auto-review     | ✅           |
 | 4. Technical Planning        | `/codexspec:spec-to-plan`    | `plan.md` + auto-review     | ✅           |
 | 5. Task Breakdown            | `/codexspec:plan-to-tasks`   | `tasks.md` + auto-review    | ✅           |
@@ -369,15 +367,15 @@ Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /i
 
 | Aspect | `/codexspec:specify` | `/codexspec:clarify` |
 |--------|----------------------|----------------------|
-| **Purpose** | Initial requirement exploration | Refine existing spec |
-| **When to Use** | No spec.md exists yet | spec.md needs improvement |
-| **Output** | None (dialogue only) | Updates spec.md |
+| **Purpose** | Initial requirement exploration and confirmation | Refine confirmed requirements or derived spec |
+| **When to Use** | Starting a feature | Requirements or spec need clarification |
+| **Output** | Creates/updates `requirements.md` | Updates `requirements.md` first, then synchronizes `spec.md` |
 | **Method** | Open-ended Q&A | Structured scan (4 categories) |
 | **Questions** | Unlimited | Max 5 per run |
 
 ### Key Concept: Iterative Quality Loop
 
-Every generation command includes **automatic review**, generating a review report. You can:
+Every generation command includes **automatic review**. Verified defects may be fixed and re-reviewed for at most two rounds; advisory suggestions remain separate and never trigger automatic changes.
 
 1. Review the report
 2. Describe issues to fix in natural language
@@ -405,8 +403,8 @@ flowchart TB
     A["Generate Spec/Plan/Tasks"]:::rectStyle --> B["Auto Review"]:::rectStyle
     B --> C{"Issues Found?"}:::diamondStyle
 
-    C -->|Yes| D["Describe Fix in Natural Language"]:::rectStyle
-    D --> E["Update Spec + Review Report"]:::rectStyle
+    C -->|Verified defect| D["Fix with evidence"]:::rectStyle
+    D --> E["Update artifact + review report"]:::rectStyle
 
     E --> B
 
@@ -442,7 +440,8 @@ This command will:
 
 - Ask clarifying questions to understand your idea
 - Explore edge cases you might not have considered
-- **NOT** generate files automatically - you stay in control
+- Ask you to confirm the final requirement summary
+- Persist confirmed needs, constraints, decisions, exclusions, and open questions in `requirements.md`
 
 ### 4. Generate Specification Document
 
@@ -454,7 +453,8 @@ Once requirements are clarified:
 
 This command:
 
-- Compiles clarified requirements into structured specification
+- Compiles confirmed entries from `requirements.md` into a structured specification
+- Adds source references for requirement traceability
 - **Automatically** runs review and generates `review-spec.md`
 
 ### 5. Create Technical Plan
@@ -463,7 +463,7 @@ This command:
 /codexspec:spec-to-plan Use Python FastAPI for backend, PostgreSQL for database, React for frontend
 ```
 
-Includes **constitutionality review** - verifies plan aligns with project principles.
+Uses only relevant planning sections, records `Covers` links to specification requirements, and verifies applicable project principles.
 
 ### 6. Generate Tasks
 
@@ -471,11 +471,12 @@ Includes **constitutionality review** - verifies plan aligns with project princi
 /codexspec:plan-to-tasks
 ```
 
-Tasks are organized into standard phases:
+Tasks are organized around verifiable outcomes:
 
-- **TDD Enforcement**: Test tasks precede implementation tasks
-- **Parallel Markers `[P]`**: Identify independent tasks
+- **Conditional testing**: Test-first ordering is used when required by the plan, constitution, or task risk
+- **Parallel Markers `[P]`**: Used only for genuinely independent tasks
 - **File Path Specifications**: Clear deliverables per task
+- **Traceability**: Each task links to the plan and requirements it covers
 
 ### 7. Cross-Artifact Analysis (Optional but Recommended)
 
@@ -483,7 +484,7 @@ Tasks are organized into standard phases:
 /codexspec:analyze
 ```
 
-Detects issues across spec, plan, and tasks:
+Detects issues across requirements, spec, plan, and tasks:
 
 - Coverage gaps (requirements without tasks)
 - Duplication and inconsistencies
@@ -549,10 +550,10 @@ Implementation follows **conditional TDD workflow**:
 | Command                      | Description                                                       |
 | ---------------------------- | ----------------------------------------------------------------- |
 | `/codexspec:constitution`    | Create/update project constitution with cross-artifact validation |
-| `/codexspec:specify`         | Clarify requirements through interactive Q&A                      |
+| `/codexspec:specify`         | Clarify, confirm, and persist requirements in `requirements.md`    |
 | `/codexspec:generate-spec`   | Generate `spec.md` document ★ Auto-review                         |
 | `/codexspec:spec-to-plan`    | Convert spec to technical plan ★ Auto-review                      |
-| `/codexspec:plan-to-tasks`   | Break down plan into atomic tasks ★ Auto-review                   |
+| `/codexspec:plan-to-tasks`   | Break down plan into traceable, verifiable tasks ★ Auto-review    |
 | `/codexspec:implement-tasks` | Execute tasks (conditional TDD)                                   |
 
 #### Review Commands (Quality Gates)
@@ -602,7 +603,7 @@ CodexSpec is inspired by GitHub spec-kit with key differences:
 | Review Commands     | Optional                | 3 dedicated review commands + scoring         |
 | Clarify Command     | Yes                     | 4 focus categories, review integration        |
 | Analyze Command     | Yes                     | Read-only, severity-based, constitution-aware |
-| TDD in Tasks        | Optional                | Enforced (tests before implementation)        |
+| TDD in Tasks        | Optional                | Conditional on requirements, risk, and policy |
 | Implementation      | Standard                | Conditional TDD (code vs docs/config)         |
 | Extension System    | Yes                     | Yes                                           |
 | PowerShell Scripts  | Yes                     | Yes                                           |
@@ -612,7 +613,7 @@ CodexSpec is inspired by GitHub spec-kit with key differences:
 
 1. **Review-First Culture**: Every major artifact has a dedicated review command
 2. **Constitution Governance**: Principles are validated, not just documented
-3. **TDD by Default**: Test-first methodology enforced in task generation
+3. **Evidence-Based Review**: Defects require concrete evidence; advisory design ideas do not affect acceptance
 4. **Human Checkpoints**: Workflow designed around validation gates
 
 ---

{codexspec-0.5.20 → codexspec-0.6.0}/README.md

@@ -57,7 +57,7 @@ Why use CodexSpec on top of Claude Code? Here's the comparison:
 
 ```
 Traditional:  Idea → Code → Debug → Rewrite
-SDD:          Idea → Spec → Plan → Tasks → Code
+SDD:          Idea → Confirmed Requirements → Spec → Plan → Tasks → Code
 ```
 
 **Why use SDD?**
@@ -75,9 +75,9 @@ SDD:          Idea → Spec → Plan → Tasks → Code
 ### Core Workflow
 
 - **Constitution-Based Development** - Establish project principles that guide all decisions
-- **Two-Phase Specification** - Interactive clarification (`/specify`) followed by document generation (`/generate-spec`)
-- **Automatic Reviews** - Every artifact includes built-in quality checks
-- **TDD-Ready Tasks** - Task breakdowns enforce test-first methodology
+- **Persistent Requirement Capture** - `/specify` records confirmed discussion in `requirements.md` before document generation
+- **Automatic Reviews** - Every generated spec, plan, and task artifact includes built-in quality checks
+- **Traceable Tasks** - Task breakdowns preserve requirement and plan coverage, applying test-first only where required
 
 ### Human-AI Collaboration
 
@@ -115,14 +115,14 @@ CodexSpec is built on the belief that **effective AI-assisted development requir
 CodexSpec structures development into **reviewable checkpoints**:
 
 ```
-Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /implement
-                         │                  │                │
-                    Review spec        Review plan      Review tasks
-                         │                  │                │
-                      ✅ Human            ✅ Human          ✅ Human
+Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
+                                                   │                         │                            │
+                                              Review spec               Review plan                  Review tasks
 ```
 
-**Every artifact has a corresponding review command:**
+Confirmed requirements are the highest-priority feature authority. Derived artifacts carry explicit source links so conflicts can be traced back instead of silently propagated.
+
+**Every generated artifact has a corresponding review command:**
 
 - `spec.md` → `/codexspec:review-spec`
 - `plan.md` → `/codexspec:review-plan`
@@ -301,11 +301,9 @@ The config command will guide you through:
 CodexSpec breaks development into **reviewable checkpoints**:
 
 ```
-Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /implement
-                         │                  │                │
-                    Review spec        Review plan      Review tasks
-                         │                  │                │
-                      ✅ Human            ✅ Human          ✅ Human
+Idea → /specify → requirements.md → /generate-spec → spec.md → /spec-to-plan → plan.md → /plan-to-tasks → tasks.md → /implement
+                                                   │                         │                            │
+                                              Review spec               Review plan                  Review tasks
 ```
 
 ### Workflow Steps
@@ -313,7 +311,7 @@ Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /i
 | Step                         | Command                      | Output                      | Human Check |
 | ---------------------------- | ---------------------------- | --------------------------- | ----------- |
 | 1. Project Principles        | `/codexspec:constitution`    | `constitution.md`           | ✅           |
-| 2. Requirement Clarification | `/codexspec:specify`         | None (interactive dialogue) | ✅           |
+| 2. Requirement Clarification | `/codexspec:specify`         | `requirements.md`           | ✅           |
 | 3. Generate Spec             | `/codexspec:generate-spec`   | `spec.md` + auto-review     | ✅           |
 | 4. Technical Planning        | `/codexspec:spec-to-plan`    | `plan.md` + auto-review     | ✅           |
 | 5. Task Breakdown            | `/codexspec:plan-to-tasks`   | `tasks.md` + auto-review    | ✅           |
@@ -324,15 +322,15 @@ Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /i
 
 | Aspect | `/codexspec:specify` | `/codexspec:clarify` |
 |--------|----------------------|----------------------|
-| **Purpose** | Initial requirement exploration | Refine existing spec |
-| **When to Use** | No spec.md exists yet | spec.md needs improvement |
-| **Output** | None (dialogue only) | Updates spec.md |
+| **Purpose** | Initial requirement exploration and confirmation | Refine confirmed requirements or derived spec |
+| **When to Use** | Starting a feature | Requirements or spec need clarification |
+| **Output** | Creates/updates `requirements.md` | Updates `requirements.md` first, then synchronizes `spec.md` |
 | **Method** | Open-ended Q&A | Structured scan (4 categories) |
 | **Questions** | Unlimited | Max 5 per run |
 
 ### Key Concept: Iterative Quality Loop
 
-Every generation command includes **automatic review**, generating a review report. You can:
+Every generation command includes **automatic review**. Verified defects may be fixed and re-reviewed for at most two rounds; advisory suggestions remain separate and never trigger automatic changes.
 
 1. Review the report
 2. Describe issues to fix in natural language
@@ -360,8 +358,8 @@ flowchart TB
     A["Generate Spec/Plan/Tasks"]:::rectStyle --> B["Auto Review"]:::rectStyle
     B --> C{"Issues Found?"}:::diamondStyle
 
-    C -->|Yes| D["Describe Fix in Natural Language"]:::rectStyle
-    D --> E["Update Spec + Review Report"]:::rectStyle
+    C -->|Verified defect| D["Fix with evidence"]:::rectStyle
+    D --> E["Update artifact + review report"]:::rectStyle
 
     E --> B
 
@@ -397,7 +395,8 @@ This command will:
 
 - Ask clarifying questions to understand your idea
 - Explore edge cases you might not have considered
-- **NOT** generate files automatically - you stay in control
+- Ask you to confirm the final requirement summary
+- Persist confirmed needs, constraints, decisions, exclusions, and open questions in `requirements.md`
 
 ### 4. Generate Specification Document
 
@@ -409,7 +408,8 @@ Once requirements are clarified:
 
 This command:
 
-- Compiles clarified requirements into structured specification
+- Compiles confirmed entries from `requirements.md` into a structured specification
+- Adds source references for requirement traceability
 - **Automatically** runs review and generates `review-spec.md`
 
 ### 5. Create Technical Plan
@@ -418,7 +418,7 @@ This command:
 /codexspec:spec-to-plan Use Python FastAPI for backend, PostgreSQL for database, React for frontend
 ```
 
-Includes **constitutionality review** - verifies plan aligns with project principles.
+Uses only relevant planning sections, records `Covers` links to specification requirements, and verifies applicable project principles.
 
 ### 6. Generate Tasks
 
@@ -426,11 +426,12 @@ Includes **constitutionality review** - verifies plan aligns with project princi
 /codexspec:plan-to-tasks
 ```
 
-Tasks are organized into standard phases:
+Tasks are organized around verifiable outcomes:
 
-- **TDD Enforcement**: Test tasks precede implementation tasks
-- **Parallel Markers `[P]`**: Identify independent tasks
+- **Conditional testing**: Test-first ordering is used when required by the plan, constitution, or task risk
+- **Parallel Markers `[P]`**: Used only for genuinely independent tasks
 - **File Path Specifications**: Clear deliverables per task
+- **Traceability**: Each task links to the plan and requirements it covers
 
 ### 7. Cross-Artifact Analysis (Optional but Recommended)
 
@@ -438,7 +439,7 @@ Tasks are organized into standard phases:
 /codexspec:analyze
 ```
 
-Detects issues across spec, plan, and tasks:
+Detects issues across requirements, spec, plan, and tasks:
 
 - Coverage gaps (requirements without tasks)
 - Duplication and inconsistencies
@@ -504,10 +505,10 @@ Implementation follows **conditional TDD workflow**:
 | Command                      | Description                                                       |
 | ---------------------------- | ----------------------------------------------------------------- |
 | `/codexspec:constitution`    | Create/update project constitution with cross-artifact validation |
-| `/codexspec:specify`         | Clarify requirements through interactive Q&A                      |
+| `/codexspec:specify`         | Clarify, confirm, and persist requirements in `requirements.md`    |
 | `/codexspec:generate-spec`   | Generate `spec.md` document ★ Auto-review                         |
 | `/codexspec:spec-to-plan`    | Convert spec to technical plan ★ Auto-review                      |
-| `/codexspec:plan-to-tasks`   | Break down plan into atomic tasks ★ Auto-review                   |
+| `/codexspec:plan-to-tasks`   | Break down plan into traceable, verifiable tasks ★ Auto-review    |
 | `/codexspec:implement-tasks` | Execute tasks (conditional TDD)                                   |
 
 #### Review Commands (Quality Gates)
@@ -557,7 +558,7 @@ CodexSpec is inspired by GitHub spec-kit with key differences:
 | Review Commands     | Optional                | 3 dedicated review commands + scoring         |
 | Clarify Command     | Yes                     | 4 focus categories, review integration        |
 | Analyze Command     | Yes                     | Read-only, severity-based, constitution-aware |
-| TDD in Tasks        | Optional                | Enforced (tests before implementation)        |
+| TDD in Tasks        | Optional                | Conditional on requirements, risk, and policy |
 | Implementation      | Standard                | Conditional TDD (code vs docs/config)         |
 | Extension System    | Yes                     | Yes                                           |
 | PowerShell Scripts  | Yes                     | Yes                                           |
@@ -567,7 +568,7 @@ CodexSpec is inspired by GitHub spec-kit with key differences:
 
 1. **Review-First Culture**: Every major artifact has a dedicated review command
 2. **Constitution Governance**: Principles are validated, not just documented
-3. **TDD by Default**: Test-first methodology enforced in task generation
+3. **Evidence-Based Review**: Defects require concrete evidence; advisory design ideas do not affect acceptance
 4. **Human Checkpoints**: Workflow designed around validation gates
 
 ---

{codexspec-0.5.20 → codexspec-0.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codexspec"
-version = "0.5.20"
+version = "0.6.0"
 description = "CodexSpec - A Spec-Driven Development (SDD) toolkit for Claude Code"
 readme = "README.md"
 requires-python = ">=3.11"

codexspec-0.6.0/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+# Check development prerequisites or resolve SDD workflow artifact paths.
+
+set -e
+
+# Source common utilities
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+JSON=false
+PATHS_ONLY=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+FEATURE_ARG=""
+WORKFLOW_MODE=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --json)
+            JSON=true
+            WORKFLOW_MODE=true
+            shift
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            WORKFLOW_MODE=true
+            shift
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            WORKFLOW_MODE=true
+            shift
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            WORKFLOW_MODE=true
+            shift
+            ;;
+        --feature)
+            FEATURE_ARG="$2"
+            WORKFLOW_MODE=true
+            shift 2
+            ;;
+        -h|--help)
+            cat <<'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+With no options, checks the local development environment.
+
+Workflow options:
+  --json             Output JSON
+  --paths-only       Resolve artifact paths without requiring plan/tasks
+  --require-tasks    Require tasks.md
+  --include-tasks    Include tasks.md in AVAILABLE_DOCS
+  --feature PATH|ID  Resolve an explicit feature directory or ID
+EOF
+            exit 0
+            ;;
+        *)
+            log_error "Unknown option: $1"
+            exit 1
+            ;;
+    esac
+done
+
+resolve_feature_dir() {
+    local specs_dir
+    specs_dir=$(get_specs_dir)
+
+    if [ -n "$FEATURE_ARG" ]; then
+        if [ -d "$FEATURE_ARG" ]; then
+            local explicit_dir
+            explicit_dir=$(cd "$FEATURE_ARG" && pwd -P)
+            if ! is_feature_name "$(basename "$explicit_dir")"; then
+                log_error "Invalid feature directory name: $FEATURE_ARG"
+                return 1
+            fi
+            printf "%s\n" "$explicit_dir"
+            return
+        fi
+        if [ -f "$FEATURE_ARG" ]; then
+            local artifact_dir
+            artifact_dir=$(cd "$(dirname "$FEATURE_ARG")" && pwd -P)
+            if ! is_feature_name "$(basename "$artifact_dir")"; then
+                log_error "Invalid feature directory name: $artifact_dir"
+                return 1
+            fi
+            printf "%s\n" "$artifact_dir"
+            return
+        fi
+        if [ -d "$specs_dir/$FEATURE_ARG" ]; then
+            if ! is_feature_name "$FEATURE_ARG"; then
+                log_error "Invalid feature directory name: $FEATURE_ARG"
+                return 1
+            fi
+            (cd "$specs_dir/$FEATURE_ARG" && pwd -P)
+            return
+        fi
+
+        if ! is_feature_id "$FEATURE_ARG"; then
+            log_error "Invalid feature ID: $FEATURE_ARG"
+            return 1
+        fi
+
+        # A short ID is only a local lookup convenience. The full directory
+        # name identifies the workspace, and ambiguity must be explicit.
+        local id_matches=()
+        local candidate
+        if [ -d "$specs_dir" ]; then
+            for candidate in "$specs_dir"/*; do
+                [ -d "$candidate" ] || continue
+                if is_feature_name "$(basename "$candidate")" &&
+                    [[ "$(basename "$candidate")" == "$FEATURE_ARG"-* ]]; then
+                    id_matches+=("$candidate")
+                fi
+            done
+        fi
+        if [ "${#id_matches[@]}" -eq 1 ]; then
+            (cd "${id_matches[0]}" && pwd -P)
+            return
+        fi
+        if [ "${#id_matches[@]}" -gt 1 ]; then
+            log_error "Multiple feature directories match ID '$FEATURE_ARG'. Pass a full directory or artifact path."
+            return 1
+        fi
+
+        log_error "Feature directory not found: $FEATURE_ARG"
+        return 1
+    fi
+
+    local feature_id
+    feature_id=$(get_feature_id)
+    if [ -n "$feature_id" ] && [ -d "$specs_dir/$feature_id" ]; then
+        (cd "$specs_dir/$feature_id" && pwd -P)
+        return
+    fi
+
+    local candidates=()
+    if [ -d "$specs_dir" ]; then
+        while IFS= read -r candidate; do
+            if is_feature_name "$(basename "$candidate")"; then
+                candidates+=("$candidate")
+            fi
+        done < <(find "$specs_dir" -mindepth 1 -maxdepth 1 -type d | sort)
+    fi
+
+    if [ "${#candidates[@]}" -eq 1 ]; then
+        (cd "${candidates[0]}" && pwd -P)
+        return
+    fi
+
+    if [ "${#candidates[@]}" -gt 1 ]; then
+        log_error "Multiple feature directories found. Pass --feature explicitly."
+    else
+        log_error "No feature directory found. Run /codexspec:specify first."
+    fi
+    return 1
+}
+
+if [ "$WORKFLOW_MODE" = true ]; then
+    require_codexspec_project
+
+    REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd -P)
+    if ! FEATURE_DIR=$(resolve_feature_dir); then
+        printf "%s\n" "$FEATURE_DIR"
+        exit 1
+    fi
+    BRANCH=$(git branch --show-current 2>/dev/null || true)
+    REQUIREMENTS="$FEATURE_DIR/requirements.md"
+    FEATURE_SPEC="$FEATURE_DIR/spec.md"
+    IMPL_PLAN="$FEATURE_DIR/plan.md"
+    TASKS="$FEATURE_DIR/tasks.md"
+
+    if [ "$PATHS_ONLY" = false ]; then
+        if [ ! -f "$IMPL_PLAN" ]; then
+            log_error "plan.md not found in $FEATURE_DIR"
+            exit 1
+        fi
+        if [ "$REQUIRE_TASKS" = true ] && [ ! -f "$TASKS" ]; then
+            log_error "tasks.md not found in $FEATURE_DIR"
+            exit 1
+        fi
+    fi
+
+    AVAILABLE_DOCS=()
+    [ -f "$REQUIREMENTS" ] && AVAILABLE_DOCS+=("requirements.md")
+    [ -f "$FEATURE_SPEC" ] && AVAILABLE_DOCS+=("spec.md")
+    [ -f "$IMPL_PLAN" ] && AVAILABLE_DOCS+=("plan.md")
+    if [ "$INCLUDE_TASKS" = true ] && [ -f "$TASKS" ]; then
+        AVAILABLE_DOCS+=("tasks.md")
+    fi
+
+    if [ "$JSON" = true ]; then
+        python3 -c '
+import json
+import sys
+
+keys = (
+    "REPO_ROOT",
+    "BRANCH",
+    "FEATURE_DIR",
+    "REQUIREMENTS",
+    "FEATURE_SPEC",
+    "IMPL_PLAN",
+    "TASKS",
+)
+values = sys.argv[1:8]
+payload = dict(zip(keys, values))
+payload["AVAILABLE_DOCS"] = sys.argv[8:]
+print(json.dumps(payload, separators=(",", ":")))
+' "$REPO_ROOT" "$BRANCH" "$FEATURE_DIR" "$REQUIREMENTS" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS" "${AVAILABLE_DOCS[@]}"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "REQUIREMENTS: $REQUIREMENTS"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+        echo "AVAILABLE_DOCS: ${AVAILABLE_DOCS[*]}"
+    fi
+    exit 0
+fi
+
+log_info "Checking prerequisites for CodexSpec..."
+
+# Check Python
+if command_exists python3; then
+    PYTHON_VERSION=$(python3 --version 2>&1 | cut -d' ' -f2)
+    log_success "Python 3 installed: $PYTHON_VERSION"
+else
+    log_error "Python 3 is not installed"
+    exit 1
+fi
+
+# Check uv
+if command_exists uv; then
+    UV_VERSION=$(uv --version 2>&1)
+    log_success "uv installed: $UV_VERSION"
+else
+    log_warning "uv is not installed. Recommended for package management."
+    echo "  Install with: curl -LsSf https://astral.sh/uv/install.sh | sh"
+fi
+
+# Check git
+if command_exists git; then
+    GIT_VERSION=$(git --version 2>&1 | cut -d' ' -f3)
+    log_success "Git installed: $GIT_VERSION"
+else
+    log_warning "Git is not installed. Recommended for version control."
+fi
+
+# Check Claude Code
+if command_exists claude; then
+    log_success "Claude Code CLI is installed"
+else
+    log_warning "Claude Code CLI is not installed"
+    echo "  Install from: https://claude.ai/code"
+fi
+
+# Check if in a CodexSpec project
+if is_codexspec_project; then
+    log_success "Currently in a CodexSpec project"
+else
+    log_info "Not currently in a CodexSpec project"
+    echo "  Run 'codexspec init' to initialize a new project"
+fi
+
+echo ""
+log_success "Prerequisite check complete!"