gtnh-java-style-skill 0.1.0 → 0.1.1

package/LICENSE

@@ -1,38 +1,38 @@
-This package contains components under two licenses.
-
-1. Installer code (`bin/`, tests, and package scaffolding)
-   MIT License
-
-   Copyright (c) 2026 contributors
-
-   Permission is hereby granted, free of charge, to any person obtaining a copy
-   of this software and associated documentation files (the "Software"), to deal
-   in the Software without restriction, including without limitation the rights
-   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-   copies of the Software, and to permit persons to whom the Software is
-   furnished to do so, subject to the following conditions:
-
-   The above copyright notice and this permission notice shall be included in all
-   copies or substantial portions of the Software.
-
-   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-   SOFTWARE.
-
-2. Skill documentation (`skill/`)
-   Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
-
-   Adapted from:
-   GT New Horizons Wiki — “Code Style”
-   https://wiki.gtnewhorizons.com/wiki/Code_Style
-
-   The source wiki states that its content is available under CC BY-SA 4.0
-   unless otherwise noted. The adapted skill documentation is distributed under
-   the same license.
-
-   License text:
-   https://creativecommons.org/licenses/by-sa/4.0/legalcode
+This package contains components under two licenses.
+
+1. Installer code (`bin/`, tests, and package scaffolding)
+   MIT License
+
+   Copyright (c) 2026 contributors
+
+   Permission is hereby granted, free of charge, to any person obtaining a copy
+   of this software and associated documentation files (the "Software"), to deal
+   in the Software without restriction, including without limitation the rights
+   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+   copies of the Software, and to permit persons to whom the Software is
+   furnished to do so, subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included in all
+   copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+   SOFTWARE.
+
+2. Skill documentation (`skill/`)
+   Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
+
+   Adapted from:
+   GT New Horizons Wiki — “Code Style”
+   https://wiki.gtnewhorizons.com/wiki/Code_Style
+
+   The source wiki states that its content is available under CC BY-SA 4.0
+   unless otherwise noted. The adapted skill documentation is distributed under
+   the same license.
+
+   License text:
+   https://creativecommons.org/licenses/by-sa/4.0/legalcode

package/README.md

