Changelog — The Craft

Notable changes to The Craft doctrine. Versioning is semantic (MAJOR.MINOR.PATCH). Entry date = publication day — when the version was deployed to thecraft.jakub.solutions and ready to download.

MAJOR — a rule or chapter reworked or removed (a breaking change to how things were understood). MINOR — a new chapter or a significant new rule. PATCH — a clarification, an example, a fix.

Shared version axis with the Rzemiosło Web site. The rule core and the site share one numbering, so a number skipped here means a site-side release — 1.0.1 and 1.0.2 belonged to Web, so the core goes 1.0.0 → 1.0.3. The gaps are deliberate, not missing.

1.0.3 — 2026-08-24

Lessons from a real reference project, folded into existing chapters in both languages (no change to the chapter list — hence a PATCH). The core: the doctrine is written for one developer working with AI, where “solo” still means several parallel Claude sessions on one repo — and it’s those, not a human team, that force the discipline of coordination.

Added

intro — “Who this is for”. A single developer plus AI as a pair; “solo” already means many writers (parallel agent sessions), so coordination rules matter from the second open session.
05 — coordinating parallel work. Review the diff before merging to the deploy branch, the origin-vs-local trap (a deploy ships origin, so check your push first), a boot-check on the target before reloading, and a full deploy dress rehearsal dev → preprod → prod.
14 §7 — cyclical jobs: watch the effect, not the runner. The Watchdog — An independent monitor that checks by itself whether data is fresh / the app is alive, and alarms when something stalls. For cyclical jobs measure the effect (age of the freshest record), not the job’s exit code — a green report can lie. measures the age of the freshest record per source, not the job’s exit code; a green report only covers what it knows, and scheduler config is production that lives outside the repo.
16 — Plan mode — A mode where the assistant first reads and presents a plan but changes no files — execution comes only after your approval. For wide or hard-to-undo work: you review the decision, not the diff. A good plan also says how you’ll check it worked. (decide the approach before a file changes; the plan is a review artifact) and an isolated git worktree per parallel session (a shared checkout is a shared Index (database) — A lookup in the database that makes searching instant instead of scanning everything in order. The first move for slow queries — like an index at the back of a book instead of reading 400 pages.).
15 — a service answers twice, and the answers can disagree. robots.txt is the owner’s policy; an anti-bot shield is a machine — identify yourself truthfully and ask the owner, don’t engineer a workaround.
03 — a guard proves itself on the incident, not the fixture. Replay a post-mortem check on the real data of that failure before you trust it.
05 — undo: you probably didn’t lose it. A rescue section for the git-shy — six common panics and the way back for each (restore, reset --soft, reflog, ORIG_HEAD), reflog as the repo’s undo button, and the only three commands that actually destroy work (and only the uncommitted kind). Commit early.
06 — the permission map: one table, three columns (do / ask / never). The whole doctrine’s boundary in one place; the wide left column is what makes autopilot safe.
06 — handing off state when context runs out. Ship in commits, not in the conversation; record a decision the moment you make it; durable facts to memory/; git status is the handoff. The test: would the next session pick it up from the repo alone?
00 — deviating from a rule, out loud. The doctrine is a default, not a cage: deviate by naming the rule, justifying it and proposing a replacement — a silent skip is a sin. Precedence: host CLAUDE.md > docs/rules > agent defaults. The floor that doesn’t move: III, V, VI, VII.
04 — absolute paths at tool boundaries (/tmp means different things in Git Bash, Python — A popular, readable programming language — The Craft’s default for scripts, data and the back end. A proven default: lots of ready tools and libraries, easy to drive with AI. and PowerShell) and a rehearsal of a mass data change on a copy of production.
13 — mobile: the viewport is a moving target. 100dvh instead of 100vh, elements above the keyboard anchored to visualViewport, and measuring real DOM geometry instead of trusting the emulator.

Changed

00 — rule zero reframed: read the Decalogue, then grep the topic index — a pointer, not a paste; a vendored copy is not the host project’s constitution.
07 — the [SYSTEM — READ FIRST] note clarified (Decalogue → topic index; pointer, not paste).

1.0.0 — 2026-06-19

The first public release — the complete The Craft doctrine, ready to drop in as docs/rules/ in a new project. From the first commit to production: how to build with Claude so the project stays understandable, safe to change and worthy of trust.

17 chapters in two languages (EN canon + PL — the same chapters, the same anchors): the Decalogue (00) + core (01–08) + depth (09–16) — from documentation, tests, Git and deployments, through law, SEO and the data model, to performance, operational resilience, Scraping — Automatically gathering data from websites with a program instead of copying by hand. Powerful for acquiring data, but it needs manners: respect others’ rules (robots.txt), don’t overload the server./AI and driving Claude.
An HTML reader in the pack — renders the .md files from a double-click (file://), light/dark mode, EN/PL switch.
The website thecraft.jakub.solutions — a friendly wrapper with a download.