@eventmodelers/cli 0.0.1

package/stacks/axon/templates/build-kit/lib/ralph.js

@@ -0,0 +1,369 @@
+// Common runtime for the ralph loop + realtime agent.
+// Not meant to be run directly — use ralph-claude.js or ralph-ollama.js.
+//
+// startRalph({ kitDir, projectDir, onTask, onPlannedSlice })
+//   onTask(prompt) — called when tasks.json has entries
+//   onPlannedSlice(prompt) — called when .slices/ has a "Planned" entry (omit to skip)
+
+import { createClient } from '@supabase/supabase-js';
+import { readFileSync, mkdirSync, writeFileSync, existsSync, readdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { randomUUID } from 'crypto';
+
+// ── HTTP helpers ──────────────────────────────────────────────────────────────
+
+class HttpError extends Error {
+  constructor(status, body) {
+    super(`HTTP ${status}: ${body}`);
+    this.status = status;
+  }
+}
+
+async function fetchJSON(url, options) {
+  const res = await fetch(url, options);
+  if (!res.ok) throw new HttpError(res.status, await res.text());
+  return res.json();
+}
+
+async function retryOn401(label, fn, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err instanceof HttpError && err.status === 401) {
+        if (attempt < maxRetries) {
+          console.warn(`[agent] ${label} — 401, retrying (${attempt}/${maxRetries})...`);
+          continue;
+        }
+        console.error(`[agent] ${label} — 401 after ${maxRetries} retries, shutting down`);
+        process.exit(1);
+      }
+      throw err;
+    }
+  }
+}
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+// Config is resolved by walking from the kit dir up through every ancestor
+// directory's .eventmodelers/config.json, merging fields as we go — a value
+// set by a closer (more specific) directory always wins over a farther one.
+// The walk stops as soon as the merged config has full connection credentials
+// (see hasCredentials); anthropicBaseUrl/model are picked up opportunistically
+// along the way but never force the walk to continue further up.
+function* configCandidates(kitDir) {
+  yield join(kitDir, '.eventmodelers', 'config.json');
+  let dir = dirname(kitDir);
+  while (true) {
+    yield join(dir, '.eventmodelers', 'config.json');
+    const parent = dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+
+function loadLocalConfig(kitDir) {
+  const merged = {};
+  const sources = [];
+
+  for (const candidate of configCandidates(kitDir)) {
+    if (!existsSync(candidate)) continue;
+    let cfg;
+    try {
+      cfg = JSON.parse(readFileSync(candidate, 'utf-8'));
+    } catch {
+      console.warn(`[ralph] Skipping invalid config at ${candidate}`);
+      continue;
+    }
+    for (const [key, value] of Object.entries(cfg)) {
+      if (merged[key] === undefined) merged[key] = value;
+    }
+    sources.push(candidate);
+    if (hasCredentials(merged)) break;
+  }
+
+  if (process.env.BASE_URL) merged.baseUrl = process.env.BASE_URL;
+
+  if (sources.length > 1) {
+    console.log(`[ralph] Merged config from: ${sources.join(', ')}`);
+  } else if (sources.length === 1 && sources[0] !== join(kitDir, '.eventmodelers', 'config.json')) {
+    console.log(`[ralph] Using credentials from ${sources[0]}`);
+  } else if (sources.length === 0) {
+    console.warn(`[ralph] Note: no .eventmodelers/config.json found — platform sync disabled.`);
+    console.warn(`        To enable board sync, follow: https://app.eventmodelers.ai/documentation#build-axon`);
+    console.warn(`        Code generation from local slice definitions will still run.`);
+  }
+
+  return merged;
+}
+
+function hasCredentials(cfg) {
+  return !!(cfg.token && cfg.organizationId && cfg.boardId && cfg.baseUrl);
+}
+
+async function fetchPlatformConfig(local) {
+  const remote = await fetchJSON(`${local.baseUrl}/api/config`, {
+    headers: { 'x-token': local.token },
+  });
+  return { ...local, ...remote };
+}
+
+// ── Realtime agent ────────────────────────────────────────────────────────────
+
+async function getRealtimeToken(cfg) {
+  const { token } = await fetchJSON(
+    `${cfg.baseUrl}/api/org/${cfg.organizationId}/prompts/realtime-token`,
+    { headers: { 'x-token': cfg.token } },
+  );
+  return token;
+}
+
+function slugify(str) {
+  return str.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
+}
+
+async function fetchAndPersistSlices(cfg, kitDir) {
+  const url = `${cfg.baseUrl}/api/org/${cfg.organizationId}/boards/${cfg.boardId}/slicedata/slices`;
+  const { slices } = await fetchJSON(url, {
+    headers: { 'x-token': cfg.token, 'x-board-id': cfg.boardId },
+  });
+  const slicesDir = join(kitDir, '.slices');
+  mkdirSync(slicesDir, { recursive: true });
+
+  // Group by context slug
+  const contexts = {};
+  for (const slice of slices) {
+    const contextSlug = slice.contextName ? slugify(slice.contextName) : 'default';
+    if (!contexts[contextSlug]) contexts[contextSlug] = { name: slice.contextName || 'default', slices: [] };
+    contexts[contextSlug].slices.push(slice);
+  }
+
+  // current_context.json is STICKY. We work within ONE context at a time and must
+  // not auto-jump to another context just because it happens to have planned work.
+  // Keep the existing context if it still exists; only seed it when absent or stale.
+  const ctxPath = join(slicesDir, 'current_context.json');
+  let activeCtx = null;
+  if (existsSync(ctxPath)) {
+    try { activeCtx = JSON.parse(readFileSync(ctxPath, 'utf-8')).name; } catch {}
+  }
+  if (!activeCtx || !contexts[activeCtx]) {
+    // First run (or the current context disappeared): seed with a context that
+    // has planned work, else the first one. This is the ONLY place we choose it.
+    const plannedCtx = Object.keys(contexts).find(c => contexts[c].slices.some(s => (s.status || '').toLowerCase() === 'planned'));
+    activeCtx = plannedCtx || Object.keys(contexts)[0] || 'default';
+    writeFileSync(ctxPath, JSON.stringify({ name: activeCtx }, null, 2), 'utf-8');
+  }
+
+  // Write per-context index.json and per-slice slice.json
+  for (const [contextSlug, { slices: ctxSlices }] of Object.entries(contexts)) {
+    const contextDir = join(slicesDir, contextSlug);
+    mkdirSync(contextDir, { recursive: true });
+
+    const indexSlices = ctxSlices.map((s, i) => {
+      const folder = (s.title ?? s.id).replaceAll(' ', '').toLowerCase();
+      return {
+        id: s.id,
+        slice: s.title,
+        index: i,
+        contextName: s.contextName || contextSlug,
+        contextSlug,
+        folder,
+        status: s.status,
+        definition: { id: s.id, title: s.title, status: s.status },
+      };
+    });
+    writeFileSync(join(contextDir, 'index.json'), JSON.stringify({ slices: indexSlices }, null, 2), 'utf-8');
+
+    for (const slice of ctxSlices) {
+      const folder = (slice.title ?? slice.id).replaceAll(' ', '').toLowerCase();
+      const sliceDir = join(contextDir, folder);
+      mkdirSync(sliceDir, { recursive: true });
+      writeFileSync(join(sliceDir, 'slice.json'), JSON.stringify(slice, null, 2), 'utf-8');
+    }
+  }
+
+  console.log(`[agent] Persisted ${slices.length} slice(s)`);
+}
+
+async function writeTask(payload, kitDir) {
+  const tasksPath = join(kitDir, 'tasks.json');
+  const existing = existsSync(tasksPath) ? JSON.parse(readFileSync(tasksPath, 'utf-8')) : [];
+  const filtered = existing.filter(t => t.payload?.sliceId !== payload.sliceId);
+  const task = { id: randomUUID(), createdAt: new Date().toISOString(), payload };
+  filtered.push(task);
+  writeFileSync(tasksPath, JSON.stringify(filtered, null, 2), 'utf-8');
+  console.log(`[agent] Task written — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
+}
+
+async function startRealtimeAgent(cfg, kitDir) {
+  let realtimeToken = await retryOn401('getRealtimeToken', () => getRealtimeToken(cfg));
+
+  await retryOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
+    console.error('[agent] Initial slice fetch error:', err),
+  );
+
+  const supabase = createClient(cfg.supabaseUrl, cfg.supabaseAnonKey, {
+    realtime: { params: { apikey: cfg.supabaseAnonKey } },
+  });
+  await supabase.realtime.setAuth(realtimeToken);
+
+  const channelName = `board:${cfg.boardId}-slicechanged`;
+
+  supabase
+    .channel(channelName, { config: { private: true } })
+    .on('broadcast', { event: 'message' }, (msg) => {
+      if (msg.payload === 'Exit') {
+        console.log('[agent] Received "Exit" — shutting down');
+        process.exit(0);
+      }
+    })
+    .on('broadcast', { event: 'slice:changed' }, async (msg) => {
+      const payload = msg.payload;
+      console.log(`[agent] slice:changed — slice="${payload.sliceTitle}" status="${payload.sliceStatus}"`);
+      await retryOn401('fetchAndPersistSlices', () => fetchAndPersistSlices(cfg, kitDir)).catch((err) =>
+        console.error('[agent] Slice persist error:', err),
+      );
+      // Planned slices are handled by onPlannedSlice directly — no task needed
+      if ((payload.sliceStatus || '').toLowerCase() !== 'planned') {
+        await writeTask(payload, kitDir).catch((err) => console.error('[agent] writeTask error:', err));
+      }
+    })
+    .subscribe((status) => console.log(`[agent] Channel "${channelName}": ${status}`));
+
+  setInterval(async () => {
+    try {
+      realtimeToken = await retryOn401('getRealtimeToken (refresh)', () => getRealtimeToken(cfg));
+      supabase.realtime.setAuth(realtimeToken);
+      console.log('[agent] Token refreshed');
+    } catch (err) {
+      console.error('[agent] Token refresh failed:', err);
+    }
+  }, 10 * 60 * 1000);
+
+  const ping = async () => {
+    try {
+      const res = await fetch(`${cfg.baseUrl}/api/agent-alive`, {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${realtimeToken}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token: cfg.token }),
+      });
+      if (!res.ok) console.error(`[agent] Ping failed: ${res.status}`);
+    } catch (err) {
+      console.error('[agent] Ping error:', err);
+    }
+  };
+  await ping();
+  setInterval(ping, 30_000);
+}
+
+// ── Ralph loop ────────────────────────────────────────────────────────────────
+
+function hasPendingTasks(kitDir) {
+  const tasksPath = join(kitDir, 'tasks.json');
+  if (!existsSync(tasksPath)) return false;
+  try {
+    const tasks = JSON.parse(readFileSync(tasksPath, 'utf-8'));
+    return Array.isArray(tasks) && tasks.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function readCurrentContext(kitDir) {
+  const ctxPath = join(kitDir, '.slices', 'current_context.json');
+  if (!existsSync(ctxPath)) return null;
+  try { return JSON.parse(readFileSync(ctxPath, 'utf-8')).name || null; } catch { return null; }
+}
+
+// Returns the first Planned slice IN THE CURRENT CONTEXT ONLY. If the current
+// context has no planned work, returns null so the loop waits — it must NEVER
+// cross into another context to find something to build.
+function getFirstPlannedSliceTitle(kitDir) {
+  const currentCtx = readCurrentContext(kitDir);
+  if (!currentCtx) return null;
+  const indexPath = join(kitDir, '.slices', currentCtx, 'index.json');
+  if (!existsSync(indexPath)) return null;
+  try {
+    const { slices } = JSON.parse(readFileSync(indexPath, 'utf-8'));
+    const planned = slices && slices.find((s) => (s.status || '').toLowerCase() === 'planned');
+    if (planned) return planned.slice || planned.id || null;
+  } catch {}
+  return null;
+}
+
+async function runWithRetry(label, fn) {
+  while (true) {
+    try {
+      console.log(`[ralph] ${label}`);
+      await fn();
+      return;
+    } catch (err) {
+      console.error(`[ralph] Error — retrying in 60s:`, err.message);
+      await new Promise((r) => setTimeout(r, 60_000));
+    }
+  }
+}
+
+async function ralphLoop(kitDir, cfg, onTask, onPlannedSlice) {
+  const promptFile = join(kitDir, 'lib', 'prompt.md');
+  const backendPromptFile = join(kitDir, 'lib', 'backend-prompt.md');
+  const credentialed = hasCredentials(cfg);
+  let lastIdleCtx;
+
+  while (true) {
+    let didWork = false;
+
+    if (credentialed && hasPendingTasks(kitDir)) {
+      const prompt = readFileSync(promptFile, 'utf-8');
+      await runWithRetry('onTask: loading slice from board...', () => onTask(prompt));
+      await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
+      didWork = true;
+    }
+
+    const plannedTitle = onPlannedSlice && getFirstPlannedSliceTitle(kitDir);
+    if (plannedTitle) {
+      const prompt = readFileSync(backendPromptFile, 'utf-8');
+      await runWithRetry(`onPlannedSlice: building slice "${plannedTitle}"...`, () => onPlannedSlice(prompt));
+      console.log(`[ralph] Slice build complete — waiting for next slice`);
+      if (credentialed) await fetchAndPersistSlices(cfg, kitDir).catch(() => {});
+      didWork = true;
+    }
+
+    if (!didWork) {
+      // No planned work in the current context — wait, do NOT switch contexts.
+      const ctx = readCurrentContext(kitDir);
+      if (ctx !== lastIdleCtx) {
+        console.log(`[ralph] No planned slices in current context "${ctx}" — waiting. Switch context on the board to continue.`);
+        lastIdleCtx = ctx;
+      }
+      await new Promise((r) => setTimeout(r, 10_000));
+    } else {
+      lastIdleCtx = undefined;
+    }
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+export { loadLocalConfig, fetchPlatformConfig, retryOn401, startRealtimeAgent };
+
+export async function startRalph({ kitDir, projectDir, onTask, onPlannedSlice }) {
+  const local = loadLocalConfig(kitDir);
+
+  console.log(`Ralph — kit: ${kitDir}`);
+  console.log(`         project: ${projectDir}`);
+
+  if (!hasCredentials(local)) {
+    console.log(`         mode: local-only (no platform sync)\n`);
+    await ralphLoop(kitDir, local, onTask, onPlannedSlice);
+    return;
+  }
+
+  const cfg = await retryOn401('fetchPlatformConfig', () => fetchPlatformConfig(local));
+  console.log(`         org=${cfg.organizationId}, board=${cfg.boardId}, base=${cfg.baseUrl}\n`);
+
+  await Promise.all([
+    startRealtimeAgent(cfg, kitDir),
+    ralphLoop(kitDir, cfg, onTask, onPlannedSlice),
+  ]);
+}

package/stacks/axon/templates/build-kit/ralph-claude.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// Ralph loop + realtime agent using Claude Code as the executor.
+// Usage: node ralph-claude.js [project_dir]
+
+import { startRalph, loadLocalConfig } from './lib/ralph.js';
+import { spawn } from 'child_process';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const kitDir = dirname(fileURLToPath(import.meta.url));
+const projectDir = process.argv[2] ? resolve(process.argv[2]) : resolve(kitDir, '..');
+
+const cfg = loadLocalConfig(kitDir);
+const inlineHeader = cfg.boardId
+  ? `board=${cfg.boardId} token=${cfg.token} org=${cfg.organizationId} baseUrl=${cfg.baseUrl}\n\n`
+  : '';
+
+const claudeArgs = ['--dangerously-skip-permissions'];
+if (cfg.model) claudeArgs.push('--model', cfg.model);
+const claudeEnv = cfg.anthropicBaseUrl
+  ? { ...process.env, ANTHROPIC_BASE_URL: cfg.anthropicBaseUrl }
+  : process.env;
+
+function runClaude(prompt) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('claude', [...claudeArgs, '-p', inlineHeader + prompt], {
+      cwd: projectDir,
+      stdio: 'inherit',
+      env: claudeEnv,
+    });
+    proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`Claude exited ${code}`))));
+    proc.on('error', reject);
+  });
+}
+
+startRalph({
+  kitDir,
+  projectDir,
+  onTask: runClaude,
+  onPlannedSlice: runClaude,
+}).catch((err) => {
+  console.error('[ralph] Fatal:', err);
+  process.exit(1);
+});

package/stacks/axon/templates/build-kit/ralph.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# Ralph agent loop — two independent loops, each triggered by their own condition
+#
+# onTask:        tasks.json has entries  → load slice from board, update .build-kit/.slices/
+# onPlannedSlice: .build-kit/.slices/ has a "Planned" slice → build it
+#
+# The loops are NOT causally linked — either can trigger on its own.
+#
+# Usage: ./ralph.sh [iterations] [project_dir]
+#   iterations  — number of loop cycles to run; 0 or omitted means run forever
+#   project_dir — path to the project root; defaults to the parent of .build-kit
+
+set -euo pipefail
+
+KIT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ITERATIONS="${1:-0}"
+PROJECT_DIR="${2:-"$KIT_DIR/.."}"
+TASKS_FILE="$KIT_DIR/tasks.json"
+PROMPT_FILE="$KIT_DIR/lib/prompt.md"
+BACKEND_PROMPT_FILE="$KIT_DIR/lib/backend-prompt.md"
+AGENT_SCRIPT="$KIT_DIR/lib/agent.sh"
+
+HAS_CREDENTIALS=true
+if [[ ! -f "$KIT_DIR/.eventmodelers/config.json" ]]; then
+  echo "[ralph] Note: no .eventmodelers/config.json found — platform sync disabled." >&2
+  echo "        To enable board sync, follow: https://app.eventmodelers.ai/documentation#build-axon" >&2
+  echo "        Code generation from local slice definitions will still run." >&2
+  HAS_CREDENTIALS=false
+fi
+
+echo "Ralph — kit: $KIT_DIR  project: $PROJECT_DIR"
+
+# Returns 0 if tasks.json has at least one task
+has_pending_tasks() {
+  [[ -f "$TASKS_FILE" ]] || return 1
+  local content
+  content=$(cat "$TASKS_FILE")
+  [[ "$content" != "[]" && -n "$content" ]]
+}
+
+# Returns 0 if any JSON under .build-kit/.slices/ contains a "Planned" status
+has_planned_slices() {
+  grep -rqi '"status"[[:space:]]*:[[:space:]]*"planned"' "$KIT_DIR/.slices/" --include='index.json' 2>/dev/null
+}
+
+# Returns the title of the first "Planned" slice, or empty string
+get_planned_slice_title() {
+  for index_file in "$KIT_DIR/.slices/"*/index.json; do
+    [[ -f "$index_file" ]] || continue
+    local title
+    title=$(node -e "
+      try {
+        const d = JSON.parse(require('fs').readFileSync(process.argv[1], 'utf-8'));
+        const s = (d.slices||[]).find(s => (s.status||'').toLowerCase() === 'planned');
+        if (s) process.stdout.write(s.slice || s.id || '');
+      } catch(e) {}
+    " "$index_file" 2>/dev/null)
+    if [[ -n "$title" ]]; then
+      echo "$title"
+      return
+    fi
+  done
+}
+
+# Runs agent.sh with the given prompt; retries on non-zero exit
+run_agent() {
+  local label="$1"
+  local prompt="$2"
+  while true; do
+    echo "[$(date -u +%H:%M:%S)] $label"
+    (cd "$PROJECT_DIR" && bash "$AGENT_SCRIPT" "$prompt") 2>&1 && return 0
+    echo "[$(date -u +%H:%M:%S)] Agent error — retrying in 60s..."
+    sleep 60
+  done
+}
+
+cycle=0
+while [[ "$ITERATIONS" -eq 0 || "$cycle" -lt "$ITERATIONS" ]]; do
+  ran_something=false
+
+  if [[ "$HAS_CREDENTIALS" == true ]] && has_pending_tasks; then
+    run_agent "onTask: loading slice from board..." "$(cat "$PROMPT_FILE")"
+    ran_something=true
+  fi
+
+  if has_planned_slices; then
+    slice_title=$(get_planned_slice_title)
+    run_agent "onPlannedSlice: building \"$slice_title\"..." "$(cat "$BACKEND_PROMPT_FILE")"
+    echo "[$(date -u +%H:%M:%S)] Slice \"$slice_title\" build complete — waiting for next slice"
+    ran_something=true
+  fi
+
+  if [[ "$ran_something" == false ]]; then
+    sleep 3
+  fi
+
+  (( cycle++ )) || true
+done

package/stacks/axon/templates/root/.env.example

@@ -0,0 +1,5 @@
+# Copy this file to .env and fill in your AxonIQ credentials.
+# Get these from https://console.axoniq.io
+AXONIQ_PLATFORM_CREDENTIALS=your-org-id:your-credential-token
+AXONIQ_PLATFORM_AUTHENTICATION=your-org-id-asc:your-authentication-token
+AXONIQ_INSIGHTS_AUTHENTICATION=your-org-id:your-insights-token

package/stacks/axon/templates/root/CLAUDE.md

@@ -0,0 +1,60 @@
+# Project Configuration
+
+Read Events in src/events to understand the global structure.
+
+## File Structure Constraints
+
+- **Strict Path Limitation**: if not instructed otherwise, only check `src/slices/{slicename}/*.ts`
+- **Slice Organization**: Each feature/domain should be organized as a separate slice
+
+## Code Standards
+
+- **Language**: TypeScript only
+- **Module System**: Use ES modules (import/export)
+- **Type Safety**: Ensure all code is properly typed
+
+## Development Guidelines
+
+1. Each slice should be self-contained and focused on a specific domain
+2. Maintain clear separation of concerns within each slice
+3. Follow TypeScript best practices for type definitions and interfaces
+
+Only check src/slices/{slice}/*.ts, do not check subfolders unless explicitely tasked to.
+If not tasked explicitely to change routes, ignore routes*.ts
+
+Ignore case for files and slices in prompts. "CartItems" slice is the same as "cartitems"
+
+Do not change files with tests unless explicitely instructed: *.test.ts
+
+At the start of every session, read `AGENTS.md` if it exists to load accumulated project learnings.
+
+When starting to work on a slice, invoke the `update-slice-status` skill with `InProgress` status before doing anything else.
+
+## Building a Slice
+
+**CRITICAL: You MUST always use the provided skills to build slices. NEVER implement a slice manually.**
+**ALL fields, event names, command names, and business rules MUST come exclusively from slice.json. Do NOT invent, assume, or guess any field or logic not present in the slice definition.**
+
+When asked to build a slice, always follow this flow:
+
+1. Read the slice definition from `.build-kit/.slices/<context>/<slicename>/slice.json`.
+2. Determine the slice type:
+   - **Translation** — `sliceType === "TRANSLATION"` → read `description` and `notes` from slice.json for hints; default to `/build-automation` if nothing else is specified
+   - **Automation** — `processors` array is non-empty → invoke `/build-automation`
+   - **State-view** — `projections` or `queries` array is non-empty → invoke `/build-state-view`
+   - **State-change** — default (has `commands` / `events`) → invoke `/build-state-change`
+3. Invoke the matching skill and follow its instructions completely. Do not deviate.
+4. **Verify against slice.json**: After the skill completes, check that every command field, event field, and specification in slice.json appears in the implementation. No invented fields — if it is not in slice.json, it must not be in the code.
+5. Run quality checks (`./mvnw compile -q`, then the slice tests only).
+6. If checks pass, commit with `feat: [Slice Name]` and set slice status to `Done`.
+
+After you are done, automatically run the tests for the slice that was edited.
+
+## Example Slice Structure
+
+```
+src/slices/
+├── {slice-name}/
+│   ├── CommandHandler.ts
+│   └── routes.ts
+```

package/stacks/axon/templates/root/README.md

@@ -0,0 +1,44 @@
+# Axoniq Platform Quickstart
+
+This simple GiftCard application demonstrates the core concepts of the Axoniq Platform, including Command Handling,
+Event Sourcing, and Projections. It is built using the Axoniq Framework and Spring Boot.
+
+## Prerequisites
+- Java 21 or higher
+- Maven 3.6 or higher
+- Docker (for running the Axon Server)
+- An IDE like IntelliJ IDEA or Eclipse (optional)
+
+## Getting Started
+
+Run docker-compose to start Axon Server:
+
+```bash
+docker-compose up -d
+```
+
+Now, you can run the application using Maven:
+
+```bash
+mvn spring-boot:run
+```
+
+Alternatively, you can run the application from your IDE by running the `QuickstartApplication` class.
+
+## Using the Application
+You can interact with the application via the basic UI available on [http://localhost:8080](http://localhost:8080).
+The events are stored in Axon Server, which you can access at [http://localhost:8024](http://localhost:8024).
+You can run analytics queries using AI on your event store with Axoniq Insights, accessible at [https://localhost:8090](https://localhost:8090).
+
+Your application and Axon Server will both connect to the Axoniq Platform. You can monitor and manage your application from there: [https://monitor.axoniq.io/workspace/e6953958/env/e6953958-0](https://monitor.axoniq.io/workspace/e6953958/env/e6953958-0).
+
+## Useful resources
+
+You can access a lot of resources through the [Axoniq Platform](https://platform.axoniq.io/). This includes:
+
+- Extensive Documentation
+- Axoniq Academy with free courses
+- AI-powered Development Agent to create your applications faster
+- Community Forum to ask questions and share knowledge
+- Monitor your applications
+- And much more!

package/stacks/axon/templates/root/docker-compose.yml

@@ -0,0 +1,64 @@
+services:
+  postgres:
+    image: postgres:17
+    ports:
+      - "5432:5432"
+    environment:
+      - POSTGRES_DB=quickstart
+      - POSTGRES_USER=quickstart
+      - POSTGRES_PASSWORD=quickstart
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U quickstart"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  axon-server:
+    image: axoniq/axonserver:latest-jdk-17
+    ports:
+      - "8024:8024"
+      - "8124:8124"
+      - '8224:8224'
+    hostname: axonserver-1
+    environment:
+      - axoniq_platform_authentication=${AXONIQ_PLATFORM_AUTHENTICATION}
+      - axoniq.axonserver.autocluster.dcb=true
+    volumes:
+      - data:/axonserver/data
+      - events:/axonserver/events
+    networks:
+      - axon-server
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8024/actuator/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  axoniq-insights:
+    image: docker.axoniq.io/axoniq/axoniq-insights:1.0.0
+    ports:
+      - "8090:8080"
+    environment:
+      - insights.platform.authentication=${AXONIQ_INSIGHTS_AUTHENTICATION}
+      - insights.axonserver.routing-servers=axonserver-1:8124
+      - insights.axonserver.auto-subscribe=true
+    depends_on:
+      axon-server:
+        condition: service_healthy
+    networks:
+      - axon-server
+
+
+networks:
+  axon-server:
+
+volumes:
+  data:
+    driver: local
+  events:
+    driver: local
+  postgres-data:
+    driver: local