Add Copilot skill for Akces Framework internal development by Copilot · Pull Request #336 · elasticsoftwarefoundation/akces-framework

Copilot · 2026-04-11T11:58:06Z

New Copilot cloud agent skill (.github/skills/akces-framework-development/SKILL.md) for coding tasks on the framework internals. Complements the existing embabel-agent-framework skill which covers the Embabel/agentic side.

Activation scope: Framework architecture, core module changes, Kafka integration, state management, schema handling, build infrastructure, operator work
Module map: Full dependency graph (api → shared → runtime → client → query-support → eventcatalog → agentic) with per-module package/class tables using full org.elasticsoftware.akces package names
Technology stack: Kafka-backed JSON Schema registry (Akces-Schemas topic), Protobuf 3.x internal wire protocol (jackson-dataformat-protobuf), Jackson 3.x (tools.jackson for core/databind, com.fasterxml.jackson.annotation for annotations in api)
Runtime internals: Partition lifecycle state machine (INITIALIZING → INITIALIZING_STATE → LOADING_GDPR_KEYS → LOADING_STATE → PROCESSING → SHUTTING_DOWN), handler function adapter pattern, Kafka topic layout, exactly-once transaction boundaries, RocksDB state snapshots
Agentic module: Singleton enforcement (1 partition per topic type, 1 replica), automatic initial state creation via getCreateDomainEvent() + @EventSourcingHandler(create = true), Kafka topic table, tick model, agent resolution — defers to embabel-agent-framework skill for Embabel concepts
Coding conventions: Immutable records, error events over exceptions, schema versioning, GDPR/PII handling (shared Akces-GDPRKeys topic), Apache 2.0 headers
Common dev tasks: Step-by-step for adding annotations, built-in events, protocol records, partition lifecycle changes, and new K8s CRDs
Build/test: Per-module commands and known quirks (e.g. -Dmaven.compiler.failOnError=false for controller compilation issues)

Agent-Logs-Url: https://github.com/elasticsoftwarefoundation/akces-framework/sessions/83ba810d-6324-4d6c-a60d-967cf9b0c8e6 Co-authored-by: jwijgerd <914840+jwijgerd@users.noreply.github.com>

Copilot

Pull request overview

Adds a new GitHub Copilot skill document intended to guide contributors working on the Akces Framework internals (core modules, runtime internals, operator, and build/test workflows), complementing the existing Embabel-focused skill.

Changes:

Introduces .github/skills/akces-framework-development/SKILL.md with an internal development guide (module map, runtime/agentic internals, conventions, and common tasks).
Documents build/test commands and operational development notes for framework modules and the Kubernetes operator.

Copilot · 2026-04-11T12:03:21Z

+- [FRAMEWORK_OVERVIEW.md](../../FRAMEWORK_OVERVIEW.md) — Detailed architecture documentation
+- [SERVICES.md](../../SERVICES.md) — Kubernetes services and deployment
+- [README.md](../../README.md) — Project overview and getting started


The relative links in the Reference Links section point to ../../FRAMEWORK_OVERVIEW.md, ../../SERVICES.md, and ../../README.md, which resolves under .github/ (e.g. .github/FRAMEWORK_OVERVIEW.md) and does not exist. These links should go up one more level to the repo root (e.g. ../../../FRAMEWORK_OVERVIEW.md).

Suggested change

- [FRAMEWORK_OVERVIEW.md](../../FRAMEWORK_OVERVIEW.md) — Detailed architecture documentation

- [SERVICES.md](../../SERVICES.md) — Kubernetes services and deployment

- [README.md](../../README.md) — Project overview and getting started

- [FRAMEWORK_OVERVIEW.md](../../../FRAMEWORK_OVERVIEW.md) — Detailed architecture documentation

- [SERVICES.md](../../../SERVICES.md) — Kubernetes services and deployment

- [README.md](../../../README.md) — Project overview and getting started

Copilot · 2026-04-11T12:03:22Z

