From 0134b94db07a6e084a33e12d3235401f22ba97d8 Mon Sep 17 00:00:00 2001 From: goodboy Date: Thu, 5 Mar 2026 15:30:34 -0500 Subject: [PATCH] Add `ai/` integration docs w/ `/commit-msg` usage Deats, - top-level `ai/README.md` w/ integration table, conventions, and links to PR #69 (origin) + issue #79 (tracking) - `ai/claude-code/README.md` covering all 5 skills (summary table) and full `/commit-msg` usage guide: invocation, `$ARGUMENTS`, output format/files, frontmatter reference, dynamic context explanation (this patch was generated in some part by [`claude-code`][claude-code-gh]) [claude-code-gh]: https://github.com/anthropics/claude-code --- ai/README.md | 50 +++++++++++ ai/claude-code/README.md | 183 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 233 insertions(+) create mode 100644 ai/README.md create mode 100644 ai/claude-code/README.md diff --git a/ai/README.md b/ai/README.md new file mode 100644 index 00000000..17b21894 --- /dev/null +++ b/ai/README.md @@ -0,0 +1,50 @@ +# AI Tooling Integrations + +Documentation and usage guides for AI-assisted +development tools integrated with this repo. + +Each subdirectory corresponds to a specific AI tool +or frontend and contains usage docs for the +custom skills/prompts/workflows configured for it. + +Originally introduced in +[PR #69](https://www.pikers.dev/pikers/piker/pulls/69); +track new integration ideas and proposals in +[issue #79](https://www.pikers.dev/pikers/piker/issues/79). + +## Integrations + +| Tool | Directory | Status | +|------|-----------|--------| +| [Claude Code](https://github.com/anthropics/claude-code) | [`claude-code/`](claude-code/) | active | + +## Adding a New Integration + +Create a subdirectory named after the tool (use +lowercase + hyphens), then add: + +1. A `README.md` covering setup, available + skills/commands, and usage examples +2. Any tool-specific config or prompt files + +``` +ai/ +├── README.md # <- you are here +├── claude-code/ +│ └── README.md +├── opencode/ # future +│ └── README.md +└── / + └── README.md +``` + +## Conventions + +- Skill/command names use **hyphen-case** + (`commit-msg`, not `commit_msg`) +- Each integration doc should describe **what** + the skill does, **how** to invoke it, and any + **output** artifacts it produces +- Keep docs concise; link to the actual skill + source files (under `.claude/skills/`, etc.) + rather than duplicating content diff --git a/ai/claude-code/README.md b/ai/claude-code/README.md new file mode 100644 index 00000000..7dd10dd0 --- /dev/null +++ b/ai/claude-code/README.md @@ -0,0 +1,183 @@ +# Claude Code Integration + +[Claude Code](https://github.com/anthropics/claude-code) +skills and workflows for piker development. + +## Skills + +| Skill | Invocable | Description | +|-------|-----------|-------------| +| [`commit-msg`](#commit-msg) | `/commit-msg` | Generate piker-style commit messages | +| `piker-profiling` | auto | `Profiler` API patterns for perf work | +| `piker-slang` | auto | Communication style + slang guide | +| `pyqtgraph-optimization` | auto | Batch rendering patterns | +| `timeseries-optimization` | auto | NumPy/Polars perf patterns | + +Skills marked **auto** are background knowledge +applied automatically when Claude detects relevance. +Only `commit-msg` is user-invoked via slash command. + +Skill source files live under +`.claude/skills//SKILL.md`. + +--- + +## `/commit-msg` + +Generate piker-style git commit messages trained on +500+ commits from the repo history. + +### Quick Start + +``` +# basic - analyzes staged diff automatically +/commit-msg + +# with scope hint +/commit-msg .ib.feed: fix bar trimming + +# with description context +/commit-msg refactor position tracking +``` + +### What It Does + +1. **Reads staged changes** via dynamic context + injection (`git diff --staged --stat`) +2. **Reads recent commits** for style reference + (`git log --oneline -10`) +3. **Generates** a commit message following + piker conventions (verb choice, backtick refs, + colon prefixes, section markers, etc.) +4. **Writes** the message to two files: + - `.claude/__commit_msg.md` + - `.claude/git_commit_msg_LATEST.md` + (overwritten each time) + +### Arguments + +The optional argument after `/commit-msg` is +passed as `$ARGUMENTS` and used as scope or +description context. Examples: + +| Invocation | Effect | +|------------|--------| +| `/commit-msg` | Infer scope from diff | +| `/commit-msg .ib.feed` | Use `.ib.feed:` prefix | +| `/commit-msg fix the null seg crash` | Use as description hint | + +### Output Format + +**Subject line:** +- ~50 chars target, 67 max +- Present tense verb (Add, Drop, Fix, Factor..) +- Backtick-wrapped code refs +- Optional module prefix (`.ib.feed: ...`) + +**Body** (when needed): +- 67 char line max +- Section markers: `Also,`, `Deats,`, `Further,` +- `-` bullet lists for multiple changes +- Piker abbreviations (`msg`, `mod`, `impl`, + `deps`, `bc`, `obvi`, `prolly`..) + +**Footer** (always): +``` +(this patch was generated in some part by +[`claude-code`][claude-code-gh]) +[claude-code-gh]: https://github.com/anthropics/claude-code +``` + +### Output Files + +After generation, the commit message is written to: + +``` +.claude/ +├── __commit_msg.md # archived +└── git_commit_msg_LATEST.md # latest +``` + +Where `` is ISO-8601 with seconds and +`` is the first 7 chars of the current +`HEAD` commit. + +Use the latest file to feed into `git commit`: + +```bash +git commit -F .claude/git_commit_msg_LATEST.md +``` + +Or review/edit before committing: + +```bash +cat .claude/git_commit_msg_LATEST.md +# edit if needed, then: +git commit -F .claude/git_commit_msg_LATEST.md +``` + +### Examples + +**Simple one-liner output:** +``` +Add `MktPair.fqme` property for symbol resolution +``` + +**Multi-file change output:** +``` +Factor `.claude/skills/` into proper subdirs + +Deats, +- `commit_msg/` -> `commit-msg/` w/ enhanced + frontmatter +- all background skills set `user-invocable: false` +- content split into supporting files + +(this patch was generated in some part by +[`claude-code`][claude-code-gh]) +[claude-code-gh]: https://github.com/anthropics/claude-code +``` + +### Frontmatter Reference + +The skill's `SKILL.md` uses these Claude Code +frontmatter fields: + +```yaml +--- +name: commit-msg +description: > + Generate piker-style git commit messages... +argument-hint: "[optional-scope-or-description]" +disable-model-invocation: true +allowed-tools: + - Bash(git *) + - Read + - Grep + - Glob + - Write +--- +``` + +| Field | Purpose | +|-------|---------| +| `argument-hint` | Shows hint in autocomplete | +| `disable-model-invocation` | Only user can trigger via `/commit-msg` | +| `allowed-tools` | Tools the skill can use | + +### Dynamic Context + +The skill injects live data at invocation time +via `!`backtick`` syntax in the `SKILL.md`: + +```markdown +## Current staged changes +!`git diff --staged --stat` + +## Recent commit style reference +!`git log --oneline -10` +``` + +This means the staged diff stats and recent log +are always fresh when the skill runs -- no stale +context.