Rules Reference

All 27 rules organized by category, with trigger types and descriptions.

Table of contents

1. How Rules Work
2. 🕸️ Rule Dependency Graph
3. 🛡️ Security & Integrity
   1. Rugged Software Constitution
   2. Security Mandate
   3. Security Principles
4. ⚡ Reliability & Performance
   1. Error Handling Principles
   2. Concurrency & Threading Principles
   3. Concurrency & Threading Mandate
   4. Performance Optimization Principles
   5. Resource & Memory Management
   6. Monitoring & Alerting Principles
   7. Configuration Management Principles
5. 🏗️ Architecture & Design
   1. Core Design Principles
   2. Architectural Pattern (Testability-First)
   3. API Design Principles
   4. Project Structure
   5. Database Design Principles
   6. Data Serialization & Interchange
   7. Command Execution Principles
6. 🧩 Maintainability & Quality
   1. Code Organization Principles
   2. Code Idioms & Conventions
   3. Testing Strategy
   4. Dependency Management Principles
   5. Documentation Principles
   6. Logging & Observability Mandate
   7. Accessibility Principles
   8. Git Workflow Principles
7. 🔄 DevOps & Operations
   1. Code Completion Mandate
   2. Rule Priority

---

How Rules Work

Rules are markdown files in .agents/rules/ that provide guidance to AI agents. Each rule has a trigger type in its YAML frontmatter:

Trigger	Behavior
always_on	Loaded in every session — non-negotiable constraints
model_decision	Activated contextually when the agent determines the rule is relevant

When rules conflict, Rule Priority determines the winner. Security always wins.

---

🕸️ Rule Dependency Graph

The rules are highly interconnected. You can explore these relationships using our Interactive Rule Dependency Graph to see how individual mandates, principles, and idioms relate to each other.

---

🛡️ Security & Integrity

Rules that ensure code is secure by default.

Rugged Software Constitution

always_on

File: rugged-software-constitution.md

The foundational philosophy based on the Rugged Software Manifesto. Establishes three commitments: Responsible, Defensible, and Maintainable. Defines the 7 Rugged Habits including defense-in-depth, instrument for awareness, reduce attack surface, design for failure, clean up after yourself, verify your defenses, and adapt to the ecosystem.

Security Mandate

always_on

File: security-mandate.md

Non-negotiable security requirements:

• Never trust user input — validate server-side
• Deny by default — require explicit permission
• Fail securely — fail closed, never open
• Defense in depth — multiple layers of security

Security Principles

model_decision

File: security-principles.md

Detailed security implementation guidance for authentication, authorization, input validation, cryptographic operations, and handling sensitive data.

---

⚡ Reliability & Performance

Rules that ensure code is robust and efficient.

Error Handling Principles

model_decision

File: error-handling-principles.md

Techniques for robust error management including error types, recovery strategies, validation errors, business rule violations, infrastructure failures, and resource cleanup.

Concurrency & Threading Principles

model_decision

File: concurrency-and-threading-principles.md

Detailed patterns for safe parallel execution: goroutines, async/await, thread pools, deadlock prevention, and race condition avoidance.

Concurrency & Threading Mandate

always_on

File: concurrency-and-threading-mandate.md

When to use concurrency (I/O-bound vs CPU-bound) and when NOT to use it. Prevents premature optimization and overuse of threads.

Performance Optimization Principles

model_decision

File: performance-optimization-principles.md

Writing efficient and scalable code. Profiling, benchmarking, and optimizing performance-critical paths.

Resource & Memory Management

model_decision

File: resources-and-memory-management-principles.md

Handling files, database connections, network sockets, and locks. Implementing resource pools, cleanup, and timeout strategies.

Monitoring & Alerting Principles

model_decision

File: monitoring-and-alerting-principles.md

Health check endpoints (/health and /ready), metrics instrumentation using RED/USE methods, error tracking integration, circuit breakers, and graceful degradation.

Configuration Management Principles

model_decision

File: configuration-management-principles.md

Separating configuration from code, environment variables, secrets management, configuration hierarchy (CLI args → env vars → config files → defaults), and .env file organization.

---

🏗️ Architecture & Design

Rules that ensure code is well-structured and scalable.

Core Design Principles

always_on

File: core-design-principles.md

Fundamental software design rules:

• SOLID — Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
• DRY — Don’t Repeat Yourself
• YAGNI — You Aren’t Gonna Need It
• KISS — Keep It Simple, Stupid
• Separation of Concerns, Composition Over Inheritance, Principle of Least Astonishment

Architectural Pattern (Testability-First)

always_on

File: architectural-pattern.md

The core architectural approach:

1. I/O Isolation — Abstract all I/O behind interfaces
2. Pure Business Logic — No side effects in calculations
3. Dependency Direction — Dependencies point inward toward business logic

