@groupby/ai-dev 0.5.15 → 0.5.17

package/teams/fhr-orchestration/skills/init-harness/assets/TEMPLATE.coding-guidelines.md

@@ -0,0 +1,320 @@
+# Coding Guidelines — {{SERVICE_NAME}}
+
+*Last updated: {{DATE}}*
+*Owner: {{TEAM_NAME}}*
+
+---
+
+## §1 Project Structure
+
+### Convention: Package layout follows strict layer boundaries
+
+The root package is `{{ROOT_PACKAGE}}`. Every class lives in exactly one named sub-package that matches its architectural role. {{REMOTE_INTEGRATION_PACKAGE_NOTE — FILL IN: describe how integrations are grouped, e.g. "Remote integrations are grouped under `remote/{integration-name}`" or remove if not applicable}}.
+
+---
+
+### Convention: Class naming encodes layer and purpose
+
+<!-- FILL IN: scan src/main/java/{{ROOT_PACKAGE}}/ and extract the actual naming patterns present in this repo.
+     Add one row per layer found. Remove layers that do not exist in this codebase. -->
+
+| Layer | Pattern | Examples |
+|-------|---------|---------|
+| {{layer}} | `{{NamingPattern}}` | {{ActualClassExamples}} |
+
+---
+
+## §2 Spring Boot Patterns
+
+<!-- FILL IN or REMOVE: only if repo uses Spring Boot. If not, replace with the equivalent framework's conventions or remove. -->
+
+### Convention: `@Bean` in `@Configuration` classes for all infrastructure beans
+
+Beans that require parameters, conditionals, or custom construction are declared as `@Bean` methods inside a `@Configuration` class. No infrastructure bean is created via `@Component` constructor alone.
+
+---
+
+### Convention: `@Service` / `@Component` for business-logic beans
+
+Service classes and standalone components (not requiring conditional creation) use stereotype annotations directly. Always paired with `@RequiredArgsConstructor`.
+
+---
+
+### Convention: Runtime bean switching
+
+{{BEAN_SWITCHING_NOTE}}
+
+---
+
+### Convention: All custom properties injected with `@Value` and a default
+
+Properties are always injected with `@Value("${...}")`. Every optional property includes a colon-separated default value. {{CONFIGURATION_PROPERTIES_NOTE}}.
+
+---
+
+### Convention: Custom property namespace is `{{PROPERTY_PREFIX}}.*`
+
+All application-specific properties are nested under the `{{PROPERTY_PREFIX}}` prefix in `application.yaml`. Spring-managed namespaces (`spring.*`, `management.*`) are used unmodified.
+
+---
+
+### Convention: Spring profile usage
+
+{{PROFILE_NOTE}}
+
+---
+
+## §3 Error Handling
+
+<!-- FILL IN or REMOVE: only if service exposes HTTP endpoints. -->
+
+### Convention: Custom exception hierarchy
+
+{{EXCEPTION_HIERARCHY_NOTE}}
+
+---
+
+### Convention: All HTTP error mapping is centralised in a single `@ControllerAdvice` class
+
+There is a single `@ControllerAdvice` class (`{{EXCEPTION_HANDLER_CLASS}}`). Services throw unchecked exceptions; they do not produce `ResponseEntity` or set HTTP status codes. Error mapping happens only in `{{EXCEPTION_HANDLER_CLASS}}`.
+
+---
+
+### Convention: Error response body format
+
+{{ERROR_RESPONSE_FORMAT}}
+
+---
+
+### Convention: Exception handler logging
+
+{{EXCEPTION_HANDLER_LOGGING_NOTE}}
+
+---
+
+## §4 Logging
+
+### Convention: Logger declaration
+
+{{LOGGER_DECLARATION_NOTE}}
+
+---
+
+### Convention: Log levels
+
+{{LOG_LEVEL_CONVENTIONS}}
+
+---
+
+### Convention: MDC usage
+
+{{MDC_NOTE}}
+
+---
+
+## §5 Testing
+
+### Convention: Test approach
+
+{{TEST_APPROACH_NOTE}}
+
+---
+
+### Convention: Test infrastructure
+
+{{TEST_INFRA_NOTE}}
+
+---
+
+### Convention: Test infrastructure wiring
+
+{{TEST_WIRING_NOTE}}
+
+---
+
+### Convention: Test interaction style
+
+{{TEST_INTERACTION_NOTE}}
+
+---
+
+<!-- FILL IN or REMOVE: include BDD sub-section only if a BDD framework is detected. -->
+
+### BDD Conventions ({{FRAMEWORK_NAME}})
+
+{{BDD_CONVENTIONS — document stage/step patterns, naming, state sharing}}
+
+---
+
+## §6 API Layer
+
+<!-- FILL IN or REMOVE: only if service exposes a REST API. -->
+
+### Convention: Controller return types
+
+{{CONTROLLER_RETURN_NOTE}}
+
+---
+
+### Convention: Base URL path pattern
+
+{{BASE_URL_PATTERN}}
+
+---
+
+### Convention: Request validation approach
+
+{{VALIDATION_NOTE}}
+
+---
+
+### Convention: Model / DTO class construction
+
+{{DTO_CONSTRUCTION_NOTE}}
+
+---
+
+## §7 Data Access
+
+<!-- FILL IN or REMOVE: only if service owns or accesses a database. -->
+
+### Convention: Data access approach
+
+{{DATA_ACCESS_NOTE}}
+
+---
+
+### Convention: SQL / query storage
+
+<!-- FILL IN or REMOVE: include only if the service uses raw SQL. -->
+
+{{SQL_STORAGE_NOTE — describe where queries live, e.g. "Simple queries are inline `private static final String` constants. Complex queries live in external `.sql` files under `src/main/resources/` loaded via `{{SQL_LOADER_CLASS}}`."}}
+
+---
+
+### Convention: Transactions
+
+<!-- FILL IN or REMOVE: include only if the service owns a database. -->
+
+{{TRANSACTION_NOTE}}
+
+---
+
+## §8 Inter-Service Communication
+
+<!-- FILL IN or REMOVE: include only if service communicates with other services. -->
+
+### Convention: Outbound HTTP client
+
+<!-- FILL IN or REMOVE: include only if service makes outbound HTTP calls. -->
+
+{{OUTBOUND_HTTP_NOTE}}
+
+---
+
+### Convention: Async messaging
+
+<!-- FILL IN or REMOVE: include only if service produces or consumes async messages. -->
+
+{{ASYNC_MESSAGING_NOTE — describe producer pattern, consumer pattern, error handling, topic naming.}}
+
+---
+
+## §9 Secret Management
+
+### Convention: No secrets in source code or config files
+
+`application.yaml` (or equivalent) contains only local development defaults. Production values are injected at runtime.
+
+{{RUNTIME_SECRET_INJECTION_NOTE — FILL IN from repo scan + engineer confirmation: describe how runtime secrets are injected, e.g. "Kubernetes secret mounts", "AWS Secrets Manager", "environment variables set by the deployment pipeline".}}
+
+---
+
+### Convention: Build-time secret handling
+
+<!-- FILL IN or REMOVE: include only if CI pipeline files exist in this repo. -->
+
+{{BUILD_SECRET_NOTE}}
+
+---
+
+## §10 Dependency Management
+
+### Convention: Parent POM / BOM
+
+{{PARENT_POM_NOTE}}
+
+---
+
+### Convention: Dependency version pinning
+
+{{VERSION_PINNING_NOTE}}
+
+---
+
+### Convention: Image / artefact build
+
+{{BUILD_TOOL_NOTE}}
+
+---
+
+## §11 CI / CD
+
+<!-- FILL IN or REMOVE: include only if CI pipeline files exist in this repo. -->
+
+### Convention: CI tooling
+
+{{CI_TOOL_NOTE}}
+
+---
+
+## §12 High-Risk Areas
+
+AI may make changes anywhere in this repo. All code is reviewed before merge. The areas below are high-risk: the cost of a wrong change is high and not always visible to AI. For each, follow the specific rule and flag the change in the PR description. If a change is not clearly justified by the spec, stop and confirm with the engineer first.
+
+### High-Risk Area {{N}} — {{Name}}
+
+**What:** {{specific files, packages, or patterns}}
+**Why:** {{the failure mode if AI gets this wrong}}
+**Rule:** {{specific constraint to follow}}
+
+---
+
+## Convention Gaps
+
+<!-- FILL IN: document every inconsistency found during the codebase scan.
+     If no gaps exist, write "No convention gaps identified." and remove this comment.
+     Use the format below for each gap found. -->
+
+{{CONVENTION_GAPS_OR_NONE — for each gap found, use this format:
+
+### Gap: <short description>
+
+**Type:** Decision needed | AI hallucination risk | Intentional — needs documenting
+
+**Description:** <what is inconsistent and where it appears>
+
+**Examples of conflict:**
+- `ClassA.method` — does X
+- `ClassB.method` — does Y
+
+**Jira ticket:** <link or leave blank>
+
+---
+}}
+
+---
+
+## AI Usage Notes
+
+**Patterns AI must always follow:**
+
+{{GENERATE: one rule per confirmed convention — reference the section above}}
+
+**Patterns AI must never use:**
+
+{{GENERATE: one anti-pattern per confirmed absence or prohibition — state why (e.g. "not present in this codebase", "violates free zone", "contradicts convention in §X")}}
+
+**Things that contradict common defaults or conventions:**
+
+{{GENERATE: surprises a competent developer would not expect — things AI is likely to get wrong without being told explicitly}}

