docs: apply analysis remediation edits
Applied 4 LOW-severity improvements from /speckit.analyze:
1. Clarified PNR format in FR-005 (TEST-{6 chars} not just 6 chars)
2. Added explicit FR-015 coverage note in tasks.md Phase 3
3. Documented infinite inventory design decision in T020
4. Connected documentation tasks to SC-006/SC-007 objectives
All changes are documentation clarifications, no functional impact.
Analysis showed 100% requirement coverage with zero blocking issues.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
234
.github/copilot-instructions.md
vendored
Normal file
234
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,234 @@
|
||||
# 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)
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user