# Project-Specific Agent Instructions

## YOUR MANDATE
0. **Use the beads CLI workflow**: You will always use the beads cli for your work as explained in tool_preferences
1. **Simplicity First**: Always advocate for the simplest solution that works. Reject complexity unless it is proven necessary.
2. **DRY & YAGNI**: These are your non-negotiable pillars. Identify redundancy and premature optimization immediately.
3. **Clarity over Verbosity**: Your advice must be clear, concise, and devoid of fluff. Do not be overly descriptive. Get to the point.
4. **Generalization**: Provide advice that applies across languages and frameworks. Focus on the *pattern*, not the *syntax*.
5. **Documentation**: You should document only what is important to the work undertaken, do not fluff or bloat repos with markdown documents.
6. **Tests**: You will **never** force a test to pass if it already exists, if the test is flawed then point out do not act without permission.
7. **Committing**: You will **never** commit until all agents have completed their work, you will also **never** commit to a remote without explicit permission.
8. **Commit Hygiene**: Checkpoint work via commit only after validating tests pass and stability. Ensure clean commit hygiene.

### CORE PRINCIPLES TO ENFORCE
- **Single Source of Truth**: Data and logic should exist in one place only.
- **Just-in-Time Design**: Build only what is required for the current iteration.
- **Code is Liability**: Less code means fewer bugs. Delete unused code ruthlessly.
- **Explicit over Implicit**: Magic is bad. Clear flow is good.
- **Check progress**: Always check previous progress with the agent progress tool.
- **Delegate in Plan mode**: When in Plan mode, you can always delegate when user tells you to.

### WORK DISCIPLINE (from Sisyphus methodology)

#### Todo Management (MANDATORY for multi-step tasks)
- **Create todos BEFORE starting** any task with 2+ steps
- **Mark in_progress** before starting each step (only ONE at a time)
- **Mark completed IMMEDIATELY** after each step (NEVER batch completions)
- **Update todos** if scope changes before proceeding
- Todos provide user visibility, prevent drift, and enable recovery

#### Code Quality
- **No excessive comments**: Code should be self-documenting. Only add comments that explain WHY, not WHAT.
- **No type suppressions**: Never use `as any`, `@ts-ignore`, `@ts-expect-error`
- **No empty catch blocks**: Always handle errors meaningfully
- **Match existing patterns**: Your code should look like the team wrote it

#### Agent Delegation
- **Use @mentions** to invoke specialized subagents: `@explore`, `@librarian`, `@oracle`, `@frontend-ui-ux-engineer`
- **Frontend visual work** (styling, layout, animation) → delegate to `@frontend-ui-ux-engineer`
- **Architecture decisions** or debugging after 2+ failed attempts → consult `@oracle`
- **External docs/library questions** → delegate to `@librarian`
- **Codebase exploration** → delegate to `@explore`

#### Failure Recovery
- Fix root causes, not symptoms
- Re-verify after EVERY fix attempt
- After 3 consecutive failures: STOP, revert to working state, document what failed, consult oracle

#### Completion Criteria
A task is complete when:
- [ ] All planned todo items marked done
- [ ] Build passes (if applicable)
- [ ] User's original request fully addressed