package/teams/fhr-orchestration/skills/init-harness/assets/TEMPLATE.glossary.md

@@ -0,0 +1,55 @@
+# Glossary — {{SERVICE_NAME}}
+
+*Last updated: {{DATE}}*
+*Owner: {{TEAM_NAME}}*
+
+Domain terms used consistently in this service. Use these exact terms in code, specs, and documentation; do not introduce synonyms.
+
+Only include terms where the meaning is specific to this service or where the code uses a different word than the business/product team. Generic terms ('microservice,' 'API') do not belong here.
+
+---
+
+## Core Concepts
+
+**{{PrimaryDomainObject}}**
+{{Definition: What it is, what it represents, who submits it, what happens to it.}}
+
+**{{SecondaryDomainObject}}**
+{{Definition.}}
+
+**{{KeyIdentifier}}**
+{{Definition: e.g. "A UUID assigned at creation time. Uniquely identifies a {{object}} across its full lifecycle."}}
+
+<!-- Add more core concept entries as needed -->
+
+<!-- OPTIONAL: If this service has a state machine or enum that constrains valid values:
+
+## {{Object}} States
+
+| State | Meaning |
+|-------|---------|
+| `{{STATE}}` | {{when this state applies}} |
+
+These are the ONLY valid states. Do not introduce new states without engineer confirmation. -->
+
+---
+
+## External Services
+
+**{{ExternalServiceName}}**
+{{What it is, what role it plays relative to this service, how this service calls it.}}
+
+**{{ExternalServiceName}}** *(also known as: {{CodebaseName}})*
+{{What it is. Note: code uses "{{CodebaseName}}" (e.g. package names, class names); the canonical domain name is "{{ExternalServiceName}}". Use the canonical name in new code and docs.}}
+
+---
+
+## Infrastructure Terms
+
+<!-- Only include infrastructure terms that have domain-level significance — things that appear in specs, ADRs, or conversations with engineers, not just implementation details. -->
+
+**{{InfrastructureTerm}}**
+{{Definition: e.g. "The external_events_outbox table used to reliably publish status updates. Events are written transactionally alongside state changes and processed asynchronously."}}
+
+**{{InfrastructureTerm}}**
+{{Definition.}}

