spec-kit-skill

Original source / Raw SKILL.md

---
name: spec-kit-skill
description: GitHub Spec-Kit integration for constitution-based spec-driven development. 7-phase workflow (constitution, specify, clarify, plan, tasks, analyze, implement). Use when working with spec-kit CLI, .specify/ directories, or creating specifications with constitution-driven development. Triggered by "spec-kit", "speckit", "constitution", "specify", references to .specify/ directory, or spec-kit commands.
---

# Spec-Kit: Constitution-Based Spec-Driven Development

Official GitHub Spec-Kit integration providing a 7-phase constitution-driven workflow for feature development.

## Quick Start

This skill works with the [GitHub Spec-Kit CLI](https://github.com/github/spec-kit) to guide you through structured feature development:

1. **Constitution** → Establish governing principles
2. **Specify** → Define functional requirements
3. **Clarify** → Resolve ambiguities
4. **Plan** → Create technical strategy
5. **Tasks** → Generate actionable breakdown
6. **Analyze** → Validate consistency
7. **Implement** → Execute implementation

**Storage**: Creates files in `.specify/specs/NNN-feature-name/` directory with numbered features

## References

- For detailed detection logic and status checks, see `helpers/detection-logic.md`.
- For a runnable status report, use `scripts/detect-phase.sh`.

## When to Use

- Setting up spec-kit in a project
- Creating constitution-based feature specifications
- Working with .specify/ directory
- Following GitHub spec-kit workflow
- Constitution-driven development

---

## Prerequisites & Setup

### Check CLI Installation

First, verify if spec-kit CLI is installed:

```bash
command -v specify || echo "Not installed"
```

### Installation

If not installed:

```bash
# Persistent installation (recommended)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# One-time usage
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
```

**Requirements**:
- Python 3.11+
- Git
- uv package manager ([install uv](https://docs.astral.sh/uv/))

### Project Initialization

If CLI is installed but project not initialized:

```bash
# Initialize in current directory
specify init . --ai codex

# Initialize new project
specify init <project-name> --ai codex

# Options:
# --force: Overwrite non-empty directories
# --script ps: Generate PowerShell scripts (Windows)
# --no-git: Skip Git initialization
```

---

<details>
<summary>🔍 Phase Detection Logic</summary>

## Detecting Project State

Before proceeding, always detect the current state:

### 1. CLI Installed?

```bash
if command -v specify &> /dev/null || [ -x "$HOME/.local/bin/specify" ]; then
  echo "CLI installed"
else
  echo "CLI not installed - guide user through installation"
fi
```

### 2. Project Initialized?

```bash
if [ -d ".specify" ] && [ -f ".specify/memory/constitution.md" ]; then
  echo "Project initialized"
else
  echo "Project not initialized - guide user through 'specify init'"
fi
```

### 3. Current Feature

```bash
# Get latest feature directory
LATEST=$(ls -d .specify/specs/[0-9]* 2>/dev/null | sort -V | tail -1)
echo "Latest feature: $LATEST"
```

### 4. Current Phase

Detect phase by checking file existence in latest feature:

```bash
FEATURE_DIR=".specify/specs/001-feature-name"

if [ ! -f ".specify/memory/constitution.md" ]; then
  echo "Phase: constitution"
elif [ ! -d "$FEATURE_DIR" ]; then
  echo "Phase: specify"
elif [ -f "$FEATURE_DIR/spec.md" ] && ! grep -q "## Clarifications" "$FEATURE_DIR/spec.md"; then
  echo "Phase: clarify"
elif [ ! -f "$FEATURE_DIR/plan.md" ]; then
  echo "Phase: plan"
elif [ ! -f "$FEATURE_DIR/tasks.md" ]; then
  echo "Phase: tasks"
elif [ -f "$FEATURE_DIR/tasks.md" ] && grep -q "\\- \\[ \\]" "$FEATURE_DIR/tasks.md"; then
  echo "Phase: implement"
else
  echo "Phase: complete"
fi
```

</details>

<details>
<summary>📜 Phase 1: Constitution</summary>

## Constitution Phase

Establish foundational principles that govern all development decisions.

### Purpose

Create `.specify/memory/constitution.md` with:
- Project values and principles
- Technical standards
- Decision-making frameworks
- Code quality expectations
- Architecture guidelines

### Process

1. **Gather Context**
   - Understand project domain
   - Identify key stakeholders
   - Review existing standards (if any)

2. **Draft Constitution**
   - Core values and principles
   - Technical standards
   - Quality expectations
   - Decision criteria

3. **Structure**

```markdown
# Project Constitution

## Core Values

1. **[Value Name]**: [Description and implications]
2. **[Value Name]**: [Description and implications]

## Technical Principles

### Architecture
- [Principle with rationale]

### Code Quality
- [Standards and expectations]

### Performance
- [Performance criteria]

## Decision Framework

When making technical decisions, consider:
1. [Criterion with priority]
2. [Criterion with priority]
```

4. **Versioning**
   - Constitution can evolve
   - Track changes for governance
   - Review periodically

### Example Content

```markdown
# Project Constitution

## Core Values

1. **Simplicity Over Cleverness**: Favor straightforward solutions that are easy to understand and maintain over clever optimizations.

2. **User Experience First**: Every technical decision should improve or maintain user experience.

## Technical Principles

### Architecture
- Prefer composition over inheritance
- Keep components loosely coupled
- Design for testability

### Code Quality
- Code reviews required for all changes
- Unit test coverage > 80%
- Documentation for public APIs

### Performance
- Page load < 3 seconds
- API response < 200ms
- Progressive enhancement for slower connections

## Decision Framework

When choosing between approaches:
1. Does it align with our core values?
2. Is it maintainable by the team?
3. Does it scale with our growth?
4. What's the long-term cost?
```

</details>

<details>
<summary>📝 Phase 2: Specify</summary>

## Specify Phase

Define *what* needs building and *why*, avoiding technology specifics.

### Script Usage

```bash
# Create new feature
.specify/scripts/bash/create-new-feature.sh --json "feature-name"

# Expected JSON output:
# {"BRANCH_NAME": "001-feature-name", "SPEC_FILE": "/path/to/.specify/specs/001-feature-name/spec.md"}
```

**Parse JSON**: Extract `BRANCH_NAME` and `SPEC_FILE` for subsequent operations.

### Template Structure

Load `.specify/templates/spec-template.md` to understand required sections, then create specification at `SPEC_FILE` location.

### Specification Content

Focus on **functional requirements**:

```markdown
# Feature Specification: [Feature Name]

## Problem Statement

[What problem are we solving?]

## User Stories

### Story 1: [Title]

As a [role]
I want [capability]
So that [benefit]

**Acceptance Criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

### Story 2: [Title]

[Continue...]

## Non-Functional Requirements

- Performance: [Specific metrics]
- Security: [Requirements]
- Accessibility: [Standards]
- Scalability: [Expectations]

## Success Metrics

- [Measurable outcome]
- [Measurable outcome]

## Out of Scope

[Explicitly state what's NOT included]
```

### Key Principles

- **Technology-agnostic**: Don't specify "use React" or "MySQL"
- **Outcome-focused**: Describe what user achieves, not how
- **Testable**: Acceptance criteria must be verifiable
- **Complete**: Address edge cases and error scenarios

### Git Integration

The script automatically:
- Creates new feature branch (e.g., `001-feature-name`)
- Checks out the branch
- Initializes spec file

</details>

<details>
<summary>❓ Phase 3: Clarify</summary>

## Clarify Phase

Resolve underspecified areas through targeted questioning.

### Purpose

Before planning implementation, ensure specification is complete and unambiguous.

### Process

1. **Analyze Specification**
   - Read spec.md thoroughly
   - Identify ambiguities, gaps, assumptions
   - Note areas with multiple valid interpretations

2. **Generate Questions** (Maximum 5)
   - Prioritize high-impact areas
   - Focus on decisions that affect architecture
   - Ask about edge cases and error handling

3. **Question Format**

```markdown
## Clarifications

### Q1: [Clear, specific question]

**Context**: [Why this matters]
**Options**: [If multiple approaches exist]

### Q2: [Clear, specific question]

**Context**: [Why this matters]
**Impact**: [What decisions depend on this]
```

4. **Update Specification**
   - Add "## Clarifications" section to spec.md
   - Document questions and answers
   - Update relevant sections based on answers
   - Iterate until all critical questions answered

### Guidelines

- **Maximum 5 questions** per round
- **Specific, not general**: "How should we handle concurrent edits?" not "How should it work?"
- **Decision-focused**: Questions that inform technical choices
- **Incremental**: Can run multiple clarification rounds

### Example Questions

```markdown
## Clarifications

### Q1: How should the system handle conflicts when two users edit the same document simultaneously?

**Context**: This affects data model design and user experience.
**Options**:
- Last-write-wins (simple, may lose data)
- Operational transforms (complex, preserves all edits)
- Locked editing (simple, limits collaboration)

**Answer**: [User provides answer]

### Q2: What's the maximum number of concurrent users we need to support?

**Context**: Affects infrastructure planning and architecture decisions.
**Impact**: Determines caching strategy, database choices, and scaling approach.

**Answer**: [User provides answer]
```

</details>

<details>
<summary>🏗️ Phase 4: Plan</summary>

## Plan Phase

Create technical implementation strategy based on clarified specification.

### Script Usage

```bash
# Setup plan phase
.specify/scripts/bash/setup-plan.sh --json

# Expected JSON output:
# {"FEATURE_SPEC": "/path/spec.md", "IMPL_PLAN": "/path/plan.md", "SPECS_DIR": "/path/specs", "BRANCH": "001-feature"}
```

### Documents to Create

#### 1. Main Plan (`plan.md`)

```markdown
# Implementation Plan: [Feature Name]

## Technology Stack

### Frontend
- Framework: [Choice with rationale]
- State Management: [Choice with rationale]
- Styling: [Choice with rationale]

### Backend
- Language/Framework: [Choice with rationale]
- Database: [Choice with rationale]
- API Style: [REST/GraphQL/etc with rationale]

## Architecture

### System Overview

```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service Layer]
    C --> D[Data Layer]
```

### Component Design

#### Component 1: [Name]
- **Responsibility**: [What it does]
- **Interfaces**: [APIs it exposes]
- **Dependencies**: [What it needs]

[Continue for all components...]

## Design Patterns

- [Pattern]: [Where and why used]

## Security Considerations

- Authentication: [Approach]
- Authorization: [Approach]
- Data Protection: [Approach]

## Performance Strategy

- Caching: [Strategy]
- Optimization: [Key areas]

## Error Handling

- Error types and handling strategies
- Logging and monitoring approach
```

#### 2. Data Model (`data-model.md`)

```markdown
# Data Model

## Entity Relationship

```mermaid
erDiagram
    USER ||--o{ DOCUMENT : creates
    USER {
        string id
        string email
        string role
    }
    DOCUMENT {
        string id
        string title
        string content
    }
```

## Schemas

### User
```typescript
interface User {
  id: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
  createdAt: Date;
}
```

[Continue for all entities...]
```

#### 3. API Contracts (`contracts/`)

Create API specifications:
- `api-spec.json` (OpenAPI/Swagger)
- `signalr-spec.md` (if using SignalR)
- Other contract definitions

#### 4. Research (`research.md`) - Optional

Document technology investigations:

```markdown
# Research: [Topic]

## Options Evaluated

### Option 1: [Technology]
**Pros**: [Benefits]
**Cons**: [Drawbacks]
**Fit**: [How well it matches our needs]

### Option 2: [Technology]
[Same structure...]

## Recommendation

[Chosen option with rationale]

## References

- [Source 1]
- [Source 2]
```

#### 5. Quick start (`quickstart.md`) - Optional

Setup instructions for developers.

### Alignment Check

Before finalizing:
- ✅ Does plan address all requirements?
- ✅ Does it follow constitution principles?
- ✅ Are technical choices justified?
- ✅ Are dependencies identified?
- ✅ Is it implementable?

</details>

<details>
<summary>✅ Phase 5: Tasks</summary>

## Tasks Phase

Generate dependency-ordered, actionable implementation tasks.

### Prerequisites Script

```bash
# Check prerequisites
.specify/scripts/bash/check-prerequisites.sh --json [--require-tasks] [--include-tasks]

# Output: {"FEATURE_DIR": "/path", "AVAILABLE_DOCS": ["spec.md", "plan.md", ...]}
```

### Task Generation

Create `.specify/specs/NNN-feature/tasks.md`:

```markdown
# Implementation Tasks: [Feature Name]

## Phase 1: Foundation

- [ ] 1.1 Set up project structure
  - Create directory layout per architecture doc
  - Configure build tools
  - Initialize testing framework
  - **Depends on**: None
  - **Requirement**: R1.1

- [ ] 1.2 [P] Configure development environment
  - Set up linters and formatters
  - Configure CI/CD pipeline basics
  - **Depends on**: 1.1
  - **Requirement**: R1.2

## Phase 2: Core Implementation

- [ ] 2.1 Implement User model and persistence
  - Create User entity with validation
  - Implement repository pattern
  - Write unit tests
  - **Depends on**: 1.1
  - **Requirement**: R2.1, R2.3

- [ ] 2.2 [P] Implement Document model
  - Create Document entity
  - Define relationships with User
  - Write unit tests
  - **Depends on**: 1.1
  - **Requirement**: R2.2

- [ ] 2.3 Implement API endpoints
  - Create REST controllers
  - Add request/response validation
  - Write integration tests
  - **Depends on**: 2.1, 2.2
  - **Requirement**: R3.1, R3.2

[Continue with all phases...]

## Phase N: Integration & Testing

- [ ] N.1 End-to-end testing
  - Write E2E test scenarios
  - Test critical user paths
  - **Depends on**: [all previous]
  - **Requirement**: All

## Notes

- `[P]` indicates tasks that can be parallelized
- Always check dependencies before starting
- Reference requirements for acceptance criteria
```

### Task Characteristics

**Each task should**:
- Be specific and actionable
- Reference requirements (R1.1, R2.3, etc.)
- List dependencies
- Be completable in 1-4 hours
- Have clear acceptance criteria

**Task Types**:
- Implementation tasks (write code)
- Testing tasks (write tests)
- Configuration tasks (set up tools)
- Integration tasks (connect components)

**Exclude**:
- Deployment tasks
- User training
- Marketing activities
- Non-coding work

### Dependency Markers

- **None**: Can start immediately
- **1.1**: Must complete task 1.1 first
- **1.1, 2.2**: Must complete both first
- **[P]**: Can run in parallel with siblings

</details>

<details>
<summary>🔍 Phase 6: Analyze</summary>

## Analyze Phase

Cross-artifact consistency and quality validation (read-only).

### Purpose

Before implementation, verify:
- All requirements covered by tasks
- Plan aligns with constitution
- No conflicts between documents
- No missing dependencies

### Analysis Process

1. **Read All Documents**
   - Constitution
   - Specification
   - Plan
   - Data model
   - Tasks

2. **Coverage Check**

```bash
# Extract requirements
grep -E "R[0-9]+\.[0-9]+" spec.md | sort -u > requirements.txt

# Extract referenced requirements in tasks
grep -E "Requirement.*R[0-9]+" tasks.md | sort -u > covered.txt

# Compare
comm -23 requirements.txt covered.txt
```

3. **Consistency Checks**

**Constitution Alignment**:
- Does plan follow stated principles?
- Are architecture choices justified per constitution?

**Requirement Coverage**:
- Is every requirement addressed in tasks?
- Are acceptance criteria testable?

**Technical Coherence**:
- Do data models match spec needs?
- Do API contracts align with plan?
- Are dependencies realistic?

**Task Dependencies**:
- Are all dependencies valid?
- Is critical path identified?
- Any circular dependencies?

4. **Report Findings**

```markdown
# Analysis Report

## ✅ Passing Checks

- All requirements covered
- Constitution alignment verified
- No circular dependencies

## ⚠️ Warnings

- Requirement R3.4 has no corresponding task
- Task 5.2 references undefined dependency

## 🔴 Critical Issues

None found

## Recommendations

1. Add task for Requirement R3.4
2. Clarify dependency for task 5.2
3. Consider breaking task 6.1 into smaller tasks (estimated 8 hours)
```

### Guidelines

- **Read-only**: Don't modify documents
- **Objective**: Report facts, not opinions
- **Actionable**: Provide specific recommendations
- **Prioritized**: Critical issues first

</details>

<details>
<summary>⚙️ Phase 7: Implement</summary>

## Implement Phase

Execute tasks systematically, respecting dependencies and test-driven development.

### Implementation Strategy

1. **Phase-by-Phase Execution**
   - Complete all Phase 1 tasks before Phase 2
   - Respect task dependencies
   - Leverage parallel markers [P]

2. **Task Execution Pattern**

```bash
# For each task:
# 1. Read context
cat .specify/specs/001-feature/spec.md
cat .specify/specs/001-feature/plan.md
cat .specify/specs/001-feature/data-model.md

# 2. Check dependencies
# Verify all depends-on tasks are complete

# 3. Implement
# Write code per task description

# 4. Test
# Write and run tests

# 5. Validate
# Check against requirements

# 6. Mark complete
# Update tasks.md: - [x] task completed
```

3. **Test-Driven Approach**

For each task:
- Write tests first (when applicable)
- Implement to pass tests
- Refactor while maintaining green tests
- Integration test when connecting components

4. **Quality Checks**

Before marking task complete:
- [ ] Code follows plan architecture
- [ ] Tests written and passing
- [ ] Meets acceptance criteria
- [ ] No obvious bugs
- [ ] Integrated with previous work

### Handling Errors

If implementation reveals issues:

1. **Design Issues**: Return to plan phase, update plan
2. **Requirement Gaps**: Return to specify/clarify, update spec
3. **Technical Blockers**: Document, escalate to user

### Progress Tracking

Update tasks.md as you go:

```markdown
- [x] 1.1 Set up project structure ✓ Complete
- [x] 1.2 [P] Configure development environment ✓ Complete
- [ ] 2.1 Implement User model ← Currently here
- [ ] 2.2 [P] Implement Document model
```

### Completion Criteria

Feature is complete when:
- [ ] All tasks marked complete
- [ ] All tests passing
- [ ] All requirements validated
- [ ] Code reviewed (if applicable)
- [ ] Documentation updated

</details>

---

## File Structure

```
.specify/
├── memory/
│   └── constitution.md              # Phase 1
├── specs/
│   └── 001-feature-name/            # Numbered features
│       ├── spec.md                  # Phase 2
│       ├── plan.md                  # Phase 4
│       ├── data-model.md            # Phase 4
│       ├── contracts/               # Phase 4
│       │   ├── api-spec.json
│       │   └── signalr-spec.md
│       ├── research.md              # Phase 4 (optional)
│       ├── quickstart.md            # Phase 4 (optional)
│       └── tasks.md                 # Phase 5
├── scripts/
│   └── bash/
│       ├── check-prerequisites.sh
│       ├── create-new-feature.sh
│       ├── setup-plan.sh
│       └── common.sh
└── templates/
    ├── spec-template.md
    ├── plan-template.md
    └── tasks-template.md
```

## Workflow Rules

1. **Sequential Phases**: Must complete phases in order
2. **Constitution First**: Always establish constitution before features
3. **Branch per Feature**: Each feature gets its own Git branch
4. **Numbered Features**: Use sequential numbering (001, 002, 003)
5. **Script Integration**: Use provided bash scripts for consistency
6. **Principle-Driven**: All decisions align with constitution

## Summary

Spec-Kit provides a rigorous, constitution-based approach to feature development with clear phases, explicit dependencies, and comprehensive documentation at every step. The workflow ensures alignment from principles through implementation.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### helpers/detection-logic.md

```markdown
# 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 codex

# Initialize new project
specify init <project-name> --ai codex

# 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 codex"
  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
```

```

### scripts/detect-phase.sh

```bash
#!/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

  if command -v uv &> /dev/null; then
    if uv tool list 2>/dev/null | grep -q "specify-cli"; then
      return 0
    fi
  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

  if [ ! -d ".specify/scripts/bash" ] || [ ! -d ".specify/templates" ]; 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
    local init_status=$?
    if [ "$init_status" -eq 2 ]; then
      echo -e "${YELLOW}⚠${NC} Project partially initialized"
      if [ ! -f ".specify/memory/constitution.md" ]; then
        echo -e "  ${YELLOW}Missing:${NC} .specify/memory/constitution.md"
      fi
      if [ ! -d ".specify/scripts/bash" ]; then
        echo -e "  ${YELLOW}Missing:${NC} .specify/scripts/bash/"
      fi
      if [ ! -d ".specify/templates" ]; then
        echo -e "  ${YELLOW}Missing:${NC} .specify/templates/"
      fi
      echo -e "  ${YELLOW}Next:${NC} Re-run init: specify init . --ai codex --force"
    else
      echo -e "${RED}✗${NC} Project not initialized"
      echo -e "  ${YELLOW}Initialize:${NC} specify init . --ai codex"
    fi
    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 "$@"

```