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
9 changes: 8 additions & 1 deletion .agents/_TOC.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,4 +13,11 @@
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](skills/java-to-kotlin/SKILL.md)
14. [Team memory](memory/MEMORY.md)
15. [Task plans](tasks/README.md)
16. [Java to Kotlin conversion](skills/java-to-kotlin/SKILL.md)
17. [Dependency update](skills/dependency-update/SKILL.md)
18. [Documentation review](skills/review-docs/SKILL.md)
19. [Pre-PR checklist](skills/pre-pr/SKILL.md)
20. [Kotlin code review](skills/kotlin-review/SKILL.md)
21. [Dependency audit](skills/dependency-audit/SKILL.md)
2 changes: 1 addition & 1 deletion .agents/coding-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@
- Reflection unless specifically requested

## Text formatting
- ✅ Remove double empty lines in the code.
- ✅ Replace double empty lines with a single empty line in the code.
- ✅ Remove trailing space characters in the code.

[spine-docs]: https://github.com/SpineEventEngine/documentation/wiki
16 changes: 16 additions & 0 deletions .agents/memory/MEMORY.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# Team memory index

One line per memory. Scan at the start of every session.
See [README.md](README.md) for the format and routing rules.

## Feedback (validated patterns & corrections)

*(no entries yet)*

## Project (durable context & rationale)

*(no entries yet)*

## Reference (external systems)

*(no entries yet)*
89 changes: 89 additions & 0 deletions .agents/memory/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# Team memory — `.agents/memory/`

Validated patterns, durable project context, and pointers to external
systems. Checked into git so the whole team — and any agent working in
this repo — benefits from accumulated knowledge.

This complements Claude Code's built-in per-developer auto-memory:
team-shareable knowledge lives here; personal preferences and ephemeral
state live in the auto-memory.

## Layout

.agents/memory/
├── MEMORY.md # Index — scan at start of every session
├── README.md # This file — read when adding/updating memories
├── feedback/ # Validated patterns & corrections
├── project/ # Durable project context & rationale
└── reference/ # External systems & resources

One file per memory. Filename = the memory's kebab-case slug.

## File format

---
name: tests-no-db-mocks
description: One-line summary — used to surface relevance, so be specific.
metadata:
type: feedback # feedback | project | reference
since: 2026-05-19 # date added (ISO)
---

<one-paragraph rule or fact>

**Why:** <reason — incident, constraint, team convention>

**How to apply:** <when this kicks in; what to do or avoid>

Related: [[other-memory-slug]]

`Why:` and `How to apply:` are required for `feedback` and `project`
memories — they let future readers judge edge cases. `reference`
memories may be shorter (link + one-line purpose).