package/teams/fhr-orchestration/skills/init-harness/assets/TEMPLATE.harness-gap-log.md

@@ -0,0 +1,59 @@
+# harness-gap-log.md — {{SERVICE_NAME}}
+
+*Last updated: {{DATE}}*
+*Owner: {{TEAM_NAME}}*
+
+---
+
+## Purpose
+
+Post-generation review found a problem rooted in a harness gap. Log it here with a workaround so the agent avoids repeating it.
+
+Agent: check Active entries in the relevant area before generating. Apply the corrective action.
+
+---
+
+## Active Gaps
+
+*Most recent first.*
+
+<!-- ENTRY FORMAT:
+
+### {{YYYY-MM-DD}} — {{short description}}
+
+**Area:** {{package, class, or concern area}}
+**Exposed by:** {{spec or ticket where the problem surfaced}}
+**What happened:** {{What did the generated code get wrong?}}
+**Root cause:** {{Why did the harness fail to prevent this?}}
+**Interim instruction:** {{What the agent must do differently until fixed permanently}}
+**Fix required:** {{Which harness file needs what change}}
+**Reached main?:** {{Yes / No}}
+**Status:** Active
+**Ticket:** {{link}}
+
+Only log entries where:
+- The root cause is a harness gap (not a spec error or random one-off)
+- The interim instruction changes agent behaviour (if it doesn't, track in Jira only)
+
+-->
+
+*No active gaps.*
+
+---
+
+## Resolved Gaps
+
+*Moved here once the harness fix is merged.*
+
+<!-- ENTRY FORMAT:
+
+### {{YYYY-MM-DD}} — {{short description}}
+
+**Area:** {{area}}
+**What happened:** {{what the generated code got wrong}}
+**Propagated to:** {{which harness file was updated to fix this permanently}}
+**Status:** Closed
+
+-->
+
+*No resolved gaps.*

package/teams/fhr-orchestration/skills/use-case-writer/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: use-case-writer
+description: 'Produce a structured test plan from a PRD, spec file, Jira ticket, or plain description. Tags each test case by type (E2E / acceptance / contract / lint) so it can be handed directly to the matching writer skill. Use when: "write test cases for...", "plan the tests for...", "what tests do we need for...", "test plan for this feature".'
+argument-hint: "Path to a PRD or spec (.md/.txt), a Jira key (FHR-XXXX), or a plain-English feature description"
+user-invocable: true
+allowed-tools: [Read, Grep, Glob, Bash, Write]
+---
+
+# /use-case-writer — Test case planner for Titan services
+
+Produces a test plan file (`test-plan-{slug}.md`) with test cases tagged by type.
+Each test case maps directly to a writer skill:
+
+| Tag | Writer skill |
+|---|---|
+| `[E2E]` | _dev-owned — no automated writer; author these manually in `titan-e2e-tests`_ |
+| `[acceptance]` | `/acceptance-tests-writer` |
+| `[contract]` | `/contract-tests-writer` |
+| `[lint]` | `/lint-tests-writer` |
+
+**Nothing is invented.** Test cases are derived from the input and verified against
+the actual service code and docs. Ambiguous assertions go in the "open questions"
+section — not into a test case.
+
+---
+
+## Step 0 — Detect input type
+
+Check `$ARGUMENTS`:
+
+- **File path ending in `.md` or `.txt`** → read it as a PRD or spec
+- **`FHR-XXXX` pattern** → fetch the Jira ticket (if Atlassian MCP is connected) or ask the user to paste the description
+- **Anything else** → treat as a plain-English description of the feature or change
+
+If `$ARGUMENTS` is empty → ask: "Paste a PRD, a Jira ticket ID, or describe the feature."
+
+---
+
+## Step 1 — Read context sources
+
+Read the relevant files for whichever services the feature touches:
+
+```
+team-config.yaml                        # testing stack + repo list
+titan-e2e-tests/docs/architecture.md    # deployment topology
+titan-e2e-tests/TESTING_GAPS.md         # known gaps — don't plan tests that duplicate open gaps
+```
+
+For `csp-apigateway`:
+- `csp-apigateway/docs/` — existing specs/ADRs
+- `csp-apigateway/apigateway-tests/src/test/java/.../tests/` — existing acceptance tests (don't plan duplicates)
+
+For `csp-trigger-scheduler`:
+- `csp-trigger-scheduler/src/test/java/.../integration/` — existing integration tests
+
+For `fas-argo-deployment` / `titan-argo-deployment`:
+- `charts/` — chart structure (for lint scope)
+
+Only read what's relevant. Skip repos the feature doesn't touch.
+
+---
+
+## Step 2 — Extract functional requirements
+
+From the input, list every distinct behaviour the feature introduces or changes:
+
+- What does the system do (happy path)?
+- What does it reject or handle differently (error / boundary cases)?
+- What does it emit (Kafka messages, state changes)?
+- What crosses a service boundary?
+- What is deployed via Helm/Argo?
+
+Group requirements by service boundary. Each requirement is a candidate test case.
+
+---
+
+## Step 3 — Assign test types
+
+For each requirement, assign one type using these rules:
+
+| Requirement type | Test type |
+|---|---|
+| Full flow across multiple services (apigw → scheduler → curator → Kafka) | `E2E` |
+| Single service HTTP API behaviour in isolation | `acceptance` |
+| Message schema / structure on a Kafka topic between two services | `contract` |
+| Helm chart validity, template rendering, required fields | `lint` |
+| Unit-level logic | *(skip — dev responsibility, out of QA AI scope)* |
+
+A single feature may produce test cases of multiple types.
+
+---
+
+## Step 4 — Write the test plan
+
+Create `titan-e2e-tests/docs/test-plan-{slug}.md` where `{slug}` is a kebab-case summary
+of the feature (e.g. `test-plan-load-xml-e2e`, `test-plan-fas-healthcheck`).
+
+Follow the structure in `skills/use-case-writer/TEMPLATE.md` — one entry per test case,
+numbered sequentially and grouped by type (E2E → acceptance → contract → lint).
+
+For each TC, populate the plain-English fields:
+
+- **Why this matters:** one sentence naming what's at risk in production if this scenario fails. Derive from the ticket, the PRD, or the wording of the Expected outcome. If nothing in the input suggests a risk, write `TBD — engineer to fill` and note it in the Open questions table.
+- **How this is verified:** one or two plain-English sentences translating the `**Assertion layer:**` value into what actually happens at runtime. Example: `Assertion layer: JGiven` → `The test sends a real HTTP request via the JGiven stages and asserts against the response and any Kafka messages produced.` Do not skip this field just because the assertion layer is obvious to a developer.
+
+---
+
+## Step 5 — Summarise open questions
+
+Collect open questions in the bottom table of `TEMPLATE.md`. These must be resolved
+before the corresponding writer skill is run.
+
+---
+
+## Step 6 — Present the output
+
+Show:
+1. Path to the generated test plan file
+2. Summary table: test case count per type
+3. List of open questions
+4. Suggested next step: "Run `/{writer-skill} path/to/test-plan-{slug}.md` to generate code for each type."
+
+Do not generate test code in this skill — that is the writer skills' job.

package/teams/fhr-orchestration/skills/use-case-writer/TEMPLATE.md

@@ -0,0 +1,39 @@
+# Test plan: {Feature name}
+
+## Test cases
+
+Number sequentially. Group by type: E2E first, then acceptance, then contract, then lint.
+
+## TC-{NNN} [{type}] {title}
+
+**Service(s):** {comma-separated list}
+**Jira:** {FHR-XXXX or n/a}
+
+**Why this matters:** {one plain-English sentence — what's at risk in production if this scenario fails}
+
+**Preconditions:**
+- {what must be true before this test runs}
+
+**Steps:**
+1. {action}
+2. {action}
+
+**Expected outcome:**
+- {observable result — HTTP status, Kafka message field, K8s state, etc.}
+
+**How this is verified:** {plain-English description of the mechanism — example: "The test sends a real HTTP POST to the running apigateway, then checks the JSON body of the response and reads the message the service publishes to Kafka to confirm it matches the expected shape."}
+
+**Assertion layer:** {RestAssured / JGiven / JSON Schema / helm lint}
+
+**Writer skill:** `/{skill-name}`
+
+**Open questions:**
+- {anything that must be confirmed from the code before this can be implemented}
+
+---
+
+## Open questions
+
+| # | Question | Blocks |
+|---|---|---|
+| 1 | {question} | TC-{NNN} |

package/teams/fhr-orchestration/skills/write-spec/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: write-spec
+description: Generate a complete implementation spec from a Jira ticket. Accepts a Jira key (e.g. FHR-1234) or a feature description. Fetches ticket details via Atlassian MCP, investigates the codebase, and produces a spec an AI coding agent can execute without further clarification. Outputs docs/specs/FHR-XXXX/SPEC.md. Run from the target service repo. Use when asked to write or generate a spec for a ticket or feature.
+argument-hint: "Jira key (e.g. FHR-1234) or feature description"
+user-invocable: true
+---
+
+# /write-spec
+
+Produces a clear, actionable spec that an AI coding agent can execute without further clarification. The output is the source of truth for plan generation.
+
+## Trigger
+
+`/write-spec` followed by either:
+- A JIRA ticket key (e.g. `FHR-1234`)
+- A feature description
+  If missing, ask.
+
+## Input Resolution
+
+1. If a JIRA key is provided, attempt to fetch via MCP. If MCP is unavailable or fails, ask the user to paste the ticket content.
+2. Read `docs/specs/{JIRA-ID}/TICKET.md` if it exists.
+3. Read repository markdown files (architecture docs, glossary, coding guidelines) for context.
+4. Search codebase for components, tests, models, and contracts relevant to the feature.
+
+## Process
+
+1. **Gather context** - read the ticket, repository docs, and search the codebase for relevant files.
+2. **Clarify** unknowns before writing.
+- Group related questions into a single message to minimize round-trips.
+- Do not produce the spec until the user has explicitly answered all questions. A response about something else (e.g. "I don't see the file") is NOT permission to proceed — re-ask the questions.
+- Never add assumptions in place of asking. If something is unknown, ask. Do not write the spec with assumptions documented inline.
+- Never ask about information already present in the ticket or codebase.
+- Only proceed without asking if the user explicitly says to (e.g. "proceed", "write what you have").
+3. **Write** the spec. Be concrete: exact file paths, method names, field names, types.
+4. **Validate** before presenting:
+   - Goal is concrete, not a placeholder.
+   - At least one G/W/T requirement exists.
+   - No unresolved unknowns remain.
+5. **Present** a short summary of what the spec covers and whether `/grill-with-docs` is recommended.
+
+## Output
+
+- Template: `skills/write-spec/TEMPLATE.md`
+- Write to: `docs/specs/{JIRA-ID}/SPEC.md`
+
+## Rules
+
+- Use exactly the section names from the template.
+- Requirements use Given/When/Then format. Edge cases are inline with the requirement they belong to.
+- Context table lists key files with their roles (Read / Modify / Create), up to 8.
+- Technical constraints are derived from the ticket and codebase, not invented.
+- Omit sections that don't apply.
+- NFRs cover performance, observability, and security — omit if none apply.
+- Use only terms from the repository glossary if one exists.
+- Write the spec to the output file; confirm only the file path.

package/teams/fhr-orchestration/skills/write-spec/TEMPLATE.md

@@ -0,0 +1,29 @@
+# {JIRA-ID}: {Title}
+
+## Goal
+
+{One or two sentences. What does this change achieve and why.}
+
+## Context
+
+| Reference | Role |
+|-----------|------|
+| `path/to/file` | Read / Modify / Create |
+
+## Requirements
+
+### FR-1: {Name}
+
+**Given** ...
+**When** ...
+**Then** ...
+
+**Edge case:** ...
+
+### NFR-1: {Name}
+
+{Description.}
+
+## Technical Constraints
+
+{Constraints relevant to this feature, derived from the ticket and codebase.}