@groupby/ai-dev 0.5.4 → 0.5.7

package/package.json

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

package/teams/OOF/skills/jira-ticket-creator/README.md

@@ -0,0 +1,22 @@
+# Jira Ticket Creator
+
+Creates well-structured Jira epics, stories, and sub-tasks from product and 
+technical specifications using the Atlassian MCP connector.
+
+## What it does
+- Reads product and/or technical specs from Confluence
+- Plans Epics → Stories → Sub-tasks hierarchy
+- Previews all ticket content for approval before creating anything in Jira
+- Creates tickets with correct parent relationships and team assignments
+
+## Prerequisites
+- Atlassian MCP connector connected
+- Write access to the target Jira project
+
+## Trigger phrases
+- "Create Jira tickets from this spec"
+- "Break this PRD into epics and stories"
+- "Generate Jira tickets from this Confluence page"
+
+## Team
+OOF

package/teams/OOF/skills/jira-ticket-creator/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: jira-ticket-creator
+description: Create Jira epics, stories and sub-tasks from product and technical specifications. Use this skill whenever a user asks to create epics, stories, sub-tasks, or tickets in Jira from a spec, PRD, product specification, technical specification, or Confluence page. Also trigger when a user says things like "break this spec into epics", "create Jira tickets from this document", "plan this initiative into stories", "generate epics for this project", or any request involving turning requirements or specifications into structured Jira work items. Requires the Atlassian MCP connector.
+---
+
+# Jira Ticket Creator
+
+Creates well-structured Jira epics, stories and sub-tasks from product and technical specifications, using the Atlassian MCP connector.
+
+## Prerequisites
+
+- **Atlassian MCP connector** must be connected. If not connected, prompt the user to connect it before proceeding.
+- The user must have write access to the target Jira project.
+
+---
+
+## Configuration Parameters
+
+Collect ALL mandatory parameters before creating any tickets. Present them clearly and confirm with the user before proceeding.
+
+### Mandatory Parameters
+
+| Parameter | Description | Validation |
+|---|---|---|
+| **Jira Team** | The Jira team to assign to ALL tickets. The user MUST choose one of the two fixed options below. | Required. Present as a two-choice selection. Do not advance until the user selects a team. |
+| **Parent** | The Jira initiative key that all epics will be children of (e.g. `BD-7711`). | Required. Must be a valid Jira issue key. Do not advance until provided. |
+| **Product Specification** | A Confluence page URL containing the product spec / PRD. | Required. Must be a valid Confluence URL. Do not advance until provided. |
+
+**Jira Team options** (offer these two as selectable choices — do NOT ask the user to type a free-text team name):
+
+| Team name | Team ID (`customfield_10700` value) |
+|---|---|
+| **OOF Mobile Solution Team** | `b3f517d4-c4f8-4144-8920-b762ec5a033b` |
+| **OOF Application Solution Team** | `9817d9ca-6170-48e8-9e98-1aeb7c81daa5` |
+
+### Optional Parameters
+
+| Parameter | Description | Default |
+|---|---|---|
+| **Technical Specification** | A Confluence page URL containing the technical spec. | None — if not supplied, generate tickets from the product spec only. |
+| **Epic Number** | Maximum number of epics to produce. | LLM decides based on the scope of the specification. |
+| **Ticket Style** | A URL pointing to a Confluence page with guidelines for how to write/format tickets. Always offer the user the choice to accept the default page or enter a new URL. | `https://rezolvetech.atlassian.net/wiki/spaces/CPST/pages/5303500826/Definition+of+user+story+acceptance+criteria` |
+| **Sub Tasks** | Whether to create sub-tasks under each story. `yes` or `no`. | `no` — do not create sub-tasks unless explicitly set to `yes`. |
+
+---
+
+## Workflow
+
+### Step 1 — Collect and Confirm Configuration
+
+**Always ask the user for the configuration values interactively before doing anything else.** Go through the parameters **one at a time, in order**. For each parameter:
+
+- State the parameter name and a short description.
+- Show its **default value** (or `None` / `LLM decides` where there is no fixed default).
+- Offer the user the choice to **accept the default** or **enter a new value**. Use interactive options where possible (e.g. an "Accept default" choice alongside a free-text input).
+- **For mandatory parameters (Jira Team, Parent, Product Specification), you MUST NOT advance to the next parameter until the user supplies a value.** If the user leaves it blank, skips, or gives an empty answer, re-ask the SAME parameter and keep asking until a value is provided.
+- For **Jira Team**, present the two fixed options (**OOF Mobile Solution Team** and **OOF Application Solution Team**) as a selectable choice. Do NOT accept or ask for a free-text team name. Map the chosen team to its ID for the `customfield_10700` field.
+- For **Ticket Style**, always present an explicit choice to **accept the default Confluence page** or **enter a new ticket style URL**.
+
+Use a prompt along these lines, asking for one value at a time:
+
+> Let's set up the configuration. For each item, reply **"default"** to accept the shown default, or type a new value.
+>
+> | # | Parameter | Mandatory | Default value |
+> |---|---|---|---|
+> | 1 | **Jira Team** | Yes | None — choose **OOF Mobile Solution Team** or **OOF Application Solution Team** |
+> | 2 | **Parent** | Yes | None — please provide (e.g. `BD-7711`) |
+> | 3 | **Product Specification** | Yes | None — please provide a Confluence URL |
+> | 4 | **Technical Specification** | No | None (skipped if blank) |
+> | 5 | **Epic Number** | No | LLM decides based on spec scope |
+> | 6 | **Ticket Style** | No | `https://rezolvetech.atlassian.net/wiki/spaces/CPST/pages/5303500826/Definition+of+user+story+acceptance+criteria` |
+> | 7 | **Sub Tasks** | No | `no` |
+
+Once all values are collected, **display a summary table of the final configuration** — indicating for each parameter whether the default was accepted or a custom value was entered — and ask the user to confirm before proceeding.
+
+### Step 2 — Read the Specifications
+
+Use the Atlassian MCP connector to read the Confluence pages:
+
+1. **Read the Product Specification** from the supplied Confluence URL. This is the primary source of requirements.
+2. **Read the Technical Specification** (if supplied) from the Confluence URL. This supplements the product spec with implementation details.
+3. **Read the Ticket Style guide** from the Ticket Style URL. This defines how to format epic descriptions, story titles, acceptance criteria, and other ticket fields.
+
+If any page cannot be read, inform the user and ask for a corrected URL.
+
+### Step 3 — Jira Field Reference
+
+Use the following Jira field IDs and exact payload formats when creating tickets in the BD project. The `parent` field MUST be passed as an object (`{ "key": "..." }`), never as a bare string — passing a string is the usual cause of "can't find / invalid parent field" errors.
+
+1. **Team field** — custom field `customfield_10700` (Atlassian Team field type). It is **mandatory** on every ticket. Set it to the **ID** of the configured **Jira Team** as a **bare string**, e.g. `"customfield_10700": "b3f517d4-c4f8-4144-8920-b762ec5a033b"`. Use the ID, never the team name. **Do NOT wrap the ID in an object** (e.g. `{ "id": "..." }`) — although the field reads back as an object, on write the API rejects the object form with `Team id 'JsonData{data={id=...}}' is not valid`. Pass the raw ID string only:
+   - **OOF Mobile Solution Team** → `b3f517d4-c4f8-4144-8920-b762ec5a033b`
+   - **OOF Application Solution Team** → `9817d9ca-6170-48e8-9e98-1aeb7c81daa5`
+2. **Epic → parent initiative** — standard `parent` field: `"parent": { "key": "BD-7711" }` (substitute the configured **Parent** initiative key).
+3. **Story → parent epic** — standard `parent` field set to the epic's key: `"parent": { "key": "<EPIC-KEY>" }`.
+4. **Sub-task → parent story** — standard `parent` field: `"parent": { "key": "<STORY-KEY>" }`.
+
+All ticket content must be derived exclusively from the Product Specification and Technical Specification provided by the user.
+
+### Step 4 — Plan the Epics and Stories
+
+Based on the specifications and ticket style guide, plan the breakdown:
+
+1. **Identify logical epic groupings** from the product spec. Each epic should represent a coherent feature area or workstream.
+2. If **Epic Number** is set, constrain to that maximum. If not set, choose the number that best represents the natural groupings in the spec.
+3. For each epic, identify the user stories needed. Stories should be independently deliverable increments of work.
+4. If **Sub Tasks** is `yes`, further decompose each story into sub-tasks (implementation steps, testing, etc.).
+
+**Present the full plan to the user as a high-level tree for initial structural review:**
+
+```
+Epic 1: [Title]
+  ├── Story 1.1: [Title]
+  ├── Story 1.2: [Title]
+  └── Story 1.3: [Title]
+
+Epic 2: [Title]
+  ├── Story 2.1: [Title]
+  └── Story 2.2: [Title]
+  ...
+```
+
+Ask the user: **"Does this structure look right? Should I add, remove, merge, or split any epics or stories before I draft the full ticket content?"**
+
+Wait for approval or iterate on the structure until the user is satisfied.
+
+### Step 5 — Preview Full Ticket Content
+
+**CRITICAL: Do NOT create any tickets in Jira until the user explicitly approves the content in this step.**
+
+Once the structure is approved, draft the **complete content** for every ticket and present it to the user for review. Show each ticket exactly as it will be created, including all fields:
+
+#### For each Epic, show:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+EPIC: [Title]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Type:        Epic
+Team:        [configured team]
+Parent:      [configured initiative key]
+Summary:     [epic title]
+Description:
+  📄 Product Spec: [Confluence URL]
+  📄 Tech Spec: [Confluence URL or N/A]
+
+  [Full epic description per Ticket Style guide]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+#### For each Story, show:
+
+```
+──────────────────────────────────────
+  STORY under [Epic Title]: [Story Title]
+──────────────────────────────────────
+  Type:        Story
+  Team:        [configured team]
+  Epic:        [parent epic title]
+  Summary:     [story title]
+  Description:
+    📄 Product Spec: [Confluence URL]
+    📄 Tech Spec: [Confluence URL or N/A]
+
+    [Full story description per Ticket Style guide]
+
+    Acceptance Criteria:
+    [Full acceptance criteria per Ticket Style guide]
+──────────────────────────────────────
+```
+
+#### For each Sub-Task (if Sub Tasks = yes), show:
+
+```
+  · SUB-TASK under [Story Title]: [Sub-task Title]
+    Type:        Sub-task
+    Team:        [configured team]
+    Parent:      [parent story title]
+    Summary:     [sub-task title]
+    Description: [sub-task details]
+```
+
+After presenting ALL ticket content, ask the user:
+
+> **"Here is the full content for all tickets I'm about to create. Please review and let me know:**
+> - **Approve** — create all tickets as shown
+> - **Edit** — tell me which tickets to change and what to modify
+> - **Cancel** — abort without creating anything"
+
+**Do NOT proceed to Step 6 until the user explicitly says to approve / go ahead / create.** If the user requests edits, make the changes, re-display the affected tickets, and ask for approval again. Repeat until approved.
+
+### Step 6 — Create Tickets in Jira
+
+**Only execute this step after the user has explicitly approved the ticket content in Step 5.**
+
+Use the Atlassian MCP connector to create the tickets. Follow this order:
+
+#### 6a. Create Epics
+
+For each epic, create it using the exact content approved in Step 5:
+
+- **Issue Type**: Epic
+- **Summary**: As approved
+- **Description**: As approved — Product Spec link at top, Tech Spec link if supplied, full description per Ticket Style
+- **Team**: Set the `customfield_10700` field to the **ID** of the configured Jira Team (mandatory)
+- **Parent**: Set via the standard `parent` field as an object — `"parent": { "key": "<INITIATIVE-KEY>" }` (the user-supplied initiative key)
+
+#### 6b. Create Stories
+
+For each story, create it using the exact content approved in Step 5:
+
+- **Issue Type**: Story
+- **Summary**: As approved
+- **Description**: As approved — Product Spec link at top, Tech Spec link if supplied, acceptance criteria and context per Ticket Style
+- **Team**: Same team as the epics, set via `customfield_10700` to the selected team's ID (mandatory)
+- **Parent**: Set via the standard `parent` field as an object — `"parent": { "key": "<EPIC-KEY>" }` (the epic created in step 6a)
+
+#### 6c. Create Sub-Tasks (only if Sub Tasks = yes)
+
+For each sub-task, create it using the exact content approved in Step 5:
+
+- **Issue Type**: Sub-task
+- **Summary**: As approved
+- **Description**: As approved
+- **Team**: Same team as the epics, set via `customfield_10700` to the selected team's ID (mandatory)
+- **Parent**: Set via the standard `parent` field as an object — `"parent": { "key": "<STORY-KEY>" }` (the parent story)
+
+### Step 7 — Report Results
+
+After all tickets are created, present a summary:
+
+1. A table of all created tickets with their keys, titles, types, and parent relationships
+2. Direct links to each ticket
+3. A link to the parent initiative showing the new epics
+4. Any tickets that failed to create, with error details
+
+---
+
+## Ticket Content Rules
+
+These rules apply to ALL tickets (epics, stories, and sub-tasks):
+
+1. **Jira Team field is mandatory.** Set it on every ticket (epic, story, sub-task) using the **ID** of the team the user selected (`OOF Mobile Solution Team` → `b3f517d4-c4f8-4144-8920-b762ec5a033b`, `OOF Application Solution Team` → `9817d9ca-6170-48e8-9e98-1aeb7c81daa5`) via `customfield_10700`.
+2. **Product Specification link** must appear at the top of every story description and every epic description. Format as a clickable Confluence link.
+3. **Technical Specification link** (if provided) must appear directly below the product spec link in every description.
+4. **All epics must be children of the parent initiative.** Use the Jira parent field, not just a link.
+5. **Follow the Ticket Style guide** for all content — titles, descriptions, acceptance criteria, and formatting.
+6. **Respect the Epic Number** constraint. If a max is set, do not exceed it. Consolidate related work into fewer epics if needed.
+
+---
+
+## Error Handling
+
+- If the Atlassian MCP connector is not connected, stop and ask the user to connect it.
+- If a Confluence page cannot be read, report the error and ask for a corrected URL.
+- If a ticket fails to create, log the error, continue with remaining tickets, and report all failures at the end.
+- If the selected team's ID is rejected by Jira, report this and confirm the user's team choice before retrying.
+- If the parent initiative key is invalid, report this and ask for correction.
+
+---
+
+## Tips for Best Results
+
+- Provide a detailed product specification — the more complete the spec, the better the epic/story breakdown.
+- Adding a technical specification helps generate more accurate implementation-focused stories.
+- Use the Epic Number parameter to control granularity — fewer epics means broader groupings, more means finer-grained.
+- Review the structure in Step 4 and the full ticket content in Step 5 carefully — nothing is created in Jira until you explicitly approve.

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.

