diff --git a/.claude/skills/implement/SKILL.md b/.claude/skills/implement/SKILL.md index 680f55b0f..1ee6a9310 100644 --- a/.claude/skills/implement/SKILL.md +++ b/.claude/skills/implement/SKILL.md @@ -13,8 +13,9 @@ A complete feature implementation requires these skills — run them in sequence 1. **`refactor` skill** — if nearby existing code, tests, or configuration would benefit from cleanup *before* adding new code, do it first rather than working around it 2. **`implement` skill** (this skill) — write the production code -3. **`test` skill** — add/update unit and integration tests (`*Test.kt`, `*IT.kt`) -4. **`document` skill** — update `CHANGELOG.md`, `README.md`, and `AGENTS.md` where applicable +3. **`lint` skill** — fix formatting and verify style gates pass +4. **`test` skill** — add/update unit and integration tests (`*Test.kt`, `*IT.kt`) +5. **`document` skill** — update `CHANGELOG.md`, `README.md`, and `AGENTS.md` where applicable > **Prefer refactoring over workarounds**: if you find yourself adding complexity to work around existing code, stop and invoke the `refactor` skill to clean it up first. @@ -32,12 +33,12 @@ Follow **DTO → Store → Service → Controller** (see AGENTS.md Architecture) - [ ] Read root + module `AGENTS.md` (required before any other step) - [ ] Identify the S3 API operation ([AWS docs](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)) - [ ] Review existing similar implementations -- [ ] Run `make format` then `make install` +- [ ] Invoke the **`lint` skill** to fix formatting and verify style gates pass - [ ] Invoke the **`test` skill** to add/update unit and integration tests - [ ] Invoke the **`document` skill** to update `CHANGELOG.md`, `README.md`, and `AGENTS.md` ## Troubleshooting -- **Build fails**: Check Java 25, run `make format` +- **Build fails**: Check Java 25, invoke the **`lint` skill** - **Tests fail**: Ensure XML matches AWS API exactly — run integration tests - **Docker fails**: Try `make skip-docker` to isolate diff --git a/.claude/skills/lint/SKILL.md b/.claude/skills/lint/SKILL.md new file mode 100644 index 000000000..b2ba376bc --- /dev/null +++ b/.claude/skills/lint/SKILL.md @@ -0,0 +1,53 @@ +--- +name: lint +description: Fix code style issues and ensure linting passes. Use when asked to fix lint errors, formatting issues, or when ktlint or Checkstyle violations are reported. +--- + +# Lint Skill — S3Mock + +Read `AGENTS.md` (root + relevant module) before making changes. + +## Linters + +S3Mock uses two linting tools that run as required CI gates: + +| Tool | Target | Config | Auto-fix? | +|------|--------|--------|-----------| +| **ktlint** | Kotlin source files | `.editorconfig` | Yes — `make format` | +| **Checkstyle** | Java source + XML files | `etc/checkstyle.xml` | No — fix manually | + +Both run automatically as part of the full build (`make install`). + +## Workflow + +1. **Run `make format`** — auto-formats all Kotlin files with ktlint. Fixes the vast majority of Kotlin style issues. +2. **Run `./mvnw checkstyle:check`** — reports Checkstyle violations for Java and XML files. Fix violations manually. +3. **Re-run `make install`** — confirm all linting gates pass before submitting. + +## ktlint (Kotlin) + +`make format` auto-fixes most issues. Common violations: +- Wrong indentation (4 spaces for Kotlin) +- Unused or wildcard imports +- Missing trailing newline +- Line length (max 120 characters — see `.editorconfig`) + +To check without modifying files: `./mvnw ktlint:check` + +## Checkstyle (Java / XML) + +Violations must be fixed manually. Common violations (config in `etc/checkstyle.xml`): +- Wrong indentation (2 spaces for Java) +- Line length (max 120 characters) +- Import ordering +- Missing or malformed Javadoc + +See **[docs/JAVA.md](../../../docs/JAVA.md)** for Java style conventions. + +## Checklist + +- [ ] Read root + module `AGENTS.md` for the files being changed +- [ ] Run `make format` to auto-fix Kotlin style +- [ ] Run `./mvnw checkstyle:check` to check Java/XML style +- [ ] Fix any remaining violations manually (see `docs/JAVA.md` for Java conventions, `docs/KOTLIN.md` for Kotlin) +- [ ] Re-run `make install` to confirm all CI gates pass diff --git a/.claude/skills/refactor/SKILL.md b/.claude/skills/refactor/SKILL.md index 62fb428e1..5090ff831 100644 --- a/.claude/skills/refactor/SKILL.md +++ b/.claude/skills/refactor/SKILL.md @@ -34,7 +34,7 @@ Document what, why, and gotchas. Link to AWS API docs where relevant. See **[doc ## Checklist - [ ] Verify no behavior changes — run tests -- [ ] Run `make format` +- [ ] Invoke the **`lint` skill** to fix formatting and verify style gates pass - [ ] Ensure comments explain *why*, not *what* - [ ] Add KDoc for all public APIs - [ ] Use self-documenting names diff --git a/.claude/skills/review/SKILL.md b/.claude/skills/review/SKILL.md index 65ba89f00..07267b70d 100644 --- a/.claude/skills/review/SKILL.md +++ b/.claude/skills/review/SKILL.md @@ -57,6 +57,6 @@ For each finding, reference the specific AGENTS.md rule or AWS API doc where app - [ ] Read root + relevant module `AGENTS.md` - [ ] Check all categories above in priority order -- [ ] Verify CI gates will pass (ktlint, checkstyle, tests, Docker build) +- [ ] Verify CI gates will pass (ktlint, checkstyle, tests, Docker build) — suggest invoking the **`lint` skill** if style issues are found - [ ] Confirm `CHANGELOG.md` is updated if needed - [ ] Provide actionable feedback with specific file/line references diff --git a/.claude/skills/test/SKILL.md b/.claude/skills/test/SKILL.md index 2acf80193..e6c14c133 100644 --- a/.claude/skills/test/SKILL.md +++ b/.claude/skills/test/SKILL.md @@ -24,4 +24,4 @@ Read **[docs/TESTING.md](../../../docs/TESTING.md)**, **[docs/KOTLIN.md](../../. - [ ] Cover both success and failure cases - [ ] Keep tests independent (no shared state, UUID bucket names) - [ ] Use specific assertions -- [ ] Run `make format` +- [ ] Invoke the **`lint` skill** to fix formatting and verify style gates pass diff --git a/AGENTS.md b/AGENTS.md index c3fe70897..1b7d6e81a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -104,9 +104,11 @@ make install # Full build make skip-docker # Skip Docker make test # Unit tests only make integration-tests # Run integration tests -make format # Format Kotlin code +make format # Format Kotlin code (ktlint) ``` +Use the **`lint` skill** to fix formatting and verify style gates (ktlint + Checkstyle) pass. + ## CI/CD Pipeline All PRs and pushes are validated by the `maven-ci-and-prb.yml` GitHub Actions workflow.