Skip to content

AGENTS.md

Latest commit

 

History

History
113 lines (94 loc) · 6 KB

AGENTS.md

File metadata and controls

113 lines (94 loc) · 6 KB
Raw

AGENTS.md

Note for agents. This file describes how to contribute to this repository. For agents retrieving SEAL Frameworks content to answer user questions (not editing the repo), see SKILL.md instead.

Workflow

  • Before contributing, see CODE_OF_CONDUCT.md. For SEAL Certifications, also see docs/pages/certs/contributions.mdx. To take ownership of a framework, see docs/pages/contribute/stewards.
  • PRs target develop branch.
  • Setup: pnpm install
  • Dev server: pnpm exec just serve (generators + Vocs on :5173)
  • Build/verify: pnpm run docs:build then pnpm run docs:preview (preview available on :4173)
  • Lint: pnpm exec just lint (cspell + markdownlint on docs/pages/**/*.mdx)
  • Content structure checks: pnpm run validate:content (optional --path docs/pages/<framework>, --strict)
  • Devcontainer: .devcontainer/devcontainer.json (pre-installs pnpm/Node/tools)

Authoritative content standards

Do not improvise structure or terminology. Follow this ownership map:

Concern Source
Page types, required sections, overview maps, exceptions docs/pages/contribute/content-model.mdx
Voice, modality (must/should/may), terminology docs/pages/contribute/style-and-terminology.mdx
Executable page skeleton docs/pages/config/template.mdx
Human workflow, sidebar, images, signed commits docs/pages/contribute/contributing.mdx
Framework normalization PR checklist docs/pages/contribute/docs-normalization-checklist.mdx
Retrieval-only behavior SKILL.md

Canonical framework overview example: docs/pages/supply-chain/overview.mdx.

Content Structure

  • New/expanded pages: Copy docs/pages/config/template.mdx and apply the content model for the page type

  • Frontmatter required:

    title: "Page Title | Security Alliance"
description: "140-160 chars, keywords/action verbs"
tags:
  - Engineer/Developer
  - Security Specialist
  - Operations & Strategy
contributors:
  - role: wrote
    users: [username]
  - role: reviewed
    users: []
  - role: fact-checked
    users: []

  • Attribution roles are not interchangeable: wrote is for a new page, a new section, or a substantial rewrite; fact-checked is for changes that correct, qualify, or source a specific claim, never a fallback list for edits too small to be authorship; reviewed is a reviewer's sign-off on the whole page and is never self-assigned on your own PR. Never remove or reorder existing contributors. See docs/pages/contribute/contributing.mdx "Attribution and contributor roles"

  • Sidebar: Update vocs.config.ts items; dev: true for WIP (hides on main site)

  • Never edit: index.mdx files are auto-generated by the build command (do not create or edit manually)

  • Images: do not commit images to the repo. In the PR description (or a PR comment), attach the images and flag that they need uploading. A maintainer or a steward will trigger the /img-bot workflow, which uploads to S3 and posts the resulting links back as a PR comment. Then, use those links in the PR content.

  • Generators run on build: tags, indexes, printables, certs (postbuild: sitemap, llms, searchbar index).

Conventions Agents Miss

  • Explain: non-technical first, then technical depth
  • Language: direct/technical, no first person (implement X not I suggest)
  • Headings: sentence case required (## Signing verification, not Title Case). Applies to all H2/H3 including catalog labels: ## Further reading, ## Related frameworks, ## What this framework covers (or ## What this section covers on a nested subsection overview) — never ## Further Reading & Tools or Title Case reserved names. See docs/pages/contribute/style-and-terminology.mdx
  • Key Takeaway (canonical): > 🔑 **Key Takeaway**: under ~40 words; the point of the page, not a TOC summary
  • Use <Checklist> for interactive checklists; never plain - [ ] task lists outside examples
  • Failure modes: anchor next to the related recommendation (do not invent a generic "Pitfalls" dump by default)
  • Links: descriptive text; ## Further reading / ## Resources; relative internal paths
  • Frontmatter precision: title under 60 chars or use | SEAL; description 140–160 chars; contributors use GitHub usernames. First-time contributors register in docs/pages/config/contributors.json
  • Contributors database shape:
"<github-username>": {
  "slug": "<github-username>",
  "name": "<Full Name>",
  "avatar": "https://avatars.githubusercontent.com/<github-username>",
  "github": "https://github.com/<github-username>",
  "twitter": null,
  "website": null,
  "company": null,
  "role": "contributor",
  "job_title": null,
  "description": null,
  "badges": []
}

Leave badges: [] and role: "contributor" when self-registering; maintainers assign badges and specific roles.

  • Style: American English; objective tone; introduce acronyms; future-proof; no full-AI content (grammar help OK); Mermaid allowed; images via PR comments then S3 (/img-bot)
  • New pages: MUST update vocs.config.ts sidebar items (dev: true for WIP)
  • WIP pages: stub notice per contributing guide
  • Framework normalization: one framework per PR targeting develop; do not open a repo-wide rewrite PR

Commits/PRs

  • Sign: git commit -S; amend unsigned via rebase/edit/amend-S/continue; force-push only when rewriting your branch
  • Pre-PR: build + preview locally; update contributors.json if new; run validate:content on touched framework paths
  • CI enforces: spellcheck comments on PRs, markdownlint, preview deploys, vocs-config reminders
  • Unsigned commits fix: git rebase -i HEAD~N; pick→edit; git commit --amend -S --no-edit && git rebase --continue (repeat); git push --force; verify git log --show-signature