From 7aa6160c7536a63cbb02685bafadd4a8fe03f474 Mon Sep 17 00:00:00 2001 From: Ed Zynda Date: Mon, 4 May 2026 12:10:46 +0300 Subject: [PATCH] updates --- .kit/extensions/subagent-monitor.go | 9 ++--- .kit/prompts/create-pr.md | 47 ++++++++++++++++++++++ .kit/prompts/feature-request.md | 4 +- .kit/prompts/file-issue.md | 4 +- .kit/prompts/fix-issue.md | 59 ++++++++++++++++++++++++++++ .kit/prompts/new-prompt.md | 61 +++++++++++++++++++++++------ .kit/prompts/update-docs.md | 52 ++++++++++++++++++++++++ 7 files changed, 213 insertions(+), 23 deletions(-) create mode 100644 .kit/prompts/create-pr.md create mode 100644 .kit/prompts/fix-issue.md create mode 100644 .kit/prompts/update-docs.md diff --git a/.kit/extensions/subagent-monitor.go b/.kit/extensions/subagent-monitor.go index d61b2541..f7e86d0c 100644 --- a/.kit/extensions/subagent-monitor.go +++ b/.kit/extensions/subagent-monitor.go @@ -13,8 +13,6 @@ // - No channels in maps (Yaegi panics on range over map[string]chan) // - All ctx.* calls guarded with nil checks // - Simple data structures only -// - The extension runner serializes handler calls per-extension, so -// concurrent subagent events cannot race on this shared state. package main import ( @@ -45,8 +43,7 @@ const ( ) // --------------------------------------------------------------------------- -// Package-level state — safe because the runner serializes all handler -// invocations for the same extension (per-extension reentrant mutex). +// Package-level state - all simple types // --------------------------------------------------------------------------- var ( @@ -285,8 +282,8 @@ func Init(api ext.API) { submonPushWidget() - // Remove the entry — build a new slice to avoid aliasing bugs - newEntries := make([]*submonEntry, 0, len(submonEntries)) + // Remove the entry immediately (no goroutine to avoid races) + newEntries := submonEntries[:0] for _, en := range submonEntries { if en.callID != e.ToolCallID { newEntries = append(newEntries, en) diff --git a/.kit/prompts/create-pr.md b/.kit/prompts/create-pr.md new file mode 100644 index 00000000..33fc1f5b --- /dev/null +++ b/.kit/prompts/create-pr.md @@ -0,0 +1,47 @@ +--- +description: Open a GitHub PR for the current branch using the repo's PR template +--- + +Open a GitHub pull request for the current branch, filling out the repository's PR template with a description grounded in the actual commits and diff. + +## Steps + +1. **Verify the branch is pushed**: + - `git status -sb` and `git log @{u}..HEAD --oneline 2>/dev/null` — if there is no upstream or unpushed commits, run `git push -u origin "$(git branch --show-current)"` first + - If the working tree is dirty, stop and tell the user to commit first (suggest `/commit-push`) +2. **Gather context**: + - `git log origin/main..HEAD --oneline` — list of commits going into the PR + - `git diff origin/main...HEAD --stat` then `git diff origin/main...HEAD` — read the actual changes + - Identify the linked issue (from commit messages, branch name, or extra user input: $@) — capture as `Fixes #N` if applicable +3. **Locate the PR template**: + - Check `.github/pull_request_template.md`, `.github/PULL_REQUEST_TEMPLATE.md`, or `docs/pull_request_template.md` + - If none exists, use a minimal `## Description` / `## Type of Change` / `## Checklist` structure +4. **Draft the PR body** by filling out the template: + - **Description**: 1–3 short paragraphs explaining *what* changed and *why*, grounded in the diff. Include a brief before/after example for new APIs when useful. + - **Fixes #N**: only if there is a real linked issue + - **Type of Change**: tick the single most accurate box with `[x]` (leave others as `[ ]`) + - **Checklist**: tick items that are genuinely true (style, self-review, tests added, docs updated) + - **Additional Information**: bullet list of added / modified files and any backward-compatibility notes + - Remove template sections explicitly marked "remove if not applicable" (e.g. MCP Spec Compliance) when they don't apply +5. **Write the body to a temp file**: `/tmp/pr-body-.md` — never inline a long body via `--body`, always use `--body-file` +6. **Choose the title**: prefer the subject of the primary commit if it already follows Conventional Commits; otherwise craft one in the same style (`(): `, ≤72 chars) +7. **Create the PR**: + ``` + gh pr create \ + --title "" \ + --body-file /tmp/pr-body-<...>.md \ + --base main \ + --head "$(git branch --show-current)" + ``` + Use the repo's actual default branch if it isn't `main` (`gh repo view --json defaultBranchRef -q .defaultBranchRef.name`) +8. **Report the PR URL** returned by `gh` and stop + +## Guidelines + +- Read the diff and commit messages — do **not** invent features that aren't in the code +- One PR per logical change; if the branch contains unrelated commits, surface that and ask before continuing +- Keep the description focused on reviewer-relevant information (what / why), not a replay of the diff +- Only check checklist boxes that are actually satisfied; leave the rest unchecked rather than lying +- If `gh` is not authenticated (`gh auth status` fails), stop and tell the user + +$@ diff --git a/.kit/prompts/feature-request.md b/.kit/prompts/feature-request.md index bcaf689e..9f71d7ab 100644 --- a/.kit/prompts/feature-request.md +++ b/.kit/prompts/feature-request.md @@ -2,7 +2,7 @@ description: Create a feature request using the GitHub template --- -Create a feature request for the Kit repository. The user wants to request: $+ +Create a feature request for the Kit repository. The user wants to request: $@ ## Feature Request Template @@ -16,7 +16,7 @@ This prompt uses the `feature_request` GitHub template which requires: ## Steps -1. **Understand the request** from `$+` +1. **Understand the request** from the user input: $@ - What capability is missing? - What would the ideal behavior look like? diff --git a/.kit/prompts/file-issue.md b/.kit/prompts/file-issue.md index 688f171b..049f880e 100644 --- a/.kit/prompts/file-issue.md +++ b/.kit/prompts/file-issue.md @@ -2,7 +2,7 @@ description: File a GitHub issue using the appropriate template --- -File a GitHub issue for the Kit repository. The user wants to create an issue about: $+ +File a GitHub issue for the Kit repository. The user wants to create an issue about: $@ ## Issue Templates Available @@ -16,7 +16,7 @@ This repository has structured issue templates. You MUST use the appropriate tem ## Steps -1. **Determine the issue type** from `$+`: +1. **Determine the issue type** from the user input: $@ - Bug → use `--template bug_report` - Feature → use `--template feature_request` - Documentation → use `--template documentation` diff --git a/.kit/prompts/fix-issue.md b/.kit/prompts/fix-issue.md new file mode 100644 index 00000000..24d7edc2 --- /dev/null +++ b/.kit/prompts/fix-issue.md @@ -0,0 +1,59 @@ +--- +description: Resolve a GitHub issue by fixing, implementing, or documenting based on its type +--- + +Resolve GitHub issue #$1 by reading it, classifying it, and producing the appropriate change (bug fix, feature implementation, documentation update, etc.). + +## Steps + +1. **Fetch the issue**: + - Run: gh issue view $1 --json number,title,body,labels,state,author,comments + - If the issue is closed, stop and ask the user whether to proceed +2. **Classify the issue** from labels, title prefix, and body content: + - `bug` / `fix:` → reproduce, then fix + - `enhancement` / `feature` / `feat:` → design, then implement + - `documentation` / `docs:` → locate and update docs + - `question` / `discussion` → answer in a comment, do **not** open a PR + - Anything else → ask the user how to proceed +3. **Create a working branch** off the default branch: + - `git checkout main && git pull --ff-only` + - Branch name: <type>/$1-<slug> (e.g. `fix/42-borderColor-ignored`, `feat/57-keyboard-clear`, `docs/63-widget-lifecycle`) +4. **Do the work** based on type: + + ### Bug (`bug` label / `fix:` title) + - Reproduce the failure first (write a failing test if feasible) — if you cannot reproduce, comment on the issue asking for clarification and stop + - Locate the root cause; do not patch symptoms + - Add or extend a regression test that fails before and passes after the fix + - Run `go test ./... -race` and `golangci-lint run` + + ### Feature (`enhancement` / `feature` label / `feat:` title) + - Re-read the motivation and proposed implementation in the issue body + - For large, ambiguous, or breaking changes, sketch the design in a comment on the issue and wait for sign-off before writing code + - Implement behind sensible defaults; add godoc on every exported symbol + - Add unit tests covering the new behaviour and edge cases + - Update `README.md` / `docs/` if the public surface changed + - Run `go test ./... -race` and `golangci-lint run` + + ### Documentation (`documentation` label / `docs:` title) + - Open the file/URL referenced in the issue's "Documentation Location" + - Apply the suggested improvement; verify code samples compile (`go build ./...`) + - No tests required, but run `golangci-lint run` if Go files were touched + +5. **Commit** with a Conventional Commit subject that references the issue: + - fix: <summary> (#$1) / feat: <summary> (#$1) / docs: <summary> (#$1) + - Body explains what changed and why, in the user's voice +6. **Push and open a PR** with "Fixes #$1" in the body — delegate to `/create-pr` if the user prefers, otherwise run: + + git push -u origin "$(git branch --show-current)" + gh pr create --title "<type>: <summary> (#$1)" --body-file /tmp/pr-body-$1.md --base main + +7. **Report** the branch name, commit SHA, and PR URL + +## Guidelines + +- Read the **entire** issue including comments before writing code — the latest comment often refines the ask +- If the issue is unclear, post a clarifying comment on the issue and stop; do not guess +- Do not close the issue manually — "Fixes #$1" in the PR handles that on merge +- Keep the change scoped to the issue; surface unrelated cleanups separately +- For breaking changes or architecture shifts, propose the design on the issue first and wait for maintainer sign-off +- If the issue is a duplicate or already fixed on `main`, comment with the reference and stop diff --git a/.kit/prompts/new-prompt.md b/.kit/prompts/new-prompt.md index 102f93e0..83f54cef 100644 --- a/.kit/prompts/new-prompt.md +++ b/.kit/prompts/new-prompt.md @@ -2,7 +2,7 @@ description: Scaffold a new prompt template in .kit/prompts/ --- -Create a new kit prompt template. The user wants a prompt that does: $+ +Create a new kit prompt template. The user wants a prompt that does: $@ ## What a prompt template is @@ -16,30 +16,64 @@ It becomes a `/slug` slash command in the kit input box — typed as `/filename` description: One-line description shown in autocomplete --- -Body text of the prompt. Use $@ for all user-supplied arguments, -$1 $2 etc. for positional arguments. +Body text of the prompt. Reference user-supplied arguments +with positional placeholders (see "Argument placeholders" below). ``` - **Filename** → slug: `commit-push.md` becomes `/commit-push` - **Frontmatter**: only `description` is recognised; keep it under ~80 chars - **Body**: plain markdown; the full text is submitted as the user's message when the template fires -- **Arguments**: `$+` expands to everything the user typed after the slash command name - (requires at least one argument); `$@` is the same but allows zero arguments; - `$1`, `$2` for individual positional args; omit entirely if no arguments are needed +- **Required args**: kit infers required positional args from the highest `$N` it finds *outside* backtick/tilde code fences — a stray `$2` in active prose means kit will refuse to run without 2 arguments + +## Argument placeholders + +kit performs shell-style substitution before sending the prompt to the model: + +- `$1`, `$2`, … — positional arguments (1-indexed) +- `${1}`, `${2}`, … — same, brace form (use when followed by digits/letters: `${1}_suffix`) +- `$@` — all arguments joined by spaces (zero or more, optional) +- `$+` — all arguments, **at least one required** +- `$ARGUMENTS` / `${ARGUMENTS}` — alias for `$@` +- `${@:N}` — args from the Nth onwards (1-indexed, bash-style) +- `${@:N:L}` — `L` args starting from the Nth + +### ⚠️ Critical: code fences and inline code preserve placeholders verbatim + +Anything inside triple-backtick fences, `~~~` fences, or single-backtick `inline` code spans is **left untouched** so example code samples don't get corrupted. That means: + +- An inline-coded `gh issue view $1` stays literal `$1` in the model's input ❌ +- The same command without backticks: gh issue view $1 → expands to `gh issue view 42` ✓ + +**Rule of thumb:** if you want a placeholder to substitute, keep it outside backticks and fences. If you want a literal `$1` in the output (e.g. teaching the user shell syntax), put it inside backticks. + +### Workarounds for "I want it to look like code AND substitute" + +1. **Drop the backticks** around just the placeholder portion — the rest can still read as a command line in prose +2. **Use a 4-space-indented code block** instead of a triple-backtick fence — kit only skips backtick/tilde fences, so indentation-style code blocks still get substitution: + + git push -u origin "$(git branch --show-current)" + gh pr create --title "fix: ... (#$1)" --base main + +3. **Bind once, reference loosely**: put `Issue: $1` at the top in prose, then leave the backticked examples literal — the model will substitute mentally ## Steps -1. **Understand the workflow** the user described in `$+` — ask a clarifying question if the intent is ambiguous +1. **Understand the workflow** the user described in $@ — ask a clarifying question if the intent is ambiguous 2. **Choose a filename**: short, lowercase, hyphen-separated, descriptive (e.g. `code-review.md`) 3. **Write the description**: one sentence, imperative, fits in autocomplete -4. **Draft the body**: - - Open with a single sentence stating the goal +4. **Decide on arguments**: + - No args needed → omit placeholders entirely + - One required value (issue number, PR url, file path) → use `$1` + - Free-form trailing context → end with a single `$@` line + - Multiple distinct values → use `$1`, `$2`, … and document each at the top +5. **Draft the body**: + - Open with a single sentence stating the goal, weaving in `$1`/`$@` where the value belongs - Use `## Steps` for multi-step workflows; use plain prose for simple prompts - Be specific: name commands, flags, and file paths where relevant - - End with `$+` on its own line if the user must pass context; use `$@` if arguments - are optional; omit if the prompt is self-contained -5. **Write the file** to `.kit/prompts/<slug>.md` -6. **Confirm** by showing the final file content and the slash command that activates it + - **Audit every backtick and code fence**: any `$N` or `$@` inside them will not expand — was that intentional? If not, apply one of the workarounds above +6. **Write the file** to `.kit/prompts/<slug>.md` +7. **Verify substitution** by mentally (or actually) replacing `$1`/`$@` with a sample value and confirming every reference resolves — and that the prompt's *own* example snippets don't accidentally bump the required-arg count (wrap illustrative `$N` examples in triple-backtick fences, not 4-space indentation, so `RequiredArgs()` ignores them) +8. **Confirm** by showing the final file content and the slash command that activates it (e.g. `/code-review 42`) ## Guidelines @@ -47,3 +81,4 @@ $1 $2 etc. for positional arguments. - Prefer concrete steps over vague instructions - A prompt that does one thing well beats one that tries to cover every edge case - If the workflow already exists as a prompt, suggest extending it instead of duplicating +- When in doubt about substitution behaviour, write the file and run `/<slug> testvalue` once to confirm — wrong placement of backticks is the #1 failure mode diff --git a/.kit/prompts/update-docs.md b/.kit/prompts/update-docs.md new file mode 100644 index 00000000..ee987a3b --- /dev/null +++ b/.kit/prompts/update-docs.md @@ -0,0 +1,52 @@ +--- +description: Audit and update project documentation (README and docs site) for a recent change +--- + +Review recent code changes, identify all documentation surfaces that should +mention them, and update each one — grounded in the actual diff, not guesses. + +## Steps + +1. **Identify the change**: + - If the user input ($@) names a commit / PR / branch / topic, use that as the focus + - Otherwise inspect `git log origin/main..HEAD --oneline` and `git diff origin/main...HEAD --stat` to discover what shipped on the current branch + - Read the actual diff (`git diff origin/main...HEAD`) — never document features that aren't in the code + +2. **Inventory the doc surfaces**: + - `README.md` at the repo root + - Any docs site (commonly `www/`, `docs/`, `site/`) — list its pages and identify the one(s) most thematically related to the change + - Inline godoc / API reference comments on the new exported symbols + - `CHANGELOG.md` if the project keeps one + - Any `examples/` directory entries that demonstrate the affected area + +3. **Audit each surface** with `grep`: + - Search for the names of related existing APIs (e.g. if you added `IterTools`, grep for `ListTools`) to find every page that already discusses the area + - Decide for each hit: does it need a cross-reference, a side-by-side comparison, or to stay untouched? + +4. **Decide where new content lives**: + - Prefer extending an existing page over creating a new one + - For a docs site, place new sections near related content (check the page's `## Heading` outline first) + - Skip surfaces that genuinely don't apply (e.g. a server-focused README for a client-only change) and say so explicitly + +5. **Draft the updates**: + - Lead with a one-sentence statement of what's new and why + - Show concrete code examples copied from real signatures — verify against the source files + - Include a comparison / "when to use which" table when adding an alternative to an existing API + - Note backwards-compatibility behaviour if relevant + +6. **Verify the docs build** before committing: + - For vocs / docusaurus / mkdocs sites, run the local build command (e.g. `npx vocs build`, `mkdocs build`) and fix any MDX/markdown errors + - For godoc, run `go vet ./...` and `go doc <pkg> <Symbol>` to sanity-check rendering + +7. **Report**: + - List every file changed and every file deliberately left alone (with a one-line reason) + - Suggest the next step (typically `/commit-push`) — do not auto-commit unless asked + +## Guidelines + +- Read the diff before writing anything — invented API names erode trust faster than missing docs +- One change per doc commit; keep doc updates separate from code changes when possible +- Match the existing voice and formatting of each surface (headings, code-fence languages, table styles) +- Prefer linking between pages over duplicating content + +$@