Draconai Documentation

Overview

This rulebook is the highest-priority behavioral contract for Codex. If any other guidance conflicts with this rulebook, this rulebook wins.

Priority Order

(1) Rulebook (the rules in docs/rulebook/) (2) DevDocs (developer documentation in docs/devdocs/) (3) UserDocs (user-facing documentation) (4) The current code (existing implementation)

If two rules conflict, the newest version wins. Do not silently choose; record the decision as a short ADR note.

Read Order

(1) DOC-AI-RULEBOOK-CORE (2) DOC-AI-RULEBOOK-STAGED-PASSES (3) DOC-AI-RULEBOOK-ROLES (4) DOC-AI-RULEBOOK-CHANGE-BUDGET (5) DOC-AI-RULEBOOK-DIFF-FIRST (6) DOC-AI-RULEBOOK-DOD (7) DOC-AI-RULEBOOK-BOUNDARIES (8) DOC-AI-RULEBOOK-UNCLEAR (9) DOC-AI-RULEBOOK-DEPLOY (10) DOC-AI-RULEBOOK-REPORTING (11) DOC-AI-RULEBOOK-HYGIENE

—

Core Operating Rules

(1) One task at a time, in chronological order. Do not start the next task until the current one is completed and moved to codex_work_queue/3. done/. (2) Stay within the task scope. No drive-by edits or unrelated changes. (3) Documentation-first. Update docs/devdocs/ before or alongside implementation changes. (4) One source of truth for rules. Keep rules short, hard, and versioned. Long explanations are secondary and must not override rules. (5) No dead artifacts. Do not introduce unused files/classes/functions/routes/templates. If you create something, it must be referenced/used. If you replace something, remove the replaced code/file unless explicitly told to keep it. (6) Do not weaken security to “make it work”. Keep access control and validation strict. (7) Report every file touched and every command run. If a command fails or times out, state it explicitly and stop; do not continue “as if it worked”.

—

Staged Multi-Pass Workflow (Explicit)

Passes

The default execution model is staged passes. Each pass has one job. Do not merge passes unless explicitly requested.

Pass 1 — Prepare (Planner): (1) Restate goal + acceptance criteria. (2) Classify change type (PATCH / FEATURE / REFACTOR). (3) List target files + hands-off areas. (4) List risks, edge cases, rollback plan. (5) Define checks/tests to run. (6) No code.

Pass 2 — Execute (Implementer): (1) Implement exactly the prepared plan. (2) No extra refactors, renames, moves, “improvements”. (3) Keep changes bounded to the target list. (4) If the plan is insufficient, stop and return to Pass 1.

Pass 3 — Audit (Reviewer: correctness + rulebook): (1) Verify acceptance criteria. (2) Identify rule violations, missing docs/backlinks, dead artifacts, security/validation mismatches, leftovers. (3) No new features or refactors. (4) If fixes are required, create an explicit Fix Pass (scoped) instead of mixing with Audit.

Pass 4 — Compatibility (Integrator: global consistency): (1) Check for conflicts with existing features/architecture (routes, services, tables, docs). (2) Check invariants (naming, data model, access control). (3) Prefer follow-up tasks over broad changes.

Pass 5 — Documentation (Doc Editor): (1) Update docs only (canonical pages, minimal duplication). (2) Enforce backlinks (no one-way references). (3) If DevDocs are affected, run the approved WordPress sync in the same task unless explicitly told not to. (4) Do not change product code in this pass. If docs reveal a product bug, create a new scoped fix task.

Pass 6 — Testing (Test Author): (1) Add/update tests only (unit/integration/e2e as applicable). (2) Run the defined checks/tests. (3) Do not change product logic in this pass. If tests fail due to product logic, stop and create a new scoped fix task.

Pass 7 — Cleanup (Janitor): (1) Remove leftovers, unused code/files, temporary debug output. (2) Tighten references and backlinks where applicable. (3) No behavior changes.

Stop conditions (apply to all passes): (1) If requirements are unclear: stop and ask a direct question. (2) If a command fails or times out: stop and report. (3) If conflicts are detected: stop and propose minimal options + next step. (4) If a pass would require breaking its boundaries: stop and create a new scoped follow-up task.

—

Roles Workflow (No Mixing)

Roles

Work in explicit roles. Do not mix roles in one step unless explicitly requested.

Planner / Architect: (1) Output a plan only. No code. (2) Must include: change type, file list, hands-off list, risks, rollback plan, checks/tests.

Implementer: (1) Implement exactly the approved plan. (2) Do not add extra refactors, renames, moves, or “improvements”. (3) If the plan is insufficient, stop and return to Planner role.

Reviewer: (1) Only inspect and report: rule violations, inconsistencies, missing links, leftovers, security concerns. (2) Do not implement new features or refactors.

Integrator: (1) Only check global consistency and conflicts across features/modules/docs. (2) Do not implement broad changes; prefer creating follow-up tasks.

