Skip to content

Commit 898ef88

Browse files
misama-ctmisama-ct
committed
chore: add AI agent configuration and shared skills
Install agent skills and configuration files for Claude Code, Continue, and Goose across the monorepo. Adds AGENTS.md and CLAUDE.md to each package/template, configures MCP servers, and sets up shared skills (repo-healthcheck, renovate-review, security-auditor, etc.).
1 parent af5b3c5 commit 898ef88

File tree

106 files changed

+3030
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

106 files changed

+3030
-0
lines changed

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

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
---
2+
name: pr-review-navigator
3+
description: Generate AI-assisted navigation aids to help humans start reviewing a pull request more efficiently.
4+
disable-model-invocation: false
5+
argument-hint: '[pr-number] [--comment]'
6+
allowed-tools: Bash, Grep, Glob, Read
7+
---
8+
9+
# PR Review Navigator
10+
11+
Generate navigation aids to help humans review pull requests more efficiently. Provides orientation and structure, not pre-review or judgment.
12+
13+
**Important constraints:**
14+
15+
- No interpretation of business intent or purpose, only factual descriptions of what changed
16+
17+
## Arguments
18+
19+
- `pr-number` (required): The PR number to review
20+
- `--comment` (optional): Post the navigator output as a PR comment. If omitted, write to a local markdown file.
21+
22+
## Process
23+
24+
### 1. Fetch PR Information
25+
26+
```bash
27+
gh pr view $ARGUMENTS --json title,body,files,additions,deletions,url
28+
```
29+
30+
Extract: changed files, additions/deletions count, PR URL for link construction.
31+
32+
For commits/branches without a PR, use `git show --name-status` and `git diff`.
33+
34+
### 2. Fetch the Diff
35+
36+
```bash
37+
gh pr diff <pr-number>
38+
```
39+
40+
Understand file contents and relationships from the diff.
41+
42+
### 3. Analyze Dependencies
43+
44+
Read imports/references in the diff to determine which files depend on which.
45+
46+
### 4. Determine Review Order
47+
48+
Based on dependency flow, use outside-in ordering:
49+
50+
1. API endpoints, HTTP routes, GraphQL resolvers
51+
2. Service/business logic layer
52+
3. Repository/persistence layer
53+
4. Data models/entities
54+
5. Wiring/configuration
55+
6. Unit tests (after the implementation files they test)
56+
7. Cornichon/integration tests last (they test the full stack from outside)
57+
58+
### 5. Generate Mermaid Diagram
59+
60+
Create a `flowchart TB` showing:
61+
62+
- All changed files as nodes with circled numbers: ①, ②, ③, etc.
63+
- Dependency relationships (arrows showing "depends on" or "uses")
64+
- Test files connected to implementation files they test
65+
- Subgraphs grouped by architectural layer
66+
- Color coding: unit tests green (`fill:#e8f5e9`), integration tests blue (`fill:#e3f2fd`, dashed border)
67+
68+
Node format: `["① filename.ext<br/><i>one-liner</i>"]`
69+
70+
**Cornichon test styling:**
71+
72+
```mermaid
73+
subgraph "🧪 Integration Tests (Cornichon)"
74+
style IntegrationTests fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,stroke-dasharray: 5 5
75+
...
76+
end
77+
```
78+
79+
### 6. Create Review Table
80+
81+
A numbered table with columns:
82+
83+
- `#` - Review order number
84+
- `File` - Filename (short, without full path)
85+
- `What it does` - One factual sentence about what the file contains/does
86+
- `Link` - Anchor link to the file in the PR
87+
88+
### 7. Construct File Links
89+
90+
GitHub uses SHA256 hashes of file paths for PR file anchors:
91+
92+
```bash
93+
hash=$(echo -n "<filepath>" | shasum -a 256 | cut -d' ' -f1)
94+
# Link: https://github.com/{owner}/{repo}/pull/{number}/files#diff-{hash}
95+
```
96+
97+
Use the file path exactly as returned by `gh pr view --json files`. Compute the hash for each file.
98+
99+
For commits/branches without a PR, omit the Link column.
100+
101+
### 8. Output the Result
102+
103+
If `--comment` flag is provided, post as a PR comment:
104+
105+
```bash
106+
gh pr comment <pr-number> --body "<content>"
107+
```
108+
109+
If `--comment` is NOT provided, write to `pr-review-navigator.md` in the workspace root and inform the user of the file path.
110+
111+
## Output Format
112+
113+
The output (whether file or comment) should be valid markdown structured as:
114+
115+
```markdown
116+
## AI Review Navigator
117+
118+
**Summary:** <one factual sentence about what was added/changed/removed>
119+
120+
---
121+
122+
### File Relationships & Review Order
123+
124+
\`\`\`mermaid
125+
flowchart TB
126+
subgraph "1️⃣ API Layer"
127+
A["① FeatureXController.scala<br/><i>HTTP endpoints</i>"]
128+
end
129+
130+
subgraph "2️⃣ Service Layer"
131+
B["② FeatureXService.scala<br/><i>Business logic</i>"]
132+
end
133+
134+
subgraph "3️⃣ Unit Tests"
135+
C["③ FeatureXServiceSpec.scala"]
136+
end
137+
138+
subgraph IntegrationTests ["🧪 Integration Tests (Cornichon)"]
139+
D["④ FeatureXFeature.scala"]
140+
end
141+
142+
A --> B
143+
B -.->|tested by| C
144+
A -.->|tested by| D
145+
146+
style C fill:#e8f5e9
147+
style IntegrationTests fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,stroke-dasharray: 5 5
148+
149+
\`\`\`
150+
151+
---
152+
153+
### Suggested Review Order
154+
155+
| # | File | What it does | Link |
156+
| --- | --------------------------- | ---------------------------- | ------------ |
157+
| 1 | `FeatureXController.scala` | HTTP endpoints for FeatureX | [View](link) |
158+
| 2 | `FeatureXService.scala` | Business logic | [View](link) |
159+
| 3 | `FeatureXServiceSpec.scala` | Unit tests for service layer | [View](link) |
160+
| 4 | `FeatureXFeature.scala` | Cornichon integration tests | [View](link) |
161+
```
162+
163+
**Summary rules:**
164+
165+
- State only facts about what changed
166+
- Do NOT interpret purpose, intent, or business value
167+
- Do NOT use phrases like "optimized for", "designed to", "intended for"
168+
169+
## Guidelines
170+
171+
- This skill assists with review orientation only. The human reviewer makes all judgments about code quality, correctness, and approval.
172+
- If the PR is too large (>30 files), suggest reviewing in logical chunks.
173+
- Wrap the mermaid diagram in triple backticks with `mermaid` language identifier so GitHub renders it as a diagram.

