Global AI Directives & Agent Rules
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Global AI Directives (GAD) and Agent Rules constitute the immutable "Physical Laws" of the NeuralDBG repository ecosystem. These directives govern how AI agents and human contributors interact with the codebase, ensuring high standards of technical excellence, pedagogical clarity, and rigorous validation. The framework prioritizes value over code, mandating that every feature solves a real user problem validated through methodology such as the "Mom Test."
The scope of these rules is global across the project, enforced through automated gates, manual verification, and strict branch authority. They serve to maintain project isolation, ensure security hardening by default, and provide a traceable record of every development session. Sources: GAD.md:1-20, copilot-instructions.md:1-15, infrastructure_planning/RULE_SYNC_PROCEDURE.md:12-18
Core Directives and Rule Enforcement
The project operates under three primary directives: Value over Code (features must be validated), Pedagogical Execution (agents must act as teachers), and Professionalism (high standards for testing and documentation). These are enforced through a numbered rule system.
Key Rule Summary
| Directive | ID | Requirement |
|---|---|---|
| Read Rules | R1 | Agents must read rule files at the start of every session. |
| Mom Test | R2 | No production code until 5+ user interviews validate the problem. |
| Pessimistic Progress | R3 | Track progress in summaries; subtract 10-15% for realism. |
| Traceability | R4 | Update SESSION_SUMMARY.md in English and French every session. |
| Test Coverage | R5 | Maintain a minimum of 60% test coverage for all additions. |
| Security | R6 | Proactively run scanners like bandit, safety, or clippy. |
| No Emojis | R9 | Zero emojis allowed in any project files or documentation. |
| Project Isolation | R34 | Scope limited strictly to the current project context. |
Sources: GAD.md:25-50, copilot-instructions.md:150-180, ROADMAP.md:85-100
Development Lifecycle & Validation Gates
Development is governed by a "Hard Milestone Lock" strategy. Progress is tracked at specific percentages (25%, 50%, 75%, 90%, 95%), and all development MUST stop at these gates until mandatory validation is completed.
Milestone Requirements
- Feature Focus (Rule 22): Focus on only ONE specific feature per validation cycle to ensure depth.
- Working Demos: At each milestone, the project must have at least 2 runnable, error-free demos.
- Deep Understanding: Before transitioning phases, the agent must teach the user a new concept and ask critical thinking "Devil's Advocate" questions.
The following diagram illustrates the flow from code implementation to milestone validation:
Operational Infrastructure & Personas
The system adapts its behavior based on the professional persona of the user (CEO, DevOps, MLOps, or Developer) and strictly integrates with project management tools.
Persona Adaptability (Rule 27)
- CEO/Product: Focus on business value, KPIs, and the "Mom Test."
- DevOps/MLOps: Focus on CI/CD gates, reproducibility, and infrastructure.
- Developer: Focus on architecture (Hub & Spokes), modularity, and SOLID principles.
Mandatory Tool Stack (Rule 32)
The project mandates a standardized stack that includes Linear for issue tracking, Cursor/VS Code for development, and GitHub Actions for CI/CD. Rule 29 specifies that no work may occur without a verified Linear connection.
Branching and Rule Synchronization
To maintain "Global Rule Parity" (Rule 33), rule files such as AGENTS.md and GAD.md are treated as immutable laws that must be identical across all branches.
Branch Authority (Rule 30)
- ceo/: Authorized to modify rule files and core strategy.
- infra/: DevOps and infrastructure tasks.
- feat/: New feature development.
- fix/: Bug fixes.
Rule Sync Procedure
When rules are modified in a ceo/ branch, a mandatory sync process triggers:
- Changes are committed to the
ceo/branch. - Changes are merged into all other active branches (main, infra, etc.).
- The master
kuro-rulesrepository is updated. - CI/CD pipelines (GitHub Actions) detect rule changes and enforce sync via PR templates.
Security and CI/CD Debugging
Security is non-negotiable. Agents must run language-specific scanners (e.g., bandit for Python) before declaring any task complete. Furthermore, Rule 39 ("CI/CD Debugging First") mandates that if a GitHub Actions check is failing, the agent must prioritize fixing the pipeline over any feature work.
Automated Gates
The CI/CD pipeline acts as an "unbreakable digital bouncer," rejecting any push that falls below 60% test coverage or fails security scans.
Sources: GAD.md:105-125, GAD.md:415-435, infrastructure_planning/milestone_0_tasks.md:25-40
Conclusion
The Global AI Directives and Agent Rules provide a rigorous framework for the NeuralDBG project. By enforcing strict validation milestones, persona-based interaction, and mandatory rule synchronization, the system ensures that all technical debt is documented and that every line of code contributes to a validated, secure, and pedagogically sound causal inference engine. Sources: GAD.md:165-175, infrastructure_planning/CODEBASE_GUIDE.md:1-15