From f6581cfd4833d8935611b3039bbb186cc80c0070 Mon Sep 17 00:00:00 2001 From: Einar Date: Tue, 22 Sep 2026 11:11:07 +0200 Subject: [PATCH] docs: align getting-started, guides, understand, and reference docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fill in the Documentation toc entries that pointed at pages which never existed (guides/, understand/, reference/ were empty). Adds: - getting-started/first-slice.md — a Planned-to-Done walkthrough - guides/connect-a-board.md — credentials, config resolution, /connect - understand/the-loop.md — the two independent triggers and slice-type routing, grounded in ralph.sh - reference/cli-commands.md — install/uninstall/status reference Also fixes the install.md 'Verify Installation' step, which pointed at a path the installer never creates (node .build-kit/cli.js), and points README.md's broken Documentation/ links at the pages that actually exist. The three sibling kits (C#, Kotlin, Java) now carry an identical toc.yml and section structure, so their docs read as one aligned set. --- Documentation/getting-started/first-slice.md | 85 ++++++++++++++++++ Documentation/getting-started/install.md | 80 +++++++++++++++-- Documentation/guides/connect-a-board.md | 94 ++++++++++++++++++++ Documentation/index.md | 36 ++++++-- Documentation/reference/cli-commands.md | 79 ++++++++++++++++ Documentation/toc.yml | 24 +++-- Documentation/understand/the-loop.md | 50 +++++++++++ README.md | 1 + 8 files changed, 426 insertions(+), 23 deletions(-) create mode 100644 Documentation/getting-started/first-slice.md create mode 100644 Documentation/guides/connect-a-board.md create mode 100644 Documentation/reference/cli-commands.md create mode 100644 Documentation/understand/the-loop.md diff --git a/Documentation/getting-started/first-slice.md b/Documentation/getting-started/first-slice.md new file mode 100644 index 0000000..c974134 --- /dev/null +++ b/Documentation/getting-started/first-slice.md @@ -0,0 +1,85 @@ +--- +title: Run Your First Slice +description: See a slice go from Planned to Done with the Eventmodelers Build Kit - Java +tableOfContents: false +--- + +# Run Your First Slice + +This walkthrough shows a slice going from `Planned` on your Eventmodelers board to a tested, working Cratis vertical slice in your Java project — with no manual coding in between. + +## Prerequisites + +[Install the kit](install.md) and [connect it to a board](../guides/connect-a-board.md) first. The loop needs a running agent (`node .build-kit/ralph-claude.js`) and valid credentials in `.eventmodelers/config.json`. + +## Look at the example slice first + +Every install ships a working example under `SomeModule/SomeFeature/` — a `Registration` slice (a command and its event) and a `Listing` slice (a projection and read model). Open them before you build your own; they show every convention the kit's build skills reproduce: + +- One type per slice, with the command/event/reactor together +- `@Command`/`@EventType`-style artifacts with a `handle()`-shaped method that returns the event +- The React screen and command wiring in `.tsx`/`.ts` files beside them + +## Start the loop + +```bash +node .build-kit/ralph-claude.js +``` + +The loop polls for two independent triggers — see [Understanding the Loop](../understand/the-loop.md) — and idles quietly until one fires. + +## 1. Mark a slice `Planned` on your board + +On [app.eventmodelers.ai](https://app.eventmodelers.ai), create or open a slice and set its status to `Planned`. For example, a "Register Author" slice might look like: + +```json +{ + "id": "slice-123", + "title": "Register Author", + "status": "Planned", + "contextName": "Authors", + "sliceType": "StateChange", + "commands": ["RegisterAuthor"], + "events": ["AuthorRegistered"], + "description": "Register a new author with name and email" +} +``` + +## 2. The kit fetches and persists the slice + +The real-time subscription picks up the status change and saves the definition to `.build-kit/.slices/Authors/register-author/slice.json`. + +## 3. The kit generates the vertical slice + +Because the slice only carries `commands`/`events` (no `processors`, no `projections`/`queries`), the loop routes to the `build-state-change` skill, which generates `Authors/Registration/RegisterAuthor.java`: + +```java +@Command +@AllowAnonymous +public record RegisterAuthor(@CommandKey String id, String name) { + public AuthorRegistered handle() { + return new AuthorRegistered(new AuthorName(name)); + } +} + +@EventType +public record AuthorRegistered(AuthorName name) { +} +``` + +## 4. The kit builds and tests the slice + +```bash +./gradlew build +./gradlew test +``` + +## 5. The kit updates the board to `Done` + +Once the build and tests pass, the kit calls back to the platform and marks the slice `Done` — closing the loop without you touching an editor. + +## What's next + +- Try a slice with `projections`/`readModel` set — it routes to `build-state-view` instead +- Try a slice with `processors` set — it routes to `build-automation` +- If a slice gets stuck in `InProgress`, check the loop's terminal output, confirm `./gradlew build` succeeds locally, then re-run the loop diff --git a/Documentation/getting-started/install.md b/Documentation/getting-started/install.md index 96cb365..7257900 100644 --- a/Documentation/getting-started/install.md +++ b/Documentation/getting-started/install.md @@ -29,12 +29,12 @@ npx github:Cratis/Eventmodelers-Build-Kit-Java install This will: -1. Copy the **Cratis starter app** (Java backend with Arc + Chronicle, example slice, shared React frontend) into your project root +1. Copy the **Cratis starter app** (Java backend with Arc + Chronicle, an example slice, and the shared React frontend) into your project root 2. Create a `.build-kit/` directory with the agent loop and skills 3. Install Node.js dependencies for the loop 4. Add `.build-kit/` to your `.gitignore` 5. Create `.eventmodelers/config.json` in your project root -6. Configure MCP server in `.build-kit/.claude/settings.json` +6. Configure the MCP server in `.build-kit/.claude/settings.json` ### Option 2: Upstream CLI with Git Stack @@ -58,8 +58,8 @@ The installer prompts for your Eventmodelers credentials: Token: ``` -Get these from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account). You can skip -them and configure later — see the `connect` skill. +Get these from [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account). You can skip any +field and configure it later — see [Connect a Board](../guides/connect-a-board.md). ## After Installation @@ -69,17 +69,79 @@ Start the agent loop: node .build-kit/ralph-claude.js ``` +Or, using a local Ollama model (run `ollama serve` first): + +```bash +OLLAMA_MODEL=qwen3:8b node .build-kit/ralph-ollama.js +``` + Verify the installation: ```bash npx github:Cratis/Eventmodelers-Build-Kit-Java status ``` -Build and run the starter: +You should see: + +``` +.build-kit Status + +Kit dir: ✅ installed +Skills: ✅ installed +Config (root): ✅ present +Config (kit): ✅ present + +Connected to: https://api.eventmodelers.ai +Organization: +Board: +``` + +Build and run the starter app: ```bash -docker-compose up -d # Chronicle development kernel -./gradlew build # backend -./gradlew bootRun # run the backend (http://localhost:8080) -npm install && npm run dev # frontend dev server +docker-compose up -d # Chronicle development kernel +./gradlew build # backend +./gradlew bootRun # run the backend (http://localhost:8080) +npm install && npm run dev # frontend dev server (http://localhost:5173) ``` + +## Next Steps + +Now that the kit is installed: + +1. [Connect your Eventmodelers board](../guides/connect-a-board.md) +2. [Mark a slice as `Planned`](https://app.eventmodelers.ai) on your board +3. [Run the kit](first-slice.md) to implement the slice + +## Troubleshooting + +### Installation Fails + +If installation fails: + +1. Check the Node.js version: `node --version` (should be 18+) +2. Ensure you're in a valid project directory +3. Check network connectivity +4. Try running with elevated permissions if needed + +### Config Not Found + +If the kit can't find your config: + +1. Verify `.eventmodelers/config.json` exists in your project root +2. Check that the JSON is valid: `cat .eventmodelers/config.json | jq .` +3. Ensure your credentials are correct: [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account) + +### MCP Server Not Configured + +If MCP server configuration fails: + +1. Check that `.build-kit/.claude/settings.json` exists +2. Verify the `mcpServers.eventmodelers` entry is present +3. Restart Claude Code after installation + +## See Also + +- [Connect a Board](../guides/connect-a-board.md) +- [Run Your First Slice](first-slice.md) +- [CLI Commands](../reference/cli-commands.md) diff --git a/Documentation/guides/connect-a-board.md b/Documentation/guides/connect-a-board.md new file mode 100644 index 0000000..5bd4cdb --- /dev/null +++ b/Documentation/guides/connect-a-board.md @@ -0,0 +1,94 @@ +--- +title: Connect a Board +description: Set up Eventmodelers board credentials for the Build Kit - Java +tableOfContents: false +--- + +# Connect a Board + +The kit needs three values to talk to your Eventmodelers board: an **organization ID**, a **board ID**, and an API **token**. This guide covers getting them, where they're stored, and how to change them later. + +## Get your credentials + +1. Sign in at [app.eventmodelers.ai/account](https://app.eventmodelers.ai/account) +2. Generate an API token in your workspace settings — it is a UUID and is **shown only once**, so copy it immediately +3. Note your **organization ID** (from your organization settings) and the **board ID** (from the board's URL) + +## Option 1: During installation + +The installer asks for credentials interactively: + +``` +🔑 Enter your Eventmodelers credentials (press Enter to skip any field): + + Organization ID: + Board ID: + Token: +``` + +Paste each value, or press Enter to skip and connect later. + +## Option 2: With the `connect` skill + +If you skipped credentials at install time, or need to change them later, use `/connect` inside Claude Code. The skill: + +1. Checks for inline overrides (`board=`, `token=`, `org=`, `baseUrl=`) in the prompt that invoked it +2. Falls back to `.eventmodelers/config.json` for any value not overridden +3. Asks you for anything still missing, one field at a time +4. Writes the resolved config back to disk + +Every other skill in the kit (`build-state-change`, `build-state-view`, `build-automation`, `load-slice`, `update-slice-status`) calls `connect` first, so you never have to wire credentials into each one individually. + +## Where credentials live + +The installer writes the same config to two places: + +| Location | Purpose | +|---|---| +| `.eventmodelers/config.json` (project root) | The primary config, checked first | +| `.build-kit/.eventmodelers/config.json` (kit directory) | An optional override, checked second | + +Resolution order is **inline parameter > project-root config > kit-directory config > ask the user**. Both files are excluded from version control automatically. + +The config shape is: + +```json +{ + "organizationId": "", + "boardId": "", + "token": "", + "baseUrl": "https://api.eventmodelers.ai" +} +``` + +`baseUrl` defaults to `https://api.eventmodelers.ai` and only needs to be set explicitly when pointing at a self-hosted or local instance. + +## Verify the connection + +```bash +npx github:Cratis/Eventmodelers-Build-Kit-Java status +``` + +A working connection prints the organization and board the kit is currently pointed at: + +``` +Connected to: https://api.eventmodelers.ai +Organization: +Board: +``` + +## Rotate or change credentials + +Run `/connect` again with an inline override to switch boards without editing files by hand: + +``` +/connect board= +``` + +Or edit `.eventmodelers/config.json` directly and restart the loop. + +## See Also + +- [Install the Kit](../getting-started/install.md) +- [Run Your First Slice](../getting-started/first-slice.md) +- [CLI Commands](../reference/cli-commands.md) diff --git a/Documentation/index.md b/Documentation/index.md index ff9d054..1c27c6f 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -14,7 +14,7 @@ When a slice is marked `Planned` on your Eventmodelers board, this kit automatic 1. **Connects** to the Eventmodelers Platform in real-time 2. **Fetches** the slice definition and board context -3. **Generates** a complete Cratis vertical slice (commands, events, read models, React components) +3. **Generates** a complete Cratis vertical slice (commands, events, projections, read models, React components) 4. **Builds** the slice with `./gradlew build` and runs tests with `./gradlew test` 5. **Updates** the board status to `Done` when complete @@ -22,8 +22,9 @@ The entire process happens automatically, with your Claude agent implementing th ## Where to Start -- **[Getting Started](getting-started/)** — Install the kit and run your first slice from Planned to Done -- **[Install the Kit](getting-started/install.md)** — The installer, step by step +- **[Install the Kit](getting-started/install.md)** — Get up and running in five minutes +- **[Run Your First Slice](getting-started/first-slice.md)** — Watch a slice go from `Planned` to `Done` +- **[Connect a Board](guides/connect-a-board.md)** — Wire the kit up to your Eventmodelers board ## How It Works @@ -38,11 +39,15 @@ The kit implements the [Eventmodelers Build Kits platform contract](https://gith - `projections`/`queries`/`readModel` → `build-state-view` (read models) - Otherwise (`commands`/`events`) → `build-state-change` (commands/events) 4. **Cratis conformance** — Generated slices follow Cratis best practices: - - One slice folder per slice (one public type per file) with `@Command` and `@EventType` - - `ConceptAs` for identities and values in events and read models - - Read models exposed as Arc queries with `@Path` + - One public type per file (one slice folder per slice) — command, event, and reactor sit together + - `@Command` records carry a `handle()` method — no separate handler class + - `@EventType` records use past-tense, self-describing names + - `ConceptAs` wraps identities and values in events and read models instead of raw primitives + - Read models are exposed as Arc queries annotated with `@Path` - Package mirrors the folder structure +See [Understanding the Loop](understand/the-loop.md) for the full mechanics. + ## Place in the Cratis Ecosystem This kit sits between the [Eventmodelers Platform](https://app.eventmodelers.ai) and [Cratis](https://cratis.dev): @@ -61,6 +66,12 @@ Install from git (this package is private, so use the git install path): npx github:Cratis/Eventmodelers-Build-Kit-Java install ``` +Or use the upstream CLI with this repository as a git stack: + +```bash +npx @eventmodelers/cli init --stack cratis-java --git https://github.com/Cratis/Eventmodelers-Build-Kit-Java +``` + After installation, run: ```bash @@ -70,6 +81,13 @@ node .build-kit/ralph-claude.js ## Next Steps 1. [Install the kit](getting-started/install.md) -2. Connect your Eventmodelers board credentials -3. Mark a slice as `Planned` on your board -4. Watch the kit automatically implement it as a Cratis vertical slice +2. [Connect your Eventmodelers board](guides/connect-a-board.md) +3. [Mark a slice as `Planned`](https://app.eventmodelers.ai) on your board +4. Watch the kit automatically implement it as a Cratis vertical slice — see [Run Your First Slice](getting-started/first-slice.md) + +## See Also + +- [Understanding the Loop](understand/the-loop.md) — How the two triggers work independently +- [CLI Commands](reference/cli-commands.md) — `install`, `uninstall`, and `status` +- [Cratis Conventions](https://github.com/Cratis/Eventmodelers-Build-Kit-Java/tree/main/templates/.claude/skills/_shared/cratis-conventions.md) — The conventions the kit enforces, generated from the Cratis AI corpus +- [Eventmodelers Build Kits platform contract](https://github.com/Nebulit-GmbH/Eventmodelers-Build-Kits) — The platform skills the kit uses diff --git a/Documentation/reference/cli-commands.md b/Documentation/reference/cli-commands.md new file mode 100644 index 0000000..c119897 --- /dev/null +++ b/Documentation/reference/cli-commands.md @@ -0,0 +1,79 @@ +--- +title: CLI Commands +description: Command reference for the Eventmodelers Build Kit - Java installer CLI +tableOfContents: false +--- + +# CLI Commands + +The kit ships a small installer CLI (`src/cli.js`, invoked via `npx github:Cratis/Eventmodelers-Build-Kit-Java `) that manages the `.build-kit/` directory in your project. It does not run the agent loop itself — that's `node .build-kit/ralph-claude.js`, started separately once the kit is installed. + +| Command | Description | +|---|---| +| `install` | Install `.build-kit` into the current directory | +| `uninstall` | Remove `.build-kit` from the current directory | +| `status` | Check installation and connection status | + +## `install` + +```bash +npx github:Cratis/Eventmodelers-Build-Kit-Java install +``` + +1. Copies the starter app (`templates/root/`) into the project root +2. Copies the agent loop and skills (`templates/build-kit/`) into `.build-kit/` +3. Runs `npm install` inside `.build-kit/` for the loop's own dependencies +4. Adds `.build-kit/` to `.gitignore` +5. Prompts for Eventmodelers credentials and writes `.eventmodelers/config.json` at the project root, with a copy under `.build-kit/.eventmodelers/config.json` +6. Writes the `mcpServers.eventmodelers` entry into `.build-kit/.claude/settings.json`, pointing at `/mcp` + +See [Install the Kit](../getting-started/install.md) for the full walkthrough. + +## `uninstall` + +```bash +npx github:Cratis/Eventmodelers-Build-Kit-Java uninstall +``` + +Removes the `.build-kit/` directory. It does **not** remove the starter app files that were copied into the project root during install, or `.eventmodelers/config.json`. + +## `status` + +```bash +npx github:Cratis/Eventmodelers-Build-Kit-Java status +``` + +Reports whether the kit directory, skills, and both config files are present, and — when `.eventmodelers/config.json` is valid — which organization and board it's connected to: + +``` +.build-kit Status + +Kit dir: ✅ installed +Skills: ✅ installed +Config (root): ✅ present +Config (kit): ✅ present + +Connected to: https://api.eventmodelers.ai +Organization: +Board: +``` + +If `.eventmodelers/config.json` exists but isn't valid JSON, `status` reports `⚠️ Config file is invalid JSON` instead of the connection details. + +## Running the loop + +These aren't CLI subcommands — they're the scripts `install` copies into `.build-kit/`, run directly with Node: + +| Script | Purpose | +|---|---| +| `node .build-kit/ralph-claude.js` | Run the loop with Claude (default) | +| `OLLAMA_MODEL=qwen3:8b node .build-kit/ralph-ollama.js` | Run the loop with a local Ollama model (`ollama serve` must be running) | +| `node .build-kit/ralph-claude.js /path/to/project` | Point the loop at a project directory other than the kit's parent | + +See [Understanding the Loop](../understand/the-loop.md) for what happens once the loop is running. + +## See Also + +- [Install the Kit](../getting-started/install.md) +- [Connect a Board](../guides/connect-a-board.md) +- [Understanding the Loop](../understand/the-loop.md) diff --git a/Documentation/toc.yml b/Documentation/toc.yml index 07f9a6e..184683e 100644 --- a/Documentation/toc.yml +++ b/Documentation/toc.yml @@ -1,10 +1,24 @@ -- text: Home +- name: Home href: index.md -- text: Getting Started +- name: Getting Started items: - - text: Install the Kit + - name: Install the Kit href: getting-started/install.md -- text: Decisions + - name: Run Your First Slice + href: getting-started/first-slice.md +- name: Guides items: - - text: Kit Directory Name + - name: Connect a Board + href: guides/connect-a-board.md +- name: Understand + items: + - name: The Loop and Triggers + href: understand/the-loop.md +- name: Reference + items: + - name: CLI Commands + href: reference/cli-commands.md +- name: Decisions + items: + - name: Kit Directory Name href: decisions/kit-directory-name.md diff --git a/Documentation/understand/the-loop.md b/Documentation/understand/the-loop.md new file mode 100644 index 0000000..688882a --- /dev/null +++ b/Documentation/understand/the-loop.md @@ -0,0 +1,50 @@ +--- +title: The Loop and Triggers +description: How the Eventmodelers Build Kit - Java agent loop decides what to do next +tableOfContents: false +--- + +# The Loop and Triggers + +The kit runs as a long-lived agent loop (`ralph-claude.js` / `ralph-ollama.js`) that repeatedly checks for work and idles quietly when there is none. It implements the [Eventmodelers Build Kits platform contract](https://github.com/Nebulit-GmbH/Eventmodelers-Build-Kits/tree/main/eventmodelers-cli/shared/build-kit). + +## Two independent triggers + +Each loop iteration checks two conditions. They are **not causally linked** — either can fire on its own, and both can fire in the same iteration: + +| Trigger | Condition | What runs | +|---|---|---| +| **Task trigger** | `.build-kit/tasks.json` is non-empty | `lib/prompt.md` — reacts to board status changes (fetches newly `Planned` slices, logs `Done`/`Blocked` results) | +| **Build trigger** | A slice under `.build-kit/.slices/*/index.json` has status `"planned"` | `lib/backend-prompt.md` — builds exactly **one** slice, then stops so the loop can re-check for more work | + +Building one slice per iteration, rather than draining the whole queue at once, keeps each build isolated: if one slice fails, it doesn't block the others from being picked up on the next pass. + +## Running without board credentials + +If `.build-kit/.eventmodelers/config.json` is missing, the task trigger is disabled — there's no board to sync with — but the build trigger still runs. You can drop a slice definition directly into `.build-kit/.slices///index.json` with `"status": "planned"` and the kit will still generate, build, and test it locally. See [Connect a Board](../guides/connect-a-board.md) to enable full board sync. + +## Slice-type routing + +When the build trigger fires, the kit reads the slice definition and routes to one of three build skills: + +| Condition | Skill | Generates | +|---|---|---| +| `sliceType === "TRANSLATION"` | `build-automation` | A reactor that adapts an external fact into a local command | +| `processors[]` is non-empty | `build-automation` | A reactor that reacts to a fact and issues a follow-up command | +| `projections` / `queries` / `readModel` present | `build-state-view` | A projection and read model | +| Otherwise (`commands` / `events` only) | `build-state-change` | A command and its event(s) | + +This mirrors [event modeling](https://eventmodeling.org/)'s four slice patterns — Command, View, Automation, and Translation — applied to Cratis's Arc and Chronicle primitives. + +## One iteration, end to end + +1. **Check triggers.** Read `tasks.json` and scan `.slices/*/index.json` for a `planned` entry. +2. **If a task is pending:** run `prompt.md` — fetch the slice from the board via the `load-slice` skill, persist it under `.slices/`, and clear the task. +3. **If a slice is planned:** run `backend-prompt.md` — route to the correct build skill, generate the code, run `./gradlew build` and `./gradlew test`, then call `update-slice-status` to mark the slice `Done` (or `Blocked`, with the failure reason, if the build or tests fail). +4. **Idle.** If neither trigger fired, wait and check again. + +## See Also + +- [Run Your First Slice](../getting-started/first-slice.md) — this loop, watched end to end +- [CLI Commands](../reference/cli-commands.md) +- [Connect a Board](../guides/connect-a-board.md) diff --git a/README.md b/README.md index 775f3a5..fec031e 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ Note: The Java kit currently uses the `cratis/chronicle/client-java` profile fro - [What the kit owns](#what-the-kit-owns) — capabilities and boundaries - [Usage](#usage) — how to run the agent loop - [Cratis AI corpus](#cratis-ai-corpus) — generated conventions and skills +- [Documentation](Documentation/) — full walkthroughs: install, run your first slice, connect a board, the loop, CLI reference - [License](#license) — MIT - [Sibling kits](#sibling-kits) — C# and Kotlin variants