package/teams/snpd/skills/code-review-github/SKILL.md

@@ -0,0 +1,475 @@
+---
+name: code-review-github
+description: Use when the user wants to add Claude Code Agent + GitHub Copilot AI tooling to a repository — automatic PR code review, on-demand `@claude` assistance, a Copilot setup workflow, a structured PR template, and AI context files (`CLAUDE.md`, `.github/copilot-instructions.md`, `docs/*`). Triggered by `/code-review-github` or requests like "set up Claude PR review", "add the AI agent setup", "configure the copilot workflows", "bootstrap AI agents in this repo". Originally built for GroupBy Java/Micronaut repos but adapts to any stack.
+---
+
+# code-review-github
+
+Bootstrap a repository with the standard Claude Code Agent + GitHub Copilot
+setup: GitHub Actions for automatic PR review and `@claude` assistance, a
+Copilot environment-setup workflow, a PR template with an AI checklist, and the
+AI context files agents read on every session.
+
+This skill is **self-contained** — every file template lives below, verified
+against a working reference implementation. Do not fetch anything external.
+
+## What this setup provides
+
+| Capability | Tool | Trigger |
+|---|---|---|
+| Automatic PR code review | Claude Code | PR opened |
+| On-demand AI assistance | Claude Code | `@claude` in PR comment |
+| Copilot workspace environment | GitHub Copilot | workflow_dispatch / file change |
+| Structured PR descriptions | PR template | PR creation |
+| AI context for IDE Copilot | `copilot-instructions.md` | IDE session |
+| AI context for Claude | `CLAUDE.md` | Claude session |
+
+## Files this skill creates or updates
+
+| # | File | Action | Project-specific? |
+|---|---|---|---|
+| 1 | `.github/workflows/claude.yml` | Create | No — copy verbatim |
+| 2 | `.github/workflows/claude-pr-review.yml` | Create | Yes — tune review prompt |
+| 3 | `.github/workflows/copilot-setup-steps.yml` | Create | Yes — match build/runtime |
+| 4 | `.github/PULL_REQUEST_TEMPLATE.md` | Create | Yes — Jira/issue prefix |
+| 5 | `.github/copilot-instructions.md` | Create | Yes — full rewrite |
+| 6 | `CLAUDE.md` | Create | Yes — full rewrite |
+| 7 | `.gitignore` | Update | No — append AI section |
+| 8 | `docs/source-control.md` | Create | No — universal |
+| 9 | `docs/project-rule.md` | Create | Yes — tune tech rules |
+| 10 | `docs/project-structure.md` | Create | Yes — full rewrite |
+| 11 | `docs/<service-name>.md` | Create | Yes — main service doc |
+
+## Procedure
+
+### 1. Scan the repo first — never guess
+
+Before writing anything, gather the facts that drive the project-specific files:
+
+- **Build & runtime:** `build.gradle`/`pom.xml`/`package.json`/`go.mod`/etc. —
+  language + version, framework, build commands, test commands.
+- **Submodules:** check for `.gitmodules`. Drives whether the Copilot workflow
+  needs `submodules: recursive` and a `GIT_TOKEN`.
+- **Issue tracker prefix:** infer from existing branch names / commit history
+  (e.g. `S4R-`, `PROJ-`). Drives the PR template link.
+- **Existing files:** if any target file already exists, read it and propose a
+  merge rather than overwriting. Never clobber a hand-maintained `CLAUDE.md`.
+- **CI:** existing `.github/workflows/` — note the runner, JDK/Node version,
+  and cache strategy already in use so the Copilot workflow matches.
+
+Announce what you found and what you intend to create before writing.
+
+### 2. Confirm prerequisites with the user
+
+These are configured outside the repo and the skill cannot do them. List them
+and ask the user to confirm they are (or will be) set:
+
+- **GitHub secret `ANTHROPIC_API_KEY`** — from console.anthropic.com.
+- **GitHub secret `GIT_TOKEN`** — a PAT with `contents:read`, only if the repo
+  uses submodules.
+- **Claude GitHub App** installed for the repo
+  (https://github.com/apps/claude) with `contents:read` and
+  `pull_requests:write`.
+- **Branch protection** on the default branch: require PR before merge, require
+  status checks, allow GitHub Actions to create/approve PRs.
+
+### 3. Create the workflow files (verbatim templates below)
+
+Write files 1–3 from the templates in the **Templates** section. Apply the
+✏️ edits noted there: review focus areas, JDK/Node version, submodule handling,
+and the build/dependency command.
+
+### 4. Create the PR template
+
+Write `.github/PULL_REQUEST_TEMPLATE.md` from the template, replacing the
+issue-tracker prefix with the one detected in step 1.
+
+### 5. Update `.gitignore`
+
+Append the AI section from the template. Skip any line already present (e.g.
+don't add `/.cursor/` if `.cursor` already appears).
+
+### 6. Create the documentation files
+
+- `docs/source-control.md` — copy verbatim (universal).
+- `docs/project-rule.md` — copy, then tune the tech-specific lines (language
+  version, framework name).
+- `docs/project-structure.md` — write from the repo scan: top-level layout,
+  main source packages and their purpose, test layout, key config files.
+- `docs/<service-name>.md` — write for the main service/entry point: main
+  endpoint, request flow, key methods, dependencies, feature flags, error
+  handling.
+
+### 7. Write the AI context files (`CLAUDE.md` + `copilot-instructions.md`)
+
+These are fully project-specific and mirror each other. **Verify every claim**
+against source before including it: confirm each build/test command exists,
+quote exact config keys, list directories before describing them, and never
+instruct placing credentials in a repo-tracked file (use `~/.gradle/...`,
+`~/.m2/...`, `~/.npmrc`, or env vars). Keep `CLAUDE.md` a thin index that points
+into `docs/`. Use the skeletons in the Templates section.
+
+If the repo already follows the `docs-init` canonical structure (architecture /
+local-setup / conventions / operations / decisions), point `CLAUDE.md` at those
+files instead of inventing new ones — don't duplicate.
+
+### 8. Verify
+
+Run through the checklist and report status to the user:
+
+- [ ] `ANTHROPIC_API_KEY` secret set (and `GIT_TOKEN` if submodules used).
+- [ ] Claude GitHub App installed for the repo.
+- [ ] `copilot-setup-steps.yml` job is named exactly `copilot-setup-steps`.
+- [ ] Review prompt tuned to the project's real concerns.
+- [ ] JDK/Node version in the Copilot workflow matches the build file.
+- [ ] All `docs/*.md` exist and the links in `CLAUDE.md` resolve.
+- [ ] Suggest a test PR to confirm `claude-pr-review.yml` triggers and posts,
+      and an `@claude` comment to confirm `claude.yml` triggers.
+- [ ] Suggest a commit message (e.g. `chore: add Claude Code + Copilot AI setup`).
+
+## Hard rules
+
+- **Never overwrite an existing hand-maintained file silently.** Read it,
+  propose a merge, confirm.
+- **The Copilot job MUST be named `copilot-setup-steps`** or Copilot won't pick
+  it up.
+- **Verify every command and config key** in `CLAUDE.md` /
+  `copilot-instructions.md` against source. Don't fabricate tasks.
+- **Never put credentials in repo-tracked files.** Secrets live in GitHub
+  Actions secrets; local creds live in user-home config.
+- **Pin the action and model versions** as written; only bump when the user
+  asks. Update the `--model` value if the user wants a specific model.
+- **`submodules: recursive` + `GIT_TOKEN`** only if the repo actually has
+  submodules — remove both otherwise.
+
+---
+
+## Templates
+
+### 1. `.github/workflows/claude.yml` — copy verbatim
+
+```yaml
+name: Claude Code
+
+# Triggers: new PR opened or @claude mentioned in a PR comment
+on:
+  pull_request:
+    types: [ opened ]
+  issue_comment:
+    types: [ created ]
+
+# Cancel redundant runs on the same PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  claude:
+    name: Run Claude Code Agent
+    # Run on new PRs or when @claude is mentioned in a PR comment
+    if: |
+      (github.event_name == 'pull_request' && github.event.action == 'opened') ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '@claude'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ github.token }}
+          claude_args: |
+            --model claude-opus-4-5
+```
+
+### 2. `.github/workflows/claude-pr-review.yml` — ✏️ tune the `prompt` focus areas
+
+```yaml
+name: Claude Code PR Review
+
+# Triggers: new PR opened or @claude mentioned in a PR comment
+on:
+  pull_request:
+    types: [ opened ]
+  issue_comment:
+    types: [ created ]
+
+# Cancel redundant runs on the same PR
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  claude-pr-review:
+    name: Run Claude PR Review
+    # Run on new PRs or when @claude is mentioned in a PR comment
+    if: |
+      (github.event_name == 'pull_request' && github.event.action == 'opened') ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && contains(github.event.comment.body, '@claude'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: PR Review with Progress Tracking
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ github.token }}
+
+          # Enable progress tracking
+          track_progress: true
+
+          # ✏️ UPDATE these focus areas for your project
+          prompt: |
+            REPO: ${{ github.repository }}
+            PR NUMBER: ${{ github.event.pull_request.number }}
+
+            Perform a comprehensive code review with the following focus areas:
+
+            1. **Code Quality**
+               - Clean code principles and best practices (Single responsibility principle)
+               - Code clarity, readability and maintainability
+               - Proper error handling and edge cases
+               - Check for unnecessary complexity and nesting
+               - Check for redundant code and abstractions
+               - Ensure consistency with project standards
+               - Check for overly compact or clever code
+
+            2. **Security**
+               - Check for potential security vulnerabilities
+               - Validate input sanitization
+               - Review authentication/authorization logic
+
+            3. **Performance**
+               - Identify potential performance bottlenecks
+               - Review database queries for efficiency
+               - Check for memory leaks or resource issues
+
+            4. **Testing**
+               - Verify adequate test coverage
+               - Review test quality and edge cases
+               - Check for missing test scenarios
+               - Check for superfluous tests
+
+            5. **Documentation**
+               - Ensure code is properly documented
+               - Verify README updates for new features
+               - Check API documentation accuracy
+
+            Provide detailed feedback using inline comments for specific issues.
+            Do not include your todo list in the final review.
+            Use top-level comments for general observations or praise.
+            At the end of the review, add a wit quatrain describing the PR. (Do it only once per PR)
+
+          # Tools for comprehensive PR review
+          claude_args: |
+            --allowedTools "mcp__github_inline_comment__create_inline_comment,Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Read,Glob,Grep,TodoWrite,Task,Skill"
+            --model claude-opus-4-5
+```
+
+### 3. `.github/workflows/copilot-setup-steps.yml` — ✏️ match build/runtime
+
+Java/Gradle reference below. For Node/Python/Go, swap the setup step, cache key,
+and the final "Download dependencies" command (`npm ci`, `pip install -r ...`,
+`go mod download`). **Keep the job name `copilot-setup-steps`.**
+
+```yaml
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      contents: read
+
+    steps:
+      - name: Set up JDK 21        # ✏️ UPDATE: language/version (or use setup-node / setup-python / setup-go)
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive    # ✏️ REMOVE this + token line if no submodules
+          fetch-depth: 0
+          token: ${{ secrets.GIT_TOKEN }}
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Cache Gradle packages
+        uses: actions/cache@v4
+        with:
+          key: v1-dependencies-${{ hashFiles('build.gradle') }}
+          path: |
+            ~/.gradle/caches
+            ~/.gradle/wrapper
+
+      - name: Download dependencies
+        run: ./gradlew dependencies   # ✏️ UPDATE: npm ci / pip install / go mod download
+```
+
+### 4. `.github/PULL_REQUEST_TEMPLATE.md` — ✏️ replace the issue-tracker prefix
+
+```markdown
+[S4R-1234](https://rezolvetech.atlassian.net/browse/S4R-1234)
+<!-- ✏️ UPDATE: replace S4R with your Jira/issue project prefix and the base URL -->
+
+## Description
+
+A high-level description of what is changed by this PR.
+
+## Checks
+
+- [ ] Unit Tests
+- [ ] Update 'vault' variables
+- [ ] Feature flag added / updated / removed
+- [ ] Update documentation (diagram, confluence pages, content inside "/docs" directory, swagger)
+
+## AI Development Checklist
+
+- [ ] Spec/requirement linked: <!-- link here -->
+- [ ] AI tool used: <!-- Copilot / @claude / Agent / Other -->
+- [ ] Tests generated/refined with AI
+- [ ] AI review pass completed
+- [ ] Repo context files are still accurate (update if not)
+```
+
+### 5. `.gitignore` — append (skip any line already present)
+
+```gitignore
+# AI docs
+/.claude/
+/.serena/
+/docs/archive/
+/docs/prompts/
+/docs/review/
+/docs/templates/
+```
+
+### 6. `docs/source-control.md` — copy verbatim (universal)
+
+```markdown
+# Source Control
+
+## Branches
+- Branch names must start with the Jira ticket number followed by a short description in kebab-case.
+- Prefixes: `feature/`, `bugfix/`, `hotfix/`, `chore/`
+- Example: `feature/S4R-1234-add-search-caching`
+- `main` is the protected default branch; direct pushes are not allowed.
+
+## Commits
+- Messages must start with the Jira ticket number: `S4R-1234: add search result caching`
+- Write in **imperative mood** and **lowercase** after the ticket prefix.
+- Explain *what* and *why*, not *how*.
+
+## Pull Requests
+- PR title: `S4R-1234: Add result caching for autocomplete`
+- Fill in PR description using the PR template — all checklist items must be reviewed.
+- PRs must be reviewed and approved before merging.
+- Use **Squash and Merge** to keep `main` history clean.
+- Delete the source branch after merging.
+```
+
+### 7. `docs/project-rule.md` — ✏️ tune the tech-specific lines
+
+```markdown
+- Do not look at Linter errors until the user explicitly asks.
+- Do not reformat existing code or imports unrelated to implementation changes.
+- Use `var` for new variables' declaration with new operator.   <!-- ✏️ language-specific -->
+- Use the same naming and style patterns as in the existing code.
+- Use Java 21 with preview features for all new code.            <!-- ✏️ UPDATE language/version -->
+- <Framework> is used as the framework. Check official docs for actual APIs.  <!-- ✏️ UPDATE -->
+- Ensure app build and tests pass before committing any changes.
+```
+
+### 8. `CLAUDE.md` — thin index, fully project-specific
+
+```markdown
+# CLAUDE.md
+
+## Project Overview
+<2-3 sentences: what the service does, framework, main purpose>
+
+## Project Guidelines
+- Coding standards: @docs/project-rule.md
+- Project structure: @docs/project-structure.md
+- Source control: @docs/source-control.md
+- <service name> specifics: @docs/<service-name>.md
+- Configuration reference: @docs/configuration-reference.md
+- API reference: @docs/api-reference.md
+
+## Tech Stack
+<table: Framework, Language, Build, Databases, Cache, Messaging, Testing, Monitoring>
+
+## Essential Commands
+<Local Development, Build & Test, Docker — real, verified commands only>
+
+## Architecture
+<Package structure table, request flow, key patterns>
+
+## Critical Logic
+<the most important business logic / algorithm>
+
+## Development Guidelines
+<code style, how to add a feature step-by-step, testing approach>
+
+## Important Files
+<table: file → purpose>
+
+## Local Development Notes
+<prerequisites, credentials (user-home only), environment variables>
+
+## Common Issues
+<table: issue → solution>
+```
+
+### 9. `.github/copilot-instructions.md` — mirrors `CLAUDE.md` for Copilot
+
+Required sections:
+
+1. **Title** — `# AI Coding Agent Instructions for <Project Name>`
+2. **Build, Test, and Development Commands** — all real build-tool commands.
+3. **High-Level Architecture** — core components, integration points, design decisions.
+4. **Development Guidelines** — code style, framework patterns, testing, how to add a service.
+5. **Project Guidelines** — links to `/docs/*.md`.
+6. **Claude Code PR Reviewer Setup** — GitHub config, what Claude reviews, how to disable.