@groupby/ai-dev 0.5.7 → 0.5.9

package/teams/agentic-checkout/skills/karpathy-guidelines/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: karpathy-guidelines
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+license: MIT
+---
+
+# Karpathy Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

package/teams/agentic-checkout/skills/secret-safety/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: secret-safety
+description: Prevent credentials and sensitive tokens from being committed, logged, or pushed. Use before commits, pushes, PRs, and when editing config or examples.
+license: MIT
+---
+
+# Secret Safety
+
+Use this skill before committing, pushing, creating PRs, or editing configuration, examples, logs, credentials, or local
+environment files.
+
+## Rules
+
+- Never commit real credentials, API keys, private keys, tokens, session cookies, certificates, keystores, or populated `.env` files.
+- Keep secrets in environment variables, local untracked files, Vault, Azure Key Vault, GitHub Actions secrets, or another approved secret store.
+- Only commit placeholder examples such as `.env.example`, `.env.sample`, or documentation values that are clearly non-secret.
+- Do not paste secrets into prompts, PR descriptions, logs, commit messages, plans, or generated documentation.
+- If a secret appears in a tracked file, stop and remove it before committing or pushing.
+- If a real secret was committed or pushed, treat it as compromised: rotate/revoke it and remove it from git history using an approved process.
+
+## Checks
+
+Run the harness secret scanner before commit or push:
+
+```bash
+scripts/check-secrets .
+```
+
+When checking a component repository from the harness root, pass the component path:
+
+```bash
+scripts/check-secrets components/<component>
+```
+
+Install the harness pre-push hook for the harness checkout:
+
+```bash
+scripts/install-git-hooks
+```
+
+The scanner is a guardrail, not a guarantee. Also inspect diffs manually for sensitive values.

package/teams/agentic-checkout/skills/sync-components/SKILL.md

@@ -1,76 +1,39 @@
 ---
 name: sync-components
-description: Sync a multi-repository component workspace by cloning repositories listed in components.txt with minimal inspection. Use when asked to sync up, clone, or refresh project components.
+description: Sync component repositories from components.txt using the deterministic harness script.
 license: MIT
 ---
 
 # Sync Components
 
-Use this skill when the user asks to sync up a project's component repositories.
-
-## Goal
-
-Populate `components/` from the entries in `components.txt` using `git clone`, and leave each synced component on the `main` branch.
-
-Keep this workflow lightweight. Do not inspect component source trees, run builds, run tests, scan every repository, or perform broad Git status checks unless the user explicitly asks.
-
-Do not create a shell script, temporary script, generated helper, Makefile target, or wrapper command for this workflow. Running generated scripts often triggers extra approval prompts. Use direct shell commands only.
-
-## Source Of Truth
-
-Read `components.txt` from the framework or workspace checkout.
-
-Each non-empty, non-comment line is either:
-
-- A full Git remote URL, used as-is.
-- A repository name. If the file uses bare repository names, infer the Git remote from the project instructions or ask the user for the organization/remote prefix before cloning.
-
-The local checkout path for each entry is:
-
-```text
-components/<repo-name>
-```
-
-Derive `<repo-name>` from the entry basename and remove a trailing `.git`.
+Use when the user asks to sync, clone, refresh, or update component repositories.
 
 ## Workflow
 
-1. Confirm the current directory is the framework checkout.
-2. Create `components/` if it does not exist.
-3. Read `components.txt`.
-4. For each component entry:
-   - If `components/<repo-name>` does not exist, run:
-
-     ```bash
-     git clone <remote> components/<repo-name>
-     ```
-
-   - If the directory already exists, keep it and report `exists`.
-   - After clone or exists, run:
-
-     ```bash
-     git -C components/<repo-name> checkout main
-     ```
+1. Ask for the user's command approval through the normal Copilot CLI approval flow; do not enable `/allow-all`.
+2. Run exactly one of these commands after approval:
 
-   - If `main` is not available locally, fetch only the main branch and try again:
+   ```bash
+   scripts/sync-components
+   ```
 
