sysadmin-chronicles/AGENTS.md

sysadmin-chronicles

@RTK.md

Multi-agent orchestration framework for agentic coding

Project Overview

A Claude Flow powered project

Tech Stack: TypeScript, Node.js Architecture: Domain-Driven Design with bounded contexts

Quick Start

Installation

npm install

Dual-Agent Note

• This repo is set up for both Claude and Codex CLI
• If shell-based delegation is needed, prefer /home/aaron/.npm-global/bin/codex instead of relying on codex being on PATH
• Use RuFlo for orchestration and Codex for execution when a second coding agent is helpful
• Use rtk for noisy shell commands to reduce token/context usage; see RTK.md

Project Map

Before substantive work, read PROJECT_MAP.md.

Use it to:

• identify relevant files before loading context
• follow hot paths and change-impact notes
• avoid known anti-patterns

Update PROJECT_MAP.md when:

• commands, routes, public APIs, or user-facing workflows change
• meaningful files/modules are added, removed, or renamed
• persistence formats or compatibility contracts change
• feature ownership or architecture changes
• major known issues are discovered or resolved

Do not update it for tiny refactors, wording tweaks, or dependency bumps that do not change workflow or structure.

Build

npm run build

Test

npm test

Development

npm run dev

Agent Coordination

Swarm Configuration

This project uses hierarchical swarm coordination for complex tasks:

Setting	Value	Purpose
Topology	hierarchical	Queen-led coordination (anti-drift)
Max Agents	8	Optimal team size
Strategy	specialized	Clear role boundaries
Consensus	raft	Leader-based consistency

When to Use Swarms

Invoke swarm for:

• Multi-file changes (3+ files)
• New feature implementation
• Cross-module refactoring
• API changes with tests
• Security-related changes
• Performance optimization

Skip swarm for:

• Single file edits
• Simple bug fixes (1-2 lines)
• Documentation updates
• Configuration changes

Available Skills

Use $skill-name syntax to invoke:

Skill	Use Case
$swarm-orchestration	Multi-agent task coordination
$memory-management	Pattern storage and retrieval
$sparc-methodology	Structured development workflow
$security-audit	Security scanning and CVE detection

Agent Types

Type	Role	Use Case
researcher	Requirements analysis	Understanding scope
architect	System design	Planning structure
coder	Implementation	Writing code
tester	Test creation	Quality assurance
reviewer	Code review	Security and quality

Code Standards

File Organization

• NEVER save to root folder
• /src - Source code files
• /tests - Test files
• /docs - Documentation
• /config - Configuration files

Quality Rules

• Files under 500 lines
• No hardcoded secrets
• Input validation at boundaries
• Typed interfaces for public APIs
• TDD London School (mock-first) preferred

Commit Messages

<type>(<scope>): <description>

[optional body]

Co-Authored-By: claude-flow <ruv@ruv.net>

Types: feat, fix, docs, style, refactor, perf, test, chore

Security

Critical Rules

• NEVER commit secrets, credentials, or .env files
• NEVER hardcode API keys
• Always validate user input
• Use parameterized queries for SQL
• Sanitize output to prevent XSS

Path Security

• Validate all file paths
• Prevent directory traversal (../)
• Use absolute paths internally

Memory System

Storing Patterns

npx @claude-flow/cli memory store \
  --key "pattern-name" \
  --value "pattern description" \
  --namespace patterns

Searching Memory

npx @claude-flow/cli memory search \
  --query "search terms" \
  --namespace patterns

Links

• Documentation: https://github.com/ruvnet/claude-flow
• Issues: https://github.com/ruvnet/claude-flow/issues