@groupby/ai-dev 0.5.15 → 0.5.16

package/package.json

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

package/teams/fhr-orchestration/skills/create-jira/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: create-jira
+description: Groom a Jira ticket into a structured, grooming-ready ticket file. Accepts a Jira key (e.g. FHR-1234), a Jira URL, or rough notes/description. Fetches ticket details via Atlassian MCP if available. Outputs docs/specs/FHR-XXXX/TICKET.md. Use when asked to create, groom, or write a Jira ticket.
+argument-hint: "Jira key (e.g. FHR-1234), Jira URL, or a description/notes for the ticket"
+user-invocable: true
+---
+
+# /create-jira
+
+Transforms rough input (notes, conversation, pasted JIRA content) into a structured, grooming-ready ticket saved to `docs/specs/{JIRA-ID}/TICKET.md`.
+
+## Trigger
+
+`/create-jira` followed by either:
+- Pasted ticket content, rough notes, or a description
+- A JIRA ticket key (e.g. `FHR-7054`)
+
+## Input Resolution
+
+1. If the user provides content directly, use it as the source material.
+2. If the user provides only a JIRA key, attempt to fetch via MCP. If MCP is unavailable or fails, ask the user to paste the ticket content.
+
+## Process
+
+1. **Parse** the input to identify what is known and what is missing.
+2. **Clarify** unknowns before writing. Group related questions into a single message to minimize round-trips. Do not produce the ticket until all ambiguity is resolved.
+3. **Write** the final ticket.
+
+## Clarification Guidelines
+
+- Group related unknowns into one question (e.g. "I need: (1) which repo owns this, (2) who is the engineer, (3) link to the source of truth").
+- Never ask about information already present in the input.
+- If something can be reasonably inferred from context, state the assumption and ask for confirmation rather than asking an open question.
+
+## Output
+
+- Template: `skills/create-jira/TEMPLATE.md`
+- Write to: `docs/specs/{JIRA-ID}/TICKET.md`
+
+## Rules
+
+- Use exactly the section names from the template. Do not rename, split, or add sections.
+- Acceptance Criteria are plain-language observable outcomes as checklist items. It should be self-evidently verifiable.
+- If a section does not apply, omit it entirely. No "N/A" filler.
+- Do not use emojis, icons, decorative symbols, backtick code formatting for shell commands, or non-ASCII punctuation (e.g. em dashes, curly quotes) anywhere in the output. Use plain ASCII only.
+- Do not produce the ticket with unresolved gaps. Ask first, write second.
+- Write the ticket directly to the output file. Do not display the ticket content in the conversation - only confirm the file path once written.

package/teams/fhr-orchestration/skills/create-jira/TEMPLATE.md

@@ -0,0 +1,10 @@
+# {JIRA-ID}: {Title}
+
+## TL;DR
+{2–3 sentences. What is changing, why and why the work matters, and what it touches or enables. Concise overview of the work; enough to understand the ticket at a glance without reading the full body.}
+
+## Affected Areas
+{Module, service, component, or file names. Approximate is fine}
+
+## Acceptance Criteria
+- [ ] {Plain-language observable outcome, independently verifiable}

package/teams/fhr-orchestration/skills/create-plan/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: create-plan
+description: Generate a TDD implementation plan from a spec file. Accepts a Jira key (e.g. FHR-1234), a Jira URL, or a path to a SPEC.md file. Reads the spec and breaks it into ordered, independently executable tasks for a coding agent. Outputs docs/specs/FHR-XXXX/PLAN.md. Use when asked to create a plan or implementation tasks for a ticket or spec.
+argument-hint: "Jira key (e.g. FHR-1234), Jira URL, or path to SPEC.md"
+user-invocable: true
+---
+
+# /create-plan
+
+Reads a spec and produces a detailed TDD implementation plan with ordered tasks, each independently executable by a coding agent.
+
+## Trigger
+
+`/create-plan` followed by one of:
+- A JIRA key (e.g. `FHR-1234`) - resolves to `docs/specs/FHR-1234/SPEC.md`
+- A JIRA link (e.g. `https://attraqt.atlassian.net/browse/FHR-1234`) - extracts key, resolves same as above
+- A path to a spec or ticket file (e.g. `docs/specs/FHR-1234/SPEC.md`)
+
+## Input Resolution
+
+1. Resolve the argument to a JIRA key.
+2. Read `docs/specs/{JIRA-ID}/SPEC.md`. If it does not exist, check for `docs/specs/{JIRA-ID}/TICKET.md` and ask whether to write a spec first.
+3. Read repository markdown files (coding guidelines, architecture docs) for conventions.
+
+## Process
+
+1. **Plan** - break the spec into discrete implementation tasks.
+2. **Order** - dependencies first (e.g. data model before service before controller).
+3. **Validate** before presenting:
+   - Every functional requirement in the spec has at least one corresponding task.
+   - Every task is independently executable by a coding agent.
+   - Tasks name exact files to create or modify.
+4. **Present** - summary of the plan structure and task count.
+
+## Output
+
+- Template: `skills/create-plan/TEMPLATE.md`
+- Write to: `docs/specs/{JIRA-ID}/PLAN.md`
+
+Each task follows the format in `TEMPLATE.md`.
+
+## Rules
+
+- Tasks must be ordered so each can be executed without forward dependencies.
+- Each task names exact files to create or modify.
+- Follow conventions from repository coding guidelines.
+- Do not invent requirements beyond what the spec states.
+- If the spec has gaps that prevent planning, stop and ask rather than assuming.