Link related memories with `[[slug]]` (the target file's `name:`).

## Routing — repo vs. auto-memory

| Kind of fact | Goes to |
|---|---|
| Personal preference, role, style | auto-memory (`user`) |
| Personal habit feedback | auto-memory (`feedback`) |
| Team coding/test/PR rule | **`feedback/`** |
| Durable project rationale | **`project/`** |
| Ephemeral project state (freezes, OOO, deadlines) | auto-memory (`project`) — would rot in git |
| Team-shared external resource | **`reference/`** |
| Personal external resource | auto-memory (`reference`) |

**Litmus test:** *would a teammate joining the project next month benefit
from knowing this?* If no, it belongs in auto-memory.

## Write protocol

1. Write the file **uncommitted** in the working tree.
2. **Surface the change** in the same turn so the human can review.
3. **Do not auto-commit** memory edits as part of an unrelated PR — memory
changes should be reviewable on their own.
4. **Correct in place** when an existing memory turns out wrong; `git blame`
carries the history.
5. **Propose deletion explicitly** when a memory has gone stale, rather
than silently editing it out.

## Updating the index

After adding or removing a memory file, update `MEMORY.md`. One line under
the matching section:

- [slug](category/slug.md) — description from frontmatter

Keep the index short — long descriptions belong in the file body.

## Anti-patterns — do not store

- Anything derivable from the code (module structure, paths, conventions
visible in source). Use `grep` / `Read`.
- Recent-activity summaries or PR lists — `git log` is authoritative.
- Fix recipes for specific bugs — the commit message belongs in the commit.
- Anything already documented in `.agents/` reference docs — keep one
source of truth.
- Personal preferences (see routing).
Empty file.
Empty file added .agents/memory/project/.gitkeep
Empty file.
Empty file.
2 changes: 1 addition & 1 deletion .agents/project-structure-expectations.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,5 +17,5 @@ build.gradle.kts # Kotlin-based build configuration
settings.gradle.kts # Project structure and settings
README.md # Project overview
AGENTS.md # Entry point for LLM agent instructions
version.gradle.kts # Declares the project version.
version.gradle.kts # Declares the project version in versioned Gradle Build Tools repos.
```
115 changes: 115 additions & 0 deletions .agents/skills/dependency-audit/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
---
name: dependency-audit
description: >
Audit changes to dependency declarations under
`buildSrc/src/main/kotlin/io/spine/dependency/` — catches accidental
version downgrades, BOM mismatches, missing deprecation markers when
artifacts are renamed or removed, copyright drift, and convention drift.
Use whenever a diff touches that directory, or when asked to "audit
this dependency bump". Read-only; does not run builds.
---

# Dependency audit (repo-specific)

You are the dependency auditor for a Spine Event Engine repo. All managed
dependencies live under:

buildSrc/src/main/kotlin/io/spine/dependency/

organized by sub-package:

- `lib/` — third-party runtime libraries (Kotlin, Guava, Protobuf, gRPC, …).
- `local/` — Spine SDK artifacts (Base, CoreJvm, ModelCompiler, …).
- `test/` — testing libraries (JUnit, Kotest, AssertK, Truth, Jacoco, Kover).
- `build/` — static-analysis and build-time tools (Dokka, ErrorProne, Pmd,
CheckStyle, KSP, …).
- `kotlinx/` — Kotlin-ecosystem libraries (Coroutines, Serialization,
DateTime, AtomicFu).
- `boms/` — BOM declarations.

Each file declares a Kotlin `object` extending `Dependency` or `DependencyWithBom`
(see `dependency/Dependency.kt`). The shape is:

object Kotest {
const val version = "6.1.11"
const val group = "io.kotest"
const val assertions = "$group:kotest-assertions-core:$version"
// …
}

## How to run an audit

1. **Scope the diff.**
- Run `git diff --stat <base>...HEAD -- 'buildSrc/src/main/kotlin/io/spine/dependency/**'`
(or `--staged` if the user is mid-commit) and read the file list.
- If the diff is empty, ask the user which files to audit.

2. **Read each changed file fully.** Don't trust the hunk in isolation —
`version` constants are often referenced elsewhere in the same file (e.g.
`runtimeVersion` reused as `embeddedVersion`).

3. **Run the checks below in order. Stop the audit and surface a finding the
moment any check fails.**

## Checks

### A. Version sanity
- **No silent downgrade.** Compare the old and new `version` value as semver.
A decrease (`2.0.0 -> 1.9.0`) or a snapshot regression (`-SNAPSHOT.183` ->
`.182`) is a Must-fix unless the commit message explicitly justifies it.
- **Snapshot vs. release consistency.** If `version` switches from a release
(`2.0.0`) to a snapshot (`2.0.1-SNAPSHOT.001`), confirm the consuming code
isn't pinned to the release elsewhere via `grep -r '<libName>:<oldVersion>'`.
- **BOM ↔ component agreement.** For objects extending `DependencyWithBom`,
check that `bom` references the same version as `version` (e.g. Kotlin's
`kotlin-bom:$runtimeVersion`).

### B. Naming and structure
- **Object name matches the upstream library name** (PascalCase). New files
must follow the convention of neighbors (e.g. `lib/Foo.kt` declares
`object Foo`).
- **No type names in property names** (`fooList`, `barObject`) — this is in
`.agents/coding-guidelines.md`.
- **Module constants use `"$group:<artifact>:$version"`**, not hardcoded
Maven coordinates. Catch copy-paste like `"io.kotest:kotest-assertions-core:6.1.11"`.

### C. Deprecation discipline
When an artifact is **renamed or removed**:
- The old `const val` must stay with `@Deprecated("…", ReplaceWith("…"))`
or `@Deprecated("…")` (see `Kotest.frameworkApi` and `Kotest.datatest` for
the established style).
- If the diff deletes a `const val` outright, grep the repo with
`git grep '<oldName>'` to confirm no caller is left behind. If callers exist,
this is a Must-fix.

### D. Convention drift
- **Copyright header year.** Every changed file should have a current-year
copyright line. If a file was edited but its copyright says `2024`, flag it
(the user can run `/update-copyright` to fix).
- **GitHub URL comment.** New `lib/` and `kotlinx/` files conventionally
start with `// https://github.com/<owner>/<repo>` above the object.
Recommend it if missing.
- **`@Suppress("unused", "ConstPropertyName")` on the object.** This is the
established style for constant-heavy declarations.

### E. Cross-cutting checks
- **`local/` deps don't leak.** Spine SDK artifacts in `local/` should not be
declared in `lib/` or `test/` (and vice versa).
- **No mixing Groovy and Kotlin DSL.** All Gradle code in `buildSrc/` must be
`.kt` or `.gradle.kts`. Catch any `.gradle` file slipping in.

## Output format

Three sections, in this order:

- **Must fix** — version downgrades, missing deprecation markers on removed
symbols, broken callers, BOM/version mismatches.
- **Should fix** — convention drift, missing deprecation `ReplaceWith`,
missing copyright update, missing URL comment, naming oddities.
- **Nits** — formatting, ordering, doc-comment polish.

For each finding, cite the file and line, quote the offending lines, and
show the recommended fix.

End with a one-line verdict: `APPROVE`, `APPROVE WITH CHANGES`, or
`REQUEST CHANGES`.
Loading
Loading