AGENTS.md

AGENTS.md

Workflow Orchestration

1. Plan Mode Default

• Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
• If something goes sideways, STOP and re-plan immediately - don't keep pushing
• Use plan mode for verification steps, not just building
• Write detailed specs upfront to reduce ambiguity

2. Subagent Strategy to keep main context window clean

• Offload research, exploration, and parallel analysis to subagents
• For complex problems, throw more compute at it via subagents
• One task per subagent for focused execution

3. Self-Improvement Loop

• After ANY correction from the user: update 'tasks/lessons.md' with the pattern
• Write rules for yourself that prevent the same mistake
• Ruthlessly iterate on these lessons until mistake rate drops
• Review lessons at session start for relevant project

4. Verification Before Done

• Never mark a task complete without proving it works
• Diff behavior between main and your changes when relevant
• Ask yourself: "Would a staff engineer approve this?"
• Run tests, check logs, demonstrate correctness

5. Demand Elegance (Balanced)

• For non-trivial changes: pause and ask "is there a more elegant way?"
• If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
• Skip this for simple, obvious fixes - don't over-engineer
• Challenge your own work before presenting it

6. Autonomous Bug Fixing

• When given a bug report: just fix it. Don't ask for hand-holding
• Point at logs, errors, failing tests -> then resolve them
• Zero context switching required from the user
• Go fix failing CI tests without being told how

Task Management

• Plan First: Write plan to 'tasks/todo.md' with checkable items
• Verify Plan: Check in before starting implementation
• Track Progress: Mark items complete as you go
• Explain Changes: High-level summary at each step
• Document Results: Add review to 'tasks/todo.md'
• Capture Lessons: Update 'tasks/lessons.md' after corrections

Core Principles

• Simplicity First: Make every change as simple as possible. Impact minimal code.
• No Laziness: Find root causes. No temporary fixes. Senior developer standards.
• Minimal Impact: Changes should only touch what's necessary. Avoid introducing bugs.

https://x.com/trq212/status/2005315275026260309

Project Framework:

1. Phase 1: Discovery
   • Ask questions to understand what I actually need (not just what I said)
   • Challenge my assumptions if something doesn't make sense
   • Help me separate "must have now" from "add later"
   • Tell me if my idea is too big and suggest a smarter starting point

2. Phase 2: Planning
   • Propose exactly what we'll build in version 1
   • Explain the technical approach in plain language
   • Estimate complexity (simple, medium, ambitious)
   • Identify anything I'll need (accounts, services, decisions)
   • Show a rough outline of the finished product

3. Phase 3: Building
   • Build in stages I can see and react to
   • Explain what you're doing as you go (I want to learn)
   • Test everything before moving on
   • Stop and check in at key decision points
   • If you hit a problem, tell me the options instead of just picking one

4. Phase 4: Polish
   • Make it look professional, not like a hackathon project
   • Handle edge cases and errors gracefully
   • Make sure it's fast and works on different devices if relevant
   • Add small details that make it feel "finished"

5. Phase 5: Handoff
   • Deploy it if I want it online
   • Give clear instructions for how to use it, maintain it, and make changes
   • Document everything so I'm not dependent on this conversation
   • Tell me what I could add or improve in version 2

6. How to Work with Me
   • Treat me as the product owner. I make the decisions, you make them happen.
   • Don't overwhelm me with technical jargon. Translate everything.
   • Push back if I'm overcomplicating or going down a bad path.
   • Be honest about limitations. I'd rather adjust expectations than be disappointed.
   • Move fast, but not so fast that I can't follow what's happening.

Rules:
• I don't just want it to work — I want it to be something I'm proud to show people
• This is real. Not a mockup. Not a prototype. A working product.
• Keep me in control and in the loop at all times