diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c9ac0f0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,79 @@ +# Changelog + +All notable changes to this documentation repository, grouped by version and release date. +Document versions of the individual guideline files are tracked separately in their headers. + +## 0.4.0 — 2026-08-18 + +### Added +- Skill versioning: every `SKILL.md` now carries `metadata.version` — `changelog` v2, `check` v1, + `commit` v2, `documentation` v1, `documentation_context` v2. The skill format has no top-level + `version` field; `metadata` is one of the six Agent Skills spec fields, so the frontmatter still + packages and uploads cleanly +- "Skills" section in `README.md` describing the versioning convention, the install location + (`~/.claude/skills/`) and the rule that the folder name — not `name:` — is the command +- The five skills listed individually in the `README.md` structure tree +- `AGENTS.md` v5 → v6: new "Commit messages" subsection under Git — commits and pull requests must + never carry AI authorship (`Co-Authored-By`, "Generated with …", tool signatures or emoji footers). + The subsection also states the single-line verbal English style, so assistants without the `commit` + skill get the same rules; the AI-authorship rule was added to the skill as well +- `CHANGELOG.md` for this repository, with history backfilled from the git log +- Explicit line length for Rust: 100 characters (rustfmt default `max_width`) in both Rust design documents +- `README.md`, `docs/`, `prebuild.py` and the PyInstaller `.spec` to the template structure in `Python/TEMPLATE.md` +- Note in `Python/TEMPLATE.md` that `AGENTS.md` and `DESIGN_DOCUMENT.md` are not part of the template +- `README.md` to the session read list in `Claude/CLAUDE.md`, plus a missing top-level heading + +### Changed +- Document versions bumped for the structural changes released on 2026-08-18: + `DESIGN_DOCUMENT.md` v8 → v9, `DESIGN_DOCUMENT_MODULE.md` v1 → v2, + `Rust/DESIGN_DOCUMENT.md` v1 → v2, `Rust/DESIGN_DOCUMENT_LIB.md` v1 → v2, + `DESIGN_DOCUMENT_GODOT.md` v1 → v2 +- `Project template/CHANGELOG.md` now names the project manifest generically + (`pyproject.toml`, `Cargo.toml`, `project.godot`) instead of `pyproject.toml` only +- Godot debug constant renamed `Constants.DEBUG` → `Constants.DEFAULT_DEBUG`, matching the Python reference module +- `README.md` step 1 of "Starting a new project" now also requires writing a `README.md` +- `Python/TEMPLATE.md` entry point is named by purpose or tool name instead of `main.py` +- `prebuild.py` loads `.env` before importing `src.constants` instead of relying on the import side effect + +### Fixed +- Skill folder `Claude/skills/context/` renamed to `documentation_context/`, with the frontmatter + `name` matched to it. The folder name is what Claude Code turns into the command, so the old + mismatch meant installing from this repository would have changed `/documentation_context` + into `/context` +- Removed the misplaced lock-file rule from the Testing sections of `DESIGN_DOCUMENT_MODULE.md` (§9) + and `Rust/DESIGN_DOCUMENT_LIB.md` (§8) — it already belongs to the Poetry / Distribution sections + +## 0.3.0 — 2026-08-18 + +### Added +- `Zscaler/ZSCALER_CERTIFICATE.md` — full certificate setup for Node, Python, git and cargo +- Language-specific `.gitignore` files for Python, Rust and Godot, plus a shared core in `Project template/` +- `poetry.lock` and `prebuild.py` sections in `Python/DESIGN_DOCUMENT.md` + +### Changed +- Unified task notation across all languages on the Todo Tree tags `TODO`, `FIXME`, `BUG`, `HACK`, `NOTE` +- `AGENTS.md` v4 → v5: rewritten as strictly language-agnostic, naming no concrete tool +- Python line length 150 → 120 characters +- Rust edition 2021 → 2024 (requires Rust 1.85 or newer) +- Godot project version key corrected to `application/config/version` +- Every design document now lists `README.md` among the core root documents + +### Removed +- `Zscaler/NODE_EXTRA_CA_CERTS.md`, superseded by `ZSCALER_CERTIFICATE.md` + +## 0.2.0 — 2026-06-24 + +### Added +- `Godot/DESIGN_DOCUMENT_GODOT.md` — Godot development guidelines (v1) + +## 0.1.0 — 2026-05-25 + +### Added +- `Rust/DESIGN_DOCUMENT.md` and `Rust/DESIGN_DOCUMENT_LIB.md` — Rust guidelines for applications and libraries (v1) +- `Claude/` — `CLAUDE.md`, `AGENTS.md` (v4) and the custom skills `changelog`, `check`, `commit`, `context`, `documentation` +- `Python/` — `DESIGN_DOCUMENT.md` (v8), `DESIGN_DOCUMENT_MODULE.md` (v1), `TEMPLATE.md`, and the reference `constants.py` module with tests +- `Project template/` — `PROJECT.md` and `CHANGELOG.md` templates + +### Changed +- Documentation organised into topic folders: `Claude/`, `Python/`, `Zscaler/`, `Project template/` +- `README.md` rewritten to describe the repository itself instead of a single project diff --git a/Claude/AGENTS.md b/Claude/AGENTS.md index 7d940a0..053c8a8 100644 --- a/Claude/AGENTS.md +++ b/Claude/AGENTS.md @@ -1,6 +1,6 @@ # AI Agents - Project Rules -**Document Version:** v5 (independent, incremented on structural changes) +**Document Version:** v6 (independent, incremented on structural changes) Language-agnostic rules for AI assistants (Claude Code, Cursor, Copilot, etc.). @@ -68,6 +68,13 @@ Where this file and a design document disagree, **the design document wins**. - **Never commit shared documentation** (`AGENTS.md`, `DESIGN_DOCUMENT*.md`) — it comes from the documentation repository, not from the project - `README.md`, `PROJECT.md` and `CHANGELOG.md` **are committed** — they are project-specific +### Commit messages + +- **Never sign commits with AI authorship** — no `Co-Authored-By: Claude` (or any other assistant), no "Generated with …" line, no tool name or emoji footer. The same applies to pull request descriptions and issue comments. +- The commit author is the human running the tool; the message describes the change, nothing else +- Single-line verbal style — "Add X", "Fix Y", "Refactor Z" — never a filename-style message +- Written in English + ## Versioning - Follow semantic versioning (MAJOR.MINOR.PATCH) diff --git a/Claude/CLAUDE.md b/Claude/CLAUDE.md index 303b099..1972560 100644 --- a/Claude/CLAUDE.md +++ b/Claude/CLAUDE.md @@ -1,10 +1,12 @@ +# CLAUDE.md ## First-time setup **At the start of every new session, read all of the following files before doing anything else:** - `CLAUDE.md` (this file) +- `README.md` - `AGENTS.md` - `PROJECT.md` - `CHANGELOG.md` -- `DESIGN_DOCUMENT*.md` (`DESIGN_DOCUMENT.md`, `DESIGN_DOCUMENT_MODULE.md`, `DESIGN_DOCUMENT_LIB.md` or `DESIGN_DOCUMENT_GODOT.md`) \ No newline at end of file +- `DESIGN_DOCUMENT*.md` (`DESIGN_DOCUMENT.md`, `DESIGN_DOCUMENT_MODULE.md`, `DESIGN_DOCUMENT_LIB.md` or `DESIGN_DOCUMENT_GODOT.md`) diff --git a/Claude/skills/changelog/SKILL.md b/Claude/skills/changelog/SKILL.md index 2eef8aa..b80c1b3 100644 --- a/Claude/skills/changelog/SKILL.md +++ b/Claude/skills/changelog/SKILL.md @@ -1,6 +1,8 @@ --- name: changelog description: Updates changelog in project +metadata: + version: v2 --- Take known info and make changes to CHANGELOG.md to make them up-to-date. diff --git a/Claude/skills/check/SKILL.md b/Claude/skills/check/SKILL.md index db1395f..a273102 100644 --- a/Claude/skills/check/SKILL.md +++ b/Claude/skills/check/SKILL.md @@ -1,5 +1,7 @@ --- name: check description: Check for failed tests +metadata: + version: v1 --- Try running tests and investigate failed results \ No newline at end of file diff --git a/Claude/skills/commit/SKILL.md b/Claude/skills/commit/SKILL.md index 9f5fa14..943735d 100644 --- a/Claude/skills/commit/SKILL.md +++ b/Claude/skills/commit/SKILL.md @@ -1,6 +1,8 @@ --- name: commit description: Updates changelog and proposes a concise verbal git commit message +metadata: + version: v2 --- 1. Run the changelog skill: read git log and staged changes, then update CHANGELOG.md accordingly (same as /changelog). @@ -9,4 +11,5 @@ description: Updates changelog and proposes a concise verbal git commit message - Concise, verbal style — e.g. "Add X", "Fix Y", "Refactor Z" - NOT filename-style — never "update_something.py" or "changes to foo" - In English + - **No AI authorship** — never append `Co-Authored-By: Claude`, a "Generated with …" line, or any tool signature or emoji footer. The same applies to pull request descriptions. - Do NOT run git commit — only propose the message and wait for user confirmation. diff --git a/Claude/skills/documentation/SKILL.md b/Claude/skills/documentation/SKILL.md index 6818979..81a54cf 100644 --- a/Claude/skills/documentation/SKILL.md +++ b/Claude/skills/documentation/SKILL.md @@ -1,5 +1,7 @@ --- name: documentation description: Updates documentation in project +metadata: + version: v1 --- Create or update documentation of project in docs/ folder. Documentation should contain description of each part of program and documentation of each function. Separate documents for each module. Write in markdown format. \ No newline at end of file diff --git a/Claude/skills/context/SKILL.md b/Claude/skills/documentation_context/SKILL.md similarity index 96% rename from Claude/skills/context/SKILL.md rename to Claude/skills/documentation_context/SKILL.md index 980ec44..538e681 100644 --- a/Claude/skills/context/SKILL.md +++ b/Claude/skills/documentation_context/SKILL.md @@ -1,6 +1,8 @@ --- -name: context +name: documentation_context description: Compress docs/ into CONTEXT.md at project root — minimum tokens, lossless +metadata: + version: v2 --- Read every `.md` file in `docs/`. Generate `CONTEXT.md` at the project root. diff --git a/Godot/DESIGN_DOCUMENT_GODOT.md b/Godot/DESIGN_DOCUMENT_GODOT.md index c716df7..f9005a5 100644 --- a/Godot/DESIGN_DOCUMENT_GODOT.md +++ b/Godot/DESIGN_DOCUMENT_GODOT.md @@ -1,6 +1,6 @@ # Godot Development Guidelines -**Document Version:** v1 +**Document Version:** v2 > **Note on Versioning:** > - This document version is independent — reused across Godot projects @@ -90,7 +90,7 @@ Use a dedicated `Log` autoload that wraps `print`/`push_warning`/`push_error` wi The file sink retains **max 10 log files**. Each run creates a new file via the timestamp in the filename. -The `DEBUG` sink is only active when `Constants.DEBUG` is `true` (controlled by an `ENV_DEBUG` value read at startup, e.g. from a `user://settings.cfg` or an export feature tag). +The `DEBUG` sink is only active when `Constants.DEFAULT_DEBUG` is `true` (controlled by an `ENV_DEBUG` value read at startup, e.g. from a `user://settings.cfg` or an export feature tag). Additional sinks (e.g. an in-game debug overlay / console panel) may be added per project. @@ -112,7 +112,7 @@ Additional sinks (e.g. an in-game debug overlay / console panel) may be added pe ## 7. Settings and Secrets - Store user/runtime config in `user://settings.cfg` via `ConfigFile` -- Toggle debug behaviour with an `ENV_DEBUG`-style flag read at startup into `Constants.DEBUG` +- Toggle debug behaviour with an `ENV_DEBUG`-style flag read at startup into `Constants.DEFAULT_DEBUG` - Never commit any secrets; keep them out of `project.godot` and committed `.tres`/`.cfg` files --- @@ -191,7 +191,7 @@ When the game is distributed as a standalone build: godot --headless --export-release "Windows Desktop" build/Game.exe ``` - Compiled builds are stored in `build/` (or `dist/`). Decide per project whether builds are committed — for small internal distribution the repository may serve as the channel; otherwise keep `build/` in `.gitignore` -- Strip debug-only nodes and disable `Constants.DEBUG` in release presets +- Strip debug-only nodes and disable `Constants.DEFAULT_DEBUG` in release presets > This section applies only to projects that produce shippable builds. diff --git a/Project template/CHANGELOG.md b/Project template/CHANGELOG.md index 7cb4fc0..6b2ac05 100644 --- a/Project template/CHANGELOG.md +++ b/Project template/CHANGELOG.md @@ -16,5 +16,5 @@ Each version entry uses these sections (include only those that apply): - Follow semantic versioning: `MAJOR.MINOR.PATCH` - Newest version goes at the top -- Always update this file before bumping the version in `pyproject.toml` +- Always update this file before bumping the version in the project manifest (`pyproject.toml`, `Cargo.toml`, `project.godot`) - Document changes as they are made, not all at once at release time diff --git a/Python/DESIGN_DOCUMENT.md b/Python/DESIGN_DOCUMENT.md index 604af96..693aeba 100644 --- a/Python/DESIGN_DOCUMENT.md +++ b/Python/DESIGN_DOCUMENT.md @@ -1,6 +1,6 @@ # Python Development Guidelines -**Document Version:** v8 +**Document Version:** v9 > **Note on Versioning:** > - This document version is independent — reused across projects diff --git a/Python/DESIGN_DOCUMENT_MODULE.md b/Python/DESIGN_DOCUMENT_MODULE.md index 1906942..4fcfa84 100644 --- a/Python/DESIGN_DOCUMENT_MODULE.md +++ b/Python/DESIGN_DOCUMENT_MODULE.md @@ -1,6 +1,6 @@ # Python Library Development Guidelines -**Document Version:** v1 +**Document Version:** v2 > **Note on Versioning:** > - This document version is independent — reused across projects @@ -127,7 +127,6 @@ Define specific exception types in `src//exceptions.py`. Use a fail-fas - **pytest** only — no `unittest`, no `TestCase` classes, no `self.assert*` - Arrange-Act-Assert pattern - Test naming: `test__` -- Do not commit `poetry.lock` — this is a library; consumers pin their own dependencies --- diff --git a/Python/TEMPLATE.md b/Python/TEMPLATE.md index 57c91a7..f3568f1 100644 --- a/Python/TEMPLATE.md +++ b/Python/TEMPLATE.md @@ -8,12 +8,15 @@ Create a `template/` folder in project root with reusable files for new Python p template/ ├── .env # Environment variables (sample) ├── .gitignore # Git ignore rules -├── AGENTS.md # AI assistant rules ├── CHANGELOG.md # Changelog template -├── DESIGN_DOCUMENT.md # Development guidelines ├── PROJECT.md # Project documentation template -├── main.py # Entry point with loguru +├── README.md # Project overview, tool descriptions, build instructions +├── .py # Entry point — named by purpose or tool name +├── .spec # PyInstaller spec (only for projects shipping an .exe) +├── prebuild.py # Pre-build script: venv check, version print, console= rewrite ├── pyproject.toml # Poetry config (ruff, mypy, pytest) +├── docs/ +│ └── .gitkeep # Detailed documentation lives here, never in the root ├── src/ │ ├── __init__.py │ ├── _version.py # Version fallback for PyInstaller @@ -23,12 +26,16 @@ template/ └── test_constants.py # Basic test ``` +`AGENTS.md` and `DESIGN_DOCUMENT.md` are **not** part of the template — they are copied +into the project root from the documentation repository and are never committed. + ## Key Features - **Version extraction** from `pyproject.toml` with `_version.py` fallback for PyInstaller builds - **DEBUG mode** via `ENV_DEBUG=true` in `.env` (adds "DEV" suffix to version: v1.2.3DEV) -- **loguru** for logging (never print) -- **Poetry** for dependency management +- **Build configuration** via `ENV_BUILD_CONSOLE` and `ENV_BUILD_SPEC` in `.env`, applied by `prebuild.py` +- **loguru** for logging (never print for debugging) +- **Poetry** for dependency management, `poetry.lock` committed - **pytest** for testing (no unittest) - **ruff + mypy** for linting and type checking (120-character lines) @@ -38,3 +45,5 @@ template/ - Generic/reusable format - Keep files simple and minimal - `.gitignore` is the shared core from `Project template/.gitignore` with `Python/.gitignore` appended +- Entry point is named by purpose or tool name — a project may have several +- `prebuild.py` and the `.spec` file are only needed for projects distributed as a standalone `.exe` diff --git a/Python/prebuild.py b/Python/prebuild.py index 7d400b4..83f61e9 100644 --- a/Python/prebuild.py +++ b/Python/prebuild.py @@ -4,10 +4,12 @@ from pathlib import Path from dotenv import load_dotenv -from src.constants import VERSION - +# .env must be loaded before src.constants is imported — constants.py reads ENV_DEBUG +# at import time to build VERSION. load_dotenv() +from src.constants import VERSION # noqa: E402 + print("=" * 50) print("PREBUILD CONFIGURATION") print("=" * 50) diff --git a/README.md b/README.md index 3a3f41f..7077d01 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,11 @@ Dokumentace/ │ ├── CLAUDE.md # Claude Code session instructions │ ├── AGENTS.md # Language-agnostic rules for all AI assistants │ └── skills/ # Custom Claude Code skills +│ ├── changelog/ # /changelog — update CHANGELOG.md +│ ├── check/ # /check — run tests, investigate failures +│ ├── commit/ # /commit — changelog + commit message proposal +│ ├── documentation/ # /documentation — write docs/ +│ └── documentation_context/ # /documentation_context — compress docs/ into CONTEXT.md │ ├── Python/ # Python development guidelines │ ├── DESIGN_DOCUMENT.md # Guidelines for Python applications @@ -38,9 +43,11 @@ Dokumentace/ │ ├── PROJECT.md # Project documentation template │ └── .gitignore # Shared, language-agnostic ignore rules │ -└── Zscaler/ # Corporate network setup - ├── ZSCALER_CERTIFICATE.md # Cert setup for Node, Python, git, cargo - └── ZscalerRootCertificate-2048-SHA256.crt +├── Zscaler/ # Corporate network setup +│ ├── ZSCALER_CERTIFICATE.md # Cert setup for Node, Python, git, cargo +│ └── ZscalerRootCertificate-2048-SHA256.crt +│ +└── CHANGELOG.md # History of this repository ``` ## AI Coding Workflow @@ -62,11 +69,38 @@ Where the two disagree, **the design document wins**. ### Starting a new project -1. Copy `Project template/PROJECT.md` and `Project template/CHANGELOG.md` into the project root — both are committed. +1. Copy `Project template/PROJECT.md` and `Project template/CHANGELOG.md` into the project root and write a `README.md` — all three are committed. 2. Build `.gitignore` from `Project template/.gitignore` plus the `.gitignore` of the matching language folder. 3. Copy `Claude/AGENTS.md` and the matching `DESIGN_DOCUMENT*.md` into the project root — these are **not** committed, they come from here. 4. For Python, follow `Python/TEMPLATE.md` to generate the project skeleton. +### Skills + +The skills in `Claude/skills/` are the source of truth; the copies Claude Code actually runs live in +`~/.claude/skills/`. Install or refresh them by copying the whole folder across. + +Two rules keep the two sides from drifting apart: + +- **The folder name is the command.** For personal skills the frontmatter `name` is only a display + label — `/documentation_context` comes from the directory, not from `name:`. Keep the two identical + so renaming a folder can never silently change the command. +- **Every skill carries a version** in `metadata.version`, incremented on every content change, the + same way design documents carry `Document Version`: + + ```yaml + --- + name: commit + description: Updates changelog and proposes a concise verbal git commit message + metadata: + version: v2 + --- + ``` + + There is no top-level `version:` field in the skill format. `metadata` is a free-form map that + Claude Code ignores, and it is one of the six fields the [Agent Skills](https://agentskills.io) + spec allows — so it also survives an upload to claude.ai or the Skills API. Any other invented + key fails packaging with `Unexpected key(s) in SKILL.md frontmatter`. + ## Key Conventions - **Python tooling:** Poetry · Ruff · mypy · pytest · loguru @@ -74,7 +108,7 @@ Where the two disagree, **the design document wins**. - **Godot tooling:** gdformat · gdlint · GUT - **No `print()` for debugging** — the language's logging library, everywhere - **Static typing required** on every parameter and return value -- **Line length:** 120 characters (Python), 100 soft limit (GDScript) +- **Line length:** 120 characters (Python), 100 characters (Rust, rustfmt default), 100 soft limit (GDScript) - **Tests:** the framework named in the design document — pytest (Python, never `unittest`), built-in `#[test]` (Rust), GUT (Godot) - **Tasks:** single-line `TODO` / `FIXME` / `BUG` / `HACK` / `NOTE` comments in code — no checkboxes in documentation - **Versioning:** semantic, always ask before bumping, `CHANGELOG.md` updated first diff --git a/Rust/DESIGN_DOCUMENT.md b/Rust/DESIGN_DOCUMENT.md index d2f1176..551f12d 100644 --- a/Rust/DESIGN_DOCUMENT.md +++ b/Rust/DESIGN_DOCUMENT.md @@ -1,6 +1,6 @@ # Rust Application Development Guidelines -**Document Version:** v1 +**Document Version:** v2 > **Note on Versioning:** > - This document version is independent — reused across projects @@ -25,6 +25,7 @@ The root directory contains only the core documents: `README.md`, `AGENTS.md`, ` ## 1. Code Style - **Rust edition:** 2024 (requires Rust 1.85 or newer) +- **100-character lines** (rustfmt default `max_width`) - Format with **rustfmt** — run `cargo fmt` before every commit - Lint with **clippy** — run `cargo clippy -- -D warnings` before every commit - **snake_case** functions/variables/modules, **PascalCase** types/traits, **SCREAMING_SNAKE_CASE** constants diff --git a/Rust/DESIGN_DOCUMENT_LIB.md b/Rust/DESIGN_DOCUMENT_LIB.md index 868b513..d1d7322 100644 --- a/Rust/DESIGN_DOCUMENT_LIB.md +++ b/Rust/DESIGN_DOCUMENT_LIB.md @@ -1,6 +1,6 @@ # Rust Library Development Guidelines -**Document Version:** v1 +**Document Version:** v2 > **Note on Versioning:** > - This document version is independent — reused across projects @@ -28,6 +28,7 @@ The root directory contains only the core documents: `README.md`, `AGENTS.md`, ` - **Rust edition:** 2024 (requires Rust 1.85 or newer) - Declare the minimum toolchain in `Cargo.toml` (`rust-version = "1.85"`) so consumers get a clear error instead of a compile failure +- **100-character lines** (rustfmt default `max_width`) - Format with **rustfmt** — run `cargo fmt` before every commit - Lint with **clippy** — run `cargo clippy -- -D warnings` before every commit - **snake_case** functions/variables/modules, **PascalCase** types/traits, **SCREAMING_SNAKE_CASE** constants @@ -169,8 +170,6 @@ mod tests { } ``` -`Cargo.lock` is **not committed** for libraries — add it to `.gitignore`. Consumers pin their own dependency graph. - --- ## 9. Documentation