-     ```bash
-     git -C components/<repo-name> fetch origin main
-     git -C components/<repo-name> checkout main
-     ```
+   or, when a local fast model summary is useful:
 
-5. Report only cloned, existing, checked-out-main, skipped, and failed component names.
+   ```bash
+   scripts/local-fast-report sync
+   ```
 
-Prefer issuing the `git clone` commands directly from the terminal. It is acceptable to run them one at a time. Do not generate a loop script or ask the user to run a script.
+3. Label `scripts/local-fast-report sync` runs as using the local fast model in any shell command title/description.
+4. Do not run both commands; `scripts/local-fast-report sync` already runs `scripts/sync-components`.
+5. Report cloned, existing, checked-out-main, rebased-main, skipped-dirty, and failed components.
+6. If any component is `skipped-dirty`, stop and ask before destructive cleanup or retry.
 
-## Constraints
+## Rules
 
-- Use direct `git clone` commands for this workflow.
-- Do not create, modify, chmod, or execute any sync script.
-- Do not use heredocs, shell redirection, or generated files to automate cloning.
-- Do not delete, reset, clean, or force checkout any component repository.
-- Do not pull existing repositories unless the user asks to update already-cloned components.
-- Do not fetch existing repositories except `git fetch origin main` when needed to make `main` available for checkout.
-- Do not open or validate component-local instruction files during this sync workflow.
-- Do not run dependency installation, tests, formatters, linters, or builds.
-- Keep all cloned repositories directly under `components/`.
+- Do not reimplement sync with model-driven `git clone`/`fetch`/`checkout`/`rebase` sequences unless the script fails and
+  the user approves manual recovery.
+- Do not bypass the user's normal command approval prompts.
+- Never delete, reset, clean, force-checkout, or discard existing component work without explicit approval for that
+  component.
+- Do not inspect component source, install dependencies, run tests/builds/formatters/linters, or read component-local
+  instructions during sync.

package/teams/agentic-checkout/skills/tdd/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: tdd
+description: Use a test-driven workflow for implementation tasks. Write or update a failing test first, implement the smallest change to pass, then verify and refactor.
+license: MIT
+---
+
+# TDD
+
+Use this skill when the user asks for TDD, test-first development, bug fixes with regression tests, or implementation
+where behavior should be proven by tests.
+
+## Workflow
+
+1. Identify the smallest observable behavior change.
+2. Find the closest existing test file, fixture style, and assertion pattern.
+3. Write or update a focused test before changing production code.
+4. Run the narrowest relevant test command and confirm the test fails for the expected reason.
+5. Implement the smallest production change needed to pass.
+6. Re-run the focused test.
+7. Run the nearest broader relevant test set when the change touches shared behavior, contracts, event payloads, or
+   public APIs.
+8. Refactor only after tests pass, then re-run the focused test.
+
+## Component Commands
+
+Prefer component-local instructions when present. Otherwise use the verification matrix in `AGENTS.md` as the canonical source for install/test/build/lint commands.
+
+For focused tests, use the component's existing test runner syntax for a single file, module, class, or test case.
+
+## Constraints
+
+- Do not make broad refactors before the red/green loop is complete.
+- Do not add new test frameworks or dependencies unless the component already uses them and the change requires it.
+- Do not add large test scaffolding when an existing test style can cover the behavior.
+- Do not skip the failing-test step unless tests cannot run locally or the change is documentation/configuration only.
+- If the failing-test step is skipped, explain why before editing production code.
+- Keep tests focused on observable behavior, not private implementation details.
+- For bug fixes, the first test should fail on the original bug.
+- For new behavior, the first test should encode the expected contract or user-visible behavior.
+
+## Reporting
+
+In the final response, include:
+
+- The test added or changed.
+- The initial failing command and failure summary, if run.
+- The passing verification command.
+- Any broader tests that were skipped and why.

package/teams/fhr-ai-team/github/PULL_REQUEST_TEMPLATE/full.md

