ProxyScript-Template/.github/copilot-instructions.md

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:

# 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:

.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:

.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