Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/XxYouDeaDPunKxX/CSBP-Codex-Shared-Best-Practice/llms.txt

Use this file to discover all available pages before exploring further.

Getting CSBP running in a Codex setup takes only a few minutes. You will place three files in a recommended directory, add one bootstrap line to your AGENTS.md, and then verify that Codex acknowledges the layer at session start. Once CSBP is active, Codex reads the entry point first every session, then loads the runtime practice file — and only opens the compiler when you explicitly ask for practice formation work.
1

Create the directory layout

Place all three CSBP files inside your .codex/memories/ directory. This keeps them co-located and clearly separate from project source files.
.codex/
  memories/
    CSBP-entry-point.txt
    shared-best-practice.txt
    shared-best-practice-compiler.txt
Copy the files from the CSBP repository exactly as released. Do not modify CSBP-entry-point.txt or shared-best-practice-compiler.txt — they are fixed system-definition layers.
2

Wire the entry point into AGENTS.md

Open your .codex/AGENTS.md and add a bootstrap instruction that tells Codex to read CSBP-entry-point.txt at the start of every session, before any other CSBP file is consulted.The exact phrasing depends on your host environment contract, but the minimal bootstrap line looks like this:
## CSBP

Read `.codex/memories/CSBP-entry-point.txt` at the start of every session before using CSBP.
This ensures a fresh Codex session reads the entry point first, activates CSBP for that session, and then loads the runtime practice file. Do not rely on filename inference alone — the entry point must be read explicitly.
3

Initialise shared-best-practice.txt

On first install, shared-best-practice.txt should contain only the file header that ships with the CSBP repository — no practice blocks yet. That is the correct empty state.When the runtime file has no active practices, Codex continues work normally without CSBP runtime guidance. There is nothing to configure. The compiler is not loaded during normal runtime; it is only opened when you ask for practice formation work.The shipped shared-best-practice.txt begins with a fixed header. On first install, with no practices yet promoted, the file contains only this header:
ENTRY
load through CSBP-entry-point.txt

NAME
shared best practice runtime

VERSION
0.1

ROLE
runtime store for practices already promoted by the shared best practice compiler protocol
runtime store for runtime-ready practices only

AUTHORITY
see CSBP-entry-point.txt for authority order
shared best practice runtime does not redefine policy
shared best practice runtime does not redefine scope
shared best practice runtime does not redefine authority

USE
apply only when applies_when matches current work
active entries guide current work decisions
deprecated entries do not guide runtime use
deprecated entries remain available for review only

READ ORDER
check status
if status is deprecated, stop reading the block
check applies_when
use goal for interpretation
apply do as default action
use avoid as competing-pattern guard

BLOCK SHAPE
id: PNNN sequential practice identifier
status: whether the practice is active for runtime use
scope: whether the practice is global or environment-global
kind: practice category used for interpretation
applies_when: operational condition for relevance
goal: intended operational effect
do: primary default action
avoid: recurring competing pattern

STATUS
active: use at runtime when relevant
deprecated: exclude from runtime use

SCOPE
global: stable across work contexts
environment-global: stable across the current working environment across sessions

KIND
environment: stable environment constraint or affordance
orientation: setup, framing, or initial approach
operation: execution step or working method during real work
verification: check, confirmation, or closure practice

WRITE RULE
runtime practice changes must follow shared-best-practice-compiler.txt
do not add or revise a runtime practice without operator approval
do not deprecate or remove a runtime practice without operator approval
As practices are formed and approved, promoted blocks are appended below the header using the fixed block shape.
4

Understand what an active practice block looks like

Once you have gone through at least one formation cycle, promoted practices will appear in shared-best-practice.txt in this shape:
id: P001
status: active
scope: global
kind: verification
applies_when: closing out a task that involved file changes
goal: ensure all changed files are confirmed written before marking work done
do: explicitly verify each modified file exists and contains the expected content before closing
avoid: assuming a write succeeded because no error was reported
Each field has a specific runtime function. The status field is checked first — deprecated blocks are skipped entirely. Then applies_when is evaluated against the current work context. If it matches, do is applied as the default action and avoid is used as the competing-pattern guard.
The id (in PNNN format) is assigned only at promotion, not during the proposal stage. Never assign a final runtime id to a practice that has not yet been approved by the operator.
5

Verify CSBP is active

At the start of your next Codex session, ask Codex to confirm CSBP is loaded:
Confirm CSBP is active and report any active practices.
A correctly configured session will produce a response like one of the following:If shared-best-practice.txt has active practices:
CSBP is active. Entry point loaded. Runtime file loaded.
Active practices: P001 (verification, global).
If shared-best-practice.txt is empty or has no active practices:
CSBP is active. Entry point loaded. Runtime file loaded.
No active practices found. Continuing without CSBP runtime guidance.
If Codex does not acknowledge CSBP, check that the bootstrap line in AGENTS.md correctly references the path to CSBP-entry-point.txt and that the file exists at that path.

​
Session load order

It helps to understand exactly what Codex loads and when:
PathFiles loadedWhen
Runtime path (every session)CSBP-entry-point.txt → shared-best-practice.txtSession start
Formation path (on request only)CSBP-entry-point.txt → shared-best-practice.txt → shared-best-practice-compiler.txtWhen you ask for practice formation or maintenance work
The compiler is never loaded into normal runtime behavior. Loading it only when needed keeps the layer light, prevents speculative guidance from becoming active behavior, and ensures that formation logic never leaks into regular work sessions.

​
What not to do

  • Do not modify CSBP-entry-point.txt or shared-best-practice-compiler.txt — they are fixed system-definition layers.
  • Do not add practices to shared-best-practice.txt without going through the compiler protocol and receiving operator approval.
  • Do not run CSBP alongside an automatic memory system that is doing the same job — two persistence layers create unclear authority.

The Three-File System

Understand the purpose of each file and why their jobs must stay separate.

Practice Formation

Learn how to raise a candidate practice and guide it through the compiler protocol.

Authority Model

See exactly how CSBP fits into the Codex authority stack.

Runtime Behavior

Understand how active practices are read, matched, and applied during work.

Build docs developers (and LLMs) love

Get started for freeTalk to us