AGENTS.md

1# AGENTS.md
2 
3## Project Overview
4 
5HordeForge is an AI-first, agent-driven system for building, testing, and deploying code through deterministic pipelines.
6 
7Core principles:
8- AI Pipeline > Integrations > Platform
9- Deterministic execution over “smart” behavior
10- Simplicity over abstraction
11- Minimal infrastructure unless required
12 
13---
14 
15## Architecture Rules
16 
17- The system is agent-driven: logic is implemented via agents, not services
18- Each agent has a single responsibility
19- No hidden side effects between components
20- Avoid unnecessary layers, abstractions, or frameworks
21- Prefer explicit data flow over implicit coupling
22 
23---
24 
25## Agent Rules
26 
27- One agent = one responsibility
28- Agents must use structured input and structured output
29- No direct agent-to-agent calls (use orchestrator/pipeline)
30- Agents must be deterministic and reproducible
31- All important steps must be logged
32- Avoid hidden state and implicit context
33 
34---
35 
36## Code Rules
37 
38- Language: Python 3.11+
39- All functions must have type hints
40- Prefer `dataclasses` over plain classes
41- Use `pydantic` for validation and schemas
42- No global mutable state
43- Max file size: ~500 lines (split if larger)
44 
45Code style:
46- Follow `ruff` rules
47- Keep functions small and focused
48- Avoid duplication
49- Prefer readability over cleverness
50 
51---
52 
53## Edit Rules
54 
55- Always search for existing implementation before adding new code
56- Prefer editing existing files over creating new ones
57- Make the smallest possible change to solve the task
58- Do not rewrite entire files unless absolutely necessary
59- Do not duplicate functionality
60- Preserve existing architecture and patterns
61 
62Before major edits:
63- Understand the relevant part of the codebase
64- Identify impacted files
65- Keep changes localized
66 
67---
68 
69## Testing Workflow (MANDATORY)
70 
71- Tests must be written or updated before implementation (TDD)
72- After code changes:
73  1. Run `ruff check --fix`
74  2. Run `ruff format`
75  3. Run `pytest -v --tb=short` (only if tests exist for edited code)
76 
77Rules:
78- All tests must pass before task is considered complete
79- Do not skip or disable tests
80- Do not change tests to make failures disappear without fixing root cause
81 
82---
83 
84## Refactoring Rules
85 
86- Refactoring only allowed when tests exist
87- Must not change behavior
88- No mixing refactoring with new features
89- Keep changes incremental and verifiable
90 
91---
92 
93## Pipeline Rules
94 
95- Work follows deterministic pipeline:
96  1. Analyze
97  2. Plan
98  3. Test
99  4. Implement
100  5. Validate
101 
102- Do not skip steps
103- Do not jump directly to coding without understanding context
104 
105---
106 
107## Safety Rules
108 
109- Do not modify unrelated files
110- Do not delete files unless explicitly required
111- No destructive git operations:
112  - no force push
113  - no history rewrite
114- Do not introduce breaking changes without clear reason
115 
116---
117 
118## Failure & Stop Conditions
119 
120- Maximum 3 attempts to fix the same issue
121- Do not repeat the same fix strategy
122- If the same error persists:
123  - Stop
124  - Analyze root cause
125  - Output diagnosis instead of continuing blindly
126 
127Stop immediately if:
128- Errors repeat without progress
129- Required context is missing
130- The change would break architecture or safety rules
131 
132---
133 
134## Loop Prevention
135 
136- Do not repeat identical edits
137- Do not re-run the same failing approach
138- Always change strategy after a failed attempt
139- Prefer analysis over blind retries
140 
141---
142 
143## Expected Behavior
144 
145- Be precise and minimal
146- Prefer correct over clever
147- Explain reasoning when making non-trivial changes
148- Keep output structured and actionable
149- When blocked — stop and explain, not guess