docs(readme): split Use cases into its own section + fix Why-prose authorship#87
Merged
Merged
Conversation
…Why-prose authorship Two README polish changes: 1. **Why section authorship.** Previous prose said "You describe the flow in YAML (your agent writes it for you)" — contradictory. Users don't write YAML; they describe the codebase area in English and the agent writes the YAML. Rewrote as: "You ask in plain English; your agent writes the flow as YAML and pushes it; OpenHop renders…" 2. **Move prompts to a dedicated `## Use cases` section.** The 8 example prompts added in #86 were inline inside "Give your agent the skill" alongside install instructions, which mixed two concerns: setup-once vs use-every-day. Split them: the install section keeps the install steps and a one-line pointer; the new Use cases section is a discoverable section users can deep-link to (anchor added to the top-of-README nav). Also added a one-line trigger-shape note ("explain / walk through / trace / visualize / diagram _ flow") at the bottom of Use cases — it's the same activation phrase pattern documented in 17-install-and-activation-flow.md, surfaced for users who want to know what the skill actually matches on. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughREADME.md updates: navigation adds "Install" and "Use cases"; "Why" clarifies YAML-authored animated data-flow rendering with node drill-down; "Install" rewrites setup into agent-skill + CLI/server paths; "Use cases" and activation text now show trigger-phrase patterns that produce YAML + animation. ChangesDocumentation Structure & Installation Guidance
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
…s / agent-driven / contributor) Previous Install table mixed two orthogonal axes — server-side commands (demo, serve) and agent-side commands (init, openskills) — listed as peers, which made it look like the user picks one. Reality: most users need *both* a server (so flows render) and a skill (so the agent knows how to call openhop). Restructured into three labeled paths: - Path A: just see what it does → `npx openhop demo`. One command. - Path B: real agent-driven use → 3 explicit steps: 1. install the skill (init or openskills) 2. run the server long-lived (`npx openhop serve`) 3. ask the agent for a flow - Path C: contributor → clone, npm install, npm run dev. Also dropped the now-redundant "## Give your agent the skill" section (its content is folded into Path B). Updated nav anchor from "AI skill" → "Install" since the install section now covers skill setup explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…o a preview. Previous Install section listed Path A (kicking the tires via demo) and Path B (agent-driven, multi-step) as peers. That framing was wrong: OpenHop has no use without an AI agent. The product is the skill; the CLI just paints the pixels. Restructured to put the skill install front-and-center: - Path A (Tier-1, auto-detect): `npx openhop init` - Path B (Tier-2, via OpenSkills): `npx openskills install …` Both paths are about HOW to install the skill (the only required step). After install, the agent boots `openhop serve` automatically when it needs to render — the user doesn't run a server unless they want to. `openhop serve` and `openhop demo` are now positioned as optional / preview commands beneath the skill install paths, with explicit framing: serve = "if you'd rather pre-start it yourself", demo = "just looking, no agent involved." That matches how a first-time user actually consumes the README. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 128: Update the activation pattern line that currently reads "explain /
walk through / trace / visualize / diagram _ flow" to accurately reflect the
examples or make the examples match the pattern; either change the pattern
string to a broader description such as "Ask the agent to explain, walk through,
trace, visualize, or diagram any system behavior or data flow" (update the
quoted pattern text in README.md) or revise examples 3–8 so they include one of
the listed verbs and the word "flow" (or otherwise match the new pattern)
ensuring consistency between the pattern text and the example prompts.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 12ccfe7c-0770-4f32-a0b7-e34663bf0790
📒 Files selected for processing (1)
README.md
Each prompt was wrapped in _underscores_ for italics, which renders visibly slanted on GitHub and reads as noisy formatting on a straightforward bulleted list. Plain-quoted strings carry the "agent prompt" signal on their own. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Each path now shows just the command. Section headers carry the context (which clients each path is for) and the commands speak for themselves. Removes ~5 paragraphs of "what this does" prose that was restating what the section header already said. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
♻️ Duplicate comments (1)
README.md (1)
128-128:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winPattern text is still stricter than the examples.
Line 128 says prompts must match
"explain / walk through / trace / visualize / diagram _ flow", but several examples on Line 119-Line 127 use other verbs or omit “flow”. Please either broaden the pattern sentence or normalize the examples so users can predict activation reliably.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@README.md` at line 128, The README's activation pattern "explain / walk through / trace / visualize / diagram _ flow" is too strict relative to examples; update the sentence to accept those verbs with optional suffixes (e.g., allow "explain|walk through|trace|visualize|diagram|illustrate|describe" and make "flow" optional or allow "the flow"/"flow of" variants) or alternatively normalize the examples on lines 119–127 to all include the exact phrase; modify the pattern sentence so it clearly states the verbs list and that "flow" is optional (or update example prompts to match the quoted pattern) to ensure consistent, predictable activation.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Duplicate comments:
In `@README.md`:
- Line 128: The README's activation pattern "explain / walk through / trace /
visualize / diagram _ flow" is too strict relative to examples; update the
sentence to accept those verbs with optional suffixes (e.g., allow "explain|walk
through|trace|visualize|diagram|illustrate|describe" and make "flow" optional or
allow "the flow"/"flow of" variants) or alternatively normalize the examples on
lines 119–127 to all include the exact phrase; modify the pattern sentence so it
clearly states the verbs list and that "flow" is optional (or update example
prompts to match the quoted pattern) to ensure consistent, predictable
activation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: 9c06a4cd-cfcc-4be9-bda3-981d3c06113a
📒 Files selected for processing (1)
README.md
CodeRabbit (PR #87 review) caught a mismatch between the pattern description and the example prompts above it. The previous text suggested every prompt must use one of five verbs *and* include the word "flow" — but several listed examples (state machines, "Show me how the checkout pipeline processes…", "How does cache invalidation work?", etc.) don't fit that strict shape. Rewrote the pattern line to describe the broader activation surface the examples actually demonstrate: prompts asking the agent to explain / walk through / trace / visualize / diagram how something works in code — flows, request paths, lifecycles, state machines, processing pipelines, click-to-action traces. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… trigger list
Per review: the README's activation pattern should match the skill's
own declared triggers. Updated to mirror SKILL.md:3 frontmatter
verbatim:
Verbs (6): understand, explain, walk through, trace, visualize, diagram
Subjects: data, requests, control, auth, or state flows through code
Previous README had only 5 verbs (missing "understand") and described
the subjects as a vaguer list ("flows, paths, lifecycles, state
machines, ..."). The skill router phrase-matches on the SKILL.md
frontmatter, so the README description should be identical to maximise
the chance that what users see in the README is what actually
activates the skill.
Also added a pointer to the full per-phrase trigger list in
skills/openhop/SKILL.md (lines 19-30) for users who want to dig in.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per request. The README now lists 5 verbs (explain, walk through, trace, visualize, diagram) where the skill's frontmatter has 6 (includes "understand"). The skill router still phrase-matches "understand" — so user prompts using that verb still activate the skill — the README just describes the more concrete subset. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 11, 2026
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
1 participant
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
Two README polish fixes following #86:
1. Fix Why-section prose
Previous text:
That contradicts itself. Users don't write YAML — they describe the codebase area in plain English and the agent emits the YAML. Rewrote as:
2. Split prompts into a dedicated
## Use casessection#86 added 8 example prompts but inlined them inside "Give your agent the skill," mixing two concerns (one-time install vs every-day usage). Split them:
## Use casessection is the home of the prompt examples + a one-line trigger-shape note ("explain / walk through / trace / visualize / diagram _ flow").#use-casesadded to the top-of-README nav so it's discoverable from the page header.Diff
README.mdTesting
npx prettier --check README.md→ clean#use-casesresolves to the new heading (GitHub auto-generates anchors from## Headingtitles)Linked context
Direct follow-up to #86 (which created the prompt examples). No new audit items closed by this change — it's structural / prose polish.
🤖 Generated with Claude Code
Summary by CodeRabbit