Skip to content

chore: Update the coding-agent setup and contributor docs - #9287

Merged
Jason3S merged 2 commits into
mainfrom
chore/agent-setup-docs
Sep 27, 2026
Merged

Jason3S merged 2 commits into
mainfrom
chore/agent-setup-docs

Conversation

@Jason3S

@Jason3S Jason3S commented Sep 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Moves the knowledge contributors need out of AGENTS.md into docs for people under docs/, rewrites the out-of-date CONTRIBUTING.md, and updates the Claude Code skills to follow those docs. Agent files shrink to commands, the "Do not" rules, and one-line rules that link to the docs.

Docs for maintainers and contributors (docs/)

  • build-and-packaging.md: layout, tooling, commands, every generated file and what regenerates it, the "if you change X, also do Y" table, bundled dictionaries, adding a package, and CI.
  • config-and-cli.md: how to add or change a config option or a CLI flag, traced from past PRs. It covers the three registries the build enforces, the _merge step it doesn't, and the Build Docs workflow that doesn't run on its own for CLI changes.
  • releasing.md: release-drafter, the title and label table from chore: Release notes: exclude internal refactors, publish all breaking changes, strip tool attribution #9280 and chore: Release notes: leave out docs and website changes #9288, the Prepare Release flow, prerelease mode, and how to fix an entry after merge.
  • design-principles.md and glossary.md.
  • ADRs/: the ADR process and templates, and how ADRs relate to rfc/. Features are finalized before merge and archived about three months after shipping.

CONTRIBUTING.md

  • Fixes the Node.js version (it said 18; engines requires >=22.18.0).
  • PR titles and descriptions are written for the people who read the release notes: users of the CLI, its config, and its packages. It says which types are published, and that PR bodies carry no tool attribution.
  • docs: is for README files and the repo's docs, and website: for site content. Neither is published.
  • Comments: public API doc comments are user documentation, as are config option doc comments.
  • Invisible characters, writing for users, and the repo's own spelling word lists.
  • Links: Coveralls, Codecov, and the three packages other projects use most.

Agent setup

  • AGENTS.md stays the source, and CLAUDE.md still imports it. The six "Do not" rules stay in full. Where a rule depends on a list that changes, it links to the list in docs/.
  • New workflow rule: use workflow_dispatch when possible. Add workflow_call only to a new workflow without a concurrency section.
  • feature-adr is rewritten to run docs/ADRs/ as an interview. The worktree path now matches .gitignore, and links go to a feature's README.
  • New skills: release-notes (fix a merged PR's entry, or audit the Prepare Release PR), config-option, and cli-option.

Website

  • Replaces five no-break spaces in the GitHub Action example in website/docs/installation.md. A copied workflow file failed to parse.

Describes the release rules from #9288, so merge it after #9288. Follow-ups are tracked in #9282.

- Add docs/ for maintainers: build and packaging, config options and CLI flags, releasing, design principles, glossary, and the ADR process.
- Rewrite CONTRIBUTING.md: PR titles and bodies for release note readers, comments, invisible characters, writing for users.
- Shrink AGENTS.md to commands, the "Do not" rules, and one-line rules that link to the docs.
- Rewrite the feature-adr skill to run docs/ADRs as an interview; add release-notes, config-option, and cli-option skills.
- Replace no-break spaces in the GitHub Action example in website/docs/installation.md.
…ebsite prefixes

- Fix the malformed code spans in docs/releasing.md "Prerelease mode".
- skipLibCheck: prefer false; tsconfig.esm.json sets true because third-party types broke builds.
- Describe the rules from #9288: `docs:` and `website:` are not published, labels come from the title only,
  and reverts are published only for `feat` and `fix`.
- ADR design PRs are `docs:`.
- cli-option and config-option: filter while iterating, then build everything and update all snapshots.
@Jason3S
Jason3S merged commit 49da8eb into main Sep 27, 2026
15 checks passed
@Jason3S
Jason3S deleted the chore/agent-setup-docs branch September 27, 2026 08:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant