Skip to content

AGENTS.md

Latest commit

 

History

History
210 lines (152 loc) · 10.2 KB

AGENTS.md

File metadata and controls

210 lines (152 loc) · 10.2 KB

Project Rules

Generated by @hivellm/rulebook. Spec files live in /.rulebook/specs/. This file is regenerated by rulebook update — put project overrides in AGENTS.override.md.

Tier 1 — Absolute Prohibitions (highest precedence)

These override everything else. Violation = output rejected.

  1. No shortcuts, stubs, or placeholders. No TODO/FIXME/HACK, no return 0; // stub, no simplified algorithms, no partial implementations. Implement completely or explain concretely why you can't.
  2. No destructive git ops without authorization. Forbidden: stash, rebase, reset --hard, checkout -- ., restore ., revert, cherry-pick, merge, branch -D, push --force, clean -f, checkout <branch>, switch. Allowed: status, diff, log, blame, add, commit.
  3. No deletion without authorization. Never rm/del without explicit user "yes, delete it". Caches auto-invalidate — don't manually delete them.
  4. Research before implementing. State what you KNOW and what you DON'T KNOW, then research the unknown. "I think this might be the problem" is not acceptable.
  5. Sequential file editing. Read file1 → Edit file1 → Read file2 → Edit file2. Never batch-read then batch-edit. For 3+ files, decompose into 1–2 file sub-tasks.
  6. No deferred tasks. If it's in the checklist, implement it. No "Deferred" labels. If a dependency blocks you, implement the dependency first.
  7. Follow task sequence. Execute tasks.md items in the EXACT order listed. No reordering, no cherry-picking, no starting Phase N+1 before Phase N is 100% done. The list is an ORDER, not a MENU.
  8. Execute the full task in one turn. Never stop mid-task to ask "should I proceed?" or "want me to also...?". Make autonomous decisions within scope. Only ask for genuine ambiguity, destructive ops, or impossible tasks.

Critical Rules

  • ALWAYS read /.rulebook/specs/RULEBOOK.md before creating tasks.
  • Use Rulebook MCP tools (mcp__rulebook__*) for task management. Never mkdir + Write in .rulebook/tasks/ — the structural enforcement hook will block you.
  • Never run destructive deletions (rm -rf) in this repository.
  • Temporary files: must live in /scripts and be removed immediately after use.
  • Diagnostic-first: run type-check/lint before tests.
  • Fail twice → escalate: if a fix fails twice with the same approach, stop and research/ask.
  • Quality gates before commit: type-check + lint (zero warnings) + tests (100% pass) + coverage (≥95%). Pre-commit hooks enforce this — never --no-verify.

Task Management (MANDATORY)

File structure

.rulebook/tasks/<task-id>/
├── proposal.md     # Why and What Changes (≥20 char Why section)
├── tasks.md        # ONLY checklist items, no explanations
├── design.md       # Optional: technical design
└── specs/<module>/spec.md   # Technical specs (SHALL/MUST + Given/When/Then)

Rules:

  • tasks.md = simple - [ ] / - [x] only. No long explanations.
  • proposal.md = detailed Why + What Changes.
  • specs/ = technical requirements with SHALL/MUST keywords.
  • NEVER create README.md, PROCESS.md, or any other file in task directories.

Spec format

## ADDED Requirements
### Requirement: <Name>
The system SHALL/MUST <do something>.

#### Scenario: <Name>
Given <context>
When <action>
Then <outcome>

Use ## ADDED, ## MODIFIED, ## REMOVED, ## RENAMED headers. Scenarios use 4 hashtags (not 3, not bullets).

Workflow

  1. Always create the task BEFORE coding — never mkdir manually, always rulebook_task_create.
  2. Pick the first unchecked item from the lowest-numbered phase.
  3. Read proposal.md and tasks.md before touching code.
  4. Implement → run lint + type-check → mark [x] → next item.
  5. Update task status with rulebook_task_update.
  6. The mandatory tail (docs + tests + verify) is not optional — rulebook_task_archive will refuse without it.

Deferred-items protocol

If you must defer an item before archiving, you MUST create a follow-up rulebook task for it BEFORE calling archive. No orphan deferred items.

Agent Automation Workflow

After ANY implementation, execute in order:

  1. Quality checks (all must pass): type-check → lint (0 warnings) → format → tests (100%) → coverage (≥95%). Stop and fix on any failure.
  2. Capture to memory: rulebook_memory_save for decisions, patterns, gotchas, bug fixes.
  3. Security audit: npm audit --production (or language equivalent).
  4. Update task: rulebook_task_update + mark items [x].
  5. Update docs: CHANGELOG (conventional commits), README if public API changed.
  6. Commit (English only): <type>(<scope>): <description> — types: feat, fix, docs, refactor, perf, test, build, ci, chore.
  7. Report minimally: "Done. Committed: ". Skip emoji tables, "Next Steps" sections, status boxes.

Skip steps only with explicit user permission.

Persistent Memory

