Merge branch 'develop' into AI-1153

Author: dbarkowsky

.claude/skills/requirements-refiner/SKILL.md

@@ -17,14 +17,13 @@ description: "Requirements Refiner: Iteratively questions the user to clarify va
 - This document should include the initial requirements plus all details gathered during the Q&A process.
 - Ensure the output is structured and ready for a User Story writer to consume.
 4. **Save to feature-docs**:
-- Examine the `feature-docs/` directory to find the highest numbered folder (e.g., `001-graph-workflows`).
-- Determine the next increment number (e.g., if `001` exists, use `002`).
+- Generate a datetime stamp in the format `YYYYMMDDHHmmss` (same format as Prisma migrations) using the current UTC time.
 - Generate a short feature name/slug (kebab-case, e.g., "benchmarking-system").
-- Create a new folder: `feature-docs/{NNN}-{feature-slug}/` (e.g., `feature-docs/002-benchmarking-system/`).
+- Create a new folder: `feature-docs/{YYYYMMDDHHmmss}-{feature-slug}/` (e.g., `feature-docs/20260313143022-benchmarking-system/`).
 - Save the consolidated requirements as `REQUIREMENTS.md` in that folder.
 
 ## Key Behaviors
 - **Iterative Approach**: Do not rush to the final output. Prioritize clarity over speed.
 - **Probe Deeply**: Ask about edge cases, error states, and user roles.
-- **Auto-increment Folders**: Always check existing feature-docs folders to determine the next number.
-- **Output Format**: The final output must be saved as `feature-docs/{NNN}-{feature-slug}/REQUIREMENTS.md`.
+- **Datetime-stamped Folders**: Use the current UTC time in `YYYYMMDDHHmmss` format as the folder prefix.
+- **Output Format**: The final output must be saved as `feature-docs/{YYYYMMDDHHmmss}-{feature-slug}/REQUIREMENTS.md`.

