@groupby/ai-dev 0.5.12 → 0.5.14

package/package.json

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

package/teams/brain-studio/skills/docs-init/SKILL.md

@@ -0,0 +1,405 @@
+---
+name: docs-init
+description: Use when the user wants to initialize or refresh the fast-layer summary docs (`docs/*.md`), `CLAUDE.md`, and `README.md` from the current repo state. The authoritative source of truth stays in `docs/architecture/`; these summaries index and link into it. Triggered by `/docs-init` or requests like "update the docs", "refresh project documentation", "init docs", "bring docs up to date".
+---
+
+# docs-init
+
+Generate and audit the **fast/index layer** of project documentation. This layer
+indexes and links into the authoritative `docs/architecture/`, never duplicating
+it and never fabricating facts.
+
+This is a **standalone utility** — not part of the main AI workflow pipeline.
+Run it any time, independently of tickets or implementation.
+
+## Two documentation layers
+
+This project has two doc layers. Keep them distinct:
+
+1. **`docs/architecture/`** — the authoritative, detailed source of truth.
+   13+ files covering system overview, module structure, state management, data
+   flow, auth, tenancy, feature flags, services, integrations, build, testing,
+   code conventions, git workflow. **This skill never modifies these — it only
+   reads them.**
+
+2. **Fast layer (this skill manages it)** — `docs/*.md` summaries
+   (`architecture.md`, `local-setup.md`, `conventions.md`, `operations.md`,
+   `decisions.md`) plus `CLAUDE.md` and `README.md` as thin indexes. These are
+   executive summaries for quick human onboarding and quick AI context. They
+   **summarize and link into** `docs/architecture/` — they never replace or
+   duplicate it.
+
+## The fast-layer structure
+
+```text
+README.md                ← 30-second landing page + links
+CLAUDE.md                ← thin index for AI agents (~40 lines)
+docs/
+  architecture.md        ← summary: system, packages, domain model
+  local-setup.md         ← prerequisites, run, test commands
+  conventions.md         ← summary: code style, testing, PR norms
+  operations.md          ← deploy, secrets, observability
+  decisions.md           ← append-only "why" log (ADR-lite)
+```
+
+Every `docs/*.md` summary MUST start with a disclaimer block naming
+`docs/architecture/` as the authoritative source. Two rules govern it:
+
+**Which convention to use:**
+- New file (init mode), or an existing file with no disclaimer → use the
+  `> **Note:**` template below.
+- Existing file that already has a disclaimer (e.g. a `> **Scope:**` /
+  `> **Referenced from:**` block) → **preserve it as-is**. Do not swap
+  conventions; mixing them is noise, not an improvement.
+
+**The Doc Routing Table link is conditional.** The base disclaimer always points
+to `docs/architecture/`. Append the Doc Routing Table sentence **only if
+`.github/copilot-instructions.md` actually exists in the repo** (confirm with
+`ls` first). If it does not exist, omit that sentence — never emit a link to a
+file that is not there.
+
+Base (always):
+
+```markdown
+> **Note:** This is an executive summary for quick AI context. The
+> authoritative source of truth is `docs/architecture/`.
+```
+
+Append only when `.github/copilot-instructions.md` exists:
+
+```markdown
+> See the [Doc Routing Table](../.github/copilot-instructions.md) for which
+> architecture doc to consult for each task type.
+```
+
+## Procedure
+
+### 1. Detect mode
+
+- Check for `README.md`, `CLAUDE.md`, and each of the five `docs/*.md` summaries.
+- If three or more summaries are missing → **init mode**.
+- Otherwise → **refresh mode**.
+- Announce the detected mode before proceeding.
+
+### 2. Scan sources
+
+The primary source for the fast layer is `docs/architecture/` — **not raw code**:
+
+- Read the relevant `docs/architecture/*.md` files to extract facts.
+- Cross-reference actual code only where architecture docs may be stale.
+- `package.json` — versions, dependencies, and **yarn scripts** (the run/build/
+  test commands).
+- `.github/workflows/` — CI details and triggers.
+- `helm/`, `Dockerfile` — deploy details.
+- `docs/architecture/13-git-workflow.md` — commit/PR conventions.
+
+For refresh mode, also run `git log --since="<doc-mtime>"` per summary to narrow
+attention to recent changes a summary may not yet reflect.
+
+### 3a. Init mode — draft (do NOT write yet)
+
+Draft the seven fast-layer files in memory using the **canonical templates**
+below. Content comes from `docs/architecture/` — summarize and link, do not
+duplicate. Every `docs/*.md` starts with the `> **Note:**` disclaimer. Leave
+honest placeholders where no authoritative source exists yet. Do not fabricate.
+
+**Verification checklist — apply to every claim before including it.** The core
+rule: **every fact in a summary must trace to `docs/architecture/`, or to real
+source when the architecture docs are silent or stale.**
+
+1. **Commands** — Before writing any `yarn <script>` / `npm run <script>`,
+   confirm the script exists in `package.json`. Never guess script names.
+2. **Config keys** — Quote exact property paths from the actual config file
+   (`.env`, JSON, YAML, Helm values). Do not paraphrase or use placeholder
+   syntax like `${...}`.
+3. **Directory contents** — `ls` the directory before describing what it
+   contains. Never say "contains X" without checking.
+4. **Credentials** — Never instruct placing credentials in a repo-tracked file.
+   Recommend user-home config (`~/.npmrc`) or environment variables instead.
+5. **CI/CD triggers** — Read the actual GitHub Actions `on:` block. List all
+   branches/events accurately; do not guess.
+6. **Scope qualifiers** — When stating "all X do Y," verify there are no
+   exceptions before writing it.
+7. **File references** — When describing what a file is for, trace its
+   references (grep the filename) so the description matches actual usage.
+8. **Architecture-doc links** — When a summary section points to
+   `docs/architecture/NN-*.md`, confirm that file exists and covers that topic.
+9. **Cross-references resolve** — Every link in `CLAUDE.md`, `README.md`, and
+   the disclaimer's conditional Routing Table line must point to a file that
+   exists. `ls` before linking; omit or fix any link whose target is absent.
+
+Targets: `CLAUDE.md` ≤ 40 lines, `README.md` ≤ 30 lines, each `docs/*.md`
+summary ≤ 80 lines.
+
+**Do not write these files to disk yet.** Continue to step 4, where the drafts
+are summarized in the audit report and the user approves before any file is
+created.
+
+### 3b. Refresh mode — audit each summary
+
+For each existing summary, compare against `docs/architecture/` and code, and
+classify findings into three buckets:
+
+- **Outdated** — the summary states something no longer true.
+- **Drifted** — correct but missing material that `docs/architecture/` or the
+  code now contains.
+- **New opportunities** — content the summary does not have but probably should.
+
+`decisions.md` is **append-only**: propose new entries on approval, but never
+rewrite or remove existing ones.
+
+### 4. Report to the user (human-readable, NOT a diff)
+
+In **init mode**, the report summarizes what each new file will contain (one
+paragraph per file) and the "Proposed actions" list reads as `Create <path>`
+items. In **refresh mode**, it follows the per-file findings format below.
+
+```markdown
+# Documentation audit — <YYYY-MM-DD>
+
+Mode: <init | refresh>
+
+## Summary
+<2-3 sentences: what was created or what needs attention overall>
+
+## Per-file findings
+
+### docs/architecture.md (summary)
+**Outdated:** ...
+**Drifted:** ...
+**New opportunities:** ...
+
+(... continue for each file ...)
+
+## Proposed actions
+Numbered list of concrete edits. Group by file. Each item is one sentence — no diffs.
+
+## Verified against source
+- Commands: <which package.json scripts were confirmed>
+- Config keys: <which files were read for exact names>
+- Directories: <which directories were listed>
+- Workflow triggers: <which workflow files were read>
+- Architecture links: <which docs/architecture/ files were confirmed>
+- Line limits: <CLAUDE.md ≤40, README.md ≤30, each docs/*.md ≤80 — confirmed>
+- Credentials: <confirm no repo-tracked file instructions>
+
+## Awaiting your approval
+Reply "apply" to make the changes, "apply <numbers>" to apply a subset
+(e.g. "apply 1,3,5"), or "skip" to make no changes.
+```
+
+If a bucket is empty for a file, write `(none)` — do not omit it. This makes it
+obvious the check ran.
+
+### 5. Apply on approval
+
+- On `apply` — create or edit each affected file. In init mode, create all seven
+  fast-layer files from the step-3a drafts. In refresh mode, edit existing files
+  in place. Preserve `> **Note:**` and `> **Scope:**` blocks. Do not reorganize
+  content across files. Do not change file names.
+- On `apply <numbers>` — apply only the selected proposed actions.
+- On `skip` — make no edits or creations; thank the user and exit.
+- After applying, print a short summary of which files changed and suggest a
+  commit message.
+
+## Hard rules
+
+- **Apply edits only after explicit user approval.** No fast-layer file is
+  written before the user replies `apply` or `apply <numbers>`.
+- **Never touch `docs/architecture/`.** It is authoritative and managed
+  separately. Read it; never edit it.
+- **`decisions.md` is append-only.** New entries on approval; existing entries
+  are never edited or removed.
+- **Preserve every `> **Note:**` and `> **Scope:**` block** verbatim on edit.
+- **Do not move content between files.** Each file's scope is the convention.
+  If content fits none of the five, mention it in the report and ask.
+- **Do not fabricate.** If the repo has no dashboards, runbooks, or decisions
+  yet, leave honest placeholders or empty sections.
+- **Verify every factual claim** against `docs/architecture/` or source before
+  including it. See the verification checklist in step 3a.
+- **Summaries link, never duplicate.** Reference architecture docs by relative
+  path (e.g. "See `docs/architecture/03-state-management.md` for details")
+  instead of copying their content.
+- **Never reference repo-tracked files for credentials.** Use `~/.npmrc` or
+  environment variables.
+- **Qualify universal statements.** If writing "all X do Y," verify there are no
+  exceptions and add qualifiers if needed.
+- **Do not delete sections without flagging them** in the report.
+- **Do not edit `.github/`, CI files, or source code.** This skill only touches
+  the fast-layer docs.
+- **Keep line limits:** `CLAUDE.md` ≤ 40, `README.md` ≤ 30, each `docs/*.md`
+  ≤ 80. If pointers no longer fit, ask before expanding.
+
+## Common mistakes
+
+- Duplicating content from `docs/architecture/` into summaries (summarize and
+  link, do not copy).
+- Treating summaries as the source of truth — they are NOT.
+- Editing `docs/architecture/` files (out of scope for this skill).
+- Removing the `> **Note:**` disclaimer from a summary.
+- Making changes before user approval.
+- Fabricating operations info (dashboards, runbook URLs) that does not exist.
+- Guessing a `yarn` script name instead of confirming it in `package.json`.
+
+## Canonical templates
+
+When in init mode, use these summary-shaped skeletons. Each section holds 1–2
+sentences plus a link into `docs/architecture/` — not the details themselves.
+Fill from the architecture-doc scan.
+
+### `docs/architecture.md`
+
+```markdown
+# Architecture (summary)
+
+> <disclaimer block — see "The fast-layer structure" section.
+> Always points to `docs/architecture/`; append the Doc Routing Table line
+> only if `.github/copilot-instructions.md` exists.>
+
+## Overview
+<one paragraph: what this system is. → `docs/architecture/01-*.md`>
+
+## Module Structure
+<top-level layout in 2-3 lines. → `docs/architecture/02-*.md`>
+
+## State & Data Flow
+<one line each. → `docs/architecture/03-state-management.md`, `…-data-flow.md`>
+
+## Cross-Cutting Concerns
+<auth, tenancy, feature flags — one line each, with links into docs/architecture/>
+```
+
+### `docs/local-setup.md`
+
+```markdown
+# Local Setup (summary)
+
+> <disclaimer block — see "The fast-layer structure" section.
+> Always points to `docs/architecture/`; append the Doc Routing Table line
+> only if `.github/copilot-instructions.md` exists.>
+
+## Prerequisites
+<node/yarn versions and required tooling — confirmed from package.json>
+
+## Run / Build / Test
+<the actual `yarn <script>` commands, confirmed in package.json>
+
+## Environment
+<key env vars, exact names. → relevant docs/architecture/ doc>
+
+## Troubleshooting
+<common gotchas, or an honest placeholder if none documented yet>
+```
+
+### `docs/conventions.md`
+
+```markdown
+# Conventions (summary)
+
+> <disclaimer block — see "The fast-layer structure" section.
+> Always points to `docs/architecture/`; append the Doc Routing Table line
+> only if `.github/copilot-instructions.md` exists.>
+
+## Code Style
+<one line. → `docs/architecture/` code-conventions doc>
+
+## Testing
+<framework + philosophy in 1-2 lines. → testing doc>
+
+## PRs & Commits
+<commit/PR norms. → `docs/architecture/13-git-workflow.md`>
+```
+
+### `docs/operations.md`
+
+```markdown
+# Operations (summary)
+
+> <disclaimer block — see "The fast-layer structure" section.
+> Always points to `docs/architecture/`; append the Doc Routing Table line
+> only if `.github/copilot-instructions.md` exists.>
+
+## Deploy
+<pipeline + environments in 1-2 lines. → relevant docs/architecture/ doc>
+
+## Secrets
+<where secrets come from — never a repo-tracked file>
+
+## Observability
+<dashboards/alerts, or an honest placeholder if none exist yet>
+```
+
+### `docs/decisions.md`
+
+```markdown
+# Decisions
+
+> **Scope:** Short, append-only log of *why* this codebase is the way it is.
+> Captures decisions whose rationale is not obvious from reading the code.
+> Do **not** put how-to instructions here.
+
+## Format
+
+Append a new entry as a new top-level section. Don't edit prior entries — if a
+decision is reversed, add a new entry that supersedes the old one.
+
+Each entry:
+- **Context:** what prompted the decision
+- **Decision:** what we chose
+- **Consequence:** what this means going forward (and what we give up)
+
+## Entries
+
+*(No entries yet.)*
+```
+
+### `CLAUDE.md`
+
+```markdown
+# CLAUDE.md
+
+Index for AI coding agents. Keep this file short — point to `docs/` for substance.
+
+## What this repo is
+
+<one-paragraph description from the architecture-doc scan>
+
+## Where things live
+
+- **Architecture, domain model, module layout** → [docs/architecture.md](docs/architecture.md)
+- **Build / run / test commands** → [docs/local-setup.md](docs/local-setup.md)
+- **Code style, testing, PR rules** → [docs/conventions.md](docs/conventions.md)
+- **Deploy, secrets, observability** → [docs/operations.md](docs/operations.md)
+- **Why things are the way they are** → [docs/decisions.md](docs/decisions.md)
+
+> **Note:** `docs/*.md` files are executive summaries; the authoritative source
+> is `docs/architecture/`. (If `.github/copilot-instructions.md` exists, route
+> via its Doc Routing Table.)
+
+## Rules for working in this repo
+
+<3-6 short bullets — only repo-specific gotchas an agent must follow every turn.
+Do not duplicate detail that lives in docs/>
+```
+
+### `README.md`
+
+```markdown
+# <repo name>
+
+<one-paragraph description>
+
+## Quick start
+
+<3-5 lines: the shortest possible happy path, using confirmed yarn scripts>
+
+Requires <prereqs>. For detail see [docs/local-setup.md](docs/local-setup.md).
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — system overview, domain model, layout
+- [Local setup](docs/local-setup.md) — full setup, tasks, troubleshooting
+- [Conventions](docs/conventions.md) — code style, testing, PR rules
+- [Operations](docs/operations.md) — deploy, secrets, observability
+- [Decisions](docs/decisions.md) — why things are the way they are
+```

package/teams/fhr-andromeda/github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,51 @@
+## AI Generation Info
+
+- **Jira ticket:** <!-- e.g. ETL-1234 -->
+- **Agent type:** <!-- e.g. Java Dev - data-quality | Angular Dev - frontend | Python Dev - workflow-scripts -->
+- **AI tool:** <!-- e.g. Claude (claude-sonnet-4-6) | GitHub Copilot -->
+- **Spec referenced:** <!-- link to Jira spec or paste inline -->
+
+---
+
+## TDD Summary
+
+- **Tests written first:** <!-- yes / no — if no, explain why -->
+- **Test files:**
+  - <!-- src/test/java/... or src/integration-test/groovy/... -->
+- **Production files:**
+  - <!-- src/main/java/... -->
+
+---
+
+## What was generated
+
+<!-- Brief description of what the AI produced -->
+
+---
+
+## What was reviewed / changed after generation
+
+<!-- Any manual corrections made post-generation, and the reason -->
+<!-- If nothing was changed: "None — generated output accepted as-is" -->
+
+---
+
+## Review notes
+
+<!-- Areas that warrant careful human review — edge cases, security, reactive chains, migrations, etc. -->
+<!-- If none: "None identified" -->
+
+---
+
+## Checklist
+
+- [ ] Jira ticket referenced above
+- [ ] AI tool and agent type declared
+- [ ] Tests written before or alongside production code (TDD order)
+- [ ] Unit tests ≥ 90% coverage of new code, positive + negative cases
+- [ ] `BUILD SUCCESS` confirmed locally (`mvn clean install -pl <module> -am` or `ng build`)
+- [ ] No `TODO`, `FIXME`, or placeholder comments
+- [ ] No secrets, hardcoded URLs, or environment-specific values
+- [ ] Lombok used for all Java boilerplate; no manual getters/setters/constructors
+- [ ] Constructor injection used in all Spring beans (no `@Autowired` field injection)
+- [ ] Cross-repo impact checked — if `andromeda-argo-deployments` is affected, linked ticket exists

package/teams/fhr-andromeda/github/copilot-instructions.md

@@ -0,0 +1,47 @@
+# GitHub Copilot Repository Instructions
+
+This file is the Copilot bootstrap for this repository. It should stay short and only explain
+which context files to load and how to resolve conflicts.
+
+---
+
+## Mandatory Context
+
+Before answering technical questions or generating changes, read and apply:
+
+| File | Owns |
+|---|---|
+| [`CLAUDE.md`](../CLAUDE.md) | Repository map and harness file ownership |
+| [`.ai/architecture.md`](../.ai/architecture.md) | System boundaries, ETL workflow structure, and module responsibilities |
+| [`.ai/domain.md`](../.ai/domain.md) | Business terminology and ETL domain concepts |
+| [`.ai/ai-instructions.md`](../.ai/ai-instructions.md) | AI workflow, TDD protocol, stop conditions |
+| [`.ai/coding-guidelines.md`](../.ai/coding-guidelines.md) | Coding conventions and implementation rules |
+| Relevant module `CLAUDE.md` | Module-specific context and constraints |
+| [`.ai/jira-ticket-template.md`](../.ai/jira-ticket-template.md) | Full Jira ticket spec template |
+
+Use [`.ai/code-review.md`](../.ai/code-review.md) when reviewing code or diffs.
+
+---
+
+## Instruction Priority
+
+If guidance conflicts, apply this order:
+
+1. System/developer instructions.
+2. This bootstrap file.
+3. `.ai/ai-instructions.md`.
+4. Relevant module `CLAUDE.md`.
+5. `.ai/coding-guidelines.md`.
+6. Existing local code patterns.
+
+If a conflict still remains, stop and ask instead of guessing.
+
+---
+
+## Non-Negotiable Bootstrap Rules
+
+- For functional code tasks, follow the TDD workflow in `.ai/ai-instructions.md`.
+- Do not generate test or production code before Phase 1 approval.
+- Do not modify existing Flyway migrations.
+- Do not introduce new dependencies, modules, or infrastructure scope without explicit approval.
+- If required context is missing, declare a harness gap and wait for clarification.

package/teams/fhr-andromeda/instructions/CLAUDE.md

@@ -0,0 +1,66 @@
+# CLAUDE.md - Repository Context
+
+This file is the repository entrypoint for AI agents. It explains what this repo contains and
+which harness file owns each kind of guidance.
+
+---
+
+## Repository Purpose
+
+`fhr-apache-hop` contains application code for Fredhopper ETL 2.0, a Kubernetes-native data
+pipeline platform built around Apache Hop.
+
+Infrastructure definitions live in `andromeda-argo-deployments`. See `.ai/architecture.md` for
+the repository boundary definition.
+
+---
+
+## Harness File Ownership
+
+| File | Owns |
+|---|---|
+| `.github/copilot-instructions.md` | Copilot bootstrap and context-loading order |
+| `CLAUDE.md` | Repository map and harness ownership |
+| `.ai/architecture.md` | Stable system boundaries, ETL workflow structure, and module responsibilities |
+| `.ai/domain.md` | Business terminology and domain concepts |
+| `.ai/ai-instructions.md` | AI workflow, clarification, TDD, stop conditions, verification |
+| `.ai/coding-guidelines.md` | Coding conventions and implementation rules |
+| `.ai/code-review.md` | Review severity and checklist |
+| `.ai/jira-ticket-template.md` | Full Jira ticket spec template |
+| `<module>/CLAUDE.md` | Module-specific constraints and integration context |
+
+Keep each file focused on its owner topic. Do not duplicate detailed rules across files.
+
+---
+
+## Systems in This Repository
+
+| System | Modules | Purpose |
+|---|---|---|
+| ETL Engine | `fhr-custom-transforms`, `standard-etl-transformations`, `fhr-hop-server` | Apache Hop extensions, packaged ETL flows, and runtime image assembly |
+| Workflow Scripts | `workflow-scripts` | Python logic executed by Argo Workflow steps |
+| HDSys | `hop-dev-platform`, `hop-dev-platform-frontend` | Browser-based Hop workspace platform for ETL customisation |
+| DQSys | `data-quality`, `data-quality-frontend` | Data-quality reporting service and UI |
+
+---
+
+## Working in a Module
+
+Before changing a module:
+
+1. Read this file and the root context files listed above.
+2. Read the module's `CLAUDE.md`.
+3. Inspect existing code in the target area instead of relying on stale inventories.
+4. Follow `.ai/ai-instructions.md` for workflow and `.ai/coding-guidelines.md` for
+   implementation style.
+
+---
+
+## Build Entry Points
+
+Use the root Maven project for Java and packaging modules. Use each Angular module's package
+scripts for frontend modules. Prefer module-scoped builds unless a shared parent or cross-module
+contract changed.
+
+Exact commands are in `.ai/ai-instructions.md` §8. Use the module's current build files as the
+authoritative source for profiles and flags.