@groupby/ai-dev 0.5.4 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Interactive installer for Rezolve Ai development content",
   "type": "module",
   "bin": {

package/teams/fhr-core/skills/address-pr/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: address-pr
+description: Work through unresolved GitHub PR review threads on the current branch — fix valid findings in code and reply to invalid ones with an explanation. Use when the user wants to address review comments, respond to PR feedback, or run "/address-pr".
+arguments: pr-number (optional)
+---
+
+# Address PR
+
+Work through unresolved GitHub PR review threads: fix the valid ones in code, and reply to the invalid ones with a clear explanation.
+
+Argument: `$ARGUMENTS` — optional. Pass the PR number to target a specific PR; omit it to auto-detect from the current branch.
+
+## Quick start
+
+```
+/address-pr
+```
+
+## Step 1: Find the PR
+
+If a PR number was passed in `$ARGUMENTS`, substitute it for `<PR_NUMBER>` in the commands below; otherwise omit `<PR_NUMBER>` entirely and `gh` auto-detects the PR from the current branch:
+
+```bash
+gh pr view <PR_NUMBER> --json number,url,title,headRefName
+gh repo view --json owner,name --jq '.owner.login, .name'   # first line = <OWNER>, second = <REPO>
+```
+
+Extract the PR number and `headRefName`. If no open PR exists, stop and report.
+
+Make sure the working tree is on the PR's branch before changing any code — fixes must land on the right branch:
+```bash
+git checkout <headRefName>
+git pull
+```
+
+## Step 2: Fetch unresolved review threads
+
+```bash
+gh api graphql -f query='
+  query($owner: String!, $repo: String!, $number: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $number) {
+        reviewThreads(first: 100) {
+          nodes {
+            id
+            isResolved
+            isOutdated
+            comments(first: 10) {
+              nodes { id databaseId body path line author { login } createdAt }
+            }
+          }
+        }
+      }
+    }
+  }
+' -f owner=<OWNER> -f repo=<REPO> -F number=<PR_NUMBER>
+```
+
+Keep threads where `isResolved` is `false`. Skip threads where `isOutdated` is `true` — they reference lines that have since changed and no longer block review.
+
+If there are no unresolved threads, report "No open review threads" and stop.
+
+## Step 3: Evaluate each unresolved thread
+
+Read the full comment text and load the referenced file at the path/line for context. Decide for each thread:
+- **Valid** — a real problem or improvement that is technically correct and appropriate for this codebase.
+- **Invalid** — based on a misunderstanding, would be incorrect, or does not apply.
+
+## Step 4: Apply fixes for valid findings
+
+Apply each fix in the most specific module that owns the code (respect the `architecture.md` module boundaries). Collect all code changes, then run the tests for each affected module. Skip the build for docs/config-only changes (e.g. `suggest-docs`, `*.adoc`, `*.md`) — there is nothing to test:
+
+```bash
+# Unit tests for an affected module (with upstream deps built):
+mvn -pl <module> -am test
+
+# Acceptance tests — run if an acceptance test module exists in the repository (e.g. suggest-tests):
+mvn -pl suggest-tests verify
+
+# Full build / static analysis before merge:
+mvn -P verify-project verify
+```
+
+If tests fail, fix the failure before proceeding.
+
+## Step 5: Commit and push (only if code changed)
+
+```bash
+git add <changed files>
+git commit -m "FHR-<number>: address review feedback"
+git push
+```
+
+Confirm with the user before pushing.
+
+## Step 6: Reply to all threads
+
+`<MODEL_NAME>` is the model powering this session (e.g., "Sonnet 4.6", "Opus 4.8") and `<MODEL_SLUG>` is its URL slug (e.g., "sonnet", "opus", "haiku") — substitute from your system context.
+
+For each **valid** thread that was fixed:
+```bash
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments \
+  --method POST \
+  --field body="Fixed — <one-sentence summary of the change made>.
+
+🤖 Addressed by [Claude <MODEL_NAME>](https://www.anthropic.com/claude/<MODEL_SLUG>)" \
+  --field in_reply_to=<FIRST_COMMENT_DATABASE_ID>
+```
+
+For each **invalid** thread:
+```bash
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/comments \
+  --method POST \
+  --field body="<Clear, professional explanation of why no change is needed.>
+
+🤖 Addressed by [Claude <MODEL_NAME>](https://www.anthropic.com/claude/<MODEL_SLUG>)" \
+  --field in_reply_to=<FIRST_COMMENT_DATABASE_ID>
+```
+
+Use the `databaseId` of the first comment in each thread as `in_reply_to`.
+
+## Step 7: Report
+
+Summarise how many threads were fixed (with code changes), how many received a reply (no change), any that need manual attention, and the commit SHA if code was pushed.
+
+## Constraints
+
+- Never push without explicit user confirmation.
+- Fix failing tests before moving on — do not push a broken build.

package/teams/fhr-core/skills/plan-spec/SKILL.md

@@ -2,6 +2,7 @@
 name: plan-spec
 description: Read a spec file and produce a detailed design and implementation plan — with BDD acceptance tests and TDD test cases per task — written into the spec's "Design and Implementation Plan" section, then committed. Use when user references a spec file and wants a plan, implementation design, or test specifications derived from requirements.
 arguments: spec-file
+model: claude-opus-4-8
 ---
 
 # Plan Spec

package/teams/fhr-core/skills/ready-pr/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ready-pr
+description: Check that all GitHub PR review threads are resolved, then promote the PR from draft to ready for review. Stops with a clear message if any unresolved threads remain. Use when the user wants to mark a PR ready, promote a draft, or run "/ready-pr".
+arguments: pr-number (optional)
+---
+
+# Ready PR
+
+Check the PR's review threads. If all are resolved, mark the PR ready for review. If any are still open, stop and say what to do.
+
+Argument: `$ARGUMENTS` — optional. Pass the PR number to target a specific PR; omit it to auto-detect from the current branch.
+
+## Quick start
+
+```
+/ready-pr
+```
+
+## Step 1: Find the PR
+
+If a PR number was passed in `$ARGUMENTS`, substitute it for `<PR_NUMBER>` in the commands below; otherwise omit `<PR_NUMBER>` entirely and `gh` auto-detects the PR from the current branch:
+
+```bash
+gh pr view <PR_NUMBER> --json number,url,title,isDraft,state
+gh repo view --json owner,name --jq '.owner.login, .name'   # first line = <OWNER>, second = <REPO>
+```
+
+Stop and report if any of these hold — do not continue:
+- No PR is found.
+- `state` is not `OPEN` (the PR is merged or closed — there is nothing to promote).
+- `isDraft` is `false` (the PR is already marked ready for review).
+
+## Step 2: Check for unresolved review threads
+
+```bash
+gh api graphql -f query='
+  query($owner: String!, $repo: String!, $number: Int!) {
+    repository(owner: $owner, name: $repo) {
+      pullRequest(number: $number) {
+        reviewThreads(first: 100) {
+          nodes {
+            isResolved
+            isOutdated
+            comments(first: 1) {
+              nodes { body path line author { login } }
+            }
+          }
+        }
+      }
+    }
+  }
+' -f owner=<OWNER> -f repo=<REPO> -F number=<PR_NUMBER>
+```
+
+Keep threads where `isResolved` is `false` AND `isOutdated` is `false`. Outdated threads do not block readiness.
+
+## Step 3: If unresolved threads exist — STOP
+
+Report and do nothing further:
+
+> **Not ready:** N unresolved review thread(s) remain:
+>
+> - `path:line` — "comment text" (by @reviewer)
+> - …
+>
+> Run `/address-pr` to fix or reply to each thread, or resolve them manually on GitHub, then run `/ready-pr` again.
+
+## Step 4: If all threads are resolved — mark ready
+
+```bash
+gh pr ready <PR_NUMBER>
+```
+
+Report the PR URL and confirm it is now ready for review.

package/teams/fhr-core/skills/refine-spec/SKILL.md

@@ -2,6 +2,7 @@
 name: refine-spec
 description: Conduct a structured requirements-refinement interview against a spec file, using the project's ubiquitous language from glossary.md, until scope and acceptance criteria are clear, then update the spec file in place. Use when user references a spec file and wants to clarify requirements, define scope, or sharpen acceptance criteria — but not write code or tests.
 arguments: spec-file
+model: claude-opus-4-8
 ---
 
 # Refine Spec

package/teams/fhr-core/skills/review-pr/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: review-pr
+description: Review the current branch's GitHub PR — fetch its description and diff, compare against the spec/plan if present, and submit a GitHub PR review with inline comments for every finding. Use when the user wants to review a PR, run an AI review pass, or run "/review-pr".
+arguments: pr-number (optional)
+---
+
+# Review PR
+
+Review the open GitHub PR for this branch by acting as a code reviewer. The output is a **submitted GitHub PR review with inline comments** — not a local file.
+
+Argument: `$ARGUMENTS` — optional. Pass the PR number to review a specific PR; omit it to auto-detect from the current branch.
+
+## Quick start
+
+```
+/review-pr
+```
+
+## Step 1: Find the PR
+
+If a PR number was passed in `$ARGUMENTS`, substitute it for `<PR_NUMBER>` in the commands below; otherwise omit `<PR_NUMBER>` entirely and `gh` auto-detects the PR from the current branch:
+
+```bash
+gh pr view <PR_NUMBER> --json number,url,title,state,body,headRefName,baseRefName
+```
+
+Extract the PR number, title, description, and base branch. If no PR is found, stop and ask the user to run `/write-pr` first.
+
+Get the latest commit SHA (required to anchor inline comments):
+```bash
+gh pr view <PR_NUMBER> --json commits --jq '.commits[-1].oid'
+```
+
+## Step 2: Fetch the diff
+
+```bash
+gh pr diff <PR_NUMBER>
+gh pr view <PR_NUMBER> --json files --jq '[.files[].path]'
+```
+
+## Step 3: Load spec/plan and project standards (if available)
+
+Detect the ticket number from the branch name (pattern `FHR-\d+`).
+
+Read if present (the spec may be in any of these locations):
+- `.claude/resources/FHR-<number>-*.md`
+- `suggest-docs/src/main/docs/specs/FHR-<number>-*.md`
+- `documentation/releases/*/FHR-<number>-*.md`
+
+The plan is embedded in the spec's `## Design and Implementation Plan` section — there is no separate plan file.
+
+Also read:
+- `coding-guidelines.md`, `architecture.md`, `glossary.md` (project root) — the standards to review against.
+
+If the spec is missing, proceed and review code quality only.
+
+## Step 4: Review the PR
+
+Review the diff and PR description against `coding-guidelines.md` and `architecture.md`.
+
+**What to check:**
+
+1. **PR description accuracy** — does the body describe what actually changed? Are diagrams present and correct for complex changes?
+2. **Spec compliance** (if a spec was found) — does the implementation satisfy each acceptance criterion? Are there missing tests for any plan task?
+3. **Code quality:**
+   - Correctness and edge cases (nulls, boundary values, empty inputs)
+   - Error handling and resilience (no swallowed exceptions)
+   - Security and input validation (no injection, no hardcoded secrets)
+   - Test coverage (every new/changed conditional branch has a dedicated test)
+   - Readability, naming, complexity, duplication
+   - Architecture and module boundaries (refer to `architecture.md` for module structure and dependency rules; no circular dependencies)
+   - Domain language matches `glossary.md`
+   - Logging and observability (no secrets or PII in logs)
+
+**For each finding, record:**
+- `path` — relative file path in the repo
+- `line` — absolute line number in the new version of the file
+- `side` — always `"RIGHT"` for added or unchanged lines
+- `severity` — `BLOCKER` | `MAJOR` | `MINOR` | `NIT`
+- `body` — comment text prefixed with the severity tag, e.g. `BLOCKER: Missing null check. Add a guard before line 42.`
+
+Only raise a finding if the evidence is clear from the diff. Do not speculate about code you cannot see.
+
+**Inline comments can only anchor to lines that are part of the PR's diff hunks** (added or directly-adjacent context lines). The GitHub reviews API rejects the whole submission (HTTP 422) if any comment targets a line outside the diff. If a finding concerns an unchanged line, put it in the review `body` instead of inline.
+
+## Step 5: Submit the GitHub PR review
+
+Get the owner and repo (printed on separate lines — the first is `<OWNER>`, the second is `<REPO>`):
+```bash
+gh repo view --json owner,name --jq '.owner.login, .name'
+```
+
+Choose the review `event` from the highest finding severity:
+- `REQUEST_CHANGES` — at least one `BLOCKER` or `MAJOR` finding (these block the PR).
+- `COMMENT` — only `MINOR`/`NIT` findings (non-blocking, so the severity tags carry weight).
+
+Submit the full review in a single API call:
+```bash
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/reviews \
+  --method POST \
+  --field commit_id=<LATEST_COMMIT_SHA> \
+  --field body="Review: <N> finding(s) — <X> blocker(s), <Y> major, <Z> minor, <W> nit(s)." \
+  --field event="<REQUEST_CHANGES or COMMENT>" \
+  --raw-field comments='[
+    {"path":"suggest-api/src/main/java/Foo.java","line":42,"side":"RIGHT","body":"BLOCKER: …"},
+    {"path":"suggest-lucene/src/main/java/Bar.java","line":17,"side":"RIGHT","body":"MINOR: …"}
+  ]'
+```
+
+If a finding cannot be anchored to a specific file line (e.g. a description-level issue), include it in the review `body` instead of as an inline comment.
+
+If there are **no findings**, approve:
+```bash
+gh api repos/<OWNER>/<REPO>/pulls/<PR_NUMBER>/reviews \
+  --method POST \
+  --field body="LGTM — all quality gates pass." \
+  --field event="APPROVE"
+```
+
+## Step 6: Report
+
+Output the PR URL, the review decision (`REQUEST_CHANGES` or `APPROVE`), finding counts by severity, and any findings placed in the review body rather than inline.

package/teams/fhr-core/skills/tdd-green/SKILL.md

@@ -2,6 +2,7 @@
 name: tdd-green
 description: Implement production code (green phase) for the next incomplete task in a spec file's Design and Implementation Plan, writing only enough code to make the failing tests pass, then refactor while keeping tests green, mark the Production code sub-task done, and commit the green and refactor work separately. Use when user references a spec file and wants to implement a feature, or says "green phase", "make tests pass", "tdd green", or "green and refactor".
 arguments: spec-file
+model: claude-haiku-4-5-20251001
 ---
 
 # TDD Green

package/teams/fhr-core/skills/tdd-red/SKILL.md

@@ -2,6 +2,7 @@
 name: tdd-red
 description: Write failing tests (red phase) for the next incomplete task in a spec file's Design and Implementation Plan — acceptance tests (JGiven BDD) and unit tests (JUnit Jupiter) — then mark the Acceptance tests and Unit tests sub-tasks done and commit. Use when user references a spec file and wants to write the failing tests before implementing a feature, or says "red phase", "write tests", or "tdd red".
 arguments: spec-file
+model: claude-haiku-4-5-20251001
 ---
 
 # TDD Red

package/teams/fhr-core/skills/tdd-workflow/SKILL.md

@@ -2,6 +2,7 @@
 name: tdd-workflow
 description: Drive the full red-green-refactor TDD cycle across every task in a spec file's Design and Implementation Plan — picking the next incomplete task, then running the red, green, and refactor phases for it, then looping to the next task until the plan is complete. Use when user references a spec file and wants to implement the whole plan end to end, or says "run the tdd workflow", "implement the plan", or "tdd workflow".
 arguments: spec-file
+model: claude-haiku-4-5-20251001
 ---
 
 # TDD Workflow

package/teams/fhr-core/skills/write-pr/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: write-pr
+description: Render the repo PR template from the current branch's diff, and create (or update) a draft GitHub PR. Use when the user wants to open a PR, write a PR description, or run "/write-pr" on a branch.
+arguments: extra-context (optional)
+---
+
+# Write PR
+
+Render the `.github/pull_request_template.md` from the current branch's changes and open a **draft** GitHub PR. PRs are always created as drafts — use `/ready-pr` to promote them once review is complete.
+
+Argument: `$ARGUMENTS` — optional free text treated as extra context for the description.
+
+## Quick start
+
+```
+/write-pr
+```
+
+## Workflow
+
+1. **Detect the ticket and diff**
+   - Read the ticket number from the branch name (pattern `FHR-\d+`). If the branch name has no ticket, ask the user for the ticket number before continuing.
+   - Make sure the branch is committed — `git diff origin/master...HEAD` only shows committed work, not uncommitted or untracked files. Get the diff vs `master`:
+     ```bash
+     git diff origin/master...HEAD --stat
+     git diff origin/master...HEAD
+     ```
+
+2. **Render the template** — fill in `.github/pull_request_template.md`:
+   - Set the Jira link to `https://attraqt.atlassian.net/browse/FHR-<number>`.
+   - Tick the AI Development Checklist items that genuinely apply (spec present, tests present, docs present, AI review pass, etc.). Leave unticked anything not yet true.
+   - Prepend a `## Summary of changes` section (the template has no such section) describing what changed and why.
+
+4. **Approve before publishing** — present the title and rendered body and wait for explicit approval. Support correction cycles.
+
+5. **Publish** — write the approved body to a temp file (e.g. `pr-body.md`), then with confirmation push the branch and create or update the draft PR:
+   ```bash
+   gh pr create --draft --title "FHR-<number>: <Title>" --body-file pr-body.md
+   # or, if a PR already exists for this branch (omit the number — gh auto-detects it):
+   gh pr edit --title "FHR-<number>: <Title>" --body-file pr-body.md
+   ```
+   Delete the temp file afterwards and report the PR URL.
+
+## Constraints
+
+- Always create the PR as a **draft**.
+- Never push without explicit user confirmation.
+- The title MUST match `FHR-<number>: <description>` — the `pull-request.yml` CI check fails otherwise.
+- Only tick checklist items that are actually true.