# 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
```markdown
## 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: <hash>". 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
| **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
- **RUST**: `/.rulebook/specs/RUST.md`
- **PYTHON**: `/.rulebook/specs/PYTHON.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.
```bash
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
| 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