Skip to content

Commit 22e7da3

Browse files
micronaut-buildmicronaut-build
committed
Update common files
1 parent 6b08a9e commit 22e7da3

File tree

15 files changed

+1436
-2
lines changed

15 files changed

+1436
-2
lines changed

‎.agents/skills/agent-md-refactor/SKILL.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
name: agent-md-refactor
3+
description: Refactor oversized agent instruction files into a progressive-disclosure structure. Use when users ask to split AGENTS.md/CLAUDE.md/COPILOT.md, reduce instruction bloat, or organize guidance into linked topic files.
4+
license: Apache-2.0
5+
compatibility: Repositories using markdown instruction files such as AGENTS.md, CLAUDE.md, or COPILOT.md
6+
metadata:
7+
author: Álvaro Sánchez-Mariscal
8+
version: "1.0.0"
9+
---
10+
11+
# Agent MD Refactor
12+
13+
Refactor monolithic instruction files into a compact root file plus linked topic files.
14+
Keep this file focused on execution flow and load detailed templates/examples from references.
15+
16+
## Goal
17+
18+
Deliver a maintainable instruction system with:
19+
20+
- a minimal root instruction file containing only universal guidance,
21+
- linked topic files for detailed rules,
22+
- contradictions resolved and vague/redundant rules removed.
23+
24+
## Trigger Examples
25+
26+
Should trigger:
27+
28+
- "Refactor this AGENTS.md to use progressive disclosure."
29+
- "Split my CLAUDE.md into focused instruction files."
30+
- "My instruction file is too long, reorganize it."
31+
32+
Should not trigger:
33+
34+
- "Explain what AGENTS.md is."
35+
- "Fix one typo in CLAUDE.md."
36+
- "Write a brand-new coding standard from scratch."
37+
38+
More examples: [examples-and-anti-patterns](references/examples-and-anti-patterns.md).
39+
40+
## Procedure
41+
42+
1. Inventory instruction sources (`AGENTS.md`, `CLAUDE.md`, `COPILOT.md`, related guidance docs).
43+
2. Detect contradictions and resolve by repository precedence.
44+
3. Keep only root-level essentials in the root instruction file.
45+
4. Group remaining content into 3-8 linked topic files with clear names.
46+
5. Remove non-actionable, redundant, and outdated directives.
47+
6. Validate links, coverage, and consistency before completion.
48+
49+
Detailed step playbook: [refactor-playbook](references/refactor-playbook.md).
50+
51+
## Inputs
52+
53+
- Root instruction file path(s)
54+
- Existing repository conventions (commands, toolchain, style)
55+
- User constraints (must-keep rules, preferred layout)
56+
57+
## Outputs
58+
59+
- Refactored root instruction file (minimal, universal guidance)
60+
- Topic files with detailed rules
61+
- List of removed/merged rules with rationale
62+
- Notes on contradiction handling
63+
64+
## Edge Cases
65+
66+
- If rule precedence is impossible to infer, request one targeted user decision.
67+
- If multiple files repeat the same rule, keep one canonical source and replace others with links.
68+
- If the instruction file is already concise, avoid unnecessary splitting.
69+
- Use relative markdown links for portability.
70+
71+
## Validation Checklist
72+
73+
- [ ] Frontmatter is valid YAML and `name` matches directory.
74+
- [ ] Description states capability and usage triggers.
75+
- [ ] Root file contains only universal instructions.
76+
- [ ] Topic files are self-contained and linked from root.
77+
- [ ] Contradictions are resolved or explicitly called out.
78+
- [ ] Vague/default/redundant directives are removed or rewritten.
79+
- [ ] Relative links resolve.
80+
81+
## References
82+
83+
- [Refactor playbook](references/refactor-playbook.md)
84+
- [Examples and anti-patterns](references/examples-and-anti-patterns.md)