@@ -0,0 +1,31 @@
+## Summary
+
+<!-- What problem does this solve? Link the ticket (XO-XXXX / EB-XXXX) if there is one. Brief summary of the approach. -->
+
+## Scope
+
+<!-- What is included in this PR? Delete this section when the scope is self-evident from the title. -->
+
+## Behavior
+
+<!-- Describe the observable outcomes of this change, not the implementation details.
+What does the system do differently after this PR? State it in terms a reviewer can verify:
+  - Given X, the system now does Y (previously: Z)
+  - Config key `foo.bar` controls ... ; default is ...
+For design decisions, explain what was chosen and why the alternatives were rejected. -->
+
+## Wiring
+
+<!-- How is the new code connected to the rest of the system? Which callers, configs, or entry points are affected? Delete this section for self-contained changes. -->
+
+## Tests
+
+<!-- How was this tested? List test commands, key scenarios covered, or link CI results. -->
+
+## How to run
+
+<!-- Steps to run or test this locally, if applicable. Delete this section for changes that don't need manual verification. -->
+
+## Backward compatibility
+
+<!-- Does this change any public API, config key, data format, or pipeline interface? If yes, explain the migration path. If fully backward-compatible, write "No breaking changes". Delete this section for internal-only changes. -->

package/teams/fhr-ai-team/github/PULL_REQUEST_TEMPLATE/light.md

@@ -0,0 +1,7 @@
+## What changed
+
+<!-- One or two sentences: what changed and why. -->
+
+## Notes for reviewer
+
+<!-- Optional: anything non-obvious about the change, or "None". -->

package/teams/fhr-ai-team/github/copilot-instructions.md

@@ -0,0 +1,24 @@
+# Custom instructions for GitHub Copilot
+
+When performing a code review, please ensure the following:
+
+## Crownpeak AI Team Conventions
+- Search the codebase for existing utilities before creating new ones.
+- Check shared libraries: earlybirds_commons, torch_toolbox, item-toolbox, nlp-toolbox.
+- Use "item" not "product", "encodings" not "embeddings".
+- JSON/YAML config keys: camelCase.
+- Parquet columns: camelCase.
+- GCS paths: kebab-case.
+- Strategy IDs: kebab-case.
+- Docker images: kebab-case.
+- Parquet column labels: class-level attributes (_label pattern), not module-level constants.
+- Config classes: use standard suffixes (*Config, *ModelConfig, *BatchConfig, etc.).
+- No placeholders, no "TBD", no vague error handling.
+
+## Commit Messages - Use the following guidelines
+- Use the imperative mood in the subject line (e.g., "Fix bug" instead of "Fixed bug").
+- Start with a capital letter.
+- Do not end the subject line with a period.
+- Use the body to explain what and why vs. how.
+- Use bullet points for multiple changes if necessary.
+- Keep the subject line under 50 characters.

package/teams/fhr-ai-team/github/instructions/python.instructions.md

@@ -0,0 +1,23 @@
+---
+applyTo: "**/*.py"
+---
+
+# Python Coding Style
+
+- Use PEP 8 style guide for Python code.
+- Don't write docstrings for all public modules, classes, functions, and methods.
+- Use meaningful variable and function names.
+- Use snake_case for variable and function names.
+- Use CamelCase for class names.
+- Use type annotations for function parameters and return types.
+- Add '_opt' at the end of the function name for optional parameters and at the end of variable name for optional variables.
+- Use double quotes for string literals. Use single quotes for string literals only when the string contains double quotes.
+- Use triple quotes for multi-line strings. Use implicit string concatenation inside parentheses when joining shorter fragments across lines.
+- Use f-strings for string formatting. Avoid using the format() method or % operator for string formatting.
+- Use list comprehensions and generator expressions for creating lists and iterators. Avoid using map() and filter() functions.
+- Use `with open(...) as file_obj:` for file I/O operations. Avoid manual `close()` calls when a context manager can manage the file handle.
+- Use context managers for resource management when available. Avoid using `try/finally` for resource cleanup when a context manager can express the same behavior more clearly.
+- Use exceptions for error handling. Avoid using return codes for error handling.
+- Use pytest for functional testing. Avoid using other testing frameworks unless necessary.
+- If a dict key is used in several places, use a variable for the key name. Use a constant for the key name if it is used in several modules. The variable name should be in snake_case and start with an underscore.
+- Use single responsibility principle for SOLID code.

