Speckit Orchestrator

# Spec-Kit Artifact Structure

## Overview

Spec-kit uses a step-by-step approach to organizing specification, planning, and implementation artifacts. This document defines the purpose and structure of each artifact type.

## Directory Structure

```
project-root/
├── .specify/                    # Spec-kit infrastructure
│   ├── scripts/                 # Workflow automation scripts
│   ├── templates/               # Artifact templates
│   └── memory/                  # Project context and constitution
│
└── specs/                       # Feature specifications
    └── {N}-{short-name}/        # Feature directory
        ├── spec.md              # What & Why (user-focused)
        ├── plan.md              # How (technical design)
        ├── tasks.md             # Implementation tasks
        ├── checklists/          # Quality validation checklists
        │   ├── requirements.md  # Spec quality validation
        │   ├── ux.md           # UX requirements validation
        │   ├── api.md          # API requirements validation
        │   └── security.md     # Security requirements validation
        ├── research.md          # Technical research & decisions
        ├── data-model.md        # Entity definitions
        ├── quickstart.md        # Test scenarios
        └── contracts/           # API contracts
            ├── openapi.yaml
            └── graphql/
```

> **Note: Claude Code Plan Mode Namespace**
>
> Claude Code's native Plan Mode (v2.0.51+) creates a `plan.md` file at the
> **project root** when users enter plan mode via `Shift+Tab` or `--permission-mode plan`.
> Spec-kit plans are intentionally stored in `specs/{feature}/plan.md` to avoid
> collision. When searching for scope artifacts:
> 1. Always check `specs/*/plan.md` first (spec-kit feature plans)
> 2. Then check root `plan.md` (may be Claude Plan Mode artifact)
>
> The two systems are complementary: Claude Plan Mode is for exploratory planning,
> while spec-kit plans are structured implementation blueprints.

## Core Artifacts

### spec.md - Feature Specification

**Purpose**: Define WHAT users need and WHY, without implementation details.

**Audience**: Business stakeholders, product managers, non-technical reviewers.

**Structure**:
```markdown
# Feature Name

## Overview
- Problem statement
- User value proposition

## User Scenarios
- Who uses it
- Primary flows
- User goals

## Functional Requirements
- What must it do (testable)
- Acceptance criteria

## Success Criteria
- Measurable outcomes
- Technology-agnostic metrics
- User-facing goals

## Success Criteria (Optional)
- Performance expectations
- Security considerations
- Accessibility needs

## Edge Cases (Optional)
- Boundary conditions
- Error scenarios
- Fallback behaviors

## Dependencies & Assumptions (Optional)
- External dependencies
- Documented assumptions
```

**Key Principles**:
- No technology choices (no "React", "PostgreSQL", "REST API")
- Focus on user value, not system internals
- Measurable, testable requirements
- Maximum 3 [NEEDS CLARIFICATION] markers

### plan.md - Implementation Plan

**Purpose**: Define HOW to build the feature technically.

**Audience**: Developers, technical leads, architects.

**Structure**:
```markdown
# Implementation Plan: Feature Name

## Technical Context
- Tech stack decisions
- Architecture choices
- Libraries and frameworks

## Constitution Check
- Alignment with project principles
- Gate evaluation

## Phase 0: Research
- Technical unknowns
- Best practices research
- Decision rationale

## Phase 1: Design
- Data model
- API contracts
- Integration points

## Phase 2: Implementation
- Component structure
- Service layer
- Infrastructure needs
```

**Key Principles**:
- T