Copilot Instructions

# Copilot Project Instructions — {{PROJECT_NAME}}
#
# ┌─────────────────────────────────────────────────────────────┐
# │  TUTORIAL: What is .github/copilot-instructions.md?        │
# │                                                             │
# │  This file is LOADED AUTOMATICALLY by Copilot CLI          │
# │  every time you open a session in this repository.         │
# │  You don't need to run /agent or /instructions for it      │
# │  to apply — it is always active.                           │
# │                                                             │
# │  Use it to:                                                 │
# │  - Give general project context to ALL agents              │
# │  - Define global rules that apply regardless of role       │
# │  - Establish project conventions                           │
# │  - Indicate where to find key documentation                │
# │                                                             │
# │  Difference from AGENTS.md:                                │
# │  - copilot-instructions.md = global context, always on     │
# │  - AGENTS.md = selectable roles via /agent                 │
# │                                                             │
# │  Difference from .github/instructions/*.instructions.md:   │
# │  - copilot-instructions.md = applies to ALL                │
# │  - *.instructions.md = modular, toggleable instructions    │
# │    via /instructions                                       │
# └─────────────────────────────────────────────────────────────┘

## Project

- **Name**: {{PROJECT_NAME}}
- **Description**: {{PROJECT_DESCRIPTION}}
- **Main stack**: {{TECH_STACK}}
- **Repository**: {{REPOSITORY_URL}}
- **Project Manager**: {{TEAM_LEAD}}

## Team context

This project uses the **Understudy** system: a team of specialized AI agents.
Each agent has a defined role in `AGENTS.md` and detailed instructions in
`.github/instructions/<role>.instructions.md`.

Available roles:
- **Architect** — Solution design and architectural decisions
- **Backend** — API, service and business logic implementation
- **Frontend** — User interfaces and experience
- **DevOps** — Infrastructure, CI/CD and operations
- **Security** — Security integrated throughout the cycle
- **QA** — Testing and software quality (.NET, Node.js, Python)

## Spec-Driven Development

This project follows **Spec-Driven Development**:
1. Before writing code, the specification is documented in `docs/spec.md`
2. The spec must be approved by the PM before starting
3. Any scope change is first reflected in the spec

## Mandatory context files

| File | Purpose |
|---|---|
| `docs/spec.md` | Project specification — the source of truth |
| `docs/decisions.md` | Architecture Decision Records (ADR) |
| `docs/session-log.md` | Session log — read at the start of each session |
| `docs/team-roster.md` | Active team roster and capabilities |

## Global rules

### At the start of a session
1. **Always** read `docs/session-log.md` to know what was done before
2. **Always** read `docs/spec.md` for project context
3. **Always** read `docs/decisions.md` for decisions already made
4. Before working, confirm your understanding of the current state

### At the end of a session
1. Update `docs/session-log.md` with:
   - What was done in this session
   - What is still pending
   - Decisions made
   - Blockers identified
2. This ensures the next session (another day, another time) has full context

### Recognizing good stopping points

A long conversation costs more (tokens, time, money) than starting fresh
with a concise summary. Watch for natural stopping points — a feature just
finished with tests passing, a bug fixed and verified, a question fully
answered — and proactively suggest wrapping up:
1. Run `/end-session` (or update `docs/session-log.md` yourself) so the
   next session has a clean handoff.
2. Tell the user this is a good point to close this chat and start a new
   one — `/start-session` picks up full context from `docs/session-log.md`,
   so nothing is lost.

Don't interrupt in-progress work to suggest this, and never refuse to keep
going if the user wants to continue — it's a suggestion at natural breaks,
not a requirement.

### Code standards
- Readable and maintainable code for any team member
- Single-responsibility functions
- Business domain names, not generic names
- Explicit error handling with context in messages
- No hardcoded secrets — use vault/env vars
- No dead code or TODO comments in commits

### Project structure