pi-orchestrator-config 4.1.5

package/prompts/query-db.md

@@ -0,0 +1,154 @@
+---
+description: Query the reviews database for analytics and insights
+argument-hint: "<query>"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+# Review Database Query Command
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior, or reproducible bug
+> while executing this command — DO NOT work around it silently. Ask the user:
+> "Should I create a GitHub issue for this?" Route to:
+> `myk-org/pi-config` for plugin/command spec or `myk-pi-tools` CLI issues.
+> Do not silently skip steps or apply manual fixes that hide the root cause.
+
+Query the reviews database for analytics and insights about PR review history.
+
+## Prerequisites Check (MANDATORY)
+
+### Step 0: Check uv
+
+```bash
+uv --version
+```
+
+If not found, install from <https://docs.astral.sh/uv/getting-started/installation/>
+
+### Step 1: Check myk-pi-tools
+
+```bash
+myk-pi-tools --version
+```
+
+If not found, prompt to install: `uv tool install myk-pi-tools`
+
+## Usage
+
+```bash
+/query-db stats --by-source        # Stats by source
+/query-db stats --by-reviewer      # Stats by reviewer
+/query-db patterns --min 2         # Find duplicate patterns
+/query-db dismissed --owner X --repo Y
+/query-db query "SELECT * FROM comments WHERE status='skipped' LIMIT 10"
+/query-db find-similar < comments.json   # Find similar dismissed comments
+```
+
+## Available Queries
+
+### Stats by Source
+
+Show addressed rate by source (human vs AI reviewers):
+
+```bash
+myk-pi-tools db stats --by-source
+```
+
+### Stats by Reviewer
+
+Show statistics by individual reviewer:
+
+```bash
+myk-pi-tools db stats --by-reviewer
+```
+
+### Duplicate Patterns
+
+Find recurring dismissed suggestions:
+
+```bash
+myk-pi-tools db patterns --min 2
+```
+
+### Dismissed Comments
+
+Get all dismissed comments for a specific repo:
+
+```bash
+myk-pi-tools db dismissed --owner <owner> --repo <repo>
+```
+
+### Custom Query
+
+Run a custom SELECT query:
+
+```bash
+myk-pi-tools db query "SELECT * FROM comments WHERE status = 'skipped' ORDER BY id DESC LIMIT 10"
+```
+
+### Find Similar Comments
+
+Find comments similar to previously dismissed ones. Accepts JSON input via stdin:
+
+```bash
+echo '[{"body": "Consider adding error handling", "path": "src/main.py"}]' | myk-pi-tools db find-similar
+```
+
+Input format: JSON array of objects with `body` (required) and optionally `path` fields.
+
+Returns matches with similarity scores to help identify recurring patterns that were previously dismissed.
+
+## Database Schema
+
+**reviews table:**
+
+| Column | Type |
+|--------|------|
+| id | INTEGER PRIMARY KEY |
+| pr_number | INTEGER |
+| owner | TEXT |
+| repo | TEXT |
+| commit_sha | TEXT |
+| created_at | TEXT (ISO 8601) |
+
+**comments table:**
+
+| Column | Type |
+|--------|------|
+| id | INTEGER PRIMARY KEY |
+| review_id | INTEGER (FK -> reviews.id) |
+| source | TEXT (human/qodo/coderabbit) |
+| thread_id | TEXT |
+| node_id | TEXT |
+| comment_id | INTEGER |
+| author | TEXT |
+| path | TEXT |
+| line | INTEGER |
+| body | TEXT |
+| priority | TEXT (HIGH/MEDIUM/LOW) |
+| status | TEXT (pending/addressed/skipped/not_addressed) |
+| reply | TEXT |
+| skip_reason | TEXT |
+| posted_at | TEXT (ISO 8601) |
+| resolved_at | TEXT (ISO 8601) |
+
+## Database Location and Constraints
+
+The reviews database is located at `<project-root>/.claude/data/reviews.db`.
+
+**Query Constraints:**
+
+- Only SELECT statements and CTEs (Common Table Expressions) are allowed
+- INSERT, UPDATE, DELETE, DROP, and other modifying statements are blocked
+- This ensures the database remains read-only for analytics queries
+
+## Workflow
+
+1. Parse the raw arguments above to determine which query to run
+2. Execute the appropriate myk-pi-tools db command
+3. Present results in a clear, formatted way
+4. For natural language questions, compose the appropriate query

package/prompts/refine-review.md