Includes pattern discovery protocol, language-specific idioms table, and enforcement checklist.

API Design Principles

model_decision

File: api-design-principles.md

Creating clean, intuitive, and versionable REST/HTTP APIs. Covers endpoints, handlers, middleware, and response formatting.

Project Structure

always_on

File: project-structure.md

The single source of truth for project organization. Enforces feature-based organization (not layer-based). Includes complete layout examples for:

• Monorepo (backend + frontend + mobile)
• Flutter/Mobile apps
• Single backend/frontend apps
• Microservices

Database Design Principles

model_decision

File: database-design-principles.md

Schema design (3NF), naming conventions, migration safety rules, query performance (parameterized queries, indexing, N+1 prevention), and transaction management.

Data Serialization & Interchange

model_decision

File: data-serialization-and-interchange-principles.md

Safe data handling for JSON, XML, YAML, Protocol Buffers, MessagePack, and other formats.

Command Execution Principles

model_decision

File: command-execution-principles.md

Principles for running external commands and shell scripts securely — preventing injection, handling exit codes, and managing process lifecycles.

Language-specific project layouts are now in Skills. Go, TypeScript/Vue, Flutter, Rust, and Python directory layouts live in their respective skill files:

• Go: .agents/skills/go-idioms/references/project-structure.md
• Vue/React: .agents/skills/vue-idioms/references/project-structure.md
• Flutter: .agents/skills/flutter-idioms/references/project-structure.md
• Rust: .agents/skills/rust-idioms/references/project-structure.md
• Python: .agents/skills/python-idioms/references/project-structure.md

---

🧩 Maintainability & Quality

Rules that ensure code is readable, testable, and long-lived.

Code Organization Principles

always_on

File: code-organization-principles.md

Feature-based organization with clear public interfaces. Module boundaries, feature interaction patterns, and wiring examples.

Code Idioms & Conventions

always_on

File: code-idioms-and-conventions.md

Write idiomatic code for the target language. Follow community conventions, use language built-ins, avoid cross-language anti-patterns. Delegates to dedicated language idiom files for ecosystem-specific guidance.

Language idioms are now Skills, not Rules. The Go, TypeScript, Vue, Flutter, Rust, and Python idiom files have been consolidated into dedicated skill directories under .agents/skills/. Load them via the code-idioms-and-conventions.md rule which delegates to the appropriate skill. See the Skills Reference for the full list.

Testing Strategy

model_decision

File: testing-strategy.md

Comprehensive testing guidance:

• Unit tests (mocked I/O, >85% coverage on domain logic)
• Integration tests (Testcontainers, real infrastructure)
• E2E tests (Playwright, full user journeys)
• Test organization and naming conventions

Dependency Management Principles

model_decision

File: dependency-management-principles.md

Managing external libraries safely — version pinning, audit, and minimizing attack surface.

Documentation Principles

model_decision

File: documentation-principles.md

Self-documenting code, when to comment (WHY, not WHAT), and documentation levels from inline comments to architecture docs.

Logging & Observability Mandate

always_on

File: logging-and-observability-mandate.md

All operation entry points MUST be logged (start, success, failure). Mandatory context: correlationId, operation name, duration, userId, error.

Accessibility Principles

model_decision

File: accessibility-principles.md

WCAG 2.1 Level AA compliance: semantic HTML, keyboard navigation, ARIA attributes, color contrast, images, and forms.

Git Workflow Principles

model_decision

File: git-workflow-principles.md

Conventional commits format, branch naming, commit hygiene, PR size guidelines (<400 lines ideal), and merge strategy.

---

🔄 DevOps & Operations

Rules that ensure the development pipeline is reliable and automated.

CI/CD, GitOps, and Feature Flags are now Skills, not Rules. These topics were migrated to dedicated skill directories:

• CI/CD Pipelines: .agents/skills/ci-cd/SKILL.md
• GitOps/Kubernetes: .agents/skills/ci-cd/references/gitops-kubernetes.md
• Feature Flags: .agents/skills/feature-flags/SKILL.md

See the Skills Reference for details.

Code Completion Mandate

always_on

File: code-completion-mandate.md

Before marking any code task as complete, you MUST run automated quality checks:

1. Generate → 2. Validate → 3. Remediate → 4. Verify → 5. Deliver

Delegates language-specific quality commands (linters, formatters, type checkers) to the respective idiom files.

Rule Priority

always_on

File: rule-priority.md

Conflict resolution when rules contradict each other. Priority order:

1. Security Mandate (always wins)
2. Rugged Software Constitution
3. Code Completion Mandate
4. Testability-First Design
5. Feature-specific principles
6. PRD-gated principles (feature flags, GitOps)
7. YAGNI / KISS