docs: refresh launch artifacts and bump guide versions for v2.1.0#42
Merged
Nathan Schram (nathanschram) merged 8 commits intomainfrom Mar 15, 2026
Merged
Conversation
…iew fixes, launch artifacts ✅ Per-project activation system complete - docs-freshness agent: read-only freshness checks for advisory - docs-awareness rule: documentation trigger map - doc-standards rule: quality standards (installed per-project via /pitchdocs:activate) - Optional content-filter-guard.sh hook for strict mode 🔧 Plugin review fixes documented - Version sync (SKILL.md frontmatter, plugin.json, RESULTS.md) - Stale references (doc-refresh ai-context delegation, CLAUDE.md counts) - Hook exit codes (content-filter-guard uses exit 0 for clean block) - Command dimension counts (docs-verify lists 6 dimensions) - Circular reference fixes (TTHW targets table added) - llms.txt orphan cleanup (skill links, command count) 🚀 Launch artifacts ready for review - INDEX.md: Central launch coordination checklist - devto-article.md: Long-form narrative with problem-solution framing - hackernews-post.md: Technical-depth Show HN submission - reddit-posts.md: 3 subreddit variants (r/programming, r/webdev, r/opensource) - twitter-thread.md: 5-tweet narrative thread - awesome-list-submissions.md: 6 relevant lists with submission strategy - social-preview-guide.md: GitHub social preview image specs 📚 Documentation updates - CHANGELOG.md: Enhanced [Unreleased] section with all fixes, additions, removals - ROADMAP.md: v2.1 marked complete, v2.2 focus documented (API reference, upstream specs) - llms.txt: Added Launch Artifacts section, fixed duplicate line, corrected command count ✨ Skill count: 15 (removed out-of-scope skill-authoring) Commands: 16 active + stub redirects (ai-context, context-guard → ContextDocs) Closes #40, #36, #37, #12, #41
- Cleared stale pre-release entries from [Unreleased] - Added 7 post-release commits: plugin review fixes, skill-authoring removal, GitHub Actions security - Reorganized into Fixed, Removed, and Security categories - Used benefit-driven language per changelog standards Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Updated feature-benefits skill description to include explicit trigger phrases: - 'features and benefits section' - 'why should someone use this project?' This improves natural language activation reliability. Also synced evaluation test expectations to mark changelog and launch commands as non-deterministic. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Rewrite all launch promotion content (Dev.to article, HN post, Reddit templates, Twitter thread, awesome list submission, social preview guide). Rename files to singular form, replace INDEX.md with README.md hub, and trim content to tighter drafts ready for posting. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Expand the feature-benefits skill description to mention concrete output types (features/benefits sections, "Why [Project]?" content, feature audit reports) and clarify the extraction workflow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughAdds a read-only documentation freshness agent and docs-awareness rules, extensive launch and marketing materials, synchronized docs metadata, updated feature-benefits descriptions, and small test config adjustments. Changes are documentation, metadata, and test updates; no runtime public API modifications. Changes
sequenceDiagram
participant User
participant DocsAgent as DocsFreshnessAgent
participant Git as GitRepo
participant Manifest as ManifestFiles
participant Docs as DocumentationFiles
participant Reporter as FreshnessReport
User->>DocsAgent: Trigger (docs-awareness moment / query / pre-release)
DocsAgent->>Git: Inspect git tags, commits, file timestamps
DocsAgent->>Manifest: Locate/parse manifests (package.json, pyproject.toml, ...)
DocsAgent->>Docs: Search README, CHANGELOG, llms.txt, docs/ structure
DocsAgent->>Git: Compare tags vs CHANGELOG entries
DocsAgent->>Docs: Check versions, last README change, structural coverage
DocsAgent->>Reporter: Produce structured Stale / Missing / Fresh report + /pitchdocs:* suggestions
Reporter->>User: Present read-only findings and concrete command suggestions
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/launch/awesome-list-submission.md`:
- Around line 11-13: Change the two US-spelled words to UK spelling in
docs/launch/awesome-list-submission.md: replace "README generation and
optimization" (near the "awesome-readme" entry) with "README generation and
optimisation" and update "Template PR Body (Customize per List)" to "Template PR
Body (Customise per List)"; ensure both occurrences are edited so the docs
linter passes.
In `@docs/launch/README.md`:
- Line 11: Replace all US English occurrences of "customize" and "customizable"
(including capitalised forms "Customize" and "Customizable") with Australian
English "customise" and "customisable" across the README content (e.g., the line
currently reading "Status: Ready to customize tags before publishing" and the
other flagged occurrences). Ensure you update all case variations and
plural/gerund forms consistently (customize → customise, customizable →
customisable, customizing → customising, customized → customised) so the
document conforms to the Australian English standard.
In `@docs/launch/reddit-post.md`:
- Line 19: Replace the US spelling "optimized" with the UK spelling "optimised"
in the document; specifically update the phrase "GEO-optimized" and the other
occurrence of "optimized" on line 79 to "GEO-optimised" and "optimised"
respectively so the docs lint passes.
In `@docs/launch/social-preview-guide.md`:
- Line 21: The phrase "Upper half, centered or left-aligned" (and the matching
phrases at the other two occurrences) contains spelling/dialect variants that
fail the docs lint; update those three occurrences so they use the project's
preferred dialect and exact spelling (e.g., change centered/centre or
left-aligned/left aligned to the convention used in the repo) by editing the
literal strings "Upper half, centered or left-aligned" and the two corresponding
phrases at the other locations, then re-run the docs lint to confirm the fixes.
In `@ROADMAP.md`:
- Line 90: Update the ROADMAP.md checklist item text to use Australian English
spelling: locate the line containing "Multi-language README support — generate
localized docs for i18n projects" and change "localized" to "localised" so it
reads "generate localised docs for i18n projects"; ensure only the spelling is
altered and formatting/checkbox state remains unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d968da96-e267-4406-b086-605c223d27af
📒 Files selected for processing (25)
.claude/agents/docs-freshness.md.claude/rules/docs-awareness.md.claude/skills/feature-benefits/SKILL.mdAGENTS.mdCHANGELOG.mdROADMAP.mddocs/guides/command-reference.mddocs/guides/concepts.mddocs/guides/customising-output.mddocs/guides/getting-started.mddocs/guides/other-ai-tools.mddocs/guides/troubleshooting.mddocs/guides/untether-integration.mddocs/guides/workflows.mddocs/launch/README.mddocs/launch/awesome-list-submission.mddocs/launch/awesome-list-submissions.mddocs/launch/devto-article.mddocs/launch/hackernews-post.mddocs/launch/reddit-post.mddocs/launch/social-preview-guide.mddocs/launch/twitter-thread.mddocs/tutorials/build-your-first-docs-suite.mdllms.txttests/evaluations.json
💤 Files with no reviewable changes (1)
- docs/launch/awesome-list-submissions.md
- Fix 11 American English spellings to Australian English across launch docs and ROADMAP (customize→customise, centered→centred, etc.) - Fix broken relative links in docs/launch/README.md (../CHANGELOG.md → ../../CHANGELOG.md to correctly reach repo root) - Remove 2 ContextDocs file references from llms.txt that only exist when ContextDocs is installed locally, not in the tracked repo Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (2)
ROADMAP.md (1)
131-131: Consider more specific target version date.The metrics table shows the plugin version target as "3.0.0 (2026)", but line 88 specifies "v3.0 — Expansion (Q3 2026)". For consistency, consider updating the metrics target to "3.0.0 (Q3 2026)".
📋 Proposed consistency fix
-| Plugin version | 2.1.0 | 3.0.0 (2026) | +| Plugin version | 2.1.0 | 3.0.0 (Q3 2026) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@ROADMAP.md` at line 131, The plugin version target in the metrics table ("| Plugin version | 2.1.0 | 3.0.0 (2026) |") is inconsistent with the roadmap text ("v3.0 — Expansion (Q3 2026)"); update the table cell to read "3.0.0 (Q3 2026)" so both the table entry and the "v3.0 — Expansion (Q3 2026)" text match exactly.docs/launch/awesome-list-submission.md (1)
28-28: Avoid hard-coding release metadata inside a reusable template.
latest release v2.1.0, 2026-03-12will age quickly and make copied submissions inaccurate. Prefer placeholders (e.g.,[LATEST_VERSION],[RELEASE_DATE]) in the template body.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/launch/awesome-list-submission.md` at line 28, Replace the hard-coded release metadata string "latest release v2.1.0, 2026-03-12" in the template with placeholders so copies don't age; change occurrences of that literal to a placeholder format such as "[LATEST_VERSION], [RELEASE_DATE]" (or a single "[LATEST_RELEASE]" if preferred) and update any guidance text to mention that contributors should fill those placeholders when submitting; ensure the template line containing the checkbox "[X] Actively maintained (latest release v2.1.0, 2026-03-12)" references the new placeholders instead.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/launch/reddit-post.md`:
- Line 88: Update the posting window text "Post to r/programming first
(Tuesday–Thursday, 2–4 PM EST)" to use "ET" instead of "EST" (e.g., "2–4 PM ET")
or explicitly list both zones (e.g., "2–4 PM EST/EDT") so the time is correct
during daylight saving; locate the string as it appears in the reddit-post
launch copy and replace the timezone token accordingly.
In `@docs/launch/social-preview-guide.md`:
- Line 113: Replace the plain text URL in the "Platform preview" checklist item
so the validator is clickable: change the text "cards-dev.twitter.com/validator"
to a Markdown link that includes the protocol, e.g. [Twitter Card
Validator](https://cards-dev.twitter.com/validator), in the "Platform preview"
line so the checklist is directly actionable.
In `@ROADMAP.md`:
- Around line 9-11: The milestone target "Target: Q1 2026" under the heading "##
🎯 Current Milestone: v2.2 — Command Completeness & Upstream Stability" is
likely unrealistic given the PR date; update that line in ROADMAP.md to a more
appropriate timeframe (e.g., "Target: Q2 2026" or a concrete date like "Target:
2026-06-30") and ensure the chosen target aligns with the listed "In Progress"
items and project timelines.
- Line 16: Update the inaccurate version note in the ROADMAP entry titled
"Resolve upstream spec version drift" by changing the parenthetical "(latest is
v2.1)" to the correct latest version string "(latest is v3.0)" so the line reads
that Contributor Covenant v3.0 is the latest; ensure the adjacent mention of
Contributor Covenant v3.0 remains consistent with the earlier part of the
sentence and keep the issue link and filename references untouched.
---
Nitpick comments:
In `@docs/launch/awesome-list-submission.md`:
- Line 28: Replace the hard-coded release metadata string "latest release
v2.1.0, 2026-03-12" in the template with placeholders so copies don't age;
change occurrences of that literal to a placeholder format such as
"[LATEST_VERSION], [RELEASE_DATE]" (or a single "[LATEST_RELEASE]" if preferred)
and update any guidance text to mention that contributors should fill those
placeholders when submitting; ensure the template line containing the checkbox
"[X] Actively maintained (latest release v2.1.0, 2026-03-12)" references the new
placeholders instead.
In `@ROADMAP.md`:
- Line 131: The plugin version target in the metrics table ("| Plugin version |
2.1.0 | 3.0.0 (2026) |") is inconsistent with the roadmap text ("v3.0 —
Expansion (Q3 2026)"); update the table cell to read "3.0.0 (Q3 2026)" so both
the table entry and the "v3.0 — Expansion (Q3 2026)" text match exactly.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ef9bd898-63f1-40fd-b40b-7e753c9757cc
📒 Files selected for processing (6)
ROADMAP.mddocs/launch/README.mddocs/launch/awesome-list-submission.mddocs/launch/reddit-post.mddocs/launch/social-preview-guide.mdllms.txt
🚧 Files skipped from review as they are similar to previous changes (1)
- llms.txt
| 4. **Wait 24 hours** | ||
| 5. **Post to r/opensource** (if interested in attracting contributors) | ||
| **Reddit posting strategy:** | ||
| - Post to r/programming first (Tuesday–Thursday, 2–4 PM EST) |
There was a problem hiding this comment.
Use “ET” instead of “EST” for posting windows.
“2–4 PM EST” is seasonally wrong during daylight saving time. Use “ET” (or specify both EST/EDT) to avoid mis-timed posting.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/launch/reddit-post.md` at line 88, Update the posting window text "Post
to r/programming first (Tuesday–Thursday, 2–4 PM EST)" to use "ET" instead of
"EST" (e.g., "2–4 PM ET") or explicitly list both zones (e.g., "2–4 PM EST/EDT")
so the time is correct during daylight saving; locate the string as it appears
in the reddit-post launch copy and replace the timezone token accordingly.
| 1. **Thumbnail test:** Resize to 300×150px in your design tool — is it still legible? | ||
| 2. **Contrast test:** Convert to grayscale — is the hierarchy clear without colour? | ||
| 3. **Mobile test:** View on phone screen — are text and logo readable? | ||
| 4. **Platform preview:** Use Twitter Card Validator (cards-dev.twitter.com/validator) to see how it renders |
There was a problem hiding this comment.
Make the validator URL clickable.
Use a markdown link (with https://) for the validator URL so the checklist is directly actionable.
Proposed edit
-4. **Platform preview:** Use Twitter Card Validator (cards-dev.twitter.com/validator) to see how it renders
+4. **Platform preview:** Use [Twitter Card Validator](https://cards-dev.twitter.com/validator) to see how it renders📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 4. **Platform preview:** Use Twitter Card Validator (cards-dev.twitter.com/validator) to see how it renders | |
| 4. **Platform preview:** Use [Twitter Card Validator](https://cards-dev.twitter.com/validator) to see how it renders |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/launch/social-preview-guide.md` at line 113, Replace the plain text URL
in the "Platform preview" checklist item so the validator is clickable: change
the text "cards-dev.twitter.com/validator" to a Markdown link that includes the
protocol, e.g. [Twitter Card
Validator](https://cards-dev.twitter.com/validator), in the "Platform preview"
line so the checklist is directly actionable.
Comment on lines
+9
to
+11
| ## 🎯 Current Milestone: v2.2 — Command Completeness & Upstream Stability | ||
|
|
||
| ### Context Token Optimisation | ||
| Target: Q1 2026 |
There was a problem hiding this comment.
Verify Q1 2026 target is realistic.
The target date "Q1 2026" for v2.2 ends on March 31, 2026, which is only ~16 days from the PR creation date (March 15, 2026). Given the "In Progress" items below include feature implementation, eval tests, and upstream spec updates, this timeline may be too tight.
Consider updating to "Q2 2026" or a specific date if the Q1 target is no longer realistic.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@ROADMAP.md` around lines 9 - 11, The milestone target "Target: Q1 2026" under
the heading "## 🎯 Current Milestone: v2.2 — Command Completeness & Upstream
Stability" is likely unrealistic given the PR date; update that line in
ROADMAP.md to a more appropriate timeframe (e.g., "Target: Q2 2026" or a
concrete date like "Target: 2026-06-30") and ensure the chosen target aligns
with the listed "In Progress" items and project timelines.
| - **Auto-loaded rules overspend** ([#36](https://github.com/littlebearapps/pitchdocs/issues/36)) — ✅ Resolved in v2.0.0: moved `doc-standards.md` and `docs-awareness.md` to per-project installable rules via `/pitchdocs:activate`. Only `content-filter.md` remains auto-loaded (~500 tokens) | ||
| - **Skills exceed individual budgets** ([#37](https://github.com/littlebearapps/pitchdocs/issues/37)) — ✅ Partially resolved: 4 of 6 skills split into companion reference files (`docs-verify`, `package-registry`, `pitchdocs-suite`, `user-guides`). Remaining 2 (`doc-refresh` ~2,453, `launch-artifacts` ~2,286) accepted as near-budget | ||
| - **Add `/pitchdocs:api-reference` command** ([#41](https://github.com/littlebearapps/pitchdocs/issues/41)) — Direct slash command for TypeDoc, Sphinx, godoc, and rustdoc integration. Currently unreachable through primary `/pitchdocs:*` pattern. Needs command definition, 1–2 eval test cases, and skill cross-references to `user-guides` and `platform-profiles` | ||
| - **Resolve upstream spec version drift** ([#12](https://github.com/littlebearapps/pitchdocs/issues/12)) — Contributor Covenant v3.0 detected in monthly check (latest is v2.1). Update `upstream-versions.json` and refresh skill content |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What is the latest version of Contributor Covenant?
💡 Result:
The latest version of the Contributor Covenant is Contributor Covenant 3.0 (released July 28, 2025). [1], [2]
Citation(s): [1] [2]
Update incorrect Contributor Covenant version reference.
The statement "(latest is v2.1)" is outdated. The latest version of Contributor Covenant is v3.0 (released July 28, 2025). Update this line to reflect the correct version.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@ROADMAP.md` at line 16, Update the inaccurate version note in the ROADMAP
entry titled "Resolve upstream spec version drift" by changing the parenthetical
"(latest is v2.1)" to the correct latest version string "(latest is v3.0)" so
the line reads that Contributor Covenant v3.0 is the latest; ensure the adjacent
mention of Contributor Covenant v3.0 remains consistent with the earlier part of
the sentence and keep the issue link and filename references untouched.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
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
INDEX.mdwithREADME.mdhublast_verifiedfrom2.0.0to2.1.0across all 8 guides and the tutorialfeature-benefitsskill description inAGENTS.mdandllms.txtto reflect output typesTest plan
llms.txtfile references resolve to existing files🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
New Features
Chores
Tests