@@ -0,0 +1,208 @@
+---
+description: Refine pending PR review comments with AI before submitting
+argument-hint: "[instructions]"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+# Refine Pending Review Command
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior, or reproducible bug
+> while executing this command — DO NOT work around it silently. Ask the user:
+> "Should I create a GitHub issue for this?" Route to:
+> `myk-org/pi-config` for plugin/command spec or `myk-pi-tools` CLI issues.
+> Do not silently skip steps or apply manual fixes that hide the root cause.
+
+Refines the user's pending GitHub PR review comments using AI before submitting. The user starts a review on GitHub, adds comments, then calls this command to polish and submit.
+
+## Prerequisites Check (MANDATORY)
+
+### Step 0: Check uv
+
+```bash
+uv --version
+```
+
+If not found, install from <https://docs.astral.sh/uv/getting-started/installation/>
+
+### Step 1: Check myk-pi-tools
+
+```bash
+myk-pi-tools --version
+```
+
+If not found, prompt user: "myk-pi-tools is required. Install with: `uv tool install myk-pi-tools`. Install now?"
+
+## Usage
+
+- `/refine-review https://github.com/owner/repo/pull/123`
+
+## Workflow
+
+**`PROJECT_TMP_DIR`** is the project-scoped temp directory from `getProjectTmpDir(cwd)` — all temp files go here.
+
+### Phase 1: Fetch Pending Review
+
+Parse the raw arguments above as the PR URL. If empty, abort with: "PR URL required. Usage: `/refine-review https://github.com/owner/repo/pull/123`"
+
+```bash
+myk-pi-tools reviews pending-fetch --output-dir ${PROJECT_TMP_DIR} "<PR_URL>"
+```
+
+The command saves the review data to a JSON file and outputs the file path to stdout.
+
+The JSON file contains:
+
+- `metadata`: owner, repo, pr_number, review_id, username, author, json_path
+- `comments`: array of pending review comments with id, path, line, body, diff_hunk
+- `diff`: PR diff text for context
+
+If the command fails (exit code 1), display the error and abort.
+
+Capture the output (json_path) for later phases.
+
+### Phase 2: Refine Comments
+
+For each comment in the JSON, use the PR diff context, file path, line number, and diff hunk to generate a refined version.
+
+**Refinement goals:**
+
+- Improve clarity and conciseness
+- Make comments more actionable (suggest specific fixes when possible)
+- Fix grammar and formatting
+- Add code suggestions in Markdown code blocks where appropriate
+- Preserve the original intent and technical accuracy
+- Keep the tone professional and constructive
+
+### Phase 3: Present Side-by-Side
+
+Display each comment with its refinement, numbered for reference. If a comment has no line number (file-level comment), show only the path:
+
+```text
+Comment #1 (path/to/file.py:42):
+  Original: <user's original comment>
+  Refined:  <AI-refined version>
+
+Comment #2 (src/main.py):
+  Original: <file-level comment>
+  Refined:  <AI-refined version>
+```
+
+### Phase 4: User Approval
+
+Ask the user which refinements to accept using AskUserQuestion:
+
+Options:
+
+- **Accept all** - Use all refined versions
+- **Pick specific** - Enter comment numbers to accept (e.g., "1,3,5")
+- **Keep originals** - Skip refinement, go straight to submit step
+- **Cancel** - Abort without making any changes
+- **Custom text** - Type a custom replacement for specific comments (e.g., "2: my custom comment text")
+
+If "Pick specific": ask user to enter comma-separated numbers. Validate that numbers are within range (1 to N). Ignore duplicates. Re-prompt on invalid input.
+
+If "Custom text": user provides comment number followed by their custom text. The custom text replaces the refined version for that comment.
+
+After applying custom text, re-display the affected comment(s) showing the custom text for user confirmation before proceeding to Phase 5.
+
+### Phase 5: Update JSON
+
+Update the JSON file at `json_path`:
+
+- For each accepted refinement: set `refined_body` to the refined text and `status` to `"accepted"`
+- For comments kept as original: leave `refined_body` as null and `status` as `"pending"`
+
+**Important:** Only modify `refined_body` and `status` fields on each comment. Do NOT modify the `diff`, `metadata`, or other fields — metadata is updated separately in Phase 6.
+
+### Phase 6: Submit Decision
+
+Ask the user using AskUserQuestion:
+
+> Submit the review with **Request Changes**? (yes/no)
+
+Options:
+
+- **Yes** - Submit with Request Changes
+- **No** - Keep the review pending (comments are already updated)
+
+If user chooses "Yes", ask a follow-up: "Add a review summary? (leave empty to skip)"
+
+Update the JSON metadata:
+
+- If submitting: set `submit_action` to `REQUEST_CHANGES` and `submit_summary` to the summary text (or empty string)
+- If keeping pending: do not set `submit_action`
+
+### Phase 7: Execute Updates
+
+If user chose to submit (Phase 6), run with `--submit` flag:
+
+```bash
+myk-pi-tools reviews pending-update "<json_path>" --submit
+```
+
+If user chose "No", run without `--submit`:
+
+```bash
+myk-pi-tools reviews pending-update "<json_path>"
+```
+
+This updates accepted comment bodies on GitHub and submits the review when `--submit` is provided.
+
+If the command fails, display the error. If it reports a 404, inform the user their pending review may have been submitted or deleted externally.
+
+### Phase 7b: Store Posted Comments (MANDATORY)
+
+After submitting the review (Phase 7), store the comments in the PR review database
+for future `/pr-review` cycle tracking:
+
+1. Write a JSON file with the submitted comments:
+
+```bash
+cat > ${PROJECT_TMP_DIR}/pr-review-store.json << 'EOF'
+{
+  "metadata": {"owner": "{owner}", "repo": "{repo}", "pr_number": {pr_number}, "head_sha": "{head_sha}", "author": "{author}"},
+  "comments": [
+    {
+      "thread_id": null,
+      "comment_id": null,
+      "path": "file.py",
+      "line": 42,
+      "body": "Comment body as posted (refined or original)",
+      "severity": null,
+      "posted_at": "<ISO timestamp>"
+    }
+  ]
+}
+EOF
+```
+
+1. Store to database:
+
+```bash
+myk-pi-tools pr store-pr-review ${PROJECT_TMP_DIR}/pr-review-store.json
+```
+
+**This step is MANDATORY — never skip it.** Only store if the review was actually
+submitted (user chose "Yes" in Phase 6). Skip if review was kept pending.
+
+### Phase 8: Summary
+
+Display:
+
+- Number of comments refined vs kept as original
+- Review action taken (submitted as Request Changes, or kept pending)
+- PR URL for reference
+
+---
+
+**CRITICAL RULES:**
+
+- NEVER update comments or submit the review without explicit user confirmation
+- Always show what will change before changing it
+- The user controls which refinements are accepted
+- If an API call fails with 404/422, the pending review may have been externally submitted or deleted - inform the user

