FEC-332: Add AI tooling configuration and agent skills

.agents/skills/pr-review-navigator/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: pr-review-navigator
+description: Generate AI-assisted navigation aids to help humans start reviewing a pull request more efficiently.
+disable-model-invocation: false
+argument-hint: '[pr-number] [--comment]'
+allowed-tools: Bash, Grep, Glob, Read
+---
+
+# PR Review Navigator
+
+Generate navigation aids to help humans review pull requests more efficiently. Provides orientation and structure, not pre-review or judgment.
+
+**Important constraints:**
+- No interpretation of business intent or purpose, only factual descriptions of what changed
+
+## Arguments
+
+- `pr-number` (required): The PR number to review
+- `--comment` (optional): Post the navigator output as a PR comment. If omitted, write to a local markdown file.
+
+## Process
+
+### 1. Fetch PR Information
+
+```bash
+gh pr view $ARGUMENTS --json title,body,files,additions,deletions,url
+```
+
+Extract: changed files, additions/deletions count, PR URL for link construction.
+
+For commits/branches without a PR, use `git show --name-status` and `git diff`.
+
+### 2. Fetch the Diff
+
+```bash
+gh pr diff <pr-number>
+```
+
+Understand file contents and relationships from the diff.
+
+### 3. Analyze Dependencies
+
+Read imports/references in the diff to determine which files depend on which.
+
+### 4. Determine Review Order
+
+Based on dependency flow, use outside-in ordering:
+
+1. API endpoints, HTTP routes, GraphQL resolvers
+2. Service/business logic layer
+3. Repository/persistence layer
+4. Data models/entities
+5. Wiring/configuration
+6. Unit tests (after the implementation files they test)
+7. Cornichon/integration tests last (they test the full stack from outside)
+
+### 5. Generate Mermaid Diagram
+
+Create a `flowchart TB` showing:
+- All changed files as nodes with circled numbers: ①, ②, ③, etc.
+- Dependency relationships (arrows showing "depends on" or "uses")
+- Test files connected to implementation files they test
+- Subgraphs grouped by architectural layer
+- Color coding: unit tests green (`fill:#e8f5e9`), integration tests blue (`fill:#e3f2fd`, dashed border)
+
+Node format: `["① filename.ext<br/><i>one-liner</i>"]`
+
+**Cornichon test styling:**
+```mermaid
+subgraph "🧪 Integration Tests (Cornichon)"
+    style IntegrationTests fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,stroke-dasharray: 5 5
+    ...
+end
+```
+
+### 6. Create Review Table
+
+A numbered table with columns:
+- `#` - Review order number
+- `File` - Filename (short, without full path)
+- `What it does` - One factual sentence about what the file contains/does
+- `Link` - Anchor link to the file in the PR
+
+### 7. Construct File Links
+
+GitHub uses SHA256 hashes of file paths for PR file anchors:
+
+```bash
+hash=$(echo -n "<filepath>" | shasum -a 256 | cut -d' ' -f1)
+# Link: https://github.com/{owner}/{repo}/pull/{number}/files#diff-{hash}
+```
+
+Use the file path exactly as returned by `gh pr view --json files`. Compute the hash for each file.
+
+For commits/branches without a PR, omit the Link column.
+
+### 8. Output the Result
+
+If `--comment` flag is provided, post as a PR comment:
+
+```bash
+gh pr comment <pr-number> --body "<content>"
+```
+
+If `--comment` is NOT provided, write to `pr-review-navigator.md` in the workspace root and inform the user of the file path.
+
+## Output Format
+
+The output (whether file or comment) should be valid markdown structured as:
+
+```markdown
+## AI Review Navigator
+
+**Summary:** <one factual sentence about what was added/changed/removed>
+
+---
+
+### File Relationships & Review Order
+
+\`\`\`mermaid
+flowchart TB
+    subgraph "1️⃣ API Layer"
+        A["① FeatureXController.scala<br/><i>HTTP endpoints</i>"]
+    end
+
+    subgraph "2️⃣ Service Layer"
+        B["② FeatureXService.scala<br/><i>Business logic</i>"]
+    end
+
+    subgraph "3️⃣ Unit Tests"
+        C["③ FeatureXServiceSpec.scala"]
+    end
+
+    subgraph IntegrationTests ["🧪 Integration Tests (Cornichon)"]
+        D["④ FeatureXFeature.scala"]
+    end
+
+    A --> B
+    B -.->|tested by| C
+    A -.->|tested by| D
+
+    style C fill:#e8f5e9
+    style IntegrationTests fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,stroke-dasharray: 5 5
+\`\`\`
+
+---
+
+### Suggested Review Order
+
+| # | File | What it does | Link |
+|---|------|--------------|------|
+| 1 | `FeatureXController.scala` | HTTP endpoints for FeatureX | [View](link) |
+| 2 | `FeatureXService.scala` | Business logic | [View](link) |
+| 3 | `FeatureXServiceSpec.scala` | Unit tests for service layer | [View](link) |
+| 4 | `FeatureXFeature.scala` | Cornichon integration tests | [View](link) |
+```
+
+**Summary rules:**
+- State only facts about what changed
+- Do NOT interpret purpose, intent, or business value
+- Do NOT use phrases like "optimized for", "designed to", "intended for"
+
+## Guidelines
+
+- This skill assists with review orientation only. The human reviewer makes all judgments about code quality, correctness, and approval.
+- If the PR is too large (>30 files), suggest reviewing in logical chunks.
+- Wrap the mermaid diagram in triple backticks with `mermaid` language identifier so GitHub renders it as a diagram.