+| `o.e.akces.aggregate` | `Aggregate<S>`, `AgenticAggregate<S>`, `AggregateState`, `MemoryAwareState`, `TaskAwareState`, `CommandHandlerFunction`, `EventSourcingHandlerFunction`, `EventHandlerFunction`, `EventBridgeHandlerFunction`, `UpcastingHandlerFunction`, `CommandType`, `DomainEventType`, `AggregateStateType`, `SchemaType` |
+| `o.e.akces.annotations` | `@AggregateInfo`, `@AgenticAggregateInfo`, `@CommandInfo`, `@DomainEventInfo`, `@AggregateStateInfo`, `@CommandHandler`, `@EventSourcingHandler`, `@EventHandler`, `@EventBridgeHandler`, `@UpcastingHandler`, `@PIIData`, `@AggregateIdentifier`, `@QueryModelInfo`, `@QueryModelEventHandler`, `@DatabaseModelInfo`, `@DatabaseModelEventHandler`, `@QueryModelStateInfo`, `@ReflectorInfo`, `@ReflectorEventHandler` |
+| `o.e.akces.commands` | `Command`, `CommandBus` interfaces |
+| `o.e.akces.events` | `DomainEvent`, `ErrorEvent` interfaces |
+| `o.e.akces.processmanager` | `ProcessManager<S, P>` interface |
+| `o.e.akces.query` | `QueryModel<S>`, `QueryModelState`, `DatabaseModel` |


The package names in the module tables use o.e.akces.*, but the actual packages in this repo are org.elasticsoftware.akces.*. Using the abbreviated prefix here is likely to confuse contributors searching/navigating the code (and the later task steps also reference o.e.akces.*).

Suggested change

| `o.e.akces.aggregate` | `Aggregate<S>`, `AgenticAggregate<S>`, `AggregateState`, `MemoryAwareState`, `TaskAwareState`, `CommandHandlerFunction`, `EventSourcingHandlerFunction`, `EventHandlerFunction`, `EventBridgeHandlerFunction`, `UpcastingHandlerFunction`, `CommandType`, `DomainEventType`, `AggregateStateType`, `SchemaType` |

| `o.e.akces.annotations` | `@AggregateInfo`, `@AgenticAggregateInfo`, `@CommandInfo`, `@DomainEventInfo`, `@AggregateStateInfo`, `@CommandHandler`, `@EventSourcingHandler`, `@EventHandler`, `@EventBridgeHandler`, `@UpcastingHandler`, `@PIIData`, `@AggregateIdentifier`, `@QueryModelInfo`, `@QueryModelEventHandler`, `@DatabaseModelInfo`, `@DatabaseModelEventHandler`, `@QueryModelStateInfo`, `@ReflectorInfo`, `@ReflectorEventHandler` |

| `o.e.akces.commands` | `Command`, `CommandBus` interfaces |

| `o.e.akces.events` | `DomainEvent`, `ErrorEvent` interfaces |

| `o.e.akces.processmanager` | `ProcessManager<S, P>` interface |

| `o.e.akces.query` | `QueryModel<S>`, `QueryModelState`, `DatabaseModel` |

| `org.elasticsoftware.akces.aggregate` | `Aggregate<S>`, `AgenticAggregate<S>`, `AggregateState`, `MemoryAwareState`, `TaskAwareState`, `CommandHandlerFunction`, `EventSourcingHandlerFunction`, `EventHandlerFunction`, `EventBridgeHandlerFunction`, `UpcastingHandlerFunction`, `CommandType`, `DomainEventType`, `AggregateStateType`, `SchemaType` |

| `org.elasticsoftware.akces.annotations` | `@AggregateInfo`, `@AgenticAggregateInfo`, `@CommandInfo`, `@DomainEventInfo`, `@AggregateStateInfo`, `@CommandHandler`, `@EventSourcingHandler`, `@EventHandler`, `@EventBridgeHandler`, `@UpcastingHandler`, `@PIIData`, `@AggregateIdentifier`, `@QueryModelInfo`, `@QueryModelEventHandler`, `@DatabaseModelInfo`, `@DatabaseModelEventHandler`, `@QueryModelStateInfo`, `@ReflectorInfo`, `@ReflectorEventHandler` |

| `org.elasticsoftware.akces.commands` | `Command`, `CommandBus` interfaces |

| `org.elasticsoftware.akces.events` | `DomainEvent`, `ErrorEvent` interfaces |

| `org.elasticsoftware.akces.processmanager` | `ProcessManager<S, P>` interface |

| `org.elasticsoftware.akces.query` | `QueryModel<S>`, `QueryModelState`, `DatabaseModel` |

Copilot · 2026-04-11T12:03:22Z

+
+**Rules when modifying `api`:**
+- Interfaces and annotations here are the public API. Changes are breaking.
+- Keep the module dependency-free (no Kafka, no Spring, no Jackson).


The guidance 'Keep the module dependency-free (no Kafka, no Spring, no Jackson)' is inaccurate for main/api: it depends on spring-context and jackson-annotations (and uses com.fasterxml.jackson.annotation.* in the API types). Consider updating this to the real constraint (e.g. no Kafka/runtime deps, and only Jackson annotations).

Suggested change

