Skip to content
Merged
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
28 changes: 13 additions & 15 deletions .agents/_TOC.md
Original file line number Diff line number Diff line change
@@ -1,18 +1,16 @@
# Table of Contents

1. [Quick Reference Card](quick-reference-card.md)
2. [Purpose](purpose.md)
3. [Project overview](project-overview.md)
4. [Coding guidelines](coding-guidelines.md)
5. [Documentation & comments](documentation-guidelines.md)
6. [Documentation typography & structure](documentation-typography-and-structure.md)
7. [Documentation tasks](documentation-tasks.md)
8. [Running builds](running-builds.md)
9. [Version policy](version-policy.md)
10. [Project structure expectations](project-structure-expectations.md)
11. [Testing](testing.md)
12. [Safety rules](safety-rules.md)
13. [Advanced safety rules](advanced-safety-rules.md)
14. [Refactoring guidelines](refactoring-guidelines.md)
15. [Common tasks](common-tasks.md)
16. [Java to Kotlin conversion](java-kotlin-conversion.md)
2. [Project overview](project-overview.md)
3. [Coding guidelines](coding-guidelines.md)
4. [Documentation & comments](documentation-guidelines.md)
5. [Documentation tasks](documentation-tasks.md)
6. [Running builds](running-builds.md)
7. [Version policy](version-policy.md)
8. [Project structure expectations](project-structure-expectations.md)
9. [Testing](testing.md)
10. [Safety rules](safety-rules.md)
11. [Advanced safety rules](advanced-safety-rules.md)
12. [Refactoring guidelines](refactoring-guidelines.md)
13. [Common tasks](common-tasks.md)
14. [Java to Kotlin conversion](java-kotlin-conversion.md)
2 changes: 1 addition & 1 deletion .agents/documentation-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,6 @@
## Avoid widows, runts, orphans, or rivers

Agents should **AVOID** text flow patters illustrated
on [this diagram](widow-runt-orphan-river.jpg).
on [this diagram](widow-runt-orphan.jpg).

[todo-comments]: https://github.com/SpineEventEngine/documentation/wiki/TODO-comments
1 change: 0 additions & 1 deletion .agents/project-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@

- **Languages**: Kotlin (primary), Java (secondary).
- **Build tool**: Gradle with Kotlin DSL.
- **Architecture**: Event-driven Command Query Responsibility Segregation (CQRS).
- **Static analysis**: detekt, ErrorProne, Checkstyle, PMD.
- **Testing**: JUnit 5, Kotest Assertions, Codecov.
- **Tools used**: Gradle plugins, IntelliJ IDEA Platform, KSP, KotlinPoet, Dokka.
2 changes: 1 addition & 1 deletion .agents/project-structure-expectations.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,6 @@ buildSrc/
build.gradle.kts # Kotlin-based build configuration
settings.gradle.kts # Project structure and settings
README.md # Project overview
AGENTS.md # LLM agent instructions (this file)
AGENTS.md # Entry point for LLM agent instructions
version.gradle.kts # Declares the project version.
```
20 changes: 0 additions & 20 deletions .agents/purpose.md

This file was deleted.

2 changes: 1 addition & 1 deletion .agents/refactoring-guidelines.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# ⚙️ Refactoring guidelines

- Do not replace Kotest assertions with standard Kotlin's Built-In Test Assertions.
- Do NOT replace Kotest assertions with standard Kotlin's built-in test assertions.
51 changes: 51 additions & 0 deletions .agents/skills/writer/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
---
name: writer
description: >
Write, edit, and restructure user-facing and developer-facing documentation.
Use when asked to create/update docs such as `README.md`, `docs/**`, and
other Markdown documentation;
when drafting tutorials, guides, troubleshooting pages, or migration notes; and
when improving inline API documentation (KDoc) and examples.
---

# Write documentation (repo-specific)

## Decide the target and audience

- Identify the target reader: end user, contributor, maintainer, or tooling/automation.
- Identify the task type: new doc, update, restructure, or documentation audit.
- Identify the acceptance criteria: “what is correct when the reader is done?”

## Choose where the content should live

- Prefer updating an existing doc over creating a new one.
- Place content in the most discoverable location:
- `README.md`: project entry point and “what is this?”.
- `docs/`: longer-form docs (follow existing conventions in that tree).
- Source KDoc: API usage, examples, and semantics that belong with the code.

## Follow local documentation conventions

- Follow `.agents/documentation-guidelines.md` and `.agents/documentation-tasks.md`.
- Use fenced code blocks for commands and examples; format file/dir names as code.
- Avoid widows, runts, orphans, and rivers by reflowing paragraphs when needed.

## Make docs actionable

- Prefer steps the reader can execute (commands + expected outcome).
- Prefer concrete examples over abstract descriptions.
- Include prerequisites (versions, OS, environment) when they are easy to miss.
- Use consistent terminology (match code identifiers and existing docs).

## KDoc-specific guidance

- For public/internal APIs, include at least one example snippet demonstrating common usage.
- When converting from Javadoc/inline comments to KDoc:
- Remove HTML like `<p>` and preserve meaning.
- Prefer short paragraphs and blank lines over HTML formatting.

## Validate changes

- For code changes, follow `.agents/running-builds.md`.
- For documentation-only changes in Kotlin/Java sources, prefer `./gradlew dokka`.

5 changes: 5 additions & 0 deletions .agents/skills/writer/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
interface:
display_name: "Writer"
short_description: "Write and update user/developer docs"
default_prompt: "Write or revise documentation in this repository (for example: README.md, docs/**, CONTRIBUTING.md, and API documentation/KDoc). Follow local documentation guidelines in .agents/*.md, keep changes concise and actionable, and include concrete examples and commands where appropriate."

23 changes: 23 additions & 0 deletions .agents/skills/writer/assets/templates/doc-page.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# Title

## Goal

State what the reader will accomplish.

## Prerequisites

- List versions/tools the reader needs.

## Steps

1. Do the first thing.
2. Do the next thing.

## Verify

Show how the reader can confirm success.

## Troubleshooting

- Common failure: likely cause → fix.

11 changes: 11 additions & 0 deletions .agents/skills/writer/assets/templates/kdoc-example.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
````kotlin
/**
* Explain what this API does in one sentence.
*
* ## Example
* ```kotlin
* // Show the typical usage pattern.
* val result = doThing()
* ```
*/
````
13 changes: 13 additions & 0 deletions .agents/skills/writer/assets/templates/kotlin-java-example.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
{{< code-tabs langs="Kotlin, Java">}}

