@loomhelm/multi-task-flow 0.0.0-stage → 0.2.6

package/toolkit/skills/rust-crate-release/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: rust-crate-release
+description: "Set up and run Rust crate releases."
+---
+
+# Rust Crate Release
+
+## Overview
+
+Use this skill to implement Ivan’s default crates.io publishing workflow (CI + manual GitHub Actions release), and to run releases safely (version bump, tag, push, publish).
+
+## Guardrails
+
+- **No guessing:** confirm crate/workspace structure, default branch (usually `main`), and whether `main` is protected.
+- **No file writes without explicit OK (in the target repo):** propose a plan + file list, then wait.
+- **No publishing without explicit OK:** never publish to crates.io or push tags without confirmation.
+- **Toolchain policy:** default is latest stable; if local toolchain is not latest and an update is needed, ask before any `rustup` change.
+- **Version policy:** default to latest stable versions; treat any versions observed in Ivan repos as minimum acceptable; do not pin versions unless required, and ask when pinning (MSRV, compatibility, security) matters.
+
+## Workflow
+
+### 1) Inventory + confirm intent
+
+Collect:
+
+- crate(s) to publish (single crate vs workspace)
+- current version(s), features, MSRV (`rust-version`)
+- current CI gates (fmt/clippy/test/build) and existing release process
+- if this is an embedded driver crate: confirm the async+sync support plan (typically `async` feature + `maybe-async-cfg`)
+
+Confirm:
+
+- publish target is crates.io
+- release tag format is `release/<semver>`
+- release runs from `main`
+
+### 2) Make the crate publishable (Cargo metadata + package hygiene)
+
+Use `references/cargo-package-checklist.md` for the exact checklist.
+
+Defaults observed in Ivan’s published crates:
+
+- Rust edition: use latest stable Rust edition.
+- `license = "MIT OR Apache-2.0"`
+- `exclude = [...]` to keep crates.io uploads small (typically exclude `target/`, `.github/`, `scripts/`, editor configs, generated assets)
+
+### 3) Add CI quality gates (recommended)
+
+Create/adjust `.github/workflows/build.yml` (template provided).
+
+Baseline gates:
+
+- `cargo fmt --all -- --check`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo build`
+- `cargo test`
+
+If the crate has important feature combos, add a matrix like in `references/release-style.md`.
+
+### 4) Add GitHub Actions release workflow (Ivan default)
+
+Create/adjust `.github/workflows/release.yml` (template provided).
+
+Behavior:
+
+- Manual trigger via `workflow_dispatch`, with an input `version` (`major|minor|patch` or semver)
+- Publish via `kaleidawave/crates-release-gh-action@main` using `secrets.CARGO_REGISTRY_TOKEN`
+- Commit updated `Cargo.toml`, tag `release/<new-version>`, and push `main` + tags
+
+Notes:
+
+- If the repo uses commitlint/conventional commits, adjust the release commit message accordingly (e.g. `chore(release): ...`).
+- If `main` is protected and Actions cannot push, stop and ask the user which workaround to adopt (settings vs PR-based release).
+
+### 5) Run a release (operator runbook)
+
+Before triggering release:
+
+- Ensure CI is green on `main`.
+- Ensure `CARGO_REGISTRY_TOKEN` is configured in repo secrets.
+- Confirm the version bump input (`patch` by default).
+
+Trigger the workflow, then verify:
+
+- tag `release/<semver>` exists in the repo
+- crates.io shows the new version
+
+## Templates
+
+- Release workflow: `templates/workflows/release.yml`
+- CI workflow: `templates/workflows/build.yml`
+
+## References (load only when needed)
+
+- Ivan’s release conventions (evidence + matrices): `references/release-style.md`
+- Cargo packaging checklist (Cargo.toml keys, license, exclude): `references/cargo-package-checklist.md`

package/toolkit/skills/rust-crate-release/references/cargo-package-checklist.md

@@ -0,0 +1,52 @@
+# Cargo package checklist (publishable crate)
+
+Use this checklist before the first publish and before every release.
+
+## Cargo.toml `[package]` essentials
+
+- `name`, `version`
+- Rust edition: use the latest stable Rust edition.
+- `license = "MIT OR Apache-2.0"`
+- `description`
+- `repository`
+- `keywords` (optional but recommended)
+- `categories` (optional but recommended)
+- `documentation = "https://docs.rs/<crate-name>"` (optional but recommended)
+- `readme = "README.md"` (optional but recommended)
+- `rust-version = "<msrv>"` (optional; set when MSRV matters)
+
+## Licensing consistency
+
+- Ensure the repo contains license text matching `license`.
+  - If using dual license (`MIT OR Apache-2.0`), include both license texts (separate files or a combined file), and keep README/license statements consistent.
+
+## Keep crates.io package small
+
+Prefer a conservative `[package].exclude` list that omits build artifacts and repo-only files.
+
+Example-style exclude list (observed in existing crates):
+
+```toml
+exclude = [
+    "docs",
+    "target/",
+    ".vscode/",
+    ".github/",
+    "lefthook.yml",
+    "scripts/"
+]
+```
+
+Adjust for your repo:
+
+- Exclude `examples/*/target/` if examples build inside their own target dirs.
+- Exclude large binary assets under `docs/` (e.g. PDFs, screenshots) if not needed on crates.io.
+
+## Preflight checks (recommended)
+
+- `cargo fmt --all`
+- `cargo clippy --all-targets -- -D warnings`
+- `cargo test`
+- `cargo package` (ensures the packaged crate contains the right files)
+
+If CI is configured, ensure it’s green on `main` before releasing.

package/toolkit/skills/rust-crate-release/references/release-style.md

@@ -0,0 +1,33 @@
+# Ivan Rust crate release style (crates.io)
+
+## Release tags
+
+- Tag format: `release/<semver>` (example: `release/x.y.z`).
+
+## GitHub Actions release workflow (pattern)
+
+- Trigger: `workflow_dispatch` with input `version` (`major|minor|patch` or semver), default `patch`.
+- Concurrency group: `release-crate`.
+- Publish step: `kaleidawave/crates-release-gh-action@main`
+  - `with.version`: `${{ github.event.inputs.version }}`
+  - `with.crates-token`: `${{ secrets.CARGO_REGISTRY_TOKEN }}`
+- Git steps (after publish):
+  - `git add .`
+  - `git commit -m "Release: ${{ steps.release.outputs.new-versions-description }}"`
+  - `git tag "release/${{ steps.release.outputs.new-version }}"`
+  - `git push --tags origin main`
+
+Recommended hardening:
+
+- Add `permissions: { contents: write }` if the repo’s default `GITHUB_TOKEN` permissions are read-only.
+
+## CI gate style (example: stricter crate)
+
+- Install toolchain via `dtolnay/rust-toolchain@stable` with `rustfmt` + `clippy`.
+- Run `cargo fmt --all -- --check`.
+- Run `cargo clippy --all-targets ... -- -D warnings`.
+- Build + test.
+- If the crate has important feature combinations, use a matrix. For embedded driver crates, always include **sync** (default, no features) and **async** (`--features async`). Example set observed in practice:
+  - `""`, `"async"`, `"defmt"`, `"async,defmt"`
+
+If the repo contains example firmware/projects (e.g. under `examples/*`), consider building them as a separate job and (if needed) install `thumbv7em-none-eabihf` targets.

package/toolkit/skills/rust-crate-release/templates/workflows/build.yml

@@ -0,0 +1,44 @@
+name: Build and Test
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      # Replace vX with the latest stable major version when applying this template.
+      - uses: actions/checkout@vX
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache cargo registry
+        # Replace vX with the latest stable major version when applying this template.
+        uses: actions/cache@vX
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Check formatting
+        run: cargo fmt --all -- --check
+
+      - name: Run clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: Build
+        run: cargo build --verbose
+
+      - name: Run tests
+        run: cargo test --verbose

package/toolkit/skills/rust-crate-release/templates/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release crate
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "major/minor/patch or semver"
+        required: false
+        default: "patch"
+
+concurrency: release-crate
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      # Replace vX with the latest stable major version when applying this template.
+      - uses: actions/checkout@vX
+
+      - name: Set git credentials
+        run: |
+          git config user.name github-actions
+          git config user.email github-actions@github.com
+
+      - name: Crates publish
+        uses: kaleidawave/crates-release-gh-action@main
+        id: release
+        with:
+          version: ${{ github.event.inputs.version }}
+          crates-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+
+      - name: Push updated Cargo.toml
+        run: |
+          git add .
+          git commit -m "Release: ${{ steps.release.outputs.new-versions-description }}"
+          git tag "release/${{ steps.release.outputs.new-version }}"
+          git push --tags origin main

package/toolkit/skills/solution-sync/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: solution-sync
+description: "Read, refresh, or create docs/solutions for reusable engineering learnings."
+---
+
+# Solution sync (`docs/solutions/`)
+
+当当前 run 需要清掉 solution gate、review/CI 暴露了新的可复用经验，或当前任务命中了相关 `docs/solutions/**` / legacy knowledge docs 时，使用本 skill。
+
+## Goal
+
+让 canonical `docs/solutions/**` 持续表达“下次遇到类似问题时该怎么更快、更稳地处理”，同时保持与 spec、项目文档、任务日志分层。
+
+## Inputs（可选）
+
+- `MODE=check|write`（默认 `write`）
+- `SOURCE_HINTS=<spec/module/symptom/paths>`
+- `TARGET_HINTS=<solution paths/category hints>`
+- `LEGACY_OK=yes|no`（默认 `yes`）
+
+## Hard rules
+
+- canonical 目标文件只允许落在 `docs/solutions/<category>/<slug>.md`。
+- 如果只命中了 legacy knowledge docs（`docs/notes/**`、`docs/troubleshooting/**`、`docs/workflow/**`、`docs/learnings/**`），不要手写重复 solution；先用 `$docs-migrate MODE=solutions|auto` 把当前任务相关子集 canonicalize，再继续本 skill。
+- 优先 `update` / `refresh` 已有 canonical solution，避免平行创建重复主题文档。
+- 只有 `main-agent` 可以在共享流程里写 `docs/solutions/**`；sidecar / sub-agent 默认只做 `MODE=check` 并回传 hint。
+- 不要把任务时间线、PR 对话、review 循环流水账或项目当前真相原样塞进 solution；这些分别属于 workflow/PR 或 human-facing project docs。
+- 若稳定结论已经应该给人类项目文档直接看，交给 `$project-doc-promote`；本 skill 只负责 `docs/solutions/**`。
+
+## Workflow
+
+1. Focused lookup
+
+- 以当前 spec、模块名、症状、接口关键词、关键变更路径为线索，优先查 canonical `docs/solutions/**`。
+- 若相关知识仍在 legacy knowledge docs，先经 `$docs-migrate` 建立 canonical solution，再继续判断。
+- 记录 `Solution检索=命中|未命中|未检查` 与 `Solution引用=<paths|none|未检查>`。
+
+2. Settle disposition
+
+- `none`：没有新增可复用经验，或现有 solution 无需改动。
+- `update`：已有 solution 结论仍成立，但需要补新证据、边界、命令或 guardrail。
+- `create`：当前没有合适的 canonical solution，需要新建一篇。
+- `refresh`：现有 solution 的路径、入口、命令、依赖或结论已漂移，需要刷新/替换。
+- `MODE=check` 时返回 `solution_disposition_hint`；`MODE=write` 时返回正式 `solution_disposition`。
+
+3. Write canonical solution (`MODE=write`)
+
+- 优先复用已有 canonical solution；只有确实没有 owner 时才创建新文件。
+- 保持最小可复用结构：`Context`、`Symptoms`、`Root cause`、`Resolution`、`Guardrails / Reuse notes`、`References`（按需增减）。
+- 维护 frontmatter 最小 schema：`title/module/problem_type/component/tags/status/related_specs`；必要时补 `symptoms/root_cause/resolution_type/supersedes`。
+- 若刷新/替换旧 solution，确保 `status`、`supersedes` 与引用关系一致。
+
+4. Return evidence
+
+- `MODE=check`：
+  - `Solution检索=<命中|未命中|未检查>`
+  - `Solution引用=<paths|none|未检查>`
+  - `solution_disposition_hint=<none|update|create|refresh|未检查>`
+  - `Solution同步证据=<solution_path@sha|none|未检查>`
+- `MODE=write`：
+  - `Solution检索=<命中|未命中|未检查>`
+  - `Solution引用=<paths|none|未检查>`
+  - `solution_disposition=<none|update|create|refresh|未检查>`
+  - `Solution同步证据=<solution_path@sha|none|未检查>`
+
+## Heuristics
+
+优先考虑写/更 solution 的场景：
+
+- 当前问题未来大概率还会重复出现。
+- 本轮确认了更稳的命令、路径、边界条件或排障顺序。
+- review / CI / main-sync 暴露出“旧经验已 stale”的事实。
+- 同一问题在多个任务里重复被口头解释，但仓库里还没有 canonical solution。

package/toolkit/skills/solution-sync/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Solution sync"
+  short_description: "Read or update reusable learnings in docs/solutions"
+  default_prompt: "Use $solution-sync to settle the shared solution gate and update docs/solutions for reusable engineering learnings."