@groupby/ai-dev 0.5.15 → 0.5.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.5.15",
+  "version": "0.5.17",
   "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.