Skip to content

AGENTS.md

Latest commit

 

History

History
68 lines (64 loc) · 3.81 KB

AGENTS.md

File metadata and controls

68 lines (64 loc) · 3.81 KB

AGENTS.md

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: just lint (cspell + markdownlint on docs/pages/**/*.mdx)
  • Devcontainer: .devcontainer/devcontainer.json (pre-installs pnpm/Node/tools)

Content Structure

  • New/expanded pages: Copy docs/pages/config/template.mdx
  • 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: []
- Sidebar: Update `vocs.config.tsx` 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, mermaid, printables, certs

## Conventions Agents Miss
- Explain: Non-technical first → technical depth
- Language: Direct/technical, no 1st person ("implement X" not "I suggest")
- Playbooks/templates: Top `> 🔑 **Key Takeaway**:` (<40 words summary)
- Sections: Practical guidance (steps/checklist), Why important (incidents), Pitfalls/examples, Cheat sheet, Further reading
- Tech details: Balanced (detailed for AWS/Cloudflare/etc., generic timeless principles)
- Links: Descriptive; Resources section; relative internal paths
- Frontmatter precision: title: "Page | Security Alliance" (&lt;60 chars or "| SEAL"), description: 140-160 chars (action verbs/keywords like tool names/attacks/standards), contributors: add github username under the appropriate role (wrote|reviewed|fact-checked). First-time contributors must also register a profile in `docs/pages/config/contributors.json` (see "Contributors database" below).
- Contributors database: first-time contributors must register a profile in `docs/pages/config/contributors.json` keyed by GitHub username. Structure:

"": { "slug": "", "name": "", "avatar": "https://avatars.githubusercontent.com/", "github": "https://github.com/", "twitter": null, "website": null, "company": null, "role": "contributor", "job_title": null, "description": null, "badges": [] }

Leave `badges: []` and `role: "contributor"` when self-registering as badges and specific roles are assigned by maintainers.
- Style: American English; objective/explanatory tone (no simplifications); introduce acronyms; future-proof; no full-AI content (grammar ok); mermaid; images via PR comments → S3 (/img-bot)
- New pages: MUST update vocs.config.tsx sidebar items (dev: true for WIP)
- WIP pages: Add stub notice &gt; ⚠️ Stub/in progress, help contribute/expand

## Commits/PRs
- Sign: `git commit -S`; amend unsigned via rebase/edit/amend-S/continue; force-push
- Pre-PR: Build + preview locally; update contributors.json if new
- CI enforces: Spellcheck comments PRs, mdlint, preview deploys, vocs-config reminders
- Unsigned commits fix: git rebase -i HEAD~N; pick→edit; git commit --amend -S --no-edit &amp;&amp; git rebase --continue (repeat); git push --force; verify git log --show-signature