From 20896bfbab24b17c6585aa73a0f4c921bff375e7 Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Sun, 1 Mar 2026 15:46:27 -0500
Subject: [PATCH 1/5] Add `commit-msg` skill + style guide reference

Add a `claude-code` skill for generating commit msgs
matching `tractor`'s style, plus a companion style guide
derived from analysis of 500 repo commits.

Deats,
- `SKILL.md` defines the `commit-msg` skill with YAML
  frontmatter, outlining the generation process, formatting
  rules, and footer conventions.
- `style-guide-reference.md` documents verb frequencies,
  backtick usage patterns, section markers, abbreviations,
  and tone from historical commit analysis.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 .claude/skills/commit-msg/SKILL.md            |  73 ++++++
 .../commit-msg/style-guide-reference.md       | 227 ++++++++++++++++++
 2 files changed, 300 insertions(+)
 create mode 100644 .claude/skills/commit-msg/SKILL.md
 create mode 100644 .claude/skills/commit-msg/style-guide-reference.md

diff --git a/.claude/skills/commit-msg/SKILL.md b/.claude/skills/commit-msg/SKILL.md
new file mode 100644
index 00000000..445eb33a
--- /dev/null
+++ b/.claude/skills/commit-msg/SKILL.md
@@ -0,0 +1,73 @@
+---
+name: commit-msg
+description: Generate git commit messages following project style.
+             Use when user wants to create a commit or asks for a commit message.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+
+When generating commit messages, always follow this process:
+
+1. **Gather context**: Run, `~/repos/claude_wks/commit_gen.py`
+   to get staged changes, recent commits, and style guide rules
+
+2. **Analyze the diff**: Understand what files changed and the nature
+   of the changes (new feature, bug fix, refactor, etc.)
+
+3. **Write the commit message** following these rules:
+
+**Use the accompanying style guide:**
+- Use the style guide `./style-guide-reference.md` for more details
+  on how to write the message based on analysis of past commits in
+  this repo.
+
+**Subject Line Format:**
+- Present tense verbs: Add, Drop, Fix, Use, Move, Adjust, etc.
+- Target 50 chars (hard max: 67)
+- Backticks around ALL code elements (classes, functions, modules, vars)
+- Specific about what changed
+
+**Body Format (optional - keep simple if warranted):**
+- Max 67 char line length
+- Use `-` bullets for lists
+- Section markers: `Also,` `Deats,` `Other,` `Further,`
+- Abbreviations: msg, bg, ctx, impl, mod, obvi, tn, fn, bc, var, prolly
+- Casual yet technically precise tone
+- Never write lines with only whitespace
+
+**Common Opening Patterns:**
+- New features: "Add `feature` to `module`"
+- Removals: "Drop `attr` from `class`"
+- Bug fixes: "Fix `issue` in `function`"
+- Code moves: "Move `thing` to `new_location`"
+- Adoption: "Use `new_tool` for `task`"
+- Minor tweaks: "Adjust `behavior` in `component`"
+
+4. **Write to TWO files**:
+   - `.claude/<timestamp>_<hash>_commit_msg.md` (timestamp from `date
+     --iso-8601=seconds`, hash from `git log -1 --format=%h` first
+     7 chars)
+   - `.claude/git_commit_msg_LATEST.md` (overwrite)
+
+5. **Always include credit footer**:
+
+When no part of the patch was written by `claude`,
+```
+(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
+
+[claude-code-gh]: https://github.com/anthropics/claude-code
+```
+
+and when some or all of the patch was written by `claude` instead
+use,
+
+```
+(this patch was generated in some part by [`claude-code`][claude-code-gh])
+
+[claude-code-gh]: https://github.com/anthropics/claude-code
+```
+
+Keep it concise. Match the tone of recent commits. For simple
+changes, use subject line only.
diff --git a/.claude/skills/commit-msg/style-guide-reference.md b/.claude/skills/commit-msg/style-guide-reference.md
new file mode 100644
index 00000000..97445d29
--- /dev/null
+++ b/.claude/skills/commit-msg/style-guide-reference.md
@@ -0,0 +1,227 @@
+# Commit Message Style Guide for `tractor`
+
+Analysis based on 500 recent commits from the `tractor` repository.
+
+## Core Principles
+
+Write commit messages that are technically precise yet casual in
+tone. Use abbreviations and informal language while maintaining
+clarity about what changed and why.
+
+## Subject Line Format
+
+### Length and Structure
+- Target: ~49 chars (avg: 48.7, max: 50 preferred)
+- Use backticks around code elements (72.2% of commits)
+- Rarely use colons (5.2%), except for file prefixes
+- End with '?' for uncertain changes (rare: 0.8%)
+- End with '!' for important changes (rare: 2.0%)
+
+### Opening Verbs (Present Tense)
+
+Most common verbs from analysis:
+- `Add` (14.4%) - wholly new features/functionality
+- `Use` (4.4%) - adopt new approach/tool
+- `Drop` (3.6%) - remove code/feature
+- `Fix` (2.4%) - bug fixes
+- `Move`/`Mv` (3.6%) - relocate code
+- `Adjust` (2.0%) - minor tweaks
+- `Update` (1.6%) - enhance existing feature
+- `Bump` (1.2%) - dependency updates
+- `Rename` (1.2%) - identifier changes
+- `Set` (1.2%) - configuration changes
+- `Handle` (1.0%) - add handling logic
+- `Raise` (1.0%) - add error raising
+- `Pass` (0.8%) - pass parameters/values
+- `Support` (0.8%) - add support for something
+- `Hide` (1.4%) - make private/internal
+- `Always` (1.4%) - enforce consistent behavior
+- `Mk` (1.4%) - make/create (abbreviated)
+- `Start` (1.0%) - begin implementation
+
+Other frequent verbs: `More`, `Change`, `Extend`, `Disable`, `Log`,
+`Enable`, `Ensure`, `Expose`, `Allow`
+
+### Backtick Usage
+
+Always use backticks for:
+- Module names: `trio`, `asyncio`, `msgspec`, `greenback`, `stackscope`
+- Class names: `Context`, `Actor`, `Address`, `PldRx`, `SpawnSpec`
+- Method names: `.pause_from_sync()`, `._pause()`, `.cancel()`
+- Function names: `breakpoint()`, `collapse_eg()`, `open_root_actor()`
+- Decorators: `@acm`, `@context`
+- Exceptions: `Cancelled`, `TransportClosed`, `MsgTypeError`
+- Keywords: `finally`, `None`, `False`
+- Variable names: `tn`, `debug_mode`
+- Complex expressions: `trio.Cancelled`, `asyncio.Task`
+
+Most backticked terms in tractor:
+`trio`, `asyncio`, `Context`, `.pause_from_sync()`, `tn`,
+`._pause()`, `breakpoint()`, `collapse_eg()`, `Actor`, `@acm`,
+`.cancel()`, `Cancelled`, `open_root_actor()`, `greenback`
+
+### Examples
+
+Good subject lines:
+```
+Add `uds` to `._multiaddr`, tweak typing
+Drop `DebugStatus.shield` attr, add `.req_finished`
+Use `stackscope` for all actor-tree rendered "views"
+Fix `.to_asyncio` inter-task-cancellation!
+Bump `ruff.toml` to target py313
+Mv `load_module_from_path()` to new `._code_load` submod
+Always use `tuple`-cast for singleton parent addrs
+```
+
+## Body Format
+
+### General Structure
+- 43.2% of commits have no body (simple changes)
+- Use blank line after subject
+- Max line length: 67 chars
+- Use `-` bullets for lists (28.0% of commits)
+- Rarely use `*` bullets (2.4%)
+
+### Section Markers
+
+Use these markers to organize longer commit bodies:
+- `Also,` (most common: 26 occurrences)
+- `Other,` (13 occurrences)
+- `Deats,` (11 occurrences) - for implementation details
+- `Further,` (7 occurrences)
+- `TODO,` (3 occurrences)
+- `Impl details,` (2 occurrences)
+- `Notes,` (1 occurrence)
+
+### Common Abbreviations
+
+Use these freely (sorted by frequency):
+- `msg` (63) - message
+- `bg` (37) - background
+- `ctx` (30) - context
+- `impl` (27) - implementation
+- `mod` (26) - module
+- `obvi` (17) - obviously
+- `tn` (16) - task name
+- `fn` (15) - function
+- `vs` (15) - versus
+- `bc` (14) - because
+- `var` (14) - variable
+- `prolly` (9) - probably
+- `ep` (6) - entry point
+- `OW` (5) - otherwise
+- `rn` (4) - right now
+- `sig` (4) - signal/signature
+- `deps` (3) - dependencies
+- `iface` (2) - interface
+- `subproc` (2) - subprocess
+- `tho` (2) - though
+- `ofc` (2) - of course
+
+### Tone and Style
+
+- Casual but technical (use `XD` for humor: 23 times)
+- Use `..` for trailing thoughts (108 occurrences)
+- Use `Woops,` to acknowledge mistakes (4 subject lines)
+- Don't be afraid to show personality while being precise
+
+### Example Bodies
+
+Simple with bullets:
+```
+Add `multiaddr` and bump up some deps
+
+Since we're planning to use it for (discovery)
+addressing, allowing replacement of the hacky (pretend)
+attempt in `tractor._multiaddr` Bp
+
+Also pin some deps,
+- make us py312+
+- use `pdbp` with my frame indexing fix.
+- mv to latest `xonsh` for fancy cmd/suggestion injections.
+
+Bump lock file to match obvi!
+```
+
+With section markers:
+```
+Use `stackscope` for all actor-tree rendered "views"
+
+Instead of the (much more) limited and hacky `.devx._code`
+impls, move to using the new `.devx._stackscope` API which
+wraps the `stackscope` project.
+
+Deats,
+- make new `stackscope.extract_stack()` wrapper
+- port over frame-descing to `_stackscope.pformat_stack()`
+- move `PdbREPL` to use `stackscope` render approach
+- update tests for new stack output format
+
+Also,
+- tweak log formatting for consistency
+- add typing hints throughout
+```
+
+## Special Patterns
+
+### WIP Commits
+Rare (0.2%) - avoid committing WIP if possible
+
+### Merge Commits
+Auto-generated (4.4%), don't worry about style
+
+### File References
+- Use `module.py` or `.submodule` style
+- Rarely use `file.py:line` references (0 in analysis)
+
+### Links
+- GitHub links used sparingly (3 total)
+- Prefer code references over external links
+
+## Footer
+
+The default footer should credit `claude` (you) for helping generate
+the commit msg content:
+
+```
+(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
+
+[claude-code-gh]: https://github.com/anthropics/claude-code
+```
+
+Further, if the patch was solely or in part written by `claude`, instead
+add:
+
+```
+(this patch was generated in some part by [`claude-code`][claude-code-gh])
+
+[claude-code-gh]: https://github.com/anthropics/claude-code
+```
+
+## Summary Checklist
+
+Before committing, verify:
+- [ ] Subject line uses present tense verb
+- [ ] Subject line ~50 chars (hard max 67)
+- [ ] Code elements wrapped in backticks
+- [ ] Body lines ≤67 chars
+- [ ] Abbreviations used where natural
+- [ ] Casual yet precise tone
+- [ ] Section markers if body >3 paragraphs
+- [ ] Technical accuracy maintained
+
+## Analysis Metadata
+
+```
+Source: tractor repository
+Commits analyzed: 500
+Date range: 2019-2025
+Analysis date: 2026-02-08
+```
+
+---
+
+(this style guide was generated by [`claude-code`][claude-code-gh]
+analyzing commit history)
+
+[claude-code-gh]: https://github.com/anthropics/claude-code