.claude/skills/story-implementer/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: story-implementer
+description: "Implements user stories from a user_stories directory in dependency order using subagents. Reads README.md to find the next unchecked story, spawns Agent tool subagents to implement each one, tracks progress via scenario checkboxes in story files and story checkboxes in README. Trigger phrases: implement stories, implement user stories, story implementer, work on stories, implement next story. Do NOT invoke for: writing user stories (use write-user-stories), general code changes, checklist execution."
+---
+
+Implement user stories from: $ARGUMENTS
+
+**Role**: You are an implementation orchestrator. You read a user stories README.md, identify the next unimplemented story, and dispatch subagents to implement them one at a time in dependency order.
+
+## Input
+
+$ARGUMENTS should be a path to either:
+- A `user_stories/README.md` file, OR
+- A `user_stories/` directory (read README.md inside it), OR
+- A feature-docs directory containing a `user_stories/` subfolder
+
+If no argument is provided, look for the most recently modified directory under `feature-docs/` that contains `user_stories/README.md`.
+
+## Orchestration Algorithm
+
+### Step 1: Read README.md and locate context
+
+1. Read the `user_stories/README.md` file
+2. Extract the path to the requirements document from the NOTE line at the top
+3. Identify the base directory (the parent of `user_stories/`)
+
+### Step 2: Find the next unchecked story
+
+1. Go to the "Suggested Implementation Order" section
+2. Find the first line matching `- [ ] **US-XXX**`
+3. Extract the story ID (e.g., `US-001`)
+4. If no unchecked stories remain, report completion to the user and stop
+
+### Step 3: Read the story file and assess size
+
+1. Find the story file matching the ID in the `user_stories/` directory (e.g., `US-001-*.md`)
+2. Read the story file
+3. Count the number of `- [ ]` scenario checkboxes in the Acceptance Criteria section
+4. Decide the implementation strategy:
+   - **8 or fewer unchecked scenarios**: Send ALL to a single subagent
+   - **More than 8 unchecked scenarios**: Split into batches of 4-6 scenarios, send to sequential subagents
+
+### Step 4: Dispatch subagent(s)
+
+Read the workflow template from `.claude/skills/story-implementer/Workflows/implement-story.md` and construct the subagent prompt by substituting the variables.
+
+Use the **Agent tool** to spawn the subagent. Pass the constructed prompt as the `prompt` parameter.
+
+**For a single subagent (all scenarios fit):**
+- Pass the full story file content
+- Pass the requirements document path
+- Pass the list of ALL scenario numbers to implement
+- Pass the story file path (so subagent can check off scenarios)
+
+**For batched scenarios:**
+- For each batch:
+  - Pass the full story file content
+  - Pass the requirements document path
+  - Pass the specific scenario numbers for THIS batch only (e.g., "Scenarios 1-4")
+  - Pass the story file path
+  - Add batch note: "This is batch N of M. Only implement the specified scenarios."
+  - After each batch subagent completes, re-read the story file to verify the scenarios were checked off
+  - Then dispatch the next batch
+
+### Step 5: Verify story completion
+
+After the subagent(s) finish:
+1. Re-read the story file
+2. Verify ALL scenario checkboxes are `[x]`
+3. If any scenarios remain unchecked, report which ones to the user and ask whether to retry or skip
+
+### Step 6: Mark story complete and commit
+
+1. In `user_stories/README.md`, change the line `- [ ] **US-XXX**` to `- [x] **US-XXX**`
+2. Stage all changes and commit with message: `feat: implement US-XXX - <story title>`
+   - Include `Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>`
+3. Report to the user: which story was completed, summary of what was implemented
+
+### Step 7: Loop
+
+Return to Step 2 to find the next unchecked story. Continue until all stories are implemented or the user interrupts.
+
+## Rules
+
+- Implement stories strictly in the order listed in the README (respect dependency chain)
+- Never skip a story without user approval
+- Always re-read README.md fresh before each iteration (it may have been modified)
+- Each subagent MUST follow all CLAUDE.md rules (tests for backend, proper typing, no placeholders, update docs-md)
+- Auto-commit after each STORY (not each scenario)
+- If a subagent encounters a question or ambiguity, it should surface it to the user rather than making assumptions
+- Do not modify the story file format beyond checking off scenario checkboxes
+- The orchestrator never implements code directly — always delegate to subagents via Agent tool
+
+## Workflow Reference
+
+- [Implement a single story](Workflows/implement-story.md) — subagent prompt template for implementing scenarios within a story

.claude/skills/story-implementer/Workflows/implement-story.md