{{< code-tab lang="Kotlin" >}}
```kotlin
```
{{< /code-tab >}}

{{< code-tab lang="Java" >}}
```java
```
{{< /code-tab >}}

{{< /code-tabs >}}
Binary file added .agents/widow-runt-orphan.jpg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
8 changes: 7 additions & 1 deletion .claude/settings.local.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,13 @@
"Bash(./gradlew:*)",
"Bash(find:*)",
"Bash(ls:*)",
"Bash(mkdir:*)"
"Bash(mkdir:*)",
"WebSearch",
"WebFetch(domain:kotest.io)",
"WebFetch(domain:github.com)",
"WebFetch(domain:slack-chats.kotlinlang.org)",
"WebFetch(domain:central.sonatype.com)",
"Bash(jar tf:*)"
],
"deny": []
}
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,6 @@ jobs:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
FORMAL_GIT_HUB_PAGES_AUTHOR: developers@spine.io
# https://docs.github.com/en/actions/reference/environment-variables
REPO_SLUG: $GITHUB_REPOSITORY # e.g. SpineEventEngine/core-java
REPO_SLUG: ${{ github.repository }} # e.g. SpineEventEngine/core-jvm
GOOGLE_APPLICATION_CREDENTIALS: ./maven-publisher.json
NPM_TOKEN: ${{ secrets.NPM_SECRET }}
5 changes: 3 additions & 2 deletions .idea/kotlinc.xml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions .idea/live-templates/README.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 1 addition & 2 deletions .idea/misc.xml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 3 additions & 3 deletions .junie/guidelines.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Guidelines for Junie and AI Agent from JetBrains

Read the `../.agents/_TOC.md` file at the root of the project to understand:
Read the `../.agents/_TOC.md` file to understand:
- the agent responsibilities,
- project overview,
- coding guidelines,
- project overview,
- coding guidelines,
- other relevant topics.

Also follow the Junie-specific rules described below.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,10 +48,10 @@ import org.junit.jupiter.api.Test

/**
* Tests for interaction between
* [ScopedLoggingContext][io.spine.logging.jvm.context.ScopedLoggingContext]
* [ScopedLoggingContext][io.spine.logging.context.ScopedLoggingContext]
* and [Log4j2LoggerBackend].
*
* [ScopedLoggingContext][io.spine.logging.jvm.context.ScopedLoggingContext] is abstract.
* [ScopedLoggingContext][io.spine.logging.context.ScopedLoggingContext] is abstract.
* To test it with the Log4j backend, a concrete implementation is needed.
*
* This test suite uses
Expand Down
4 changes: 1 addition & 3 deletions build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ apply(from = "$rootDir/version.gradle.kts")

spinePublishing {
artifactPrefix = "spine-logging-"
toolArtifactPrefix = "NONE"
modules = setOf(
"log4j2-backend",
"jul-backend",
Expand All @@ -64,9 +65,6 @@ spinePublishing {
gitHub("logging")
)
}
dokkaJar {
java = false
}
}

allprojects {
Expand Down
Loading
Loading