- Keep the module dependency-free (no Kafka, no Spring, no Jackson).

- Keep the module free of Kafka and runtime implementation dependencies; only lightweight API-level dependencies such as Spring context support and Jackson annotations should be used here.

Copilot · 2026-04-11T12:03:22Z

+- **Maven** — multi-module build, Bill of Materials (`bom/`), annotation processors
+- **RocksDB** — embedded key–value store for aggregate state snapshots
+- **Confluent Schema Registry** — Avro schema management for commands, events, and state
+- **Jackson 3.x** — JSON serialization via `tools.jackson` package (not `com.fasterxml.jackson`)


The Jackson note says to use tools.jackson and not com.fasterxml.jackson, but the codebase still uses com.fasterxml.jackson.annotation.* / jackson-annotations (notably in main/api). This should be clarified (e.g. tools.jackson for databind/core, com.fasterxml.jackson.annotation still used for annotations) to avoid misleading imports.

Suggested change

- **Jackson 3.x** — JSON serialization via `tools.jackson` package (not `com.fasterxml.jackson`)

- **Jackson 3.x** — use `tools.jackson` for core/databind JSON serialization APIs; `com.fasterxml.jackson.annotation` may still be used for annotations where the codebase depends on `jackson-annotations` (notably in `main/api`)

Copilot · 2026-04-11T12:03:22Z

+- **Spring Boot 4.x** — auto-configuration, dependency injection, Spring Kafka
+- **Maven** — multi-module build, Bill of Materials (`bom/`), annotation processors
+- **RocksDB** — embedded key–value store for aggregate state snapshots
+- **Confluent Schema Registry** — Avro schema management for commands, events, and state


The tech stack claims 'Confluent Schema Registry' and 'Avro schema management', but the framework’s SchemaRegistry implementation is Kafka-topic based (Akces-Schemas) and schemas are generated/validated as JSON Schema. Also, protocol records are serialized via Protobuf in ProtocolRecordSerde, not Avro. Updating this would prevent incorrect guidance.

Suggested change

- **Confluent Schema Registry** — Avro schema management for commands, events, and state

- **Kafka-backed schema registry** — schemas are stored in the `Akces-Schemas` topic and generated/validated as JSON Schema; protocol records use Protobuf serialization

Copilot · 2026-04-11T12:03:23Z

+`STARTING` → `INITIALIZING` → `CATCHING_UP` → `PROCESSING` → `SHUTTING_DOWN`
+
+For agentic aggregates, there is an additional `INITIALIZING_STATE` step between `INITIALIZING` and `CATCHING_UP` for auto-creating singleton state.


The partition lifecycle state list (STARTING → INITIALIZING → CATCHING_UP → PROCESSING → SHUTTING_DOWN) does not match the actual AggregatePartitionState enum (INITIALIZING, INITIALIZING_STATE, LOADING_GDPR_KEYS, LOADING_STATE, PROCESSING, SHUTTING_DOWN). This section should reflect the real state machine names to avoid confusion when debugging partition behavior.

Suggested change

`STARTING` → `INITIALIZING` → `CATCHING_UP` → `PROCESSING` → `SHUTTING_DOWN`

For agentic aggregates, there is an additional `INITIALIZING_STATE` step between `INITIALIZING` and `CATCHING_UP` for auto-creating singleton state.

`INITIALIZING` → `INITIALIZING_STATE` → `LOADING_GDPR_KEYS` → `LOADING_STATE` → `PROCESSING` → `SHUTTING_DOWN`

These names should be used as-is when correlating logs, metrics, and partition behavior during startup, state restoration, GDPR key loading, normal processing, and shutdown.

Copilot · 2026-04-11T12:03:23Z

+### GDPR / PII
+
+- Fields annotated with `@PIIData` are encrypted/decrypted transparently.
+- Encryption keys are per-aggregate, stored in a dedicated `*-GDPRKeys` Kafka topic.


The GDPR section says encryption keys are stored in a dedicated *-GDPRKeys topic. In the current implementation the keys are stored in the shared Akces-GDPRKeys topic (partitioned), not per-aggregate topic. Please update this to match the actual topic layout.

Suggested change

- Encryption keys are per-aggregate, stored in a dedicated `*-GDPRKeys` Kafka topic.

- Encryption keys are stored in the shared partitioned `Akces-GDPRKeys` Kafka topic.

jwijgerd · 2026-04-11T11:59:14Z

+- **Spring Boot 4.x** — auto-configuration, dependency injection, Spring Kafka
+- **Maven** — multi-module build, Bill of Materials (`bom/`), annotation processors
+- **RocksDB** — embedded key–value store for aggregate state snapshots
+- **Confluent Schema Registry** — Avro schema management for commands, events, and state