Doc Editor: (1) Only update documentation. (2) No product code changes; open a new task for product fixes.

Test Author: (1) Only write/update tests and run tests. (2) No product logic changes; open a new task for product fixes.

Janitor: (1) Cleanup only: remove dead artifacts, unused code paths, temporary debug output, duplicate utilities, unreferenced routes/templates, TODO/FIXME without tracking. (2) Do not introduce new behavior.

—

Change Budget (PATCH / FEATURE / REFACTOR)

Budget

Every task must be classified before coding:

PATCH: (1) Minimal edits. (2) Max file count: define in task. If not defined, keep as low as possible. (3) No new tables, no new modules, no broad rewrites.

FEATURE: (1) New behavior with explicit boundaries. (2) Exact affected modules/files must be listed. (3) No unrelated refactors.

REFACTOR: (1) No behavior changes. (2) Bounded scope and explicit goal (readability, duplication removal, performance). (3) Must not expand into feature work.

Before coding, state: (1) Type (2) Target file list (3) Hands-off list (4) Risks (5) Rollback plan

—

Diff-First Guardrails

First

Do not start coding without explicit guardrails:

Required upfront: (1) Goal / outcome (2) Target files to touch (3) Hands-off areas (4) Max diff budget (lines or scope), if provided by the task; otherwise keep minimal (5) No renames/moves unless explicitly requested (6) No drive-by refactor

At the end: (1) Provide a per-file patch summary: what changed and why (1–3 bullets per file).

—

File Map + Architecture + Decisions (Project Map)

Map

Maintain a small project map to reduce guessing:

(1) docs/devdocs/file-map.md: each folder purpose (1–2 lines) + key files (2) docs/devdocs/architecture.md: high-level boundaries only (modules, data flow) (3) docs/devdocs/ADR-*.md: short decision notes (what/why)

If a change affects structure, update the relevant map/ADR in the same task.

—

Definition of Done (DoD)

Definition Of Done

A task is “done” only if all are true:

(1) No unreferenced new files. (2) No TODO/FIXME without a tracking reference (issue/ticket/path). (3) New logic has tests OR an explicit reason why not (and what to test later). (4) No drive-by refactor outside the affected modules. (5) Docs updated minimally: rules / file map / feature page as applicable. (6) Backlinks present where links are introduced (no one-way references). (7) Cleanup performed: no abandoned code paths, no temporary debug output. (8) Audit + Compatibility passes completed, or explicitly skipped with reason. (9) Documentation pass completed, or explicitly skipped with reason. (10) Testing pass completed, or explicitly skipped with reason.

—

Execution Boundaries

Boundaries

(1) Do not modify or write to .ssh. Use existing keys only. (2) Operate from the repo directory unless a task explicitly requires a server action. (3) Do not introduce ambiguous behavior. Prefer explicit steps and explicit choices when requirements are unclear. (4) No broad refactors unless explicitly requested. No renames/moves unless explicitly requested.

—

Missing or Unclear Instructions

Unclear

(1) If requirements are missing or ambiguous, ask a direct question before proceeding. (2) If blocked by missing files or access, state what is missing and the minimal next step to unblock. (3) If multiple interpretations exist, list the minimal set of options and ask which one to pick. Do not guess.

—

Deployment and Sync

Deployment

(1) When code or DevDocs assets change, deploy/sync exactly as specified in python3 scripts_local/publish_devdocs.py. (2) For docs sync, use: python3 scripts_local/publish_devdocs.py. (3) After documentation changes that affect DevDocs, perform the WordPress sync in the same task unless explicitly told not to. (4) If sync/deploy fails: report the error output and stop; do not proceed to the next task.

—

Required Reporting Format (End of Each Task)

(1) Change type (PATCH / FEATURE / REFACTOR) (2) Passes executed (Prepare/Execute/Audit/Compatibility/Documentation/Testing/Cleanup) and any skipped passes + reason (3) Files changed (exact paths) (4) Commands run (exact commands) (5) Result summary (what changed, 1–5 bullets) (6) Errors/timeouts (if any) (7) Docs synced? (yes/no + command + outcome) (8) Tests run? (yes/no + commands + outcome) (9) Cleanup performed? (yes/no + what) (10) Per-file patch summary (what/why)

—

Hygiene Gates (No Orphan Artifacts)

(1) Prefer automatic checks where available (lint/static checks/dead code). (2) Do not leave large unreviewed diffs. Keep iterations small. (3) If a task introduces new files, ensure they are referenced and documented in the relevant file map/feature page. (4) Remove duplicates and unused exports/imports when encountered inside scope. (5) If recurring hygiene issues appear, propose a minimal repo “watcher” (pre-commit/CI/hygiene job) instead of repeated manual cleanup.

DeveloperDoc ID: Page: AI Rulebook (Highest Priority)