feat: v2.3.0 — ecosystem refresh, Agent Skills compliance, FAQ rename#50
feat: v2.3.0 — ecosystem refresh, Agent Skills compliance, FAQ rename#50Nathan Schram (nathanschram) wants to merge 4 commits into
Conversation
Adds the canonical build-dist.sh script that generates platform-specific distributions from the .claude/ source tree, plus pre-built artefacts for 8 platforms (Codex CLI, Gemini CLI, Cursor, Cline, Windsurf, Goose, Aider, OpenCode), the platform-neutral pitchdocs.json manifest, the portable docs-writer-flat agent for tools without sub-agent support, and a universal setup.sh installer. Codex and Gemini distributions ship native .agents/skills/ and skills/ directories respectively, aligning with the Agent Skills open standard. Cursor distribution uses .cursor/rules/*.mdc + .cursor/agents/. CLAUDE.md, README.md, llms.txt, and docs/guides/other-ai-tools.md updated to document the new build pipeline and dist/ contents. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…igration, content updates **Bucket A — Claude Code ecosystem alignment** * Migrate 6 command/skill name collisions into skills (changelog, roadmap, visual-standards, docs-verify, doc-refresh, llms-txt). Per Claude Code's command/skill merge, skills now take precedence on name collisions; the command files were dead code. Each skill gained an `## Invocation` section preserving the procedural prose, plus `argument-hint` and `allowed-tools` in the frontmatter. * Reference the Agent Skills open standard (https://agentskills.io) — added badge to README, `agent-skills` keyword to plugin.json, and citations across CLAUDE.md, AGENTS.md, ROADMAP.md, SKILL.md, and bridge files. * Fix "16 skills" → "15 skills" count drift introduced after the skill-authoring skill was removed in v2.2. New canonical counts: 15 skills, 10 commands (8 active + 2 stubs), 14 user-invocable slash commands total. **Bucket B — Skill frontmatter modernisation** * Add `paths:` frontmatter to docs-awareness rule for path-scoped activation on documentation file edits (forward-compatible with newer Claude Code). **Bucket C — Cross-tool distribution (already shipped in WIP)** * Verified `dist/codex/.agents/skills/`, `dist/gemini/skills/`, and `dist/cursor/.cursor/` are populated and regenerate cleanly. **Bucket D — Upstream spec & content refresh** * `upstream-versions.json`: refresh all `last_verified` to 2026-05-06; add `notes` capturing Issue Forms attachments, npm version floors, PEP 740 default attestations, Django CC 3.0 adoption; new `agent-skills` source. * `package-registry`: npm CLI ≥ 11.5.1 and Node ≥ 22.14.0 floors; CircleCI/private-repo provenance unsupported; PyPI PEP 740 attestations now default via pypa/gh-action-pypi-publish. * `pitchdocs-suite/SKILL-templates.md`: Issue Forms `attachments` field; alphabetical-template-ordering note; Issue Fields preview note; Django CC 3.0 adoption credibility signal; FUNDING.yml gained `polar:`, `patreon:`, `liberapay:`, `tidelift:`, `buy_me_a_coffee:`, `thanks_dev:`, `issuehunt:`. * `visual-standards`: new Diagrams (Mermaid) section with diagram-type table including Wardley Maps; "neo look" styling note; theme auto-sync warning. * `docs/guides/other-ai-tools.md`: feature-support matrix updated for Cursor 2.6+ AGENTS.md primacy, Antigravity 1.20+ AGENTS.md, Gemini CLI v0.25+ native skills/. **Bucket E — Release hygiene** * All bridge files synced (.cursorrules, .clinerules, .windsurfrules, .github/copilot-instructions.md, GEMINI.md, AGENTS.md, CLAUDE.md, README, ROADMAP, SKILL.md). * Validation: `python3 tests/validate-frontmatter.py` ✓ (15/10/5), `bash tests/validate-llms-txt.sh` ✓ (0 errors), `bash scripts/build-dist.sh --check` ✓ (no drift). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…e, llms-full regen Final preparation for the v2.3.0 publish. **Version bumps to 2.3.0:** * `.claude-plugin/plugin.json`, `pitchdocs.json`, `.release-please-manifest.json` * `README.md` badge (release-please marker), `SKILL.md` frontmatter (was 2.1.0, release-please missed it on the v2.2.0 cut) * `dist/gemini/gemini-extension.json` (auto-bumped after fixing `scripts/build-dist.sh` to read PLUGIN_VERSION from `plugin.json` rather than hardcoding) * All `last_verified:` frontmatter in `docs/guides/` and `docs/tutorials/` bumped from "2.1.0" to "2.3.0" **Forward-compat:** `pitchdocs.json` added to `release-please-config.json` `extra-files` so future releases auto-bump it. **FAQ rename (closes #49):** `docs/faq/index.md` → `docs/faq/faq.md` so the marketing-site URL becomes `/help/pitchdocs/faq/` instead of `/index/`. Pure rename, no content change. All 8 internal references updated (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.clinerules`, `.windsurfrules`, `.github/copilot-instructions.md`, `llms.txt`); regenerated bridge files in `dist/codex/AGENTS.md` and `dist/gemini/GEMINI.md` via `bash scripts/build-dist.sh`. **Marketing surfaces:** * `CHANGELOG.md` — `[Unreleased]` promoted to `[2.3.0] (2026-05-06)` with a curated Keep-a-Changelog entry list (Added / Changed / Documentation / Internal). The previous Unreleased content (v2.2.0 cycle holdover) was superseded by the v2.2.0 entries above and removed. * `ROADMAP.md` — v2.2.0 moved to "Recently Completed", v2.3.0 added with full bullet list, current milestone now "v2.4 — Automation & Polish (Q3 2026)"; metrics table bumped to 2.3.0; "Last updated" → 2026-05-06. * `llms-full.txt` — fully regenerated (94 files concatenated from the live `llms.txt` index) eliminating the pre-v2.0 references and the long-removed `skill-authoring` skill that had persisted in the file. **Validation:** `bash scripts/build-dist.sh --check` clean, `python3 tests/validate-frontmatter.py` ✓ (15/10/5), `bash tests/validate-llms-txt.sh` ✓ (0 errors). Closes #49 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (13)
📒 Files selected for processing (20)
📝 WalkthroughWalkthroughThis PR implements version 2.3.0 release, featuring FAQ file path migration (docs/faq/index.md → faq.md), expanded skill specification with frontmatter and invocation workflows, comprehensive cross-platform distribution build system (build-dist.sh, setup.sh, pitchdocs.json), portable docs-writer agent, and coordinated documentation/configuration refresh across 60+ files reflecting version bump and updated capability counts. ChangesPitchDocs v2.3.0 Release
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related issues
Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 15
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (4)
SKILL.md (1)
1-93:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winFix hard tab at line 198 — blocking CI failure.
The
docs / lintpipeline is failing withMD010/no-hard-tabsat line 198 (column 3). The line is outside the diff view but is in this file. Replace the hard tab with spaces to unblock CI.To locate and fix it:
grep -Pn '\t' SKILL.md🤖 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 `@SKILL.md` around lines 1 - 93, The linter reports MD010/no-hard-tabs in SKILL.md (line 198); replace the hard tab character on that line with spaces and ensure no other tabs remain in the file so the docs/lint pipeline passes; search SKILL.md for any '\t' characters (or use your editor's "show whitespace") and convert them to spaces, then re-run the linter.docs/guides/troubleshooting.md (1)
180-182:⚠️ Potential issue | 🟠 Major | ⚡ Quick winFix broken FAQ link path after file rename
The link still targets
../faq/index.md, which no longer exists. This is causing the docs link-check workflow failure. Update it to../faq/faq.md(Line 181).Suggested fix
-> **[FAQ](../faq/index.md)** — installation, AI tool support, data privacy, +> **[FAQ](../faq/faq.md)** — installation, AI tool support, data privacy,Based on learnings: hard-fail docs-sync when FAQ paths are missing, and keep references updated when files move.
🤖 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 `@docs/guides/troubleshooting.md` around lines 180 - 182, The FAQ link in the markdown sentence "Looking for the headline questions? See the standalone **[FAQ](../faq/index.md)**" points to a non-existent path and breaks the docs link-check workflow; update that link target from ../faq/index.md to ../faq/faq.md so the anchor reads **[FAQ](../faq/faq.md)** and ensure any other references to the old ../faq/index.md are replaced accordingly to prevent future broken links.docs/README.md (2)
89-89:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winStale skill count — "16 specialised skills" should be 15.
Line 89 reads "PitchDocs includes 16 specialised skills" but
AGENTS.md,.cursorrules, and.github/copilot-instructions.mdall consistently state 15 skills following this PR's changes.📝 Proposed fix
-PitchDocs includes **16 specialised skills** loaded automatically when you use commands. Each skill has structured knowledge for a specific task: +PitchDocs includes **15 specialised skills** loaded automatically when you use commands. Each skill has structured knowledge for a specific task:🤖 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 `@docs/README.md` at line 89, Update the stale count in the README by changing the phrase "PitchDocs includes **16 specialised skills**" to "PitchDocs includes **15 specialised skills**" so it matches AGENTS.md, .cursorrules, and .github/copilot-instructions.md; locate the exact string "PitchDocs includes **16 specialised skills**" in docs/README.md and replace the numeric value only, then run a quick grep across the repo to confirm all references consistently state 15.
27-27:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winBroken links to
faq/index.md— causing CI pipeline failure.Both references still point to the old path. The FAQ was renamed to
docs/faq/faq.mdin this PR, but these two links were not updated, which is why lychee is failing withCannot find file: docs/faq/index.md.🔗 Proposed fix
-| **[Frequently Asked Questions](faq/index.md)** — Quick answers on installation, AI tool support, data privacy, monorepos, updates, and uninstall +| **[Frequently Asked Questions](faq/faq.md)** — Quick answers on installation, AI tool support, data privacy, monorepos, updates, and uninstall-| Get a quick answer to a common question | [FAQ](faq/index.md) | +| Get a quick answer to a common question | [FAQ](faq/faq.md) |Also applies to: 103-103
🤖 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 `@docs/README.md` at line 27, Update the broken FAQ links in docs/README.md that currently point to "faq/index.md": find the link text "**[Frequently Asked Questions](faq/index.md)**" (and any other occurrences of "faq/index.md") and replace the path with the new location "docs/faq/faq.md" so the link becomes "**[Frequently Asked Questions](docs/faq/faq.md)**"; verify both occurrences (including the one at line 103) are updated and run the link checker/CI locally to confirm the error is resolved.
♻️ Duplicate comments (1)
.claude/rules/docs-awareness.md (1)
1-5:⚠️ Potential issue | 🟠 Major | ⚡ Quick winSame
paths:/FUNDING.ymlissues asrules/docs-awareness.mdThe identical
paths:frontmatter issue and.github/FUNDING.ymlpath correction raised forrules/docs-awareness.mdapply here as well — apply the sameglobs:fix to keep both files in sync.🤖 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 @.claude/rules/docs-awareness.md around lines 1 - 5, The frontmatter uses the incorrect key and filename: replace the top-level "paths:" key with "globs:" and update the listed "FUNDING.yml" entry to the corrected ".github/FUNDING.yml" so the docs-awareness frontmatter matches the other rules file; locate the frontmatter block containing "paths:" and the "FUNDING.yml" string in docs-awareness and make those two substitutions (keep all other entries unchanged).
🧹 Nitpick comments (5)
pitchdocs.json (1)
7-96: 💤 Low valueNormalise
companion(string) andcompanions(array) to a single field shapeSome skills use
"companion": "<path>"(string) while others use"companions": [...](array), which means any tooling consuming this manifest must handle both field names. Standardising on the array form avoids a dual-key schema:🛠️ Suggested normalisation — rename all singular `companion` to `companions` arrays
{ "name": "docs-verify", "path": ".claude/skills/docs-verify/SKILL.md", - "companion": ".claude/skills/docs-verify/SKILL-reference.md", + "companions": [".claude/skills/docs-verify/SKILL-reference.md"], "description": "..." },Apply the same change to
feature-benefits,package-registry,platform-profiles,public-readme, andvisual-standards.🤖 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 `@pitchdocs.json` around lines 7 - 96, Normalize the manifest by replacing every "companion": "<path>" string with "companions": ["<path>"] so all companion metadata uses an array shape; update the entries for the skills "feature-benefits", "package-registry", "platform-profiles", "public-readme", "visual-standards" (and "docs-verify" which already uses "companion") to use the plural "companions" array form while leaving existing "companions" arrays intact and preserving the same path values and ordering.scripts/setup.sh (1)
188-200: 💤 Low valueInteractive
readwill hang in non-interactive contexts.If a user pipes the installer (
curl ... | bash), runs it from CI, or has redirected stdin, theread -r answerhere will block indefinitely (or fail underset -uifreadexits abnormally). Consider guarding with[ -t 0 ]and defaulting to "skip append" when stdin isn't a TTY, or accept a--yes/--no-appendflag.♻️ Possible guard
- if [ -f "$PROJECT_DIR/.goosehints" ]; then - echo "" - echo "Existing .goosehints detected. Append PitchDocs standards? [y/N]" - read -r answer - if [ "$answer" = "y" ] || [ "$answer" = "Y" ]; then + if [ -f "$PROJECT_DIR/.goosehints" ]; then + answer="n" + if [ -t 0 ]; then + echo "" + echo "Existing .goosehints detected. Append PitchDocs standards? [y/N]" + read -r answer + else + echo "Existing .goosehints detected — skipping append (non-interactive shell)." + fi + if [ "$answer" = "y" ] || [ "$answer" = "Y" ]; then🤖 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 `@scripts/setup.sh` around lines 188 - 200, The interactive read -r answer in the .goosehints append flow can block in non-interactive contexts; update the conditional around the .goosehints handling to detect a TTY (e.g., [ -t 0 ]) and skip prompting when stdin is not a TTY, defaulting to "no append" behavior, and also support an explicit non-interactive override (environment variable or CLI flag like --yes/--no-append) so callers can force append; adjust the block that references read -r answer, .goosehints, PROJECT_DIR, DIST and use the existing log function to record the chosen non-interactive default or flag-driven action.scripts/build-dist.sh (2)
86-96: 💤 Low value
copy_skillsmay silently fail if a skill directory has noSKILL*.md.
cp "$skill_dir"SKILL*.md "${target}/${skill_name}/"relies on shell globbing. Withset -euo pipefailand default (non-nullglob) behaviour, an empty match passes the literal patternSKILL*.mdtocp, which exits non-zero and aborts the whole build. That's actually OK as a fail-fast, but the error message will be confusing (cp: cannot stat 'SKILL*.md') rather than naming the offending skill. Consider a quick guard:♻️ Suggested guard
- for skill_dir in "$SKILLS_DIR"/*/; do - local skill_name - skill_name=$(basename "$skill_dir") - mkdir -p "${target}/${skill_name}" - cp "$skill_dir"SKILL*.md "${target}/${skill_name}/" - done + for skill_dir in "$SKILLS_DIR"/*/; do + local skill_name + skill_name=$(basename "$skill_dir") + if ! compgen -G "${skill_dir}SKILL*.md" > /dev/null; then + echo "ERROR: no SKILL*.md found in ${skill_dir}" >&2 + exit 1 + fi + mkdir -p "${target}/${skill_name}" + cp "$skill_dir"SKILL*.md "${target}/${skill_name}/" + done🤖 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 `@scripts/build-dist.sh` around lines 86 - 96, The copy_skills function can call cp with a glob that may not match and produce a confusing error; modify copy_skills to check for matching files before running cp: inside the loop over skill_dir (using skill_name and SKILLS_DIR), test whether any files match "$skill_dir"SKILL*.md (e.g. via a glob check or listing) and if none exist log/print a clear error identifying the skill_name and continue or abort as desired, otherwise perform the cp into "${target}/${skill_name}/". Ensure the guard avoids passing a literal pattern to cp so the failure message names the offending skill.
17-18: ⚡ Quick winBrittle JSON parsing for
PLUGIN_VERSION.
grep -E '"version"' | head -1 | sed ...will match the first occurrence of"version"in.claude-plugin/plugin.json, regardless of its position in the JSON tree. If anyone later adds a sibling object (e.g., a"schema_version"key or adependenciessection with versioned entries) above the plugin's"version"field, release tooling will silently embed the wrong version intodist/gemini/gemini-extension.json. Prefer a real JSON parser:♻️ Suggested fix
-PLUGIN_VERSION=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | head -1 | sed 's/.*"\([0-9.]*\)".*/\1/') -[ -n "$PLUGIN_VERSION" ] || { echo "ERROR: could not read plugin version from .claude-plugin/plugin.json" >&2; exit 1; } +if command -v jq >/dev/null 2>&1; then + PLUGIN_VERSION=$(jq -r '.version' "$ROOT/.claude-plugin/plugin.json") +else + PLUGIN_VERSION=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1]))["version"])' "$ROOT/.claude-plugin/plugin.json") +fi +[ -n "$PLUGIN_VERSION" ] && [ "$PLUGIN_VERSION" != "null" ] || \ + { echo "ERROR: could not read plugin version from .claude-plugin/plugin.json" >&2; exit 1; }🤖 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 `@scripts/build-dist.sh` around lines 17 - 18, The PLUGIN_VERSION extraction in scripts/build-dist.sh is brittle because it uses grep/head/sed and can pick up unrelated "version" keys; replace that pipeline with a JSON parser (e.g., use jq -r '.version' on .claude-plugin/plugin.json) to set the PLUGIN_VERSION variable reliably, then keep the existing validation check ([ -n "$PLUGIN_VERSION" ] || { echo ...; exit 1; }) to fail fast if the version is missing or empty; update any related error text if desired.tests/RESULTS.md (1)
1-7: 💤 Low valueUpdating a single count in a historical test report is misleading.
This file is a dated test report (
Date: 2026-03-14,Plugin version: 2.1.0). Editing only the frontmatter-validation line to "15 skills, 10 commands, 5 agents" makes the historical record internally inconsistent (the rest of the file still describes the v2.1.0 inventory and 16 skills appear elsewhere in this doc). Either revert the change and let v2.3.0 results live in a new section/file, or update the report header and the other inventory references for consistency.Also applies to: 71-71
🤖 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 `@tests/RESULTS.md` around lines 1 - 7, The report's frontmatter ("Date: 2026-03-14", "Plugin version: 2.1.0") was partially edited to "15 skills, 10 commands, 5 agents" creating an inconsistent historical record (the body still references v2.1.0 and 16 skills); either revert the single-line change so the v2.1.0 report remains untouched, or fully migrate the update to a new v2.3.0 section/report by changing the header fields ("Date", "Plugin version") and updating every inventory reference (e.g., occurrences of "16 skills" and any skill/command/agent counts) to match "15 skills, 10 commands, 5 agents" for internal consistency.
🤖 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 @.claude/skills/llms-txt/SKILL.md:
- Line 24: Remove the orphaned duplicate sentence "Generate structured,
LLM-friendly content indexes following the [llmstxt.org](https://llmstxt.org/)
specification." from SKILL.md (it currently sits between ## Invocation and ##
Background) since the same text already appears in the Invocation section;
either delete this line entirely or move it under an appropriate heading if you
intended it as a separate note so the document no longer contains the redundant
standalone sentence.
In @.claude/skills/pitchdocs-suite/SKILL-templates.md:
- Around line 318-325: Update the FUNDING.yml template entries to match GitHub's
required formats: change the thanks_dev line so the value includes the "gh"
namespace (replace "thanks_dev: u/username" with the "gh" style, e.g.,
"thanks_dev: u/gh/username"), and change the issuehunt entry from the org/repo
form to the single-username format (replace "issuehunt: org/repo" with
"issuehunt: USERNAME"); update the template lines for the thanks_dev and
issuehunt keys accordingly so they conform to GitHub's specification.
In @.claude/skills/visual-standards/SKILL.md:
- Around line 98-100: Update the Mermaid minimum-version wording: change any
occurrences that say "Mermaid 11+" (notably the `wardleyMap` row and the
paragraph referencing the "neo look") to explicitly state "Mermaid 11.14.0+"
since the `wardley-beta`/`wardleyMap` diagram type and the Neo/"neo" look
require Mermaid.js 11.14.0 or later; ensure both the table cell for `wardleyMap`
and the sentence about opting into the neo look use "Mermaid 11.14.0+".
In `@agents/docs-writer-flat.md`:
- Around line 156-163: Replace the invalid Contributor Covenant v3.0 curl URL
that points to an HTML-only path with the upstream raw GitHub Markdown source:
update the curl command that currently uses
"https://www.contributor-covenant.org/version/3/0/code_of_conduct/code_of_conduct.md"
to instead fetch
"https://raw.githubusercontent.com/ContributorCovenant/contributor_covenant/release/CODE_OF_CONDUCT.md"
so the CODE_OF_CONDUCT.md file is downloaded correctly; leave the MIT license
curl line untouched.
In `@CHANGELOG.md`:
- Around line 23-56: The changelog has duplicate and misordered sections: move
the entire "## [2.3.0] (2026-05-06)" block so it appears above the existing "##
[2.2.0]" entry, ensure a single "## [Unreleased]" header exists immediately at
the top of the file (above 2.3.0), and delete the stale "## [Unreleased]" block
later in the file (the old block whose contents describe v2.0.0/v2.1.0 work);
confirm the file follows descending semver order with only one "## [Unreleased]"
header and that the "## [2.3.0]" heading text is preserved exactly.
In `@CLAUDE.md`:
- Line 30: Update the `dist/` description line in CLAUDE.md to include the
missing OpenCode distribution so it matches the build pipeline and CHANGELOG:
add "OpenCode" (matching the `build_opencode` artifact written to
`dist/opencode/` by `scripts/build-dist.sh`) to the comma-separated list
alongside Codex, Gemini, Cursor, Cline, Windsurf, Goose, and Aider.
In `@docs/guides/command-reference.md`:
- Line 3: Update the stale "16" count to "14" in this document's frontmatter
description and the H1 blockquote so it matches docs/README.md; specifically
edit the description frontmatter value (the string starting "All 16 PitchDocs
commands...") and the H1 blockquote text (the line that reads "All 16 PitchDocs
commands") to read "All 14 PitchDocs commands" to remove the conflicting
numbers.
In `@docs/guides/other-ai-tools.md`:
- Around line 87-90: The compatibility table has inconsistent counts for
commands—update the "Slash commands (14 user-invocable: 8 + 6 from skills)" cell
to explicitly separate "total command files" vs "user-invocable commands" and
make the numbers match the rest of the doc (the earlier "16 command files" and
the "14 TOML command wrappers/files"); locate the table row labeled "Slash
commands (14 user-invocable: 8 + 6 from skills)" and change its text to
something like "Slash commands — total command files: 16; user-invocable: 14 (8
core + 6 from skills)" or the correct counts, and then update the other nearby
mentions ("16 command files", "14 TOML command wrappers/files") so they all
match; also ensure README.md, AGENTS.md, llms.txt and the bug report template
component dropdown are updated as sync points if counts or labels change.
In `@README.md`:
- Around line 204-216: Update the README intro that currently reads "ships
pre-built distributions for 6 more platforms" to reflect the actual count:
change it to "7 more platforms" (or to "7 more platforms (8 total including
OpenCode)" to match CHANGELOG and scripts/build-dist.sh). Locate the phrase in
README.md and ensure the table of platforms (rows: Codex CLI, Gemini CLI,
Cursor, Cline, Windsurf, Goose, Aider) remains unchanged.
In `@ROADMAP.md`:
- Line 5: The headline count "24 evaluation test cases" is inconsistent with the
metrics table entry "21 scenarios (95.2% Haiku)"; reconcile them by either
reverting the headline phrase "24 evaluation test cases" back to "21 evaluation
test cases" if no tests were added, or—if tests were actually added—update the
metrics table entry "21 scenarios (95.2% Haiku)" to "24 scenarios" and adjust
any related percent/notes and changelog entries to reflect the added tests;
locate the headline string and the metrics table row by searching for "24
evaluation test cases" and "21 scenarios (95.2% Haiku)" and make the matching
change.
In `@rules/docs-awareness.md`:
- Around line 1-5: Update the rule frontmatter by replacing the deprecated
paths: key with globs: and list comma-separated unquoted file patterns (e.g.,
README.md, docs/**, .github/ISSUE_TEMPLATE/**) so the rule scopes reliably
across Claude Code versions; also rename the top-level FUNDING.yml entry to
.github/FUNDING.yml to match GitHub's expected location. Target the frontmatter
keys in this file (the existing paths: line and the FUNDING.yml entry) and
change them to globs: with the corrected filename. Ensure formatting matches the
surrounding YAML frontmatter (no quotes and comma-separated patterns).
In `@scripts/build-dist.sh`:
- Around line 117-126: The hard-coded counts in build-dist.sh are stale; update
the copy loops to compute the actual number of items and use that in the log
messages instead of literal numbers. Specifically, in the commands copy loop
that iterates over "$COMMANDS_DIR"/*.md (and the corresponding TOML creation
step), track a counter (or collect filenames into an array) and log the computed
count (e.g., number of copied prompts and number of generated TOML files) rather
than "Copied 14..."/ "Created 14..."; make the same change for the skills copy
section (replace "Copied 15 skills" with a dynamically computed count) and apply
the dynamic-count pattern in any related functions or invocations such as
build_gemini and copy_skills so all summary log lines reflect real counts.
- Around line 49-84: The generated TOML/MDC is not escape-safe: command_to_toml
and command_to_mdc interpolate description (desc) and body raw, so quotes,
backslashes or a body containing """ break the output; also frontmatter_val is
fragile for multi-line or quoted YAML values. Fix by sanitizing/serializing
instead of raw interpolation: either replace shell interpolation with a small
Python helper that reads the source, parses frontmatter with pyyaml and writes
TOML via tomli_w (use tomllib/pyyaml + tomli_w to produce proper description and
multi-line literals), or at minimum escape desc (escape backslashes and double
quotes) and safely serialize body (replace any """ sequences or pick a delimiter
that cannot appear, or write body via printf '%s' "$body" into a here-doc using
a quoted delimiter like <<'TOML' so no interpolation occurs), and update
frontmatter_val to handle multi-line/quoted YAML values (use a Python/YAML parse
or robust grep/awk). Also run a validation step (--check) to parse the produced
TOML files before publishing.
In `@scripts/setup.sh`:
- Around line 74-75: The script currently treats presence of AGENTS.md alone as
a definitive signal for Codex by running the "[ -f \"$PROJECT_DIR/AGENTS.md\" ]
&& echo \"codex\" && return" branch, which is too generic; change this to only
auto-select Codex when a Codex-specific marker exists (e.g., check for a Codex
workspace marker like ".codex" or a codex config dir such as "~/.codex") or, if
only AGENTS.md is present without CLAUDE.md or any codex marker, do not
auto-evaluate to codex—either fall through to prompt the user for the platform
or print a message asking them to run the script with an explicit <platform>
argument; update the branch that currently references AGENTS.md and the echo
"codex" && return behavior accordingly (remove or guard the fallback) and ensure
CLAUDE.md detection remains unchanged.
In `@upstream-versions.json`:
- Around line 64-72: The "agent-skills" entry contains an unsupported published
version string; remove or replace the "version": "1.0" field in the agent-skills
object and instead either delete the version property entirely or set it to a
verifiable commit/date reference (e.g., use the GitHub commit hash or the
last-updated date "2026-04-22") so that the entry only contains verifiable
upstream provenance; update the entry that references "agent-skills" and ensure
related fields like "last_verified" remain accurate.
---
Outside diff comments:
In `@docs/guides/troubleshooting.md`:
- Around line 180-182: The FAQ link in the markdown sentence "Looking for the
headline questions? See the standalone **[FAQ](../faq/index.md)**" points to a
non-existent path and breaks the docs link-check workflow; update that link
target from ../faq/index.md to ../faq/faq.md so the anchor reads
**[FAQ](../faq/faq.md)** and ensure any other references to the old
../faq/index.md are replaced accordingly to prevent future broken links.
In `@docs/README.md`:
- Line 89: Update the stale count in the README by changing the phrase
"PitchDocs includes **16 specialised skills**" to "PitchDocs includes **15
specialised skills**" so it matches AGENTS.md, .cursorrules, and
.github/copilot-instructions.md; locate the exact string "PitchDocs includes
**16 specialised skills**" in docs/README.md and replace the numeric value only,
then run a quick grep across the repo to confirm all references consistently
state 15.
- Line 27: Update the broken FAQ links in docs/README.md that currently point to
"faq/index.md": find the link text "**[Frequently Asked
Questions](faq/index.md)**" (and any other occurrences of "faq/index.md") and
replace the path with the new location "docs/faq/faq.md" so the link becomes
"**[Frequently Asked Questions](docs/faq/faq.md)**"; verify both occurrences
(including the one at line 103) are updated and run the link checker/CI locally
to confirm the error is resolved.
In `@SKILL.md`:
- Around line 1-93: The linter reports MD010/no-hard-tabs in SKILL.md (line
198); replace the hard tab character on that line with spaces and ensure no
other tabs remain in the file so the docs/lint pipeline passes; search SKILL.md
for any '\t' characters (or use your editor's "show whitespace") and convert
them to spaces, then re-run the linter.
---
Duplicate comments:
In @.claude/rules/docs-awareness.md:
- Around line 1-5: The frontmatter uses the incorrect key and filename: replace
the top-level "paths:" key with "globs:" and update the listed "FUNDING.yml"
entry to the corrected ".github/FUNDING.yml" so the docs-awareness frontmatter
matches the other rules file; locate the frontmatter block containing "paths:"
and the "FUNDING.yml" string in docs-awareness and make those two substitutions
(keep all other entries unchanged).
---
Nitpick comments:
In `@pitchdocs.json`:
- Around line 7-96: Normalize the manifest by replacing every "companion":
"<path>" string with "companions": ["<path>"] so all companion metadata uses an
array shape; update the entries for the skills "feature-benefits",
"package-registry", "platform-profiles", "public-readme", "visual-standards"
(and "docs-verify" which already uses "companion") to use the plural
"companions" array form while leaving existing "companions" arrays intact and
preserving the same path values and ordering.
In `@scripts/build-dist.sh`:
- Around line 86-96: The copy_skills function can call cp with a glob that may
not match and produce a confusing error; modify copy_skills to check for
matching files before running cp: inside the loop over skill_dir (using
skill_name and SKILLS_DIR), test whether any files match "$skill_dir"SKILL*.md
(e.g. via a glob check or listing) and if none exist log/print a clear error
identifying the skill_name and continue or abort as desired, otherwise perform
the cp into "${target}/${skill_name}/". Ensure the guard avoids passing a
literal pattern to cp so the failure message names the offending skill.
- Around line 17-18: The PLUGIN_VERSION extraction in scripts/build-dist.sh is
brittle because it uses grep/head/sed and can pick up unrelated "version" keys;
replace that pipeline with a JSON parser (e.g., use jq -r '.version' on
.claude-plugin/plugin.json) to set the PLUGIN_VERSION variable reliably, then
keep the existing validation check ([ -n "$PLUGIN_VERSION" ] || { echo ...; exit
1; }) to fail fast if the version is missing or empty; update any related error
text if desired.
In `@scripts/setup.sh`:
- Around line 188-200: The interactive read -r answer in the .goosehints append
flow can block in non-interactive contexts; update the conditional around the
.goosehints handling to detect a TTY (e.g., [ -t 0 ]) and skip prompting when
stdin is not a TTY, defaulting to "no append" behavior, and also support an
explicit non-interactive override (environment variable or CLI flag like
--yes/--no-append) so callers can force append; adjust the block that references
read -r answer, .goosehints, PROJECT_DIR, DIST and use the existing log function
to record the chosen non-interactive default or flag-driven action.
In `@tests/RESULTS.md`:
- Around line 1-7: The report's frontmatter ("Date: 2026-03-14", "Plugin
version: 2.1.0") was partially edited to "15 skills, 10 commands, 5 agents"
creating an inconsistent historical record (the body still references v2.1.0 and
16 skills); either revert the single-line change so the v2.1.0 report remains
untouched, or fully migrate the update to a new v2.3.0 section/report by
changing the header fields ("Date", "Plugin version") and updating every
inventory reference (e.g., occurrences of "16 skills" and any
skill/command/agent counts) to match "15 skills, 10 commands, 5 agents" for
internal consistency.
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: e5161a6b-9af7-448e-a7c0-7e72466ae293
⛔ Files ignored due to path filters (86)
dist/aider/.aider.conf.ymlis excluded by!**/dist/**dist/aider/CONVENTIONS.mdis excluded by!**/dist/**dist/cline/.clinerules/pitchdocs-content-filter.mdis excluded by!**/dist/**dist/cline/.clinerules/pitchdocs-standards.mdis excluded by!**/dist/**dist/cline/README.mdis excluded by!**/dist/**dist/codex/.agents/skills/api-reference/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/changelog/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/doc-refresh/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/docs-verify/SKILL-reference.mdis excluded by!**/dist/**dist/codex/.agents/skills/docs-verify/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/feature-benefits/SKILL-signals.mdis excluded by!**/dist/**dist/codex/.agents/skills/feature-benefits/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/geo-optimisation/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/launch-artifacts/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/llms-txt/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/package-registry/SKILL-reference.mdis excluded by!**/dist/**dist/codex/.agents/skills/package-registry/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/pitchdocs-suite/SKILL-reference.mdis excluded by!**/dist/**dist/codex/.agents/skills/pitchdocs-suite/SKILL-templates.mdis excluded by!**/dist/**dist/codex/.agents/skills/pitchdocs-suite/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/platform-profiles/SKILL-tables.mdis excluded by!**/dist/**dist/codex/.agents/skills/platform-profiles/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/public-readme/SKILL-reference.mdis excluded by!**/dist/**dist/codex/.agents/skills/public-readme/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/roadmap/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/user-guides/SKILL-reference.mdis excluded by!**/dist/**dist/codex/.agents/skills/user-guides/SKILL-templates.mdis excluded by!**/dist/**dist/codex/.agents/skills/user-guides/SKILL.mdis excluded by!**/dist/**dist/codex/.agents/skills/visual-standards/SKILL-reference.mdis excluded by!**/dist/**dist/codex/.agents/skills/visual-standards/SKILL.mdis excluded by!**/dist/**dist/codex/.codex/agents/pitchdocs-writer.mdis excluded by!**/dist/**dist/codex/AGENTS.mdis excluded by!**/dist/**dist/codex/doc-standards.mdis excluded by!**/dist/**dist/codex/prompts/activate.mdis excluded by!**/dist/**dist/codex/prompts/docs-audit.mdis excluded by!**/dist/**dist/codex/prompts/features.mdis excluded by!**/dist/**dist/codex/prompts/geo.mdis excluded by!**/dist/**dist/codex/prompts/launch.mdis excluded by!**/dist/**dist/codex/prompts/platform.mdis excluded by!**/dist/**dist/codex/prompts/readme.mdis excluded by!**/dist/**dist/codex/prompts/user-guide.mdis excluded by!**/dist/**dist/cursor/.cursor/agents/pitchdocs-writer.mdis excluded by!**/dist/**dist/cursor/.cursor/rules/pitchdocs-filter.mdcis excluded by!**/dist/**dist/cursor/.cursor/rules/pitchdocs-standards.mdcis excluded by!**/dist/**dist/gemini/GEMINI.mdis excluded by!**/dist/**dist/gemini/commands/activate.tomlis excluded by!**/dist/**dist/gemini/commands/docs-audit.tomlis excluded by!**/dist/**dist/gemini/commands/features.tomlis excluded by!**/dist/**dist/gemini/commands/geo.tomlis excluded by!**/dist/**dist/gemini/commands/launch.tomlis excluded by!**/dist/**dist/gemini/commands/platform.tomlis excluded by!**/dist/**dist/gemini/commands/readme.tomlis excluded by!**/dist/**dist/gemini/commands/user-guide.tomlis excluded by!**/dist/**dist/gemini/doc-standards.mdis excluded by!**/dist/**dist/gemini/gemini-extension.jsonis excluded by!**/dist/**dist/gemini/skills/api-reference/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/changelog/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/doc-refresh/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/docs-verify/SKILL-reference.mdis excluded by!**/dist/**dist/gemini/skills/docs-verify/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/feature-benefits/SKILL-signals.mdis excluded by!**/dist/**dist/gemini/skills/feature-benefits/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/geo-optimisation/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/launch-artifacts/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/llms-txt/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/package-registry/SKILL-reference.mdis excluded by!**/dist/**dist/gemini/skills/package-registry/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/pitchdocs-suite/SKILL-reference.mdis excluded by!**/dist/**dist/gemini/skills/pitchdocs-suite/SKILL-templates.mdis excluded by!**/dist/**dist/gemini/skills/pitchdocs-suite/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/platform-profiles/SKILL-tables.mdis excluded by!**/dist/**dist/gemini/skills/platform-profiles/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/public-readme/SKILL-reference.mdis excluded by!**/dist/**dist/gemini/skills/public-readme/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/roadmap/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/user-guides/SKILL-reference.mdis excluded by!**/dist/**dist/gemini/skills/user-guides/SKILL-templates.mdis excluded by!**/dist/**dist/gemini/skills/user-guides/SKILL.mdis excluded by!**/dist/**dist/gemini/skills/visual-standards/SKILL-reference.mdis excluded by!**/dist/**dist/gemini/skills/visual-standards/SKILL.mdis excluded by!**/dist/**dist/goose/.goosehintsis excluded by!**/dist/**dist/goose/recipes/pitchdocs-changelog.yamlis excluded by!**/dist/**dist/goose/recipes/pitchdocs-features.yamlis excluded by!**/dist/**dist/goose/recipes/pitchdocs-readme.yamlis excluded by!**/dist/**dist/opencode/README.mdis excluded by!**/dist/**dist/windsurf/.windsurf/rules/pitchdocs.mdis excluded by!**/dist/**
📒 Files selected for processing (50)
.claude-plugin/plugin.json.claude/rules/docs-awareness.md.claude/skills/changelog/SKILL.md.claude/skills/doc-refresh/SKILL.md.claude/skills/docs-verify/SKILL.md.claude/skills/llms-txt/SKILL.md.claude/skills/package-registry/SKILL.md.claude/skills/pitchdocs-suite/SKILL-templates.md.claude/skills/roadmap/SKILL.md.claude/skills/user-guides/SKILL-reference.md.claude/skills/visual-standards/SKILL.md.clinerules.cursorrules.github/copilot-instructions.md.release-please-manifest.json.windsurfrulesAGENTS.mdCHANGELOG.mdCLAUDE.mdGEMINI.mdREADME.mdROADMAP.mdSKILL.mdagents/docs-writer-flat.mdcommands/changelog.mdcommands/doc-refresh.mdcommands/docs-verify.mdcommands/llms-txt.mdcommands/roadmap.mdcommands/visual-standards.mddocs/README.mddocs/faq/faq.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/tutorials/build-your-first-docs-suite.mdllms-full.txtllms.txtpitchdocs.jsonrelease-please-config.jsonrules/docs-awareness.mdscripts/build-dist.shscripts/setup.shtests/RESULTS.mdupstream-versions.json
💤 Files with no reviewable changes (6)
- commands/doc-refresh.md
- commands/llms-txt.md
- commands/docs-verify.md
- commands/roadmap.md
- commands/changelog.md
- commands/visual-standards.md
|
|
||
| **Arguments:** No arguments → `llms.txt` only. `full` → both `llms.txt` and `llms-full.txt`. Path argument → generate for a specific project directory. | ||
|
|
||
| Generate structured, LLM-friendly content indexes following the [llmstxt.org](https://llmstxt.org/) specification. |
There was a problem hiding this comment.
Orphaned sentence — duplicate of content already in the new Invocation section.
Line 24 (Generate structured, LLM-friendly content indexes following the [llmstxt.org](https://llmstxt.org/) specification.) is a leftover from the pre-refactor body. The Invocation section (line 13) already states the same thing. The sentence now sits awkwardly between ## Invocation and ## Background with no heading of its own.
🗑️ Proposed fix
-Generate structured, LLM-friendly content indexes following the [llmstxt.org](https://llmstxt.org/) specification.
-
## Background📝 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.
| Generate structured, LLM-friendly content indexes following the [llmstxt.org](https://llmstxt.org/) specification. | |
| ## Background |
🤖 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 @.claude/skills/llms-txt/SKILL.md at line 24, Remove the orphaned duplicate
sentence "Generate structured, LLM-friendly content indexes following the
[llmstxt.org](https://llmstxt.org/) specification." from SKILL.md (it currently
sits between ## Invocation and ## Background) since the same text already
appears in the Invocation section; either delete this line entirely or move it
under an appropriate heading if you intended it as a separate note so the
document no longer contains the redundant standalone sentence.
| # patreon: project-name | ||
| # polar: org-or-user # developer-focused funding (added to GitHub's allowlist) | ||
| # liberapay: project-name | ||
| # tidelift: npm/package-name # npm:foo, pypi:foo, etc. | ||
| # buy_me_a_coffee: username | ||
| # thanks_dev: u/username # GitHub Sponsors alternative | ||
| # issuehunt: org/repo | ||
| # custom: ["https://example.com/donate"] |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What funding platforms are supported in GitHub FUNDING.yml file as of 2026?
💡 Result:
Supported funding platforms in a GitHub FUNDING.yml file (as of 2026-05-08): - GitHub Sponsors: github: USERNAME (or github: [USERNAME, ...]) [1] - Patreon: patreon: USERNAME [1] - Open Collective: open_collective: USERNAME [1] - Ko-fi: ko_fi: USERNAME [1] - Liberapay: liberapay: USERNAME [1] - Tidelift: tidelift: PLATFORM-NAME/PACKAGE-NAME [1] - IssueHunt: issuehunt: USERNAME [1] - LFX Mentorship (formerly CommunityBridge): community_bridge: PROJECT-NAME [1] - Polar: polar: USERNAME [1] - Buy Me a Coffee: buy_me_a_coffee: USERNAME [1] - thanks.dev: thanks_dev: u/gh/USERNAME [1] - Custom funding URL(s): custom: LINK1 or custom: [LINK1, LINK2, LINK3, LINK4] [1] (These platform keys are the ones documented for the FUNDING.yml sponsor-button configuration.) [1]
Citations:
Fix two FUNDING.yml key formats to match GitHub's specification.
The template has inaccurate value formats for two funding platforms:
thanks_dev: u/usernameshould bethanks_dev: u/gh/username(missing theghcomponent per GitHub docs)issuehunt: org/reposhould beissuehunt: USERNAME(IssueHunt format uses a single username, not org/repo)
The patreon, polar, liberapay, tidelift, buy_me_a_coffee, and custom keys are correctly formatted.
🤖 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 @.claude/skills/pitchdocs-suite/SKILL-templates.md around lines 318 - 325,
Update the FUNDING.yml template entries to match GitHub's required formats:
change the thanks_dev line so the value includes the "gh" namespace (replace
"thanks_dev: u/username" with the "gh" style, e.g., "thanks_dev:
u/gh/username"), and change the issuehunt entry from the org/repo form to the
single-username format (replace "issuehunt: org/repo" with "issuehunt:
USERNAME"); update the template lines for the thanks_dev and issuehunt keys
accordingly so they conform to GitHub's specification.
| | `wardleyMap` | Strategy diagrams — capability evolution from genesis → custom → product → commodity (Mermaid 11+) | | ||
|
|
||
| **Styling:** Mermaid 2026's "neo look" refresh applies cleaner defaults to flowchart, class, sequence, state, and gitGraph diagrams. To opt into the new defaults explicitly, set `%%{init: {"look": "neo"}}%%` at the top of the diagram block. To keep the classic look across versions, use `"look": "classic"`. |
There was a problem hiding this comment.
Tighten the Mermaid minimum version from "Mermaid 11+" to "Mermaid 11.14.0+".
Both wardleyMap and the neo look were introduced in Mermaid 11.14.0 specifically — the Neo and Redux themes and the neo look require Mermaid.js 11.14.0 or later, and the wardley-beta diagram type requires Mermaid 11.14.0+. "Mermaid 11+" could mislead users on earlier 11.x patch versions.
📝 Proposed fix
-| `wardleyMap` | Strategy diagrams — capability evolution from genesis → custom → product → commodity (Mermaid 11+) |
+| `wardleyMap` | Strategy diagrams — capability evolution from genesis → custom → product → commodity (Mermaid 11.14.0+) |
-**Styling:** Mermaid 2026's "neo look" refresh applies cleaner defaults to flowchart, class, sequence, state, and gitGraph diagrams.
+**Styling:** Mermaid's "neo look" (11.14.0+) applies cleaner defaults to flowchart, class, sequence, state, and gitGraph diagrams.📝 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.
| | `wardleyMap` | Strategy diagrams — capability evolution from genesis → custom → product → commodity (Mermaid 11+) | | |
| **Styling:** Mermaid 2026's "neo look" refresh applies cleaner defaults to flowchart, class, sequence, state, and gitGraph diagrams. To opt into the new defaults explicitly, set `%%{init: {"look": "neo"}}%%` at the top of the diagram block. To keep the classic look across versions, use `"look": "classic"`. | |
| | `wardleyMap` | Strategy diagrams — capability evolution from genesis → custom → product → commodity (Mermaid 11.14.0+) | | |
| **Styling:** Mermaid's "neo look" (11.14.0+) applies cleaner defaults to flowchart, class, sequence, state, and gitGraph diagrams. To opt into the new defaults explicitly, set `%%{init: {"look": "neo"}}%%` at the top of the diagram block. To keep the classic look across versions, use `"look": "classic"`. |
🤖 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 @.claude/skills/visual-standards/SKILL.md around lines 98 - 100, Update the
Mermaid minimum-version wording: change any occurrences that say "Mermaid 11+"
(notably the `wardleyMap` row and the paragraph referencing the "neo look") to
explicitly state "Mermaid 11.14.0+" since the `wardley-beta`/`wardleyMap`
diagram type and the Neo/"neo" look require Mermaid.js 11.14.0 or later; ensure
both the table cell for `wardleyMap` and the sentence about opting into the neo
look use "Mermaid 11.14.0+".
| For HIGH-risk files, always fetch rather than generate: | ||
| ```bash | ||
| # Contributor Covenant v3.0 | ||
| curl -sL "https://www.contributor-covenant.org/version/3/0/code_of_conduct/code_of_conduct.md" -o CODE_OF_CONDUCT.md | ||
|
|
||
| # MIT License | ||
| curl -sL "https://raw.githubusercontent.com/spdx/license-list-data/main/text/MIT.txt" -o LICENSE | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Does https://www.contributor-covenant.org/version/3/0/code_of_conduct/code_of_conduct.md exist as a downloadable file?
💡 Result:
The URL https://www.contributor-covenant.org/version/3/0/code_of_conduct/code_of_conduct.md does not appear to exist as a downloadable file. Instead, the Contributor Covenant 3.0 code of conduct is published at the HTML page https://www.contributor-covenant.org/version/3/0/code_of_conduct/ and https://www.contributor-covenant.org/version/3/0/code_of_conduct.html [1][2]. Evidence: the site’s Contributor Covenant 3 landing page is the directory/HTML route (not a.md asset) [1][2], while the downloadable Markdown source for “Contributor Covenant 3.0 Code of Conduct” is available from the project repository as CODE_OF_CONDUCT.md [3]. So, based on what the official site exposes, that specific.md path is not a valid downloadable resource, whereas the code of conduct content for v3.0 is available via the site’s HTML page and via the repository’s Markdown file [1][2][3].
Citations:
- 1: https://www.contributor-covenant.org/version/3/0/code_of_conduct/
- 2: https://www.contributor-covenant.org/version/3/0/code_of_conduct.html
- 3: https://github.com/ContributorCovenant/contributor_covenant/blob/release/CODE_OF_CONDUCT.md
Fix the Contributor Covenant v3.0 fetch URL — .md extension does not exist
The fetch command at line 159 uses an invalid path:
curl -sL "https://www.contributor-covenant.org/version/3/0/code_of_conduct/code_of_conduct.md"The .md file is not available from contributor-covenant.org. The site publishes v3.0 as HTML pages only. Use the confirmed GitHub raw Markdown source instead:
# Contributor Covenant v3.0 — fetch from upstream repository
curl -sL "https://raw.githubusercontent.com/ContributorCovenant/contributor_covenant/release/CODE_OF_CONDUCT.md" -o CODE_OF_CONDUCT.md🤖 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 `@agents/docs-writer-flat.md` around lines 156 - 163, Replace the invalid
Contributor Covenant v3.0 curl URL that points to an HTML-only path with the
upstream raw GitHub Markdown source: update the curl command that currently uses
"https://www.contributor-covenant.org/version/3/0/code_of_conduct/code_of_conduct.md"
to instead fetch
"https://raw.githubusercontent.com/ContributorCovenant/contributor_covenant/release/CODE_OF_CONDUCT.md"
so the CODE_OF_CONDUCT.md file is downloaded correctly; leave the MIT license
curl line untouched.
| ## [2.3.0](https://github.com/littlebearapps/pitchdocs/compare/v2.2.0...v2.3.0) (2026-05-06) | ||
|
|
||
| ### Fixed | ||
| ### Added | ||
|
|
||
| * **Plugin review issues from v2.1.0 release** — Version sync in skill frontmatter, hook exit codes, stale references to moved skills, and evaluation test coverage now properly aligned with production state. | ||
| * **Cross-platform distribution build pipeline** — `scripts/build-dist.sh` generates pre-built distributions for 8 platforms (Codex CLI `.agents/skills/`, Gemini CLI `skills/`, Cursor `.cursor/`, Cline, Windsurf, Goose, Aider, OpenCode) from canonical `.claude/` sources. Run `bash scripts/build-dist.sh` after editing skills, commands, or rules. Use `bash scripts/build-dist.sh --check` in CI to verify sync. | ||
| * **Agent Skills standard compliance** — PitchDocs now follows the [Agent Skills](https://agentskills.io) cross-tool open standard. Badge added to README; `agent-skills` keyword in `plugin.json`; citations in CLAUDE.md, AGENTS.md, and bridge files. | ||
| * **`paths:` frontmatter on `docs-awareness` rule** — path-scoped activation only fires on documentation file edits (README, CHANGELOG, ROADMAP, CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, SUPPORT, docs/**, llms.txt, llms-full.txt, .github/ISSUE_TEMPLATE/**, FUNDING.yml). Forward-compatible with newer Claude Code. | ||
| * **Portable `docs-writer-flat` agent** — single-file pipeline at `agents/docs-writer-flat.md` for non-Claude Code platforms without sub-agent support. | ||
| * **Platform-neutral `pitchdocs.json` manifest** — machine-readable index of all 15 skills, 10 commands, 4 agents, and 3 rules for setup tooling. | ||
| * **Universal `scripts/setup.sh` installer** — auto-detects platform and copies the matching pre-built distribution. | ||
|
|
||
| ### Removed | ||
| ### Changed | ||
|
|
||
| * **`skill-authoring` skill** — This meta-guide about token budgets for writing Claude Code skills is out of scope for PitchDocs (a documentation plugin). Skill authoring guidance belongs in the `plugin-dev` plugin instead. | ||
| * **6 command/skill name collisions resolved** — `changelog`, `roadmap`, `visual-standards`, `docs-verify`, `doc-refresh`, `llms-txt` previously existed as both commands and skills. Per Claude Code's command/skill merge ([docs](https://code.claude.com/docs/en/skills)), skills now take precedence on name collisions, making the 6 command files dead code. Each command's procedural prose has been migrated into the corresponding skill's `## Invocation` section, with `argument-hint` and `allowed-tools` added to skill frontmatter; the 6 command files have been deleted. Closes [#41](https://github.com/littlebearapps/pitchdocs/issues/41) (skill activation parity). | ||
| * **Canonical counts updated** — 15 skills (was stale "16"), 10 commands (8 active + 2 stubs), 14 user-invocable slash commands total (8 from `commands/` + 6 from skills). | ||
| * **FAQ filename** — `docs/faq/index.md` renamed to `docs/faq/faq.md` for a cleaner marketing-site URL (`/help/pitchdocs/faq/` instead of `/help/pitchdocs/index/`). Closes [#49](https://github.com/littlebearapps/pitchdocs/issues/49). Pure rename — no content change. | ||
| * **`scripts/build-dist.sh`** — version is now read from `.claude-plugin/plugin.json` rather than hardcoded; release-please bumps cascade automatically to `dist/gemini/gemini-extension.json`. | ||
|
|
||
| ### Security | ||
| ### Documentation | ||
|
|
||
| * **GitHub Actions supply chain security** — All third-party GitHub Actions are now pinned to specific commit SHAs instead of mutable version tags, preventing malicious updates. CODEOWNERS file added for transparent code review governance. | ||
| * **`package-registry` skill** — npm CLI ≥ 11.5.1 and Node ≥ 22.14.0 floors documented; CircleCI/private-repo provenance unsupported caveat; PyPI PEP 740 attestations now default via `pypa/gh-action-pypi-publish` (≈20k packages currently covered). | ||
| * **`pitchdocs-suite/SKILL-templates.md`** — GitHub Issue Forms `attachments` field example added; alphabetical-template-ordering note (2026-03-05); Issue Fields preview note (2026-03-12); Django Contributor Covenant 3.0 adoption (2026-04-15) cited as credibility signal; FUNDING.yml expanded with `polar:`, `patreon:`, `liberapay:`, `tidelift:`, `buy_me_a_coffee:`, `thanks_dev:`, `issuehunt:`. | ||
| * **`visual-standards` skill** — new Diagrams (Mermaid) section with diagram-type table including Wardley Maps; "neo look" styling note; GitHub theme auto-sync warning when `%%{init}%%` is set. | ||
| * **`docs/guides/other-ai-tools.md`** — feature-support matrix updated for Cursor 2.6+ AGENTS.md primacy, Antigravity 1.20+ AGENTS.md support, and Gemini CLI v0.25+ native skills/. | ||
| * **`llms-full.txt`** — fully regenerated from current `llms.txt` index, removing pre-v2.0 references and the removed `skill-authoring` skill. | ||
| * **All `last_verified:` frontmatter** — bumped from "2.1.0" to "2.3.0" across `docs/guides/` and `docs/tutorials/`. | ||
|
|
||
| ### Internal | ||
|
|
||
| * **`upstream-versions.json`** — refreshed all `last_verified` dates to 2026-05-06 across 7 sources; added new `agent-skills` v1.0 source entry; added `notes` fields capturing GitHub Issue Forms updates, npm version floors, PEP 740 default behaviour, and Django CC adoption. | ||
| * **Forward-compat improvement** — `pitchdocs.json` added to `release-please-config.json` `extra-files` so future version bumps cascade automatically. | ||
| * **All bridge files synced** — `.cursorrules`, `.clinerules`, `.windsurfrules`, `.github/copilot-instructions.md`, `GEMINI.md` updated for accurate counts and Agent Skills branding. | ||
|
|
||
| ## [Unreleased] |
There was a problem hiding this comment.
Two [Unreleased] sections and broken version ordering — fix before release.
Two real problems with the v2.3.0 changelog placement:
- Duplicate
[Unreleased]headers. A new empty## [Unreleased]was inserted at line 56 below the new 2.3.0 entry, but the pre-existing## [Unreleased]block at line 191 (with stale Breaking Changes / Added / Documentation / Fixed content describing v2.0.0/v2.1.0 work) wasn't removed. Markdown renderers and release-please will both be confused, and downstream tooling that scrapes "Unreleased" will pick the wrong block. - Newest-first ordering is broken. Current order is
2.2.0 → 2.3.0 → [Unreleased] → 2.1.0 → 2.0.0 → …. Keep a Changelog convention (and the rest of this file) is descending semver with[Unreleased]at the very top.
Recommended cleanup: move the new 2.3.0 block above 2.2.0, place a single empty ## [Unreleased] above 2.3.0, and delete the stale [Unreleased] block at lines 191–216 (its contents are already represented in v2.0.0/v2.1.0 above).
As per coding guidelines: "Use Keep a Changelog format for CHANGELOG.md with user-benefit language".
Also applies to: 191-216
🧰 Tools
🪛 LanguageTool
[uncategorized] ~29-~29: The official name of this software platform is spelled with a capital “H”.
Context: ...ORT, docs/, llms.txt, llms-full.txt, .github/ISSUE_TEMPLATE/, FUNDING.yml). Forwar...
(GITHUB)
[uncategorized] ~54-~54: The official name of this software platform is spelled with a capital “H”.
Context: ...ules, .clinerules, .windsurfrules, .github/copilot-instructions.md, GEMINI.md` u...
(GITHUB)
🤖 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 `@CHANGELOG.md` around lines 23 - 56, The changelog has duplicate and
misordered sections: move the entire "## [2.3.0] (2026-05-06)" block so it
appears above the existing "## [2.2.0]" entry, ensure a single "## [Unreleased]"
header exists immediately at the top of the file (above 2.3.0), and delete the
stale "## [Unreleased]" block later in the file (the old block whose contents
describe v2.0.0/v2.1.0 work); confirm the file follows descending semver order
with only one "## [Unreleased]" header and that the "## [2.3.0]" heading text is
preserved exactly.
| --- | ||
| name: docs-awareness | ||
| description: Documentation trigger map — surface PitchDocs commands at the right documentation moments (file edits, version bumps, release prep). Advisory; never blocks work. | ||
| paths: README.md, CHANGELOG.md, ROADMAP.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, docs/**, llms.txt, llms-full.txt, .github/ISSUE_TEMPLATE/**, .github/PULL_REQUEST_TEMPLATE.md, FUNDING.yml | ||
| --- |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Claude Code rules frontmatter globs vs paths field which works 2025 2026
💡 Result:
Short answer (2025–2026): Prefer globs: for reliable glob-scoped rules; paths: has documentation/implementation issues in early 2026 (quoted strings and YAML list forms often don’t work, multiple patterns may not all match, and user-level rules under ~/.claude/rules/ may be ignored). 1) What the official docs say - Claude Code rules in.claude/rules/ can be scoped to file patterns using YAML frontmatter with a paths field (glob patterns); these “conditional rules … only apply when Claude is working with files matching the specified patterns.” [1] 2) What is actually reported to work vs not work (2026 bug reports) A. paths: frontmatter syntax problems - The documented YAML frontmatter syntax for paths has been reported as incorrect: the reporter found the “documented string syntax does not work” and that only a specific YAML array form loaded; the issue includes examples of patterns that failed to load. [2] - Separate reports indicate that YAML list syntax in paths can be parsed incorrectly (array elements concatenated) due to the parser expecting a string, causing broken globs. [3][4] - Quoted paths values may also fail (e.g., paths: "/.cs" reported failing while unquoted paths: /.cs worked). [3] - Multiple patterns under paths may only evaluate the first pattern (others ignored). [5] B. globs: frontmatter is the reliable alternative - Multiple reports state globs: works more reliably than the documented paths: formats for glob-scoped rule behavior. [6] C. Loading semantics: read vs write - Path-based rules are reported to load only when Claude reads matching files, not when it writes/creates them (at least in the reported case). [7] D. user-level vs project-level rules - User-level rules placed in ~/.claude/rules/ with paths: have been reported as “never loaded,” while the same rule works when placed in project-level rules. [4][8] 3) Practical guidance (works in 2025/2026 per reports) - Use globs: (rather than paths:) when you need glob-scoped loading, because reports indicate it works reliably. [6] - If you use paths:, be cautious: unquoted CSV-style strings on one line may work in some cases; YAML arrays/lists and quoted strings are repeatedly reported as broken. [3][2][4] - Assume path-scoped rules trigger on read/open rather than write/create operations. [7] Confidence: High that official docs describe paths-based scoping, and high that multiple 2026 reports describe paths: syntax/behavior issues and that globs: is the practical workaround. Lower confidence on exactly which single syntax form will work for all users/versions, because the evidence is largely from community issues rather than updated official spec text.
Citations:
- 1: https://docs.anthropic.com/en/docs/claude-code/claude-md
- 2: [DOCS]
paths:frontmatter syntax in rules files is incorrect anthropics/claude-code#16038 - 3: [DOCS] paths: frontmatter syntax in rules files is incorrect anthropics/claude-code#19377
- 4: [BUG] paths: frontmatter in user-level rules (~/.claude/rules/) is ignored anthropics/claude-code#21858
- 5: [BUG] paths: frontmatter with multiple patterns only matches first pattern; globs: has no scoping at all anthropics/claude-code#45587
- 6: Documentation: .claude/rules/ frontmatter format incorrect - globs works, paths with quotes/YAML list does not anthropics/claude-code#17204
- 7: Path-based rules (.claude/rules/ with paths: frontmatter) are not loaded on Write tool — only on Read anthropics/claude-code#23478
- 8: paths field in ~/.claude/rules/ frontmatter not working - rules with paths are not loaded anthropics/claude-code#22170
🌐 Web query:
GitHub FUNDING.yml standard location .github or root 2025 2026
💡 Result:
The standard location for the GitHub FUNDING.yml file is in the repository's.github folder, on the default branch [1][2]. Official GitHub documentation explicitly states: "You can configure your sponsor button by editing a FUNDING.yml file in your repository's .github folder" [1][2]. This enables the sponsor button in the repository. While some non-official sources mention placing it in the repository root (e.g., for non-GitHub hosts like GitLab) [3], or tools that generate it there [4], GitHub's authoritative guidance specifies.github/FUNDING.yml. No changes to this standard are indicated in sources from 2025 or 2026 [5].
Citations:
- 1: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
- 2: https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
- 3: https://gist.github.com/Poussinou/c253ff56559ab42d08a46de1688a0fe8
- 4: https://nova.cbnventures.io/docs/cli/generators/github/funding/
- 5: FUNDING.yml custom links does not include information on valid formats github/docs#35690
Replace paths: with globs: for reliable rule scoping
The paths: frontmatter key has documented issues in Claude Code (issues #17204, #13905, #16038, #19377, #21858, #45587, #23478, #22170) where it silently fails to scope rules correctly. Use globs: with comma-separated unquoted patterns instead — this field works reliably across Claude Code versions.
Also, FUNDING.yml should be .github/FUNDING.yml per GitHub's official standard. The root-level FUNDING.yml is not the expected location.
🛠️ Suggested fix
---
name: docs-awareness
description: Documentation trigger map — surface PitchDocs commands at the right documentation moments (file edits, version bumps, release prep). Advisory; never blocks work.
-paths: README.md, CHANGELOG.md, ROADMAP.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, docs/**, llms.txt, llms-full.txt, .github/ISSUE_TEMPLATE/**, .github/PULL_REQUEST_TEMPLATE.md, FUNDING.yml
+globs: README.md, CHANGELOG.md, ROADMAP.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, docs/**, llms.txt, llms-full.txt, .github/ISSUE_TEMPLATE/**, .github/PULL_REQUEST_TEMPLATE.md, .github/FUNDING.yml
---📝 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.
| --- | |
| name: docs-awareness | |
| description: Documentation trigger map — surface PitchDocs commands at the right documentation moments (file edits, version bumps, release prep). Advisory; never blocks work. | |
| paths: README.md, CHANGELOG.md, ROADMAP.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, docs/**, llms.txt, llms-full.txt, .github/ISSUE_TEMPLATE/**, .github/PULL_REQUEST_TEMPLATE.md, FUNDING.yml | |
| --- | |
| --- | |
| name: docs-awareness | |
| description: Documentation trigger map — surface PitchDocs commands at the right documentation moments (file edits, version bumps, release prep). Advisory; never blocks work. | |
| globs: README.md, CHANGELOG.md, ROADMAP.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md, docs/**, llms.txt, llms-full.txt, .github/ISSUE_TEMPLATE/**, .github/PULL_REQUEST_TEMPLATE.md, .github/FUNDING.yml | |
| --- |
🤖 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 `@rules/docs-awareness.md` around lines 1 - 5, Update the rule frontmatter by
replacing the deprecated paths: key with globs: and list comma-separated
unquoted file patterns (e.g., README.md, docs/**, .github/ISSUE_TEMPLATE/**) so
the rule scopes reliably across Claude Code versions; also rename the top-level
FUNDING.yml entry to .github/FUNDING.yml to match GitHub's expected location.
Target the frontmatter keys in this file (the existing paths: line and the
FUNDING.yml entry) and change them to globs: with the corrected filename. Ensure
formatting matches the surrounding YAML frontmatter (no quotes and
comma-separated patterns).
| command_to_toml() { | ||
| local src="$1" dest="$2" | ||
| local desc body name | ||
| desc=$(frontmatter_val "$src" "description" | sed 's/: \$ARGUMENTS$//') | ||
| name=$(basename "$src" .md) | ||
| body=$(strip_frontmatter "$src") | ||
|
|
||
| cat > "$dest" <<TOML | ||
| description = "${desc}" | ||
|
|
||
| [prompt] | ||
| text = """ | ||
| ${body} | ||
|
|
||
| --- | ||
| For the full PitchDocs skill reference, read the corresponding SKILL.md file | ||
| from the PitchDocs skills/ directory. | ||
| """ | ||
| TOML | ||
| } | ||
|
|
||
| # Convert a PitchDocs command .md to Cursor .mdc agent-selected rule | ||
| command_to_mdc() { | ||
| local src="$1" dest="$2" | ||
| local desc body | ||
| desc=$(frontmatter_val "$src" "description" | sed 's/: \$ARGUMENTS$//') | ||
| body=$(strip_frontmatter "$src") | ||
|
|
||
| cat > "$dest" <<MDC | ||
| --- | ||
| description: "${desc} — PitchDocs documentation standards and workflow" | ||
| --- | ||
|
|
||
| ${body} | ||
| MDC | ||
| } |
There was a problem hiding this comment.
TOML/MDC generation isn't escape-safe for description or body.
command_to_toml interpolates ${desc} directly into a "…" TOML string and ${body} directly inside a """…""" literal. Two real failure modes:
- Description containing
"(or unescaped backslash) — produces invalid TOML/MDC. Same issue incommand_to_mdc(line 79). - Body containing
"""— terminates the TOML multi-line literal early and leaves trailing content as syntax errors. Markdown command bodies in this repo include code/heredoc fragments; future commands could legitimately introduce""".
frontmatter_val (line 39) is also fragile: it can't handle YAML values that span multiple lines, contain :, or use single quotes, and it strips a trailing " even when the value wasn't quoted.
Suggest either escaping (printf '%s' "$desc" | sed 's/\\/\\\\/g; s/"/\\"/g') before interpolation, or — better — switching to a small Python helper using the tomllib/tomli_w and pyyaml modules to generate the per-platform manifests deterministically. At minimum, validate the generated TOML files in --check mode before they ship.
🧰 Tools
🪛 Shellcheck (0.11.0)
[info] 52-52: Expressions don't expand in single quotes, use double quotes for that.
(SC2016)
[info] 74-74: Expressions don't expand in single quotes, use double quotes for that.
(SC2016)
🤖 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 `@scripts/build-dist.sh` around lines 49 - 84, The generated TOML/MDC is not
escape-safe: command_to_toml and command_to_mdc interpolate description (desc)
and body raw, so quotes, backslashes or a body containing """ break the output;
also frontmatter_val is fragile for multi-line or quoted YAML values. Fix by
sanitizing/serializing instead of raw interpolation: either replace shell
interpolation with a small Python helper that reads the source, parses
frontmatter with pyyaml and writes TOML via tomli_w (use tomllib/pyyaml +
tomli_w to produce proper description and multi-line literals), or at minimum
escape desc (escape backslashes and double quotes) and safely serialize body
(replace any """ sequences or pick a delimiter that cannot appear, or write body
via printf '%s' "$body" into a here-doc using a quoted delimiter like <<'TOML'
so no interpolation occurs), and update frontmatter_val to handle
multi-line/quoted YAML values (use a Python/YAML parse or robust grep/awk). Also
run a validation step (--check) to parse the produced TOML files before
publishing.
| for cmd in "$COMMANDS_DIR"/*.md; do | ||
| local name | ||
| name=$(basename "$cmd") | ||
| # Skip stubs | ||
| case "$name" in | ||
| ai-context.md|context-guard.md) continue ;; | ||
| esac | ||
| cp "$cmd" "$d/prompts/$name" | ||
| done | ||
| log "Copied 14 command prompts to prompts/" |
There was a problem hiding this comment.
Hard-coded "14 command prompts / 14 TOML command files" log message will go stale.
Per the PR summary and CHANGELOG ("10 commands (8 active + 2 stubs)"), commands/ now contains 10 files; the loop above skips the 2 stubs, so it actually copies/converts 8 files, not 14. The log lines Copied 14 command prompts and Created 14 TOML command files are leftover hard-coded counts from the pre-collision-resolution inventory and are now misleading. Same risk applies to Copied 15 skills (lines 110 and 157) — any future skill addition will silently drift.
Replace with the actual count derived from the loop:
✏️ Suggested fix
- for cmd in "$COMMANDS_DIR"/*.md; do
- local name
- name=$(basename "$cmd")
+ local copied=0
+ for cmd in "$COMMANDS_DIR"/*.md; do
+ local name
+ name=$(basename "$cmd")
# Skip stubs
case "$name" in
ai-context.md|context-guard.md) continue ;;
esac
cp "$cmd" "$d/prompts/$name"
+ copied=$((copied + 1))
done
- log "Copied 14 command prompts to prompts/"
+ log "Copied ${copied} command prompts to prompts/"Apply the same dynamic-count pattern in build_gemini and the copy_skills calls.
Also applies to: 160-168
🤖 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 `@scripts/build-dist.sh` around lines 117 - 126, The hard-coded counts in
build-dist.sh are stale; update the copy loops to compute the actual number of
items and use that in the log messages instead of literal numbers. Specifically,
in the commands copy loop that iterates over "$COMMANDS_DIR"/*.md (and the
corresponding TOML creation step), track a counter (or collect filenames into an
array) and log the computed count (e.g., number of copied prompts and number of
generated TOML files) rather than "Copied 14..."/ "Created 14..."; make the same
change for the skills copy section (replace "Copied 15 skills" with a
dynamically computed count) and apply the dynamic-count pattern in any related
functions or invocations such as build_gemini and copy_skills so all summary log
lines reflect real counts.
| # Check for AGENTS.md (Codex/OpenCode) vs CLAUDE.md (Claude Code/OpenCode) | ||
| [ -f "$PROJECT_DIR/AGENTS.md" ] && echo "codex" && return |
There was a problem hiding this comment.
AGENTS.md is too generic to identify Codex specifically.
AGENTS.md is the cross-tool AI context spec used by Codex, Cursor 2.6+, Antigravity, OpenCode, Claude Code, and others — your own README and CLAUDE.md describe this. Falling through to echo "codex" whenever the project just has an AGENTS.md will mis-route many users (e.g., a Cursor user who has only AGENTS.md will get the Codex install). Either drop this fallback or pair it with a Codex-specific signal (e.g., ~/.codex/ or a .codex workspace marker), and prefer asking the user to specify <platform> explicitly when ambiguous.
🤖 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 `@scripts/setup.sh` around lines 74 - 75, The script currently treats presence
of AGENTS.md alone as a definitive signal for Codex by running the "[ -f
\"$PROJECT_DIR/AGENTS.md\" ] && echo \"codex\" && return" branch, which is too
generic; change this to only auto-select Codex when a Codex-specific marker
exists (e.g., check for a Codex workspace marker like ".codex" or a codex config
dir such as "~/.codex") or, if only AGENTS.md is present without CLAUDE.md or
any codex marker, do not auto-evaluate to codex—either fall through to prompt
the user for the platform or print a message asking them to run the script with
an explicit <platform> argument; update the branch that currently references
AGENTS.md and the echo "codex" && return behavior accordingly (remove or guard
the fallback) and ensure CLAUDE.md detection remains unchanged.
| "agent-skills": { | ||
| "version": "1.0", | ||
| "url": "https://agentskills.io/specification", | ||
| "repo": "agentskills/agentskills", | ||
| "check_url": "https://api.github.com/repos/agentskills/agentskills/releases/latest", | ||
| "last_verified": "2026-05-06", | ||
| "stability": "evolving — newly ratified", | ||
| "notes": "Cross-tool skill spec (name, description, license, compatibility, metadata, allowed-tools). Adopted by Claude Code, Codex CLI (.agents/skills/), Gemini CLI, Cursor, and others." | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What is the current published version of the Agent Skills open standard at agentskills.io?
💡 Result:
The Agent Skills open standard at agentskills.io does not publish a single standalone “current version” number on the official specification page; the specification is provided as the canonical format at https://agentskills.io/specification and there is no visible version field on that page indicating a standard version release.[1] If you mean the repository/standard’s latest published code/docs state, the official Agent Skills repository (agentskills/agentskills) shows it was last pushed on 2026-04-22 (default branch: main), which represents the current state of the published standard content.[2]
Citations:
Remove or correct the unpublished version field in the agent-skills entry.
The upstream specification at https://agentskills.io/specification does not publish a "version 1.0" identifier. The specification page has no visible version field, and the official GitHub repository does not release numbered versions. Pinning "version": "1.0" violates the requirement to verify upstream spec versions before adding them to this file. Either remove the version field, use a commit/date-based reference from the GitHub repository (last updated 2026-04-22), or find documented evidence of a published version number from the upstream source.
🤖 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 `@upstream-versions.json` around lines 64 - 72, The "agent-skills" entry
contains an unsupported published version string; remove or replace the
"version": "1.0" field in the agent-skills object and instead either delete the
version property entirely or set it to a verifiable commit/date reference (e.g.,
use the GitHub commit hash or the last-updated date "2026-04-22") so that the
entry only contains verifiable upstream provenance; update the entry that
references "agent-skills" and ensure related fields like "last_verified" remain
accurate.
…tion
The v2.3.0 collision migration deleted commands/{changelog,roadmap,
visual-standards,docs-verify,doc-refresh,llms-txt}.md based on the assumption
that skills with the same name would expose as /pitchdocs:<name> slash
commands. The 2026-05-08 activation eval run (62.5%) revealed that
assumption was wrong: plugin slash commands resolve from commands/, NOT
from .claude/skills/. Skill content augments context but does not register
plugin slash commands.
Fix: re-create the 6 deleted files as thin pointers (~15 lines each):
- description, argument-hint, allowed-tools restored from pre-v2.3.0
- 2-3 line body delegates to the matching skill's ## Invocation section
- No knowledge duplication — that lives in the skill body
The skills retain the ## Invocation content added in v2.3.0 (single source
of truth for procedural knowledge); the command files exist purely to
register the slash interface in plugin contexts.
Counts updated across canonical and bridge files (10 → 16 commands):
CLAUDE.md, ROADMAP.md, SKILL.md, GEMINI.md, .cursorrules, .clinerules,
.windsurfrules, .github/copilot-instructions.md, llms.txt, tests/RESULTS.md,
docs/guides/other-ai-tools.md, pitchdocs.json (+6 entries), CHANGELOG.md
("Changed" bullet rewritten to reflect the actual approach).
Closes the v2.3.0 release-blocker regression. Re-running activation evals
should bring pass rate back from 62.5% to ≥80%.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 participant
Summary
PitchDocs v2.3.0 — first ecosystem-aligned release after the Claude Code skill/command merge, the Agent Skills standard ratification, and a wave of upstream best-practice updates.
This PR contains 3 commits:
feat: cross-platform distribution build pipeline— checks in the previously-uncommittedscripts/build-dist.sh,scripts/setup.sh,dist/(8 platforms),pitchdocs.jsonmanifest, portableagents/docs-writer-flat.md, and aligned doc updates.feat: v2.3.0 ecosystem refresh— the substantive v2.3.0 development work (collision migration, Agent Skills branding, content refresh).chore(release): v2.3.0 prep— version bumps, CHANGELOG promotion, ROADMAP update, FAQ rename, llms-full regen.Highlights
Added
.agents/skills/, Geminiskills/, Cursor.cursor/, Cline, Windsurf, Goose, Aider, OpenCode)paths:frontmatter ondocs-awarenessrule for path-scoped activationdocs-writer-flatagent for non-Claude Code platformspitchdocs.jsonmanifestChanged
changelog,roadmap,visual-standards,docs-verify,doc-refresh,llms-txtmigrated from duplicate command files into skill## Invocationsections (skills now take precedence per Claude Code's command/skill merge)docs/faq/index.md→docs/faq/faq.mdfor cleaner marketing-site URL/help/pitchdocs/faq/(closes docs(faq): rename docs/faq/index.md → docs/faq/faq.md for cleaner site URL #49)scripts/build-dist.sh— version now read fromplugin.json; release-please bumps cascade automaticallyDocumentation
package-registryskill — npm CLI ≥ 11.5.1, Node ≥ 22.14.0; PyPI PEP 740 attestations now defaultpitchdocs-suite/SKILL-templates.md— Issue Formsattachments, Issue Fields preview, Django CC 3.0 adoption, FUNDING.yml expandedvisual-standards— Mermaid Wardley Maps + "neo look"docs/guides/other-ai-tools.md— Cursor 2.6+, Antigravity 1.20+, Gemini CLI v0.25+llms-full.txt— fully regenerated (94 files), removing staleskill-authoringreferencesInternal
upstream-versions.json— refreshed alllast_verifieddates to 2026-05-06; newagent-skillsv1.0 sourcerelease-please-config.json— addedpitchdocs.jsontoextra-filesfor forward-compat.cursorrules,.clinerules,.windsurfrules,.github/copilot-instructions.md,GEMINI.md)Closes
Test plan
bash scripts/build-dist.sh --check—dist/in syncpython3 tests/validate-frontmatter.py— all valid (15 skills, 10 commands, 5 agents)bash tests/validate-llms-txt.sh— 0 errors/plugin install pitchdocs@lba-pluginsin a fresh clone, verify the 6 user-invocable skills (/changelog,/roadmap,/visual-standards,/docs-verify,/doc-refresh,/llms-txt) resolve correctlydocs/faq/faq.mdand the new/help/pitchdocs/faq/URL goes live (separate site-side 301 redirect tracked outside this PR)🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Chores