JSON schema management

Fixed in ae94fc8 — updated to "Kafka-backed schema registry — schemas are stored in the Akces-Schemas compacted Kafka topic and generated/validated as JSON Schema".

jwijgerd · 2026-04-11T12:01:15Z

+
+---
+
+## Technology Stack


mention Protobuf 3.x for Internal Wire Protocol

Added in ae94fc8 — new bullet: "Protobuf 3.x — internal wire protocol for all protocol records (ProtocolRecordSerde, SchemaRecordSerde) using Jackson's jackson-dataformat-protobuf".

jwijgerd · 2026-04-11T12:04:40Z

+| `AgentProcessResultTranslator` | Drains `DomainEvent` objects from the Embabel Blackboard after each tick |
+| `AgenticAggregateRuntimeFactory` | Spring bean factory — registers built-in memory/task events and adapters |
+
+**Important agentic internals:**


mention here that AgenticAggrates are singleton instances with only 1 partition per topic type (add same table as for normal Aggregates). Also mention that the Framework takes care of creating the initital state (base on a DomainEvent and EventSourcingHandler provided by implementing class)

Expanded in ae94fc8 — added singleton enforcement details, auto-creation via getCreateDomainEvent() + @EventSourcingHandler(create = true) during INITIALIZING_STATE, and a Kafka topic table for AgenticAggregates (same structure as normal aggregates but always 1 partition).

…e details Agent-Logs-Url: https://github.com/elasticsoftwarefoundation/akces-framework/sessions/4701bce1-6520-4321-9138-807dce4cd2cb Co-authored-by: jwijgerd <914840+jwijgerd@users.noreply.github.com>

Add Akces Framework development skill for Copilot cloud agent

1d40a92

Agent-Logs-Url: https://github.com/elasticsoftwarefoundation/akces-framework/sessions/83ba810d-6324-4d6c-a60d-967cf9b0c8e6 Co-authored-by: jwijgerd <914840+jwijgerd@users.noreply.github.com>

Copilot AI assigned Copilot and jwijgerd Apr 11, 2026

Copilot created this pull request from a session on behalf of jwijgerd April 11, 2026 11:58 View session

jwijgerd marked this pull request as ready for review April 11, 2026 11:58

Copilot AI review requested due to automatic review settings April 11, 2026 11:58

Copilot started reviewing on behalf of jwijgerd April 11, 2026 11:58 View session

Copilot AI reviewed Apr 11, 2026

View reviewed changes

jwijgerd requested changes Apr 11, 2026

View reviewed changes

Copilot started work on behalf of jwijgerd April 11, 2026 12:05 View session

Copilot AI requested a review from jwijgerd April 11, 2026 12:11

Copilot finished work on behalf of jwijgerd April 11, 2026 12:11

jwijgerd approved these changes Apr 11, 2026

View reviewed changes

jwijgerd merged commit bebef1c into main Apr 11, 2026
3 checks passed

jwijgerd deleted the copilot/create-akces-framework-skill branch April 11, 2026 12:17

	- Keep the module dependency-free (no Kafka, no Spring, no Jackson).
	- Keep the module free of Kafka and runtime implementation dependencies; only lightweight API-level dependencies such as Spring context support and Jackson annotations should be used here.

	- Jackson 3.x — JSON serialization via `tools.jackson` package (not `com.fasterxml.jackson`)
	- Jackson 3.x — use `tools.jackson` for core/databind JSON serialization APIs; `com.fasterxml.jackson.annotation` may still be used for annotations where the codebase depends on `jackson-annotations` (notably in `main/api`)

	- Confluent Schema Registry — Avro schema management for commands, events, and state
	- Kafka-backed schema registry — schemas are stored in the `Akces-Schemas` topic and generated/validated as JSON Schema; protocol records use Protobuf serialization

		`STARTING` → `INITIALIZING` → `CATCHING_UP` → `PROCESSING` → `SHUTTING_DOWN`

		For agentic aggregates, there is an additional `INITIALIZING_STATE` step between `INITIALIZING` and `CATCHING_UP` for auto-creating singleton state.

	- Encryption keys are per-aggregate, stored in a dedicated `*-GDPRKeys` Kafka topic.
	- Encryption keys are stored in the shared partitioned `Akces-GDPRKeys` Kafka topic.

Uh oh!

Conversation

Copilot AI commented Apr 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

jwijgerd Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

jwijgerd Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

jwijgerd Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Apr 11, 2026 •

edited

Loading