@groupby/ai-dev 0.5.7 → 0.5.8

package/package.json

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

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.

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 |