From d4f2fa547ab757b0e075e255ec609f8235da54e4 Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Sun, 1 Mar 2026 17:46:03 -0500
Subject: [PATCH 2/5] Extend `.gitignore` for dev/gen artifacts

Add ignore rules for commit-msg gen tmp files, nix dev
profiles, vim sessions, macOS metadata, gitea local docs,
and private LLM conversation logs.

(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 .gitignore | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/.gitignore b/.gitignore
index 894a44cc..61a677df 100644
--- a/.gitignore
+++ b/.gitignore
@@ -102,3 +102,27 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# all files under
+.git/
+
+# any commit-msg gen tmp files
+.claude/*_commit_*.md
+.claude/*_commit*.toml
+
+# nix develop --profile .nixdev
+.nixdev*
+
+# :Obsession .
+Session.vim
+# gitea local `.md`-files
+# TODO? would this be handy to also commit and sync with
+# wtv git hosting service tho?
+gitea/
+
+# ------ macOS ------
+# Finder metadata
+**/.DS_Store
+
+# LLM conversations that should remain private
+docs/conversations/

From c5ea6040bf720c12397a0ad3825db7c58558d85e Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Wed, 4 Mar 2026 14:36:00 -0500
Subject: [PATCH 3/5] Improve `/commit-msg` skill fmting + consistency

Align `SKILL.md` and `style-guide-reference.md` with the
claude-code skills docs and actual usage conventions.

Deats,
- add missing frontmatter fields: `argument-hint`,
  `disable-model-invocation`, and scope `Bash` tool to
  `Bash(git *)` prefix pattern per docs.
- add `Grep`/`Glob` to `allowed-tools`.
- restructure `!`backtick`` usage for proper dynamic
  context injection (not mixed with instructional text).
- use markdown link for `style-guide-reference.md` ref
  per docs' supporting-files convention.
- switch timestamp format to cross-OS-safe
  `date -u +%Y%m%dT%H%M%SZ`.

Also,
- rm errant blank lines between footer attribution and
  reference-def lines in both files.
- fix double space in style guide subject length desc.
- reflow long lines for 67 char limit.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 .claude/skills/commit-msg/SKILL.md            | 47 ++++++++++++-------
 .../commit-msg/style-guide-reference.md       |  8 ++--
 2 files changed, 33 insertions(+), 22 deletions(-)

diff --git a/.claude/skills/commit-msg/SKILL.md b/.claude/skills/commit-msg/SKILL.md
index 445eb33a..98741952 100644
--- a/.claude/skills/commit-msg/SKILL.md
+++ b/.claude/skills/commit-msg/SKILL.md
@@ -1,27 +1,41 @@
 ---
 name: commit-msg
-description: Generate git commit messages following project style.
-             Use when user wants to create a commit or asks for a commit message.
+description: >
+  Generate git commit messages following project style. Use when user
+  wants to create a commit or asks for a commit message.
+argument-hint: "[optional-scope-or-description]"
+disable-model-invocation: true
 allowed-tools:
-  - Bash
+  - Bash(git *)
+  - Bash(date *)
+  - Bash(cp *)
   - Read
+  - Grep
+  - Glob
   - Write
 ---
 
 When generating commit messages, always follow this process:
 
-1. **Gather context**: Run, `~/repos/claude_wks/commit_gen.py`
-   to get staged changes, recent commits, and style guide rules
+0. **Check for staged changes**: if `git diff --staged` is
+   empty, STOP and tell the user "nothing is staged!" with
+   a reminder to `git add` before invoking this skill.
 
-2. **Analyze the diff**: Understand what files changed and the nature
-   of the changes (new feature, bug fix, refactor, etc.)
+1. **Gather context** from the staged diff and recent
+   history:
+
+   - Staged changes: !`git diff --staged --stat`
+   - Recent commits: !`git log --oneline -5`
+
+2. **Analyze the diff**: understand what files changed and
+   the nature of the changes (new feature, bug fix, refactor,
+   etc.)
 
 3. **Write the commit message** following these rules:
 
 **Use the accompanying style guide:**
-- Use the style guide `./style-guide-reference.md` for more details
-  on how to write the message based on analysis of past commits in
-  this repo.
+- See [style-guide-reference.md](style-guide-reference.md)
+  for detailed analysis of past commits in this repo.
 
 **Subject Line Format:**
 - Present tense verbs: Add, Drop, Fix, Use, Move, Adjust, etc.
@@ -46,9 +60,10 @@ When generating commit messages, always follow this process:
 - Minor tweaks: "Adjust `behavior` in `component`"
 
 4. **Write to TWO files**:
-   - `.claude/<timestamp>_<hash>_commit_msg.md` (timestamp from `date
-     --iso-8601=seconds`, hash from `git log -1 --format=%h` first
-     7 chars)
+   - `.claude/<timestamp>_<hash>_commit_msg.md`
+     * with `<timestamp>` from `date -u +%Y%m%dT%H%M%SZ` or similar
+       filesystem-safe format.
+     * and `<hash>` from `git log -1 --format=%h` first 7 chars.
    - `.claude/git_commit_msg_LATEST.md` (overwrite)
 
 5. **Always include credit footer**:
@@ -56,16 +71,14 @@ When generating commit messages, always follow this process:
 When no part of the patch was written by `claude`,
 ```
 (this commit msg was generated in some part by [`claude-code`][claude-code-gh])
-
 [claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
-and when some or all of the patch was written by `claude` instead
-use,
+when some or all of the patch was written by `claude`
+instead use,
 
 ```
 (this patch was generated in some part by [`claude-code`][claude-code-gh])
-
 [claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
diff --git a/.claude/skills/commit-msg/style-guide-reference.md b/.claude/skills/commit-msg/style-guide-reference.md
index 97445d29..3c9fe180 100644
--- a/.claude/skills/commit-msg/style-guide-reference.md
+++ b/.claude/skills/commit-msg/style-guide-reference.md
@@ -11,7 +11,7 @@ clarity about what changed and why.
 ## Subject Line Format
 
 ### Length and Structure
-- Target: ~49 chars (avg: 48.7, max: 50 preferred)
+- Target: ~50 chars with a hard-max of 67.
 - Use backticks around code elements (72.2% of commits)
 - Rarely use colons (5.2%), except for file prefixes
 - End with '?' for uncertain changes (rare: 0.8%)
@@ -185,16 +185,14 @@ the commit msg content:
 
 ```
 (this commit msg was generated in some part by [`claude-code`][claude-code-gh])
-
 [claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 
-Further, if the patch was solely or in part written by `claude`, instead
-add:
+Further, if the patch was solely or in part written
+by `claude`, instead add:
 
 ```
 (this patch was generated in some part by [`claude-code`][claude-code-gh])
-
 [claude-code-gh]: https://github.com/anthropics/claude-code
 ```
 

From c735fc85447c66d61bad9f073d879595e4c0b631 Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Wed, 4 Mar 2026 16:04:30 -0500
Subject: [PATCH 4/5] Update `.gitignore` for `gish` local files

Rename `gitea/` comment to `gish`, add `gh/` ignore, and
expand TODOs about syncing with git hosting services.
Also mute any `.claude/*_commit*.txt` files.

(this commit msg was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 .gitignore | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/.gitignore b/.gitignore
index 61a677df..1d5e994d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -109,16 +109,19 @@ venv.bak/
 # any commit-msg gen tmp files
 .claude/*_commit_*.md
 .claude/*_commit*.toml
+.claude/*_commit*.txt
 
 # nix develop --profile .nixdev
 .nixdev*
 
 # :Obsession .
 Session.vim
-# gitea local `.md`-files
-# TODO? would this be handy to also commit and sync with
-# wtv git hosting service tho?
+# `gish` local `.md`-files
+# TODO? better all around automation!
+# -[ ] it'd be handy to also commit and sync with wtv git service?
+# -[ ] everything should be put under a `.gish/` no?
 gitea/
+gh/
 
 # ------ macOS ------
 # Finder metadata

From 1704f73504f8ab55813734a440503b7ac1536476 Mon Sep 17 00:00:00 2001
From: goodboy <goodboy_foss@protonmail.com>
Date: Wed, 4 Mar 2026 16:09:37 -0500
Subject: [PATCH 5/5] Add local `claude` settings for commit-msg perms

Auto-allow the tool calls used by the `/commit-msg` skill
so the workflow requires minimal user prompting.

(this patch was generated in some part by [`claude-code`][claude-code-gh])
[claude-code-gh]: https://github.com/anthropics/claude-code
---
 .claude/settings.local.json | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 .claude/settings.local.json

diff --git a/.claude/settings.local.json b/.claude/settings.local.json
new file mode 100644
index 00000000..d2c8f9d9
--- /dev/null
+++ b/.claude/settings.local.json
@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Write(.claude/*commit_msg*)",
+      "Write(.claude/git_commit_msg_LATEST.md)",
+      "Bash(date *)",
+      "Bash(cp .claude/*)",
+      "Bash(git diff *)",
+      "Bash(git log *)",
+      "Bash(git status)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}