docs: consolidate voice/writing-style guidance into the brand MCP (rebase of #19777) - #20664
Draft
CamSoper wants to merge 5 commits into
Draft
docs: consolidate voice/writing-style guidance into the brand MCP (rebase of #19777)#20664CamSoper wants to merge 5 commits into
CamSoper wants to merge 5 commits into
Conversation
Make the Pulumi brand guide (served by the public pulumi-brand MCP server) the source of truth for voice and writing-style, and have the docs STYLE-GUIDE and content skills consult it instead of restating it. - STYLE-GUIDE.md: trim to Hugo/repo mechanics + a pointer to the brand guide's voice/writing-style sections; add a precedence rule (the brand guide wins on any overlap, including social/SEO/AEO). - AGENTS.md: point content rules at the brand guide; standardize headings on sentence case at every level; precedence rule. - glow-up: require the pulumi-brand MCP (fail loud if unreachable) and defer voice/prose/terminology to it. - prose-patterns: source-of-truth note pointing at brand writing-style. - new-doc / new-blog-post: suggest sentence-case titles; point at the guide. - .vale.ini: put punctuation outside quotes; note the sentence-case standard. - claude-code-review.yml / content-review-article.yml: wire the public brand MCP (mcp_config + get_guidelines/search_guidelines) so CI review can consult voice/writing-style. SEO and social guidance intentionally stay in this repo's skills for now. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
… input) The pinned anthropics/claude-code-action@v1 rejects a top-level mcp_config input (logged 'Unexpected input(s) mcp_config' and ignored it). v1 expects custom MCP servers in claude_args via --mcp-config; the config merges with the action's built-in GitHub MCP server. Move the pulumi-brand HTTP server there and keep its tools in --allowed-tools. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The 'Upload Claude execution log' step pointed at a hardcoded temp path (/home/runner/work/_temp/claude-execution-output.json) that claude-code-action@v1 no longer writes, so with if-no-files-found:ignore it silently uploaded nothing — losing per-tool spend telemetry and any visibility into MCP usage. Point it at the action's `execution_file` output instead. The stream-JSON log's system/init message lists mcp_servers + connection status, which also lets us confirm the brand MCP connects. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The execution_file output renders empty under the pinned claude-code-action@v1, and an empty upload-artifact path fails the step. Restore the original harmless no-op path; execution-log observability is a separate follow-up. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Fallout from rebasing onto master: Pulumi.HeadingSentenceCase and its .vale.ini entry both described Title Case H1 as the convention, which now contradicts AGENTS.md and STYLE-GUIDE.md. Restate the comments as what the scoping actually is — sentence case is the standard at every level; the rule stays scoped to H2+ so it doesn't flag the backlog of Title Case front-matter titles. No rule behavior changes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015KpCy5B47c2oNqEeX1Znwx
Collaborator
|
Your site preview for commit 91ff9d5 is ready! 🎉 http://www-testing-pulumi-docs-origin-pr-20664-91ff9d5b.s3-website.us-west-2.amazonaws.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
4 participants
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.
Proposed changes
Rebase of #19777 onto current
master, with the merge conflicts resolved. #19777's branch was based onfc0063b9(~900 commits back) and had gonedirty; this branch replays its four commits on top ofmasterand adds one follow-up commit for consistency fallout.Same intent as #19777: make the Pulumi brand guide (public
pulumi-brandMCP server athttps://brand.pulumi.com/mcp) the source of truth for voice and writing style, haveSTYLE-GUIDE.mdand the content skills consult it rather than restate it, and add a precedence rule (brand guide wins on overlap).Conflicted files and how each was resolved
.vale.iniGoogle.Headingsrationale (it now describesPulumi.HeadingSentenceCase, which didn't exist when #19777 was written); added #19777's brand source-of-truth comment and the newGoogle.Quotes = NO..github/workflows/claude-code-review.ymlallowed_bots(now includesworkprentice) and its model flags (--model claude-opus-5 --effort low, not the branch'sclaude-opus-4-8); took the branch'sclaude_args --mcp-configblock-scalar form and its MCP tools in--allowed-tools..github/workflows/content-review-article.ymlclaude_argsmodel flags,applied[]verdict-schema prompt text, and broad-Bash rationale comment; the branch's--mcp-configwiring and MCP tools.STYLE-GUIDE.mdTwo substantive divergences from master that need a call — please confirm before this goes ready
These are the points where master moved in the opposite direction from #19777 after the branch was cut. I resolved both toward #19777's intent, since that's what the PR is for, but they're the author's decision, not mine:
STYLE-GUIDE.mdgrew a "Brand guidelines" section putting this guide first ("When this guide and the brand guidelines diverge, this guide wins here"). docs: consolidate voice/writing-style guidance into the brand MCP #19777 reverses that — brand guide wins. Master's section is dropped here.AGENTS.mdhunk auto-merged to docs: consolidate voice/writing-style guidance into the brand MCP #19777's wording, so leaving master's note inSTYLE-GUIDE.mdwould have made the two files contradict each other — the note is dropped.styles/Pulumi/HeadingSentenceCase.ymlstill scopes enforcement to H2+; only its comment (and the matching.vale.inicomment) changed, so no existing Title Case H1 starts getting flagged. Migrating H1s is a separate decision.Verification
make lint— clean (1839 files parsed, 0 errors; Prettier clean)mcp_configinput remains (docs: consolidate voice/writing-style guidance into the brand MCP #19777's commit 3 moved it intoclaude_args)path, which is preservedUnreleased product version (optional)
N/A
Related issues (optional)
Supersedes #19777 — that PR can be closed if this one is taken, or these commits force-pushed onto its branch instead.
🤖 Generated with Claude Code
https://claude.ai/code/session_015KpCy5B47c2oNqEeX1Znwx
Generated by Claude Code