@groupby/ai-dev 0.5.3 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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/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,57 @@
+---
+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
+---
+
+# 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/refine-spec/SKILL.md

@@ -0,0 +1,47 @@
+---
+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
+---
+
+# 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/tdd-green/SKILL.md

@@ -0,0 +1,61 @@
+---
+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
+---
+
+# 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,50 @@
+---
+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
+---
+
+# 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,51 @@
+---
+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
+---
+
+# 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