Skip to content

AGENTS.md

Latest commit

 

History

History
44 lines (33 loc) · 7.61 KB

AGENTS.md

File metadata and controls

44 lines (33 loc) · 7.61 KB
Raw

Agent collaboration conventions — Overture Docs

For AI agents: this file is instructions you read and follow, not documentation written for people. If you're a person, see README.md instead.

Adapted from softeng/agentics. This is the canonical, agent-neutral source for Overture Docs-specific conventions; CLAUDE.md is a stub that points here.

Universal conventions (interaction style, critical constraints, testing, code style, security, documentation, session discipline), the developer role, the softeng team layer, and the Overture product-family layer (CLAUDE.overture.md, applied because project memory flags this as an Overture repo) are not duplicated here: they come from the developer's agentics-based global context and the local clone at ~/.claude/agentics/template/. Any agent working in this repo reads those on demand; this file adds only what is specific to Overture Docs.

Session start

Before touching content, read .dev/roadmap.md, .dev/tech-debt.md, and the most recent file(s) in .dev/sessions/. Full session-start sequence: ~/.claude/agentics/template/conventions/session-discipline.md.

When to read what (agentics conventions — read on demand)

The canonical task→convention dispatch table lives in ~/.claude/agentics/template/AGENTS.md § "When to read what": tests, code style, code review, docs, security, convention levels, upgrading adoption. Read the matching file from ~/.claude/agentics/template/conventions/ when doing that task. Most work here is documentation, so conventions/documentation.md applies to the majority of changes.

Project context

Overture Docs is the centralized documentation site for the Overture stack, built with Docusaurus. It aggregates Markdown from the /docs directory of each Overture project repository (pulled in as git submodules) and renders them as one navigable site. The point of the setup is that documentation stays with its source project while readers get a single hub. Full overview in README.md; planned work lives in .dev/roadmap.md.

Verifying a UI change

A clean npm run build says a page compiled, not that it looks right. Before calling any visual change done, render it and look at it.

  • Build and serve: cd website && npm run build && npm run serve --port <port>. npm start renders in the browser, so its HTML is an empty shell and tells you nothing.
  • Screenshot with a real browser at a real viewport. Chrome's --headless --screenshot --window-size is unreliable: the window size is not the CSS viewport, and it will show you clipping and overflow that do not exist. Drive it with puppeteer-core and page.setViewport instead, pointing executablePath at the installed Chrome. Install it outside this repo (the scratchpad), never as a dependency here.
  • Check the widths that change behaviour, not just the one you are working at. The marketing navbar collapses at 1160px.
  • When something looks wrong, measure it in the page (getComputedStyle, getBoundingClientRect, scrollWidth against clientWidth) before changing CSS. Reading a screenshot is guessing.
  • Check a documentation page too whenever marketing styles or theme components change: the two sites are separate builds but one codebase, and src/theme/ and the emitted stylesheet are shared by both. npm run build and npm run build:marketing both have to pass.

Project-specific constraints

  • Public repository (overture-stack/docs): no credentials, secrets, tokens, or private URLs in any committed file, ever.
  • Documentation content is owned by the submodules, not this repo. Each project's docs live in submodules/<project>/docs/ and are symlinked into website/docs/. Edit the source file under submodules/<project>/, never the symlinked copy under website/docs/: editing through the link mutates the vendored submodule's working tree in a way that is easy to lose and confusing to review. Symlinks are (re)generated by symlinker.sh.
  • Submodules are separate Overture repos with their own conventions. Defer to any in-tree AGENTS.md/CLAUDE.md inside a submodule; do not apply this repo's root conventions on top of vendored component code. Changes to a submodule's actual content belong in that submodule's own repo and PR flow, not here.
  • Only site scaffolding and aggregation live in this repo: the Docusaurus config, theme, components, and the symlink/build wiring under website/. That is what a change to this repo (as opposed to a submodule) should normally touch.

Repository orientation

  • submodules/ — vendored Overture repos as git submodules: arranger, lectern, lyric, maestro, score, song, stage, and .github. Each carries its own /docs. Defined in .gitmodules (see .dev/roadmap.md: release-branch tracking is not yet configured, so git submodule update --remote currently follows each repo's default branch).
  • website/ — the Docusaurus site: docs/ (aggregated, symlinked from submodules), community/, guides/, and src/ (components/, css/, marketing/, theme/, pages/).
  • website/src/marketing/: everything the overture.bio site is made of: its routes under pages/ (whose index.tsx is the home page at /), plus components, constants, case-study data, and the Sass tree. Its styles are all imported inside .marketing by styles/index.scss, and only MarketingPage.tsx imports that file, which is what kept those bare class names and element rules off the documentation pages while one build served both. The builds are separate now, so this is belt and braces, but the scoping stays: src/theme/ is still shared. Add marketing styles as a partial imported there, never as a stray import "./styles.scss" in a component.
  • symlinker.sh — regenerates the symlinks that bring selected submodule /docs files into website/docs/.
  • Two sites, two builds, one branch. docusaurus.config.ts reads OVERTURE_SITE: unset it builds docs.overture.bio (npm run build), marketing builds overture.bio (npm run build:marketing). The marketing build drops the documentation plugin instances and the redirect table, and points the pages plugin at src/marketing/pages/. Both builds keep Algolia: MarketingNavbar renders the same @theme/SearchBar, and the marketing build adds externalUrlRegex so results navigate cross-host to docs.overture.bio instead of 404ing. Components ask which build they are in through useIsMarketingSite, never by inspecting the route.
  • website/static-docs/ and website/static-marketing/ — what each host owns alone: robots.txt for both, and the _redirects file each one publishes. website/static/ is still shared. There is deliberately no netlify.toml: one file on one branch cannot say different things to two Netlify sites, and docs.overture.bio is configured through the Netlify UI. Redirects belong in the _redirects file of the host that owes them.
  • website-legacy/ is gone as of 2026-08-07. It was a staged copy of the overture-stack/website Gatsby site, kept while the port ran. Everything it held is either ported into website/ or still in that repo, which serves overture.bio until DNS is cut over to the marketing build here, and is cloned locally at ~/Desktop/website. Until that cutover, a change that has to reach the live overture.bio goes there, not here.
  • README.md, preview.png — human-facing project overview and screenshot.
  • Local setup: Node 18+, npm ci, then npm start (see README.md § Getting Started).