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

• Use subagents liberally 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

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

Architecture Guidelines (Modular Clean Architecture + Vertical Slicing)

Core Philosophy

• Prefer modular, feature-based architecture (vertical slicing) over layered monoliths
• Each feature should be self-contained (UI → application → domain → infrastructure)
• Minimize cross-feature dependencies
• Optimize for changeability, testability, and clarity

SOLID Principles

• Single Responsibility: Each module/class has one reason to change
• Open/Closed: Extend behavior without modifying existing code
• Liskov Substitution: Subtypes must be interchangeable with base types
• Interface Segregation: Prefer small, focused interfaces
• Dependency Inversion: Depend on abstractions, not concrete implementations

OOP Best Practices

• Encapsulate behavior with data (avoid anemic models)
• Prefer composition over inheritance
• Use clear domain models and meaningful naming
• Keep objects small and focused

GRASP Principles

• High Cohesion: Keep related logic together
• Low Coupling: Minimize dependencies between modules
• Information Expert: Place behavior where the data lives
• Creator: Assign object creation responsibility logically
• Controller: Use application services to coordinate workflows

Clean Architecture

• Separate concerns into:

  • Domain (business rules, entities, value objects)
  • Application (use cases, orchestration)
  • Infrastructure (DB, APIs, external systems)
  • Interface/UI (controllers, endpoints, UI)

• Dependencies always point inward (toward domain)

• Use interfaces/adapters to isolate external systems

Vertical Slicing (Preferred Style)

• Organize by feature, not by layer:

/features
  /orders
    /domain
    /application
    /infrastructure
    /api

• Each slice contains everything needed for that feature
• Avoid shared "god" layers — share only when necessary
• Favor duplication over tight coupling when appropriate

Clean Code Practices

• Use meaningful, intention-revealing names
• Keep functions small and single-purpose
• Avoid deep nesting and complex conditionals
• Write code that reads like prose
• Prefer explicitness over cleverness

Testing Strategy

• Unit tests for domain logic
• Integration tests for feature slices
• End-to-end tests for critical flows
• Test behavior, not implementation details

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