Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions .claude/skills/implement/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
53 changes: 53 additions & 0 deletions .claude/skills/lint/SKILL.md
Original file line number Diff line number Diff line change
@@ -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)
Copy link

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The indentation specification is incorrect. According to the .editorconfig file (line 8), the default indent_size is 2 spaces, and there's no Kotlin-specific override. Kotlin files in this project use 2 spaces for indentation, not 4. This can be verified by examining any Kotlin file in the server/src directory.

Suggested change
- Wrong indentation (4 spaces for Kotlin)
- Wrong indentation (2 spaces for Kotlin)

Copilot uses AI. Check for mistakes.
- Unused or wildcard imports
- Missing trailing newline
- Line length (max 120 characters — see `.editorconfig`)
Copy link

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The reference to .editorconfig for line length is incorrect. The .editorconfig file does not contain a max_line_length setting for Kotlin files. Ktlint uses 120 characters as its default maximum line length when not explicitly configured. The documentation should state this is the ktlint default rather than referencing .editorconfig.

Suggested change
- Line length (max 120 characters — see `.editorconfig`)
- Line length (ktlint default: max 120 characters)

Copilot uses AI. Check for mistakes.

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)
Copy link

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The indentation specification is incorrect. According to the .editorconfig file (line 8), the default indent_size is 2 spaces for all files including Java. There's no Java-specific override that changes this to 2 spaces - it's already 2 spaces by default. The statement about "2 spaces for Java" is technically correct but misleading since it's the same as the default for all files in the project.

Suggested change
- Wrong indentation (2 spaces for Java)
- Wrong indentation (2 spaces, per `.editorconfig`)

Copilot uses AI. Check for mistakes.
- 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
2 changes: 1 addition & 1 deletion .claude/skills/refactor/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .claude/skills/review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion .claude/skills/test/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
4 changes: 3 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down