Work with AI coding agents

BitaKit is built so that a person and a coding agent find the same answer to "where does this go?". This guide shows what an agent gets from a BitaKit app and how to brief it.

What the agent readsCopy Anchor Link

Apps created with @bitakit/create-app contain an AGENTS.md (and a CLAUDE.md that imports it, which Claude Code reads) and the bitakit-app-development agent skill. npx @bitakit/cli init adds the same files to an existing Next.js or TanStack Start app. Both need version 0.2.2 or later.

The AGENTS.md block fits on one screen:

• a table that maps each task to its file, from a page to extending a feature you do not own;
• the rules: start small, bind every control to its Action, React only under ui/, and do not rebuild what BitaKit provides;
• the commands to create files and check the result, and a pointer to the skill.

Keep the block as it is and add your own product rules above or below it.

Every plugin folder keeps its own AGENTS.md too: what the plugin owns, the contracts other plugins use, its constraints and how to check it. npx bitakit add plugin starts one from the plugin's actual files, with a CLAUDE.md beside it that only imports it. Keep each guide complete and current with its plugin, and keep plugin details out of the app-wide rules. The sample apps have one for every plugin. Installed packages explain themselves the same way in node_modules/@bitakit/<name>/AGENTS.md.

The skill holds the fuller workflow. Before a change the agent reads the installed packages, runs info and doctor, and checks which layout renders the place it wants to use. It then follows a recipe for the task (pages, Actions, services and events, slots, interceptors, settings, tests), checks the result in the browser and tells you what it built and how it connects. The skill is written to two folders, ready to commit:

A skill folder you edited is never overwritten, so a team can adapt its copy. The skill ships with @bitakit/cli, so it changes when you update BitaKit.

Use the skillCopy Anchor Link

Open the agent in the app folder; Codex looks for skills only from the current folder up. Then name the skill before your request:

$bitakit-app-development Show the number of todos in the app header from a new summary plugin. Do not change the todos plugin.

That is the Codex form; in Claude Code write /bitakit-app-development instead, and in Cursor type / and pick the skill. Agents also load the skill on their own when a request matches it; naming it is the reliable way. The request above works in an app created with --sample; the skill's README lists more requests that build on that sample, one building block at a time.

Update BitaKitCopy Anchor Link

A new skill version reaches the app in two steps: update the packages, then refresh the agent files. Keep every @bitakit/* package on one release line (0.2.x); patch versions may differ within it.

Within the line, update the @bitakit/* packages your package.json lists:

npm update @bitakit/core @bitakit/ui @bitakit/next @bitakit/cli @bitakit/discovery

For a new line, install all of them at it in one command, for example npm install @bitakit/core@0.3 @bitakit/ui@0.3 @bitakit/next@0.3 @bitakit/cli@0.3 @bitakit/discovery@0.3, never the CLI alone. Then, in both cases:

npx bitakit init --update-agent-files
npx bitakit doctor

The first command replaces unedited skill copies and the BitaKit block of AGENTS.md; doctor reports copies that are still out of date or packages on different lines. Start a new agent session afterwards so it loads the new rules and skill. Update BitaKit has the details, and Keep agent files current what happens to each file.

What the agent can runCopy Anchor Link

info --json reads plugin files without starting services or Actions, so it is safe to run at any time. Installed packages such as Shell show declarations: null; npx bitakit slots lists their slots too; --json adds the payload keys of the app's own slots and what the app already puts in each slot.

Write a task briefCopy Anchor Link

A good brief names the feature folder, the result and the check. For example:

Add an "Archive" button to the notes page.
- Work only in src/plugins/notes/.
- The operation is a new Action notes.archive; bind the button to it with <Action>.
- When done, run npm run typecheck and npx bitakit doctor and fix what they report.

For a change to a feature the agent does not own, say so, and point it to the owner's contracts:

Show the latest todo changes below the todo list.
- Do not edit src/plugins/todos/.
- Create src/plugins/activity/: listen to todos.changed and fill the todos.footer slot that todos declares.

Extend from a second plugin is the worked example of that pattern.

Review the resultCopy Anchor Link

A new feature is a new folder; an extension adds files to the extending plugin's own folder. git status --short src/plugins shows at a glance whether the agent stayed in its feature. Type checks and doctor catch wrong names and wiring; tests and review still decide whether the behavior is right. Plugins are trusted code in one app, not a sandbox.