chore: add PLAN.md

[brillout]

@suleimansh We can have a call about this if you want. In the meantime, feel free to disagree with anything, and let me know if you have questions.

I've seen more than enough potential value. I think we can and should proceed with The Framework (and go all-in with it).

The plan isn't fixed yet: I'll further think & scrutinize everything (very well worth it).

[suleimansh]

Re your "can we access Claude's usage limits?" TODO: no, we can't. The 5h/weekly quota is server-side only. Nothing reads it: no API, no CLI flag, no JSON output, no local file. Admin/Analytics APIs cover pay-per-token spend, not subscription quota. Only the interactive /usage screen shows it, reset time included.

So "check the limit, fire if there's capacity" isn't buildable. The workable flip: fire until we hit the wall, parse the reset time from the error ("hit your session limit, resets 3:45pm"), sleep the queue until then. Brittle (depends on that error text) and loses "pick a cheaper model when low", but still stops us wasting daily quota, which is the point.

(fallbackModel won't help: it fires on overload/safety, not quota. Quota hits are terminal.)

[brillout]

Only the interactive /usage screen shows it, reset time included.

Maybe we can use that then? Tricky to implement? (It's brittle, but worst case it degrades the "Usage maxing" feature.)

The workable flip: fire until we hit the wall [...] but still stops us wasting daily quota, which is the point.

Agreed. If parsing the /usage commend is complex, we can still implement the "eager strategy".

[brillout]

@suleimansh Can I merge?

[suleimansh]

/usage scraping is possible (drive the TUI in a pty, send /usage, scrape the panel) but it's the brittlest path: a whole interactive UI to parse, unsupported, breaks on updates. So eager strategy first, /usage scraping later only if we want the proactive "don't fire when low" bit.

And merge away, shape the plan however you see right. Your call, I'm on board.

[brillout]

it's the brittlest path

I agree in the sense that it makes scraping harder as we'd have to maintain one pattern matching regex per breaking version. I'd say the bottom line is this: how much effort is it to scrape the /usage command? If it isn't too much effort, then maybe it's worth it. But let me know further think and dig into prioritization.

Alternative: we ask a cheap AI model to parse the /usage stdout for us => 99% reliable (if not 100%).