@@ -1,58 +1,56 @@
-# gtnh-java-style-skill
-
-An installable [Agent Skills](https://agentskills.io/) package for GT New Horizons Java code style.
-
-It turns the GTNH Code Style wiki page into a compact agent workflow plus an on-demand reference, so coding agents can apply the conventions while writing and reviewing Java.
-
-## Install with npx
-
-After publishing to npm:
-
-```bash
-npx gtnh-java-style-skill
-```
-
-Default destination:
-
-```text
-~/.agents/skills/gtnh-java-style/
-```
-
-Install into another skills directory:
-
-```bash
-npx gtnh-java-style-skill --dir ~/.claude/skills
-```
-
-Replace an existing installation:
-
-```bash
-npx gtnh-java-style-skill --force
-```
-
-## Local development
-
-```bash
-npm test
-npm run check
-```
-
-Test the package exactly as npm will publish it:
-
-```bash
-npm pack
-npx ./gtnh-java-style-skill-0.1.0.tgz --dir ./tmp-skills
-```
-
-## Publish
-
-1. Pick an available npm package name if `gtnh-java-style-skill` is already taken.
-2. Run `npm login`.
-3. Run `npm run check`.
-4. Run `npm publish`.
-
-The package has one `bin` entry, so `npx gtnh-java-style-skill` resolves directly to the installer.
-
-## Licensing and attribution
-
-The installer code is MIT licensed. The skill documentation is adapted from the GT New Horizons Wiki “Code Style” page and is licensed under CC BY-SA 4.0. See `LICENSE` for details.
+# gtnh-java-style-skill
+
+An installable [Agent Skills](https://agentskills.io/) package for GT New Horizons Java code style.
+
+It turns the GTNH Code Style wiki page into a compact agent workflow plus an on-demand reference, so coding agents can apply the conventions while writing and reviewing Java.
+
+## Install with npx
+
+```bash
+npx gtnh-java-style-skill
+```
+
+Default destination:
+
+```text
+~/.agents/skills/gtnh-java-style/
+```
+
+Install into another skills directory:
+
+```bash
+npx gtnh-java-style-skill --dir ~/.claude/skills
+```
+
+Replace an existing installation:
+
+```bash
+npx gtnh-java-style-skill --force
+```
+
+## Local development
+
+```bash
+npm test
+npm run check
+```
+
+Test the package exactly as npm will publish it:
+
+```bash
+npm pack
+npx ./gtnh-java-style-skill-0.1.0.tgz --dir ./tmp-skills
+```
+
+## Publish
+
+1. Pick an available npm package name if `gtnh-java-style-skill` is already taken.
+2. Run `npm login`.
+3. Run `npm run check`.
+4. Run `npm publish`.
+
+The package has one `bin` entry, so `npx gtnh-java-style-skill` resolves directly to the installer.
+
+## Licensing and attribution
+
+The installer code is MIT licensed. The skill documentation is adapted from the GT New Horizons Wiki “Code Style” page and is licensed under CC BY-SA 4.0. See `LICENSE` for details.

package/bin/cli.mjs

@@ -1,87 +1,87 @@
-#!/usr/bin/env node
-
-import { cp, mkdir, rm, stat } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const source = join(packageRoot, 'skill');
-const skillName = 'gtnh-java-style';
-
-function usage() {
-  return `Usage: gtnh-java-style-skill [options]\n\n` +
-    `Installs the ${skillName} Agent Skill.\n\n` +
-    `Options:\n` +
-    `  --dir <path>   Parent skills directory (default: ~/.agents/skills)\n` +
-    `  --force        Replace an existing installation\n` +
-    `  -h, --help     Show this help\n`;
-}
-
-function parseArgs(argv) {
-  let dir = join(homedir(), '.agents', 'skills');
-  let force = false;
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (arg === '--force') {
-      force = true;
-    } else if (arg === '--dir') {
-      const value = argv[i + 1];
-      if (!value || value.startsWith('--')) {
-        throw new Error('--dir requires a path');
-      }
-      dir = value;
-      i += 1;
-    } else if (arg === '--help' || arg === '-h') {
-      return { help: true, dir, force };
-    } else {
-      throw new Error(`unknown option: ${arg}`);
-    }
-  }
-
-  return { help: false, dir, force };
-}
-
-async function exists(path) {
-  try {
-    await stat(path);
-    return true;
-  } catch (error) {
-    if (error?.code === 'ENOENT') return false;
-    throw error;
-  }
-}
-
-async function main() {
-  let options;
-  try {
-    options = parseArgs(process.argv.slice(2));
-  } catch (error) {
-    console.error(`error: ${error.message}\n`);
-    console.error(usage());
-    process.exitCode = 2;
-    return;
-  }
-
-  if (options.help) {
-    process.stdout.write(usage());
-    return;
-  }
-
-  const target = join(options.dir, skillName);
-  if (await exists(target)) {
-    if (!options.force) {
-      console.error(`error: ${target} already exists; use --force to replace it`);
-      process.exitCode = 1;
-      return;
-    }
-    await rm(target, { recursive: true, force: true });
-  }
-
-  await mkdir(options.dir, { recursive: true });
-  await cp(source, target, { recursive: true });
-  console.log(`installed ${skillName} -> ${target}`);
-}
-
-await main();
+#!/usr/bin/env node
+
+import { cp, mkdir, rm, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const source = join(packageRoot, 'skill');
+const skillName = 'gtnh-java-style';
+
+function usage() {
+  return `Usage: gtnh-java-style-skill [options]\n\n` +
+    `Installs the ${skillName} Agent Skill.\n\n` +
+    `Options:\n` +
+    `  --dir <path>   Parent skills directory (default: ~/.agents/skills)\n` +
+    `  --force        Replace an existing installation\n` +
+    `  -h, --help     Show this help\n`;
+}
+
+function parseArgs(argv) {
+  let dir = join(homedir(), '.agents', 'skills');
+  let force = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--force') {
+      force = true;
+    } else if (arg === '--dir') {
+      const value = argv[i + 1];
+      if (!value || value.startsWith('--')) {
+        throw new Error('--dir requires a path');
+      }
+      dir = value;
+      i += 1;
+    } else if (arg === '--help' || arg === '-h') {
+      return { help: true, dir, force };
+    } else {
+      throw new Error(`unknown option: ${arg}`);
+    }
+  }
+
+  return { help: false, dir, force };
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function main() {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`error: ${error.message}\n`);
+    console.error(usage());
+    process.exitCode = 2;
+    return;
+  }
+
+  if (options.help) {
+    process.stdout.write(usage());
+    return;
+  }
+
+  const target = join(options.dir, skillName);
+  if (await exists(target)) {
+    if (!options.force) {
+      console.error(`error: ${target} already exists; use --force to replace it`);
+      process.exitCode = 1;
+      return;
+    }
+    await rm(target, { recursive: true, force: true });
+  }
+
+  await mkdir(options.dir, { recursive: true });
+  await cp(source, target, { recursive: true });
+  console.log(`installed ${skillName} -> ${target}`);
+}
+
+await main();

