From b30b7ee739f9e2225d6a5496d290beb0e009c8ef Mon Sep 17 00:00:00 2001 From: Michael Chus Date: Sun, 1 Mar 2026 17:04:41 +0300 Subject: [PATCH] Add project bible rules and update README - rules/patterns/go-project-bible/contract.md: required files, ADL format, runtime-flows rules, what not to duplicate, how to keep current - README.md: rewritten to reflect actual repo purpose and structure Co-Authored-By: Claude Sonnet 4.6 --- README.md | 65 ++++++------ rules/patterns/go-project-bible/contract.md | 110 ++++++++++++++++++++ 2 files changed, 144 insertions(+), 31 deletions(-) create mode 100644 rules/patterns/go-project-bible/contract.md diff --git a/README.md b/README.md index ac2adfb..a5a94e9 100644 --- a/README.md +++ b/README.md @@ -1,41 +1,44 @@ -# UI Design Code +# Bible -Submodule-first design-code kit for Go web applications and AI coding agents. +Shared engineering rules library for Go web projects. -This repository is meant to be added to host projects as a git submodule and used to -copy/sync canonical documentation, AI instruction templates, scaffolds, and UI pattern -building blocks. +Add as a git submodule to any project — agents (Claude, Codex) will read the rules automatically. -## Intended Usage - -1. Add as submodule (recommended path: `tools/ui-design-code`) -2. Use `tools/designsync` to list/plan/apply bundles into the host repo -3. Review changes and commit in the host repo - -## Public Surface (stable) - -- `kit/` -- `exports/` -- `tools/designsync/` -- `README.md` -- `VERSIONING.md` -- `CHANGELOG.md` - -`demo/` is a runnable reference app and may change faster. - -## Quick Start (this repo) +## Usage ```bash -go test ./... -go build ./tools/designsync +# Add to a project +git submodule add https://git.mchus.pro/mchus/bible.git bible -cd demo -go test ./... -go run ./cmd/demo-server +# Update to latest rules +git submodule update --remote bible ``` -## Documentation +## Structure -- Architecture source of truth: `bible/README.md` -- AI instructions: `CLAUDE.md`, `AGENTS.md` +``` +rules/patterns/ — shared engineering rule contracts + go-logging/ — slog, server-side only + go-database/ — cursor safety, soft delete, GORM, N+1 + go-api/ — REST conventions, error format, status codes + go-background-tasks/ — Task Manager pattern, polling + go-code-style/ — layering, error wrapping, startup sequence + go-project-bible/ — how to write and maintain a project bible + import-export/ — CSV Excel-compatible format, streaming export + table-management/ — toolbar, filtering, pagination + modal-workflows/ — state machine, htmx pattern, confirmation + forms-validation/ — validation, multi-step flows + controls-selection/ — buttons, checkboxes, segmented filters +rules/ai/claude/ + CLAUDE.template.md — base CLAUDE.md template for new projects +``` +## Project Setup + +Each project needs: +- `bible/` — this submodule +- `bible-local/` — project-specific architecture (data model, API, ADL) +- `CLAUDE.md` + `AGENTS.md` — point agents to both + +See `rules/ai/claude/CLAUDE.template.md` for a ready-made template. +See `rules/patterns/go-project-bible/contract.md` for what goes in `bible-local/`. diff --git a/rules/patterns/go-project-bible/contract.md b/rules/patterns/go-project-bible/contract.md new file mode 100644 index 0000000..def60bf --- /dev/null +++ b/rules/patterns/go-project-bible/contract.md @@ -0,0 +1,110 @@ +# Contract: Project Bible (bible-local/) + +## Purpose + +`bible-local/` is the single source of truth for everything **specific to this project**: +data model, API surface, business rules, architectural decisions. + +Shared engineering rules (CSV, logging, DB, tables, etc.) live in the `bible/` submodule. +Do not duplicate them in `bible-local/`. + +## Required Files + +Every project bible must have these files: + +``` +bible-local/ + README.md — index: what files exist and what each covers + architecture/ + system-overview.md — what the product does, active scope, non-goals + data-model.md — domain entities, DB tables, naming conventions + api-surface.md — all HTTP endpoints with methods and response shape + runtime-flows.md — key mutation flows, invariants, critical rules + decisions/ + README.md — ADL format explanation + YYYY-MM-DD-topic.md — one file per architectural decision +``` + +Optional (add when relevant): +``` + architecture/ + ui-information-architecture.md — page structure, navigation, UI invariants + docs/ + INTEGRATION_GUIDE.md — external system integration (formats, protocols) +``` + +## system-overview.md Rules + +- List what is **in scope** and what is **explicitly out of scope**. +- Out of scope section prevents scope creep — update it when you reject a feature. +- Include tech stack and local run command. + +## data-model.md Rules + +- Document canonical naming: if domain model uses `Machine` but API uses `asset`, say so explicitly. +- List all DB tables with one-line description of each. +- Document any non-obvious invariants (e.g. "parts are projections of history, not source of truth"). +- Migration policy: how migrations are numbered and applied. + +## api-surface.md Rules + +- Every endpoint: method, path, brief description, key response fields. +- Group by domain area (Registry, Ingest, Timeline, etc.). +- Note any endpoints that are UI-only routes vs JSON API. +- Document pagination, filtering params where non-obvious. + +## runtime-flows.md Rules + +This is the most important file. Document flows that are **easy to break**: + +- Mutation paths (what happens step by step when user does X) +- Event/time source priority rules +- Deduplication logic +- Cross-entity side effects (e.g. removing a component affects asset status) +- Anything that caused a bug or regression — add a "DO NOT reintroduce" note + +Format each flow as a numbered list of steps, not prose. + +## Architectural Decision Log (ADL) + +Write a decision entry when: +- You choose between two non-obvious approaches +- You intentionally reject a feature or pattern +- A bug caused a rule change (e.g. cursor safety) +- You freeze or deprecate something + +**Format:** + +```markdown +# Decision: + +**Date:** YYYY-MM-DD +**Status:** active | superseded by YYYY-MM-DD-topic.md + +## Context +What situation made this decision necessary. + +## Decision +What was decided, stated clearly. + +## Consequences +What this means going forward. What is now forbidden or required. +``` + +- One decision per file, named `YYYY-MM-DD-short-topic.md`. +- When a decision is superseded, add `superseded by` to the old file's status — do not delete it. +- Record the decision **in the same commit** as the code that implements it. + +## What NOT to Put in bible-local/ + +- Generic rules (CSV format, logging, pagination) → these are in `bible/rules/patterns/` +- Work-in-progress notes, TODO lists → use issues or a separate `docs/` folder +- Duplicate of what is already in code (don't restate what the code clearly shows) +- Speculative future architecture — document what exists, not what might exist + +## Keeping the Bible Current + +- Update `bible-local/` in the **same commit** as the code change it describes. +- If you change a flow, update `runtime-flows.md` in the same PR. +- If a section becomes outdated, fix or delete it — stale docs are worse than no docs. +- Bible files are in **English only**.