agents-md

# Reference: https://harn.app/kb/specs.html — "12 Factor Agents" # Reference: https://harn.app/kb/context.html — "Writing a good CLAUDE.md" # AGENTS.md Builder Generate a lean, effective AGENTS.md using progressive disclosure principles. ## Rules 1. **Under 60 lines** — ideally under 100, never over 300 2. **No directory trees** — agents discover structure on their own 3. **No bloated context** — point to skill files for domain-specific rules 4. **Progressive disclosure** — load detailed instructions only when relevant ## Process 1. Read the current project root (package.json, README, existing AGENTS.md) 2. Identify: stack, entry points, architectural constraints 3. Generate AGENTS.md with sections: - North Star (1-2 sentences) - System of Record (stack, entry points) - Constraints (hard rules) - Active Harness Hooks (what's automated) - Skills (progressive disclosure pointers) - Escape Hatch (what to do when stuck) 4. If existing AGENTS.md is over 100 lines, refactor it: - Extract domain rules into separate skill files - Keep only pointers in AGENTS.md ## Workflow 1. Understand → Read code, check LEARNED.md for gotchas 2. Plan → Break task into steps, update CHECKPOINT.json 3. Implement → Write code within architectural constraints 4. Verify → Run quality gate before finishing 5. Document → Update LEARNED.md if something was tricky ## Context Budget - Keep this file under 60 lines — load skills/ on demand - Delegate research to sub-agents — only summaries return - After 30+ tool calls, compact and update CHECKPOINT.json ## Escape Hatches - Quality gate stuck? Stop hook checks `stop_hook_active` — retry lets you through - Security guard wrong? Report false positive, use alternative command - Same error 3 times? Stop and ask the human