@groupby/ai-dev 0.5.3 → 0.5.5

package/package.json

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

package/teams/fhr-core/github/pull_request_template.md

@@ -0,0 +1,19 @@
+<!--
+PR TITLE must follow: FHR-<number>: <description>
+Example: FHR-7113: Add AI-first development workflow for FAS
+The pull-request.yml CI check will fail if the format is wrong.
+-->
+
+## Jira ticket
+
+[FHR-XXXX](https://attraqt.atlassian.net/browse/FHR-XXXX)
+
+## AI Development Checklist
+
+- [ ] Specification file present
+- [ ] Unit tests present and passing
+- [ ] Documentation file present
+- [ ] AI tool used: _Claude Code / Copilot / Agent / Other_
+- [ ] Tests generated/refined with AI (failing tests written before implementation)
+- [ ] AI review pass completed (visible in PR comments)
+- [ ] Repo context files (`CLAUDE.md`, `AGENTS.md`, `architecture.md`, `coding-guidelines.md`, `glossary.md`) still accurate

package/teams/fhr-core/resources/spec-template.md

@@ -0,0 +1,22 @@
+# FHR-XXXX TITLE
+
+> Task description, including background context, user stories, and so on.
+
+## Acceptance Criteria
+
+**Functional requirements**
+> - criteria 1
+> - criteria 2
+> - ...
+
+**Non-Functional requirements**
+> - criteria 1
+> - criteria 2
+
+
+## Design and Implementation Plan
+
+> Fill with the design and implementation plan.
+> List of user acceptance tests
+> List of unit tests
+

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/jira-ticket/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: jira-ticket
+description: Fetch a Jira ticket by number using the Atlassian MCP and report a summary. Use when the user says "jira", "ticket", or provides a ticket number like FHR-1234 or FAS-5678.
+tools: mcp__atlassian__getJiraIssue, mcp__atlassian__getAccessibleAtlassianResources
+---
+
+# Jira Ticket Summary
+
+Fetch a Jira ticket via the Atlassian MCP and return a structured summary.
+
+## Prerequisites
+
+The `atlassian` MCP server must be connected and authenticated. If the MCP tools are unavailable, tell the user:
+> The Atlassian MCP isn't connected. Run `/mcp` to connect and authenticate, then try again.
+
+## Steps
+
+1. **Validate input**: the ticket number comes from `$ARGUMENTS` (e.g. `FHR-6921`). If empty, ask the user for one.
+
+2. **Fetch the ticket** with the `mcp__atlassian__getJiraIssue` tool:
+   - `cloudId`: `attraqt.atlassian.net`
+   - `issueIdOrKey`: the ticket number from `$ARGUMENTS`
+   - `responseContentFormat`: `markdown` (so the description comes back as plain text, not ADF JSON)
+   - `fields`: `["summary", "status", "assignee", "reporter", "description", "labels", "components", "issuetype", "priority", "issuelinks", "fixVersions"]`
+
+   If the call fails with a cloudId/site error, call `mcp__atlassian__getAccessibleAtlassianResources` to find the correct cloudId, then retry with that value.
+
+3. **Check for errors**: if the tool returns an error (e.g. issue not found, no access), report it clearly and stop.
+
+4. **Report** a structured summary using these fields from the response:
+
+   - **Ticket**: `key` — `fields.summary`
+   - **Type / Priority**: `fields.issuetype.name` / `fields.priority.name`
+   - **Status**: `fields.status.name`
+   - **Assignee**: `fields.assignee.displayName` (or "Unassigned")
+   - **Reporter**: `fields.reporter.displayName`
+   - **Labels**: `fields.labels[]` joined, or "none"
+   - **Components**: `fields.components[].name` joined, or "none"
+   - **Fix Version**: `fields.fixVersions[].name`, or "none"
+   - **Description**: synthesise `fields.description` into 3–6 readable sentences
+   - **Linked tickets**: for each entry in `fields.issuelinks[]`, show the link type and the linked issue key + summary
+
+## Notes
+
+- Authentication is handled by the MCP's OAuth session — no API tokens or `CONFLUENCE_USER`/`CONFLUENCE_PASS` env vars are needed.
+- Never print the raw JSON. Synthesise a clean human-readable summary from the parsed fields.
+- If the description is empty or null, say "No description provided."

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

@@ -0,0 +1,58 @@
+---
+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
+
+Turns a refined spec into a concrete design and implementation plan with tests, committed to git.
+
+## Quick start
+
+```
+/plan-spec suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Enter Plan mode** — call `EnterPlanMode` immediately; stay in it while producing the plan
+
+2. **Load context**
+   - Read the spec file passed as argument
+   - Read `glossary.md` from the project root for ubiquitous language
+   - Read `architecture.md` from the project root for architecture guidelines
+
+3. **Produce the plan**
+   - Break the feature into discrete implementation tasks
+   - For each task, use this format:
+     ```
+     ### Task: <name>
+     - [ ] Acceptance tests
+     - [ ] Unit tests
+     - [ ] Production code
+
+     **Acceptance tests (BDD)**
+     - Given ... When ... Then ...
+
+     **Unit tests (TDD)**
+     - should ... when ...
+     ```
+   - Respect module boundaries and patterns from `architecture.md`
+   - Use only domain terms from `glossary.md`
+
+4. **Exit Plan mode and write into spec** — call `ExitPlanMode`, then update the spec file
+   - Write the full plan under the `## Design and Implementation Plan` section
+   - Create the section if it does not already exist
+
+5. **Commit**
+   - Stage the spec file
+   - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: add design and implementation plan`
+
+## Constraints
+
+- Do NOT touch any source code
+- Do NOT implement anything — plan only
+- Use only ubiquitous language from the glossary
+- Follow architecture patterns (module boundaries, event bus, DI, interfaces) from `architecture.md`

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

@@ -0,0 +1,48 @@
+---
+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
+
+Requirements-refinement session: interview the user until scope and acceptance criteria are clear, then rewrite the spec in place.
+
+## Quick start
+
+```
+/refine-spec suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Enter Plan mode** — call `EnterPlanMode` immediately; stay in it through the entire interview
+
+2. **Load context**
+   - Read the spec file passed as argument
+   - Read `glossary.md` from the project root for ubiquitous language
+
+3. **Assess current state**
+   - Identify what is clear, what is vague, and what is missing
+   - Flag any terminology that drifts from the glossary
+
+4. **Interview loop**
+   - Ask focused, one-topic-at-a-time questions (scope, edge cases, acceptance criteria)
+   - Use only domain terms from the glossary — never invent synonyms
+   - Continue until scope is unambiguous, acceptance criteria are testable, no open questions remain
+
+5. **Exit Plan mode and update spec** — call `ExitPlanMode`, then rewrite the spec file in place
+   - Preserve original structure; add/update sections as needed
+   - Use only ubiquitous language from the glossary
+
+6. **Commit**
+   - Stage the spec file
+   - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: refine the requirements`
+
+## Constraints
+
+- Do NOT touch any source code
+- Do NOT discuss unit tests or implementation details
+- Do NOT propose solutions — only clarify requirements
+- Stop interviewing once all sections are clear

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

@@ -0,0 +1,62 @@
+---
+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
+
+Implements the production code to make the failing tests pass. Run after `/tdd-red`.
+
+## Quick start
+
+```
+/tdd-green suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Load context**
+   - Read the spec file passed as argument
+   - Read `glossary.md` from the project root for ubiquitous language
+   - Read `coding-guidelines.md` from the project root for coding conventions
+   - Read `architecture.md` from the project root for module boundaries and patterns
+
+2. **Find the next incomplete task**
+   - Scan the `## Design and Implementation Plan` section for the first task whose `- [ ] Production code` checkbox is unchecked
+   - Work on that task only — do not advance to subsequent tasks
+
+3. **Implement production code**
+   - Write only enough production code to make the failing tests pass
+   - Follow all conventions in `coding-guidelines.md`
+   - Respect module boundaries from `architecture.md`
+   - Use only domain terms from `glossary.md`
+   - This is the **green phase**: no refactoring, no gold-plating — just passing tests
+
+4. **Run the tests**
+   - Unit tests
+   - Acceptance tests (JGiven)
+   - All tests must pass before proceeding
+
+5. **Commit (green)**
+   - Stage all changed production files
+   - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: implement <task name> (green)`
+
+6. **Refactor**
+   - Remove duplication, clarify intent, simplify structure
+   - Do NOT change behaviour; no new logic, no new tests
+   - Do NOT modify test code
+   - Run all tests; they must remain green. In case of any failure, stop immediately and ask the user what to do next (rollback; make the test pass; ...)
+
+7. **Mark task done**
+   - In the spec file, check off `- [x] Production code` for the completed task
+
+8. **Commit (refactor)**
+   - Stage all changed production files and the updated spec file
+   - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: refactor <task name> (refactor)`
+## Constraints
+
+- Do NOT modify test code
+- Do NOT advance past the first incomplete task
+- Write the minimum code needed to make tests pass

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

@@ -0,0 +1,51 @@
+---
+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
+
+Writes the failing tests for the next incomplete task in the plan. Run after `/plan-spec`.
+
+## Quick start
+
+```
+/tdd-red suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Load context**
+    - Read the spec file passed as argument
+    - Read `glossary.md` from the project root for ubiquitous language
+    - Read `coding-guidelines.md` from the project root for test conventions
+
+2. **Find the next incomplete task**
+    - Scan the `## Design and Implementation Plan` section for the first task whose `- [ ] Acceptance tests` or `- [ ] Unit tests` checkbox is unchecked
+    - Work on that task only — do not advance to subsequent tasks
+
+3. **Write the tests**
+    - Write acceptance tests (JGiven BDD style) and unit tests (JUnit Jupiter) as described for that task in the plan
+    - Follow all conventions in `coding-guidelines.md`: EasyMock for mocking, stage classes named `Given*`/`When*`/`Then*`, test methods named as scenario descriptions
+    - Use only domain terms from `glossary.md`
+    - This is the **red phase**: write only tests, no production code
+
+4. **Run the tests**
+    - Run unit tests
+    - Run acceptance tests (JGiven)
+    - Confirm the suite is red (fails) before proceeding
+
+5. **Mark task done**
+    - In the spec file, check off `- [x] Acceptance tests` and `- [x] Unit tests` for the completed task
+
+6. **Commit**
+    - Stage all new test files and the updated spec file
+    - Commit with message (replace XXXX with the actual ticket number from the spec file): `FHR-XXXX: add failing tests for <task name> (red)`
+
+## Constraints
+
+- Do NOT write any production code
+- Do NOT advance past the first incomplete task
+- Use only ubiquitous language from the glossary

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

@@ -0,0 +1,52 @@
+---
+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
+
+Automates the per-task red → green → refactor cycle for an entire plan by orchestrating the
+`tdd-red` and `tdd-green` skills. Run after `/plan-spec`.
+
+## Quick start
+
+```
+/tdd-workflow suggest-docs/src/main/docs/plans/FHR-XXXX-feature-name.md
+```
+
+## Workflow
+
+1. **Load context**
+   - Read the spec file passed as argument
+   - Locate the `## Design and Implementation Plan` section and its list of `### Task:` blocks
+
+2. **Pick the next task**
+   - Find the first `### Task:` whose checkboxes are not all checked
+     (`- [ ] Acceptance tests`, `- [ ] Unit tests`, `- [ ] Production code`)
+   - This task is the current task. If every task is fully checked, stop; the plan is complete
+
+3. **Red phase (if needed)**
+   - If `Acceptance tests` or `Unit tests` is unchecked for the current task, invoke `tdd-red` with the spec file
+   - Wait for it to finish before continuing
+
+4. **Green/Refactor phase (if needed)**
+   - If `Production code` is unchecked for the current task, invoke `tdd-green` with the spec file
+   - Wait for it to finish before continuing
+
+5. **Loop to the next task**
+   - Re-read the spec file and return to step 2
+   - Continue until no incomplete task remains
+
+6. **Report**
+   - Summarise which tasks were implemented and confirm the plan is fully checked off
+
+## Constraints
+
+- Always run the phases in order (red before green/refactor) for a given task
+- Do NOT start the next task until the current one is fully complete
+- If a phase’s checkbox is already checked for the current task, treat that phase as already complete (do not re-run it)
+- Let each sub-skill enforce its own rules (tests-only in red, minimal code + refactor in green); this skill only sequences them
+- Each invoked sub-skill commits its own work; do not add extra commits between skill invocations
+- Stop and surface the problem if any phase fails (e.g. tests will not pass) rather than advancing

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.