‎.agents/skills/remember/SKILL.md‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
---
2+
name: remember
3+
description: Persist guidelines, conventions, and architectural decisions into the repository's knowledge base. Use when told to remember something for future sessions.
4+
disable-model-invocation: false
5+
argument-hint: <guideline, convention, or architectural decision to persist>
6+
allowed-tools: Bash, Grep, Glob, Read, Edit, Write
7+
---
8+
9+
# Remember
10+
11+
Persist new guidelines, best practices, or architectural decisions into the
12+
repository's knowledge base so they are available in future AI sessions.
13+
14+
## Arguments
15+
16+
- `thing to remember` (required): A guideline, convention, or decision to
17+
persist. Natural language input describing what should be remembered.
18+
19+
## Usage Examples
20+
21+
- `/remember always use the --frozen-lockfile flag in CI`
22+
- `/remember the auth module was refactored to use middleware in PR #342`
23+
- `/remember integration tests must hit a real database, never use mocks`
24+
25+
## Process
26+
27+
### 1. Intent Distillation
28+
29+
- Identify the core principle, rule, or technical intent from the user's input
30+
- Rephrase concisely using precise software development terminology
31+
32+
### 2. Identify Target File
33+
34+
Determine which file should contain this knowledge. Repositories follow a
35+
layered structure, preferring tool-agnostic paths when they exist:
36+
37+
| Intent type | Preferred target | Fallback |
38+
| --------------------------------------------------------------------- | ------------------------------- | -------------------- |
39+
| Project-wide convention or standard | `AGENTS.md` | `CLAUDE.md` |
40+
| Domain-specific best practice (testing, components, API design, etc.) | `rules/` or `docs/conventions/` | See resolution rules |
41+
| Change to an automated workflow or skill | `.agents/skills/` | `.claude/skills/` |
42+
| Agent behavior guideline | `.agents/agents/` | `.claude/agents/` |
43+
| Claude-specific configuration (MCP, hooks, permissions) | `CLAUDE.md` | — |
44+
45+
**Resolution rules:**
46+
47+
1. Check whether `rules/` or `docs/conventions/` exists
48+
2. If both exist, prefer `rules/`
49+
3. If only one exists, write there
50+
4. If only `docs/conventions/` exists, ask the user whether they want to
51+
create a symlink from `rules/` to `docs/conventions/` so both paths
52+
resolve to the same location. If they confirm, create the symlink before
53+
writing.
54+
5. If neither exists, create `rules/` and write there
55+
6. For other target types:
56+
- For `.agents/skills/` or `.agents/agents/`: Use the `.claude/` equivalent
57+
if the `.agents/` directory does not exist
58+
- For `AGENTS.md`: Use `CLAUDE.md` if `AGENTS.md` does not exist
59+
7. Only write to `CLAUDE.md` or `.claude/` directly when the information is
60+
Claude-specific or no tool-agnostic target exists
61+
62+
### 3. Conflict Analysis
63+
64+
- Thoroughly scan the identified file(s) for any existing content that
65+
contradicts the new intent
66+
- Additionally, scan the corresponding file in the other layer (e.g., if writing
67+
to `AGENTS.md`, also scan `CLAUDE.md` and vice versa). If the other layer
68+
contains conflicting or duplicated content, resolve it by replacing that
69+
content in `CLAUDE.md` with a reference to `AGENTS.md` (e.g.,
70+
"See `AGENTS.md` for project conventions.")
71+
- A contradiction is any statement that would be invalidated or made obsolete by
72+
the new guideline
73+
74+
**If a conflict is found:**
75+
76+
- Halt execution immediately
77+
- Quote the exact conflicting statement(s) from the document
78+
- Inform the user about the contradiction and ask for clarification on how to
79+
proceed
80+
- Do NOT proceed with any updates until the conflict is resolved
81+
82+
**If no conflicts are found:**
83+
84+
- Identify the most logical section within the file to add the new information
85+
- If no suitable section exists, create a new one with an appropriate heading
86+
- Refactor existing content as needed to keep the document coherent and
87+
well-structured
88+
89+
### 4. Write the Update
90+
91+
When writing the update:
92+
93+
- Only include production-ready patterns and examples that can be safely copied.
94+
Use precise, declarative language. Do not include anti-patterns or cautionary
95+
examples.
96+
97+
### 5. Skill Discovery and Synchronization
98+
99+
After successfully updating documentation, discover which skills may need
100+
updates by scanning skill files in `.agents/skills/*/SKILL.md` and
101+
`.claude/skills/*/SKILL.md` (whichever exist). When reading skill files, resolve
102+
symlinks to access the actual content rather than treating symlinks as empty or
103+
opaque files.
104+
105+
**Discovery criteria** — a skill is affected if it contains:
106+
107+
- Explicit references to the updated documentation file
108+
- Content that covers the same topic or concept as the update
109+
- Inline templates, code examples, or patterns related to the updated guideline
110+
- Instructions or rules that may now be outdated or contradicted by the new
111+
documentation
112+
113+
**If no skills are affected, skip this step.**
114+
115+
**For each affected skill, determine whether it is local or shared:**
116+
117+
A skill is **shared** if it is a symlink pointing outside the current repo or
118+
was installed by a package manager and has not been modified locally. A skill is
119+
**local** if it was authored or edited in this repo. Symlinks between
120+
`.claude/skills/` and `.agents/skills/` within the same repo are internal
121+
bridges and do not affect this determination.
122+
123+
**Local skills** — edit directly:
124+
125+
- Update the skill's templates, examples, and instructions to align with the
126+
new documentation
127+
128+
**Shared skills** — report and offer to update:
129+
130+
- Report the affected shared skill and the specific inconsistency to the user
131+
- Ask: "Shared skill `<skill-name>` is affected. Add repo-specific additions?"
132+
- If the user confirms:
133+
134+
1. Resolve the original shared skill path (the symlink target or CLI cache
135+
location where the shared skill was installed)
136+
137+
2. Determine which layer to use:
138+
139+
**If `.agents/skills/` directory exists:**
140+
141+
Create or update `.agents/skills/<skill-name>/SKILL.md` with repo-specific
142+
additions listed **before** the shared skill reference, so local rules take
143+
priority:
144+
145+
```markdown
146+
---
147+
name: <skill-name>
148+
description: <same description as the shared skill>
149+
allowed-tools: <same allowed-tools as the shared skill>
150+
---
151+
152+
## Repo-specific additions
153+
154+
- <the new convention or guideline>
155+
156+
## Shared skill
157+
158+
Read and follow the shared skill at `<original-shared-skill-path>`.
159+
```
160+
161+
Then ensure `.claude/skills/<skill-name>/SKILL.md` is a symlink to
162+
`.agents/skills/<skill-name>/SKILL.md`:
163+
164+
- If it is already a symlink to the correct path, no action needed
165+
- If it exists as a regular file, delete it and create the symlink
166+
- If it does not exist, create the symlink
167+
168+
**If `.agents/skills/` directory does not exist:**
169+
170+
Create or update `.claude/skills/<skill-name>/SKILL.md` directly with the
171+
same structure (repo-specific additions before the shared skill reference).
172+
173+
- If the user declines, log the inconsistency in the final confirmation but
174+
take no action
175+
176+
### 6. Final Confirmation
177+
178+
Report all changes made:
179+
180+
- Documentation file(s) updated
181+
- Skill file(s) updated (if any), with rationale explaining why each skill was
182+
identified as affected
183+
- Summary of what was added or modified in each file
184+
185+
## Guidelines
186+
187+
- Always read target files before modifying them
188+
- Prefer adding to an existing section over creating a new one
189+
- Keep entries concise; one to two sentences per guideline is ideal
190+
- If the user's input is ambiguous, ask for clarification before writing
191+
- Do not duplicate information that already exists in the target file
192+
- When creating skill files, create the `<skill-name>/` subdirectory if needed
193+
but do NOT create `.agents/` or `.agents/skills/` directories — only use them
194+
if they already exist

0 commit comments

Comments
 (0)