SpecPilot

# AI Coding Instructions — SpecPilot

> This file is automatically read by GitHub Copilot, Cursor, and other AI tools on every request.
> Keep this file short — only critical mandates. Full context is in `.specs/project/project.yaml`.

## Project

- **Name:** SpecPilot
- **Stack:** TypeScript / Node.js / Commander.js
- **Specs location:** `.specs/`

## 🔴 Critical Mandates — Never violate, no exceptions

1. **NEVER commit** code to git unless the developer explicitly asks. Always ask first.
2. **NEVER push** to git unless the developer explicitly asks. Always ask first.
3. **NEVER deploy, publish, or release** the project unless the developer explicitly asks. Always ask first.
4. **NEVER modify** the `.specs/` folder structure, subfolder names, or file names. Only update file contents.
5. **ALWAYS update** affected `.specs/` files after every code change — without being asked:
   - Structural changes → `architecture/architecture.md`
   - Feature changes → `project/requirements.md`
   - Test changes → `quality/tests.md`
   - Task status → `planning/tasks.md`
   - Completed work → `CHANGELOG.md`
6. **NEVER describe, quote, or reference file contents** without first reading the file via a tool call in this session. If you have not read the file yet, say so explicitly before answering.
7. **NEVER implement, write code, or make file changes** unless the developer explicitly asks. If the next step seems obvious, ask first — do not assume.
8. **SPEC-FIRST review gate**: Before touching any code or non-spec files, read all relevant `.specs/` files, update all affected spec files first, present a **Spec Report** summarizing what changed, which files were affected, and what the specs now say, then wait for the developer's explicit `yes, proceed` before writing code. If the developer declines, revert the spec changes and stop.

## 🟡 Process Mandates

- **Spec-First:** Update `.specs/` before writing code.
- **Log all AI interactions** in `.specs/development/prompts.md` with timestamps.
- **Document decisions** in `.specs/development/context.md`.

## Context — read on demand by task type

| Task type | Read |
|---|---|
| Session start | `.specs/project/project.yaml` |
| Feature / bug | + `project/requirements.md`, `planning/tasks.md` |
| Architecture | + `architecture/architecture.md` |
| Tests | + `quality/tests.md` |
| Security | + `security/threat-model.md`, `security/security-decisions.md` |
| Planning | + `planning/tasks.md`, `planning/roadmap.md` |

## Code Philosophy — Write Only What Needed

1. Need exist? No → skip. Say why.
2. Already in codebase? → reuse. Not rewrite.
3. Stdlib do it? → use it.
4. Native or installed dep cover it? → use. No new deps.
5. One line do it? → write that.
6. Only then: minimum code that work.
7. Never cut: validation, error handling, security, explicit requirement.

## Code Rules

1. No abstraction, interface, factory, or pattern unless asked.
2. No scaffold "for later". Later scaffold itself.
3. Delete before add.
4. Shortest correct diff win.
5. Fix cause, not symptom. One guard in shared function beat guard in every caller.
6. Boring over clever. Clever = 3am bug.
7. Read before write. Never reference code you haven't read.

## Re-Anchor

If you lose context mid-session, read `.specs/project/project.yaml` to restore full project context.
For a ready-made re-anchor prompt, see `.specs/development/prompts.md → ## Re-Anchor Prompt`.