Instructions for coding agents

Identify the application

Read the workspace's local instructions first. Inspect its package manifest, lockfile, and source to determine whether it already contains a Beignet app. In a monorepo, find the intended app directory and run app commands there.

Existing Beignet app: read its AGENTS.md or CLAUDE.md and README.md. Preserve application customizations and follow its package manager.
New app: follow the quickstart. Check Node.js 22.12 or newer and the selected package manager. Use the full-stack Next.js starter with SQLite unless the developer requests other choices. Read the generated guide files before editing, prepare the local environment, and follow the starter's migration and run instructions.
Existing app without Beignet: establish where Beignet should be added. Use packages and imports for integration choices; do not scaffold a new app over existing source.

Choose the right guidance

Inspect the installed Beignet package versions, including @beignet/core and @beignet/cli. Use the guidance shipped with those packages and the app's own instructions. Agent tools explains how to load the package skills for a task.

The documentation manifest identifies the website's framework version, source revision, and Markdown pages. Each Markdown page includes the same version information in its frontmatter.

Compare frameworkVersion in the manifest, or framework_version in a page, with the installed packages. These web docs describe the current checkout; they are not an archive of released versions. Even matching version numbers can include unreleased changes. Use the installed package's skills, README, exports, and changelog to resolve differences. Do not upgrade the application just to match a website example.

Fetch the documentation index, then only the pages relevant to the task. Use Guides to find instructions by the result you need. Start with Mental model for unfamiliar terminology and App architecture for file responsibilities. The full text export is optional; most tasks need a few focused pages.

Inspect before changing code

From a default Bun starter, inspect the app and focus on the existing feature:

bash

bun beignet map --json
bun beignet explain feature todos --json

Replace todos with the feature you are changing and use the app's package manager. Read the reported source files and related tests. A source map helps you find dependencies; it does not prove the feature is wired correctly at runtime or that a change is safe.

Scaffold and implement the behavior

Use the CLI generators that fit the requested change. Adapt the schemas, use cases, authorization rules, and tests to the developer's actual requirements. Follow the generator's next steps for database migrations and other setup. Keep contracts, use cases, ports, and adapters in their documented locations, or the paths selected in the app's Beignet configuration.

For a first feature, follow the Projects tutorial through API, ownership, and UI. Complete the ownership chapter before making the feature available to users.

Verify and report

In the default starter, run the formatter and validation command after the final edits:

bash

bun run format
bun beignet check --json

check runs architecture linting, strict doctor checks, and the app's lint, typecheck, and test scripts. It reports missing scripts as skipped. Inside Git, a source change during validation makes the result stale and unsuccessful; finish the edits and rerun the checks.

Inspect failures and fix their causes. Add tests for new behavior, including validation and authorization where relevant. Exercise changed user flows in the browser or over HTTP, and run the app's build when deployment behavior is affected. Passing checks only covers what those checks exercise.

Report the changed behavior, checks run, failures or skipped checks, and the steps the developer can use to try the result. For a new app, include the local URL and how to start the development server.