package/teams/fhr-ai-team/github/pull_request_template.md

@@ -0,0 +1,21 @@
+<!-- 
+  Pick a template:
+  - Small change (bug fix, config, dependency bump, typo): use light template
+    -> append ?template=light.md to the PR creation URL
+  - Feature, refactor, or architectural change: use full template
+    -> append ?template=full.md to the PR creation URL
+  
+  Or fill in the default below.
+-->
+
+## Why
+
+<!-- What problem does this solve? Link the ticket (XO-XXXX / EB-XXXX) if there is one. -->
+
+## What
+
+<!-- Describe the approach. For non-trivial changes, explain the design and key decisions. -->
+
+## Tests
+
+<!-- How was this tested? List test commands, key scenarios covered, or link CI results. -->

package/teams/fhr-ai-team/prompts/brainstorm.md

@@ -0,0 +1,7 @@
+---
+description: Brainstorm a new feature or design with codebase context. Discovers AI team repos, searches existing code, gathers requirements interactively.
+---
+
+Invoke the ai.pierre:brainstorming skill.
+
+$ARGUMENTS

package/teams/fhr-ai-team/prompts/plan-algo-tests.md

@@ -0,0 +1,7 @@
+---
+description: Plan and configure a test for an algo pipeline. Interactive 3-stage flow to select pipeline, gather config, and generate Kubeflow JSON.
+---
+
+Invoke the ai.pierre:algo-test-planning skill.
+
+$ARGUMENTS

package/teams/fhr-ai-team/prompts/plan.md

@@ -0,0 +1,7 @@
+---
+description: Plan an implementation with mandatory codebase search and code reuse. Produces TDD-based bite-sized tasks with exact file paths.
+---
+
+Invoke the ai.pierre:planning skill.
+
+Implement $ARGUMENTS. IMPORTANT: First search the codebase for existing utilities, scripts, and patterns that do similar things. Reuse them. Do not create new abstractions without showing me what already exists.

package/teams/fhr-ai-team/prompts/pr-description.md

@@ -0,0 +1,7 @@
+---
+description: Generating a PR description from the current branch diff
+---
+
+Invoke the ai.pierre:pr-description skill.
+
+Generate a PR description for the current branch. $ARGUMENTS

package/teams/fhr-ai-team/prompts/test.md

@@ -0,0 +1,7 @@
+---
+description: Run tests - local pytest, Kubeflow pipeline e2e, or MLflow model validation. Uses ml-tooling-dev for pipeline operations.
+---
+
+Invoke the ai.pierre:e2e-testing skill.
+
+$ARGUMENTS

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

