> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitfield.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules for AI agents

> Tell AI agents how to build Bitfield features without falling back to traditional coupled app architecture.

<div className="bf-article">
  <p className="bf-lead">
    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.
  </p>

  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

  ```text theme={null}
  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](/runtime-kit/build-without-tangled-code/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

  ```ts theme={null}
  import { fileTreeStore } from '../file-tree/store';

  const selected = fileTreeStore.selectedFile;
  ```

  ### Read the public value

  ```ts theme={null}
  const selected = readInput('selected-file');
  ```

  ### React adapter example

  ```tsx theme={null}
  const selected = useBitfieldData<string>('selected-file');
  ```

  ### Bad: direct implementation call

  ```ts theme={null}
  import { refreshPreviewStatus } from '../project-preview/refresh';

  await refreshPreviewStatus(projectId);
  ```

  ### Request the work

  ```ts theme={null}
  await sendRequestToBitfieldTarget({
    target: 'project-preview.refresh-status',
    payload: { projectId },
  });
  ```

  ### Bad: consumer parses package files

  ```ts theme={null}
  const boundary = await fetch('/packages/help-package/things-to-store-and-run.json');
  ```

  ### Read package output

  ```ts theme={null}
  const help = readInput('getting-started-help');
  ```

  ### Bad: every state value becomes global

  ```ts theme={null}
  await writeBitfieldState('hovered-sidebar-row', rowId);
  ```

  ### Keep visual state local

  ```ts theme={null}
  const [hoveredRow, setHoveredRow] = useState<string | null>(null);
  ```

  ### Bad: React context becomes product architecture

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

  ### Use Runtime Kit names

  ```tsx theme={null}
  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

  ```ts theme={null}
  const preview = await refreshPreviewAndReturnGlobalStore(projectStore.current.id);
  ```

  ### Split reading from running work

  ```ts theme={null}
  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:

  ```text theme={null}
  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.

  ## Next

  * Share state correctly: [Share state between packages](/runtime-kit/build-without-tangled-code/share-state-between-packages)
  * Ask for work correctly: [Ask another package to do work](/runtime-kit/build-without-tangled-code/ask-another-package-to-do-work)
  * Use the larger agent page: [Build with AI agents](/runtime-kit/ai-build-rules)
</div>