gds-mock-mcp/.github/copilot-instructions.md

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:

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

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