@@ -0,0 +1,55 @@
+# ai.pierre - Agent Instructions
+
+This file provides instructions for AI coding agents (OpenCode, Copilot, and others) working with Crownpeak AI team repositories.
+
+## Skills Available
+
+The `skills/` directory contains the following skills. Detect which skill applies based on the user's request and invoke it automatically.
+
+### Workflow Skills
+
+| Skill | Directory | Trigger |
+|-------|-----------|---------|
+| Brainstorming | `skills/brainstorming/` | User wants to design, explore, or brainstorm a feature |
+| Planning | `skills/planning/` | User wants to plan an implementation or break down tasks |
+| Algo Test Planning | `skills/algo-test-planning/` | User wants to test a Kubeflow pipeline |
+| E2E Testing | `skills/e2e-testing/` | User wants to run tests (local, pipeline, or model validation) |
+| Grill Me | `skills/grill-me/` | User wants to stress-test a plan or design through rigorous questioning |
+
+### Domain Skills
+
+| Skill | Directory | Trigger |
+|-------|-----------|---------|
+| ML Tooling Dev | `skills/ml-tooling-dev/` | User works with Kubeflow, MLflow, or MongoDB |
+| Naming Conventions | `skills/naming-conventions-reviewer/` | User writes or reviews code in any ML repo |
+
+## Automatic Skill Selection
+
+The user does **not** need to explicitly request skills. Determine the applicable skill from the user's natural language request:
+
+- "Design a feature" / "How should we approach..." -> brainstorming
+- "Break this down" / "Plan the implementation" -> planning
+- "Test the pipeline" / "Run a test for..." -> algo-test-planning or e2e-testing
+- "Check the Kubeflow run" / "Debug this job" -> ml-tooling-dev
+- "Grill me" / "Stress-test this plan" / "Challenge my design" -> grill-me
+- "Review this code" / "Is this name right?" -> naming-conventions-reviewer
+
+## Team Context
+
+### Repository Naming
+- `algo.*` - ML algorithm projects (training, inference, evaluation)
+- `algo.*-ml` - ML model training/fine-tuning (run on Kubeflow)
+- `ai.*` - AI-powered microservices (FastAPI, Streamlit)
+- `*-toolbox` - Shared Python libraries
+- `attraqt-kubeflow-*` - Kubeflow pipeline configs and definitions
+- `ebap-*` - Early Birds AI Platform infrastructure
+
+### Shared Libraries
+Before writing new utilities, check:
+- `earlybirds_commons`, `torch_toolbox`, `item-toolbox`, `nlp-toolbox`, `eb_tensorflow`
+
+### Core Rules
+1. Search the codebase for existing implementations before proposing new code
+2. Reuse shared library utilities; do not duplicate
+3. Follow naming conventions (see `skills/naming-conventions-reviewer/`)
+4. No placeholders, no "TBD", no vague instructions in plans or designs

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

@@ -0,0 +1,52 @@
+# ai.pierre - Crownpeak AI Team Engineering Skills
+
+This plugin provides engineering skills and slash commands for the Crownpeak AI team's ML development workflow.
+
+## Available Commands
+
+| Command | When to use |
+|---------|-------------|
+| `/brainstorm` | Designing a new feature, exploring architecture decisions, or evaluating approaches |
+| `/pr-description` | Generating a PR description from the current branch diff |
+| `/plan` | Breaking down an approved design into implementation tasks |
+| `/plan-algo-tests` | Configuring and planning a Kubeflow pipeline test run |
+| `/test` | Running local tests, launching pipeline e2e tests, or validating model outputs |
+
+## Auto-Routing Rules
+
+When working in any Crownpeak AI repo, apply these skills automatically:
+
+- **Writing or reviewing code** in any repo -> invoke `ai.pierre:naming-conventions-reviewer` to validate names
+- **Working with Kubeflow, MLflow, or MongoDB** -> invoke `ai.pierre:ml-tooling-dev` for operations and debugging
+- **Brainstorming or designing** -> invoke `ai.pierre:brainstorming` for codebase-aware design
+- **Planning implementation** -> invoke `ai.pierre:planning` for task breakdown
+- **Testing pipelines** -> invoke `ai.pierre:algo-test-planning` for config generation, `ai.pierre:e2e-testing` for execution
+- **Stress-testing a plan or design** -> invoke `ai.pierre:grill-me` to interrogate decisions branch by branch
+- **Creating a PR or asked to write a PR description** -> invoke `ai.pierre:pr-description` to generate from the diff
+
+## Team Repo Structure
+
+| Pattern | Purpose | Examples |
+|---------|---------|---------|
+| `algo.*` | ML algorithm projects | `algo.search`, `algo.clip`, `algo.tagging` |
+| `algo.*-ml` | ML training (Kubeflow) | `algo.search-ml`, `algo.clip-ml` |
+| `ai.*` | AI microservices | `ai.tagging-service`, `ai.guardrails-service` |
+| `*-toolbox` | Shared Python libraries | `pytorch-toolbox`, `nlp-toolbox`, `item-toolbox` |
+| `attraqt-kubeflow-*` | Kubeflow infra | `attraqt-kubeflow-configs`, `attraqt-kubeflow-pipelines` |
+| `ebap-*` | AI Platform infra | `ebap-argo-app`, `ebap-schema` |
+
+## Shared Libraries
+
+Always check these before writing new utilities:
+- `earlybirds_commons` - shared utilities and configurations
+- `torch_toolbox` - PyTorch model training/inference
+- `item-toolbox` - e-commerce item data utilities
+- `nlp-toolbox` - text tokenization and NLP
+- `eb_tensorflow` - TensorFlow model utilities
+
+## Non-Negotiable Principles
+
+1. **Search before creating.** Always search the codebase for existing implementations before proposing new code.
+2. **Reuse before writing.** If a utility exists in a shared library, use it.
+3. **Name correctly.** All names must follow the conventions enforced by `naming-conventions-reviewer`.
+4. **No placeholders.** Every plan, design, and implementation must be complete and precise.

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

