# Copilot Instructions: Speckit Framework

This repository contains a **spec-driven development framework** (Speckit) that provides structured workflows for feature specification, planning, and implementation through custom Copilot agents.

## Running Scripts

All workflow scripts are located in `.specify/scripts/bash/` and must be run from the repository root:

```bash
# Check prerequisites for current feature branch
./.specify/scripts/bash/check-prerequisites.sh --json

# Create a new feature branch (auto-detects next sequential number)
./.specify/scripts/bash/create-new-feature.sh --json --short-name "feature-name" "Feature description"

# For timestamp-based branch naming (check .specify/init-options.json first)
./.specify/scripts/bash/create-new-feature.sh --json --timestamp --short-name "feature-name" "Feature description"
```

**Important**: 
- VS Code is configured to auto-approve scripts in `.specify/scripts/bash/` (see `.vscode/settings.json`)
- Always use `--json` flag for parseable output
- Quote arguments with special characters properly: `'I'\''m text'` or `"I'm text"`
- Scripts use `set -e` - they exit on first error

## Architecture

### Workflow Structure

Speckit follows a **phase-based specification workflow**:

1. **Specification** (`/speckit.specify`) → Creates `spec.md` (what/why, no implementation)
2. **Planning** (`/speckit.plan`) → Creates `plan.md`, `research.md`, `data-model.md`, contracts
3. **Task Generation** (`/speckit.tasks`) → Creates `tasks.md` (ordered, dependency-aware)
4. **Analysis** (`/speckit.analyze`) → Cross-validates artifacts for consistency
5. **Implementation** (`/speckit.implement`) → Executes tasks from `tasks.md`

Additional commands:
- `/speckit.clarify` - Interactive clarification of underspecified requirements
- `/speckit.checklist` - Generate custom checklists for features
- `/speckit.constitution` - Manage project principles and standards
- `/speckit.taskstoissues` - Convert tasks.md into GitHub issues

### Directory Layout

```
.github/
├── agents/               # Agent definitions (.agent.md files)
├── prompts/             # Agent prompt templates (.prompt.md files)
└── copilot-instructions.md

.specify/
├── init-options.json    # Branch numbering mode (sequential/timestamp)
├── integration.json     # Integration config (copilot, speckit version)
├── memory/
│   └── constitution.md  # Project constitution (template, not yet filled)
├── templates/           # Templates for spec, plan, tasks, etc.
├── scripts/
│   └── bash/           # Workflow automation scripts
└── integrations/
    └── copilot/        # Copilot-specific integration scripts

specs/                   # Created when first feature branch is made
└── ###-feature-name/   # Feature directories (auto-numbered or timestamped)
    ├── spec.md         # Feature specification (what/why)
    ├── plan.md         # Implementation plan (how)
    ├── tasks.md        # Task breakdown
    ├── research.md     # Technical research
    ├── data-model.md   # Data structures
    ├── quickstart.md   # Usage examples
    ├── contracts/      # API/interface contracts
    └── checklists/     # Quality validation checklists
```

### Feature Branch Workflow

- Branch naming: `###-short-feature-name` (e.g., `001-user-auth`, `20260407-143052-user-auth`)
- Numbering mode stored in `.specify/init-options.json` (`branch_numbering`: `"sequential"` or `"timestamp"`)
- Each feature gets a directory under `specs/###-feature-name/`
- Scripts validate you're on a properly named feature branch before running

## Custom Copilot Agents

All agents are defined in `.github/agents/*.agent.md` with prompts in `.github/prompts/*.prompt.md`.

**Key Agent Patterns**:

1. **Extension Hooks**: Agents check for `.specify/extensions.yml` before/after execution
   - Optional hooks: Present to user with description
   - Mandatory hooks: Auto-execute with `EXECUTE_COMMAND`
   - Hook conditions are NOT evaluated by agents (delegated to HookExecutor)

2. **Constitution Authority**: `.specify/memory/constitution.md` defines non-negotiable principles
   - Constitution violations are always CRITICAL
   - Agents must validate against constitution rules
   - Constitution changes require separate, explicit workflow

