@groupby/ai-dev 0.5.5 → 0.5.8

package/teams/fhr-ai-team/resources/claude-code-setup.md

@@ -0,0 +1,60 @@
+# Claude Code Setup
+
+## Installation
+
+### Via Plugin System (Recommended)
+
+```bash
+# Add the marketplace (if not already added)
+/plugin marketplace add Attraqt/ai-agent-skills-marketplace
+
+# Install the plugin
+/plugin install ai.pierre@ai-agent-skills-marketplace
+```
+
+### Manual Install (Local Development)
+
+```bash
+# Clone the repo
+git clone https://github.com/Attraqt/ai.agent-skills.git
+
+# Run Claude Code with the plugin directory
+claude --plugin-dir /path/to/ai.agent-skills
+```
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/brainstorm` | Codebase-aware brainstorming with dynamic repo discovery |
+| `/plan` | Implementation planning with mandatory codebase search and code reuse |
+| `/plan-algo-tests` | Interactive 3-stage pipeline test configuration and Kubeflow JSON generation |
+| `/test` | Local pytest, Kubeflow pipeline e2e, or MLflow model validation |
+
+### Usage Examples
+
+```
+/brainstorm adding sparse retrieval to semantic search
+/plan BGE-M3 migration for algo.semantic-search-ml
+/plan-algo-tests
+/test algo.search-ml unit tests
+```
+
+## Bundled Skills
+
+These skills are loaded automatically and invoked based on context:
+
+| Skill | Auto-invoked when |
+|-------|-------------------|
+| `ml-tooling-dev` | Working with Kubeflow, MLflow, or MongoDB |
+| `naming-conventions-reviewer` | Writing or reviewing code in any ML repo |
+| `brainstorming` | Designing or exploring features |
+| `planning` | Breaking down implementation tasks |
+| `algo-test-planning` | Configuring pipeline test runs |
+| `e2e-testing` | Running any type of test |
+
+## How Auto-Routing Works
+
+The `CLAUDE.md` file at the plugin root defines when each skill should be invoked.
+Claude Code reads this file and applies the appropriate skill based on your request context.
+You can also invoke skills explicitly via slash commands.

package/teams/fhr-ai-team/resources/copilot-setup.md

@@ -0,0 +1,64 @@
+# GitHub Copilot Setup
+
+## Installation
+
+### Copy Skills to Your Repository
+
+```bash
+# Clone ai.agent-skills
+git clone https://github.com/Attraqt/ai.agent-skills.git /tmp/ai.agent-skills
+
+# Copy skills to your project
+mkdir -p .github/skills
+cp -R /tmp/ai.agent-skills/skills/* .github/skills/
+```
+
+### Add Copilot Instructions
+
+Copy the instructions files from this repository into your project:
+
+```bash
+cp /tmp/ai.agent-skills/.github/copilot-instructions.md .github/copilot-instructions.md
+mkdir -p .github/instructions
+cp /tmp/ai.agent-skills/.github/instructions/*.instructions.md .github/instructions/
+```
+
+The instructions are split into two layers:
+
+- [`.github/copilot-instructions.md`](../.github/copilot-instructions.md) - Generic rules: Crownpeak AI team conventions and commit message standards. Applied to all reviews.
+- [`.github/instructions/python.instructions.md`](../.github/instructions/python.instructions.md) - Python coding style. Applied only when reviewing `**/*.py` files.
+
+You can add more language-specific files (e.g. `typescript.instructions.md`) following the same pattern. See [GitHub docs on path-specific instructions](https://docs.github.com/en/copilot/tutorials/customize-code-review#when-to-use-path-specific-instructions) for details.
+
+### Agent Personas (Optional)
+
+Copy agent definitions for specialized review:
+
+```bash
+mkdir -p .github/agents
+
+# Create a naming reviewer agent
+cat > .github/agents/naming-reviewer.md << 'EOF'
+You are an expert reviewer for naming conventions in Crownpeak/Earlybirds ML repositories.
+Review code changes for naming consistency using the rules in .github/skills/naming-conventions-reviewer/SKILL.md.
+Flag violations with the correct canonical name.
+EOF
+```
+
+Invoke in Copilot Chat:
+```
+@naming-reviewer Review this PR for naming convention violations
+```
+
+## Usage Tips
+
+1. **Keep instructions concise.** Copilot works best with focused, summarized rules rather than full skill files.
+2. **Use agents for review.** The naming-reviewer agent is useful for PR reviews.
+3. **Reference skills in chat.** When working on pipeline configs, paste relevant content from `skills/ml-tooling-dev/` into Copilot Chat for context.
+4. **Combine with PR reviews.** Configure Copilot to use the naming-reviewer agent for automated PR checks.
+
+## Limitations
+
+- Copilot does not support the interactive AskUserQuestion flow used by brainstorming and algo-test-planning skills
+- Pipeline-specific skills (ml-tooling-dev, algo-test-planning) work best in Claude Code or OpenCode where they can execute commands
+- For full skill support, use Claude Code or OpenCode

package/teams/fhr-ai-team/resources/onboarding.md

@@ -0,0 +1,179 @@
+# Claude Code — Team Tips & Best Practices
+
+> After installing the plugin per [claude-code-setup.md](claude-code-setup.md), read this before your first ticket.
+
+---
+
+## 1. Initial Setup
+
+### GitHub Access
+
+Connect Claude Code to GitHub by selecting **individual repositories** — never grant org-wide access. This is a security requirement. If you run into authorization issues, ask Pavel, Julian, or Aurélie for help.
+
+### Atlassian Integration
+
+You can connect Claude Code to Atlassian so you can reference Jira ticket IDs directly in your prompts instead of copy-pasting ticket content.
+
+### Essential Skills to Install
+
+Before you start working, make sure you have at least these skills available (check with `/` in a session):
+
+- **Grill Me** — structured requirements Q&A before implementation
+- **Handoff** — summarizes a session into a spec for the next one
+- **Caveman** — strips pleasantries to save tokens (multiple verbosity levels)
+
+If skills don't appear after installation, try these steps in order:
+
+1. Open a new session and type `/` to check if skills are listed
+2. If not, try reloading skills from the settings
+3. If still missing, restart the desktop app entirely
+4. If you installed via CLI but use the desktop app (or vice versa), you may need to reinstall using the method that matches your interface
+
+---
+
+## 2. Workflow: From Ticket to PR
+
+### Step 1 — Read the Ticket
+
+Read and understand the ticket yourself first. You need to be able to answer Claude's questions during the Grill Me phase. Don't skip this.
+
+### Step 2 — Grill Me Session
+
+Paste the ticket content into a code block (triple backticks), add your instruction and context below it, then invoke `/grill-me`.
+
+```
+\`\`\`
+<ticket content here>
+\`\`\`
+
+I want to implement this ticket within the repository <repo-name>.
+/grill-me
+```
+
+**What Grill Me does:** It injects a prompt that tells Claude to interview you relentlessly about every aspect of the plan, traversing a "design tree" of implementation possibilities until you both reach a shared understanding of what to build.
+
+**Why it matters:**
+- Surfaces things you forgot or didn't think about (e.g., deployment strategy, missing endpoints)
+- Reaches an explicit **agreement** with the LLM — so it doesn't guess or go off-track during implementation
+- Without it, Claude still asks questions, but they're less structured and less relevant. You end up spending more tokens correcting course later.
+
+**During the Q&A:**
+- Read Claude's recommendations before answering — they're usually good, but not always what you want
+- You can reply with just "B" or "recommendation" when you agree — be token-efficient
+- When Claude asks about something out of scope, say so clearly: "Authentication will be handled on the infrastructure side and should not be implemented in this ticket" — not just "don't include this" (too vague, causes misinterpretation)
+- If Claude asks about something you're unsure of, provide context even if it wasn't in the ticket — this enriches later decision-making
+
+**Variant — Grill Me with Docs:** Searches your codebase documentation to ask better-informed questions. Useful when you're not sure how to answer a Grill Me question yourself.
+
+### Step 3 — Handoff to a Fresh Session
+
+After Grill Me reaches "ready to implement," use `/handoff`. This generates a markdown specification summarizing the agreed plan. Then start a new session and point Claude at that spec.
+
+**Why not just keep going in the same session?**
+- Long sessions bloat context — every message you send includes all previous conversation
+- More context = more token cost + degraded LLM quality ("the more context it has, the dumber it gets")
+- `/handoff` gives you a clean start with only what matters
+
+Alternative: `/compact` does a similar context reset within the same session.
+
+### Step 4 — Implementation
+
+Point Claude at the handoff spec and let it implement. The desktop app (not CLI) will handle PR creation and avoid pushing directly to develop.
+
+### Step 5 — Review
+
+Use `/review` for a general code review of your changes. You can also fine-tune review behavior via `copilot-instructions.md` in the repository.
+
+---
+
+## 3. Prompting Techniques
+
+### Be Terse, but Not Ambiguous
+
+Saving tokens is good. Losing meaning is not. "B" is fine when Claude gives you options. "Don't include this" is too vague when scoping out a feature — say what you mean and why.
+
+### Provide Full Stack Context
+
+Claude doesn't know your stack unless you tell it. Missing context leads to rework — even a good Grill Me session can miss things if Claude doesn't know about your tooling.
+
+At the start of a session (or in your Grill Me prompt), mention:
+- **Frameworks and services** your project depends on (LangFuse, Streamlit, FastAPI, etc.)
+- **Deployment targets** (ArgoCD, Argo App ML, Kubeflow, specific namespaces)
+- **Data sources** (MongoDB collections, MLflow experiment names)
+- **What's out of scope** for this ticket (auth, infra, other tickets handling adjacent work)
+
+If you're unsure what context matters, use the **Grill Me with Docs** variant — it reads your codebase docs to fill in gaps.
+
+### Use Code Blocks for Pasted Content
+
+Wrap ticket text, specs, or any pasted content in triple backticks. Keeps the prompt clean and helps Claude distinguish instructions from reference material.
+
+### Use `/rewind` When Things Go Wrong
+
+Rolls back both conversation and code changes to any previous point. Extremely useful when Claude goes down the wrong path.
+
+---
+
+## 4. Token Efficiency
+
+- **Caveman skill** reduces conversational overhead. At higher levels it switches to the most token-efficient language (while still generating code in English).
+- **Smaller tickets = fewer tokens.** Split work into focused subtasks. One task per session is the sweet spot.
+- **Avoid 1M-token context models** — quality degrades well before that limit. Standard context with fresh sessions works better.
+- **Handoff between sessions** instead of accumulating context in one long conversation.
+- **French uses more tokens than English** due to accents and tokenization. If token budget is tight, prompt in English.
+
+---
+
+## 5. Building & Using Skills
+
+Skills are more than markdown prompts — they're most powerful when they wrap **scripts** that Claude executes.
+
+### The Pattern
+
+1. **Skill file** (markdown) — describes the workflow, what scripts to use at each step, and provides context (URLs, environment info, conventions)
+2. **Scripts** (bash/python) — do the actual work without burning tokens on CLI commands
+
+### Example: ML Tooling Dev Skill
+
+Manages Kubeflow, MLflow, and MongoDB by providing Claude with pre-built scripts for querying pipelines, reading logs, checking run status, and updating configs. Claude uses the scripts directly instead of figuring out `kubectl` commands from scratch each time.
+
+### Why Scripts Over MCP
+
+- **Adapted to your workflow** — generic MCPs don't know your conventions
+- **Token-efficient** — scripts execute directly; MCP adds an LLM layer for each tool call
+- **Documented** — docs in the skill help Claude understand what each script does
+
+### Improving Skills Iteratively
+
+When a skill produces errors, feed those errors back to Claude and ask it to enhance the skill. Each iteration reduces token waste and improves reliability.
+
+### Creating Skills from Sessions
+
+At the end of a productive session, ask Claude: "Based on this session, use Skill Creator to build a skill that replicates what I just did." Results vary by session complexity, but it's a good starting point.
+
+---
+
+## 6. Multi-Repository Work
+
+For projects spanning multiple repos:
+
+1. Keep all project repos in one parent directory
+2. Add a `CLAUDE.md` at the parent level that summarizes how the projects relate
+3. Launch Claude from that parent directory
+4. Tell Claude to look at local repos when it needs cross-project context
+
+---
+
+## 7. Security Reminders
+
+- **GitHub:** Select individual repos, not org-wide access
+- **Credentials/tokens:** Don't hardcode secrets in code Claude generates. Use `.env` files and ensure they're in `.gitignore`. Claude Code settings can be configured to ignore sensitive files by default.
+- **Audit trail:** Everything Claude does is under **your** username. Treat its actions as your own — review before merging.
+- **Destructive commands:** Claude is reluctant to run Terragrunt, and cautious with SQL. This is by design. Don't override these guardrails without thinking.
+- **Auto mode:** Be careful — it can push to develop or skip branch creation if you're not watching. Before entering auto mode, always verify: (1) you're on a feature branch, not develop; (2) the remote is set correctly. If something goes wrong, use `git reflog` to find your previous state and `git reset` to recover. Ask for help if unsure.
+
+---
+
+## 8. Learning from Claude
+
+Read Claude's traces (`Cmd+O` on macOS) — the full trace of what Claude does is visible and educational. You'll learn bash techniques, see its reasoning process, and spot errors you can feed back to improve skills.