.agents/skills/remember/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: remember
+description: Persist guidelines, conventions, and architectural decisions into the repository's knowledge base. Use when told to remember something for future sessions.
+disable-model-invocation: false
+argument-hint: <guideline, convention, or architectural decision to persist>
+allowed-tools: Bash, Grep, Glob, Read, Edit, Write
+---
+
+# Remember
+
+Persist new guidelines, best practices, or architectural decisions into the
+repository's knowledge base so they are available in future AI sessions.
+
+## Arguments
+
+- `thing to remember` (required): A guideline, convention, or decision to
+  persist. Natural language input describing what should be remembered.
+
+## Usage Examples
+
+- `/remember always use the --frozen-lockfile flag in CI`
+- `/remember the auth module was refactored to use middleware in PR #342`
+- `/remember integration tests must hit a real database, never use mocks`
+
+## Process
+
+### 1. Intent Distillation
+
+- Identify the core principle, rule, or technical intent from the user's input
+- Rephrase concisely using precise software development terminology
+
+### 2. Identify Target File
+
+Determine which file should contain this knowledge. Repositories follow a
+layered structure, preferring tool-agnostic paths when they exist:
+
+| Intent type | Preferred target | Fallback |
+|---|---|---|
+| Project-wide convention or standard | `AGENTS.md` | `CLAUDE.md` |
+| Domain-specific best practice (testing, components, API design, etc.) | `rules/` or `docs/conventions/` | See resolution rules |
+| Change to an automated workflow or skill | `.agents/skills/` | `.claude/skills/` |
+| Agent behavior guideline | `.agents/agents/` | `.claude/agents/` |
+| Claude-specific configuration (MCP, hooks, permissions) | `CLAUDE.md` | — |
+
+**Resolution rules:**
+
+1. Check whether `rules/` or `docs/conventions/` exists
+2. If both exist, prefer `rules/`
+3. If only one exists, write there
+4. If only `docs/conventions/` exists, ask the user whether they want to
+   create a symlink from `rules/` to `docs/conventions/` so both paths
+   resolve to the same location. If they confirm, create the symlink before
+   writing.
+5. If neither exists, create `rules/` and write there
+6. For other target types:
+   - For `.agents/skills/` or `.agents/agents/`: Use the `.claude/` equivalent
+     if the `.agents/` directory does not exist
+   - For `AGENTS.md`: Use `CLAUDE.md` if `AGENTS.md` does not exist
+7. Only write to `CLAUDE.md` or `.claude/` directly when the information is
+   Claude-specific or no tool-agnostic target exists
+
+### 3. Conflict Analysis
+
+- Thoroughly scan the identified file(s) for any existing content that
+  contradicts the new intent
+- Additionally, scan the corresponding file in the other layer (e.g., if writing
+  to `AGENTS.md`, also scan `CLAUDE.md` and vice versa). If the other layer
+  contains conflicting or duplicated content, resolve it by replacing that
+  content in `CLAUDE.md` with a reference to `AGENTS.md` (e.g.,
+  "See `AGENTS.md` for project conventions.")
+- A contradiction is any statement that would be invalidated or made obsolete by
+  the new guideline
+
+**If a conflict is found:**
+
+- Halt execution immediately
+- Quote the exact conflicting statement(s) from the document
+- Inform the user about the contradiction and ask for clarification on how to
+  proceed
+- Do NOT proceed with any updates until the conflict is resolved
+
+**If no conflicts are found:**
+
+- Identify the most logical section within the file to add the new information
+- If no suitable section exists, create a new one with an appropriate heading
+- Refactor existing content as needed to keep the document coherent and
+  well-structured
+
+### 4. Write the Update
+
+When writing the update:
+
+- Only include production-ready patterns and examples that can be safely copied.
+  Use precise, declarative language. Do not include anti-patterns or cautionary
+  examples.
+
+### 5. Skill Discovery and Synchronization
+
+After successfully updating documentation, discover which skills may need
+updates by scanning skill files in `.agents/skills/*/SKILL.md` and
+`.claude/skills/*/SKILL.md` (whichever exist). When reading skill files, resolve
+symlinks to access the actual content rather than treating symlinks as empty or
+opaque files.
+
+**Discovery criteria** — a skill is affected if it contains:
+
+- Explicit references to the updated documentation file
+- Content that covers the same topic or concept as the update
+- Inline templates, code examples, or patterns related to the updated guideline
+- Instructions or rules that may now be outdated or contradicted by the new
+  documentation
+
+**If no skills are affected, skip this step.**
+
+**For each affected skill, determine whether it is local or shared:**
+
+A skill is **shared** if it is a symlink pointing outside the current repo or
+was installed by a package manager and has not been modified locally. A skill is
+**local** if it was authored or edited in this repo. Symlinks between
+`.claude/skills/` and `.agents/skills/` within the same repo are internal
+bridges and do not affect this determination.
+
+**Local skills** — edit directly:
+
+- Update the skill's templates, examples, and instructions to align with the
+  new documentation
+
+**Shared skills** — report and offer to update:
+
+- Report the affected shared skill and the specific inconsistency to the user
+- Ask: "Shared skill `<skill-name>` is affected. Add repo-specific additions?"
+- If the user confirms:
+
+  1. Resolve the original shared skill path (the symlink target or CLI cache
+     location where the shared skill was installed)
+
+  2. Determine which layer to use:
+
+     **If `.agents/skills/` directory exists:**
+
+     Create or update `.agents/skills/<skill-name>/SKILL.md` with repo-specific
+     additions listed **before** the shared skill reference, so local rules take
+     priority:
+
+     ```markdown
+     ---
+     name: <skill-name>
+     description: <same description as the shared skill>
+     allowed-tools: <same allowed-tools as the shared skill>
+     ---
+
+     ## Repo-specific additions
+
+     - <the new convention or guideline>
+
+     ## Shared skill
+
+     Read and follow the shared skill at `<original-shared-skill-path>`.
+     ```
+
+     Then ensure `.claude/skills/<skill-name>/SKILL.md` is a symlink to
+     `.agents/skills/<skill-name>/SKILL.md`:
+
+     - If it is already a symlink to the correct path, no action needed
+     - If it exists as a regular file, delete it and create the symlink
+     - If it does not exist, create the symlink
+
+     **If `.agents/skills/` directory does not exist:**
+
+     Create or update `.claude/skills/<skill-name>/SKILL.md` directly with the
+     same structure (repo-specific additions before the shared skill reference).
+
+- If the user declines, log the inconsistency in the final confirmation but
+  take no action
+
+### 6. Final Confirmation
+
+Report all changes made:
+
+- Documentation file(s) updated
+- Skill file(s) updated (if any), with rationale explaining why each skill was
+  identified as affected
+- Summary of what was added or modified in each file
+
+## Guidelines
+
+- Always read target files before modifying them
+- Prefer adding to an existing section over creating a new one
+- Keep entries concise; one to two sentences per guideline is ideal
+- If the user's input is ambiguous, ask for clarification before writing
+- Do not duplicate information that already exists in the target file
+- When creating skill files, create the `<skill-name>/` subdirectory if needed
+  but do NOT create `.agents/` or `.agents/skills/` directories — only use them
+  if they already exist