3. **Progressive Disclosure**: Agents load minimal context, avoid token waste
   - Build semantic models internally (don't dump raw artifacts)
   - Limit findings to high-signal items (e.g., max 50 in analysis)
   - Use stable identifiers (kebab-case slugs, not generic IDs)

4. **Read-Only Analysis**: `/speckit.analyze` NEVER modifies files
   - Outputs structured report
   - Offers remediation plan (requires user approval)
   - Validates cross-artifact consistency

## Key Conventions

### Specification Quality

Specs must be **technology-agnostic** and **testable**:

- ✅ Focus on WHAT and WHY (user needs, business value)
- ❌ No implementation details (frameworks, APIs, code structure)
- ✅ Success criteria must be measurable and user-focused
- ❌ No technical metrics (API latency, database TPS)
- ✅ Maximum 3 `[NEEDS CLARIFICATION]` markers per spec
- ✅ Requirements must have clear acceptance criteria

**Good Success Criteria**:
- "Users complete checkout in under 3 minutes"
- "System supports 10,000 concurrent users"
- "95% of searches return results in under 1 second"

**Bad Success Criteria** (too technical):
- "API response time under 200ms" → Use "Users see results instantly"
- "Database handles 1000 TPS" → Use user-facing metric
- "Redis cache hit rate above 80%" → Technology-specific

### Planning Phase

Plans (`plan.md`) are technical but defer implementation until tasks:

- Architecture/stack decisions documented
- Constitution compliance gates checked before Phase 0
- Technical research informs technology choices
- Data models, contracts, and quickstarts created
- Performance goals and constraints specified (domain-specific)

### Task Generation

Tasks (`tasks.md`) must be:

- **Ordered by dependencies** - foundation before integration
- **Marked for parallelization** - `[P]` for independent tasks
- **Phase-grouped** - logical implementation stages
- **File-path specific** - reference exact files to create/modify
- **Testable** - clear completion criteria

### Script Conventions

Scripts in `.specify/scripts/bash/`:

1. **common.sh** - Shared functions for feature detection
2. **check-prerequisites.sh** - Validates current context
   - `--json` - Structured output
   - `--require-tasks` - Enforce tasks.md exists
   - `--include-tasks` - Add tasks.md to available docs
   - `--paths-only` - Skip validation, just return paths
3. **create-new-feature.sh** - Initialize feature branches
   - Auto-detects next sequential number (don't pass `--number`)
   - Supports `--timestamp` for timestamp-based naming
   - Always use `--short-name "name"` for branch suffix

## Agent Handoffs

Agents define suggested next steps via `handoffs` in frontmatter:

```yaml
---
description: Agent purpose
handoffs:
  - label: Build Technical Plan
    agent: speckit.plan
    prompt: Create a plan for the spec. I am building with...
  - label: Clarify Spec Requirements
    agent: speckit.clarify
    prompt: Clarify specification requirements
    send: true
---
```

When you see handoff suggestions, route the user to the appropriate next command.

## Integration Notes

- **AI**: Configured for GitHub Copilot (`.specify/init-options.json`)
- **Version**: Speckit v0.5.1.dev0
- **Context Updates**: `.specify/integrations/copilot/scripts/update-context.sh` syncs agent context

## Common Workflows

### Starting a New Feature

1. User provides feature description
2. Run `/speckit.specify` → Creates spec.md with quality checklist
3. Validate spec passes quality gates (no CRITICAL issues)
4. Run `/speckit.plan` → Creates technical plan
5. Run `/speckit.tasks` → Generates ordered task list
6. Optional: Run `/speckit.analyze` → Cross-validate artifacts
7. Run `/speckit.implement` → Execute implementation

### Validating Specifications

- Specs auto-validate against checklist in `checklists/requirements.md`
- Max 3 validation iterations before reporting remaining issues
- Clarifications presented as multi-choice tables (max 3 questions)
- Markdown tables must be properly formatted (aligned pipes, spaced cells)

### Constitution Management

- Template stored at `.specify/memory/constitution.md`
- Defines MUST/SHOULD principles for the project
- Use `/speckit.constitution` to create/update from principles
- All specs and plans validated against constitution
- Constitution violations block implementation

## When Working with This Repository

1. **Understand the meta-nature**: This is a framework FOR building projects, not a project itself
2. **Respect the workflow phases**: Specification → Planning → Tasks → Implementation
3. **Validate branch context**: Most commands require being on a feature branch
4. **Use JSON output**: Always add `--json` to scripts for parseable results
5. **Check hooks**: Extensions can inject pre/post workflow hooks
6. **Don't hallucinate**: If a file doesn't exist, report it accurately
7. **Token efficiency**: Load minimal context, produce high-signal findings

## Active Technologies
- Node.js 20 LTS (current stable) + Minimal libraries - MCP SDK (@modelcontextprotocol/sdk), Valkey client (ioredis), Docker buildx for multi-platform builds (001-mock-gds-server)
- Valkey 8.0+ (Redis-compatible in-memory store with persistence) (001-mock-gds-server)
- Node.js 20 LTS (ES modules) + @modelcontextprotocol/sdk ^1.0.4 (MCP protocol), ioredis ^5.4.1 (Valkey client), pino ^9.5.0 (structured logging), HTTP/2 server library (TBD in research phase) (001-mock-gds-server)
- Valkey (Redis-compatible) for session state, PNR storage with TTL, rate limiting counters (001-mock-gds-server)
- Valkey 8.0+ (Redis-compatible in-memory store with persistence for PNRs and sessions) (001-mock-gds-server)
- Node.js 20 LTS with TypeScript 6.0.2 + @modelcontextprotocol/sdk ^1.0.4 (MCP protocol), @modelcontextprotocol/server ^2.0.0-alpha.2 (McpServer), @modelcontextprotocol/express ^2.0.0-alpha.2 (HTTP transport), ioredis ^5.4.1 (Valkey client), Express ^5.2.1, pino ^9.5.0 (structured logging) (001-mock-gds-server)

## Recent Changes
- 001-mock-gds-server: Added Node.js 20 LTS (current stable) + Minimal libraries - MCP SDK (@modelcontextprotocol/sdk), Valkey client (ioredis), Docker buildx for multi-platform builds