feat: add planning and code-comment preferences, tighten breaking-change rule

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
 

README.md

@@ -35,7 +35,8 @@ The repository keeps topics as separate files and the Makefile's ordered
 <repository>/
 ├── commits.md
 ├── task-starting.md
-└── ...
+├── planning.md
+└── code-comments.md
 
 $HOME/.claude/CLAUDE.md
 └── @<absolute repository path>/<topic>.md

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.

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
 

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

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.

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" {