@@ -0,0 +1,51 @@
+# ai.agent-skills
+
+Engineering skills for Crownpeak AI team coding agents. Plugin name: **ai.pierre**.
+
+Provides codebase-aware brainstorming, implementation planning with mandatory code reuse, interactive Kubeflow pipeline test configuration, and cross-repo naming convention enforcement.
+
+**New to Claude Code?** Start with the [onboarding guide](docs/onboarding.md) after installing.
+
+## Quick Install
+
+| Tool | Command |
+|------|---------|
+| **Claude Code** | `/plugin install ai.pierre` ([setup guide](docs/claude-code-setup.md)) |
+| **OpenCode** | Clone repo, open in OpenCode ([setup guide](docs/opencode-setup.md)) |
+| **GitHub Copilot** | Copy skills to `.github/skills/` ([setup guide](docs/copilot-setup.md)) |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/brainstorm` | Codebase-aware brainstorming with dynamic AI team repo discovery via `gh` |
+| `/plan` | Implementation planning with mandatory codebase search and code reuse |
+| `/plan-algo-tests` | Interactive 3-stage flow: pipeline selection, config gathering, Kubeflow JSON generation |
+| `/test` | Local pytest, Kubeflow pipeline e2e testing, or MLflow model validation |
+
+## Skills
+
+| Skill | Description |
+|-------|-------------|
+| `brainstorming` | Design exploration with repo discovery, codebase search, interactive requirements gathering |
+| `planning` | TDD-based task breakdown with cross-repo dependency mapping |
+| `algo-test-planning` | Pipeline test config generation with 3-stage interactive flow |
+| `e2e-testing` | Local, pipeline, and model validation testing workflows |
+| `ml-tooling-dev` | Kubeflow, MLflow, and MongoDB dev environment management |
+| `grill-me` | Stress-test a plan or design through relentless questioning, resolving each branch of the decision tree |
+| `naming-conventions-reviewer` | Cross-repo naming convention enforcement for ML repositories |
+
+## Copilot Instructions
+
+A reference [`copilot-instructions.md`](.github/copilot-instructions.md) is included for GitHub Copilot code reviews. It covers Python coding style, Crownpeak AI team naming conventions, and commit message standards. Copy it into your project's `.github/` directory to enable Copilot-assisted reviews. See the [Copilot setup guide](docs/copilot-setup.md) for details.
+
+## Repository Structure
+
+```
+.claude/commands/    Slash commands (thin wrappers invoking skills)
+.github/             Reference copilot-instructions.md for code reviews
+skills/              Skill definitions with SKILL.md, references/, and scripts/
+docs/                Setup guides for Claude Code, OpenCode, and Copilot
+CLAUDE.md            Agent instructions for Claude Code
+AGENTS.md            Agent instructions for OpenCode and Copilot
+```

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.