‎.agents/skills/agent-md-refactor/references/examples-and-anti-patterns.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Examples and Anti-Patterns
2+
3+
Use these examples to guide consistent refactors.
4+
5+
## Root File Pattern
6+
7+
Good root structure:
8+
9+
```markdown
10+
# Project Instructions
11+
12+
One-line project description.
13+
14+
## Commands
15+
- `pnpm build`
16+
- `pnpm test`
17+
- `pnpm typecheck`
18+
19+
## Detailed Guidance
20+
- [Architecture](.agent-instructions/architecture.md)
21+
- [Code Style](.agent-instructions/code-style.md)
22+
- [Testing](.agent-instructions/testing.md)
23+
```
24+
25+
Avoid:
26+
27+
```markdown
28+
# AGENTS.md
29+
30+
## Code Style
31+
... 150 lines ...
32+
33+
## Testing
34+
... 120 lines ...
35+
36+
## TypeScript
37+
... 180 lines ...
38+
```
39+
40+
## Topic File Pattern
41+
42+
Good topic file:
43+
44+
```markdown
45+
# Testing
46+
47+
## Scope
48+
When to use each test type.
49+
50+
## Rules
51+
- Use integration tests for persistence adapters.
52+
- Keep unit tests deterministic.
53+
54+
## Examples
55+
- Good: verifies behavior with stable fixtures.
56+
- Avoid: brittle tests tied to timestamps.
57+
```
58+
59+
## Anti-Patterns
60+
61+
- Keeping all details in root file.
62+
- Splitting into too many tiny files with unclear ownership.
63+
- Duplicating the same rule across files.
64+
- Retaining vague guidance like "write clean code".
65+
- Using absolute or agent-specific links when relative links work.
66+
67+
## Deletion Candidates
68+
69+
Flag these for removal during refactor:
70+
71+
- Rules that just restate defaults.
72+
- Outdated references to removed tools/frameworks.
73+
- Safety slogans without actionable behavior.
74+
- Duplicate rules that conflict in wording.

‎.agents/skills/agent-md-refactor/references/refactor-playbook.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Refactor Playbook
2+
3+
Use this playbook to execute a deterministic refactor from monolithic instruction files to progressive disclosure.
4+
5+
## Phase 1: Contradictions
6+
7+
Find conflicts across instruction files:
8+
9+
- style conflicts (`use semicolons` vs `no semicolons`)
10+
- workflow conflicts (`always run full test suite` vs `run only targeted tests`)
11+
- tool conflicts (`pnpm` vs `npm`)
12+
13+
Capture using:
14+
15+
```markdown
16+
## Contradiction
17+
18+
- Instruction A: <quote + file>
19+
- Instruction B: <quote + file>
20+
- Proposed resolution: <inferred precedence>
21+
- Needs user decision: <yes/no>
22+
```
23+
24+
Escalate to user only when precedence cannot be inferred from repository conventions.
25+
26+
## Phase 2: Root Essentials
27+
28+
Keep only universal material in root:
29+
30+
- one-line project description
31+
- canonical commands (build/test/typecheck/dev)
32+
- package manager only if non-default
33+
- critical global overrides applying to all tasks
34+
35+
Move everything else to topic files.
36+
37+
## Phase 3: Topic Grouping
38+
39+
Target 3-8 files. Common categories:
40+
41+
- `architecture.md`
42+
- `code-style.md`
43+
- `testing.md`
44+
- `typescript.md`
45+
- `git-workflow.md`
46+
- `security.md`
47+
48+
Rules:
49+
50+
1. One topic per file.
51+
2. No cross-file contradictions.
52+
3. Use concrete imperative rules, not slogans.
53+
54+
## Phase 4: Structure
55+
56+
Preferred structure:
57+
58+
```text
59+
project-root/
60+
├── AGENTS.md (or CLAUDE.md/COPILOT.md)
61+
└── .agent-instructions/
62+
├── architecture.md
63+
├── code-style.md
64+
├── testing.md
65+
└── ...
66+
```
67+
68+
Use relative links from root to each topic file.
69+
70+
## Phase 5: Prune
71+
72+
Remove statements that are:
73+
74+
- redundant with repository defaults
75+
- vague and non-actionable
76+
- generic safe-language with no behavioral effect
77+
- obsolete/outdated
78+
79+
When pruning, keep a short "removed rules" note with reasons.

