feat: add workflow CLI commands (Refs: beans-mmyp)

[teal-bauer]

Summary

• 8 new commands for common workflows that previously required beans update -s <status>:
  • Status transitions: complete, scrap, start — with guardrails (scrap requires a reason, start warns on blocked beans)
  • Query shortcuts: ready, next, blocked — quick access to actionable beans
  • Reporting: milestones, progress — project-level overviews with completion percentages
• Shared resolveBean() helper extracted from update.go to DRY up the resolve+archive pattern
• prompt.tmpl updated so agents learn about the new commands

Test plan

• go build ./... compiles
• go test ./... all tests pass (13 new tests in workflow_test.go)
• Manual smoke test: all 8 commands with --json and human output
• Test beans scrap without --reason flag (should error)
• Test beans start on a blocked bean (should warn, --force should override)
• Test beans complete on already-completed bean (should warn, continue)

[hmans]

Have to give this one some more thought. I specifically wanted to keep the command surface lean (unlike the other project that inspired it.) This would break with that goal.

[teal-bauer]

The workflow commands make agent use so much smoother — agents can just beans complete, beans start, beans next instead of juggling beans update <id> -s ... flags. They're also just nice to have as a human, honestly.

[teal-bauer]

I understand about the CLI surface, but this feels so much more natural, and internally it's just relatively simple shortcuts. I feel it doesn't bring it nowhere near the overburdening complexity of you-know-what.

[rektide]

Wht about a beans do complete.

Adding 8 new top level commands feels extremely bad to me, and explodes the apparent surface massively.

Adding 1 new top level command that has some subcommands to it feels managable and isolated.

[teal-bauer]

Top level command is a construct, I'm not sure I understand what "do" gives us that e.g. hiding the 8 from standard help output wouldn't. I would never type "beans do ready" or something, I think ..

[rektide]

I'm not sure I understand what "do" gives us that e.g. hiding the 8 from standard help output wouldn't.

A human user experience that isn't incredibly daunting and overwhelming? I'm trying to help you find a way to overcome an objection I too share with the author of this fine project:

I specifically wanted to keep the command surface lean (unlike the other project that inspired it.) This would break with that goal.

And I agree with the author! No way in hell do I want all these extra commands at the top level! That would be super hard to sort through, for very little value!

But I thought maybe we could still help you out and give you some commands you want, by adding them to a do subcommand would keep the ux from becoming overwhelming. I take it your objection is more than the name? beans make ready is still not going to make you happy?

I really dont want to see these commands added to the top level. NACK on that from me (a total random whose vote counts for nothing).

[hmans]

Briefly chiming in (hi!) so you know I'm following this discussion.

I'm still mostly undecided about the proposed change, but this isn't necessarily due to the change itself, but rather my own reflection about how much Beans should cater to humans compared to agents (with a scope much larger than just the CLI command surface.)

So far I've been describing Beans as a "task manager for humans and robots". That Beans provides a meaningful interface to humans (as opposed to just robots) is a core feature that will not go away, but I've been reevaluating what that means in practice.

And I'm basing this reevaluation on my own usage of the CLI, which is 100% through the agent. So to me personally, as a user of Beans, and the type of user of Beans that I am, it makes zero difference whether

• the CLI gets all these extra commands
• the CLI gets these commands, but nests them under a do umbrella command or similar
• doesn't get these commands at all because the agent is just fine with the existing CLI surface

...which in my very subjective view would be an argument for just leaving things as they are now solely because every added bit of surface is an added promise for future maintenance that I risk breaking at some point down the road.

I do understand that there are users who work more directly and manually with Beans, and who would likely benefit from these short of commands (because they're more intuitive than what Beans has today. I totally get that.)

I just don't know how large a percentage of the Beans user base this is, and whether future versions of Beans will cater to them. Ultimately, Beans remains a highly opinionated, curated tool that I'm writing to support my own workflows, in the hopes that it also helps other people, and my workflows are fully agentic, and moving towards web-based agent orchestration UIs (Conductor, Jean et al), which is a space I continue to explore for Beans for the reasons stated above.

So, tl;dr... no decision yet. So I'm happy to hear more input, especially from people who're driving the CLI manually more than I do.

[teal-bauer]

@hmans I am also using this primarily with agents and it feels much faster if they do "beans complete xy7j". Of course, for the occasional human interaction, it's even more of a benefit. I honestly don't think I understand the "command surface" bits, isn't that a question of how to display/expose/format things? i.e. beans help probably shouldn't list 8 more things that are already reachable otherwise, but it could have a single line for beans [complete|scrap|...] <bean> and one for beans next|ready.

[teal-bauer]

I'm not sure I understand what "do" gives us that e.g. hiding the 8 from standard help output wouldn't.

A human user experience that isn't incredibly daunting and overwhelming? I'm trying to help you find a way to overcome an objection I too share with the author of this fine project:

I specifically wanted to keep the command surface lean (unlike the other project that inspired it.) This would break with that goal.

And I agree with the author! No way in hell do I want all these extra commands at the top level! That would be super hard to sort through, for very little value!

I believe you are conflating the "accessible at top level" with the "exposed/visible/displayed at top level". It is absolutely possible to have a beans complete ab3d command without having every variant show up in beans help or similar. Adding an extra subcommand for all those kinda defies the purpose of easy accessibility.

As a side note, I didn't even come up with this, it was an existing bean in this repo https://github.com/hmans/beans/blob/main/.beans/beans-mmyp--workflow-cli-commands.md that I saw and thought "oh yeah, this would be super nice to have". I still feel that way :)