calorie-counter/.github/copilot-instructions.md

GOVERNANCE ACTIVE: All file operations require verification. Protected files (.github/agents/**, .github/copilot-modules/**) require override workflow. Secrets in code trigger security incidents.

# Copilot Instructions - Virsaitis Project (Hub)

**Project**: Virsaitis Three-Layer AI Governance System
**Version**: 3.0.0
**Framework**: Native VS Code Agent Skills (v1.109+)
**Updated**: 2026-02-17
**Architecture**: Hub-and-Spoke (lean hub + focused modules)

---

[GOVERNANCE_PROTECTION]
COPILOT_INSTRUCTIONS_IMMUTABLE=true
MODIFICATION_PROHIBITED=requires_explicit_approval
USER_REQUEST_OVERRIDE=prohibited
EXCEPTIONS=documented_in_change_log
ENFORCEMENT=absolute

---

## 🎯 Project Mission

**Virsaitis** is a three-layer AI governance enforcement system achieving 95%+ compliance:

1. **Layer 1: Agent** - Atomic instruction design (.github/agents/)
2. **Layer 2: MCP Server** - Pre-execution validation (TypeScript)
3. **Layer 3: VS Code Extension** - User action interception (TypeScript)

---

## 🤖 Machine-Readable Policy

```
[PROJECT_IDENTITY]
PROJECT_NAME=Virsaitis
VERSION=3.0.0
ARCHITECTURE=hub_and_spoke_modular

[MODULE_LOADING]
APPROACH=load_on_demand
CONTEXT_EFFICIENCY=high_priority
TOKEN_BUDGET=conservative
REFRESH_INTERVAL=every_10_messages
```

---

## 📚 Module Navigation

**Core Governance** (load for ALL tasks):
- 📋 [Core Policies](.github/copilot-modules/core-policies.md) - TIER system, enforcement, protected files

**Component Development** (load by component):
- 🤖 [Agent Standards](.github/copilot-modules/agent-standards.md) - Atomic sentences, markdown rules
- 🔌 [MCP Standards](.github/copilot-modules/mcp-standards.md) - TypeScript, Node.js, validation
- 🔧 [Extension Standards](.github/copilot-modules/extension-standards.md) - VS Code API, packaging
- 🎯 [Skills Standards](.github/copilot-modules/skills-standards.md) - SKILL.md format, frontmatter

**Development Practices** (load as needed):
- 🔄 [Development Workflow](.github/copilot-modules/development-workflow.md) - Discovery-first, TDD, commit checklist
- 🔒 [Security Controls](.github/copilot-modules/security-controls.md) - Secret scanning, input validation
- 📋 [Requirements Engineering](.github/copilot-modules/requirements-engineering.md) - REQ-ID, traceability
- ✅ [Testing & Quality](.github/copilot-modules/testing-quality.md) - Coverage, validation, metrics

**Integration & Deployment**:
- 🔗 [Integration Patterns](.github/copilot-modules/integration-patterns.md) - Agent↔Skills, MCP↔Extension
- 📦 [Distribution & Deployment](.github/copilot-modules/distribution-deployment.md) - Packaging, release

**Reference**:
- 📖 [Definition Library](.github/virsaitis-definition-library.md) - Authoritative terms with consequence chains (AI + human)
- 📝 [Glossary](virsaitis-development/virsaitis-requirements/glossary.md) - Quick-reference for all 54 project terms

---

##  Smart Context Loading

AI loads **ONLY relevant modules** based on task:

```yaml
Any Task:
  - core-policies.md (always loaded)

Writing Code:
  - development-workflow.md
  - testing-quality.md
  - security-controls.md

Security-Sensitive Work:
  - security-controls.md
  - testing-quality.md

Requirements & Planning:
  - requirements-engineering.md

Creating or Editing Skills:
  - skills-standards.md
  - development-workflow.md

Packaging & Release:
  - distribution-deployment.md
  - testing-quality.md

Cross-Layer Integration:
  - integration-patterns.md

Virsaitis Internal Development:
  - agent-standards.md (agent files)
  - mcp-standards.md (MCP server)
  - extension-standards.md (VS Code extension)
```

---

## 🚨 TIER-0 Critical Rules (Always Enforced)

### Protected File Modification

**PROHIBITED without approval:**
- `.github/copilot-instructions.md` (this file)
- `.github/copilot-modules/**/*.md` (all modules)
- `.github/agents/*.agent.md`
- `.github/virsaitis-definition-library.md`

**Response:** "TIER-0 VIOLATION PREVENTED" → Explain → Provide alternative workflow

### Atomic Sentence Structure (Agent.md)

All Agent.md files use atomic sentences (one concept per sentence). See [Agent Standards](.github/copilot-modules/agent-standards.md).

### Secret Management

Never commit secrets. See [Security Controls](.github/copilot-modules/security-controls.md).

### MCP Tool Enforcement

Use Virsaitis MCP tools for governance operations. See [Core Policies](.github/copilot-modules/core-policies.md).

**Full TIER-0 details:** See [Core Policies](.github/copilot-modules/core-policies.md)

---

## ⚡ Quick Reference

| Task | Load Modules | Key Action |
|------|--------------|------------|
| Write code | development-workflow, testing-quality | Discovery-first, then implement |
| Security check | security-controls | Run security scan |
| Implement feature | requirements-engineering | Search REQ-ID first |
| Create skill | skills-standards | `skills-ref validate` |
| Before commit | development-workflow | Checklist validation |
| Package release | distribution-deployment | Version sync check |
| Virsaitis agent work | agent-standards | Atomic sentences |
| Virsaitis MCP/Extension | mcp-standards / extension-standards | `npm run build && npm test` |

---

## 🆘 When Uncertain

```
IF uncertain about:
  - Which module to load
  - Component ownership
  - TIER classification
  - Security implications

THEN respond:
  "CONFIRM_NEEDED: [specific question]"

WAIT for user clarification

DO NOT proceed with assumptions
```

---

## 📞 Getting Started

**First time working on Virsaitis?**

1. **Read**: [Core Policies](.github/copilot-modules/core-policies.md) (foundation)
2. **Identify component**: Agent, MCP, Extension, or Skills
3. **Load**: Component-specific standards module
4. **Review**: [Development Workflow](.github/copilot-modules/development-workflow.md)
5. **Start**: Discovery-first approach (verify before implement)

**Module not loading?**
- Verify file exists: `.github/copilot-modules/[module-name].md`
- Check path in navigation section above
- Request module creation if missing

---

*Virsaitis Hub v3.0.0*
*Lean hub + 11 focused modules = efficient context loading*
*Token budget: ~500 tokens hub + ~1500-2500 per module*

---

## Governance Reminder

Protected files require the override workflow — no exceptions.
Every file operation starts with verification.
Every task ends with CHANGELOG, traceability, and tests.
Governance is the product. Load core-policies.md before starting any work.
Definitions: `.github/virsaitis-definition-library.md` | Glossary: `virsaitis-development/virsaitis-requirements/glossary.md`