docs/ai-working-rules.md

AI Working Rules — PulseFabric Monitor

This document defines the rules and conventions that AI assistants (GitHub Copilot, agents, etc.) must follow when working on this project.

Feature Implementation Order

All features must be implemented in this strict sequence:

1. db.json — Add or update data in backend/db.json
2. Typed model — Add or update the DTO interface in frontend/src/app/core/models/api.models.ts
3. Service — Add a method to frontend/src/app/core/services/dashboard-api.service.ts
4. UI — Build or extend the component, consuming data via the service

Never skip steps. Never put data fetching logic directly in a component.

20 Production Code Rules

#	Rule	Summary
1	Separation of Concerns	TS, HTML, SCSS in separate files
2	No Hardcoded Data	All data from API or mock files
3	Typed Interfaces	Every data structure has a TS interface; any is forbidden
4	Component-Driven	Reusable standalone Angular components
5	No Magic Numbers	Named constants, enums, or config objects only
6	CSS Token System	Use --mat-sys-*, --pf-*, or SCSS variables
7	Material 3 Compliance	Follow M3 guidelines for all UI
8	Concise Angular	Signals, input(), inject(), pipes, directives
9	No Over-Engineering	No unnecessary libraries or infrastructure
10	Reuse Before Creating	Audit existing code first
11	Generic Component Design	Input-driven; new instance = new inputs, not new file
12	Minimal Change Principle	>3 files changed → stop and explain
13	Flat HTML Structure	No unnecessary DOM wrappers
14	No console.log	Remove all logging before committing
15	No Dead Code	No commented-out blocks
16	Clean Imports	Every import must be used
17	Consistent Naming	kebab-case files, camelCase vars, PascalCase classes
18	Single Responsibility	One component/service/model group per file
19	No any (Reinforced)	Forbidden in all positions
20	SCSS Nesting ≤ 3 Levels	Refactor into separate classes if exceeded

Governance Files

File	Purpose
.github/copilot-instructions.md	Full rule set loaded into every Copilot session
.github/prompts/add-kpi-widget.prompt.md	Step-by-step prompt for adding a KPI card
.github/prompts/add-chart-widget.prompt.md	Step-by-step prompt for adding a chart widget
.github/prompts/add-new-component.prompt.md	Step-by-step prompt for creating a new component
.github/agents/network-dashboard-implementer.md	Agent profile with planning, compliance, and stop behavior
.github/skills/dashboard-widget.md	Optional skill for widget scaffolding

Stop Conditions

The AI must stop and ask the user when:

• A task requires modifying more than 3 existing files
• A task conflicts with any of the 20 rules
• The data shape is ambiguous or incomplete
• It is unclear whether to create or reuse a component

Validation Checklist

Before completing any task, verify:

• ng build passes from frontend/
• No any types introduced
• No console.log statements
• No dead or commented-out code
• All imports are used
• SCSS nesting ≤ 3 levels
• CSS tokens used (no raw hex/px/rem)
• Implementation follows db.json → model → service → UI order