From c6ec3d4144f5a139971bfcf3c183abb5822cd996 Mon Sep 17 00:00:00 2001 From: goodboy Date: Tue, 21 Jul 2026 17:09:07 -0400 Subject: [PATCH] Share piker skills across coding harnesses Use portable Agent Skills metadata and one repo-local source for both Claude Code and OpenCode. Deats, - replace harness-only frontmatter and dynamic context - make `commit-msg` runtime-aware and review-first - add a thin OpenCode command and integration docs - guard `np.searchsorted()` guidance before OOB indexing - record OpenCode prompt provenance Prompt-IO: ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md (this patch was generated in some part by `opencode` using `gpt-5.6-sol` (`openai`)) --- .claude/skills/commit-msg/SKILL.md | 131 +++++++++++------- .../commit-msg/style-guide-reference.md | 15 +- .claude/skills/piker-conc-expert/SKILL.md | 7 +- .claude/skills/piker-profiling/SKILL.md | 6 +- .claude/skills/piker-slang/SKILL.md | 6 +- .../skills/pyqtgraph-optimization/SKILL.md | 7 +- .../skills/timeseries-optimization/SKILL.md | 20 ++- .opencode/commands/commit-msg.md | 10 ++ ai/README.md | 19 ++- ai/claude-code/README.md | 84 ++++------- ai/opencode/README.md | 51 +++++++ .../20260721T205228Z_58ffe487_prompt_io.md | 64 +++++++++ ...20260721T205228Z_58ffe487_prompt_io.raw.md | 33 +++++ ai/prompt-io/opencode/README.md | 20 +++ 14 files changed, 347 insertions(+), 126 deletions(-) create mode 100644 .opencode/commands/commit-msg.md create mode 100644 ai/opencode/README.md create mode 100644 ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md create mode 100644 ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.raw.md create mode 100644 ai/prompt-io/opencode/README.md diff --git a/.claude/skills/commit-msg/SKILL.md b/.claude/skills/commit-msg/SKILL.md index 0a9f69c4..0bda9cb0 100644 --- a/.claude/skills/commit-msg/SKILL.md +++ b/.claude/skills/commit-msg/SKILL.md @@ -1,81 +1,116 @@ --- name: commit-msg description: > - Generate piker-style git commit messages from - staged changes or prompt input, following the - style guide learned from 500 repo commits. -argument-hint: "[optional-scope-or-description]" -disable-model-invocation: true -allowed-tools: Bash(git *), Read, Grep, Glob, Write + Generate piker-style git commit messages from staged + changes or prompt input. Use when the user asks for a + commit message or invokes a commit-message command. +compatibility: > + Requires git and a coding harness able to read and + write files in the active checkout. +metadata: + author: goodboy + version: "1.0" --- -## Current staged changes -!`git diff --staged --stat` - -## Recent commit style reference -!`git log --oneline -10` - # Piker Git Commit Message Generator -Generate a commit message from the staged diff above -following the piker project's conventions (learned from -analyzing 500 repo commits). - -If `$ARGUMENTS` is provided, use it as scope or -description context for the commit message. +Generate a commit message from the staged diff following +the piker project's conventions, learned from 500 repo +commits. For the full style guide with verb frequencies, section markers, abbreviations, piker-specific terms, and examples, see [style-guide-reference.md](./style-guide-reference.md). -## Quick Reference +## Safety + +- Never run `git commit`, amend, rebase, merge, or push + unless the user explicitly requests that operation. +- Do not stage or unstage files for a single-message run. +- Never change issue, plan, or checklist state merely + because the related implementation is complete. +- Preserve unrelated worktree changes. + +## Working Context + +1. Run `git rev-parse --show-toplevel`, + `git rev-parse --git-dir`, and + `git rev-parse --git-common-dir`. +2. If the git dir differs from the common dir, report the + active worktree before generating the message. +3. Inspect `git status --short`, the complete staged diff, + `git diff --staged --check`, and recent commit history. +4. If nothing is staged, stop and tell the user. Prompt + text may clarify intent but does not replace a staged + patch unless the user explicitly asks for a draft with + no staged changes. + +## Message Style - **Subject**: ~50 chars, present tense verb, use - backticks for code refs + backticks for code refs; hard maximum 67 columns - **Body**: only for complex/multi-file changes, - 67 char line max + filled close to a 67-column maximum - **Section markers**: Also, / Deats, / Other, - **Bullets**: use `-` style - **Tone**: technical but casual (piker style) -## Claude-code Footer +Use any user-supplied scope or description as context, +but verify it against the staged patch. The message must +describe the complete staged boundary, not only the most +obvious file. -When the written **patch** was assisted by -claude-code, include: +## Provenance + +If staged paths include prompt-I/O log entries under +`ai/prompt-io/`, add one trailer per non-raw log file: ``` -(this patch was generated in some part by [`claude-code`][claude-code-gh]) -[claude-code-gh]: https://github.com/anthropics/claude-code +Prompt-IO: ai/prompt-io//.md ``` -When only the **commit msg** was written by -claude-code (human wrote the patch), use: +When the patch has substantive AI-authored changes but no +prompt-I/O entry is staged, remind the user that repository +policy may require one. Do not block message generation. + +Always identify the active harness and model from runtime +context rather than hardcoding Claude Code or OpenCode. + +When the harness assisted with the patch, append: + ``` -(this commit msg was generated in some part by [`claude-code`][claude-code-gh]) -[claude-code-gh]: https://github.com/anthropics/claude-code +(this patch was generated in some part by `` using `` (``)) ``` -## Output Instructions +When it generated only the message, append: -When generating a commit message: +``` +(this commit msg was generated in some part by `` using `` (``)) +``` -1. Analyze the staged diff (injected above via - dynamic context) to understand all changes. -2. If `$ARGUMENTS` provides a scope (e.g., - `.ib.feed`) or description, incorporate it into - the subject line. -3. Write the subject line following verb + backtick - conventions from the - [style guide](./style-guide-reference.md). -4. Add body only for multi-file or complex changes. -5. Write the message to a file in the repo's - `.claude/` subdir with filename format: - `__commit_msg.md` - where `` is from `date --iso-8601=seconds`. - Also write a copy to - `.claude/git_commit_msg_LATEST.md` - (overwrite if exists). +## Output Files + +Write the final message to both of these paths relative to +the active checkout returned by `git rev-parse +--show-toplevel`: + +- `.claude/skills/commit-msg/msgs/__commit_msg.md` +- `.claude/git_commit_msg_LATEST.md` + +Use UTC `` format `YYYYMMDDTHHMMSSZ` and the +first seven characters of the current `HEAD` hash. Create +the archive directory when needed. The `.claude` path is a +legacy repository artifact location shared by all coding +harnesses; it does not imply which harness generated the +message. + +Finish by reporting both paths and this review-first +command without running it: + +``` +git commit --edit --file .claude/git_commit_msg_LATEST.md +``` --- diff --git a/.claude/skills/commit-msg/style-guide-reference.md b/.claude/skills/commit-msg/style-guide-reference.md index 1e3ba061..0698cc62 100644 --- a/.claude/skills/commit-msg/style-guide-reference.md +++ b/.claude/skills/commit-msg/style-guide-reference.md @@ -150,21 +150,18 @@ Common in piker commits (33.0% use colons): - File:line references not used (0 occurrences) - No WIP commits in analyzed set -### Claude-code Footer -When the written **patch** was assisted by claude-code, -include: +### Coding-harness Footer +When a coding harness assisted with the written patch, +identify the active harness, model, and provider: ``` -(this patch was generated in some part by [`claude-code`][claude-code-gh]) -[claude-code-gh]: https://github.com/anthropics/claude-code +(this patch was generated in some part by `` using `` (``)) ``` -When only the **commit msg** was written by claude-code -(human wrote the patch), use: +When it generated only the commit message, use: ``` -(this commit msg was generated in some part by [`claude-code`][claude-code-gh]) -[claude-code-gh]: https://github.com/anthropics/claude-code +(this commit msg was generated in some part by `` using `` (``)) ``` ## Piker-Specific Terms diff --git a/.claude/skills/piker-conc-expert/SKILL.md b/.claude/skills/piker-conc-expert/SKILL.md index 550087d0..bf471b15 100644 --- a/.claude/skills/piker-conc-expert/SKILL.md +++ b/.claude/skills/piker-conc-expert/SKILL.md @@ -8,7 +8,12 @@ description: > eps), `to_asyncio` integration, cancellation semantics, or debugging hangs/wedges/skews in the actor system. -user-invocable: false +compatibility: > + Requires a piker checkout and familiarity with Python, + trio, and tractor. +metadata: + author: goodboy + version: "1.0" --- # Piker Concurrency & Runtime Expertise diff --git a/.claude/skills/piker-profiling/SKILL.md b/.claude/skills/piker-profiling/SKILL.md index c37c2776..106a27cf 100644 --- a/.claude/skills/piker-profiling/SKILL.md +++ b/.claude/skills/piker-profiling/SKILL.md @@ -5,7 +5,11 @@ description: > across distributed actor systems. Apply when adding profiling, debugging perf regressions, or optimizing hot paths in piker code. -user-invocable: false +compatibility: > + Requires a piker checkout and Python profiling work. +metadata: + author: goodboy + version: "1.0" --- # Piker Profiling Subsystem diff --git a/.claude/skills/piker-slang/SKILL.md b/.claude/skills/piker-slang/SKILL.md index b4ec5936..935475ef 100644 --- a/.claude/skills/piker-slang/SKILL.md +++ b/.claude/skills/piker-slang/SKILL.md @@ -5,7 +5,11 @@ description: > ethos. Apply when communicating with piker devs, writing commit messages, code review comments, or any collaborative interaction. -user-invocable: false +compatibility: > + Harness-independent communication guidance. +metadata: + author: goodboy + version: "1.0" --- # Piker Slang & Communication Style diff --git a/.claude/skills/pyqtgraph-optimization/SKILL.md b/.claude/skills/pyqtgraph-optimization/SKILL.md index 612c01bd..dd3508d3 100644 --- a/.claude/skills/pyqtgraph-optimization/SKILL.md +++ b/.claude/skills/pyqtgraph-optimization/SKILL.md @@ -5,7 +5,12 @@ description: > for piker's UI. Apply when optimizing graphics performance, adding new chart annotations, or working with `QGraphicsItem` subclasses. -user-invocable: false +compatibility: > + Requires a piker checkout with PyQtGraph and Qt source + available for inspection. +metadata: + author: goodboy + version: "1.0" --- # PyQtGraph Rendering Optimization diff --git a/.claude/skills/timeseries-optimization/SKILL.md b/.claude/skills/timeseries-optimization/SKILL.md index 6fcc3321..104bd45a 100644 --- a/.claude/skills/timeseries-optimization/SKILL.md +++ b/.claude/skills/timeseries-optimization/SKILL.md @@ -6,7 +6,12 @@ description: > with OHLCV arrays, timestamp lookups, gap detection, or any array/dataframe operations in piker. -user-invocable: false +compatibility: > + Requires a piker checkout with NumPy and optionally + Polars. +metadata: + author: goodboy + version: "1.0" --- # Timeseries Optimization: NumPy & Polars @@ -61,11 +66,14 @@ ts_array = np.array(timestamps) # binary search for all timestamps at once indices = np.searchsorted(time_arr, ts_array) -# bounds check and exact match verification -valid_mask = ( - (indices < len(array)) - & - (time_arr[indices] == ts_array) +# bounds check before indexing: searchsorted may return +# len(time_arr) for values above the final timestamp +in_bounds = indices < len(time_arr) +valid_mask = np.zeros(indices.shape, dtype=bool) +valid_mask[in_bounds] = ( + time_arr[indices[in_bounds]] + == + ts_array[in_bounds] ) valid_indices = indices[valid_mask] diff --git a/.opencode/commands/commit-msg.md b/.opencode/commands/commit-msg.md new file mode 100644 index 00000000..362f0670 --- /dev/null +++ b/.opencode/commands/commit-msg.md @@ -0,0 +1,10 @@ +--- +description: Generate a piker-style message for staged changes. +--- + +Load the `commit-msg` skill and follow it completely for the currently +staged changes. Do not run `git commit` unless the user explicitly asks. +Keep all workflow and style decisions in the shared skill rather than +duplicating them in this OpenCode command. + +Additional context from the user: $ARGUMENTS diff --git a/ai/README.md b/ai/README.md index 17b21894..aff16e88 100644 --- a/ai/README.md +++ b/ai/README.md @@ -17,6 +17,18 @@ track new integration ideas and proposals in | Tool | Directory | Status | |------|-----------|--------| | [Claude Code](https://github.com/anthropics/claude-code) | [`claude-code/`](claude-code/) | active | +| [OpenCode](https://opencode.ai/) | [`opencode/`](opencode/) | active | + +## Shared Skills + +Repo-specific skills use the portable Agent Skills +frontmatter subset and live under `.claude/skills/` as a +single source. Claude Code discovers that directory +natively, and OpenCode discovers the same project skills +without copies or generated wrappers. + +Harness-specific command files should only delegate to a +shared skill. They must not duplicate the skill body. ## Adding a New Integration @@ -32,7 +44,7 @@ ai/ ├── README.md # <- you are here ├── claude-code/ │ └── README.md -├── opencode/ # future +├── opencode/ │ └── README.md └── / └── README.md @@ -45,6 +57,7 @@ ai/ - 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.) +- Keep docs concise; link to the shared skill source files rather than duplicating content +- Keep skill bodies harness-neutral; isolate slash-command + syntax and permissions in each harness integration diff --git a/ai/claude-code/README.md b/ai/claude-code/README.md index 7dd10dd0..f609c0e8 100644 --- a/ai/claude-code/README.md +++ b/ai/claude-code/README.md @@ -1,15 +1,17 @@ # Claude Code Integration [Claude Code](https://github.com/anthropics/claude-code) -skills and workflows for piker development. +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 | @@ -17,8 +19,10 @@ 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`. +Portable skill source files live under +`.claude/skills//SKILL.md` and are shared with +OpenCode. Claude-specific behavior belongs in command or +settings files, not the shared skill bodies. --- @@ -84,8 +88,7 @@ description context. Examples: **Footer** (always): ``` (this patch was generated in some part by -[`claude-code`][claude-code-gh]) -[claude-code-gh]: https://github.com/anthropics/claude-code +`claude-code` using `` (``)) ``` ### Output Files @@ -94,7 +97,8 @@ After generation, the commit message is written to: ``` .claude/ -├── __commit_msg.md # archived +├── skills/commit-msg/msgs/ +│ └── __commit_msg.md └── git_commit_msg_LATEST.md # latest ``` @@ -102,18 +106,10 @@ 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`: +Use the latest file with an editor review before 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 +git commit --edit --file .claude/git_commit_msg_LATEST.md ``` ### Examples @@ -128,56 +124,32 @@ Add `MktPair.fqme` property for symbol resolution 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 +- 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`][claude-code-gh]) -[claude-code-gh]: https://github.com/anthropics/claude-code +`claude-code` using `` (``)) ``` -### Frontmatter Reference +### Shared Frontmatter -The skill's `SKILL.md` uses these Claude Code -frontmatter fields: +Skills use the Agent Skills fields understood by both +Claude Code and OpenCode: ```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 + Generate piker-style git commit messages. Use when... +compatibility: Requires git. +metadata: + author: goodboy + version: "1.0" --- ``` -| 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. +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. diff --git a/ai/opencode/README.md b/ai/opencode/README.md new file mode 100644 index 00000000..6bc17aeb --- /dev/null +++ b/ai/opencode/README.md @@ -0,0 +1,51 @@ +# OpenCode Integration + +[OpenCode](https://opencode.ai/) uses piker's shared +repo-specific skills directly from `.claude/skills/`. +There is no second copy of each skill to keep in sync. + +## Available Skills + +| Skill | Activation | Specialization | +|-------|------------|----------------| +| `commit-msg` | `/commit-msg` or explicit request | Piker commit-message style and artifacts | +| `piker-conc-expert` | automatic | `tractor` actor topology, RPC, and cancellation | +| `piker-profiling` | automatic | Cross-actor `Profiler` instrumentation | +| `piker-slang` | automatic | Project communication style | +| `py-codestyle` | automatic | Python source conventions | +| `pyqtgraph-optimization` | automatic | Batched Qt graphics rendering | +| `timeseries-optimization` | automatic | NumPy and Polars timeseries performance | + +OpenCode's project command lives at +`.opencode/commands/commit-msg.md`. It delegates to the +shared `commit-msg` skill and only supplies command +arguments; workflow logic remains in the skill. + +A user-local skill with the same name may override a repo +skill. Treat `opencode debug skill` as authoritative when +diagnosing which source is active. + +## Verify Discovery + +From the repository root: + +```console +opencode debug skill +opencode debug config +``` + +`opencode debug skill` should list the piker skills from +the project checkout. Restart OpenCode after changing a +skill or command because configuration-time files are not +hot-reloaded into an active session. + +## Portability Rules + +- Use only portable Agent Skills frontmatter in shared + `SKILL.md` files. +- Keep harness-specific command syntax under + `.opencode/commands/`. +- Detect the active harness and model at runtime; do not + hardcode Claude Code attribution in shared workflows. +- Keep supporting references beside each shared skill so + relative links resolve in every harness. diff --git a/ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md b/ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md new file mode 100644 index 00000000..a37c0661 --- /dev/null +++ b/ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md @@ -0,0 +1,64 @@ +--- +model: gpt-5.6-sol +provider: openai +service: opencode +session: ses_0799212ebffe42arY96czXn89F +timestamp: 2026-07-21T20:52:28Z +git_ref: 58ffe487 +scope: config +substantive: true +raw_file: 20260721T205228Z_58ffe487_prompt_io.raw.md +--- + +## Prompt + +The user asked to scan Claude's repo-local skills and +documentation, summarize their specializations, and then +rework repo-specific skills for use across coding +harnesses, particularly OpenCode. The user intends to +choose one of Claude's unfinished tasks afterward. + +## Response summary + +Standardized the tracked piker skills on portable Agent +Skills frontmatter, made `commit-msg` harness-aware, +documented OpenCode discovery and command delegation, and +fixed an unsafe `np.searchsorted()` example found during +the audit. Preserved the existing `.claude` artifact path +as a shared legacy location to avoid breaking established +commit workflows. + +## Files changed + +- `.claude/skills/commit-msg/SKILL.md` - portable, + harness-aware commit-message workflow +- `.claude/skills/commit-msg/style-guide-reference.md` - + generic coding-harness attribution +- `.claude/skills/piker-conc-expert/SKILL.md` - portable + frontmatter +- `.claude/skills/piker-profiling/SKILL.md` - portable + frontmatter +- `.claude/skills/piker-slang/SKILL.md` - portable + frontmatter +- `.claude/skills/pyqtgraph-optimization/SKILL.md` - + portable frontmatter +- `.claude/skills/timeseries-optimization/SKILL.md` - + portable frontmatter and safe search bounds handling +- `ai/README.md` - shared-skill integration model +- `ai/claude-code/README.md` - cross-harness Claude Code + documentation +- `ai/opencode/README.md` - OpenCode usage and discovery + documentation +- `.opencode/commands/commit-msg.md` - thin OpenCode + command delegating to the shared skill +- `ai/prompt-io/opencode/README.md` - OpenCode provenance + policy +- `ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.raw.md` + - unedited response record +- `ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.md` + - provenance metadata and summary + +## Human edits + +None - generated changes have not yet been reviewed or +edited by the human. diff --git a/ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.raw.md b/ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.raw.md new file mode 100644 index 00000000..873146a6 --- /dev/null +++ b/ai/prompt-io/opencode/20260721T205228Z_58ffe487_prompt_io.raw.md @@ -0,0 +1,33 @@ +--- +model: gpt-5.6-sol +provider: openai +service: opencode +timestamp: 2026-07-21T20:52:28Z +git_ref: 58ffe487 +diff_cmd: git diff HEAD~1..HEAD +--- + +The repo-local skill inventory contains seven domains: +commit-message generation, actor-runtime concurrency, +distributed profiling, project communication style, +Python source style, PyQtGraph rendering, and NumPy/Polars +timeseries optimization. + +I converted the six tracked repo-specific skills to the +portable Agent Skills frontmatter subset so Claude Code +and OpenCode can load the same source files. The +commit-message workflow now gathers live git context at +execution time, uses runtime harness/model attribution, +preserves human-owned task state, and keeps the existing +message artifact paths for compatibility. + +I added OpenCode integration documentation and updated +the shared and Claude Code docs to describe a single +cross-harness skill source with thin harness commands. +During validation I also corrected an out-of-bounds +`np.searchsorted()` example in the timeseries skill. + +The unfinished artifacts found during the scan are a +shared-memory migration plan and a gap-annotation +performance handoff. The earlier datad split plan appears +implemented and is now captured by the concurrency skill. diff --git a/ai/prompt-io/opencode/README.md b/ai/prompt-io/opencode/README.md new file mode 100644 index 00000000..35ad94fc --- /dev/null +++ b/ai/prompt-io/opencode/README.md @@ -0,0 +1,20 @@ +# AI Prompt I/O Log - OpenCode + +This directory tracks prompt inputs and model outputs for +AI-assisted development using OpenCode. + +## Policy + +Prompt logging follows the +[NLNet generative AI policy][nlnet-ai]. Substantive AI +contributions are logged with the model, timestamp, +prompt, response, and affected files. + +[nlnet-ai]: https://nlnet.nl/foundation/policies/generativeAI/ + +## Usage + +Entries are created by the `prompt-io` skill. Human +contributors remain accountable for all code decisions; +AI-generated content is not presented as human-authored +work.