# Copilot Instructions: Proxy Scripts

This project uses **Specify** (Spec-Driven Development workflow) to manage feature development through structured specifications, planning, and task execution.

## Project Status

**Early Stage**: This repository was recently initialized from the Specify template. No production code exists yet—only the Specify workflow infrastructure.

## Workflow Commands

All feature development follows the Specify workflow using specialized agents:

### Feature Lifecycle

1. **Create specification**: `/speckit.specify [feature description]`
   - Generates `specs/[###-feature-name]/spec.md` with user stories, requirements, and edge cases
   - Creates feature branch

2. **Create implementation plan**: `/speckit.plan`
   - Generates `plan.md` with tech stack, architecture, and project structure
   - Produces research artifacts and API contracts
   - Must pass constitution checks before proceeding

3. **Generate tasks**: `/speckit.tasks`
   - Creates `tasks.md` with dependency-ordered implementation tasks
   - Groups tasks by user story for independent implementation
   - Enables parallel development where possible

4. **Execute implementation**: `/speckit.implement`
   - Processes tasks from `tasks.md`
   - Checks checklists before proceeding (if any exist)
   - Follows TDD workflow when tests are specified

### Supporting Commands

- `/speckit.checklist`: Generate custom checklists (UX, security, performance, etc.)
- `/speckit.clarify`: Identify underspecified areas and encode answers back into spec
- `/speckit.analyze`: Cross-artifact consistency analysis (spec/plan/tasks)
- `/speckit.taskstoissues`: Convert tasks.md into GitHub issues
- `/speckit.constitution`: Create/update project constitution

## File Structure

```
.specify/
├── memory/
│   └── constitution.md          # Project principles and standards
├── scripts/bash/
│   ├── check-prerequisites.sh   # Validate workflow state
│   ├── create-new-feature.sh    # Initialize new feature branch
│   └── update-agent-context.sh  # Sync agent prompts with templates
└── templates/                   # Templates for spec, plan, tasks, checklists

.github/
├── agents/                      # Agent definitions for each workflow step
└── prompts/                     # Agent prompt templates

specs/[###-feature-name]/        # Feature-specific documentation
├── spec.md                      # Feature specification
├── plan.md                      # Implementation plan
├── tasks.md                     # Task list
├── research.md                  # Technical research
├── data-model.md               # Data models
├── quickstart.md               # Getting started guide
├── contracts/                   # API contracts
└── checklists/                  # Custom checklists
```

## Constitution (MANDATORY)

The project constitution at `.specify/memory/constitution.md` defines **non-negotiable principles**:

### Core Principles

1. **Modular Architecture**: Discrete modules with clear boundaries, independently testable
2. **API-First Design**: Document APIs before implementation; follow RESTful principles
3. **Test-First Development (NON-NEGOTIABLE)**:
   - Write failing tests first
   - Get user approval of test scenarios
   - Implement minimum code to pass
   - Maintain 80%+ code coverage
4. **Security & Privacy by Default**: Encrypt sensitive data, use OAuth 2.0, implement least privilege
5. **Observability & Debuggability**: Structured logs, request tracing, performance metrics
6. **Semantic Versioning**: MAJOR.MINOR.PATCH with migration guides for breaking changes
7. **Simplicity & YAGNI**: Implement only demonstrated needs; justify complexity

### Quality Gates (ALL must pass before merge)

- ✅ All tests pass (unit, integration, e2e)
- ✅ Code coverage ≥ 80%
- ✅ No critical security vulnerabilities
- ✅ Documentation updated
- ✅ Performance regression checks pass

### API Standards

- Accept/return JSON
- Use HTTP methods semantically (GET, POST, PUT, DELETE, PATCH)
- Return appropriate status codes
- Include rate limiting headers
- Version endpoints explicitly (`/v1/`, `/v2/`)
- Document with OpenAPI/Swagger

## Helper Scripts

### check-prerequisites.sh

Validates workflow state before agent execution:

```bash
# JSON output with feature directory and available docs
.specify/scripts/bash/check-prerequisites.sh --json

# Require tasks.md exists (for implementation phase)
.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks

# Output just path variables
.specify/scripts/bash/check-prerequisites.sh --paths-only
```

### create-new-feature.sh

Initialize new feature branch and directory structure:

```bash
.specify/scripts/bash/create-new-feature.sh "feature description"
```

## Development Workflow

### Starting a New Feature

1. Run `.specify/scripts/bash/create-new-feature.sh "feature description"` OR use `/speckit.specify`
2. Feature branch created: `###-feature-name`
3. Directory created: `specs/###-feature-name/`

### Implementation Flow

```
spec.md (requirements)
  → plan.md (architecture + tech stack)
  → tasks.md (implementation tasks)
  → implementation (code + tests)
```

### Task Organization

Tasks in `tasks.md` are organized by:

- **Phase 1: Setup** - Project initialization
- **Phase 2: Foundational** - Core infrastructure (blocking for all stories)
- **Phase 3+: User Stories** - Grouped by story priority (P1, P2, P3...)
  - Tests written FIRST (must fail before implementation)
  - Implementation follows tests
  - Each story independently testable

Tasks marked `[P]` can run in parallel (different files, no dependencies).

### Checklist Validation

If checklists exist in `specs/[feature]/checklists/`:

- `/speckit.implement` checks completion status before proceeding
- All items must be checked off `[x]` unless user approves proceeding anyway
- Common checklist types: UX, security, performance, accessibility

## Key Conventions

### User Stories

- **Prioritized** (P1, P2, P3...) by importance
- **Independently testable** - each story is a standalone MVP slice
- Include acceptance scenarios in Given-When-Then format
- Specify why each priority level was chosen

### Test-Driven Development

1. Write tests FIRST (contract → integration → unit)
2. Ensure tests FAIL before implementation
3. Get user approval on test scenarios
4. Implement minimum code to pass
5. Refactor while maintaining green tests

### Naming Conventions

- Feature branches: `###-feature-name` (auto-numbered)
- Requirements: `FR-001`, `FR-002`, etc.
- Tasks: `T001`, `T002`, etc.
- Checklist items: `CHK001`, `CHK002`, etc.
- Mark unclear items: `[NEEDS CLARIFICATION: reason]`

## Working with Agents

### Agent Context

Agents load context from:

- Constitution (`constitution.md`)
- Templates (`.specify/templates/*.md`)
- Feature docs (`specs/[feature]/*.md`)

When templates change, run:

```bash
.specify/scripts/bash/update-agent-context.sh
```

### Agent Auto-Approval

VS Code auto-approves scripts in `.specify/scripts/bash/` and `.specify/scripts/powershell/` (see `.vscode/settings.json`).

## Important Notes

- **No production code exists yet** - implement according to constitution principles
- **Always check constitution** before making architectural decisions
- **Write tests first** - TDD is non-negotiable per constitution
- **Document APIs** before implementing them
- **Use Specify agents** for feature work rather than ad-hoc implementation
- **Validate prerequisites** with `check-prerequisites.sh` before running agents