@@ -0,0 +1,76 @@
+# Implement Story Scenarios
+
+This workflow is used by the story-implementer orchestrator. The orchestrator reads this file and substitutes the variables below before passing to the Agent tool.
+
+## Subagent Prompt Template
+
+The Agent tool should be invoked with a prompt constructed as follows:
+
+---
+
+You are implementing a user story for this project. Follow ALL rules in CLAUDE.md strictly.
+
+### Your Assignment
+
+**Story**: {STORY_ID} - {STORY_TITLE}
+
+**Scenarios to implement**: {SCENARIO_LIST}
+
+**Story file path**: {STORY_FILE_PATH}
+
+**Requirements document**: Read the requirements at {REQUIREMENTS_PATH} for full context.
+
+### Story Content
+
+{FULL_STORY_FILE_CONTENT}
+
+### Implementation Instructions
+
+1. Read the requirements document at {REQUIREMENTS_PATH} for full project context
+2. Read CLAUDE.md for project rules you must follow
+3. For each scenario in your assignment:
+   a. Read the Given/When/Then carefully
+   b. Explore the codebase to understand where changes are needed
+   c. Implement the scenario fully (no stubs, no placeholders)
+   d. For backend changes: create/update tests and run them (`npm run test` from the relevant app directory)
+   e. For frontend changes: run typecheck (`npm run typecheck`)
+   f. After the scenario is fully working, edit {STORY_FILE_PATH} and change that scenario's `- [ ]` to `- [x]`
+4. After all assigned scenarios are complete, provide a summary of:
+   - Files created or modified
+   - Tests added or updated
+   - Any gaps or questions that came up (per CLAUDE.md: do not assume, report gaps)
+
+### Rules You Must Follow
+
+- Implement ONLY the scenarios assigned to you, not others
+- Check off EACH scenario in the story file as you complete it (change `- [ ]` to `- [x]`)
+- Do NOT modify the README.md (the orchestrator handles that)
+- Do NOT commit (the orchestrator handles commits)
+- Follow all CLAUDE.md rules: no "any" types, no placeholders, create tests for backend, update docs-md, no document-specific implementations
+- If you need to run `npx prisma generate`, use `npm run db:generate` from `apps/backend-services`
+- If something is ambiguous or unclear, stop and ask the user rather than guessing
+- Do not add backwards compatibility features
+- The system is generic and must support arbitrary workloads
+
+{BATCH_NOTE}
+
+---
+
+## Variable Reference
+
+| Variable | Source |
+|----------|--------|
+| STORY_ID | Extracted from story filename (e.g., US-001) |
+| STORY_TITLE | First heading in story file |
+| SCENARIO_LIST | "All scenarios" or "Scenarios 1-4" etc. |
+| STORY_FILE_PATH | Absolute path to the story .md file |
+| REQUIREMENTS_PATH | Extracted from README.md NOTE line |
+| FULL_STORY_FILE_CONTENT | Complete contents of the story .md file |
+| BATCH_NOTE | Empty string for single subagent, or "This is batch N of M. Only implement the specified scenarios. Check off each scenario as you complete it." for batched |
+
+## Common Pitfalls
+
+- Forgetting to check off scenarios in the story file — the orchestrator relies on these checkboxes to verify completion
+- Committing changes — the subagent must NOT commit; the orchestrator does this after verifying all scenarios
+- Modifying README.md — the subagent must NOT touch the README; only the orchestrator updates it
+- Making assumptions about unclear requirements — always surface questions to the user

.claude/skills/write-user-stories/SKILL.md

@@ -12,6 +12,9 @@ Generate user stories from: $ARGUMENTS
 2.  **Decompose**: Break the requirements down into individual, independent User Stories.
 3.  **Draft**: Write each User Story using the strictly defined template at `.claude/skills/write-user-stories/user_story_template.md`.
     - Ensure each story has a clear Title, Description, and Acceptance Criteria.
+    - **Keep each story to 4-6 acceptance criteria scenarios maximum.** If a requirement naturally produces more than 6 scenarios, split it into multiple stories (e.g., sequential US numbers) preserving full detail across the split. Never sacrifice detail — distribute it across more stories instead.
+    - Each scenario must be independently implementable — a scenario's Given/When/Then should not depend on another scenario within the same story being implemented first. Cross-story dependencies are captured in the phase ordering.
+    - Ensure scenario checkboxes use exactly the format `- [ ] **Scenario N**: Title` (with the space inside brackets and bold scenario label) for consistent automated parsing.
     - Organize stories into logical phases/groups based on dependencies and priority.
 4.  **Output**:
     - Create a `user_stories` subfolder **in the same directory as the requirements file**.
@@ -67,6 +70,10 @@ After implementing the user story check it off at the bottom of this file
 ### Phase 2
 - [ ] **US-002** (brief description)
 - [ ] **US-003** (brief description)
