piker/ai/claude-code/README.md

# Claude Code Integration

[Claude Code](https://github.com/anthropics/claude-code)
integration for piker's shared coding-harness skills.

## Skills

| Skill | Invocable | Description |
|-------|-----------|-------------|
| [`commit-msg`](#commit-msg) | `/commit-msg` | Generate piker-style commit messages |
| `piker-conc-expert` | auto | Actor-tree and structured-concurrency invariants |
| `piker-profiling` | auto | `Profiler` API patterns for perf work |
| `piker-slang` | auto | Communication style + slang guide |
| `py-codestyle` | auto | Python source conventions |
| `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.

Portable skill source files live under
`.claude/skills/<skill-name>/SKILL.md` and are shared with
OpenCode. Claude-specific behavior belongs in command or
settings files, not the shared skill bodies.

---

## `/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` using `<model>` (`<provider>`))
```

### Output Files

After generation, the commit message is written to:

```
.claude/
├── skills/commit-msg/msgs/
│   └── <timestamp>_<hash>_commit_msg.md
└── 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 with an editor review before commit:

```bash
git commit --edit --file .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,
- use portable Agent Skills frontmatter
- keep harness commands as thin delegates
- share supporting references across harnesses

(this patch was generated in some part by
`claude-code` using `<model>` (`<provider>`))
```

### Shared Frontmatter

Skills use the Agent Skills fields understood by both
Claude Code and OpenCode:

```yaml
---
name: commit-msg
description: >
  Generate piker-style git commit messages. Use when...
compatibility: Requires git.
metadata:
  author: goodboy
  version: "1.0"
---
```

Live git context is gathered by the skill at execution
time. Claude-only dynamic interpolation and tool-policy
frontmatter are intentionally excluded so another harness
can execute the same workflow.