@eventmodelers/node-kit 0.0.11 → 0.0.12

package/templates/.claude/skills/load-slice/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: load-slice
-description: Load all slices from the board via the slicedata API and return the data for a specific slice by ID or title. Also refreshes the local slices/ directory so each slice is stored as a dedicated JSON file.
+description: Load all slices from the board via the slicedata API and persist them to the .slices/ directory hierarchy (index.json with full definitions, per-slice folders). Returns data for a specific slice by ID or title.
 ---
 
 # Load Slice
@@ -18,7 +18,7 @@ From `$ARGUMENTS`, extract:
 | `sliceId` | UUID of the slice (SLICE_BORDER node ID) | optional — prefer over title |
 | `sliceTitle` | slice title (case-insensitive match) | optional — used if sliceId missing |
 
-If neither is provided, return the full list of all slices without filtering.
+If neither is provided, load and persist all slices without filtering.
 
 ---
 
@@ -32,26 +32,78 @@ curl -s \
   "<BASE_URL>/api/org/<ORG_ID>/boards/<BOARD_ID>/slicedata/slices"
 ```
 
-Response: `{ "slices": [{ "id": "<nodeId>", "title": "<title>", "status": "<status>" }] }`
+Response shape: `{ "slices": [ { "id": "...", "title": "...", "status": "...", "context": "...", ... } ] }`
 
 Save the full array as `ALL_SLICES`.
 
 ---
 
-## Step 3 — Persist each slice as a dedicated file
+## Step 3 — Persist slices to .slices/ directory
 
-For every slice in `ALL_SLICES`, write it to `slices/<id>.json` in the current working directory:
+Apply the following logic for every slice in `ALL_SLICES`.
+
+### Derive paths
+
+- `contextName` = `slice.context` if present, otherwise `"default"` — **preserve original casing** (e.g. `"Beta"`, not `"beta"`)
+- `sliceFolder` = `slice.title` lowercased, with all spaces removed and the prefix `"slice:"` stripped  
+  e.g. `"Beta Enable User for Beta Test"` → `"betaenableuserforbetatest"`
+- `baseFolder` = `.slices/<contextName>/`
+- `sliceDir`   = `.slices/<contextName>/<sliceFolder>/`
+
+### Write files
 
 ```bash
-mkdir -p slices
+mkdir -p ".slices/<contextName>/<sliceFolder>"
 ```
 
-For each slice `s` in `ALL_SLICES`:
-```bash
-echo '<s as JSON>' > slices/<s.id>.json
+**`.slices/current_context.json`** — always overwrite:
+
+```json
+{ "name": "Beta" }
 ```
 
-This keeps the local `slices/` directory in sync with the board state.
+**`.slices/<contextName>/context.json`** — write once per context:
+
+```json
+{ "name": "Beta" }
+```
+
+**`.slices/<contextName>/<sliceFolder>/slice.json`** — the full slice object with the `index` field removed.
+
+### Maintain `.slices/<contextName>/index.json`
+
+Read the file if it exists, otherwise start with `{ "slices": [] }`.
+
+Each entry in `index.json` contains the index metadata **plus** the complete slice definition fetched from the API:
+
+```json
+{
+  "slices": [
+    {
+      "id": "d0dbc70c-f244-4048-886b-1d11e461f466",
+      "slice": "Beta Enable User for Beta Test",
+      "index": 0,
+      "context": "Beta",
+      "folder": "betaenableuserforbetatest",
+      "status": "Created",
+      "definition": {
+        "id": "d0dbc70c-f244-4048-886b-1d11e461f466",
+        "title": "Beta Enable User for Beta Test",
+        "status": "Created",
+        "context": "Beta"
+      }
+    }
+  ]
+}
+```
+
+The `definition` field holds the full object returned by the API for that slice (all fields as-is).
+
+**Merge rules:**
+- If an entry with the same `id` already exists: update all fields and refresh `definition`; preserve any existing `assigned` field.
+- If not found: append the new entry.
+
+Write the updated object back to `.slices/<contextName>/index.json`.
 
 ---
 
