AGENTS.md

1# codex
2 
3> Multi-agent orchestration framework for agentic coding
4 
5## Project Overview
6 
7A Claude Flow powered project
8 
9**Tech Stack**: TypeScript, Node.js
10**Architecture**: Domain-Driven Design with bounded contexts
11 
12## Quick Start
13 
14### Installation
15```bash
16npm install
17```
18 
19### Build
20```bash
21npm run build
22```
23 
24### Test
25```bash
26npm test
27```
28 
29### Development
30```bash
31npm run dev
32```
33 
34## Agent Coordination
35 
36### Swarm Configuration
37 
38This project uses hierarchical swarm coordination for complex tasks:
39 
40| Setting | Value | Purpose |
41|---------|-------|---------|
42| Topology | `hierarchical` | Queen-led coordination (anti-drift) |
43| Max Agents | 8 | Optimal team size |
44| Strategy | `specialized` | Clear role boundaries |
45| Consensus | `raft` | Leader-based consistency |
46 
47### When to Use Swarms
48 
49**Invoke swarm for:**
50- Multi-file changes (3+ files)
51- New feature implementation
52- Cross-module refactoring
53- API changes with tests
54- Security-related changes
55- Performance optimization
56 
57**Skip swarm for:**
58- Single file edits
59- Simple bug fixes (1-2 lines)
60- Documentation updates
61- Configuration changes
62 
63### Policy-Governed Concurrent Execution
64 
65- Ruflo coordinates and records policy decisions; Codex workers execute.
66- Use `guidance_brain` for live capability routing; registration is distinct
67  from configuration, reachability, health, and authorization.
68- Follow the complete loop: recall, inspect, route, plan, execute, test,
69  validate, benchmark, optimize, receipt, handoff, then authorized publish.
70- Search AgentDB before planning and store only validated patterns after success.
71- Use bounded fanout only for independent tasks.
72- Every writing worker gets a unique git worktree and a reduced capability
73  envelope. Never place two writers in one worktree.
74- Read-only researchers may share a checkout.
75- One integration agent owns shared manifests/lockfiles, consumes committed
76  handoffs in dependency order, and runs scoped then full tests.
77- Cancel dependent and not-yet-started sibling work on policy denial or dependency failure.
78- MetaHarness can benchmark candidates concurrently but cannot authorize its
79  own promotion or expand network, provider, spend, secret, or concurrency
80  scope.
81- Do not auto-commit, push, merge, release, or delete worktrees without user
82  authorization.
83- Existing projects start in ADR-324 `legacy` mode, may rehearse in `observe`,
84  and opt into `enforce` after reviewing receipts.
85- When tracked repository instructions define a local harness, assign the
86  isolated worktree first, then register a session, inspect claims, acquire
87  exact paths/resources/ports, renew leases, check acknowledged inbox messages, and
88  release ownership on handoff or exit.
89- A repository lease coordinates ownership; it does not grant authorization.
90  Protected work still requires the ADR-324/325 capability and current fencing
91  epoch.
92- In-memory reference adapters are not distributed, restart-durable release
93  authorities.
94- Heartbeats and lease expiry establish liveness; PIDs are diagnostic only.
95- `HEAD` alone is not an exact source-state identity in a dirty worktree.
96  Release receipts bind a clean commit or an immutable snapshot of tracked and
97  untracked changes.
98 
99### Available Skills
100 
101Use `$skill-name` syntax to invoke:
102 
103| Skill | Use Case |
104|-------|----------|
105| `$swarm-orchestration` | Multi-agent task coordination |
106| `$memory-management` | Pattern storage and retrieval |
107| `$sparc-methodology` | Structured development workflow |
108| `$security-audit` | Security scanning and CVE detection |
109 
110### Agent Types
111 
112| Type | Role | Use Case |
113|------|------|----------|
114| `researcher` | Requirements analysis | Understanding scope |
115| `architect` | System design | Planning structure |
116| `coder` | Implementation | Writing code |
117| `tester` | Test creation | Quality assurance |
118| `reviewer` | Code review | Security and quality |
119 
120## Code Standards
121 
122### File Organization
123- **NEVER** save to root folder
124- `/src` - Source code files
125- `/tests` - Test files
126- `/docs` - Documentation
127- `/config` - Configuration files
128 
129### Quality Rules
130- Files under 500 lines
131- No hardcoded secrets
132- Input validation at boundaries
133- Typed interfaces for public APIs
134- TDD London School (mock-first) preferred
135 
136### Commit Messages
137```
138<type>(<scope>): <description>
139 
140[optional body]
141 
142Co-Authored-By: ruflo-bot <ruflo-bot@users.noreply.github.com>
143```
144 
145Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`
146 
147## Security
148 
149### Critical Rules
150- NEVER commit secrets, credentials, or .env files
151- NEVER hardcode API keys
152- Always validate user input
153- Use parameterized queries for SQL
154- Sanitize output to prevent XSS
155 
156### Path Security
157- Validate all file paths
158- Prevent directory traversal (../)
159- Use absolute paths internally
160 
161## Memory System
162 
163### Storing Patterns
164```bash
165npx @claude-flow/cli memory store \
166  --key &quot;pattern-name&quot; \
167  --value &quot;pattern description&quot; \
168  --namespace patterns
169```
170 
171### Searching Memory
172```bash
173npx @claude-flow/cli memory search \
174  --query &quot;search terms&quot; \
175  --namespace patterns
176```
177 
178## Links
179 
180- Documentation: https://github.com/ruvnet/claude-flow
181- Issues: https://github.com/ruvnet/claude-flow/issues
182