add --help-quickstart flag with single-source quickstart guide#1
Open
brothers-morrison wants to merge 8 commits intoohare93:mainfrom
Open
add --help-quickstart flag with single-source quickstart guide#1brothers-morrison wants to merge 8 commits intoohare93:mainfrom
brothers-morrison wants to merge 8 commits intoohare93:mainfrom
Conversation
…uide Embed quickstart content from internal/cli/quickstart.md into the binary via go:embed so 'juggle --help-quickstart' prints the full setup guide. Add quickstart URL to --help output. README Quick Start section is now auto-synced from the same source file via scripts/sync-quickstart.sh.
Render quickstart.md with ANSI styling instead of raw plaintext. Uses lipgloss (already a dependency) to style headers, code blocks, blockquotes, and inline formatting for headless terminal environments.
Parse spec.md and PRD.md files to auto-generate balls from H2 sections. Available as 'juggle import spec' and 'juggle balls-from-spec', with dry-run support, duplicate detection, and priority/model-size tag parsing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
I was having trouble remembering the set of commands (session, add folders, add balls, agent run?) to get juggle going on a new project. I love the idea of juggle and it's filling a need that I had to be able to better see, understand, and prioritize work/tasks/balls that I want to run with agents (thanks for building this!). Further, I'm trying to get the most out of my AI subscriptions, so I'm attempting to seek out and understand how to run and manage agent loops in parallel. This seemed like an excellent tool for that, but with a steep learning curve. (I still have not got 2x OpenCode sessions at the same time, should I be using nohup juggle or Ctrl+Z then bg ??? or... multiple agent run on multiple sessions??? sorry if I'm just being thick)
So anyways this PR attempts to lessen the learning curve at least for starting a single agent with a single juggle task, making it easier for a beginner to get started especially for the 2nd or 3rd time when he (me) can't remember the correct command order, or what all is required for getting juggle working.
Changes
Adds command line arg --help-quickstart (colorized markdown with lipgloss), which shows the same quickstart section from the readme, but this time on the command line, so that I don't have to leave my vm/cloud machine to go look it up again.
Refactor quickstart text into it's own separate .md file, so that it can be included into readme.md (same as before, no changes) but have that same text also shown as a response to command arg --help-quickstart
by placing it in it's own file, the hope is that it can be edited in one place only (for future) single source of truth (SSOT) and still be up-to-date in both other places (readme.md and command line arg content).
third part is adding to the "juggle import spec" functionality to look for a spec.md or PRD.md file and convert that into balls.
it uses ## headers to divide the markdown file up into separate tasks/balls. Just trying to save time and make this more interoperable so that I don't have to transpose a bunch of stuff by hand if I've already got a Spec.md file written (usually partially or fully by AI tools).
Testing
devbox run test-quietpassesgo test ./internal/specparser/...— 20 test functions covering H2 parsing, priority/model-size tags, checkbox/bullet/numbered lists, directory scanning, case-insensitive file detection, realistic PRD input, and edge cases (empty files, no criteria, no context, missing files)juggle --help-quickstartprints styled quickstart guide with ANSI colors (headers, code blocks, blockquotes, inline bold/code)juggle --helpshows new--help-quickstartflag and quickstart URLjuggle import spec --dry-runon a sample spec.md correctly previews parsed balls with title, priority, model size, acceptance criteria, and source filejuggle import speccreates balls, skips duplicates on re-run, and tags withspec:<filename>scripts/sync-quickstart.shsyncs quickstart.md content into README between markers without corrupting surrounding contentChecklist
juggle --helpupdated to include--help-quickstartflag and quickstart URLinternal/specparser/specparser_test.go) with 20 test functions for the spec parserinternal/specparserpackage follows existing package conventions (exported types,_test.goin same package)init()consistent with existing command registration patterngo:embedconsistent with Go best practices for static assets