+
+> Stories are ordered by dependency chain for automated implementation.
+> Each story should be implementable after all stories in previous phases are complete.
+> Do not start a phase until all stories in prior phases are checked off.
 ```
 
 ## Key Behaviors
@@ -75,3 +82,6 @@ After implementing the user story check it off at the bottom of this file
 - **Same Directory Organization**: Create the `user_stories` subfolder in the same directory as the requirements file.
 - **Comprehensive README**: Always generate the README.md with complete phase breakdown and tracking checkboxes.
 - **Logical Phases**: Organize implementation phases based on technical dependencies and priorities from the requirements.
+- **Scenario Size Limit**: Keep each story to 4-6 acceptance criteria scenarios maximum. If a requirement naturally has more, split into multiple stories preserving full detail — never sacrifice detail, distribute it across more stories.
+- **Atomic Scenarios**: Each scenario must be independently implementable within its story. No intra-story scenario dependencies.
+- **Consistent Checkbox Format**: Scenario checkboxes must use exactly `- [ ] **Scenario N**: Title` for automated parsing by the story-implementer skill.

.claude/skills/write-user-stories/user_story_template.md

@@ -5,6 +5,7 @@
 **So that** [Benefit/Value].
 
 ## Acceptance Criteria
+<!-- Keep to 4-6 scenarios max. Each scenario should be independently implementable. -->
 - [ ] **Scenario 1**: [Title]
     - **Given** [Context]
     - **When** [Action]

.github/workflows/build-instance-images.yml

@@ -0,0 +1,114 @@
+name: Build Instance Images
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch to build images from (defaults to the branch the workflow is triggered on)"
+        required: false
+        type: string
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_BASE: ghcr.io/${{ github.repository }}
+
+jobs:
+  metadata:
+    name: Prepare Build Metadata
+    runs-on: ubuntu-latest
+    outputs:
+      sanitized-branch: ${{ steps.branch-info.outputs.sanitized }}
+      commit-sha: ${{ steps.branch-info.outputs.sha }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.branch || github.ref }}
+
+      - name: Compute branch name and SHA
+        id: branch-info
+        run: |
+          # Resolve the branch name from inputs or the current ref
+          RAW_BRANCH="${{ inputs.branch || github.ref_name }}"
+
+          # Sanitize for container image tags: lowercase, replace non-alphanumeric
+          # sequences with a single hyphen, trim leading/trailing hyphens,
+          # and truncate to 128 characters (OCI tag length limit)
+          SANITIZED=$(echo "$RAW_BRANCH" \
+            | tr '[:upper:]' '[:lower:]' \
+            | sed 's/[^a-z0-9._-]/-/g' \
+            | sed 's/--*/-/g' \
+            | sed 's/^-//;s/-$//' \
+            | cut -c1-128)
+
+          SHA=$(git rev-parse HEAD)
+
+          echo "sanitized=$SANITIZED" >> "$GITHUB_OUTPUT"
+          echo "sha=$SHA" >> "$GITHUB_OUTPUT"
+          echo "Branch: $RAW_BRANCH -> Tag: $SANITIZED"
+          echo "Commit SHA: $SHA"
+
+  build:
+    name: Build ${{ matrix.service }}
+    needs: [metadata]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - service: backend-services
+            context: "."
+            dockerfile: apps/backend-services/Dockerfile
+          - service: frontend
+            context: apps/frontend
+            dockerfile: apps/frontend/Dockerfile
+          - service: temporal
+            context: "."
+            dockerfile: apps/temporal/Dockerfile
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.branch || github.ref }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GitHub Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Cache Docker layers
+        uses: actions/cache@v4
+        with:
+          path: /tmp/.buildx-cache
+          key: ${{ runner.os }}-buildx-instance-${{ matrix.service }}-${{ github.sha }}
+          restore-keys: |
+            ${{ runner.os }}-buildx-instance-${{ matrix.service }}-
+
+      - name: Build and push image
+        uses: docker/build-push-action@v5
+        with:
+          context: ${{ matrix.context }}
+          file: ${{ matrix.dockerfile }}
+          push: true
+          tags: |
+            ${{ env.IMAGE_BASE }}/${{ matrix.service }}:${{ needs.metadata.outputs.sanitized-branch }}
+            ${{ env.IMAGE_BASE }}/${{ matrix.service }}:${{ needs.metadata.outputs.commit-sha }}
+          labels: |
+            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
+            org.opencontainers.image.revision=${{ needs.metadata.outputs.commit-sha }}
+          cache-from: type=local,src=/tmp/.buildx-cache
+          cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
+
+      - name: Rotate cache
+        run: |
+          rm -rf /tmp/.buildx-cache
+          mv /tmp/.buildx-cache-new /tmp/.buildx-cache

.gitignore

@@ -15,3 +15,7 @@ feature-docs/*/playwright/screenshots/
 # Backend logs
 apps/backend-services/backend.log
 /packages/logging/dist
+
+# OpenShift deployment tooling
+.oc-deploy-token
+backups/