package/teams/fhr-orchestration/skills/create-plan/TEMPLATE.md

@@ -0,0 +1,13 @@
+### Task N: {Name}
+
+**Files:** `path/to/file` (create | modify)
+
+**Acceptance tests (BDD)**
+- Given ... When ... Then ...
+
+**Unit tests (TDD)**
+- should {expected behaviour} when {condition}
+
+**Implementation**
+- {Concrete step}
+- {Concrete step}

package/teams/fhr-orchestration/skills/init-harness/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: init-harness
+description: "Investigate a Titan service repo and produce (or refresh) its AI harness — CLAUDE.md at the repo root plus docs/coding-guidelines.md, docs/architecture.md, docs/glossary.md, docs/harness-gap-log.md. Reads the codebase, Jira/Confluence, and Miro boards; asks the engineer about high-risk areas and unknowns; writes documentation only, never production code. Use when: \"init the harness for this repo\", \"set up AI docs for this service\", \"refresh CLAUDE.md and docs/\", \"onboard this repo for AI coding\", \"update the harness after big changes\", or when starting AI-assisted work in a new Titan service."
+argument-hint: "Optional: Jira ticket key, Confluence space URL, Miro board URL, or 'update' to refresh existing files"
+context: fork
+---
+
+# Init Harness
+
+Investigate a repo and produce, or update, the canonical set of AI harness documentation files. A coding agent must not generate production code in a repo without these files in place.
+
+**Do NOT write production code.** Research, ask questions, and write documentation only.
+
+## Output Files
+
+The skill always targets this fixed set. After writing all files, suggest any extras that appear warranted and let the engineer decide.
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `CLAUDE.md` | repo root | Agent entry point: build commands, file pointers, service identity, dependencies, definition of done, PR guidance |
+| `docs/coding-guidelines.md` | `docs/` | Every naming, structural, and pattern convention extracted from the codebase |
+| `docs/architecture.md` | `docs/` | System context, layer map, data model, messaging topology, API surface |
+| `docs/glossary.md` | `docs/` | Canonical domain terms used verbatim in code, specs, and docs |
+| `docs/harness-gap-log.md` | `docs/` | Record of generation failures and their fixes |
+
+> **Known gap:** `docs/testing.md` is not yet in the output set. Testing conventions are covered in `docs/coding-guidelines.md`. When `testing.md` is created as a shared template, add it here.
+
+> **Note on `coding-guidelines.md`:** The coding-guidelines template is Spring Boot specific. If a future Titan repo uses a different stack, create a new coding-guidelines template for that framework and add it to the assets directory.
+
+## Templates
+
+Read the template for each file before writing it.
+
+| Template | Produces |
+|----------|---------|
+| [TEMPLATE.CLAUDE.md](./assets/TEMPLATE.CLAUDE.md) | `CLAUDE.md` |
+| [TEMPLATE.coding-guidelines.md](./assets/TEMPLATE.coding-guidelines.md) | `docs/coding-guidelines.md` |
+| [TEMPLATE.architecture.md](./assets/TEMPLATE.architecture.md) | `docs/architecture.md` |
+| [TEMPLATE.glossary.md](./assets/TEMPLATE.glossary.md) | `docs/glossary.md` |
+| [TEMPLATE.harness-gap-log.md](./assets/TEMPLATE.harness-gap-log.md) | `docs/harness-gap-log.md` |
+
+## Research Tools
+
+### Atlassian (Jira / Confluence)
+
+When the engineer provides a Jira ticket key, Confluence space, or Confluence page URL, use available Atlassian MCP tools to:
+- Fetch the page content: architecture docs, team conventions, ADRs, onboarding guides
+- Extract domain terms, service names, team agreements, deployment topology
+
+### Miro
+
+When the engineer provides a Miro board URL, use available Miro MCP tools to:
+- Read the board content: system diagrams, data flow, component maps
+- Extract topology, component names, and integration boundaries
+
+## Investigation Process
+
+Work through all six steps in order. Do not skip steps.
+
+**Re-run detection:** If Step 2 classifies all files as **current** or **stale** (none missing), this is a re-run. In re-run mode: skip Step 3 unless the engineer provided external source URLs in the skill invocation. Step 4b reduces to: "I found these gaps between the existing docs and the current codebase: [list]. Anything else I should know before updating?"
+
+### Step 1 — Investigate the codebase
+
+Read every template in the Templates table. Each `{{PLACEHOLDER}}` is an investigation target.
+
+**Investigation paths (in this order):**
+
+1. **Build file** — framework, version, dependencies, plugins, and the commands needed to build, test, and run the service (full build, skip-tests, single module, single test class)
+2. **Entry point** — main class or bootstrap file, annotations, base package/module
+3. **Configuration** — app config files, property/env prefixes, profiles, feature flags
+4. **Tests** — test files and directories, framework, infrastructure (containers, mocks), naming
+5. **Source structure** — directory tree of production code, layer names
+6. **API surface** — endpoints, handlers, response types, error handling
+7. **CI and infrastructure** — pipeline files at repo root
+
+**Stop when** you can fill every template placeholder with a value from the codebase. Do not catalogue patterns that no template section requires.
+
+### Step 2 — Classify existing harness files
+
+1. Check if `CLAUDE.md` exists at root and check for `.md` files in `docs/`.
+2. For each present file, note the `*Last updated*` date.
+3. Classify: **missing** (create from template), **stale** (regenerate), **current** (targeted updates only).
+4. Check for `.md` files in `docs/` that are NOT in the Output Files table. Flag them to the engineer: "These files exist but are not part of the harness set. Should they be deleted, moved, or kept as standalone references?"
+
+A file is stale if it references non-existent classes/packages or is missing sections present in the template.
+
+### Step 3 — Gather external context
+
+Pull from every source the engineer provides:
+- Jira / Confluence: fetch linked pages; extract architecture docs, team decisions, domain glossary
+- Miro: read the board; extract system diagram, component names, integration boundaries
+- Any other URLs or documents pasted directly
+
+Ask the engineer **once**:
+- "Are there any Confluence pages, Miro boards, Jira epics, architecture diagrams, or runbooks I should read? Paste URLs or ticket keys here."
+
+### Step 4 — Identify unknowns and ask the engineer
+
+Ask the engineer **once**, grouping all questions in a single message:
+
+- **High-risk areas:** Are there areas where a wrong AI change would cause damage beyond a normal bug (data loss, broken contracts, security vulnerability, silent CI breakage)? These will go in `coding-guidelines.md` §12 High-Risk Areas.
+- **Domain:** What does `[term]` mean in this service's context? (list any terms the codebase uses that could not be inferred)
+- **Dependencies:** What does this service call outbound? What calls it inbound?
+- **Deployment:** Deployment config path or infrastructure repo location?
+- **Gaps:** For anything you could not determine from investigation paths 1-7, list each gap explicitly.
+
+Wait for answers before writing anything.
+
+### Step 5 — Write the files
+
+Write (or update) all 5 files. Rules:
+
+1. Create `docs/` if it does not exist.
+2. Read the corresponding template before writing each file.
+3. Replace every `{{PLACEHOLDER}}` with discovered or confirmed content. No placeholder may remain.
+4. **`coding-guidelines.md`:** Include a Logging section.
+5. **Re-run mode:** for existing files, diff each section against what you would generate from scratch. If an existing section contains information you cannot find in the codebase or provided external sources (team decisions, deployment details, transitional notes, "do not" warnings), preserve it and mark it with a comment `<!-- preserved: not verifiable from codebase -->` so the engineer can confirm or remove during review.
+6. **Every section must earn its space.** If it restates general knowledge (SOLID, DRY, composition over inheritance, KISS, YAGNI), delete it. Only write content specific to this repo that would cause wrong output if missing.
+7. **No cross-file duplication.** No instruction may appear in more than one output file. If you find yourself writing the same rule in two places, pick one file to own it and delete from the other.
+8. **`glossary.md`:** every definition must be complete enough to generate correct code from. Test: if reading only this definition, would the agent produce the right logic? If not, the definition is incomplete.
+9. **`architecture.md` §9 Key Design Decisions:** only include a decision when this repo deliberately chose against the common pattern and an agent would produce wrong code by defaulting to the standard approach. Zero entries is valid.
+10. **`architecture.md` §3 Layer Map:** list every class that owns meaningful logic. Depth guide: include the class if another developer needs to know it exists to avoid duplicating its responsibility. Exclude DTOs, mappers, and trivial config beans. One line per class: name, package, purpose.
+11. **`architecture.md` §10 Deployment Context:** determine the deployment mechanism from CI files and build config. Write two plain sentences: (1) how this service deploys (K8s/ArgoCD, EC2/AMI, Lambda, etc.), (2) where deployment config lives (separate repo path, or "in this repo at {{path}}"). Do not include deployment options that don't apply.
+12. **`architecture.md` §2 System Context:** if the engineer provided a Miro board, Confluence page, or diagram URL, transcribe it as an ASCII diagram above the table. If no external diagram source exists, omit the diagram block entirely. The neighbour table is always required. Populate it from codebase evidence (REST clients, Kafka producers/consumers, DB connections). For inbound callers not visible in code, ask the engineer.
+13. **`coding-guidelines.md` §12 High-Risk Areas:** include an entry when a wrong AI change causes damage beyond a normal bug (data loss, broken contracts, security vulnerability, silent CI breakage). The agent can still generate in these areas but must follow the area-specific rule and flag it in the PR. If the concern is merely inconsistent code style, fix the relevant coding-guidelines section instead. Common candidates: database migrations, published API contracts, infrastructure/CI files, credential handling, generated code. Zero entries is valid for simple repos.
+14. **`coding-guidelines.md` AI Usage Notes:** derive all three lists directly from §1–§12. Generate: (1) patterns AI must always follow, (2) patterns AI must never use, (3) things that contradict common defaults or conventions.
+
+**CLAUDE.md size check:** if the file exceeds 110 lines, audit for content that belongs in a sub-file.
+
+**Presentation mode:**
+- **Initial run (files missing):** present all files together as a complete set. Get one confirmation before writing to disk.
+- **Re-run (all files exist):** present changes one at a time. For each change: state the file, what you would change, and why (citing the template or codebase evidence). Wait for the engineer to say yes, no, or ask a question before presenting the next change. Only write approved changes to disk.
+
+### Step 6 — Validate
+
+Before presenting the output, verify:
+
+- [ ] All 5 files exist at the correct paths
+- [ ] `CLAUDE.md` has a Build Commands section with at least one runnable command
+- [ ] `CLAUDE.md` harness status table shows Present for all files that exist
+- [ ] No `{{PLACEHOLDER}}` text remains in any output file
+- [ ] `coding-guidelines.md` has at least one convention per section
+- [ ] `coding-guidelines.md` includes a Logging section
+- [ ] `architecture.md` has a system context description, layer map, and integration inventory
+- [ ] `glossary.md` has domain terms extracted from the codebase; if fewer than 3, flag to engineer
+- [ ] `coding-guidelines.md` §12 High-Risk Areas is populated (or engineer confirmed none exist)
+- [ ] `coding-guidelines.md` AI Usage Notes is populated with rules derived from §1–§12
+- [ ] `harness-gap-log.md` has the correct service name and empty Active Gaps section (or carried-over entries with actionable corrective actions)
+- [ ] All files have `*Last updated*` and `*Owner*` headers
+- [ ] No section in any file restates generic engineering principles
+- [ ] No instruction appears in more than one file
+
+Fix any failing items before presenting.
+
+## Output
+
+After all files are written, present a summary covering:
+- Files created vs updated
+- Key discoveries from investigation
+- Assumptions the engineer should confirm
+- Cross-file duplication check: confirm no instruction appears in more than one file
+- Generic content audit: confirm no SOLID/DRY/KISS/YAGNI sections remain
+
+Harness is ready. Next step is for the engineer: produce a spec for the first (or next) feature before any generation begins.

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

