diff --git a/AGENT-BOOTSTRAP.md b/AGENT-BOOTSTRAP.md index 5f8d73a..c1eb15e 100644 --- a/AGENT-BOOTSTRAP.md +++ b/AGENT-BOOTSTRAP.md @@ -12,9 +12,16 @@ Use targeted reading. 3. Read only the relevant files in `bible-local/architecture/` and `bible-local/decisions/`. 4. Read only the relevant shared contracts in `bible/rules/patterns/`. +## Editing This Repository + If you are editing this `bible/` repository itself, read the target contract and its nearby `README.md`. Do not walk all contracts unless the task is explicitly about restructuring the library. +- Edit the relevant existing contract, or create a new `rules/patterns//contract.md`. +- Normative rules go in `contract.md`; examples and rationale go in the pattern's `README.md`. +- Do not create rules outside `rules/patterns/`. Do not expand scope beyond engineering rules and patterns. +- Run `sh scripts/lint.sh` after changes. + ## Always-On Contracts Read these on most tasks: diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 815990e..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,11 +0,0 @@ -# Bible — Instructions for Codex - -This repository is the shared engineering rules library for all projects. - -Start with `AGENT-BOOTSTRAP.md`. -Do not read the whole repository by default. Read only the relevant contracts for the current task. - -Rules live in `rules/patterns/` as `contract.md` files. When adding or updating a rule: -- Find the relevant existing contract and edit it, or create a new `rules/patterns//contract.md`. -- Do not create rules outside `rules/patterns/`. -- Do not expand scope beyond engineering rules and patterns. diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000..681311e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 88ae290..bf99cd2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,11 +1,5 @@ -# Bible — Instructions for Claude +# Bible — Agent Instructions -This repository is the shared engineering rules library for all projects. - -Start with `AGENT-BOOTSTRAP.md`. -Do not read the whole repository by default. Read only the relevant contracts for the current task. - -Rules live in `rules/patterns/` as `contract.md` files. When adding or updating a rule: -- Find the relevant existing contract and edit it, or create a new `rules/patterns//contract.md`. -- Do not create rules outside `rules/patterns/`. -- Do not expand scope beyond engineering rules and patterns. +Shared engineering rules library. Start with `AGENT-BOOTSTRAP.md`; it defines the read +path, the always-on contracts, the task router, and the rules for editing this repository. +Do not read the whole repository by default. diff --git a/README.md b/README.md index acfbc2f..9ee128f 100644 --- a/README.md +++ b/README.md @@ -4,21 +4,8 @@ Shared engineering rules library for Go web projects. Add as a git submodule to any project — agents (Claude, Codex) will read the rules automatically. -## Agent Read Path - -Agents should not read the whole submodule by default. - -Start here: - -1. `bible/AGENT-BOOTSTRAP.md` -2. `bible-local/README.md` -3. Only the relevant files in `bible-local/architecture/`, `bible-local/decisions/`, and - `bible/rules/patterns/...` - -The bootstrap file contains: -- the always-on core contracts -- a router from task type to relevant contracts -- the default rule to skip unrelated contracts +Agents start at `AGENT-BOOTSTRAP.md` — it defines the read path, always-on contracts, +and the task router. Nothing in this README duplicates it. ## Usage @@ -35,21 +22,15 @@ git submodule update --remote bible ``` AGENT-BOOTSTRAP.md — first file agents should read; contains the full contract router rules/patterns// — one contract.md per topic (plus optional README.md with examples) -rules/ai/claude/ — CLAUDE.template.md for new projects -rules/ai/codex/ — AGENTS.template.md for new projects +rules/ai/AGENT.template.md — template for new projects; copy as both CLAUDE.md and AGENTS.md scripts/lint.sh — consistency checks (router coverage, broken links) ``` -The list of contracts is not duplicated here. The single source of truth for what exists -and when to read it is the router in `AGENT-BOOTSTRAP.md`. - ## Project Setup Each project needs: - `bible/` — this submodule - `bible-local/` — project-specific architecture (data model, API, ADL) -- `CLAUDE.md` + `AGENTS.md` — point agents to the bootstrap file and to `bible-local/` +- `CLAUDE.md` + `AGENTS.md` — copies of `rules/ai/AGENT.template.md` pointing agents to the bootstrap -See `rules/ai/claude/CLAUDE.template.md` for a ready-made template. -See `rules/ai/codex/AGENTS.template.md` for a ready-made Codex template. See `rules/patterns/go-project-bible/contract.md` for what goes in `bible-local/`. diff --git a/rules/ai/AGENT.template.md b/rules/ai/AGENT.template.md new file mode 100644 index 0000000..34b23c8 --- /dev/null +++ b/rules/ai/AGENT.template.md @@ -0,0 +1,17 @@ +# {{ .project_name }} — Agent Instructions + +Copy this file into a project as both `CLAUDE.md` and `AGENTS.md` (identical content). + +## Shared Engineering Rules +Read `bible/AGENT-BOOTSTRAP.md` first and follow its routing. +Do not read the whole `bible/` submodule; the bootstrap defines the read path and the +always-on contracts. + +## Project Architecture +Read `bible-local/README.md` first, then only the relevant files in +`bible-local/architecture/` and `bible-local/decisions/`. +Every architectural decision specific to this project must be recorded in `bible-local/`. + +## Default Rule +Do not claim you "read bible" unless you actually read the relevant files. +Do not walk all shared contracts unless the task is explicitly about changing the rules library itself. diff --git a/rules/ai/claude/CLAUDE.template.md b/rules/ai/claude/CLAUDE.template.md deleted file mode 100644 index fee8a18..0000000 --- a/rules/ai/claude/CLAUDE.template.md +++ /dev/null @@ -1,24 +0,0 @@ -# {{ .project_name }} — Instructions for Claude - -## Shared Engineering Rules -Read `bible/AGENT-BOOTSTRAP.md` first. -Do not read the whole `bible/` submodule by default. -Read only the contracts that `AGENT-BOOTSTRAP.md` routes you to for the current task. - -## Project Architecture -Read `bible-local/README.md` first, then only the relevant project-specific architecture files. -Every architectural decision specific to this project must be recorded in `bible-local/`. - ---- - -## Minimum Read Path - -1. `bible/AGENT-BOOTSTRAP.md` -2. `bible-local/README.md` -3. Relevant files in `bible-local/architecture/` and `bible-local/decisions/` -4. Relevant `bible/rules/patterns/*/contract.md` - -## Default Rule - -Do not claim you "read bible" unless you actually read the relevant files. -Do not walk all shared contracts unless the task is explicitly about changing the rules library itself. diff --git a/rules/ai/codex/AGENTS.template.md b/rules/ai/codex/AGENTS.template.md deleted file mode 100644 index 76290d3..0000000 --- a/rules/ai/codex/AGENTS.template.md +++ /dev/null @@ -1,24 +0,0 @@ -# {{ .project_name }} — Instructions for Codex - -## Shared Engineering Rules -Read `bible/AGENT-BOOTSTRAP.md` first. -Do not read the whole `bible/` submodule by default. -Read only the contracts that `AGENT-BOOTSTRAP.md` routes you to for the current task. - -## Project Architecture -Read `bible-local/README.md` first, then only the relevant project-specific architecture files. -Every architectural decision specific to this project must be recorded in `bible-local/`. - ---- - -## Minimum Read Path - -1. `bible/AGENT-BOOTSTRAP.md` -2. `bible-local/README.md` -3. Relevant files in `bible-local/architecture/` and `bible-local/decisions/` -4. Relevant `bible/rules/patterns/*/contract.md` - -## Default Rule - -Do not claim you "read bible" unless you actually read the relevant files. -Do not walk all shared contracts unless the task is explicitly about changing the rules library itself. diff --git a/rules/patterns/web-visual-baseline/README.md b/rules/patterns/web-visual-baseline/README.md index 939792f..c3c4b06 100644 --- a/rules/patterns/web-visual-baseline/README.md +++ b/rules/patterns/web-visual-baseline/README.md @@ -1,222 +1,12 @@ -# Web Visual Baseline — Starter Assets +# Web Visual Baseline — Reference Assets -This file keeps copyable starter code. The normative rules live in `contract.md`. +The normative rules live in `contract.md`. Canonical reference files (full, production version of the style) are in `assets/`: -- `assets/view.css` -- `assets/view.html` -- `assets/upload.html` +- `assets/view.css` — copy this as the starting stylesheet and adapt tokens +- `assets/view.html` — reference page structure (header, panels, tables) +- `assets/upload.html` — reference upload/open panel -Prefer copying `assets/view.css` directly and adapting tokens. The starter below is a -minimal distilled subset for very small apps. - -## Copyable Starter CSS - -Use this as the default starting point for new web apps: - -```css -:root { - --bg: #ffffff; - --surface: #ffffff; - --surface-2: #f9fafb; - --border: rgba(34, 36, 38, 0.15); - --border-lite: rgba(34, 36, 38, 0.1); - --ink: rgba(0, 0, 0, 0.87); - --muted: rgba(0, 0, 0, 0.6); - --accent: #2185d0; - --accent-dark: #1678c2; - --accent-bg: #dff0ff; - --ok: #16ab39; - --warn: #f2711c; - --crit: #db2828; - --header-bg: #1b1c1d; - --radius: 4px; - --shadow: 0 1px 2px 0 rgba(34, 36, 38, 0.15); - --content-width: 1500px; -} - -* { - box-sizing: border-box; -} - -body { - margin: 0; - background: var(--bg); - color: var(--ink); - font: 14px/1.5 Lato, "Helvetica Neue", Arial, Helvetica, sans-serif; -} - -.page-header { - display: flex; - align-items: center; - justify-content: space-between; - gap: 16px; - padding: 14px 24px; - background: var(--header-bg); -} - -.page-header h1 { - margin: 0; - font-size: 18px; - font-weight: 700; - color: rgba(255, 255, 255, 0.9); -} - -.page-main { - width: min(var(--content-width), calc(100vw - 48px)); - margin: 28px auto 56px; -} - -.panel { - margin-bottom: 28px; - overflow: hidden; - background: var(--surface); - border: 1px solid var(--border); - border-radius: var(--radius); - box-shadow: var(--shadow); -} - -.panel > h2 { - margin: 0; - padding: 13px 16px; - background: var(--surface-2); - border-bottom: 1px solid var(--border); - font-size: 13px; - font-weight: 700; -} - -.table-wrap { - overflow-x: auto; -} - -.kv-table, -.data-table { - width: 100%; - border-collapse: collapse; - background: var(--surface); -} - -.kv-table th, -.kv-table td, -.data-table th, -.data-table td { - padding: 11px 14px; - text-align: left; - vertical-align: top; - border-top: 1px solid var(--border-lite); -} - -.kv-table th, -.data-table th { - background: var(--surface-2); - border-top: 0; - border-bottom: 1px solid var(--border-lite); - font-weight: 700; - white-space: nowrap; -} - -.data-table tbody tr:hover { - background: rgba(0, 0, 0, 0.04); -} - -.button-primary { - display: inline-block; - padding: 8px 18px; - border: none; - border-radius: var(--radius); - background: var(--accent); - color: #fff; - font: inherit; - font-weight: 700; - text-decoration: none; - cursor: pointer; -} - -.button-primary:hover { - background: var(--accent-dark); -} - -.header-action { - display: inline-block; - padding: 6px 14px; - border-radius: var(--radius); - background: rgba(255, 255, 255, 0.12); - color: rgba(255, 255, 255, 0.85); - text-decoration: none; - font-size: 13px; - font-weight: 700; -} - -.header-action:hover { - background: rgba(255, 255, 255, 0.2); -} - -.status-ok { color: var(--ok); } -.status-warning { color: var(--warn); } -.status-critical { color: var(--crit); } -.status-unknown { color: rgba(0, 0, 0, 0.45); } - -@media (max-width: 720px) { - .page-header { - flex-direction: column; - padding: 12px 16px; - } - - .page-main { - width: calc(100vw - 24px); - margin-top: 20px; - } -} -``` - -## Copyable Starter HTML - -```html -
-

Application Title

- Back -
- -
-
-

Overview

-
- - - - - - - - - - - -
Hostserver-01
StatusOK
-
-
- -
-

Devices

-
- - - - - - - - - - - - - - - -
NameVendorStatus
NIC 1IntelWarning
-
-
-
-``` +Do not maintain a separate "starter" copy of the CSS anywhere; `assets/view.css` is the +single source. For a new app, copy it and delete unused rules. diff --git a/rules/patterns/web-visual-baseline/contract.md b/rules/patterns/web-visual-baseline/contract.md index 82a3b40..958d92f 100644 --- a/rules/patterns/web-visual-baseline/contract.md +++ b/rules/patterns/web-visual-baseline/contract.md @@ -14,7 +14,7 @@ in this pattern: - `assets/upload.html` When a project does not already have an established design system, use this baseline by default. -Copyable starter CSS and HTML live in `README.md` next to this contract. +Copy `assets/view.css` as the starting stylesheet and adapt tokens; do not rewrite it from prose. ## Core Direction