@@ -68,19 +120,22 @@ If a specific slice was requested but not found, stop and list the available tit
 ## Step 5 — Output
 
 ```
-Slices loaded: <count> total, persisted to slices/
+Slices loaded: <count> total
+Persisted to: .slices/<contextName>/
 
 Requested slice:
   Title:  <title>
   ID:     <id>
   Status: <status>
+  Folder: .slices/<contextName>/<sliceFolder>/slice.json
 ```
 
 Or if no filter was given:
+
 ```
-All slices (<count>):
-  - <title> [<status>] (<id>)
+All slices (<count>) — context: <contextName>:
+  - <title> [<status>] → .slices/<contextName>/<sliceFolder>/
   - ...
 ```
 
-Make the matched slice's `id`, `title`, and `status` available to subsequent steps in the same session.
+Make the matched slice's `id`, `title`, `status`, and local folder path available to subsequent steps in the same session.

package/templates/realtime-agent/src/index.js

@@ -6,6 +6,16 @@ import { randomUUID } from 'crypto';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+function findRalphShDir(startDir) {
+  let dir = startDir;
+  while (true) {
+    if (existsSync(join(dir, 'ralph.sh'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 function findConfigPath(startDir) {
   let dir = startDir;
   while (true) {
@@ -91,7 +101,7 @@ async function writeTask(payload, cwd) {
 }
 
 async function start() {
-  const claudeCwd = process.argv[2] ?? resolve(process.cwd(), '..');
+  const claudeCwd = process.argv[2] ?? findRalphShDir(process.cwd()) ?? resolve(process.cwd(), '.');
 
   const local = loadLocalConfig();
   const cfg = await fetchPlatformConfig(local);

package/templates/root/.env.example

@@ -0,0 +1,22 @@
+# Supabase
+SUPABASE_URL=https://<project-id>.supabase.co
+SUPABASE_PUBLISHABLE_KEY=<supabase-anon-key>
+SUPABASE_SECRET_KEY=<supabase-service-role-key>
+SUPABASE_DB_URL=postgresql://postgres.<project-id>:<db-password>@aws-1-eu-central-1.pooler.supabase.com:5432/postgres?prepareThreshold=0
+
+# Frontend (Next.js public vars)
+NEXT_PUBLIC_SUPABASE_URL=https://<project-id>.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=<supabase-anon-key>
+
+# Server
+PORT=3000
+API_URL=http://localhost:3000
+BACKEND_URL=http://localhost:3000
+
+# Flyway (database migrations)
+FLYWAY_URL=jdbc:postgresql://aws-1-eu-west-1.pooler.supabase.com:6543/postgres?user=postgres.<project-id>&password=<db-password>
+FLYWAY_USER=postgres.<project-id>
+FLYWAY_PASSWORD=<db-password>
+
+# Optional
+TESTING=false

package/templates/root/Claude.md

@@ -0,0 +1,58 @@
+# Project Configuration
+
+Read Events in src/events to understand the global structure.
+
+## Framework & Styling
+
+- **CSS Framework**: Use Bulma CSS exclusively for all styling
+- **Assumption**: Bulma CSS is already available and imported in the project
+- **Styling Guidelines**:
+    - Use Bulma's utility classes and components
+    - Follow Bulma's naming conventions and class structure
+    - Leverage Bulma's responsive design features
+    - Prefer Bulma components over custom CSS
+
+## 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. Use Bulma's grid system, components, and utilities for all UI-related code
+3. Maintain clear separation of concerns within each slice
+4. Follow TypeScript best practices for type definitions and interfaces
+
+Only check src/slices/{slice}/*.ts, do not check subfolders, if not explicitely tasked to build the UI.
+If not tasked explicitely to change routes, ignore routes*.ts
+
+Ignore case for files and slices in prompts. "CartItems" slice is the same as "cartitemsrun t"
+
+Do not change files with tests unless explicitely instructed: *.test.ts
+
+After you are done, automatically run the tests for the slice that was edited.
+
+## Example Slice Structure
+
+```
+src/slices/
+├── {slice-name}/
+│   ├── CommandHandler.ts
+│   ├── ui/
+│   └── routes.ts
+```
+
+## Bulma Integration Notes
+
+- Utilize Bulma's component library: navbar, cards, buttons, forms, modals, etc.
+- Apply Bulma's spacing utilities: `m-*`, `p-*`, `has-text-*`, `has-background-*`
+- Use Bulma's flexbox utilities for layouts
+- Implement responsive design with Bulma's breakpoint classes
+- Leverage Bulma's color palette and typography classes

package/templates/root/agent.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Runs the AI agent with the given prompt.
+# Usage: ./agent.sh "<prompt>"
+# Override by replacing this script with your own implementation.
+
+set -euo pipefail
+
+PROMPT="${1:-}"
+
+if [[ -z "$PROMPT" ]]; then
+  echo "ERROR: No prompt provided"
+  exit 1
+fi
+
+claude "$PROMPT"

package/templates/root/backend-prompt.md

@@ -0,0 +1,139 @@
+# Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project. You apply your skills to build software slices. You only work on one slice at a time.
+
+The structure defined in the Project-Skills is relevant.
+
+## Your Task
+
+0. Do not read the entire code base. Focus on the tasks in this description.
+1. Read the description at `.slices/index.json` (in the same directory as this file). Every item in status "planned" is a task.
+2. Read the progress log at `progress.txt` (check Codebase Patterns section first)
+3. Make sure you are on the right branch "feature/<slicename>", if unsure, start from main.
+5. Pick the **highest priority** slice where status is "planned" ( case insensitive ). This becomes your PRD. Set the status "InProgress" in the index.json. If no slice has status planned, reply with:
+   <promise>NO_TASKS</promise> and stop. Do not work on other slices.
+6. Pick the slice definition from the project root /.slices in <folder> defined in the prd. Never work on more than one slice per iteration.
+7. A slice can define additional prompts as codegen/backendPrompt. any additional prompts defined in backend are hints for the implementation of the slice and have to be taken into account. If you use the additional prompt, add a line in progress.txt
+7. Define the slice type and load the matching skill. If the processors-array is not empty, it´s an automation slice.
+8. Write a short progress one liner after each step to progress.txt
+9. Analyze and Implement that single slice, make use of the skills in the skills directory, but also your previsously collected
+   knowledge. Make a list TODO list for what needs to be done. Also make sure to adjust the implementation according to the json definition. Carefully inspect events, fields and compare against the implemented slice. JSON is the desired state. ATTENTION: A "planned" task can also be just added specifications. So always look at the slice itself, but also the specifications. If specifications were added in json, which are not on code, you need to add them in code.
+10. The slice in the json is always true, the code follows what is defined in the json
+11. slice is only 'Done' if business logic is implemented as defined in the JSON, APIs are implemented, all scenarios in  JSON are implemented in code and it
+    fulfills the slice.json. There must be no specification in json, that has no equivalent in code.
+12. make sure to write the ui-prompt.md as defined if defined in the skill
+13. Run quality checks ( npm run build, npm run test ) - Attention - it´s enough to run the tests for the slice. Do not run all tests.
+14. even if the slice is fully implemented, run your test-analyzer skill and provide the code-slice.json file as defined in the skill
+15. If checks pass, commit ALL changes with message: `feat: [Slice Name]` and merge back to main as FF merge ( update
+    first )
+16. Update the PRD to set `status: Done` for the completed story.
+17. Append your progress to `progress.txt` after each step in the iteration.
+18. append your new learnings to AGENTS.md in a compressed form, reusable for future iterations. Only add learnings if they are not already there.
+19. Finish the iteration.
+
+## Progress Report Format
+
+APPEND to progress.txt (never replace, always append):
+
+```
+## [Date/Time] - [Slice]
+
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+---
+```
+
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase
+better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section
+at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important
+learnings:
+
+```
+## Codebase Patterns
+- Example: Use `sql<number>` template for aggregations
+- Example: Always use `IF NOT EXISTS` for migrations
+- Example: Export types from actions.ts for UI components
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update AGENTS.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:
+
+1. **Identify directories with edited files** - Look at which directories you modified
+3. **Add valuable learnings that apply to all tasks** to the Agents.md - If you discovered something future developers/agents should know:
+    - API patterns or conventions specific to that module
+    - Gotchas or non-obvious requirements
+    - Dependencies between files
+    - Testing approaches for that area
+    - Configuration or environment requirements
+
+**Examples of good AGENTS.md additions:**
+
+- "When modifying X, also update Y to keep them in sync"
+- "This module uses pattern Z for all API calls"
+- "Tests require the dev server running on PORT 3000"
+- "Field names must match the template exactly"
+
+**Do NOT add:**
+
+- Slice specific implementation details
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+- Task speecific learnings like "- Timesheet approval requires: submitted=true, reverted=false, approved=false, declined=false"
+
+Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work
+
+## Quality Requirements
+
+- ALL commits must pass your project's quality checks (typecheck, lint, test)
+- run 'npm run build'
+- run 'npm run test'
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Skills
+
+Use the provided skills in the skills folder as guidance.
+Update skill definitions if you find an improvement you can make.
+
+## Specifications
+
+For every specification added to the Slice, you need to implement one use executable Specification in Code.
+
+A Slice is not complete if specifications are missing or can´t be executed.
+
+## Stop Condition
+
+After completing a user story, check if ALL slices have `status: Done`.
+
+If ALL stories are complete and passing, reply with:
+<promise>COMPLETE</promise>
+
+If there are no stories with `status: Planned` (but not all are Done), reply with:
+<promise>NO_TASKS</promise>
+
+If there are still stories with `status: Planned`, end your response normally (another iteration will pick up the next
+story).
+
+## Important
+
+- Work on ONE slice per iteration
+- Commit frequently
+- update progress.txt frequently
+- Read the Codebase Patterns section in progress.txt before starting
+
+## When an iteration completes
+
+Use all the key learnings from the project.txt and update the Agends.md file with those learning.

package/templates/root/flyway.conf

@@ -0,0 +1,17 @@
+# Flyway configuration file
+# Database connection from .env file
+flyway.url=${FLYWAY_URL}
+flyway.user=${FLYWAY_USER}
+flyway.password=${FLYWAY_PASSWORD}
+
+# Migration files location
+flyway.locations=filesystem:./supabase/migrations
+
+# Default schema (Flyway will create flyway_schema_history table here)
+flyway.schemas=public
+
+# Placeholder replacement
+flyway.placeholderReplacement=false
+
+# Validate on migrate
+flyway.validateOnMigrate=true

package/templates/root/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "project",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "flyway:migrate": "dotenv -e .env -- flyway -baselineOnMigrate=true migrate",
+    "dev": "node --env-file=.env --require ts-node/register server.ts",
+    "build": "tsc",
+    "start": "NODE_ENV=production node --env-file=.env --require ts-node/register server.ts",
+    "test": "tsx --test 'src/**/*.test.ts'"
+  },
+  "dependencies": {
+    "@event-driven-io/emmett": "^0.42.1-alpha.1",
+    "@event-driven-io/emmett-expressjs": "^0.42.1-alpha.1",
+    "@event-driven-io/emmett-postgresql": "^0.42.1-alpha.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@resvg/resvg-js": "^2.6.2",
+    "@supabase/ssr": "^0.10.0",
+    "@supabase/supabase-js": "^2.100.1",
+    "cookie-parser": "^1.4.7",
+    "cors": "^2.8.6",
+    "express": "^4.18.2",
+    "glob": "^11.0.3",
+    "isomorphic-git": "^1.37.6",
+    "jose": "^6.2.3",
+    "knex": "^3.1.0",
+    "multer": "^2.1.1",
+    "node-cron": "^4.2.1",
+    "pg": "^8.17.2",
+    "sharp": "^0.34.5",
+    "simple-git": "^3.36.0",
+    "swagger-jsdoc": "^6.2.8",
+    "swagger-ui-express": "^5.0.1",
+    "url": "^0.11.4"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3",
+    "@testcontainers/postgresql": "^11.0.3",
+    "@types/cors": "^2.8.19",
+    "@types/express": "^4.17.21",
+    "@types/multer": "^2.1.0",
+    "@types/node": "^20",
+    "@types/swagger-jsdoc": "^6.0.4",
+    "@types/swagger-ui-express": "^4.1.8",
+    "dotenv-cli": "^11.0.0",
+    "eslint": "^9",
+    "sql-formatter": "^15.7.0",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.20.3",
+    "typescript": "^5"
+  }
+}

package/templates/root/ralph.sh

@@ -1,7 +1,12 @@
 #!/bin/bash
-# Eventmodelers agent loop — processes tasks.json indefinitely
+# Ralph agent loop — two independent phases, each triggered by their own condition
+#
+# Phase 1: tasks.json has entries  → load slice from board, update .slices/
+# Phase 2: .slices/**/index.json has a "Planned" slice → build it
+#
+# The phases are NOT causally linked — either can trigger on its own.
+#
 # Usage: ./ralph.sh [project_dir]
-#   project_dir defaults to the directory containing this script (the project root)
 
 set -euo pipefail
 
@@ -9,39 +14,55 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_DIR="${1:-"$SCRIPT_DIR"}"
 TASKS_FILE="$PROJECT_DIR/tasks.json"
 PROMPT_FILE="$PROJECT_DIR/prompt.md"
-MODEL_FILE="$PROJECT_DIR/model.md"
+BACKEND_PROMPT_FILE="$PROJECT_DIR/backend-prompt.md"
+AGENT_SCRIPT="$PROJECT_DIR/agent.sh"
 
 if [[ ! -f "$PROJECT_DIR/.eventmodelers/config.json" ]]; then
   echo "ERROR: No .eventmodelers/config.json found in $PROJECT_DIR"
   exit 1
 fi
 
-if [[ ! -f "$MODEL_FILE" ]]; then
-  echo "ERROR: No model.md found in $PROJECT_DIR"
-  exit 1
-fi
+echo "Ralph — project: $PROJECT_DIR"
 
-CLAUDE_CMD=$(head -1 "$MODEL_FILE" | tr -d '\r\n')
+# 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" ]]
+}
 
-echo "Starting agent loop — project: $PROJECT_DIR"
-echo "Using command: $CLAUDE_CMD"
+# Returns 0 if any index.json under .slices/ contains a "Planned" slice
+has_planned_slices() {
+  grep -rqi '"status"[[:space:]]*:[[:space:]]*"planned"' "$PROJECT_DIR/.slices/" 2>/dev/null
+}
 
-# ------------------------------------------------------------
-# Main loop — runs indefinitely
-# ------------------------------------------------------------
-while true; do
-  # ---- Run Claude in the project root --------------------
+# Runs agent.sh with the given prompt; retries on non-zero exit
+run_agent() {
+  local label="$1"
+  local prompt="$2"
   while true; do
-    (cd "$PROJECT_DIR" && $CLAUDE_CMD "$(cat "$PROMPT_FILE")") 2>&1
-    EXIT_CODE=$?
-    if [[ $EXIT_CODE -eq 0 ]]; then
-      break
-    else
-      echo
-      echo "Claude exited with an error. Waiting 1 minute before retry..."
-      sleep 60
-    fi
+    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
+}
+
+while true; do
+  ran_something=false
+
+  if has_pending_tasks; then
+    run_agent "Phase 1: loading slice from board..." "$(cat "$PROMPT_FILE")"
+    ran_something=true
+  fi
+
+  if has_planned_slices; then
+    run_agent "Phase 2: building slice..." "$(cat "$BACKEND_PROMPT_FILE")"
+    ran_something=true
+  fi
 
-  sleep 2
-done
+  if [[ "$ran_something" == false ]]; then
+    sleep 3
+  fi
+done