@@ -0,0 +1,88 @@
+# CLAUDE.md — {{SERVICE_NAME}}
+
+*Last updated: {{DATE}}*
+*Owner: {{TEAM_NAME}}*
+
+---
+
+## Purpose
+
+Entry point for AI generation in `{{SERVICE_NAME}}`. This is an index. Conventions live in `docs/coding-guidelines.md`. Architecture lives in `docs/architecture.md`.
+
+---
+
+## Harness Status
+
+| File | Status |
+|------|--------|
+| coding-guidelines.md | Present |
+| architecture.md | Present |
+| glossary.md | Present |
+| harness-gap-log.md | Present |
+| testing.md | Pending — conventions in coding-guidelines.md for now |
+
+---
+
+## What This Service Does
+
+`{{SERVICE_NAME}}` {{SERVICE_ONE_LINE_DESCRIPTION}}.
+
+Service: `{{SERVICE_NAME}}` | Framework: {{FRAMEWORK_AND_VERSION}} | Main class: `{{MAIN_CLASS}}`
+
+---
+
+## Build Commands
+
+```shell
+{{BUILD_ALL_COMMAND}}
+{{BUILD_SKIP_TESTS_COMMAND}}
+{{RUN_TESTS_SINGLE_MODULE_COMMAND}}
+{{RUN_SINGLE_TEST_CLASS_COMMAND}}
+```
+
+---
+
+## Read Before Generating
+
+1. `docs/coding-guidelines.md` — conventions for this repo
+2. `docs/architecture.md` — service boundaries and integrations
+3. `docs/glossary.md` — domain terms; use exactly as defined
+4. `docs/harness-gap-log.md` — check for open gaps; apply corrective actions
+5. `docs/specs/[TICKET]/SPEC.md` — required before any generation
+
+No spec provided? Stop and ask for one.
+
+<!-- FILL IN or REMOVE: only if deployment config lives outside this repo -->
+**Deployment context:** This service deploys via a separate repo (`{{DEPLOYMENT_CONFIG_PATH}}`). The agent cannot read it. If generation needs environment config or service URLs, the engineer must paste relevant values into the session.
+
+---
+
+## Service Dependencies
+
+<!-- FILL IN: one row per dependency -->
+| Service | Communication | Declared in |
+|---------|---------------|-------------|
+| {{SERVICE}} | {{REST / Kafka / etc.}} | {{Class}} |
+
+<!-- FILL IN or REMOVE: transitional/disabled dependency notes -->
+
+---
+
+## Definition of Done
+
+- [ ] Inputs validated at the boundary
+- [ ] Errors handled explicitly (no silent swallowing)
+- [ ] No secrets or hardcoded environment values
+- [ ] Tests cover spec scenarios (happy path + failures)
+- [ ] Build passes and quality gate is green
+
+---
+
+## Pull Requests
+
+When creating a PR, include in the body:
+- **Ticket** link
+- **What changed** (one paragraph)
+- **Spec path** referenced
+- **What was manually adjusted** (be specific; "Nothing" is valid)
+- **Harness gaps** encountered (or "None")

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

