From c1ab0fd964b885258ee02e37eb56cd458eae0c68 Mon Sep 17 00:00:00 2001 From: Branimir Georgiev Date: Sun, 26 Apr 2026 08:40:45 +0300 Subject: [PATCH 1/2] docs: restructure CLAUDE.md with numbered sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add numbered sections (1–5) matching root repo convention - Add git conventions section (2.1) - Add cross-reference caveat about URL paths vs filesystem paths - Fix domain from braboj.github.io to braboj.me - Fix docs/ description from "Legacy MkDocs" to "Project docs" - Fix duplicate numbering in end-of-session checklist - Add session startup protocol (4.2) - Reorder: Project → Conventions → Figures → Session → Commands Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 120 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 69 insertions(+), 51 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d2c01db..4fc2294 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,9 +2,7 @@ Instructions for Claude Code working in this repository. -Quality conventions (git, docs, quality, scope) are defined in -`docs/solid-ai-templates/` — a git submodule from -[Imbra-Ltd/solid-ai-templates](https://github.com/Imbra-Ltd/solid-ai-templates). +Quality conventions defined in `docs/solid-ai-templates/` (submodule). Key references: - `docs/solid-ai-templates/base/git.md` — git workflow, branching, PRs - `docs/solid-ai-templates/base/docs.md` — documentation rules, ADRs, writing style @@ -16,17 +14,16 @@ Key references: Project-specific overrides and additions follow below. -## Project identity +## 1. Project - **Name**: tutorial-git (Git Tutorial — Code with Branko) - **Owner**: Branimir Georgiev — braboj - **Repo**: github.com/braboj/tutorial-git - **Stack**: Astro static site, Markdown content, draw.io diagrams - **Hosting**: GitHub Pages via GitHub Actions -- **Domain**: braboj.github.io/tutorial-git (codewithbranko.com pending) +- **Domain**: braboj.me/tutorial-git (codewithbranko.com pending) - -## Project structure +### 1.1 Project structure ``` chapters/ # SSG-agnostic tutorial content (canonical) @@ -48,41 +45,27 @@ assets/ doc/ uml/ astro-site/ # Astro build (reads directly from chapters/) -docs/ # Legacy MkDocs content (reference, not active) +docs/ # Project docs, decisions, dev journal solid-ai-templates/ # Submodule — Imbra-Ltd/solid-ai-templates ``` -## Scope guard override +## 2. Conventions -Extends `base/scope.md` with tutorial-specific boundaries: -- One chapter per session is the default scope for content work -- Diagram, exercise, and quiz changes within that chapter are in scope -- Restructuring other chapters, creating new projects, or adding - infrastructure is out of scope unless explicitly requested +### 2.1 Git -## End-of-session checklist - -Before ending a session, verify all of the following: - -1. **Dev journal** — add a session entry to `docs/dev-journal.md` - (date, tool, key changes, PRs merged, issues closed/created, open issues) -2. **CLAUDE.md** — update if project structure or conventions changed -3. **README.md** — update if chapter list, links, or setup instructions changed -4. **ONBOARDING.md** — update `docs/ONBOARDING.md` if prerequisites, - setup steps, or project structure changed -5. **PLAYBOOK.md** — update `docs/PLAYBOOK.md` if operational - workflows or file paths changed -6. **solid-ai-templates** — check if upstream submodule needs updates - based on new patterns or conventions discovered during the session - (e.g. new scope rules, documentation rules, quality conventions) -5. **Open issues** — close resolved GitHub issues, update or create - issues for remaining work +Extends `docs/solid-ai-templates/base/git.md` with project-specific rules: +- Feature branches: `feature/` +- Always run `git checkout main && git pull` before creating a new + feature branch +- One commit per logical change +- PR title: concise, under 70 characters +- Delete feature branch after merge (local and remote) -## Content conventions +### 2.2 Content -### Chapter structure +#### Chapter structure Every chapter follows this structure: @@ -92,7 +75,7 @@ Every chapter follows this structure: 4. `## Exercises` — hands-on tasks with verification steps 5. `## Quiz` — multiple-choice questions with answers at the bottom -### Writing style +#### Writing style - **American English** spelling (analyze, not analyse) - **Git** capitalised in prose, `git` lowercase in commands and code blocks @@ -102,21 +85,24 @@ Every chapter follows this structure: - No inline Practice sections — all practice goes in Exercises - No emojis unless explicitly requested -### Quiz formatting +#### Quiz formatting - Each option on a bullet line: `- A) ...`, `- B) ...` - Vary the correct answer positions — never all the same letter - Answers section at the bottom: `1. C — explanation` -### Cross-references +### 2.3 Cross-references - Reference other chapters by file: `[Building Blocks](02-building-blocks.md)` - Reference sections within a chapter by heading anchor: `[Tag Object](#tag-object-labels)` -- The remark plugin (`astro-site/src/plugins/remark-rewrite-links.ts`) - rewrites `NN-slug.md` links to `../slug/` at build time — no manual - sync needed +- Markdown links must use the **URL path** (driven by `section` frontmatter), + not the filesystem path — the remark plugin + (`astro-site/src/plugins/remark-rewrite-links.ts`) rewrites links at + build time +- Recipe pages live in `chapters/recipes/` but their URLs are + `/playbook/...` — link to them as `playbook/X.md`, not `recipes/X.md` -### Images +### 2.4 Images - Source files: `assets/drawio/` (`.drawio` format) - Exported PNGs: `assets/images/` @@ -125,11 +111,11 @@ Every chapter follows this structure: - ASCII diagrams in markdown serve as fallback and source of truth -## Figure style rules +## 3. Figure style rules Every figure follows these rules. Applies to draw.io XML, PlantUML, and SVG. -### Core principles +### 3.1 Core principles - Flat only: no gradients, shadows, glows, or 3D effects - Sentence case for prose labels — filenames and acronyms keep their casing @@ -138,7 +124,7 @@ Every figure follows these rules. Applies to draw.io XML, PlantUML, and SVG. - One visual grammar per figure — if it needs two, split into two figures - Shapes (circle vs pill vs card) distinguish elements in grayscale -### Palettes +### 3.2 Palettes **A — Difficulty** (tier cards): - Beginner: fill `#EAF3DE`, border `#3B6D11`, text `#27500A` @@ -169,7 +155,7 @@ for readers who use Git tools. - Border `#D3D1C7`, primary text `#2C2C2A`, secondary text `#5F5E5A`, arrow stroke `#444441`, white card `#FFFFFF`. -### Typography +### 3.3 Typography | Use | Font | Size | Weight | Style | |---|---|---|---|---| @@ -179,7 +165,7 @@ for readers who use Git tools. | Captions, footnotes | Helvetica | 11–12 px | Regular | — | | Descriptive notes, placeholders | Helvetica | 11 px | Regular | Italic | -### Arrow conventions +### 3.4 Arrow conventions - Solid 1 px `#444441`, 6 × 6 px chevron head. Labels in clear space, never on the line. @@ -191,7 +177,7 @@ for readers who use Git tools. - **Italic `#5F5E5A` label** for named relationships (`attached`, `parent`). - **Self-loop** (small arc above box corner) for recursive references. -### Component vocabulary +### 3.5 Component vocabulary - **Card**: rounded rect, rx=5–8, 0.5 px border, 10–12 px inner padding. - **Pill**: rounded rect with rx = height/2. For branches, tags, short labels. @@ -202,14 +188,14 @@ for readers who use Git tools. readability on both light and dark page backgrounds. Export PNGs with transparent background — the card provides the contrast. -### Commit-chain panel variant +### 3.6 Commit-chain panel variant Gray commit circles (diameter 28), branch pills to the right of the commit they point to, italic "HEAD" label above the active branch pill. `*main` means HEAD is attached to main. Dashed arrow from pill to commit shows the reference relationship. Uses Palette C. -### draw.io file conventions +### 3.7 draw.io file conventions - Source files: `assets/drawio/.drawio` - Naming: `git--.drawio` (e.g. `git-branch-merge.drawio`) @@ -217,7 +203,7 @@ shows the reference relationship. Uses Palette C. - All cells `parent="1"` - XML-escape values: `&` → `&`, `<` → `<`, `>` → `>` -### draw.io style string templates +### 3.8 draw.io style string templates ``` # Commit circle (gray): @@ -245,7 +231,7 @@ endArrow=classic;html=1;strokeColor=#444441;strokeWidth=1;endFill=1;endSize=6;da rounded=1;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#D3D1C7;strokeWidth=0.5;shadow=0;arcSize=5; ``` -### XML boilerplate +### 3.9 XML boilerplate ```xml @@ -263,7 +249,39 @@ rounded=1;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#D3D1C7;strokeWid ``` -## Commands +## 4. Session protocol + +### 4.1 Scope guard + +Extends `base/scope.md` with tutorial-specific boundaries: +- One chapter per session is the default scope for content work +- Diagram, exercise, and quiz changes within that chapter are in scope +- Restructuring other chapters, creating new projects, or adding + infrastructure is out of scope unless explicitly requested + +### 4.2 Startup + +Read all referenced template documents before starting work. Confirm +session scope with the user. + +### 4.3 End of session + +Before ending a session, verify all of the following: + +1. **Dev journal** — add a session entry to `docs/dev-journal.md` + (date, tool, key changes, PRs merged, issues closed/created, open issues) +2. **CLAUDE.md** — update if project structure or conventions changed +3. **README.md** — update if chapter list, links, or setup instructions changed +4. **ONBOARDING.md** — update `docs/ONBOARDING.md` if prerequisites, + setup steps, or project structure changed +5. **PLAYBOOK.md** — update `docs/PLAYBOOK.md` if operational + workflows or file paths changed +6. **solid-ai-templates** — check if upstream submodule needs updates +7. **Open issues** — close resolved GitHub issues, update or create + issues for remaining work + + +## 5. Commands ```bash # Astro site (from astro-site/) From 1037c16091059ce2778bbedf8c07358db99e74e2 Mon Sep 17 00:00:00 2001 From: Branimir Georgiev Date: Sun, 26 Apr 2026 08:43:15 +0300 Subject: [PATCH 2/2] docs: move figure style rules under conventions (2.5) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Figures are content — they belong under conventions, not as a separate top-level section. Renumbers sections 3–4. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4fc2294..76fe39b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -111,11 +111,11 @@ Every chapter follows this structure: - ASCII diagrams in markdown serve as fallback and source of truth -## 3. Figure style rules +### 2.5 Figures Every figure follows these rules. Applies to draw.io XML, PlantUML, and SVG. -### 3.1 Core principles +#### Core principles - Flat only: no gradients, shadows, glows, or 3D effects - Sentence case for prose labels — filenames and acronyms keep their casing @@ -124,7 +124,7 @@ Every figure follows these rules. Applies to draw.io XML, PlantUML, and SVG. - One visual grammar per figure — if it needs two, split into two figures - Shapes (circle vs pill vs card) distinguish elements in grayscale -### 3.2 Palettes +#### Palettes **A — Difficulty** (tier cards): - Beginner: fill `#EAF3DE`, border `#3B6D11`, text `#27500A` @@ -155,7 +155,7 @@ for readers who use Git tools. - Border `#D3D1C7`, primary text `#2C2C2A`, secondary text `#5F5E5A`, arrow stroke `#444441`, white card `#FFFFFF`. -### 3.3 Typography +#### Typography | Use | Font | Size | Weight | Style | |---|---|---|---|---| @@ -165,7 +165,7 @@ for readers who use Git tools. | Captions, footnotes | Helvetica | 11–12 px | Regular | — | | Descriptive notes, placeholders | Helvetica | 11 px | Regular | Italic | -### 3.4 Arrow conventions +#### Arrow conventions - Solid 1 px `#444441`, 6 × 6 px chevron head. Labels in clear space, never on the line. @@ -177,7 +177,7 @@ for readers who use Git tools. - **Italic `#5F5E5A` label** for named relationships (`attached`, `parent`). - **Self-loop** (small arc above box corner) for recursive references. -### 3.5 Component vocabulary +#### Component vocabulary - **Card**: rounded rect, rx=5–8, 0.5 px border, 10–12 px inner padding. - **Pill**: rounded rect with rx = height/2. For branches, tags, short labels. @@ -188,14 +188,14 @@ for readers who use Git tools. readability on both light and dark page backgrounds. Export PNGs with transparent background — the card provides the contrast. -### 3.6 Commit-chain panel variant +#### Commit-chain panel variant Gray commit circles (diameter 28), branch pills to the right of the commit they point to, italic "HEAD" label above the active branch pill. `*main` means HEAD is attached to main. Dashed arrow from pill to commit shows the reference relationship. Uses Palette C. -### 3.7 draw.io file conventions +#### draw.io file conventions - Source files: `assets/drawio/.drawio` - Naming: `git--.drawio` (e.g. `git-branch-merge.drawio`) @@ -203,7 +203,7 @@ shows the reference relationship. Uses Palette C. - All cells `parent="1"` - XML-escape values: `&` → `&`, `<` → `<`, `>` → `>` -### 3.8 draw.io style string templates +#### draw.io style string templates ``` # Commit circle (gray): @@ -231,7 +231,7 @@ endArrow=classic;html=1;strokeColor=#444441;strokeWidth=1;endFill=1;endSize=6;da rounded=1;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#D3D1C7;strokeWidth=0.5;shadow=0;arcSize=5; ``` -### 3.9 XML boilerplate +#### XML boilerplate ```xml @@ -249,9 +249,9 @@ rounded=1;whiteSpace=wrap;html=1;fillColor=#FFFFFF;strokeColor=#D3D1C7;strokeWid ``` -## 4. Session protocol +## 3. Session protocol -### 4.1 Scope guard +### 3.1 Scope guard Extends `base/scope.md` with tutorial-specific boundaries: - One chapter per session is the default scope for content work @@ -259,12 +259,12 @@ Extends `base/scope.md` with tutorial-specific boundaries: - Restructuring other chapters, creating new projects, or adding infrastructure is out of scope unless explicitly requested -### 4.2 Startup +### 3.2 Startup Read all referenced template documents before starting work. Confirm session scope with the user. -### 4.3 End of session +### 3.3 End of session Before ending a session, verify all of the following: @@ -281,7 +281,7 @@ Before ending a session, verify all of the following: issues for remaining work -## 5. Commands +## 4. Commands ```bash # Astro site (from astro-site/)