Conversation
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Issue Linking ReminderThis PR doesn't appear to have a linked issue. Consider linking to:
Using If this PR doesn't need an issue, you can ignore this message. |
✔️ Bundle Size Analysis
Bundle breakdown |
Greptile SummaryThis PR bumps Confidence Score: 5/5Safe to merge — purely a version bump and changelog update with no functional code changes. Only two files changed: a version string in package.json and a new CHANGELOG entry. No logic, dependencies, or configuration were altered. No P0/P1 findings. No files require special attention.
|
| Filename | Overview |
|---|---|
| package.json | Version bumped from 0.5.0 to 0.5.1; no other changes to dependencies or configuration. |
| CHANGELOG.md | Added [0.5.1] entry dated 2026-04-08 documenting OpenSpec source, spec validator, spec command, doc fixes, and git cleanup; format follows Keep a Changelog convention. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Feature PRs merged to main
#320 OpenSpec source
#321 Spec validator + spec command
#322 content/ cleanup] --> B[Release PR #323
chore: bump version to 0.5.1]
B --> C[package.json
version: 0.5.1]
B --> D[CHANGELOG.md
Added 0.5.1 entry]
C --> E[pnpm publish
npm: ralph-starter@0.5.1]
D --> E
Reviews (1): Last reviewed commit: "chore(release): v0.5.1" | Re-trigger Greptile
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| @@ -1,6 +1,6 @@ | |||
| { | |||
| "name": "ralph-starter", | |||
There was a problem hiding this comment.
🔴 The plugin manifest files in .claude-plugin/ (plugin.json and marketplace.json) still declare version 0.4.0 while package.json was bumped to 0.5.1 in this PR. Since .claude-plugin/ is listed in package.json's "files" array, these stale manifests will be published to npm — any MCP marketplace client or Claude Desktop plugin integration reading the version from these manifests will see 0.4.0 instead of 0.5.1. Fix by updating the version field in both .claude-plugin/plugin.json (line 3) and .claude-plugin/marketplace.json (lines 9 and 16) to match 0.5.1.
Extended reasoning...
What the bug is and how it manifests
Both .claude-plugin/plugin.json (line 3) and .claude-plugin/marketplace.json (lines 9 and 16) still declare version "0.4.0" while package.json was bumped from 0.5.0 to 0.5.1 in this PR. These plugin manifest files are used by MCP marketplace clients and Claude Desktop plugin integrations to identify the installed version of the package. Because the manifests ship with the package, consumers reading them will see a version two releases behind.
The specific code path that triggers it
package.json explicitly includes ".claude-plugin" in its "files" array:
"files": [
"dist",
...
".claude-plugin",
...
]This means every npm publish bundles .claude-plugin/plugin.json and .claude-plugin/marketplace.json verbatim. Whatever version strings those files contain at publish time is what gets shipped.
Why existing code doesn't prevent it
There is no automated version-sync mechanism that keeps the plugin manifests in sync with package.json. The release workflow bumps package.json (via pnpm version) but does not update the plugin manifest files. This is a manual step that was missed in both the v0.5.0 PR (#319) and this v0.5.1 PR (#323).
What the impact would be
Any MCP marketplace client, Claude Desktop plugin integration, or tooling that reads version from the plugin manifests will see "0.4.0" instead of "0.5.1". This version skew has now persisted across two consecutive releases, meaning users on v0.5.0 and v0.5.1 will both appear to be running v0.4.0 to plugin-aware tooling. This can cause incorrect update prompts, compatibility checks, or marketplace listings.
How to fix it
Update the version field in:
- .claude-plugin/plugin.json line 3: change "0.4.0" → "0.5.1"
- .claude-plugin/marketplace.json lines 9 and 16: change "0.4.0" → "0.5.1"
Long-term, consider adding a postversion npm script (or a step in the release workflow) that automatically syncs version strings across all manifest files.
Step-by-step proof
- This PR bumps package.json line 2:
"version": "0.5.0"→"version": "0.5.1" - .claude-plugin/plugin.json line 3 still reads:
"version": "0.4.0" - .claude-plugin/marketplace.json lines 9 and 16 still read:
"version": "0.4.0" - package.json "files" array contains ".claude-plugin", so both manifest files are included in the npm tarball
npm publishships all three files — package.json at 0.5.1, both manifests at 0.4.0- A Claude Desktop plugin manager installing ralph-starter@0.5.1 reads .claude-plugin/plugin.json and reports version 0.4.0 — two releases behind reality
| ### Added | ||
| - OpenSpec as builtin source: `--from openspec:my-feature` (#320) | ||
| - Spec validator with completeness scoring (0-100) and `--spec-validate` flag (#321) | ||
| - `ralph-starter spec` command: validate, list, summary subcommands (#321) |
There was a problem hiding this comment.
🟣 This is a pre-existing documentation gap: docs/docs/cli/spec.md was never created when the spec command was implemented in PR #321. Every other CLI command (auth, auto, figma, run, etc.) has a corresponding reference page in docs/docs/cli/, but spec is missing. Users who discover the command from this changelog entry will find no reference documentation.
Extended reasoning...
What the bug is: The ralph-starter spec command (with validate, list, and summary subcommands) was implemented in src/commands/spec.ts as part of PR #321, but no corresponding docs/docs/cli/spec.md documentation page was created. All 16 other CLI commands have matching reference pages in docs/docs/cli/ (auth.md, auto.md, figma.md, run.md, init.md, setup.md, etc.).
How it manifests: Users who read the v0.5.1 CHANGELOG and see the new spec command listed will attempt to look up its usage in the documentation site. They will find no reference page, leaving them with only the --help output to understand the validate, list, and summary subcommands and their options.
Why existing code doesn't prevent it: There is no automated check ensuring that each src/commands/.ts file has a corresponding docs/docs/cli/.md page. The omission was simply missed during PR #321 review.
Evidence this is pre-existing: The missing docs page originates from PR #321, which is already merged. PR #323 (this release PR) only modifies CHANGELOG.md and package.json to bump the version. It does not touch src/commands/spec.ts, does not create any docs pages, and does not worsen the existing documentation gap in any way.
Noteworthy signal in the CHANGELOG: The v0.5.1 CHANGELOG explicitly calls out the addition of 'Figma CLI docs page (docs/docs/cli/figma.md) (#321)' as a distinct line item — strongly implying that a spec.md counterpart was expected but not created during PR #321.
Step-by-step proof: 1) User reads v0.5.1 CHANGELOG and sees 'ralph-starter spec command: validate, list, summary subcommands'. 2) User navigates to docs/docs/cli/ to learn usage. 3) They find auth.md, auto.md, figma.md, run.md, and 12 others — but no spec.md. 4) The feature is already shipped; the gap was introduced in PR #321, not in this version-bump PR.
How to fix: Create docs/docs/cli/spec.md documenting the three subcommands (validate, list, summary), their flags, and example usage — mirroring the structure of existing command pages like figma.md.
| ## [0.5.1] - 2026-04-08 | ||
|
|
||
| ### Added | ||
| - OpenSpec as builtin source: `--from openspec:my-feature` (#320) |
There was a problem hiding this comment.
🟣 The --from option help text in src/cli.ts:79 lists valid sources as "file, url, github, todoist, linear, notion" but omits openspec, which was added as a builtin source in PR #320. This is a pre-existing issue unrelated to this version-bump PR, but this CHANGELOG entry advertising --from openspec:my-feature makes the discoverability gap more consequential. Fix by appending openspec to the description string in src/cli.ts:79.
Extended reasoning...
What the bug is and how it manifests
The --from CLI option in src/cli.ts line 79 defines its help text description as: 'Fetch spec from source (file, url, github, todoist, linear, notion)'. The source type openspec is absent from this enumeration, despite being a fully implemented and registered builtin source. Users running ralph-starter --help or ralph-starter run --help will never see openspec listed as a valid value for --from.
The specific code path that triggers it
PR #320 added src/sources/builtin/openspec.ts and registered it in src/sources/index.ts:13, making openspec functionally available. However, the help description string on line 79 of src/cli.ts was never updated to include openspec alongside the other named sources.
Why existing code does not prevent it
There is no automated test or linting rule that verifies the --from help text enumerates every registered builtin source. The help string is a static, manually maintained string, so it silently fell out of sync when the new source was added.
What the impact would be
Users discovering ralph-starter v0.5.1 through the CHANGELOG (which this PR introduces) will read about --from openspec:my-feature and then run --help to learn more — and find no mention of openspec. This creates confusion and reduces adoption of the new feature. The CHANGELOG advertisement makes the omission more visible than it was before.
How to fix it
In src/cli.ts line 79, change the description from:
'Fetch spec from source (file, url, github, todoist, linear, notion)'
to:
'Fetch spec from source (file, url, github, todoist, linear, notion, openspec)'
Step-by-step proof
- User installs ralph-starter@0.5.1 and reads the CHANGELOG entry: "OpenSpec as builtin source: --from openspec:my-feature (feat: add OpenSpec as builtin source #320)"
- User runs ralph-starter run --help to understand the syntax
- The --from option shows: Fetch spec from source (file, url, github, todoist, linear, notion)
- openspec is absent — the user has no CLI-discoverable indication this source type exists
- The feature works (e.g., ralph-starter run --from openspec:my-feature) but only if the user already knows the syntax from the CHANGELOG
This bug was introduced by PR #320 and is pre-existing relative to this version-bump PR (#323), which only modifies CHANGELOG.md and package.json.
1 participant
Summary
🤖 Generated with Claude Code