@@ -0,0 +1,152 @@
+# architecture.md — {{SERVICE_NAME}}
+
+*Last updated: {{DATE}}*
+*Owner: {{TEAM_NAME}}*
+
+---
+
+## 1. Purpose
+
+`{{SERVICE_NAME}}` {{SERVICE_PURPOSE_ONE_PARAGRAPH}}.
+
+---
+
+## 2. System Context
+
+<!-- Include a diagram here only if transcribed from an external source (Miro board, Confluence page, whiteboard photo). Do not invent one. The table below is the authoritative source of truth. -->
+
+| Neighbour | Role | Communication | Notes |
+|-----------|------|---------------|-------|
+| **{{ServiceName}}** | {{role relative to this service}} | {{REST / Kafka / gRPC / S3 / etc.}} | {{retry policy, cache, transitional status, or "—"}} |
+| **{{ServiceName}}** | {{role relative to this service}} | {{protocol}} | {{notes or "—"}} |
+
+{{INTEGRATION_NOTES — expand on transitional, disabled, or non-obvious integrations}}
+
+---
+
+## 3. Internal Layer Map
+
+<!-- Include only layers that exist. Remove any that do not. -->
+
+```
+{{ENTRY_POINT_LAYER}}  ({{package}})
+  ├── {{Class}}          — {{one-line purpose}}
+  └── {{Class}}          — {{one-line purpose}}
+
+{{BUSINESS_LOGIC_LAYER}}  ({{package}})
+  ├── {{Class}}             — {{one-line purpose}}
+  └── {{Class}}             — {{one-line purpose}}
+
+{{PERSISTENCE_LAYER}}  ({{package}})
+  ├── {{Class}}          — {{tables or store in scope}}
+  └── {{Class}}          — {{tables or store in scope}}
+
+<!-- FILL IN or REMOVE: only if scheduled tasks exist -->
+{{SCHEDULING_LAYER}}  ({{package}})
+  ├── {{Class}}          — {{what it does}}
+  └── {{Class}}          — {{what it does}}
+
+<!-- FILL IN or REMOVE: only if outbound integrations exist -->
+{{INTEGRATIONS_LAYER}}  ({{package}})
+  ├── {{Class}}          — {{protocol + target}}
+  └── {{Class}}          — {{protocol + target}}
+
+Cross-cutting
+  ├── {{ExceptionHandler}}
+  └── {{other cross-cutting concerns — cache, locks, filters}}
+```
+
+---
+
+## 4. {{PRIMARY_DOMAIN_CONCEPT}} Lifecycle
+
+<!-- FILL IN or REMOVE: include only if service manages a domain entity with state transitions. -->
+
+### State machine
+
+```
+{{ASCII_STATE_MACHINE}}
+```
+
+### Key invariants
+
+{{KEY_INVARIANTS — correctness guarantees that must always hold}}
+
+---
+
+## 5. Database Schema
+
+<!-- FILL IN or REMOVE: include only if service owns a database. -->
+
+Schema: `{{DB_SCHEMA_NAME}}`
+Migration tool: {{MIGRATION_TOOL}}
+
+```
+{{TABLE_DEFINITIONS — from migration files}}
+```
+
+{{SCHEMA_DESIGN_NOTES — non-obvious decisions: state split, CASCADE, idempotency}}
+
+---
+
+## 6. Messaging Topology
+
+<!-- FILL IN or REMOVE: include only if service produces or consumes async messages. -->
+
+| Topic / Queue | Direction | Producer | Consumer | Purpose |
+|---------------|-----------|----------|----------|---------|
+| `{{name}}` | Outbound | `{{Class}}` | {{downstream}} | {{purpose}} |
+| `{{name}}` | Inbound | {{upstream}} | `{{Class}}` | {{purpose}} |
+
+{{MESSAGING_DESIGN_NOTES — outbox pattern, partition strategy, delivery guarantees}}
+
+---
+
+## 7. Scheduling Subsystem
+
+<!-- FILL IN or REMOVE: include only if service has scheduled tasks. -->
+
+| Scheduler | Schedule | Lock name | Purpose |
+|-----------|----------|-----------|---------|
+| `{{Class}}` | {{delay or cron}} | {{lock name or "none"}} | {{purpose}} |
+
+{{SCHEDULING_NOTES — coordination mechanism, duplicate execution risk, timing dependencies}}
+
+---
+
+## 8. REST API Surface
+
+<!-- FILL IN or REMOVE: include only if service exposes HTTP endpoints. -->
+
+### {{ControllerClass}} — `{{/api/v1/path}}`
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| {{POST/GET/etc.}} | `{{full path}}` | {{purpose}} |
+
+Error response format: {{plain string / structured JSON / RFC 7807}}.
+Exception mapping: centralised in `{{ExceptionHandlerClass}}`.
+Status codes in use: {{list}}.
+
+---
+
+## 9. Key Design Decisions
+
+<!-- FILL IN or REMOVE: only when this repo chose against the common pattern and an agent would produce wrong code by default. Remove section if zero entries. -->
+
+### Why {{decision}} instead of {{alternative}}?
+
+{{EXPLANATION}}
+
+---
+
+## 10. Deployment Context
+
+{{DEPLOYMENT_MECHANISM}}
+{{DEPLOYMENT_CONFIG_LOCATION}}
+
+Image/artefact build: {{Jib / Docker / AMI / other}}.
+<!-- FILL IN or REMOVE: include only if service uses a container registry -->
+Registry: {{URL}}, image: {{name}}.
+
+For generation involving environment config, service URLs, or infrastructure values: engineer must paste config. Do not guess.

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.}