Merge pull request #544 from SpineEventEngine/add-config

Add Validation docs to the site

Author: alexander-yevsyukov

.agents/_TOC.md

@@ -0,0 +1,23 @@
+# Table of Contents
+
+1. [Quick Reference Card](quick-reference-card.md)
+2. [JVM project requirements](jvm-project.md) — language, build, and review checklist shared by all JVM repos
+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. [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)

.agents/advanced-safety-rules.md

@@ -0,0 +1,6 @@
+# 🚨 Advanced safety rules
+
+- Do **not** auto-update external dependencies without explicit request.
+- Do **not** inject analytics or telemetry code.
+- Flag any usage of unsafe constructs (e.g., reflection, I/O on the main thread).
+- Avoid generating blocking calls inside coroutines.

.agents/coding-guidelines.md

@@ -0,0 +1,39 @@
+# 🧾 Coding guidelines
+
+## Core principles
+
+- Adhere to [Spine Event Engine Documentation][spine-docs] for coding style.
+- Generate code that compiles cleanly and passes static analysis.
+- Respect existing architecture, naming conventions, and project structure.
+- Write clear, incremental commits with descriptive messages.
+- Include automated tests for any code change that alters functionality.
+
+## Kotlin best practices
+
+### ✅ Prefer
+- **Kotlin idioms** over Java-style approaches:
+  - Extension functions
+  - `when` expressions 
+  - Smart casts
+  - Data classes and sealed classes
+  - Immutable data structures
+- **Simple nouns** over composite nouns (`user` > `userAccount`)  
+- **Generic parameters** over explicit variable types (`val list = mutableList<Dependency>()`)  
+- **Java interop annotations** only when needed (`@file:JvmName`, `@JvmStatic`)
+- **Kotlin DSL** for Gradle files
+
+### ❌ Avoid
+- Mutable data structures
+- Java-style verbosity (builders with setters)
+- Redundant null checks (`?.let` misuse)
+- Using `!!` unless clearly justified
+- Type names in variable names (`userObject`, `itemList`)
+- String duplication (use constants in companion objects)
+- Mixing Groovy and Kotlin DSLs in build logic
+- Reflection unless specifically requested
+
+## Text formatting
+ - ✅ 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

.agents/common-tasks.md

@@ -0,0 +1,6 @@
+# 📋 Common tasks
+
+- **Adding a new dependency**: Update relevant files in `buildSrc` directory.
+- **Creating a new module**: Follow existing module structure patterns.
+- **Documentation**: Use KDoc style for public and internal APIs.
+- **Testing**: Create comprehensive tests using Kotest assertions.

.agents/documentation-guidelines.md

@@ -0,0 +1,14 @@
+# Documentation & comments
+
+## Commenting guidelines
+- Avoid inline comments in production code unless necessary.
+- Inline comments are helpful in tests.
+- When using TODO comments, follow the format on the [dedicated page][todo-comments].
+- File and directory names should be formatted as code.
+
+## Avoid widows, runts, orphans, or rivers
+
+Agents should **AVOID** text flow patters illustrated
+on [this diagram](widow-runt-orphan.jpg).
+
+[todo-comments]: https://github.com/SpineEventEngine/documentation/wiki/TODO-comments

.agents/documentation-tasks.md

@@ -0,0 +1,20 @@
+# 📄 Documentation tasks
+
+1. Ensure all public and internal APIs have KDoc examples.
+2. Add in-line code blocks for clarity in tests.
+3. Convert inline API comments in Java to KDoc in Kotlin:
+   ```java
+   // Literal string to be inlined whenever a placeholder references a non-existent argument.
+   private final String missingArgumentMessage = "[MISSING ARGUMENT]";
+   ```
+   transforms to:
+   ```kotlin
+   /**
+    * Literal string to be inlined whenever a placeholder references a non-existent argument.
+    */
+    private val missingArgumentMessage = "[MISSING ARGUMENT]"
+   ```
+
+4. Javadoc -> KDoc conversion tasks:
+   - Remove `<p>` tags in the line with text: `"<p>This"` -> `"This"`.
+   - Replace `<p>` with empty line if the tag is the only text in the line.

.agents/jvm-project.md

@@ -0,0 +1,37 @@
+# JVM Project Requirements
+
+General requirements for all JVM projects in the Spine SDK organisation.
+Repo-specific `project.md` files link here and add their own context.
+
+## Language and build
+
+- **Languages**: Kotlin (primary), Java (secondary).
+- **Build**: Gradle with Kotlin DSL.
+- **Static analysis**: detekt, ErrorProne, Checkstyle, PMD.
+- **Testing**: JUnit 5, Kotest Assertions, Codecov.
+
+## Code review checklist
+
+**Correctness and safety**
+- Code compiles and passes static analysis (detekt, ErrorProne, Checkstyle, PMD).
+- No reflection or unsafe code unless explicitly approved in scope.
+- No analytics, telemetry, or tracking code.
+- No blocking calls inside coroutines.
+
+**Kotlin/Java style**
+- Kotlin idioms preferred: extension functions, `when` expressions, data/sealed
+  classes, immutable data structures.
+- No `!!` unless provably safe. No unchecked casts.
+- No mutable state without justification.
+- No string duplication — use constants.
+
+**Tests**
+- New or changed functionality must include tests.
+- Use stubs, not mocks.
+- Prefer [Kotest assertions][kotest-assertions] over JUnit or Google Truth.
+
+**Versioning**
+- If the repo has `version.gradle.kts`, every PR must include a version bump.
+  Flag the absence as a required change.
+
+[kotest-assertions]: https://kotest.io/docs/assertions/assertions.html

.agents/memory/MEMORY.md

@@ -0,0 +1,17 @@
+# 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)
+
+- [copilot-review-request](feedback/copilot-review-request.md) — GraphQL `requestReviews` with `botIds: ["BOT_kgDOCnlnWA"]`; REST endpoint silently no-ops on re-requests.
+
+## Project (durable context & rationale)
+
+*(no entries yet)*
+
+## Reference (external systems)
+
+- [cache-warm-window](reference/cache-warm-window.md) — How prompt cache entries are shared between sibling-repo sessions and how to maximise overlap.
+- [anthropic-api-caching](reference/anthropic-api-caching.md) — Pattern and pricing for adding prompt caching to any direct Anthropic API call.

.agents/memory/README.md

@@ -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).