‎.agents/skills/coding/SKILL.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
name: coding
3+
description: Implement and review Java code changes for Micronaut framework repositories using maintainer standards. Use when users ask to add or refactor Java code, fix framework bugs, evolve internal APIs, or prepare committer-ready changes with tests and verification.
4+
license: Apache-2.0
5+
compatibility: Micronaut framework repositories in micronaut-projects generated from micronaut-project-template
6+
metadata:
7+
author: Álvaro Sánchez-Mariscal
8+
version: "1.0.0"
9+
---
10+
11+
# Coding (Micronaut Committer)
12+
13+
Use this skill for maintainer-facing Java implementation work in Micronaut repositories. Do not default to end-user application shortcuts.
14+
15+
## Goal
16+
17+
Deliver minimal, source-backed Java changes that preserve framework quality: binary compatibility, null-safety, reflection-free behavior, and full Gradle verification (`check`, `docs`, and compatibility checks when API-facing).
18+
19+
## Trigger Examples
20+
21+
Should trigger:
22+
23+
- "Implement this Micronaut Java feature in `src/main/java` and keep API compatibility."
24+
- "Refactor this module internals and mark non-public APIs correctly."
25+
- "Fix failing framework tests and prepare committer-ready validation output."
26+
- "Add configuration support using Micronaut conventions, not app-level shortcuts."
27+
28+
Should not trigger:
29+
30+
- "Explain Micronaut basics to a beginner."
31+
- "Create an end-user sample app from scratch."
32+
- "Only edit release notes/changelog text."
33+
34+
## Procedure
35+
36+
1. Establish scope and API impact.
37+
2. Implement Java code with Micronaut maintainer conventions.
38+
3. Enforce API boundaries and binary compatibility.
39+
4. Keep Gradle/build changes aligned with repository conventions.
40+
5. Verify with maintainer-grade checks before completion.
41+
42+
### 1) Establish scope and API impact
43+
44+
- Identify affected modules and whether any change is public API or internal-only.
45+
- Inspect existing package patterns before editing (imports, nullability style, tests, naming).
46+
- For API-facing edits, plan compatibility checks up front (`japiCmp`).
47+
- Keep change surface minimal; avoid opportunistic refactors unless required.
48+
49+
### 2) Implement Java with Micronaut maintainer conventions
50+
51+
- Prefer modern Java idioms where they improve clarity (records, sealed types, pattern matching, `var` for local inference), but only when supported by the repository toolchain/target level.
52+
- Do not use fully qualified class names unless import conflicts force it.
53+
- Follow the repository's established nullability annotations/defaults; use JSpecify and package-level `@NullMarked` only when that convention already exists in the module.
54+
- Avoid reflection-oriented implementations in framework code paths; prefer Micronaut compile-time/introspection mechanisms.
55+
- Use `jakarta.inject` APIs for DI, not `javax.inject`.
56+
- Prefer constructor injection and immutable state over field injection.
57+
- For configuration models, prefer `@ConfigurationProperties` over scattered `@Value` usage.
58+
59+
### 3) Enforce API boundaries and compatibility
60+
61+
- Treat all public-facing changes through a Semantic Versioning lens (`https://semver.org/`) before implementation.
62+
- Classify impact explicitly: patch for backward-compatible fixes, minor for backward-compatible feature additions, major for breaking API/behavioral changes.
63+
- Keep public API binary compatible unless a major-version change explicitly allows breaks.
64+
- Prefer non-breaking API evolution first: deprecate existing methods and add replacement variants/overloads instead of deleting methods or changing signatures in place.
65+
- When using the deprecate-and-add path, keep deprecated APIs functional, point to replacements in Javadoc, and schedule removals only for the next major version.
66+
- If breaking public-facing changes are explicitly allowed, document them in the user guide under `src/main/docs/guide` with migration notes, and update `toc.yml` when adding new guide sections.
67+
- Mark non-user-facing APIs with `@io.micronaut.core.annotation.Internal`.
68+
- Keep visibility as narrow as possible for non-public internals.
69+
- When deprecating API, provide migration-friendly Javadoc and avoid silent behavioral breaks.
70+
71+
### 4) Keep Gradle/build changes convention-aligned
72+
73+
- Use `./gradlew` for all Gradle execution.
74+
- Use Gradle version catalogs (`gradle/libs.versions.toml`) instead of hard-coded dependency versions.
75+
- Use appropriate scopes (`api`, `implementation`, `compileOnly`, `runtimeOnly`) based on API exposure.
76+
- Do not add custom build logic directly in module build files when it belongs in convention plugins.
77+
- When uncertain about module paths, use `./gradlew projects` and prefer canonical `micronaut-*` project names.
78+
79+
### 5) Verify before completion
80+
81+
First confirm canonical verification tasks from `CONTRIBUTING.md` and existing CI/build files, then run the repository equivalents from root.
82+
83+
Common sequence in Micronaut repositories:
84+
85+
```bash
86+
./gradlew :<module>:compileTestJava
87+
# If module includes Groovy tests:
88+
./gradlew :<module>:compileTestGroovy
89+
./gradlew :<module>:test --tests 'pkg.ClassTest'
90+
./gradlew :<module>:test
91+
# If repository documents cM alias/checkstyle aggregate task:
92+
./gradlew -q cM
93+
./gradlew -q spotlessCheck
94+
./gradlew check
95+
./gradlew docs
96+
```
97+
98+
For API-affecting changes, also run if configured in the repository:
99+
100+
```bash
101+
./gradlew japiCmp
102+
```
103+
104+
If Spotless fails, run `./gradlew -q spotlessApply` and re-run `spotlessCheck`.
105+
106+
## Guardrails
107+
108+
- Do not introduce `javax.inject` usage.
109+
- Do not hard-code dependency versions in module build files.
110+
- Do not break public APIs without explicit major-version intent.
111+
- Do not skip tests or docs verification for code changes.
112+
- Do not use reflection as a convenience in framework internals.
113+
114+
## Delivery Contract
115+
116+
When finishing implementation work, report:
117+
118+
1. Exactly which files changed and why.
119+
2. Whether the change is API-facing or internal-only.
120+
3. Semantic Versioning impact classification (patch/minor/major) for any public-facing change.
121+
4. For deprecate-and-add API evolution, which elements were deprecated and which replacement variants were introduced.
122+
5. For breaking public-facing changes, which user guide files were updated and what migration guidance was added.
123+
6. Commands executed for verification and outcomes.
124+
7. Any follow-up risk (for example compatibility implications).
125+
126+
## Validation Checklist
127+
128+
- [ ] `SKILL.md` frontmatter is valid and `name` matches directory (`coding`).
129+
- [ ] Guidance is maintainer-focused (not end-user app guidance).
130+
- [ ] Java conventions include nullability, DI, and reflection-free guidance.
131+
- [ ] API boundary guidance includes `@Internal` and compatibility checks.
132+
- [ ] For public API evolution without breaking changes, deprecations include clear replacement guidance and functional compatibility is preserved.
133+
- [ ] If breaking changes are allowed, user guide docs in `src/main/docs/guide` are updated with migration notes.
134+
- [ ] Verification includes tests, style checks, `check`, and `docs`.
135+
136+
## References
137+
138+
- `CONTRIBUTING.md`
139+
- `MAINTAINING.md`
140+
- `.agents/skills/gradle/SKILL.md`
141+
- `.agents/skills/docs/SKILL.md`
142+
- `.agents/skills/skill-creator/references/spec-checklist.md`

0 commit comments

Comments
 (0)