piker/ai/claude-code/README.md

# 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-name>/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/<timestamp>_<hash>_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/
├── <timestamp>_<hash>_commit_msg.md   # archived
└── git_commit_msg_LATEST.md           # latest
```

Where `<timestamp>` is ISO-8601 with seconds and
`<hash>` 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.