Backed by Rulebook MCP server (BM25 + HNSW hybrid search). Memory persists across sessions.

  • Start of session: rulebook_memory_search for relevant past context.
  • During work: rulebook_memory_save for decisions, bugs, discoveries, user preferences.
  • End of session: rulebook_session_end writes a summary.

3-layer search pattern: rulebook_memory_search (compact) → rulebook_memory_timeline (window) → rulebook_memory_get (full details).

Knowledge Base

Before non-trivial work:

  • rulebook_knowledge_list — patterns/anti-patterns
  • rulebook_learn_list — past learnings
  • rulebook_decision_list — architecture decisions

After implementing, capture ≥1 entry per task:

  • rulebook_knowledge_add for reusable patterns
  • rulebook_learn_capture for insights that don't belong in code
  • rulebook_decision_create for significant architectural choices

Dependency Architecture (DAG)

  • No circular dependencies. Validate with the project's check tool (tsc --noEmit, cargo check, madge --circular, etc.).
  • Layers: Foundation → Core → Features → Presentation. Higher layers depend on lower; never the reverse.
  • Use interfaces for cross-layer communication. No tight coupling.

Documentation Standards

  • All docs in English.
  • Root: README.md, CHANGELOG.md, AGENTS.md, LICENSE, CONTRIBUTING.md, SECURITY.md only.
  • Everything else → /docs.
  • Update by commit type: feat → README + CHANGELOG "Added"; fix → CHANGELOG "Fixed"; breaking → migration guide; perf → benchmarks.

Quality Enforcement (NON-NEGOTIABLE)

Forbidden:

  • .skip(), .only(), .todo() to bypass tests
  • Commenting out failing tests
  • @ts-ignore / @ts-expect-error to hide errors
  • Mocking just to make tests pass
  • --no-verify on commit/push
  • Boilerplate tests without assertions
  • Workarounds instead of root-cause fixes

Required: fix root causes, write meaningful tests, follow proven solutions.

Token Optimization

Tier Use for Style
Research (haiku) Read-only exploration Code over prose, "Done" reports
Standard (sonnet) Tests, implementation Brief 2-3 sentence summaries
Core (opus) Complex bugs, architecture Full reasoning when needed

Avoid: emoji status tables, "Next Steps" sections, repeating the question, markdown abuse.

Language & Framework Rules

  • LUA: /.rulebook/specs/LUA.md

Module Rules

  • AGENT_AUTOMATION: /.rulebook/specs/AGENT_AUTOMATION.md
  • MULTI_AGENT: /.rulebook/specs/MULTI_AGENT.md

Ralph Autonomous Loop

5-gate quality enforcement (type-check, lint, tests, coverage, security) per iteration, fresh context per iteration, parallel story execution, plan checkpoints, learning extraction.

rulebook ralph init                    # Generate PRD from tasks
rulebook ralph run --max-iterations 10
rulebook ralph status / history / pause / resume

PRD format: userStories array with id, title, description, acceptanceCriteria, priority, passes: boolean, notes. Status tracked via passes, NOT enum.

Iteration records in .rulebook/ralph/history/iteration-N.json. Status: success (5/5 gates), partial (2-4), failed (0-1).

Multi-Agent Teams

Requires CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Background Agent calls must use a Team (team_name parameter) — standalone background agents can't communicate via SendMessage. Foreground calls and team-lead agents are exempt.

Standard team: team-lead (orchestrator) + researcher (haiku) + implementer (sonnet) + tester (sonnet).

Workspace Mode

If this is part of a multi-project workspace, every Rulebook MCP call MUST pass projectId. Use rulebook_workspace_list to map file paths → projects. Cross-project ops: rulebook_workspace_search, rulebook_workspace_tasks. Each project has isolated .rulebook/.

Agent Delegation

Task Agent Model
Implementation implementer sonnet
Research researcher haiku
Tests tester sonnet
Docs docs-writer haiku
Code review code-reviewer sonnet
Architecture architect opus
Build/CI build-engineer sonnet
Security security-reviewer haiku

Rules: never write code directly in main conversation — delegate. Use haiku for read-only tasks. Launch independent agents in parallel.

Plans & Session Continuity

  • .rulebook/PLANS.md — persistent session scratchpad. Read at start, update during, summarize at end.
  • .rulebook/STATE.md — machine-written live status.
  • Handoff at context limits: /handoff skill writes .rulebook/handoff/_pending.md, then /clear.

Decision Records

ADRs in .rulebook/decisions/ with lifecycle: proposed → accepted → superseded/deprecated. Never delete — supersede instead. Use rulebook decision create/list/show/supersede.

Detailed Specs

For full detail, see /.rulebook/specs/:

  • TIER1_PROHIBITIONS.md — absolute rules
  • RULEBOOK.md — task management
  • QUALITY_ENFORCEMENT.md — quality gates
  • GIT.md — git workflow
  • TOKEN_OPTIMIZATION.md — verbosity by tier
  • AGENT_AUTOMATION.md, MULTI_AGENT.md, RULEBOOK_MCP.md — module specifics