package/prompts/release.md

@@ -0,0 +1,235 @@
+---
+description: Create a GitHub release with automatic changelog generation
+argument-hint: "[version]"
+---
+
+## Raw Arguments
+
+```text
+$ARGUMENTS
+```
+
+# GitHub Release Command
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior, or reproducible bug
+> while executing this command — DO NOT work around it silently. Ask the user:
+> "Should I create a GitHub issue for this?" Route to:
+> `myk-org/pi-config` for plugin/command spec or `myk-pi-tools` CLI issues.
+> Do not silently skip steps or apply manual fixes that hide the root cause.
+
+Creates a GitHub release with automatic changelog generation based on conventional commits.
+Optionally detects and updates version files before creating the release.
+
+## Prerequisites Check (MANDATORY)
+
+### Step 1: Check myk-pi-tools
+
+```bash
+myk-pi-tools --version
+```
+
+If not found, prompt to install: `uv tool install myk-pi-tools`
+
+## Usage
+
+- `/release` - Normal release (auto-detect version bump)
+- `/release 1.17.1` - Release with explicit version (skip approval)
+- `/release --dry-run` - Preview without creating
+- `/release --prerelease` - Create prerelease
+- `/release --draft` - Create draft release
+
+## Workflow
+
+**`PROJECT_TMP_DIR`** is the project-scoped temp directory from `getProjectTmpDir(cwd)` — all temp files go here.
+
+### Phase 1: Validation
+
+If `--target <branch>` was passed to the release command:
+
+```bash
+myk-pi-tools release info --target <branch>
+```
+
+If `--tag-match <pattern>` was also passed:
+
+```bash
+myk-pi-tools release info --target <branch> --tag-match <pattern>
+```
+
+Otherwise (auto-detect from current branch):
+
+```bash
+myk-pi-tools release info
+```
+
+Note: If on a version branch (e.g., `v2.10`), the command auto-detects the target
+and filters tags to that version range. No `--target` flag needed.
+
+Check validations:
+
+- Must be on default branch (or target branch if `--target` specified, or auto-detected version branch like `v2.10`)
+- Working tree must be clean
+- Must be synced with remote
+
+### Phase 2: Version Detection
+
+```bash
+myk-pi-tools release detect-versions
+```
+
+Parse the JSON output. If version files are found, store them for Phase 4.
+If no version files are detected, skip version bumping phases and continue normally.
+
+Store the detect-versions JSON output for use in Phase 4. The key fields are:
+
+- `version_files[].path` -- file path relative to repo root
+- `version_files[].current_version` -- current version string
+- `count` -- number of detected files (0 means skip version bumping)
+
+### Phase 3: Changelog Analysis & Version
+
+**Group commits by PR number first, then categorize.**
+
+1. Extract the PR number from each commit — check ALL of these locations:
+   - Subject suffix: `(#NNN)`
+   - Merge commit subject: `Merge pull request #NNN`
+   - Commit body: `(#NNN)` pattern (parenthesized only — bare `#NNN` may be an issue reference, not a PR)
+2. Group all commits that share the same PR number
+3. For each PR group, create ONE changelog entry — use the commit with the
+   highest-priority type (`feat:` > `fix:` > `refactor:` > `docs:` > `chore:`)
+   as the changelog entry. If multiple commits share the same type, use the one
+   with the most descriptive subject. Do NOT use fix-up commits as the entry.
+4. Internal fix-up commits within the same PR (e.g., `fix: address review findings (#472)`,
+   `fix: review cycle 2 (#472)`) are NOT separate entries — they are implementation
+   iterations within the parent PR
+5. Only commits WITHOUT a PR reference anywhere (subject or body) get their own entries
+
+Categorize each PR entry by the highest-priority commit type in its group:
+
+- Breaking Changes → MAJOR
+- Features (`feat:`) → MINOR
+- Bug Fixes (`fix:`), Docs (`docs:`), Maintenance (`chore:`, `refactor:`, `test:`, `ci:`) → PATCH
+
+If a PR group contains both `feat:` and `fix:` commits, categorize as `feat:` (highest priority wins).
+
+**Changelog formatting rules (MANDATORY):**
+
+1. **Use standardized emoji section headers:**
+   - `### ⚠️ Breaking Changes`
+   - `### ✨ Features`
+   - `### 🐛 Bug Fixes`
+   - `### 🏗️ Architecture`
+   - `### 📚 Documentation`
+   - `### 🔧 Maintenance`
+
+2. **Always use PR/issue references, never commit hashes:**
+   - ✅ `- **Feature name** — description (#42)`
+   - ❌ `- Feature name (c958777)`
+   - Extract PR number from merge commit messages or commit body
+   - Only fall back to commit hash if absolutely no PR/issue reference exists
+
+3. **Each entry needs a bold title + description:**
+   - ✅ `- **Date range filter** — Filter dashboard by date range with URL persistence (#141)`
+   - ❌ `- add date range filter to dashboard (#141)`
+
+4. **Semver enforcement:** If ANY `feat:` commit is present, version bump MUST be MINOR minimum, never PATCH.
+
+5. **Always append a compare link at the bottom:**
+
+   ```text
+   **Full Changelog**: https://github.com/{owner}/{repo}/compare/{last_tag}...{new_tag}
+   ```
+
+Generate changelog from the categorized commits following these rules.
+
+**Version determination:**
+
+1. If the raw arguments contain an explicit version (e.g., `1.17.1`, `2.0.0`), use it directly.
+   Skip Phase 4 (User Approval) entirely — the user already told you the version.
+2. Otherwise, determine the version bump type from the commit categories and propose a version.
+
+### Phase 4: User Approval
+
+**Skip this phase entirely if an explicit version was provided in the raw arguments.**
+
+Display the proposed release information. If version files were detected in Phase 2,
+include them in the approval prompt.
+
+**With version files:**
+
+1. **Display the changelog as regular text first** (NOT inside ask_user):
+   - Proposed version and bump type
+   - Version files to update (numbered list with current → new version)
+   - Full changelog preview
+
+2. **Then call ask_user with a SHORT question only:**
+   - Question: `Release vX.Y.Z?` (one line — no changelog, no file list)
+   - Options: `yes`, `major`, `minor`, `patch`, `exclude 1`, `exclude 2`, ..., `no`
+
+**IMPORTANT:** The ask_user question MUST be short (one line). All detailed
+information (changelog, file list) goes in the text BEFORE the ask_user call.
+The user reads the details in the chat, then sees a clean prompt to confirm.
+
+To exclude files, remove them from the list. Pass remaining file paths as
+`--files <path>` arguments to `bump-version` in Phase 5.
+
+**Without version files:**
+
+Same pattern -- display changelog as text, then short ask_user question.
+
+### Phase 5: Bump Version (if version files detected)
+
+Skip this phase if no version files were detected in Phase 2.
+
+Run the bump command with the confirmed version and files:
+
+```bash
+myk-pi-tools release bump-version <VERSION> --files <file1> --files <file2>
+```
+
+Where `<VERSION>` is the version number without `v` prefix (e.g., `1.2.0`, not `v1.2.0`).
+
+Parse the JSON output from bump-version. Only stage the files listed in the
+`updated[]` array. If `skipped[]` is non-empty, inform the user which files were
+skipped and why before proceeding.
+
+**Delegate git and GitHub operations to specialist agents:**
+
+1. **Delegate to `git-expert`:** Create branch, stage files, sync lockfile, commit, push:
+   - Create branch: `chore/bump-version-<VERSION>-$(date +%s)` from current HEAD
+   - Stage the updated version files
+   - If `uv.lock` exists: run `uv lock` then stage `uv.lock`
+   - Commit with message: `chore: bump version to <VERSION>`
+   - Push the branch
+   - **Important:** The branch creation and commit MUST be in separate bash calls
+     (enforcement checks branch before execution)
+
+2. **Delegate to `github-expert`:** Create PR and merge:
+   - Create PR: title `chore: bump version to <VERSION>`, base `<target_branch>`
+   - Merge with `--merge --admin --delete-branch`
+   - If admin merge fails (permission denied): ask user to merge manually,
+     wait for confirmation, verify PR state is MERGED
+   - If other errors: abort the release
+
+3. **Delegate to `git-expert`:** Sync local target branch:
+   - Checkout `<target_branch>` and pull from origin
+
+### Phase 6: Create Release
+
+Create a temp file with cleanup, write changelog to it, and create release:
+
+```bash
+CHANGELOG_FILE=$(mktemp ${PROJECT_TMP_DIR}/release-XXXXXX.md)
+trap "rm -f $CHANGELOG_FILE" EXIT
+
+cat > "$CHANGELOG_FILE" << 'EOF'
+<changelog content from Phase 3>
+EOF
+
+myk-pi-tools release create {owner}/{repo} {tag} "$CHANGELOG_FILE" [--prerelease] [--draft] [--target {target_branch}]
+```
+
+### Phase 7: Summary
+
+Display release URL and summary.
+If version files were bumped, include the list of updated files in the summary.

