From e4f830abf8c819f4511f2ebc9c153e9cd0236b17 Mon Sep 17 00:00:00 2001 From: Gavin Staniforth Date: Sun, 30 Aug 2026 21:07:47 +0100 Subject: [PATCH 1/2] feat: add planning and code-comment preferences --- Makefile | 2 +- README.md | 3 +- code-comments.md | 45 +++++++++++++++++++ .../specs/2026-08-30-agent-dotfiles-design.md | 2 + planning.md | 42 +++++++++++++++++ tests/apply.bats | 8 ++++ 6 files changed, 100 insertions(+), 2 deletions(-) create mode 100644 code-comments.md create mode 100644 planning.md diff --git a/Makefile b/Makefile index 1f87b14..075185f 100644 --- a/Makefile +++ b/Makefile @@ -1,7 +1,7 @@ REPO_ROOT := $(abspath $(dir $(lastword $(MAKEFILE_LIST)))) DEST_HOME ?= $(HOME) AGENTS_FILE ?= $(REPO_ROOT)/.agents/AGENTS.md -TOPIC_FILES := commits.md task-starting.md +TOPIC_FILES := commits.md task-starting.md planning.md code-comments.md .PHONY: apply test diff --git a/README.md b/README.md index c6266d8..7c3cc38 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,8 @@ The repository keeps topics as separate files and the Makefile's ordered / ├── commits.md ├── task-starting.md -└── ... +├── planning.md +└── code-comments.md $HOME/.claude/CLAUDE.md └── @/.md diff --git a/code-comments.md b/code-comments.md new file mode 100644 index 0000000..88f5ce0 --- /dev/null +++ b/code-comments.md @@ -0,0 +1,45 @@ +# Code comments + +Code should explain itself. When something genuinely needs explaining, prefer +a documentation block attached to a structure over comments scattered through +the code. + +## Prefer doc blocks over inline comments + +Attach explanations to the file, class, function, or method using the +language's documentation convention (JSDoc/TSDoc, docstrings, rustdoc, PHPDoc, +GoDoc, XML doc comments, …): + +- **File/module block** — why the module exists and how it fits into the + wider system. +- **Class block** — the responsibility of the class and how it's meant to be + used. +- **Function/method block** — behaviour, parameters, return values, and any + caveats that matter to callers. + +Doc blocks live at a stable, discoverable anchor — IDE hover, generated docs, +the top of the unit. Keeping the explanation attached to the unit makes it +easier to find and less likely to drift than a detached inline comment. + +## Keep code bodies lean + +Avoid verbosity inside the code itself: + +- Don't narrate what the next line does; the code already says it. +- Don't record change history or justify an edit in a comment — that belongs + in the commit message or PR description. +- No commented-out code. Delete it; git remembers. +- If a body needs running commentary to be understood, refactor instead: + extract a well-named function and document *that* with a block. + +An inline comment is justified only for a constraint the code cannot express: +a non-obvious invariant, a workaround (with a link to the upstream issue), or +a deliberate deviation from the approach a reader would expect. + +## Exception: YAML + +YAML (CI pipelines, Kubernetes manifests, docker-compose, …) has no doc-block +construct and little naming to lean on — comments are its only documentation +mechanism. Comment YAML as generously as needed: non-obvious keys, magic +values, and why settings are set the way they are. The same applies to other +comment-only config formats. diff --git a/docs/superpowers/specs/2026-08-30-agent-dotfiles-design.md b/docs/superpowers/specs/2026-08-30-agent-dotfiles-design.md index b01116e..5a4e3a8 100644 --- a/docs/superpowers/specs/2026-08-30-agent-dotfiles-design.md +++ b/docs/superpowers/specs/2026-08-30-agent-dotfiles-design.md @@ -13,6 +13,8 @@ The root topic files remain canonical and ordered explicitly in the Makefile: 1. `commits.md` 2. `task-starting.md` +3. `planning.md` +4. `code-comments.md` Claude continues to use its native `@`-import syntax. `make apply` renders `~/.claude/CLAUDE.md` with absolute imports for each topic file. This wrapper diff --git a/planning.md b/planning.md new file mode 100644 index 0000000..e19926a --- /dev/null +++ b/planning.md @@ -0,0 +1,42 @@ +# Planning + +Where plans live determines whether they belong in a PR. + +## Local plans stay local + +Plans written outside the repository working tree — for example in +`~/.claude/`, `~/plans/`, or scratch files in `/tmp` — are **local-only +context**. They exist to help the current session think; they are not +artifacts of the project. + +- **Never** reference, link to, paste excerpts from, or quote these local + plans in a GitHub PR description, commit message, code comment, or + review reply. Reviewers cannot open them, they are not versioned with + the code, and the paths are personal to one machine. +- The PR description should stand on its own: summarise the change, the + motivation, and the test plan inline. + +## Critical plans go in the repo + +When the *plan itself* is load-bearing — a multi-phase migration, an +architectural decision, a staged rollout, anything future contributors +will need to understand the shape of the work — put it in the repository's +established planning or design location. If the project has no convention, +use `docs/plans/` (create the directory if it doesn't exist). + +- Commit the plan alongside the code that implements it (or in a + preceding commit on the same branch). +- Then it's fine — and encouraged — to link to its repository-relative path + from the PR description, commit body, or code comments. It's part of the + repo, so the link is durable and reviewable. + +## How to decide + +Ask: *would a reviewer or a future contributor need this plan to +understand or maintain the change?* + +- Yes → write it into the repo's established location (or `docs/plans/` + when none exists) and reference it freely. +- No → keep it local and don't mention its path anywhere that ships. + +Project-level instructions may override this. diff --git a/tests/apply.bats b/tests/apply.bats index d782c8b..1d630c6 100644 --- a/tests/apply.bats +++ b/tests/apply.bats @@ -40,6 +40,8 @@ expected_claude() { printf '%s\n\n' 'Each topic is imported from the agent-dotfiles repository.' printf '@%s/commits.md\n' "$active_repo" printf '@%s/task-starting.md\n' "$active_repo" + printf '@%s/planning.md\n' "$active_repo" + printf '@%s/code-comments.md\n' "$active_repo" } expected_agents() { @@ -49,6 +51,10 @@ expected_agents() { printf '\n' cat "$active_repo/task-starting.md" printf '\n' + cat "$active_repo/planning.md" + printf '\n' + cat "$active_repo/code-comments.md" + printf '\n' } make_fixture_repo() { @@ -58,6 +64,8 @@ make_fixture_repo() { cp "$repo_root/scripts/apply.sh" "$active_repo/scripts/apply.sh" cp "$repo_root/commits.md" "$active_repo/commits.md" cp "$repo_root/task-starting.md" "$active_repo/task-starting.md" + cp "$repo_root/planning.md" "$active_repo/planning.md" + cp "$repo_root/code-comments.md" "$active_repo/code-comments.md" } @test "fresh apply renders ordered documents and an absolute Codex symlink" { From 86754af7e45ff6cb12c3925f7af0e155a051b32c Mon Sep 17 00:00:00 2001 From: Gavin Staniforth Date: Sun, 30 Aug 2026 21:07:54 +0100 Subject: [PATCH 2/2] feat(commits): require BREAKING CHANGE footer --- commits.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/commits.md b/commits.md index 1993067..2e9e3f2 100644 --- a/commits.md +++ b/commits.md @@ -5,12 +5,18 @@ Always use Conventional Commits / semantic commit format for any commit you auth - Format: `type(scope): subject` — scope optional, subject in imperative mood, no trailing period. - Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `revert`. - **Do not use `chore`** — pick a more specific type. If nothing else fits, prefer `refactor`, `build`, or `ci` based on what the change actually touches. -- Use `!` after type/scope or a `BREAKING CHANGE:` footer for breaking changes. +- Mark breaking changes with a `BREAKING CHANGE:` footer only — never use `!` after the type/scope. - Keep the subject ≤72 characters; put detail in the body separated by a blank line. - Examples: - `feat(auth): add refresh-token rotation` - `fix: handle empty response from billing API` - - `refactor(parser)!: drop legacy YAML loader` + - A breaking change: + + ``` + refactor(parser): drop legacy YAML loader + + BREAKING CHANGE: YAML 1.1 documents are no longer accepted. + ``` ## Atomic commits