package/teams/fhr-ai-team/resources/opencode-install.md

@@ -0,0 +1,29 @@
+# OpenCode Installation
+
+## Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/Attraqt/ai.agent-skills.git
+   ```
+
+2. Open the project in OpenCode. The `AGENTS.md` file at the repo root is loaded automatically and provides agent instructions.
+
+3. Skills in the `skills/` directory are discovered automatically via directory convention.
+
+## How It Works
+
+- **No slash commands needed.** The agent reads `AGENTS.md` and automatically selects the appropriate skill based on your natural language request.
+- Skills are stored as `skills/<skill-name>/SKILL.md` files with supporting references and scripts.
+- The agent maps your request to the right skill (e.g., "design a feature" triggers brainstorming, "test the pipeline" triggers algo-test-planning).
+
+## Example Prompts
+
+| What you say | Skill invoked |
+|-------------|---------------|
+| "Let's brainstorm how to add image search" | brainstorming |
+| "Plan the implementation for BGE-M3 migration" | planning |
+| "I want to test the semantic search pipeline for Myer" | algo-test-planning |
+| "Run the tests for algo.search-ml" | e2e-testing |
+| "Check the status of my Kubeflow run" | ml-tooling-dev |
+| "Review the naming in this PR" | naming-conventions-reviewer |

package/teams/fhr-ai-team/resources/opencode-setup.md

@@ -0,0 +1,43 @@
+# OpenCode Setup
+
+## Installation
+
+```bash
+git clone https://github.com/Attraqt/ai.agent-skills.git
+```
+
+Open the cloned directory in OpenCode. No additional setup is required.
+
+## How It Works
+
+- `AGENTS.md` at the repo root is loaded automatically and provides agent instructions
+- Skills in the `skills/` directory are discovered via directory convention
+- The agent automatically selects the appropriate skill based on your natural language request
+- No slash commands are needed; the agent detects intent and routes to the right workflow
+
+## Skill Routing
+
+| Your request | Skill invoked |
+|-------------|---------------|
+| "Let's brainstorm how to..." | `skills/brainstorming/SKILL.md` |
+| "Plan the implementation for..." | `skills/planning/SKILL.md` |
+| "Test the pipeline for..." | `skills/algo-test-planning/SKILL.md` |
+| "Run the tests for..." | `skills/e2e-testing/SKILL.md` |
+| "Check my Kubeflow run" | `skills/ml-tooling-dev/SKILL.md` |
+| "Review the naming in..." | `skills/naming-conventions-reviewer/SKILL.md` |
+
+## Using in Other Projects
+
+To use ai.pierre skills when working in a different project repo:
+
+1. Ensure `AGENTS.md` is copied or symlinked to your project root
+2. Copy the `skills/` directory (or specific skills you need) into your project
+3. The agent will auto-discover and apply them
+
+Alternatively, reference the skills directory in your OpenCode configuration to load them globally.
+
+## Notes
+
+- The skill routing depends on the model consistently following rules in `AGENTS.md`
+- For best results, keep your requests natural and descriptive
+- The agent will use the `question` tool (OpenCode equivalent of AskUserQuestion) to gather requirements interactively

package/teams/fhr-ai-team/skills/algo-test-planning/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: algo-test-planning
+description: >
+  Use when the user wants to plan or configure a test for an algo pipeline. Guides through
+  pipeline selection, config gathering, and Kubeflow config JSON generation via a 3-stage
+  interactive flow using AskUserQuestion. Covers full multi-step pipelines and base
+  single-step pipelines.
+---
+
+# Algo Pipeline Test Planning
+
+## Overview
+
+This skill guides you through planning and configuring a test run for an ML pipeline.
+It produces a complete Kubeflow config JSON and a test plan with launch and verification steps.
+
+All pipeline operations target the **DEV environment only**.
+
+## Stage 1: Pipeline Type Selection
+
+Use AskUserQuestion to ask:
+
+**Question:** "What type of pipeline do you want to test?"
+
+| Option | Description |
+|--------|-------------|
+| Full pipeline | Multi-step end-to-end pipeline (e.g., learning + evaluation + encoding) |
+| Base/single-step pipeline | Single step using a base pipeline template |
+
+---
+
+## Stage 2a: Full Pipeline Selection
+
+If the user chose "Full pipeline", use AskUserQuestion to ask which pipeline.
+
+Consult `references/pipeline-registry.md` for the complete list grouped by domain.
+Present the most relevant options based on context, or let the user search.
+
+Common full pipelines by domain:
+
+**Semantic Search:**
+- `semantic_search_learning_with_generated_analytics_pipeline`
+- `semantic_search_item_encoding_pipeline`
+
+**Visual Search / CLIP:**
+- `clip_learning_pipeline`
+- `clip_item_encoding_pipeline`
+
+**Tagging:**
+- `tagging_learning_pipeline`
+- `transformer_tagging_learning_pipeline`
+
+**Image:**
+- `image_encoder_learning_pipeline`
+- `image_classifier_pipeline`
+
+**Shop the Look:**
+- `shop_the_look_learning_pipeline`
+
+**FM / Recommendations:**
+- `fm_learning_pipeline`
+
+**Text Encoder:**
+- `text_encoder_learning_pipeline`
+
+Then gather pipeline-specific config fields based on the selected pipeline's requirements
+(see `references/pipeline-registry.md` for required fields per pipeline).
+
+---
+
+## Stage 2b: Base Pipeline Selection
+
+If the user chose "Base/single-step pipeline", use AskUserQuestion to ask:
+
+**Question:** "Which base pipeline type?"
+
+| Option | Description |
+|--------|-------------|
+| `python_batch_pipeline` | Standard Python batch jobs |
+| `large_python_batch_pipeline` | GPU/high-memory Python batch jobs |
+| `scala_batch_pipeline` | Scala-based batch jobs |
+| `spark_scala_batch_pipeline` | Spark Scala batch jobs |
+
+Then ask:
+- **Strategy ID** (what job to run, e.g., `semantic-search-learning`, `item-images-single-encoding`)
+- **Docker image name** (e.g., `semantic-search`, `algo-fm-batch`)
+- **Arguments** specific to the strategy (varies by step type)
+
+Key rules for base pipelines:
+- `python_batch_pipeline` and `large_python_batch_pipeline` use `batch_config.arguments` for custom params
+- `scala_batch_pipeline` and `spark_scala_batch_pipeline` use `batch_config.custom_params` (NOT `arguments`)
+- GPU jobs must include `gpu_vendor: "nvidia.com/gpu"` and `gpu_accelerator_name: "nvidia-l4"` for L4 nodes
+
+---
+
+## Stage 3: Config Gathering and JSON Generation
+
+Use AskUserQuestion sequentially for each required input:
+
+### 3.1 Predictor ID
+Ask for the MongoDB ObjectId (e.g., `64f0a12b5856b11b7aa4e71e`).
+This identifies the tenant/predictor whose config will be used.
+
+### 3.2 Experiment Name
+Discover available experiments:
+```bash
+python3 scripts/kf_query.py --experiments
+```
+Or let the user provide one directly.
+
+### 3.3 Strategy ID
+Based on the pipeline or step selected. Reference `skills/ml-tooling-dev/references/pipeline-configs.md`
+for the canonical strategy ID list.
+
+### 3.4 Image Version
+Verify the version exists in Kubeflow:
+```bash
+python3 scripts/kf_query.py --pipeline-versions <pipeline_name>
+```
+Use the most recent `version_name` from the output (e.g., `"0.1.271"`).
+
+### 3.5 Dataset Paths (if applicable)
+GCS paths from previous pipeline runs. Discover via:
+```bash
+python3 scripts/kf_query.py <previous_run_id>
+```
+Check Kubeflow UI -> run -> succeeded steps -> Output artifacts tab.
+
+### 3.6 MLflow Run ID (if applicable)
+For evaluation or encoding steps that need a trained model:
+```bash
+python3 scripts/mlflow_query.py model-for-predictor <predictor_id>
+```
+
+### 3.7 MongoDB Config Check
+Read current training hyperparameters:
+```bash
+mongosh "mongodb://10.11.96.21:27017/earlybirds" --quiet --eval '
+const doc = db.predictors.findOne({"_id": ObjectId("<PREDICTOR_ID>")});
+print(JSON.stringify(doc.config.batch, null, 2));
+'
+```
+Present the current config to the user. Ask if any changes are needed before the test run.
+If changes are needed, generate the `updateOne` command (see `skills/ml-tooling-dev/references/mongodb-config.md`).
+
+### 3.8 Resource Overrides
+Use defaults from `skills/ml-tooling-dev/references/pipeline-configs.md` unless the user specifies:
+- CPU/memory requests and limits
+- GPU type and count
+- Disk size
+
+---
+
+## Output
+
+Generate the following:
+
+### 1. Complete Kubeflow Config JSON
+A ready-to-submit JSON file. Save to `/tmp/<pipeline>-<predictor_id>-test.json`.
+
+### 2. Pre-Launch Checklist
+- [ ] `version_name` verified via `kf_query.py --pipeline-versions`
+- [ ] MongoDB config confirmed (show current values)
+- [ ] Dataset paths validated (exist in GCS)
+- [ ] Experiment exists in Kubeflow
+
+### 3. Launch Command
+```bash
+cd attraqt-kubeflow-configs/scripts
+python -m run -c <absolute_path_to_config>
+```
+
+### 4. Verification Steps
+- Monitor run: `python3 scripts/kf_query.py <run_id>`
+- Check failed steps: `python3 scripts/kf_query.py <run_id> --failed`
+- Expected step outcomes for each pipeline step
+- Pod log patterns to watch for
+
+### 5. Failure Recovery
+- Debug failed steps: see `skills/ml-tooling-dev/references/kubectl-debug.md`
+- Common failure patterns and fixes
+- How to re-run individual failed steps
+
+---
+
+## Skill Dependencies
+
+This skill invokes `ai.pierre:ml-tooling-dev` for:
+- Config templates and validation
+- Kubeflow/MLflow query commands
+- MongoDB read/update operations
+- kubectl debugging commands