Bitfield Docs

AI agents will default to traditional app architecture unless the docs teach the Bitfield translation directly. Give the agent a concrete job, the public names it may use, and the private files it must not import or parse.

You ask an AI agent to add a feature. It creates a store, imports another package, parses a JSON file, or calls an implementation directly. The code may compile, but it trains the app back into the old architecture.The useful output is code that chooses the Bitfield path before the first edit, not code that compiles after recreating the old app shape.

The prompt to paste

Build this the Bitfield way.

Do not create a shared mutable app object.
Do not import another package's private store, service, file, or implementation.
Do not make React, Swift, Kotlin, Rust, Python, or any other shell become the coordinator.

Classify the job first:
- shared product fact -> Bitfield state
- data another package made available -> data name
- work another package should run -> action request
- visual-only state -> private UI state
- bytes shipped with a package -> things-to-store-and-run.json

Before editing, state which category each new value or action belongs to.
After editing, report the public data names, action names, package files, private UI state, and tests/checks.

Classification protocol

Before writing code, the agent must fill this out:

Question	Answer format
What product fact is shared?	`shared fact: selected-file` or `none`
What named data is read?	`data name: project-preview-surface` or `none`
What work is requested?	`action request: selected-agent.update` or `none`
What state is visual-only?	`private UI state: dropdownOpen, hoveredRow`
What package material is used?	`package bytes: getting-started-help` or `none`
What public adapter is used?	`React read hook`, `action request`, `native shell read`, or another public adapter
What private file/code is avoided?	`no package store imports`, `no package file parsing`, `no direct implementation call`

If the agent cannot fill this table out, it should not edit yet.Before accepting the edit, compare it against the concrete translation page: Translate traditional code. That page shows the exact store, service import, direct call, shell branch, package-file read, and private UI state mistakes this checklist is meant to catch.

Bad output and corrected output

The shape most agents reach for

The agent reaches for a shared store, direct import, package file read, or framework coordinator because that is what most public examples show.

Bad: shared object import

import { fileTreeStore } from '../file-tree/store';

const selected = fileTreeStore.selectedFile;

Read the public value

const selected = readInput('selected-file');

React adapter example

const selected = useBitfieldData<string>('selected-file');

Bad: direct implementation call

import { refreshPreviewStatus } from '../project-preview/refresh';

await refreshPreviewStatus(projectId);

Request the work

await sendRequestToBitfieldTarget({
  target: 'project-preview.refresh-status',
  payload: { projectId },
});

Bad: consumer parses package files

const boundary = await fetch('/packages/help-package/things-to-store-and-run.json');

Read package output

const help = readInput('getting-started-help');

Bad: every state value becomes global

await writeBitfieldState('hovered-sidebar-row', rowId);

Keep visual state local

const [hoveredRow, setHoveredRow] = useState<string | null>(null);

Bad: React context becomes product architecture

export const ProductContext = createContext({
  selectedFile: null,
  currentProject: null,
  notificationMode: 'normal',
  setSelectedAgent() {},
});

Use Runtime Kit names

const selectedFile = useBitfieldData<string>('selected-file');
const currentProject = useBitfieldData<Project>('current-project');
const notificationMode = useBitfieldData<string>('notification-mode');

await sendRequestToBitfieldTarget({
  target: 'selected-agent.update',
  payload: { agentId },
});

React can hold visual-only state. It should not become the product coordination layer.

Bad: mixed read and work path

const preview = await refreshPreviewAndReturnGlobalStore(projectStore.current.id);

Split reading from running work

await sendRequestToBitfieldTarget({
  target: 'project-preview.refresh-status',
  payload: { projectId },
});

const preview = readInput('project-preview-surface');

Request work through the action name. Read data through the data name.

Review checklist

Question	Correct answer
Did the agent create a shared app store?	It should not. Use Bitfield state for shared product facts.
Did the agent import another package’s private code?	It should not. Use data names or action requests.
Did the agent put visual-only UI state in Bitfield?	It should not. Keep visual-only state private.
Did the agent parse `things-to-store-and-run.json` from app code?	It should not. Runtime Kit handles package files.
Did the agent call implementation code directly?	It should not. Send an action request.
Did the agent make React the architecture?	It should not. React is one adapter around Bitfield reads/requests.
Did the agent name data and action requests clearly?	It should. Names should describe the real product job.

Common failures

Agent phrase	What it probably means	Correction
”I’ll add a context provider.”	It is making React coordinate product state.	Ask whether this is Bitfield state or private UI state.
”I’ll import the service.”	It is importing private package code.	Use a named action request.
”I’ll read the package JSON.”	It is bypassing Runtime Kit.	Use a data name.
”I’ll add a global store.”	It is rebuilding traditional shared state.	Classify each value first.
”I’ll pass this through props.”	It may be making the shell coordinate shared product state.	Use Bitfield state when multiple packages need it.

Required self-report

At the end of generated work, the agent should report this exact shape:

Shared product facts:
- selected-file

Data names:
- project-preview-surface
- getting-started-help

Action requests:
- project-preview.refresh-status
- selected-agent.update

Private UI state:
- dropdownOpen
- hoveredRow

Private files/code not used:
- no package store imports
- no package file parsing
- no direct implementation call
- React used only as adapter

If the report says “none” for everything but the code adds a feature that coordinates multiple packages, the agent probably hid traditional coupling in the implementation. Review the imports and state placement before accepting it.

Share state correctly: Share state between packages
Ask for work correctly: Ask another package to do work
Use the larger agent page: Build with AI agents

Use Runtime Kit

Understand Runtime Kit

Build without tangled code

Runtime Kit Cookbook

Reference

Rules for AI agents

The prompt to paste

Classification protocol

Bad output and corrected output

The shape most agents reach for

Bad: shared object import

Read the public value

React adapter example

Bad: direct implementation call

Request the work

Bad: consumer parses package files

Read package output

Bad: every state value becomes global

Keep visual state local

Bad: React context becomes product architecture

Use Runtime Kit names

Bad: mixed read and work path

Split reading from running work

Review checklist

Common failures

Required self-report

Next

​The prompt to paste

​Classification protocol

​Bad output and corrected output

​The shape most agents reach for

​Bad: shared object import

​Read the public value

​React adapter example

​Bad: direct implementation call

​Request the work

​Bad: consumer parses package files

​Read package output

​Bad: every state value becomes global

​Keep visual state local

​Bad: React context becomes product architecture

​Use Runtime Kit names

​Bad: mixed read and work path

​Split reading from running work

​Review checklist

​Common failures

​Required self-report

​Next

The prompt to paste

Classification protocol

Bad output and corrected output

The shape most agents reach for

Bad: shared object import

Read the public value

React adapter example

Bad: direct implementation call

Request the work

Bad: consumer parses package files

Read package output

Bad: every state value becomes global

Keep visual state local

Bad: React context becomes product architecture

Use Runtime Kit names

Bad: mixed read and work path

Split reading from running work

Review checklist

Common failures

Required self-report

Next