package/prompts/remember.md

@@ -0,0 +1,33 @@
+---
+description: "Save a memory for future sessions — /remember <what to remember>"
+argument-hint: "<what to remember>"
+---
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior,
+> or reproducible bug while executing this command — DO NOT work around it
+> silently. Ask the user: "Should I create a GitHub issue for this?"
+> Route to `myk-org/pi-config` for prompt/extension issues,
+> or to the relevant tool's repository for CLI issues.
+
+## What to remember
+
+```text
+$ARGUMENTS
+```
+
+Save this as a **Pinned** project memory. Determine the best category:
+
+- `lesson` — something learned (how things work, gotchas, tips)
+- `decision` — an architectural or design choice made
+- `mistake` — something that went wrong and should be avoided
+- `pattern` — a recurring approach or convention
+- `done` — a completed task or milestone
+- `preference` — user preference for how things should be done
+
+Run:
+
+```bash
+uv run myk-pi-tools memory add -c <category> -s "<concise one-line summary>" --pinned
+```
+
+After saving, confirm what was stored.

package/prompts/review-handler-status.md

@@ -0,0 +1,27 @@
+---
+description: "Show live status of running review-handler agents — /review-handler-status"
+---
+
+## Raw Arguments
+
+$ARGUMENTS
+
+## Review Handler Status
+
+> **Bug Reporting Policy:** If you encounter ANY error, unexpected behavior, or reproducible bug
+> while executing this command — DO NOT work around it silently. Ask the user:
+> "Should I create a GitHub issue for this?" Route to `myk-org/pi-config` for prompt/extension issues,
+> or to the relevant tool's repository for CLI issues.
+
+Show the live state of running autoqodo/autorabbit review-handler agents.
+
+### Steps
+
+1. Run `/async-status`. Look for agents whose task contains `reviews poll`.
+   If none found → "No review handler agents running — nothing to show."
+
+2. For each running review agent, extract the PR number from the agent's task or worktree cwd.
+   Run `myk-pi-tools reviews status --output-dir ${PROJECT_TMP_DIR} --pr <number>` to generate the HTML report.
+   Extract the path from `HTML report saved: <path>` in the output.
+   - **Container** (`/.dockerenv` or `/run/.containerenv` exists): serve via file preview rule (`rules/45-file-preview.md`)
+   - **Native**: show `file://<path>`