Developer

LLM authoring guide

This workflow lets a coding agent build a valid BRT website extension without guessing at platform behavior.

Hosted context

Give a web-capable coding agent https://developers.battlereadytech.com/llms-full.txt. It is generated from the same versioned Markdown, JSON schemas, contract, and TypeScript declarations shown in the developer portal.

If the agent cannot use the web, download the developer kit or attach BRT_EXTENSION_CONTEXT.md from a new scaffold.

Give the agent authoritative context

New projects already contain BRT_EXTENSION_CONTEXT.md. For an existing project or when the contract has changed, generate a fresh context file from the downloaded developer kit:

node tools/web-extensions/brt-extension.mjs context \
  --out ./brt-extension-context.md

Attach that file to the LLM conversation. Also give the agent the extension project directory and a short feature brief containing:

  • the visible user outcome;
  • the publisher and package namespace;
  • the data the interface must show;
  • the actions a visitor may take;
  • required visual controls;
  • accessibility and browser targets.

Do not provide publisher private keys to an LLM service. A human or protected CI job should perform release signing.

Recommended prompt

Build a BRT website extension from the attached BRT extension context.

Follow the manifest and runtime contracts exactly. Do not invent capabilities,
actions, fields, network access, or browser privileges. Request the fewest
capabilities required for the visible behavior. Keep all runtime dependencies
inside runtime/. Use safe DOM APIs for every external string. Include useful
loading, empty, denied-permission, and failure states. Make the interface
responsive and keyboard accessible.

Run the BRT extension check command and fix every error. Do not sign the
release and do not request or handle a private publisher key. Return the final
file tree, declared capabilities with a reason for each, tests performed, and
any platform limitation that prevented part of the request.

Required agent process

  1. Read AGENTS.md in the scaffolded project.
  2. Read the manifest schema and runtime API before writing code.
  3. Map each requested feature to a documented named API method.
  4. Remove any feature that needs an undocumented capability. Report the gap.
  5. Declare only the capabilities used by code.
  6. Build with local HTML, CSS, JavaScript modules, images, and fonts.
  7. Render untrusted strings with textContent or equivalent safe APIs.
  8. Add loading, empty, missing-permission, unavailable-adapter, and generic failure states.
  9. Run check --json until it exits successfully.
  10. Run local preview at narrow and wide viewport sizes.
  11. Leave signing to a human or protected CI process.
  12. Package the finished project only after a human reviews the source and validation output.

Hard constraints for agents

  • Do not use fetch, XMLHttpRequest, WebSocket, EventSource, beacons, or remote imports.
  • Do not use cookies, local storage, session storage, IndexedDB, service workers, workers, or application tokens.
  • Do not read window.parent, window.top, window.opener, or the parent DOM.
  • Do not use inline scripts, inline event handlers, eval, or generated executable code.
  • Do not place JSON, Markdown, source maps, tests, or package-manager files in runtime/.
  • Do not add secrets or customer information to the manifest or settings.
  • Do not claim that a declared capability is granted.
  • Do not change the namespace after the first release.
  • Do not edit generated submission files.

Agent completion report

Require the agent to return:

Project path:
Namespace and version:
Visible behavior:
Capabilities requested:
- capability: reason it is necessary
Properties exposed:
Failure states implemented:
Accessibility checks:
BRT check command and exit status:
Manual preview sizes tested:
Known limitations:
Signing performed: no

Reject an agent result that omits command output, invents an API, requests a private key, or says a validation error can be ignored.

Human approval boundary

An LLM can scaffold, implement, test, preview, and prepare a release. It must not receive the publisher private key. A developer or protected CI job signs the reviewed source, verifies the five release files, and uploads them. BRT validation and operator approval remain required after that upload.