package/package.json

@@ -1,35 +1,35 @@
-{
-  "name": "gtnh-java-style-skill",
-  "version": "0.1.0",
-  "description": "Install an Agent Skill that teaches coding agents the GT New Horizons Java code style.",
-  "type": "module",
-  "bin": {
-    "gtnh-java-style-skill": "./bin/cli.mjs"
-  },
-  "files": [
-    "bin",
-    "skill",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "test": "node --test",
-    "check": "npm test && npm pack --dry-run"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "agent-skills",
-    "gtnh",
-    "gt-new-horizons",
-    "java",
-    "code-style",
-    "codex",
-    "claude-code"
-  ],
-  "license": "SEE LICENSE IN LICENSE",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "gtnh-java-style-skill",
+  "version": "0.1.1",
+  "description": "Install an Agent Skill that teaches coding agents the GT New Horizons Java code style.",
+  "type": "module",
+  "bin": {
+    "gtnh-java-style-skill": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "npm test && npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "agent-skills",
+    "gtnh",
+    "gt-new-horizons",
+    "java",
+    "code-style",
+    "codex",
+    "claude-code"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/SKILL.md

@@ -1,47 +1,48 @@
----
-name: gtnh-java-style
-description: Use when writing, reviewing, refactoring, or formatting Java code for GT New Horizons (GTNH), especially when a task mentions GTNH, GregTech 5 Unofficial, GTNH mods, Spotless, Java code style, naming, comments, logging, declarations, deprecation, or pull-request readability.
-license: CC-BY-SA-4.0
-metadata:
-  source: https://wiki.gtnewhorizons.com/wiki/Code_Style
-  version: "0.1.0"
----
-
-# GTNH Java Style
-
-Apply GTNH's Java conventions while keeping behavior changes and style changes easy to review.
-
-## Priority order
-
-1. Preserve correctness and requested behavior.
-2. Follow repository-local formatter/linter configuration, especially Spotless.
-3. Apply the GTNH conventions in [references/style-guide.md](references/style-guide.md).
-4. Prefer readability when a literal rule would create needless ceremony, unless the readable shortcut introduces a known pitfall.
-
-Do not churn unrelated legacy code merely to make it match the guide.
-
-## Workflow
-
-Before editing, inspect nearby code and build configuration. Determine whether the module exposes Spotless tasks and whether modern Java syntax is enabled.
-
-While editing:
-
-- Keep files reasonably sized; treat 2000 lines as a warning sign, not an automatic refactor mandate.
-- Order class members consistently: static fields, instance fields, constructors, then methods grouped by functionality.
-- Delete commented-out code instead of preserving it as comments.
-- Prefer code that explains itself; write comments for intent, constraints, or non-obvious reasoning rather than narrating syntax.
-- Declare variables at the beginning of the relevant block and initialize locals at declaration when practical.
-- Use descriptive mixed-case names: noun-like classes, verb-like methods, meaningful variables.
-- Avoid unexplained magic constants and chained assignments.
-- Keep fields non-public unless public state is genuinely part of the API.
-- Keep `@Deprecated` and `@deprecated` Javadoc paired, and point to the replacement.
-- Use parentheses generously in mixed-operator expressions when they improve clarity.
-- For GTNH logs, normally use one write call per line; keep one-sentence messages lowercase.
-
-After editing, run the repository's formatter/checker if available. Prefer the project's own Gradle tasks over manually reformatting around them.
-
-## Review output
-
-When reviewing code, report concrete violations with the smallest useful fix. Separate formatter-enforced issues from judgment calls. If a proposed style change would reduce readability or create broad diff noise, leave it alone and explain why.
-
-For exact examples and edge cases, read [references/style-guide.md](references/style-guide.md).
+---
+name: gtnh-java-style
+description: Use when writing, reviewing, refactoring, or formatting Java code for GT New Horizons (GTNH), especially when a task mentions GTNH, GregTech 5 Unofficial, GTNH mods, Spotless, Java code style, naming, comments, logging, declarations, deprecation, or pull-request readability.
+license: CC-BY-SA-4.0
+metadata:
+  source: https://wiki.gtnewhorizons.com/wiki/Code_Style
+  version: "0.1.0"
+---
+
+# GTNH Java Style
+
+Apply GTNH's Java conventions while keeping behavior changes and style changes easy to review.
+
+## Priority order
+
+1. Preserve correctness and requested behavior.
+2. Follow repository-local formatter/linter configuration, especially Spotless.
+3. Apply the GTNH conventions in [references/style-guide.md](references/style-guide.md).
+4. Prefer readability when a literal rule would create needless ceremony, unless the readable shortcut introduces a known pitfall.
+
+Do not churn unrelated legacy code merely to make it match the guide.
+
+## Workflow
+
+Before editing, inspect nearby code and build configuration. Determine whether the module exposes Spotless tasks and whether modern Java syntax is enabled.
+
+While editing:
+
+- Keep files reasonably sized; treat 2000 lines as a warning sign, not an automatic refactor mandate.
+- Order class members consistently: static fields, instance fields, constructors, then methods grouped by functionality.
+- Delete commented-out code instead of preserving it as comments.
+- Prefer code that explains itself; write comments for intent, constraints, or non-obvious reasoning rather than narrating syntax.
+- Declare variables at the beginning of the relevant block and initialize locals at declaration when practical.
+- Use descriptive mixed-case names: noun-like classes, verb-like methods, meaningful variables.
+- Avoid unexplained magic constants and chained assignments.
+- Keep fields non-public unless public state is genuinely part of the API.
+- Keep `@Deprecated` and `@deprecated` Javadoc paired, and point to the replacement.
+- Use parentheses generously in mixed-operator expressions when they improve clarity.
+- For GTNH logs, normally use one write call per line; keep one-sentence messages lowercase.
+- Do not use wildcard imports; static wildcard imports are allowed.
+
+After editing, run the repository's formatter/checker if available. Prefer the project's own Gradle tasks over manually reformatting around them.
+
+## Review output
+
+When reviewing code, report concrete violations with the smallest useful fix. Separate formatter-enforced issues from judgment calls. If a proposed style change would reduce readability or create broad diff noise, leave it alone and explain why.
+
+For exact examples and edge cases, read [references/style-guide.md](references/style-guide.md).

package/skill/references/style-guide.md

@@ -1,134 +1,157 @@
-# GTNH Java Code Style Reference
-
-Source: GT New Horizons Wiki, “Code Style” — https://wiki.gtnewhorizons.com/wiki/Code_Style
-
-This reference is an adapted, condensed form of that page. The source wiki content is available under CC BY-SA 4.0; this adaptation is distributed under the same terms.
-
-## Philosophy and formatter
-
-Consistency exists to reduce maintenance cost and make pull requests easier to read. Code is read far more often than it is written. Use good judgment: readability may override a guideline when strict compliance would be needless or less clear, but do not trade away safety merely for visual simplicity.
-
-GTNH uses Spotless for line wrapping, spacing, and indentation. When a repository provides Spotless tasks, treat their result as authoritative for mechanical formatting.
-
-## File and class organization
-
-Avoid files longer than **2000 lines** when practical.
-
-Inside a class or interface, use this broad order:
-
-1. Optional documentation comment.
-2. Class or interface declaration.
-3. Optional implementation-wide comment.
-4. Static fields: public, protected, package-private, private.
-5. Instance fields in the same accessibility order.
-6. Constructors.
-7. Methods grouped by functionality, not by visibility. A private helper may sit between public methods if that makes the feature easier to follow.
-
-## Comments
-
-Delete commented-out code; Git history already preserves old implementations. Avoid comments that are likely to become stale. Before adding a comment, consider whether clearer code would remove the need for it. Do not decorate comments with giant boxes of asterisks.
-
-Use `//` for a short single-line comment. For a multi-line explanatory comment, use a conventional block:
-
-```java
-/*
- * Explain the non-obvious reason here.
- */
-```
-
-`@author` is optional because version control already records authorship.
-
-## Declarations
-
-Prefer one declaration per line unless variables are tightly coupled, such as 3D coordinates:
-
-```java
-int x, y, z;
-```
-
-Never mix declaration styles or types in a confusing declaration. Initialize local variables where they are declared unless some required computation must happen first.
-
-Place declarations at the **beginning of blocks**. In this guide, a block is code enclosed by braces. Avoid delaying a declaration until its first use.
-
-## Statements
-
-When modern Java syntax is enabled for the mod, prefer a modern switch form:
-
-```java
-switch (condition) {
-    case ABC, DEF, KLM -> {
-        handleGroup();
-    }
-    case XYZ -> {
-        handleXyz();
-    }
-    default -> {
-        handleDefault();
-    }
-}
-```
-
-Do not introduce syntax newer than the module's configured Java compatibility allows.
-
-## Naming
-
-- **Classes:** noun-like, descriptive UpperCamelCase names. Prefer whole words; use acronyms only when widely understood.
-- **Interfaces:** UpperCamelCase like classes.
-- **Methods:** verb-like lowerCamelCase names, such as `run()` or `getBackgroundColor()`.
-- **Variables:** meaningful lowerCamelCase names. Start with a letter rather than `_` or `$`.
-
-Short names are fine when their role is obvious and local; otherwise optimize for intent rather than keystrokes.
-
-## GTNH log formatting
-
-For uniform logs, normally use **one write call per line**. A one-sentence log message should usually begin lowercase. If the message contains multiple sentences, normal sentence capitalization is appropriate.
-
-## Programming practices
-
-Do not expose instance or class variables as `public` without a good reason. Prefer behavior-oriented methods over direct mutable state access when that produces a clearer API.
-
-Replace unexplained literal values with well-named constants when the value has domain meaning:
-
-```java
-private static final int RECIPE_ID = 16281;
-
-methodName(RECIPE_ID);
-```
-
-Avoid chained assignments such as:
-
-```java
-fooBar.fChar = barFoo.lchar = 'c';
-```
-
-They save little space and make state changes harder to scan.
-
-## Deprecation
-
-`@Deprecated` and the `@deprecated` Javadoc tag must appear together. The Javadoc should identify the replacement or migration path.
-
-```java
-/**
- * @deprecated use {@link DBHelper#update(String, Map)}
- */
-@Deprecated(forRemoval = true)
-public int insert(String request, Map<String, ?> params) {
-    // existing behavior
-}
-```
-
-## Parentheses
-
-Use **parentheses** liberally when expressions mix operators and grouping could otherwise be misread. Prefer:
-
-```java
-if ((a == b) && (c == d)) {
-    run();
-}
-```
-
-over relying on every reader to mentally evaluate precedence correctly.
-
-## Review checklist
-
-Check in this order: formatter/Spotless, member organization, comments, declarations, naming, GTNH log style, field visibility, constants, assignments, deprecation pairing, then expression clarity. Keep fixes local to the touched code unless the user explicitly requests a broader cleanup.
+# GTNH Java Code Style Reference
+
+Source: GT New Horizons Wiki, “Code Style” — https://wiki.gtnewhorizons.com/wiki/Code_Style
+
+This reference is an adapted, condensed form of that page. The source wiki content is available under CC BY-SA 4.0; this adaptation is distributed under the same terms.
+
+## Philosophy and formatter
+
+Consistency exists to reduce maintenance cost and make pull requests easier to read. Code is read far more often than it is written. Use good judgment: readability may override a guideline when strict compliance would be needless or less clear, but do not trade away safety merely for visual simplicity.
+
+GTNH uses Spotless for line wrapping, spacing, and indentation. When a repository provides Spotless tasks, treat their result as authoritative for mechanical formatting.
+
+## File and class organization
+
+Avoid files longer than **2000 lines** when practical.
+
+Inside a class or interface, use this broad order:
+
+1. Optional documentation comment.
+2. Class or interface declaration.
+3. Optional implementation-wide comment.
+4. Static fields: public, protected, package-private, private.
+5. Instance fields in the same accessibility order.
+6. Constructors.
+7. Methods grouped by functionality, not by visibility. A private helper may sit between public methods if that makes the feature easier to follow.
+
+## Comments
+
+Delete commented-out code; Git history already preserves old implementations. Avoid comments that are likely to become stale. Before adding a comment, consider whether clearer code would remove the need for it. Do not decorate comments with giant boxes of asterisks.
+
+Use `//` for a short single-line comment. For a multi-line explanatory comment, use a conventional block:
+
+```java
+/*
+ * Explain the non-obvious reason here.
+ */
+```
+
+`@author` is optional because version control already records authorship.
+
+## Declarations
+
+Prefer one declaration per line unless variables are tightly coupled, such as 3D coordinates:
+
+```java
+int x, y, z;
+```
+
+Never mix declaration styles or types in a confusing declaration. Initialize local variables where they are declared unless some required computation must happen first.
+
+Place declarations at the **beginning of blocks**. In this guide, a block is code enclosed by braces. Avoid delaying a declaration until its first use.
+
+## Statements
+
+When modern Java syntax is enabled for the mod, prefer a modern switch form:
+
+```java
+switch (condition) {
+    case ABC, DEF, KLM -> {
+        handleGroup();
+    }
+    case XYZ -> {
+        handleXyz();
+    }
+    default -> {
+        handleDefault();
+    }
+}
+```
+
+Do not introduce syntax newer than the module's configured Java compatibility allows.
+
+## Naming
+
+- **Classes:** noun-like, descriptive UpperCamelCase names. Prefer whole words; use acronyms only when widely understood.
+- **Interfaces:** UpperCamelCase like classes.
+- **Methods:** verb-like lowerCamelCase names, such as `run()` or `getBackgroundColor()`.
+- **Variables:** meaningful lowerCamelCase names. Start with a letter rather than `_` or `$`.
+
+Short names are fine when their role is obvious and local; otherwise optimize for intent rather than keystrokes.
+
+## GTNH log formatting
+
+For uniform logs, normally use **one write call per line**. A one-sentence log message should usually begin lowercase. If the message contains multiple sentences, normal sentence capitalization is appropriate.
+
+## Programming practices
+
+Do not expose instance or class variables as `public` without a good reason. Prefer behavior-oriented methods over direct mutable state access when that produces a clearer API.
+
+Replace unexplained literal values with well-named constants when the value has domain meaning:
+
+```java
+private static final int RECIPE_ID = 16281;
+
+methodName(RECIPE_ID);
+```
+
+Avoid chained assignments such as:
+
+```java
+fooBar.fChar = barFoo.lchar = 'c';
+```
+
+They save little space and make state changes harder to scan.
+
+## Deprecation
+
+`@Deprecated` and the `@deprecated` Javadoc tag must appear together. The Javadoc should identify the replacement or migration path.
+
+```java
+/**
+ * @deprecated use {@link DBHelper#update(String, Map)}
+ */
+@Deprecated(forRemoval = true)
+public int insert(String request, Map<String, ?> params) {
+    // existing behavior
+}
+```
+
+## Parentheses
+
+Use **parentheses** liberally when expressions mix operators and grouping could otherwise be misread. Prefer:
+
+```java
+if ((a == b) && (c == d)) {
+    run();
+}
+```
+
+over relying on every reader to mentally evaluate precedence correctly.
+
+## Imports
+
+Do not use wildcard imports. GTNH checks this automatically.
+
+Prefer explicit imports:
+
+```java
+import java.util.List;
+import java.util.Map;
+```
+
+Avoid:
+
+```java
+import java.util.*;
+```
+
+Static wildcard imports are allowed:
+
+```java
+import static org.junit.Assert.*;
+```
+
+## Review checklist
+
+Check in this order: formatter/Spotless, member organization, comments, declarations, naming, GTNH log style, field visibility, constants, assignments, deprecation pairing, then expression clarity. Keep fixes local to the touched code unless the user explicitly requests a broader cleanup.