@rashidee/co2 1.3.7 → 1.3.9

package/plugin/skills/conductor-feature-develop/SKILL.md

@@ -1,1383 +1,1384 @@
----
-name: conductor-feature-develop
-model: claude-sonnet-5
-effort: high
-description: >
-  Application development orchestrator — orchestrates full-stack code implementation
-  module-by-module (code + Playwright E2E tests), tracking progress in IMPLEMENTATION_MASTER.md
-  and per-module IMPLEMENTATION_MODULE.md. Takes an application name (mandatory), with optional
-  source code path, version and module filters. Version supports single version, comma-separated
-  list, "all", or omit for all versions. When multiple versions are resolved, they are processed
-  SEQUENTIALLY in ascending semver order — all modules for version N are fully implemented before
-  version N+1 begins. Requires context artifacts (module models, HTML mockups, technical
-  specifications, test specifications) to already exist — use "conductor-feature-prepare" first
-  if they don't. Use this skill when the user asks to "implement the application", "start
-  development", "build the app module by module", "orchestrate implementation", "develop from
-  specs", "implement from test specs", or any request to systematically develop a full application
-  from existing specs. Also trigger when user says "resume implementation" to continue from where
-  a previous session left off using IMPLEMENTATION_MASTER.md and IMPLEMENTATION_MODULE.md
-  progress files.
----
-
-# Feature Conductor — Develop
-
-Application development orchestrator — implements full-stack code module-by-module, driven by
-test specs and tracked via implementation checklists. Requires context artifacts to already
-exist (use `conductor-feature-prepare` first).
-
-## Ralph Loop Integration (AUTO-START — MANDATORY)
-
-This skill AUTOMATICALLY starts a Ralph Loop to ensure complete implementation across all modules.
-Without Ralph Loop, the implementation may stop prematurely due to context window limits, API
-usage limits, or the agent incorrectly concluding work is "done enough". Ralph Loop ensures
-the same prompt is re-fed after each session exit, and the agent picks up where it left off
-using the IMPLEMENTATION_MASTER.md and IMPLEMENTATION_MODULE.md tracking files.
-
-### FIRST ACTION: Start Ralph Loop
-
-**BEFORE doing anything else** (before Phase 0, before reading any files), you MUST invoke the
-Ralph Loop skill using the Skill tool. This is a blocking requirement — do NOT proceed with
-any implementation work until Ralph Loop is active.
-
-**Invoke this immediately:**
-```
-Skill(skill: "ralph-loop:ralph-loop", args: "/conductor-feature-develop <application> [source:<source-code-path>] [version:<version>] [module:<module>] --completion-promise \"ALL MODULES IMPLEMENTED\" --max-iterations 100")
-```
-
-Replace `<application>` and optional arguments with the actual arguments provided by the user.
-
-**Example:** If the user invokes:
-```
-/conductor-feature-develop mainapp
-```
-
-Then invoke:
-```
-Skill(skill: "ralph-loop:ralph-loop", args: "/conductor-feature-develop mainapp --completion-promise \"ALL MODULES IMPLEMENTED\" --max-iterations 100")
-```
-
-If the user provides optional arguments:
-```
-/conductor-feature-develop mainapp version:v2 module:user
-```
-
-Then invoke:
-```
-Skill(skill: "ralph-loop:ralph-loop", args: "/conductor-feature-develop mainapp version:v2 module:user --completion-promise \"ALL MODULES IMPLEMENTED\" --max-iterations 100")
-```
-
-After Ralph Loop is active, proceed with Phase 0 (Resume Check) and continue normally.
-
-### How It Works
-
-1. This skill auto-starts a Ralph Loop with the orchestrator prompt as the loop body
-2. On each iteration, the agent reads IMPLEMENTATION_MASTER.md to find the next pending module
-3. The agent implements one or more modules until context runs out or a module completes
-4. When the agent tries to exit, the Ralph Loop stop hook re-feeds the same prompt
-5. The next iteration resumes from where the last one left off (tracked in IMPLEMENTATION_MASTER.md)
-6. When ALL modules are COMPLETED, the agent outputs the completion promise to exit the loop
-
-### Completion Promise
-
-When ALL modules in IMPLEMENTATION_MASTER.md have status `COMPLETED`, output the following
-promise tag to signal the Ralph Loop that implementation is finished:
-
-```
-<promise>ALL MODULES IMPLEMENTED</promise>
-```
-
-**CRITICAL**: Only output this promise when EVERY module in the execution order has:
-- Status = COMPLETED in IMPLEMENTATION_MASTER.md
-- All E2E tests passing
-- IMPLEMENTATION_MODULE.md fully updated
-
-Do NOT output the promise prematurely. Do NOT output it to escape the loop. The Ralph Loop
-will verify this tag and only exit when it is present.
-
-### Iteration Awareness
-
-At the START of every iteration (including the first), the agent MUST:
-1. Check if Ralph Loop is already active (if `.claude/ralph-loop.local.md` exists, skip re-invoking)
-2. Read IMPLEMENTATION_MASTER.md to determine what is already completed
-3. Find the FIRST module with status != COMPLETED
-4. If that module has an IMPLEMENTATION_MODULE.md, read it to find the last incomplete step
-5. Resume from exactly that point — do NOT re-implement completed work
-6. If ALL modules are COMPLETED, output the completion promise and stop
-
-### Never Stop Prematurely
-
-Within a Ralph Loop iteration, the agent MUST:
-- Continue implementing modules sequentially until context limits force a stop
-- After completing one module, IMMEDIATELY start the next pending module
-- Do NOT stop after a single module "to let the user review" — Ralph Loop handles iteration
-- Do NOT output the completion promise until ALL modules are verified complete
-- If approaching context limits mid-module, save progress to IMPLEMENTATION_MODULE.md so the
-  next iteration can resume from the exact step
-
-## Inputs
-
-The skill expects these arguments:
-
-```
-/conductor-feature-develop <application> [source:<source-code-path>] [version:<version>] [module:<module>]
-```
-
-| Argument | Required | Example | Description |
-|----------|----------|---------|-------------|
-| `<application>` | Yes | `mainapp` | Application name to locate the context folder |
-| `source:<path>` | No | `source:mainapp` | Path where source code resides. Defaults to `<app_folder>` (same as the resolved application folder) |
-| `version:<version>` | No | `version:v2` or `version:v1,v2` or `version:all` | Filter user stories and artifacts by version. Supports single version, comma-separated list, `all`, or omit for all versions. Multiple versions are processed sequentially in ascending semver order |
-| `module:<module>` | No | `module:user` | If provided, process only this module. If omitted, process all modules |
-
-### Input Resolution
-
-The application name is matched against root-level application folders:
-1. Strip any leading `<number>_` prefix from folder names (e.g., `1_hub_middleware` → `hub_middleware`)
-2. Match case-insensitively against the provided application name
-3. Accept snake_case, kebab-case, or title-case input
-4. If no match found, list available applications and stop
-
-### Auto-Resolved Paths
-
-| File | Resolved Path |
-|------|---------------|
-| PRD.md | `<app_folder>/context/PRD.md` |
-| Module Models | `<app_folder>/context/model/` |
-| HTML Mockups | `<app_folder>/context/mockup/` |
-| Specifications | `<app_folder>/context/specification/` |
-| Test Specs | `<app_folder>/context/test/` |
-| References | `<app_folder>/context/reference/` |
-| Development Output | `<app_folder>/context/develop/` |
-
-### Version Resolution
-
-The `version:` argument supports four forms:
-
-| Form | Example | Behavior |
-|------|---------|----------|
-| Single version | `version:v2` | Process only v2 |
-| Comma-separated list | `version:v1,v2,v3` | Process each version sequentially in ascending semver order |
-| Explicit all | `version:all` | Discover all versions from PRD.md, process sequentially in ascending semver order |
-| Omitted | _(no version arg)_ | Same as `version:all` |
-
-#### Version Discovery
-
-When `version:all` or omitted:
-1. Scan PRD.md for all `[vX.Y.Z]` version tags across all module sections
-2. Collect unique versions
-3. Sort in ascending semantic version order (v1.0.0 < v1.0.1 < v1.1.0 < v2.0.0)
-4. This becomes the ordered version list for sequential processing
-
-#### Sequential Version Processing Rule
-
-**Versions are ALWAYS processed one at a time, in ascending semver order.** All modules for
-version N must be fully implemented (status `COMPLETED`) before version N+1 begins. This ensures:
-- The application is scaffolded and fully functional at version N before N+1 changes are layered on
-- Feature implementations build incrementally on prior version work
-- E2E tests validate each version's functionality before the next version modifies the codebase
-
-#### How It Works with Multiple Versions
-
-1. **First version** (e.g., v1.0.0): Full implementation — scaffolding (Phase 2) + all modules (Phase 3)
-2. **Each subsequent version** (e.g., v1.0.1, v1.0.2): Version increment — reset affected modules
-   to PENDING, update the application version, then re-implement only modules with changes for
-   that version. The existing "Version Increment" logic in Phase 0 handles this naturally.
-3. **README** (Phase 5): Generated ONCE after the LAST version in the list is fully
-   implemented
-
-### Application Folder Structure (Expected)
-
-Source code and context artifacts coexist in the same `<app_folder>`. The `context/` subfolder
-holds all generated artifacts (models, mockups, specs, tests, tracking). All other files and
-folders at the root of `<app_folder>` are **source code** (e.g., `app/`, `Modules/`, `resources/`,
-`composer.json`, `pom.xml`, `src/`, etc.).
-
-**CRITICAL**: When scaffolding a new project (e.g., `composer create-project`, `mvn archetype:generate`),
-the source code MUST be placed directly in `<source-code-path>/` — NOT in a nested subdirectory.
-For example, with `composer create-project laravel/laravel`, you must either:
-- Create in a temp directory and move all files (including dotfiles) up to `<source-code-path>/`, OR
-- Use a technique that installs directly into the existing directory
-
-The `context/` folder already exists in `<app_folder>` and must NOT be overwritten or deleted.
-
-```
-<app_folder>/                      # = <source-code-path> (by default)
-  context/                         # Context artifacts (NOT source code)
-    PRD.md
-    model/
-      MODEL.md
-      <module-slug>/
-        model.md
-        schemas.json
-        document-model.mermaid
-    mockup/
-      MOCKUP.html
-      mockup-manifest.json
-      <role>/content/
-    specification/
-      SPECIFICATION.md
-      <module-slug>/SPEC.md
-    test/
-      TEST_PLAN.md
-      <module-slug>/TEST_SPEC.md
-    reference/
-    develop/                       # Implementation tracking files
-  (source code files)              # All other files are source code
-    app/                           # Laravel: app directory
-    Modules/                       # Laravel: nwidart modules
-    resources/                     # Laravel: views, CSS, JS
-    routes/                        # Laravel: route files
-    config/                        # Laravel: config files
-    composer.json                  # Laravel: PHP dependencies
-    package.json                   # Laravel: JS dependencies
-    ...                            # (or src/, pom.xml for Spring Boot, etc.)
-```
-
-## Pre-Requisite: Project Information from CLAUDE.md (MANDATORY)
-
-**CLAUDE.md is automatically loaded into context** at the start of every session. It contains
-project details, infrastructure paths, credentials, and configuration. You do NOT need to read
-it manually — the information is already available in your context.
-
-**Before executing ANY tool command** (Maven build, Spring Boot run, database CLI, Keycloak CLI,
-Playwright test, npm start, etc.), use the following from CLAUDE.md (already in context):
-
-- **JDK path** — Use the exact `JAVA_HOME` path specified in CLAUDE.md
-- **Maven path** — Use the exact Maven binary path specified in CLAUDE.md
-- **Database credentials** — Host, port, username, password for MongoDB, MySQL, etc.
-- **Message queue credentials** — RabbitMQ host, port, username, password
-- **Keycloak configuration** — Host, admin credentials, CLI path
-- **Mailcatcher configuration** — SMTP host/port, web UI URL
-- **Any other infrastructure details** — Ports, URLs, connection strings
-
-**WHY**: CLAUDE.md contains the actual system paths, credentials, and configuration for the
-developer's machine. Hardcoding or guessing these values will cause commands to fail. Every shell
-command that involves JDK, Maven, database access, or any external service MUST use the values
-from CLAUDE.md.
-
-## PRD.md Extended Sections
-
-During implementation, check PRD.md for the following extended sections and use them as high-level context:
-
-### Design System
-
-If PRD.md contains a `# Design System` section, read it and any file it references (e.g., `[DESIGN_SYSTEM.md](reference/DESIGN_SYSTEM.md)`) before implementing **any UI module** (Blade views, JTE templates, React components, etc.). Treat the design system as the **authoritative source** for code-level styling:
-
-- **Color tokens, typography, spacing, radii, shadows** — apply directly in Tailwind config, CSS variables, or MUI theme. Do not invent new values.
-- **Component patterns** — buttons, forms, tables, dialogs, alerts must match the design system's visual rules and accessibility behavior.
-- **Branding** — logos, favicons, and brand voice must be applied consistently across all rendered views.
-- **Accessibility rules** — WCAG level, contrast ratios, focus states, keyboard navigation requirements declared in the design system are non-negotiable.
-
-**Conflict resolution**: If `SPECIFICATION.md`'s "Design System Integration" subsection contradicts the PRD.md design system file (e.g., different color values, different component variants), the **PRD.md design system file wins**. Flag the discrepancy for human review and proceed with the design system file.
-
-If absent, fall back to `SPECIFICATION.md`'s design system guidance and CLAUDE.md's CSS framework declaration (existing behavior).
-
-### Architecture Principle
-
-If PRD.md contains an `# Architecture Principle` section, read it and use as implementation constraints:
-- **Stateless**: Ensure no module implementation stores data in HTTP session — user context must come from JWT tokens or external identity providers
-- **Event-driven**: Ensure inter-module communication uses event publishing (e.g., Spring ApplicationEvent, Laravel Event) rather than direct service injection across module boundaries
-- **Message driven**: When implementing message consumers/publishers, follow the patterns described in the architecture (e.g., dedicated queues per country, independent queue configurations)
-- **Monolithic with modular architecture**: Modules can share the same database but should not directly access each other's repositories — use events or service interfaces
-
-If absent, rely on SPECIFICATION.md for architectural guidance (existing behavior).
-
-### High Level Process Flow
-
-If PRD.md contains a `# High Level Process Flow` section, use it as the **implementation blueprint** for message-driven modules:
-1. Implement flow steps in order: (1) message consumer, (2) validation logic, (3) data persistence, (4) ACK/NACK publishing
-2. Each flow step maps to a specific method in the service layer
-3. Treat flow steps as mini-specifications within each module's implementation
-4. After implementing all steps of a flow, verify the complete end-to-end flow works before moving to the next module
-
-If absent, implement from SPECIFICATION.md messaging sections only (existing behavior).
-
----
-
-## Pre-Requisite: Context Artifacts Must Exist
-
-Before starting implementation, verify that all required context artifacts exist:
-- `<app_folder>/context/model/` — must contain module model files
-- `<app_folder>/context/mockup/` — must contain HTML mockup files
-- `<app_folder>/context/specification/` — must contain specification files
-- `<app_folder>/context/test/` — must contain test specification files
-
-If any artifacts are missing, **stop and inform the user** to run `/conductor-feature-prepare`
-first. Do NOT attempt to generate artifacts — that is the responsibility of the prepare skill.
-
-## Version Gate
-
-Before starting any work, check `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
-
-1. If `<app_folder>/CHANGELOG.md` does not exist, skip this check (first-ever execution for this application).
-2. If `<app_folder>/CHANGELOG.md` exists, scan all `## vX.Y.Z` headings and determine the **highest version** using semantic versioning comparison.
-3. Apply the gate based on the version argument form:
-   - **Single version**: If requested version **<** highest version → **STOP immediately**. Print: `"Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."`
-   - **Comma-separated list**: Check the **lowest** version in the list. If lowest **<** highest version → **STOP immediately**. Print: `"Version {lowest} in the provided list is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."`
-   - **`version:all` or omitted**: Skip this check — when processing all discovered versions, historical versions are expected.
-
-### Redo/Redevelop Guard
-
-This guard prevents accidental re-execution of already-completed work while allowing
-incremental processing of new versions. It uses a **partition and filter** approach.
-
-1. Resolve the version list (see Version Resolution).
-2. **Partition** the resolved versions into two groups:
-   - `completed_versions` — versions that have a matching `conductor-feature-develop` entry
-     in `<app_folder>/CHANGELOG.md`
-   - `new_versions` — versions with NO matching entry
-3. **Decision**:
-
-   | `new_versions` | `completed_versions` | Artifacts/code exist? | Action |
-   |---------------|---------------------|----------------------|--------|
-   | Not empty | Any (including empty) | Yes (expected — prior versions built them) | **Proceed with `new_versions` only** — filter out completed versions. Existing code is the base for version increment. |
-   | Not empty | Any | No | **Proceed with all resolved versions** — no prior code, start from scratch. |
-   | Empty | Not empty | Yes | **STOP**. Print: `"All requested versions ({list}) for {application} were already developed (recorded in <app_folder>/CHANGELOG.md) and artifacts/code still exist. To redo, first delete the existing IMPLEMENTATION_MASTER.md and source code, then re-run this skill."` |
-   | Empty | Not empty | No | **Proceed with all resolved versions** — code was cleaned up, this is a legitimate redo. |
-
-   **Artifacts/code exist check**: `<app_folder>/context/develop/IMPLEMENTATION_MASTER.md`
-   exists, OR source code files exist in `<app_folder>/` (e.g., `pom.xml`, `composer.json`,
-   `package.json`, or `src/` directory).
-
-4. **Update the resolved version list** to contain only the versions that will be processed
-   (either `new_versions` or all versions for redo). This filtered list is what the Version
-   Processing Order table and the sequential version loop will use.
-
-## Workflow
-
-### Phase 0: Resume Check (Runs Every Ralph Loop Iteration)
-
-This phase runs at the START of every iteration, including the first. In a Ralph Loop,
-each iteration begins fresh with the same prompt, so the agent MUST read the tracking
-files to understand what has already been completed.
-
-0. **Auto-Start Ralph Loop** — Check if `.claude/ralph-loop.local.md` exists. If it does NOT
-   exist, Ralph Loop is not yet active. Invoke it NOW using the Skill tool:
-   ```
-   Skill(skill: "ralph-loop:ralph-loop", args: "<the full /conductor-feature-develop invocation with args> --completion-promise \"ALL MODULES IMPLEMENTED\" --max-iterations 100")
-   ```
-   If `.claude/ralph-loop.local.md` already exists, Ralph Loop is active — skip this step.
-
-1. **Use project information from CLAUDE.md (already in context)** — extract JDK path, Maven path, database credentials,
-   message queue credentials, Keycloak config, and all infrastructure details. These values
-   are required for every subsequent tool command in this session.
-2. **Verify context artifacts exist** — Check that model/, mockup/, specification/, and test/
-   folders contain the required files. If missing, stop and inform user to run
-   `/conductor-feature-prepare` first.
-3. Check if `<app_folder>/context/develop/IMPLEMENTATION_MASTER.md` exists
-4. If it exists, read it and determine the current state:
-   - Scan the Module Implementation Status table for the FIRST module with status != COMPLETED
-   - If ALL modules are COMPLETED:
-     - **Sequential version loop check**: Resolve the version list (see Version Resolution).
-       Read the **Version Processing Order** table in IMPLEMENTATION_MASTER.md (if it exists)
-       to determine which versions have been completed.
-       - Find the FIRST version in the resolved list that is NOT yet tracked or NOT `COMPLETED`
-         in the Version Processing Order table.
-       - If such a version exists, this is the **next version to process** — perform the
-         version increment steps below and proceed to Phase 3.
-       - If ALL versions in the resolved list are `COMPLETED`, proceed to the README check below.
-     - **Version increment** — For each new version to process:
-       1. Update IMPLEMENTATION_MASTER.md: add the new version to the Version Processing Order
-          table, reset affected modules to PENDING status.
-       2. **Update the application version** in the project manifest and configuration:
-          - **Spring Boot**: Update `<version>` in `pom.xml` and `APP_VERSION` in `.env`
-          - **Laravel**: Update `version` in `composer.json` and `APP_VERSION` in `.env`
-          - **React / Node.js**: Update `version` in `package.json` and `VITE_APP_VERSION`
-            in `.env.development` (or `APP_VERSION` in `.env` for Node.js backends)
-          - **application.yml / config files**: If `app.version` has a hardcoded default in
-            `application.yml` (e.g., `${APP_VERSION:1.0.0}`), update the default to the new
-            version (e.g., `${APP_VERSION:1.0.4}`)
-          - **config/app.php** (Laravel): Update the default in `env('APP_VERSION', '1.0.0')`
-            to the new version
-          The version displayed in the application footer (or API info endpoint) MUST reflect
-          the new version after this update.
-       3. Proceed to Phase 3 (Implementation) for the affected modules.
-     - **README check**: If the top-level `**Status**:` in IMPLEMENTATION_MASTER.md is NOT
-       yet `COMPLETED`, proceed to Phase 5 (Generate README.md) — all modules are done but
-       README hasn't been generated and tracking hasn't been finalized yet.
-     - If ALL versions are completed AND top-level status is already
-       `COMPLETED` → output `<promise>ALL MODULES IMPLEMENTED</promise>` and stop
-   - Otherwise, read its `IMPLEMENTATION_MODULE.md` for detailed progress
-   - Resume from the last incomplete step in the checklist
-5. If it does not exist, proceed to Phase 1 (Planning — fresh start)
-
-### Phase 1: Planning
-
-1. **Use project information from CLAUDE.md (already in context)** — extract all paths, credentials,
-   and infrastructure configuration. This is the single source of truth for JDK, Maven, database,
-   message queue, Keycloak, and all other tool configurations.
-2. Read `<app_folder>/context/test/TEST_PLAN.md`
-3. Extract the **Execution Order** (Section 5) and **Layer Classification** (Section 4)
-4. The execution order defines the module sequence — use it as-is
-5. Read `<app_folder>/context/specification/SPECIFICATION.md` for shared infrastructure context
-
-Create `<app_folder>/context/develop/IMPLEMENTATION_MASTER.md` with this structure:
-
-```markdown
-# Implementation Master - <Application Name>
-
-**Started**: <date>
-**Source Code**: <source-code-path>
-**Context**: <app_folder>/context
-**Resolved Versions**: <comma-separated sorted version list, e.g., "v1.0.0, v1.0.1, v1.0.2">
-**Status**: IN PROGRESS
-
----
-
-## Version Processing Order
-
-| # | Version | Module Count | Status | Started | Completed |
-|---|---------|-------------|--------|---------|-----------|
-| 1 | v1.0.0 | 12 | NEW | - | - |
-| 2 | v1.0.1 | 3 | NEW | - | - |
-| 3 | v1.0.2 | 1 | NEW | - | - |
-
-> **Processing Rule**: All modules for version N must reach COMPLETED before version N+1 begins.
-> **First version**: full scaffolding + all modules. **Subsequent versions**: version increment — only modules with changes.
-
----
-
-## Execution Order
-
-<Copy the execution order tree from TEST_PLAN.md>
-
----
-
-## Module Implementation Status
-
-| # | Module | Layer | Version | Status | Started | Completed | Notes |
-|---|--------|-------|---------|--------|---------|-----------|-------|
-| 1 | User | L1 | v1.0.0 | PENDING | - | - | |
-| 2 | Location Information | L2 | v1.0.0 | PENDING | - | - | |
-...
-
-> The **Version** column tracks which version is currently being implemented for that module.
-> When a version increment occurs, affected modules are reset to PENDING with the new version.
-
----
-
-## Module Details
-
-### 1. User
-
-**Resources**:
-- User Story: <list relevant story IDs>
-- Model: `model/user/model.md`
-- Specification: `specification/user/SPEC.md`
-- Test Spec: `test/user/TEST_SPEC.md`
-- Mockup: `mockup/<role>/content/<screen>.html`
-
-**Dependencies**: None
-
----
-
-### 2. Location Information
-...
-```
-
-**IMPORTANT — Single version shortcut**: When only a single version is resolved, the Version
-Processing Order table has a single row. The behavior is identical to the original single-version
-flow — no extra complexity.
-
-**IMPORTANT — Module Count per version**: For the FIRST version, Module Count = total modules
-(full implementation). For subsequent versions, Module Count = only modules that have new/changed
-user stories for that version.
-
-### Phase 2: Pre-Implementation (Scaffolding)
-
-Read the SPECIFICATION.md shared infrastructure sections and scaffold the project.
-
-**CRITICAL — Source Code Placement Rule:**
-All source code MUST be placed directly in `<source-code-path>/` (which defaults to `<app_folder>/`).
-The `context/` folder already exists there and must be preserved. When using project creation tools
-like `composer create-project` or `mvn archetype:generate`, ensure you do NOT create a nested
-subdirectory. Instead:
-- For Laravel: Create the project in a temporary directory (e.g., `<source-code-path>/_temp_scaffold`),
-  then move ALL files (including dotfiles) from that temp directory up to `<source-code-path>/`,
-  then remove the empty temp directory. This avoids overwriting the existing `context/` folder.
-- For Spring Boot: Same approach — scaffold into a temp dir, then move files up.
-- NEVER use the project slug/name as the target directory if it would create a nested folder.
-
-**Scaffolding Checklist** (adapt to the technology stack from SPECIFICATION.md):
-
-1. **Project structure**: Create the project skeleton directly in `<source-code-path>/`
-2. **Build & dependency configuration**: composer.json / pom.xml / build.gradle with all dependencies
-3. **Application version**: Set the application version in the project manifest using the
-   FIRST version in the resolved version list (the version currently being implemented).
-   If no version argument was provided (all versions), use the first discovered version.
-   If no versions exist at all, use `1.0.0`.
-   - **Spring Boot**: Set `<version>` in `pom.xml` (e.g., `<version>1.0.0</version>`) and
-     `APP_VERSION` in `.env`
-   - **Laravel**: Set `version` in `composer.json` and `APP_VERSION` in `.env`
-   - **React / Node.js**: Set `version` in `package.json` and `VITE_APP_VERSION` in
-     `.env.development` (or `APP_VERSION` in `.env` for Node.js backends)
-   - The version in the manifest MUST match the version in the environment variable
-   - For multi-version processing, this version will be updated during each version increment
-     in the Phase 0 resume check
-4. **Application configuration**: .env, config files, or application.yml as appropriate
-4. **Security configuration**: Keycloak/OAuth2 or other auth provider setup
-5. **Shared layouts**: Blade / JTE / other template layout files (header, footer, sidebar)
-6. **Shared components**: UI components (Tailwind), JS structure, CSS
-7. **Data access layer**: Base repository / model configuration
-8. **Error handling**: Global exception handlers
-9. **Theming**: Theme configuration from spec
-10. **Pagination**: Shared pagination support
-11. **Messaging**: Message queue configuration if applicable
-12. **Scheduling**: Scheduled task configuration if applicable
-13. **Playwright test project**: Initialize Playwright in `<source-code-path>/e2e/` with:
-    - `package.json` with Playwright and `dotenv` dependencies
-    - `playwright.config.ts` with base URL read from `process.env.TEST_APP_BASE_URL`
-      (loaded via `dotenv` at the top of the config)
-    - `.env.example` — committed to git, contains all `TEST_*` environment variable names
-      with placeholder descriptions (from TEST_PLAN.md Section 2a). No real credentials.
-    - `.env` — contains actual values from CLAUDE.md for the current developer's machine.
-      Pre-populate with values from CLAUDE.md. This file MUST NOT be committed to git.
-    - **`.gitignore` update (MANDATORY)** — Add the following entries to the project's
-      `.gitignore` file (or create it if it does not exist):
-      - `e2e/.env` — prevents credentials and machine-specific paths from being committed
-      - `e2e/node_modules/` — prevents Playwright and dotenv dependencies from being committed
-      Verify both entries exist before proceeding with any other scaffolding step.
-    - `helpers/config.ts` — **single source of truth** for all infrastructure config.
-      Loads `dotenv/config` and exports named constants for every `TEST_*` env var
-      (DB, MQ, SSO, app URL). All other helpers and spec files import from this file
-      instead of reading `process.env` directly or hardcoding values.
-    - Helper utilities for login, navigation, data seeding — all helpers MUST import
-      infrastructure values from `helpers/config.ts`. **NEVER hardcode** machine-specific
-      paths, CLI tool locations, database credentials, or SSO admin passwords in any
-      TypeScript source file (helpers OR spec files).
-14. **Mockup baseline screenshots**: Capture baseline screenshots from HTML mockups for visual consistency testing:
-    - Start the shared Mockup Hub (`npm start` in `<root>/mockup/` — zero dependencies, no
-      npm install needed; port from `PORT` env or `mockup.config.json`, default 3000)
-    - Screens are served at `http://localhost:<hub_port>/<app_slug>/<role>/<page>`
-      (shadcn mockups must be built first: `npm run build` in the app's mockup folder)
-    - For each role/screen in the mockup, capture a screenshot to `<source-code-path>/e2e/visual-baselines/`
-    - Stop the Mockup Hub after capture
-    - These baselines will be compared against the application output during module testing
-
-After scaffolding, verify the application compiles/starts. **Use the exact paths, CLIs, and
-credentials from `CLAUDE.md`** — do NOT use generic commands or assume default paths:
-```bash
-# Examples (actual paths come from CLAUDE.md):
-
-# Laravel:
-<php-path-from-CLAUDE.md>/php.exe artisan --version
-<php-path-from-CLAUDE.md>/php.exe artisan serve
-
-# Spring Boot:
-JAVA_HOME="<jdk-path>" <maven-path>/mvn -f <source-code-path>/pom.xml clean compile
-```
-
-Update IMPLEMENTATION_MASTER.md: mark scaffolding as COMPLETED.
-
-### Phase 3: Implementation (Per Module)
-
-For each module in execution order:
-
-#### Step 3.1: Initialize Module Tracking
-
-Create `<app_folder>/context/develop/<module-slug>/IMPLEMENTATION_MODULE.md`:
-
-```markdown
-# Implementation - <Module Name>
-
-**Module**: <Module Name>
-**Layer**: <Layer>
-**Status**: IN PROGRESS
-**Started**: <date>
-
----
-
-## Resources
-
-| Resource | Path |
-|----------|------|
-| User Stories | <IDs from PRD.md> |
-| Bug Fixes | <IDs from PRD.md `### Bug` section, if any> |
-| Model | `model/<module-slug>/model.md` |
-| Specification | `specification/<module-slug>/SPEC.md` |
-| Test Spec | `test/<module-slug>/TEST_SPEC.md` |
-| Mockup | `mockup/<role>/content/<screen>.html` |
-
----
-
-## Implementation Checklist
-
-### UI Layer
-
-- [ ] 1. Read and analyze module resources
-- [ ] 2. Implement module model (entities/documents)
-- [ ] 3. Implement repository layer
-- [ ] 4. Implement service layer
-- [ ] 5. Implement controller layer
-- [ ] 6. Implement view templates (list, detail, form pages)
-- [ ] 7. Write Playwright E2E tests (UI scenarios)
-- [ ] 8. Run E2E tests and verify
-
-### User Stories
-
-<For each user story ID from the module's SPEC.md traceability section, add a checklist item:>
-- [ ] USxxxx: <description>
-
-### Non-Functional Requirements
-
-<For each NFR ID from the module's SPEC.md traceability section, add a checklist item:>
-- [ ] NFRxxxx: <description>
-
-### Messaging Pipeline (if applicable — include only if module has messaging NFRs)
-
-- [ ] Implement message consumer
-- [ ] Implement message validator
-- [ ] Implement ACK publisher
-- [ ] Implement forward publisher
-- [ ] Implement queue configuration
-- [ ] Implement module events
-- [ ] Write E2E tests for message processing flow
-
-### Scheduled Jobs (if applicable — include only if module has scheduling NFRs)
-
-- [ ] Implement scheduled job
-- [ ] Write E2E tests for scheduled job
-
-### Visual Consistency
-
-- [ ] Visual consistency testing (mockup vs application)
-- [ ] Fix visual deviations (if any)
-
----
-
-## Implementation Log
-
-### Step 1: Analyze Module Resources
-<timestamp> - Started
-- Read model.md, SPEC.md, TEST_SPEC.md, mockup HTML
-- Key findings: ...
-```
-
-#### Step 3.2: Analyze Module Resources
-
-Read ALL module-specific resources:
-- `model/<module-slug>/model.md` — document structure, collections, fields
-- `model/<module-slug>/schemas.json` — JSON schema examples
-- `specification/<module-slug>/SPEC.md` — full technical specification
-- `test/<module-slug>/TEST_SPEC.md` — test scenarios, seeding scripts, assertions
-- `mockup/<role>/content/<module_screen>.html` — UI mockup for visual reference
-- Relevant entries from `PRD.md` — user stories for this module
-- `### Bug` section from `PRD.md` for this module (if present) — previously fixed bugs
-- Relevant message files from `reference/message/` if applicable
-
-**Bug Regression Awareness (Redo/Redevelop Scenario):**
-If the module has a `### Bug` section in PRD.md, this means the application was previously
-developed and users reported bugs that were fixed. During redevelopment, these bug fixes MUST
-be incorporated into the implementation to prevent the same bugs from reappearing:
-- Read each bug entry (e.g., `[BUG-024] Fixed Message ID link...`) to understand what was broken and how it was fixed
-- Treat each bug fix as an implicit requirement — the implementation must produce behavior consistent with the fix description
-- If a bug fix contradicts or supplements a user story or NFR, the bug fix takes precedence (it reflects the latest validated behavior)
-
-Update IMPLEMENTATION_MODULE.md: mark step 1 complete with findings summary.
-
-#### Step 3.3: Implement Module Code
-
-Follow the module SPEC.md to implement, in order:
-1. **Entity/Document classes** — from model.md + schemas.json
-2. **Repository interfaces** — from SPEC.md data access section
-3. **Service classes** — business logic from SPEC.md
-4. **Mappers** — if specified in SPEC.md
-5. **Controller classes** — routes, request handling from SPEC.md
-6. **View templates** — from SPEC.md view section + mockup HTML
-7. **Message listeners** — from SPEC.md messaging section (if applicable)
-8. **Scheduled jobs** — from SPEC.md scheduling section (if applicable)
-
-**Traceability comment (MANDATORY)** — Every newly created source file (entity, repository,
-service, mapper, controller, view template, listener, scheduled job, configuration class)
-MUST begin with a top-of-file comment listing the requirement codes it implements.
-Extract the codes verbatim from the module's `SPEC.md` traceability section. Use the
-9-character codes emitted by `util-ustagger` — DO NOT invent or reformat the codes:
-
-| Category | Pattern | Example (`HM` initials) |
-|---|---|---|
-| User Story | `US<II><5-digit#>` | `USHM00003` |
-| Non-Functional Requirement | `NFR<II><4-digit#>` | `NFRHM0003` |
-| Constraint | `CONS<II><3-digit#>` | `CONSHM003` |
-| Reference | `REF<II><4-digit#>` | `REFHM0003` |
-
-Where `<II>` is the application's 2-letter initials (e.g., `HM` for Hub Middleware).
-The actual codes in any given file come from the module's `SPEC.md` traceability section,
-NOT from this template — never invent codes that do not appear in PRD.md.
-
-Use the language's native doc-comment style — Javadoc / PHPDoc / JSDoc (`/** ... */`)
-for code files, `{{-- ... --}}` for Blade, `@* ... *@` for JTE, `<!-- ... -->` for HTML,
-`# ...` for YAML / `.env` / `.properties`.
-
-Example (Java service for the Employer module of an app with initials `HM`):
-```java
-/**
- * Implements: USHM00003, USHM00006
- * NFR: NFRHM0003 (audit logging), NFRHM0006 (pagination)
- * Constraints: CONSHM003
- */
-public class EmployerService { ... }
-```
-
-This makes `git blame`, IDE symbol search, and downstream audits trace every line back to
-PRD.md directly — IMPLEMENTATION_MODULE.md is a transient tracking file and is not the
-system of record for traceability.
-
-After each major component, update IMPLEMENTATION_MODULE.md checklist.
-
-#### Step 3.4: Implement Playwright E2E Tests
-
-From the module's TEST_SPEC.md:
-
-1. **Create test file**: `<source-code-path>/e2e/tests/<module-slug>.spec.ts`
-2. **Implement data seeding**: Use the seeding scripts from TEST_SPEC.md Section 4.
-   All seeding helper functions MUST read paths, credentials, and connection strings
-   from `process.env.*` (loaded via `dotenv` from `<source-code-path>/e2e/.env`).
-   **NEVER hardcode** machine-specific values (file paths, CLI tool locations, database
-   hosts/passwords, SSO admin credentials) in TypeScript source code.
-3. **Implement test scenarios**: Convert each scenario from TEST_SPEC.md Section 5 into Playwright tests
-4. **DO NOT implement cleanup scripts** — test data must persist for downstream modules
-
-Pattern for shared config helper (`e2e/helpers/config.ts`) — **single source of truth**
-for all infrastructure configuration. Every other helper and spec file imports from here
-instead of reading `process.env` directly or hardcoding values:
-```typescript
-import 'dotenv/config';  // loads .env from e2e/ directory
-
-// Application
-export const APP_BASE_URL = process.env.TEST_APP_BASE_URL!;
-
-// Database (include only what exists in CLAUDE.md)
-export const DB_URI = process.env.TEST_DB_URI!;           // MongoDB
-// OR for MySQL/PostgreSQL:
-// export const DB_HOST = process.env.TEST_DB_HOST!;
-// export const DB_PORT = process.env.TEST_DB_PORT!;
-// export const DB_USER = process.env.TEST_DB_USER!;
-// export const DB_PASSWORD = process.env.TEST_DB_PASSWORD!;
-// export const DB_NAME = process.env.TEST_DB_NAME!;
-
-// Message Queue (include only if MQ exists in CLAUDE.md)
-export const MQ_HOST = process.env.TEST_MQ_HOST!;
-export const MQ_PORT = process.env.TEST_MQ_PORT!;
-export const MQ_USER = process.env.TEST_MQ_USER!;
-export const MQ_PASSWORD = process.env.TEST_MQ_PASSWORD!;
-export const MQ_VHOST = process.env.TEST_MQ_VHOST!;
-export const MQ_URL = process.env.TEST_MQ_URL!;
-
-// SSO / Auth (include only if SSO exists in CLAUDE.md)
-export const SSO_HOST = process.env.TEST_SSO_HOST!;
-export const SSO_ADMIN_USER = process.env.TEST_SSO_ADMIN_USER!;
-export const SSO_ADMIN_PASSWORD = process.env.TEST_SSO_ADMIN_PASSWORD!;
-export const SSO_CLI_PATH = process.env.TEST_SSO_CLI_PATH!;
-export const SSO_REALM = process.env.TEST_SSO_REALM!;
-```
-
-Pattern for domain-specific helper (e.g., `e2e/helpers/keycloak.ts`) — imports config
-from `config.ts`, never reads `process.env` directly:
-```typescript
-import { execSync } from 'child_process';
-import { SSO_CLI_PATH, SSO_HOST, SSO_ADMIN_USER, SSO_ADMIN_PASSWORD, SSO_REALM } from './config';
-
-function runKcadm(command: string): string {
-  try {
-    return execSync(`"${SSO_CLI_PATH}" ${command}`, { encoding: 'utf-8', timeout: 30000 });
-  } catch (error: any) {
-    return error.stdout || error.stderr || error.message || '';
-  }
-}
-
-export function kcadmConfig(): void {
-  runKcadm(`config credentials --server ${SSO_HOST} --realm master --user ${SSO_ADMIN_USER} --password ${SSO_ADMIN_PASSWORD}`);
-}
-// ... remaining helper functions use the config imports above
-```
-
-**No hardcoded config in spec files**: If a spec file needs infrastructure values (e.g.,
-database connection for direct seeding, MQ host for publishing, mail server URL), it MUST
-import them from `helpers/config.ts` — never hardcode them inline in the spec. This applies
-to ALL spec files, not just those with dedicated helper modules.
-
-**Test naming convention (MANDATORY)** — Every test name MUST be prefixed with the
-**scenario ID from TEST_SPEC.md Section 4** so test output (CI logs, reports) is traceable
-to TEST_SPEC.md without consulting IMPLEMENTATION_MODULE.md. The scenario IDs are emitted
-by `testgen-functional` and follow the pattern `<TYPE>-<MODULE-PREFIX>-<NNN>`, where
-`<TYPE>` is one of `NAV`, `SRCH`, `VIEW`, `CRUD`, `VAL`, `MAP`, `TOG`, `HIST`, `RAW`,
-`PAGE`, `REG`, or `TSTI`, and `<MODULE-PREFIX>` is the 3-letter module prefix from the
-module model (e.g., `LIN` for Location Information, `EMP` for Employer, `QUO` for Quota).
-
-Format: `'<scenario-id>: <scenario-name>'` — copied verbatim from TEST_SPEC.md Section 4.
-Do NOT invent IDs; do NOT collapse or reformat them.
-
-Each test MUST also carry a JSDoc traceability comment listing the source codes from
-the scenario's **Source** field in TEST_SPEC.md — these are the same `USHM#####`,
-`NFRHM####`, `CONSHM###`, `TSTHM####`, and `[BUG-XXX]` codes that link the scenario back
-to PRD.md. Copy them verbatim.
-
-Pattern for test file:
-```typescript
-import { test, expect } from '@playwright/test';
-import { DB_URI, MQ_URL } from '../helpers/config';  // import what this spec needs
-
-/**
- * Module: <Module Name>
- * Implements scenarios: NAV-LIN-001, SRCH-LIN-001, CRUD-LIN-001, CRUD-LIN-002
- *   (copied verbatim from TEST_SPEC.md Section 4)
- */
-test.describe('<Module Name>', () => {
-  // Data seeding (runs once before all tests in this module)
-  test.beforeAll(async () => {
-    // Execute seeding script from TEST_SPEC.md Section 4
-    // All infrastructure values come from helpers/config.ts — never hardcode
-  });
-
-  // DO NOT add afterAll cleanup — data persists for dependent modules
-
-  /**
-   * Covers: USHM00003, USHM00006
-   * NFR: NFRHM0003
-   * Bug regression: [BUG-024]   // include only if scenario covers a previously-fixed bug
-   */
-  test('NAV-LIN-001: Navigate to Location Information screen', async ({ page }) => {
-    // Steps from the matching TEST_SPEC.md Section 4 scenario
-  });
-});
-```
-
-#### Step 3.5: Run E2E Tests
-
-```bash
-cd <source-code-path>/e2e && npx playwright test tests/<module-slug>.spec.ts
-```
-
-- If tests pass: proceed to visual consistency testing (Step 3.6)
-- If tests fail: analyze failures, fix code, re-run (do NOT clean test data unless re-seeding is required for retest)
-
-#### Step 3.6: Visual Consistency Testing (Mockup vs Application)
-
-After functional E2E tests pass, compare the UI output of the application against the approved HTML mockup screens. The goal is to verify **aesthetic consistency** — colors, alignment, padding, margins, font sizes, layout structure — NOT content (data values will differ).
-
-**Process:**
-
-1. **Identify mockup screens** for this module from `<app_folder>/context/mockup/<role>/content/` that correspond to the implemented views.
-
-2. **Capture mockup baselines** (if not already captured during scaffolding):
-   - Start the shared Mockup Hub: `cd <root>/mockup && npm start` (no npm install needed)
-   - Navigate to each screen for the module at
-     `http://localhost:<hub_port>/<app_slug>/<role>/<page>` and capture a screenshot
-   - Save to `<source-code-path>/e2e/visual-baselines/<module-slug>/<screen-name>.png`
-   - Stop the Mockup Hub
-
-3. **Create visual comparison test**: `<source-code-path>/e2e/tests/<module-slug>.visual.spec.ts`
-   - For each screen in the module, navigate to the corresponding application page
-   - Capture a screenshot of the application output
-   - Use Playwright's `toHaveScreenshot()` with a **threshold** to allow content differences while catching layout/styling deviations
-   - Compare against the mockup baseline
-
-4. **Visual test pattern**:
-```typescript
-import { test, expect } from '@playwright/test';
-import { loginAs } from '../helpers/auth';
-import path from 'path';
-
-test.describe('<Module Name> - Visual Consistency', () => {
-  test('<screen-name> matches mockup layout', async ({ page }) => {
-    await loginAs(page, '<role>');
-    await page.goto('<app-route-for-screen>');
-    await page.waitForLoadState('networkidle');
-
-    // Compare against mockup baseline — threshold allows content differences
-    // but catches color, alignment, padding, margin, and layout deviations
-    await expect(page).toHaveScreenshot('<module-slug>-<screen-name>.png', {
-      maxDiffPixelRatio: 0.15,   // Allow up to 15% pixel difference (content varies)
-      threshold: 0.3,            // Per-pixel color threshold (0-1, higher = more lenient)
-      animations: 'disabled',
-    });
-  });
-});
-```
-
-5. **On first run**, Playwright generates actual screenshots. Manually review them:
-   - If the layout aesthetics match the mockup (colors, spacing, alignment), approve by updating the snapshots
-   - If deviations are found, fix the templates / CSS and re-run
-
-6. **What to check** (aesthetic consistency):
-   - Color scheme matches (backgrounds, borders, text colors, button colors)
-   - Spacing and alignment (padding, margins, gaps between elements)
-   - Layout structure (grid/flex arrangement, sidebar/header/content proportions)
-   - Typography (font sizes, weights, line heights — relative, not exact)
-   - Component styling (buttons, tables, forms, cards, badges)
-   - Responsive breakpoints if applicable
-
-7. **What to ignore** (content differences are expected):
-   - Actual text content / data values
-   - Number of rows in tables
-   - Dynamic timestamps, IDs, or generated values
-
-Update IMPLEMENTATION_MODULE.md: mark visual consistency testing step complete with findings.
-
-- If visual tests pass: update IMPLEMENTATION_MODULE.md status to COMPLETED
-- If visual tests reveal layout issues: fix templates/CSS, re-run both functional and visual tests
-
-### Phase 4: Post-Implementation (Per Module)
-
-After each module completes:
-
-1. Update `<app_folder>/context/develop/<module-slug>/IMPLEMENTATION_MODULE.md`:
-   - Set Status to COMPLETED
-   - Record completion date
-   - Record test results summary
-
-2. Update `<app_folder>/context/develop/IMPLEMENTATION_MASTER.md`:
-   - Update module row: Status = COMPLETED, Completed = date
-   - Add notes about any issues encountered
-
-3. **Check module and version completion**:
-   - Scan the Module Implementation Status table in IMPLEMENTATION_MASTER.md
-   - If there are still PENDING modules for the **current version**:
-     - **IMMEDIATELY proceed to the next module** in execution order — do NOT stop
-     - Continue implementing until context limits force a natural stop
-     - The Ralph Loop will re-feed the prompt, and the next iteration will resume via Phase 0
-   - If ALL modules for the **current version** are COMPLETED:
-     - Update the Version Processing Order table: mark current version as `COMPLETED`, record date
-     - Check if there are MORE versions in the resolved version list:
-       - If YES → perform a **version increment** (update app version in manifest, reset affected
-         modules to PENDING with the new version) and **IMMEDIATELY proceed to Phase 3** for the
-         next version's modules. Do NOT stop between versions.
-       - If NO (this was the last version) → **Proceed to Phase 5 (Generate README.md)**
-         before outputting the completion promise
-
-### Phase 5: Generate README.md
-
-After ALL modules are COMPLETED, generate a `README.md` file in the application root folder
-(`<source-code-path>/README.md`). This file serves as the primary documentation for developers
-to understand the application architecture, navigate the codebase, and run the application.
-
-**If `<source-code-path>/README.md` already exists, OVERWRITE it completely.** The existing
-README may have been auto-generated by the project scaffolding tool (e.g., Laravel, Spring
-Initializr) and does not reflect the actual implemented application. Phase 5 always produces
-a fresh README based on the specification and the final implementation state.
-
-**CRITICAL**: The README content MUST be derived from `SPECIFICATION.md` — the technical
-specification generated by the chosen `specgen-*` skill. Do NOT invent or assume technology
-details. Extract all architecture, stack, configuration, and run instructions directly from
-the specification document.
-
-#### Step 5.1: Read SPECIFICATION.md
-
-Read `<app_folder>/context/specification/SPECIFICATION.md` and extract:
-- **Technology stack** — framework, language, template engine, CSS framework, JS libraries, database, auth provider, messaging, scheduling
-- **Application architecture** — packaging structure (e.g., Spring Modulith, Laravel Modules), layer conventions (controller, service, repository, view), shared infrastructure components
-- **Configuration** — environment variables, config files, database connection, auth provider setup, message queue setup
-- **Build and run commands** — how to install dependencies, compile, run the application, run tests
-
-#### Step 5.2: Generate README.md
-
-Create `<source-code-path>/README.md` with the following structure:
-
-```markdown
-# <Application Name>
-
-<One-paragraph description from SPECIFICATION.md project overview>
-
-## Technology Stack
-
-<Table of technologies, versions, and purposes — extracted from SPECIFICATION.md technology stack section>
-
-| Technology | Version | Purpose |
-|-----------|---------|---------|
-| ... | ... | ... |
-
-## Architecture
-
-<Description of the application architecture from SPECIFICATION.md — packaging approach,
-layer conventions, module organization. Include a text-based or Mermaid diagram if the
-specification describes the architecture visually.>
-
-## Folder Structure
-
-<Tree representation of the actual source code folder structure as implemented. Use the
-real directory layout from `<source-code-path>/`, excluding `context/`, `node_modules/`,
-`.git/`, and other non-essential directories. Annotate key directories with their purpose.>
-
-```
-<source-code-path>/
-  app/                    # (Laravel) Application core
-  Modules/                # (Laravel) Feature modules
-  resources/              # (Laravel) Views, CSS, JS
-  src/                    # (Spring) Java source
-  e2e/                    # Playwright E2E tests
-  ...
-```
-
-## Prerequisites
-
-<List of software prerequisites needed to run the application — JDK, PHP, Composer, Maven,
-Node.js, database, message queue, auth provider, etc. Extracted from SPECIFICATION.md.>
-
-## Getting Started
-
-### Installation
-
-<Step-by-step instructions to install dependencies — e.g., `composer install`, `mvn clean install`,
-`npm install`. Derived from SPECIFICATION.md build configuration section.>
-
-### Configuration
-
-<Instructions for setting up configuration — .env file, application.yml, database setup,
-auth provider configuration. Reference the specific config files and environment variables
-from SPECIFICATION.md.>
-
-### Running the Application
-
-<Commands to start the application — e.g., `php artisan serve`, `mvn spring-boot:run`.
-Include the default URL where the application will be accessible.>
-
-### Running Tests
-
-<Commands to run the Playwright E2E test suite:>
-
-```bash
-cd e2e && npx playwright test
-```
-
-<Any additional test commands — unit tests, integration tests — if applicable from the spec.>
-
-## Modules
-
-<Table listing all implemented modules, their layer classification, and a brief description.
-Extracted from IMPLEMENTATION_MASTER.md execution order and module details.>
-
-| Module | Layer | Description |
-|--------|-------|-------------|
-| ... | ... | ... |
-
-```
-
-**Adapt the template above** to match the actual technology stack from SPECIFICATION.md:
-- For **Spring Boot** apps: use Maven/Gradle commands, `src/main/java` paths, `application.yml` config
-- For **Laravel** apps: use Composer/Artisan commands, `app/` paths, `.env` config
-- For **REST API** apps: omit view/template sections, focus on API endpoints and Swagger/OpenAPI docs
-- Include only sections that are relevant to the actual specification — do NOT add sections for
-  features that are not part of the spec (e.g., skip messaging section if no messaging is configured)
-
-#### Step 5.3: Generate Traceability Matrix
-
-After the README is generated and BEFORE finalizing tracking, regenerate the requirement-to-code
-traceability matrix so every PRD requirement ID is linked to the source code that now implements it
-(the per-file `Implements:` / `NFR:` / `Constraints:` comments written in Step 3.3 are the source
-of the links).
-
-1. Invoke the traceability generator (pass the resolved app folder and the version just completed):
-   ```
-   Skill(skill: "co2-skills:tracegen-matrix", args: "<app_folder> version:<current-version>")
-   ```
-   - If a `module` filter was active for this run, pass it through: append ` module:<module>`.
-   - When processing multiple versions, invoke once after the LAST version (the matrix reflects the
-     full current code state); a per-version invocation is also acceptable.
-2. Wait for it to complete. It writes/updates `<app_folder>/context/TRACEABILITY.md` and appends its
-   own `CHANGELOG.md` row.
-3. This step does **not** require the codebase-memory MCP — `tracegen-matrix` resolves links from
-   the in-source traceability comments, falling back to name-based source scanning, and only uses
-   codebase-memory for extra precision when it happens to be installed.
-
-#### Step 5.4: Update Tracking and Complete
-
-1. Update IMPLEMENTATION_MASTER.md:
-   - Set top-level `**Status**:` to `COMPLETED`
-   - Add a note: `README.md generated at <source-code-path>/README.md`
-2. Append entries to `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`) — **one entry per version processed**:
-   - Read `<app_folder>/CHANGELOG.md`. If it does not exist, create it with context header.
-   - For EACH version in the resolved version list (ascending order):
-     - Search for a `## {version}` heading matching this version.
-     - If the section **exists**: append a new row to its table.
-     - If the section **does not exist**: insert a new section after the `---` below the context header and before any existing `## vX.Y.Z` section (newest-first ordering), with a new table header and the first row.
-     - Row format: `| {YYYY-MM-DD} | {application_name} | conductor-feature-develop | {module or "All"} | Implemented modules for {version} — {count} modules |`
-   - **Never modify or delete existing rows.**
-3. Output the Ralph Loop completion promise: `<promise>ALL MODULES IMPLEMENTED</promise>`
-4. This signals the Ralph Loop to exit
-
-## Mockup Interpretation Guide (CRITICAL)
-
-The HTML mockups in `<app_folder>/context/mockup/` are organized into **role-based subfolders**
-(e.g., `hub_administrator/content/`, `hub_operation_support/content/`). This folder structure
-represents which screens each role can access — it does **NOT** dictate URL patterns or imply
-that URLs should contain role names.
-
-### Rule: Module-Based URLs, NOT Role-Based URLs
-
-**WRONG** (role in URL — NEVER do this):
-```
-/hub-administrator/employer
-/hub-operation-support/quota
-/hub-administrator/industrial-classification/create
-```
-
-**CORRECT** (module-based URL):
-```
-/employer
-/quota
-/industrial-classification/create
-```
-
-Controllers MUST use module-based `@RequestMapping` paths. Role enforcement is handled via
-`@PreAuthorize` annotations on the controller class or method level — NOT through URL segregation.
-
-### Template Strategy for Role-Based UI Differences
-
-When a module's mockup exists under multiple role folders, the screens may differ. Follow this
-decision framework to determine the template strategy:
-
-#### Step 1: Classify Each Screen
-
-For each screen in the module, compare the mockup versions across roles and classify:
-
-| Classification | Description | Example |
-|---------------|-------------|---------|
-| **Role-Exclusive** | Screen exists under only ONE role folder | `audit_trail.html` (admin only), `job_demand.html` (ops only) |
-| **Shared — Minor Differences** | Same layout and structure, but some elements are shown/hidden per role (e.g., action buttons, edit toggles, "Add" button) | `document_classification.html` — admin has toggles + edit; ops has read-only badges |
-| **Shared — Major Differences** | Fundamentally different layout, columns, or purpose despite same module name | `occupation_classification.html` — admin sees CRUD list; ops sees corridor mapping view |
-
-#### Step 2: Apply the Appropriate Strategy
-
-**A. Role-Exclusive Screens → Single template, single controller method**
-
-One template, one route. Only the authorized role can access it. No conditional logic needed.
-
-**B. Shared — Minor Differences → Single template with role-based conditionals**
-
-Use **one template** with conditional blocks to show/hide elements based on the user's role.
-This is the preferred approach when the page layout is structurally the same but some UI
-elements (buttons, action columns, edit controls, banners) differ.
-
-The controller method is accessible to both roles with appropriate authorization annotations.
-
-**C. Shared — Major Differences → Separate templates, controller selects at runtime**
-
-When the two role versions have **fundamentally different layouts, columns, or purposes**
-(not just show/hide of a few elements), create separate templates and let the controller
-choose which to render based on the authenticated user's role.
-
-#### Step 3: Document the Decision
-
-In `IMPLEMENTATION_MODULE.md`, under the analysis step, record the template strategy chosen
-for each screen and why:
-
-```markdown
-### Template Strategy
-
-| Screen | Roles | Classification | Strategy |
-|--------|-------|---------------|----------|
-| employer list | ops-only | Role-Exclusive | Single template |
-| document_classification | both | Minor Differences | Single template + conditional |
-| occupation_classification | both | Major Differences | Separate templates |
-```
-
-### How to Read Mockups During Implementation
-
-When implementing a module (Step 3.2 — Analyze Module Resources):
-
-1. **List all mockup files** for this module across ALL role folders:
-   ```
-   mockup/<role1>/content/<module>*.html
-   mockup/<role2>/content/<module>*.html
-   ```
-
-2. **Read each version** and compare structure, columns, buttons, and layout
-
-3. **Classify** each screen using the framework above
-
-4. **Extract visual design** (colors, spacing, components) from the mockup but
-   **ignore the URL paths** embedded in the mockup HTML (e.g., `href="/hub_administrator/..."`)
-   — these are mockup navigation links, NOT the actual application routes
-
-5. **Map mockup URLs to module URLs**:
-   - Mockup: `/hub_administrator/employer` → App: `/employer`
-   - Mockup: `/hub_operation_support/quota_allocation` → App: `/quota-allocation`
-
-## Critical Rules
-
-1. **CLAUDE.md is the source of truth for all tool commands** — CLAUDE.md is automatically
-   loaded into context. Use the exact JDK path, Maven path, database credentials,
-   message queue credentials, Keycloak CLI path, and all other infrastructure details from
-   CLAUDE.md. NEVER hardcode, guess, or use generic paths like `./mvnw` or `java`.
-
-2. **No test data cleanup** — DO NOT clean up test data after module tests pass. Test data
-   from earlier modules is required as seed data for downstream modules. Only clean up if
-   you need to re-seed for a retest.
-
-3. **Context window awareness (Ralph Loop handles recovery)** — If approaching context limits,
-   save progress gracefully:
-   - Update IMPLEMENTATION_MODULE.md with current progress (mark completed steps, log findings)
-   - Update IMPLEMENTATION_MASTER.md with current status
-   - The Ralph Loop will automatically re-feed the prompt, and the next iteration will resume
-     from exactly where you left off via Phase 0 resume check
-   - Do NOT worry about "losing work" — the tracking files ARE your persistence mechanism
-
-4. **Usage limit handling** — If you hit API usage limits, wait and resume. The tracking
-   files ensure no work is lost. Ralph Loop will re-feed the prompt on next iteration.
-
-5. **Module order is strict, version order is strict** — Follow the execution order from
-   TEST_PLAN.md exactly within each version. When processing multiple versions, ALL modules
-   for version N must be COMPLETED before ANY module from version N+1 begins. Dependencies
-   mean earlier modules must complete before later ones can start within the same version.
-
-6. **Track everything** — Every action should be logged in IMPLEMENTATION_MODULE.md so
-   that any future session (or Ralph Loop iteration) can understand what was done and what
-   remains. This is CRITICAL for Ralph Loop — without accurate tracking, iterations will
-   repeat already-completed work.
-
-7. **Test-driven** — Implementation is guided by TEST_SPEC.md. The test spec defines
-   what the code must do. The SPEC.md defines how to build it.
-
-8. **Mockup fidelity** — View templates MUST match the approved HTML mockup screens aesthetically.
-   Use the mockup as the visual reference for layout, components, and styling. After functional
-   E2E tests pass, run visual consistency tests comparing app screenshots against mockup
-   baselines to verify colors, alignment, padding, margins, and layout structure match. Content
-   differences (data values, row counts) are expected and acceptable — only aesthetic deviations
-   should be flagged and fixed.
-
-9. **Specification compliance** — Follow the SPECIFICATION.md shared infrastructure sections
-   for all cross-cutting concerns (security, theming, pagination, error handling, etc.).
-
-10. **Module-based URLs only** — NEVER use role names in URL paths. Mockup folder structure
-    is for organizing mockups by role visibility, NOT for defining URL routes. All controllers
-    use module-based paths. Role enforcement is via authorization annotations. See the
-    "Mockup Interpretation Guide" section above for the full template strategy framework.
-
-11. **Ralph Loop discipline — NEVER stop prematurely** — After completing a module, IMMEDIATELY
-    check for the next pending module and start it. After completing all modules for a version,
-    IMMEDIATELY perform the version increment and start the next version's modules. Do NOT
-    output the completion promise (`<promise>ALL MODULES IMPLEMENTED</promise>`) until EVERY
-    module for EVERY version is COMPLETED. Do NOT stop "to let the user review" — Ralph Loop
-    handles multi-iteration execution automatically. The only valid reasons to stop within an
-    iteration are: (a) context window approaching limit, (b) all modules for all versions
-    completed (output promise), or (c) an unrecoverable error requiring user input.
-
-12. **Complete implementation per module** — Each module must have ALL of these before marking
-    COMPLETED: (a) all source files (entities, repositories, services, controllers, mappers),
-    (b) all view templates (page + fragments), (c) E2E test file with all scenarios from TEST_SPEC,
-    (d) all E2E tests passing, (e) ALL user stories checked off in IMPLEMENTATION_MODULE.md,
-    (f) ALL NFRs checked off in IMPLEMENTATION_MODULE.md. Do NOT mark a module COMPLETED with
-    partial implementation or failing tests — this would cause the next Ralph Loop iteration to
-    skip it. If a module has messaging/async NFRs that cannot be implemented yet (e.g., upstream
-    adapter not available), mark the module as **PARTIALLY COMPLETED** and leave the unchecked
-    NFR items visible in the checklist. Only mark COMPLETED when every user story AND every NFR
-    is implemented and tested.
-
-13. **Auto-start Ralph Loop** — When this skill is triggered, the FIRST action (Phase 0, Step 0)
-    MUST be to check if Ralph Loop is active (`.claude/ralph-loop.local.md` exists). If not active,
-    invoke `Skill(skill: "ralph-loop:ralph-loop", args: "...")` with the full orchestrator prompt
-    and `--completion-promise "ALL MODULES IMPLEMENTED" --max-iterations 100`. Do NOT proceed
-    with any implementation work until Ralph Loop is confirmed active.
-
-14. **NO creative alternatives for 3rd party applications (CRITICAL)** — You MUST use the EXACT
-    methods, connection strings, CLIs, and credentials described in `CLAUDE.md` for
-    accessing all external infrastructure. This includes but is not limited to:
-
-    **NEVER do any of the following:**
-    - Connect to databases via Docker (`docker exec`, `docker run`, CLI inside a container)
-    - Start or restart services with alternative databases
-    - Spin up services via Docker Compose or Docker run
-    - Use `docker exec` to access any service that is described as running natively in CLAUDE.md
-    - Install or use alternative CLI tools when CLAUDE.md specifies a different access method
-    - Assume services run in Docker when CLAUDE.md says they run natively (or vice versa)
-    - Use embedded/in-memory databases as substitutes for the actual configured database
-    - Guess connection strings, ports, or credentials — ALWAYS read them from CLAUDE.md
-
-    **ALWAYS do the following:**
-    - Use database connection strings EXACTLY as specified in CLAUDE.md
-    - Use service instances EXACTLY as configured in CLAUDE.md
-    - Use CLIs at the EXACT paths specified in CLAUDE.md
-    - For E2E test data seeding, connect to the database using the EXACT connection details from
-      CLAUDE.md
-    - For E2E test helper classes and seeding utilities, store ALL machine-specific values
-      (CLI paths, connection strings, credentials) in `<source-code-path>/e2e/.env` and read
-      them via `process.env.*` using `dotenv`. Populate `.env` with values from CLAUDE.md
-      for the current machine, but NEVER hardcode these values in TypeScript source files.
-      Commit `.env.example` (with placeholder descriptions) and ensure `e2e/.env` is in
-      `.gitignore` so that credentials and machine-specific paths are never committed.
-
-    **WHY**: Creative alternatives (Docker containers, alternative databases, alternative CLIs) connect to
-    DIFFERENT data stores or service instances than the ones the application is configured to use.
-    This produces wrong test results, missing data, and phantom failures. Hardcoding CLAUDE.md values
-    directly in TypeScript source code makes tests non-portable — other developers with different
-    machine setups cannot run the tests without modifying source files. Using `.env` files allows
-    each developer to configure their own paths and credentials once without touching committed code.
-
-15. **Source code goes directly in `<source-code-path>/` — NO nested subdirectories (CRITICAL)** —
-    The `<source-code-path>` (which defaults to `<app_folder>`) already contains a `context/` folder
-    with all generated artifacts. Source code files MUST be placed directly alongside `context/` in the same
-    directory — NOT inside a nested project subfolder. When using project scaffolding tools,
-    these tools create a new subdirectory by default. You MUST work around this by:
-    - Creating the project in a temporary subdirectory (e.g., `<source-code-path>/_temp_scaffold`)
-    - Moving ALL files (including dotfiles) up to `<source-code-path>/`
-    - Removing the empty temporary directory
-    - Verifying the `context/` folder was NOT overwritten or deleted
-
-    **WHY**: The folder structure convention is that `<app_folder>` contains both `context/` (artifacts)
-    and source code at the same level. A nested subdirectory breaks all relative paths, makes the
-    project structure confusing, and separates context from code unnecessarily.
-
-16. **Context artifacts must pre-exist** — This skill does NOT generate context artifacts. If
-    module models, mockups, specifications, or test specs are missing, stop and instruct the
-    user to run `/conductor-feature-prepare` first. Do NOT attempt to generate artifacts inline.
-
-17. **README.md is mandatory before completion** — After ALL modules are COMPLETED,
-    Phase 5 (Generate README.md) MUST run before outputting the completion promise.
-    Phase 5 generates the README with content derived from SPECIFICATION.md — do NOT
-    invent stack details, run commands, or architecture descriptions. Deployment
-    artifacts (Dockerfile, Kubernetes manifests) are NOT generated by this skill —
-    run `/depgen-k8s` independently after development is complete.
-
-18. **Spring Boot `app:` namespace for application-specific configuration (CRITICAL)** —
-    When the application stack is Spring Boot, ALL application-owned configuration in
-    `application.yml` MUST be placed under the top-level `app:` key. NEVER place
-    application-specific keys at the YAML root (e.g., top-level `notification:`,
-    `batch-job:`, `audit-trail:`) and NEVER place them under Spring framework namespaces
-    (`spring.*`, `server.*`, `management.*`, `logging.*`, `springdoc.*`).
-
-    **Grouping:**
-    - Cross-cutting values (version, CORS, shared security, shared messaging, shared
-      object-storage) sit directly under `app.*` with no module prefix.
-    - Per-module values MUST be grouped under `app.<module-kebab-case>.*`, one block
-      per module. A single config value per module still gets its own block.
-
-    **Binding:** every `app.*` subtree MUST be bound once via a `@ConfigurationProperties`
-    record in the owning module's `config` subpackage (or in the application-level
-    `config` subpackage for cross-cutting values). NEVER inject individual values via
-    `@Value("${app....}")` scattered across beans. Use kebab-case in YAML; Spring Boot's
-    relaxed binding maps to camelCase Java fields automatically. See SPECIFICATION.md
-    section "Application-Specific Configuration (`app:` namespace)" for the authoritative
-    rules and examples.
-
-19. **Code-level traceability is MANDATORY** — Every newly created source file (entity,
-    repository, service, mapper, controller, view template, listener, scheduled job,
-    configuration class, test file) MUST carry a top-of-file comment listing the
-    requirement codes it implements. The codes follow the formats emitted by
-    `util-ustagger` and `testgen-functional` — extract them verbatim from the module's
-    `SPEC.md` and `TEST_SPEC.md` traceability sections, never invent or reformat:
-
-    | Source | Code Pattern | Example |
-    |---|---|---|
-    | PRD.md → User Story | `US<II><5-digit#>` | `USHM00003` |
-    | PRD.md → NFR | `NFR<II><4-digit#>` | `NFRHM0003` |
-    | PRD.md → Constraint | `CONS<II><3-digit#>` | `CONSHM003` |
-    | PRD.md → Reference | `REF<II><4-digit#>` | `REFHM0003` |
-    | PRD.md → Test instruction | `TST<II><4-digit#>` | `TSTHM0003` |
-    | TEST_SPEC.md → Scenario | `<TYPE>-<MODULE-PREFIX>-<NNN>` | `NAV-LIN-001`, `CRUD-EMP-002`, `REG-QUO-001` |
-
-    `<II>` is the application's 2-letter initials. `<TYPE>` is one of `NAV`, `SRCH`,
-    `VIEW`, `CRUD`, `VAL`, `MAP`, `TOG`, `HIST`, `RAW`, `PAGE`, `REG`, `TSTI`.
-    `<MODULE-PREFIX>` is the 3-letter module prefix from the module model.
-
-    Use the language's native doc-comment style (Javadoc / PHPDoc / JSDoc / `{{-- --}}` /
-    `@* *@` / `<!-- -->` / `#`). Test names MUST be prefixed with the scenario ID copied
-    verbatim from TEST_SPEC.md Section 4 (e.g., `'NAV-LIN-001: Navigate to Location
-    Information screen'`) so test output is traceable to TEST_SPEC.md without consulting
-    IMPLEMENTATION_MODULE.md.
-
-    **Why**: `git blame`, IDE symbol search, and downstream audits must trace every line
-    of code back to a PRD.md requirement or a TEST_SPEC.md scenario directly.
-    IMPLEMENTATION_MODULE.md is a transient tracking file and is not the system of record
-    for traceability — the source code itself must be self-describing. This rule applies
-    to fresh creation; bug fixes layer additional `[BUG-XXX]` markers as defined by
-    `conductor-defect`.
+---
+name: conductor-feature-develop
+model: claude-sonnet-5
+effort: high
+description: >
+  Application development orchestrator — orchestrates full-stack code implementation
+  module-by-module (code + Playwright E2E tests), tracking progress in IMPLEMENTATION_MASTER.md
+  and per-module IMPLEMENTATION_MODULE.md. Takes an application name (mandatory), with optional
+  source code path, version and module filters. Version supports single version, comma-separated
+  list, "all", or omit for all versions. When multiple versions are resolved, they are processed
+  SEQUENTIALLY in ascending semver order — all modules for version N are fully implemented before
+  version N+1 begins. Requires context artifacts (module models, HTML mockups, technical
+  specifications, test specifications) to already exist — use "conductor-feature-prepare" first
+  if they don't. Use this skill when the user asks to "implement the application", "start
+  development", "build the app module by module", "orchestrate implementation", "develop from
+  specs", "implement from test specs", or any request to systematically develop a full application
+  from existing specs. Also trigger when user says "resume implementation" to continue from where
+  a previous session left off using IMPLEMENTATION_MASTER.md and IMPLEMENTATION_MODULE.md
+  progress files.
+---
+
+# Feature Conductor — Develop
+
+Application development orchestrator — implements full-stack code module-by-module, driven by
+test specs and tracked via implementation checklists. Requires context artifacts to already
+exist (use `conductor-feature-prepare` first).
+
+## Ralph Loop Integration (AUTO-START — MANDATORY)
+
+This skill AUTOMATICALLY starts a Ralph Loop to ensure complete implementation across all modules.
+Without Ralph Loop, the implementation may stop prematurely due to context window limits, API
+usage limits, or the agent incorrectly concluding work is "done enough". Ralph Loop ensures
+the same prompt is re-fed after each session exit, and the agent picks up where it left off
+using the IMPLEMENTATION_MASTER.md and IMPLEMENTATION_MODULE.md tracking files.
+
+### FIRST ACTION: Start Ralph Loop
+
+**BEFORE doing anything else** (before Phase 0, before reading any files), you MUST invoke the
+Ralph Loop skill using the Skill tool. This is a blocking requirement — do NOT proceed with
+any implementation work until Ralph Loop is active.
+
+**Invoke this immediately:**
+```
+Skill(skill: "ralph-loop:ralph-loop", args: "/conductor-feature-develop <application> [source:<source-code-path>] [version:<version>] [module:<module>] --completion-promise \"ALL MODULES IMPLEMENTED\" --max-iterations 100")
+```
+
+Replace `<application>` and optional arguments with the actual arguments provided by the user.
+
+**Example:** If the user invokes:
+```
+/conductor-feature-develop mainapp
+```
+
+Then invoke:
+```
+Skill(skill: "ralph-loop:ralph-loop", args: "/conductor-feature-develop mainapp --completion-promise \"ALL MODULES IMPLEMENTED\" --max-iterations 100")
+```
+
+If the user provides optional arguments:
+```
+/conductor-feature-develop mainapp version:v2 module:user
+```
+
+Then invoke:
+```
+Skill(skill: "ralph-loop:ralph-loop", args: "/conductor-feature-develop mainapp version:v2 module:user --completion-promise \"ALL MODULES IMPLEMENTED\" --max-iterations 100")
+```
+
+After Ralph Loop is active, proceed with Phase 0 (Resume Check) and continue normally.
+
+### How It Works
+
+1. This skill auto-starts a Ralph Loop with the orchestrator prompt as the loop body
+2. On each iteration, the agent reads IMPLEMENTATION_MASTER.md to find the next pending module
+3. The agent implements one or more modules until context runs out or a module completes
+4. When the agent tries to exit, the Ralph Loop stop hook re-feeds the same prompt
+5. The next iteration resumes from where the last one left off (tracked in IMPLEMENTATION_MASTER.md)
+6. When ALL modules are COMPLETED, the agent outputs the completion promise to exit the loop
+
+### Completion Promise
+
+When ALL modules in IMPLEMENTATION_MASTER.md have status `COMPLETED`, output the following
+promise tag to signal the Ralph Loop that implementation is finished:
+
+```
+<promise>ALL MODULES IMPLEMENTED</promise>
+```
+
+**CRITICAL**: Only output this promise when EVERY module in the execution order has:
+- Status = COMPLETED in IMPLEMENTATION_MASTER.md
+- All E2E tests passing
+- IMPLEMENTATION_MODULE.md fully updated
+
+Do NOT output the promise prematurely. Do NOT output it to escape the loop. The Ralph Loop
+will verify this tag and only exit when it is present.
+
+### Iteration Awareness
+
+At the START of every iteration (including the first), the agent MUST:
+1. Check if Ralph Loop is already active (if `.claude/ralph-loop.local.md` exists, skip re-invoking)
+2. Read IMPLEMENTATION_MASTER.md to determine what is already completed
+3. Find the FIRST module with status != COMPLETED
+4. If that module has an IMPLEMENTATION_MODULE.md, read it to find the last incomplete step
+5. Resume from exactly that point — do NOT re-implement completed work
+6. If ALL modules are COMPLETED, output the completion promise and stop
+
+### Never Stop Prematurely
+
+Within a Ralph Loop iteration, the agent MUST:
+- Continue implementing modules sequentially until context limits force a stop
+- After completing one module, IMMEDIATELY start the next pending module
+- Do NOT stop after a single module "to let the user review" — Ralph Loop handles iteration
+- Do NOT output the completion promise until ALL modules are verified complete
+- If approaching context limits mid-module, save progress to IMPLEMENTATION_MODULE.md so the
+  next iteration can resume from the exact step
+
+## Inputs
+
+The skill expects these arguments:
+
+```
+/conductor-feature-develop <application> [source:<source-code-path>] [version:<version>] [module:<module>]
+```
+
+| Argument | Required | Example | Description |
+|----------|----------|---------|-------------|
+| `<application>` | Yes | `mainapp` | Application name to locate the context folder |
+| `source:<path>` | No | `source:mainapp` | Path where source code resides. Defaults to `<app_folder>` (same as the resolved application folder) |
+| `version:<version>` | No | `version:v2` or `version:v1,v2` or `version:all` | Filter user stories and artifacts by version. Supports single version, comma-separated list, `all`, or omit for all versions. Multiple versions are processed sequentially in ascending semver order |
+| `module:<module>` | No | `module:user` | If provided, process only this module. If omitted, process all modules |
+
+### Input Resolution
+
+The application name is matched against root-level application folders:
+1. Strip any leading `<number>_` prefix from folder names (e.g., `1_hub_middleware` → `hub_middleware`)
+2. Match case-insensitively against the provided application name
+3. Accept snake_case, kebab-case, or title-case input
+4. If no match found, list available applications and stop
+
+### Auto-Resolved Paths
+
+| File | Resolved Path |
+|------|---------------|
+| PRD.md | `<app_folder>/context/PRD.md` |
+| Module Models | `<app_folder>/context/model/` |
+| HTML Mockups | `<app_folder>/context/mockup/` |
+| Specifications | `<app_folder>/context/specification/` |
+| Test Specs | `<app_folder>/context/test/` |
+| References | `<app_folder>/context/reference/` |
+| Development Output | `<app_folder>/context/develop/` |
+
+### Version Resolution
+
+The `version:` argument supports four forms:
+
+| Form | Example | Behavior |
+|------|---------|----------|
+| Single version | `version:v2` | Process only v2 |
+| Comma-separated list | `version:v1,v2,v3` | Process each version sequentially in ascending semver order |
+| Explicit all | `version:all` | Discover all versions from PRD.md, process sequentially in ascending semver order |
+| Omitted | _(no version arg)_ | Same as `version:all` |
+
+#### Version Discovery
+
+When `version:all` or omitted:
+1. Scan PRD.md for all `[vX.Y.Z]` version tags across all module sections
+2. Collect unique versions
+3. Sort in ascending semantic version order (v1.0.0 < v1.0.1 < v1.1.0 < v2.0.0)
+4. This becomes the ordered version list for sequential processing
+
+#### Sequential Version Processing Rule
+
+**Versions are ALWAYS processed one at a time, in ascending semver order.** All modules for
+version N must be fully implemented (status `COMPLETED`) before version N+1 begins. This ensures:
+- The application is scaffolded and fully functional at version N before N+1 changes are layered on
+- Feature implementations build incrementally on prior version work
+- E2E tests validate each version's functionality before the next version modifies the codebase
+
+#### How It Works with Multiple Versions
+
+1. **First version** (e.g., v1.0.0): Full implementation — scaffolding (Phase 2) + all modules (Phase 3)
+2. **Each subsequent version** (e.g., v1.0.1, v1.0.2): Version increment — reset affected modules
+   to PENDING, update the application version, then re-implement only modules with changes for
+   that version. The existing "Version Increment" logic in Phase 0 handles this naturally.
+3. **README** (Phase 5): Generated ONCE after the LAST version in the list is fully
+   implemented
+
+### Application Folder Structure (Expected)
+
+Source code and context artifacts coexist in the same `<app_folder>`. The `context/` subfolder
+holds all generated artifacts (models, mockups, specs, tests, tracking). All other files and
+folders at the root of `<app_folder>` are **source code** (e.g., `app/`, `Modules/`, `resources/`,
+`composer.json`, `pom.xml`, `src/`, etc.).
+
+**CRITICAL**: When scaffolding a new project (e.g., `composer create-project`, `mvn archetype:generate`),
+the source code MUST be placed directly in `<source-code-path>/` — NOT in a nested subdirectory.
+For example, with `composer create-project laravel/laravel`, you must either:
+- Create in a temp directory and move all files (including dotfiles) up to `<source-code-path>/`, OR
+- Use a technique that installs directly into the existing directory
+
+The `context/` folder already exists in `<app_folder>` and must NOT be overwritten or deleted.
+
+```
+<app_folder>/                      # = <source-code-path> (by default)
+  context/                         # Context artifacts (NOT source code)
+    PRD.md
+    model/
+      MODEL.md
+      <module-slug>/
+        model.md
+        schemas.json
+        document-model.mermaid
+    mockup/
+      MOCKUP.html
+      mockup-manifest.json
+      <role>/content/
+    specification/
+      SPECIFICATION.md
+      <module-slug>/SPEC.md
+    test/
+      TEST_PLAN.md
+      <module-slug>/TEST_SPEC.md
+    reference/
+    develop/                       # Implementation tracking files
+  (source code files)              # All other files are source code
+    app/                           # Laravel: app directory
+    Modules/                       # Laravel: nwidart modules
+    resources/                     # Laravel: views, CSS, JS
+    routes/                        # Laravel: route files
+    config/                        # Laravel: config files
+    composer.json                  # Laravel: PHP dependencies
+    package.json                   # Laravel: JS dependencies
+    ...                            # (or src/, pom.xml for Spring Boot, etc.)
+```
+
+## Pre-Requisite: Project Information from CLAUDE.md (MANDATORY)
+
+**CLAUDE.md is automatically loaded into context** at the start of every session. It contains
+project details, infrastructure paths, credentials, and configuration. You do NOT need to read
+it manually — the information is already available in your context.
+
+**Before executing ANY tool command** (Maven build, Spring Boot run, database CLI, Keycloak CLI,
+Playwright test, npm start, etc.), use the following from CLAUDE.md (already in context):
+
+- **JDK path** — Use the exact `JAVA_HOME` path specified in CLAUDE.md
+- **Maven path** — Use the exact Maven binary path specified in CLAUDE.md
+- **Database credentials** — Host, port, username, password for MongoDB, MySQL, etc.
+- **Message queue credentials** — RabbitMQ host, port, username, password
+- **Keycloak configuration** — Host, admin credentials, CLI path
+- **Mailcatcher configuration** — SMTP host/port, web UI URL
+- **Any other infrastructure details** — Ports, URLs, connection strings
+
+**WHY**: CLAUDE.md contains the actual system paths, credentials, and configuration for the
+developer's machine. Hardcoding or guessing these values will cause commands to fail. Every shell
+command that involves JDK, Maven, database access, or any external service MUST use the values
+from CLAUDE.md.
+
+## PRD.md Extended Sections
+
+During implementation, check PRD.md for the following extended sections and use them as high-level context:
+
+### Design System
+
+If PRD.md contains a `# Design System` section, read it and any file it references (e.g., `[DESIGN_SYSTEM.md](reference/DESIGN_SYSTEM.md)`) before implementing **any UI module** (Blade views, JTE templates, React components, etc.). Treat the design system as the **authoritative source** for code-level styling:
+
+- **Color tokens, typography, spacing, radii, shadows** — apply directly in Tailwind config, CSS variables, or MUI theme. Do not invent new values.
+- **Component patterns** — buttons, forms, tables, dialogs, alerts must match the design system's visual rules and accessibility behavior.
+- **Branding** — logos, favicons, and brand voice must be applied consistently across all rendered views.
+- **Accessibility rules** — WCAG level, contrast ratios, focus states, keyboard navigation requirements declared in the design system are non-negotiable.
+
+**Conflict resolution**: If `SPECIFICATION.md`'s "Design System Integration" subsection contradicts the PRD.md design system file (e.g., different color values, different component variants), the **PRD.md design system file wins**. Flag the discrepancy for human review and proceed with the design system file.
+
+If absent, fall back to `SPECIFICATION.md`'s design system guidance and CLAUDE.md's CSS framework declaration (existing behavior).
+
+### Architecture Principle
+
+If PRD.md contains an `# Architecture Principle` section, read it and use as implementation constraints:
+- **Stateless**: Ensure no module implementation stores data in HTTP session — user context must come from JWT tokens or external identity providers
+- **Event-driven**: Ensure inter-module communication uses event publishing (e.g., Spring ApplicationEvent, Laravel Event) rather than direct service injection across module boundaries
+- **Message driven**: When implementing message consumers/publishers, follow the patterns described in the architecture (e.g., dedicated queues per country, independent queue configurations)
+- **Monolithic with modular architecture**: Modules can share the same database but should not directly access each other's repositories — use events or service interfaces
+
+If absent, rely on SPECIFICATION.md for architectural guidance (existing behavior).
+
+### High Level Process Flow
+
+If PRD.md contains a `# High Level Process Flow` section, use it as the **implementation blueprint** for message-driven modules:
+1. Implement flow steps in order: (1) message consumer, (2) validation logic, (3) data persistence, (4) ACK/NACK publishing
+2. Each flow step maps to a specific method in the service layer
+3. Treat flow steps as mini-specifications within each module's implementation
+4. After implementing all steps of a flow, verify the complete end-to-end flow works before moving to the next module
+
+If absent, implement from SPECIFICATION.md messaging sections only (existing behavior).
+
+---
+
+## Pre-Requisite: Context Artifacts Must Exist
+
+Before starting implementation, verify that all required context artifacts exist:
+- `<app_folder>/context/model/` — must contain module model files
+- `<app_folder>/context/mockup/` — must contain HTML mockup files
+- `<app_folder>/context/specification/` — must contain specification files
+- `<app_folder>/context/test/` — must contain test specification files
+
+If any artifacts are missing, **stop and inform the user** to run `/conductor-feature-prepare`
+first. Do NOT attempt to generate artifacts — that is the responsibility of the prepare skill.
+
+## Version Gate
+
+Before starting any work, check `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
+
+1. If `<app_folder>/CHANGELOG.md` does not exist, skip this check (first-ever execution for this application).
+2. If `<app_folder>/CHANGELOG.md` exists, scan all `## vX.Y.Z` headings and determine the **highest version** using semantic versioning comparison.
+3. Apply the gate based on the version argument form:
+   - **Single version**: If requested version **<** highest version → **STOP immediately**. Print: `"Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."`
+   - **Comma-separated list**: Check the **lowest** version in the list. If lowest **<** highest version → **STOP immediately**. Print: `"Version {lowest} in the provided list is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."`
+   - **`version:all` or omitted**: Skip this check — when processing all discovered versions, historical versions are expected.
+
+### Redo/Redevelop Guard
+
+This guard prevents accidental re-execution of already-completed work while allowing
+incremental processing of new versions. It uses a **partition and filter** approach.
+
+1. Resolve the version list (see Version Resolution).
+2. **Partition** the resolved versions into two groups:
+   - `completed_versions` — versions that have a matching `conductor-feature-develop` entry
+     in `<app_folder>/CHANGELOG.md`
+   - `new_versions` — versions with NO matching entry
+3. **Decision**:
+
+   | `new_versions` | `completed_versions` | Artifacts/code exist? | Action |
+   |---------------|---------------------|----------------------|--------|
+   | Not empty | Any (including empty) | Yes (expected — prior versions built them) | **Proceed with `new_versions` only** — filter out completed versions. Existing code is the base for version increment. |
+   | Not empty | Any | No | **Proceed with all resolved versions** — no prior code, start from scratch. |
+   | Empty | Not empty | Yes | **STOP**. Print: `"All requested versions ({list}) for {application} were already developed (recorded in <app_folder>/CHANGELOG.md) and artifacts/code still exist. To redo, first delete the existing IMPLEMENTATION_MASTER.md and source code, then re-run this skill."` |
+   | Empty | Not empty | No | **Proceed with all resolved versions** — code was cleaned up, this is a legitimate redo. |
+
+   **Artifacts/code exist check**: `<app_folder>/context/develop/IMPLEMENTATION_MASTER.md`
+   exists, OR source code files exist in `<app_folder>/` (e.g., `pom.xml`, `composer.json`,
+   `package.json`, or `src/` directory).
+
+4. **Update the resolved version list** to contain only the versions that will be processed
+   (either `new_versions` or all versions for redo). This filtered list is what the Version
+   Processing Order table and the sequential version loop will use.
+
+## Workflow
+
+### Phase 0: Resume Check (Runs Every Ralph Loop Iteration)
+
+This phase runs at the START of every iteration, including the first. In a Ralph Loop,
+each iteration begins fresh with the same prompt, so the agent MUST read the tracking
+files to understand what has already been completed.
+
+0. **Auto-Start Ralph Loop** — Check if `.claude/ralph-loop.local.md` exists. If it does NOT
+   exist, Ralph Loop is not yet active. Invoke it NOW using the Skill tool:
+   ```
+   Skill(skill: "ralph-loop:ralph-loop", args: "<the full /conductor-feature-develop invocation with args> --completion-promise \"ALL MODULES IMPLEMENTED\" --max-iterations 100")
+   ```
+   If `.claude/ralph-loop.local.md` already exists, Ralph Loop is active — skip this step.
+
+1. **Use project information from CLAUDE.md (already in context)** — extract JDK path, Maven path, database credentials,
+   message queue credentials, Keycloak config, and all infrastructure details. These values
+   are required for every subsequent tool command in this session.
+2. **Verify context artifacts exist** — Check that model/, mockup/, specification/, and test/
+   folders contain the required files. If missing, stop and inform user to run
+   `/conductor-feature-prepare` first.
+3. Check if `<app_folder>/context/develop/IMPLEMENTATION_MASTER.md` exists
+4. If it exists, read it and determine the current state:
+   - Scan the Module Implementation Status table for the FIRST module with status != COMPLETED
+   - If ALL modules are COMPLETED:
+     - **Sequential version loop check**: Resolve the version list (see Version Resolution).
+       Read the **Version Processing Order** table in IMPLEMENTATION_MASTER.md (if it exists)
+       to determine which versions have been completed.
+       - Find the FIRST version in the resolved list that is NOT yet tracked or NOT `COMPLETED`
+         in the Version Processing Order table.
+       - If such a version exists, this is the **next version to process** — perform the
+         version increment steps below and proceed to Phase 3.
+       - If ALL versions in the resolved list are `COMPLETED`, proceed to the README check below.
+     - **Version increment** — For each new version to process:
+       1. Update IMPLEMENTATION_MASTER.md: add the new version to the Version Processing Order
+          table, reset affected modules to PENDING status.
+       2. **Update the application version** in the project manifest and configuration:
+          - **Spring Boot**: Update `<version>` in `pom.xml` and `APP_VERSION` in `.env`
+          - **Laravel**: Update `version` in `composer.json` and `APP_VERSION` in `.env`
+          - **React / Node.js**: Update `version` in `package.json` and `VITE_APP_VERSION`
+            in `.env.development` (or `APP_VERSION` in `.env` for Node.js backends)
+          - **application.yml / config files**: If `app.version` has a hardcoded default in
+            `application.yml` (e.g., `${APP_VERSION:1.0.0}`), update the default to the new
+            version (e.g., `${APP_VERSION:1.0.4}`)
+          - **config/app.php** (Laravel): Update the default in `env('APP_VERSION', '1.0.0')`
+            to the new version
+          The version displayed in the application footer (or API info endpoint) MUST reflect
+          the new version after this update.
+       3. Proceed to Phase 3 (Implementation) for the affected modules.
+     - **README check**: If the top-level `**Status**:` in IMPLEMENTATION_MASTER.md is NOT
+       yet `COMPLETED`, proceed to Phase 5 (Generate README.md) — all modules are done but
+       README hasn't been generated and tracking hasn't been finalized yet.
+     - If ALL versions are completed AND top-level status is already
+       `COMPLETED` → output `<promise>ALL MODULES IMPLEMENTED</promise>` and stop
+   - Otherwise, read its `IMPLEMENTATION_MODULE.md` for detailed progress
+   - Resume from the last incomplete step in the checklist
+5. If it does not exist, proceed to Phase 1 (Planning — fresh start)
+
+### Phase 1: Planning
+
+1. **Use project information from CLAUDE.md (already in context)** — extract all paths, credentials,
+   and infrastructure configuration. This is the single source of truth for JDK, Maven, database,
+   message queue, Keycloak, and all other tool configurations.
+2. Read `<app_folder>/context/test/TEST_PLAN.md`
+3. Extract the **Execution Order** (Section 5) and **Layer Classification** (Section 4)
+4. The execution order defines the module sequence — use it as-is
+5. Read `<app_folder>/context/specification/SPECIFICATION.md` for shared infrastructure context
+
+Create `<app_folder>/context/develop/IMPLEMENTATION_MASTER.md` with this structure:
+
+```markdown
+# Implementation Master - <Application Name>
+
+**Started**: <date>
+**Source Code**: <source-code-path>
+**Context**: <app_folder>/context
+**Resolved Versions**: <comma-separated sorted version list, e.g., "v1.0.0, v1.0.1, v1.0.2">
+**Status**: IN PROGRESS
+
+---
+
+## Version Processing Order
+
+| # | Version | Module Count | Status | Started | Completed |
+|---|---------|-------------|--------|---------|-----------|
+| 1 | v1.0.0 | 12 | NEW | - | - |
+| 2 | v1.0.1 | 3 | NEW | - | - |
+| 3 | v1.0.2 | 1 | NEW | - | - |
+
+> **Processing Rule**: All modules for version N must reach COMPLETED before version N+1 begins.
+> **First version**: full scaffolding + all modules. **Subsequent versions**: version increment — only modules with changes.
+
+---
+
+## Execution Order
+
+<Copy the execution order tree from TEST_PLAN.md>
+
+---
+
+## Module Implementation Status
+
+| # | Module | Layer | Version | Status | Started | Completed | Notes |
+|---|--------|-------|---------|--------|---------|-----------|-------|
+| 1 | User | L1 | v1.0.0 | PENDING | - | - | |
+| 2 | Location Information | L2 | v1.0.0 | PENDING | - | - | |
+...
+
+> The **Version** column tracks which version is currently being implemented for that module.
+> When a version increment occurs, affected modules are reset to PENDING with the new version.
+
+---
+
+## Module Details
+
+### 1. User
+
+**Resources**:
+- User Story: <list relevant story IDs>
+- Model: `model/user/model.md`
+- Specification: `specification/user/SPEC.md`
+- Test Spec: `test/user/TEST_SPEC.md`
+- Mockup: `mockup/<role>/content/<screen>.html`
+
+**Dependencies**: None
+
+---
+
+### 2. Location Information
+...
+```
+
+**IMPORTANT — Single version shortcut**: When only a single version is resolved, the Version
+Processing Order table has a single row. The behavior is identical to the original single-version
+flow — no extra complexity.
+
+**IMPORTANT — Module Count per version**: For the FIRST version, Module Count = total modules
+(full implementation). For subsequent versions, Module Count = only modules that have new/changed
+user stories for that version.
+
+### Phase 2: Pre-Implementation (Scaffolding)
+
+Read the SPECIFICATION.md shared infrastructure sections and scaffold the project.
+
+**CRITICAL — Source Code Placement Rule:**
+All source code MUST be placed directly in `<source-code-path>/` (which defaults to `<app_folder>/`).
+The `context/` folder already exists there and must be preserved. When using project creation tools
+like `composer create-project` or `mvn archetype:generate`, ensure you do NOT create a nested
+subdirectory. Instead:
+- For Laravel: Create the project in a temporary directory (e.g., `<source-code-path>/_temp_scaffold`),
+  then move ALL files (including dotfiles) from that temp directory up to `<source-code-path>/`,
+  then remove the empty temp directory. This avoids overwriting the existing `context/` folder.
+- For Spring Boot: Same approach — scaffold into a temp dir, then move files up.
+- NEVER use the project slug/name as the target directory if it would create a nested folder.
+
+**Scaffolding Checklist** (adapt to the technology stack from SPECIFICATION.md):
+
+1. **Project structure**: Create the project skeleton directly in `<source-code-path>/`
+2. **Build & dependency configuration**: composer.json / pom.xml / build.gradle with all dependencies
+3. **Application version**: Set the application version in the project manifest using the
+   FIRST version in the resolved version list (the version currently being implemented).
+   If no version argument was provided (all versions), use the first discovered version.
+   If no versions exist at all, use `1.0.0`.
+   - **Spring Boot**: Set `<version>` in `pom.xml` (e.g., `<version>1.0.0</version>`) and
+     `APP_VERSION` in `.env`
+   - **Laravel**: Set `version` in `composer.json` and `APP_VERSION` in `.env`
+   - **React / Node.js**: Set `version` in `package.json` and `VITE_APP_VERSION` in
+     `.env.development` (or `APP_VERSION` in `.env` for Node.js backends)
+   - The version in the manifest MUST match the version in the environment variable
+   - For multi-version processing, this version will be updated during each version increment
+     in the Phase 0 resume check
+4. **Application configuration**: .env, config files, or application.yml as appropriate
+4. **Security configuration**: Keycloak/OAuth2 or other auth provider setup
+5. **Shared layouts**: Blade / JTE / other template layout files (header, footer, sidebar)
+6. **Shared components**: UI components (Tailwind), JS structure, CSS
+7. **Data access layer**: Base repository / model configuration
+8. **Error handling**: Global exception handlers
+9. **Theming**: Theme configuration from spec
+10. **Pagination**: Shared pagination support
+11. **Messaging**: Message queue configuration if applicable
+12. **Scheduling**: Scheduled task configuration if applicable
+13. **Playwright test project**: Initialize Playwright in `<source-code-path>/e2e/` with:
+    - `package.json` with Playwright and `dotenv` dependencies
+    - `playwright.config.ts` with base URL read from `process.env.TEST_APP_BASE_URL`
+      (loaded via `dotenv` at the top of the config)
+    - `.env.example` — committed to git, contains all `TEST_*` environment variable names
+      with placeholder descriptions (from TEST_PLAN.md Section 2a). No real credentials.
+    - `.env` — contains actual values from CLAUDE.md for the current developer's machine.
+      Pre-populate with values from CLAUDE.md. This file MUST NOT be committed to git.
+    - **`.gitignore` update (MANDATORY)** — Add the following entries to the project's
+      `.gitignore` file (or create it if it does not exist):
+      - `e2e/.env` — prevents credentials and machine-specific paths from being committed
+      - `e2e/node_modules/` — prevents Playwright and dotenv dependencies from being committed
+      Verify both entries exist before proceeding with any other scaffolding step.
+    - `helpers/config.ts` — **single source of truth** for all infrastructure config.
+      Loads `dotenv/config` and exports named constants for every `TEST_*` env var
+      (DB, MQ, SSO, app URL). All other helpers and spec files import from this file
+      instead of reading `process.env` directly or hardcoding values.
+    - Helper utilities for login, navigation, data seeding — all helpers MUST import
+      infrastructure values from `helpers/config.ts`. **NEVER hardcode** machine-specific
+      paths, CLI tool locations, database credentials, or SSO admin passwords in any
+      TypeScript source file (helpers OR spec files).
+14. **Mockup baseline screenshots**: Capture baseline screenshots from HTML mockups for visual consistency testing:
+    - Start the shared Mockup Hub (`npm start` in `<root>/mockup/` — zero dependencies, no
+      npm install needed; port from `PORT` env or `mockup.config.json`, default: first
+      unused port from 4000 — the effective URL is printed on start)
+    - Screens are served at `http://localhost:<hub_port>/<app_slug>/<role>/<page>`
+      (shadcn mockups must be built first: `npm run build` in the app's mockup folder)
+    - For each role/screen in the mockup, capture a screenshot to `<source-code-path>/e2e/visual-baselines/`
+    - Stop the Mockup Hub after capture
+    - These baselines will be compared against the application output during module testing
+
+After scaffolding, verify the application compiles/starts. **Use the exact paths, CLIs, and
+credentials from `CLAUDE.md`** — do NOT use generic commands or assume default paths:
+```bash
+# Examples (actual paths come from CLAUDE.md):
+
+# Laravel:
+<php-path-from-CLAUDE.md>/php.exe artisan --version
+<php-path-from-CLAUDE.md>/php.exe artisan serve
+
+# Spring Boot:
+JAVA_HOME="<jdk-path>" <maven-path>/mvn -f <source-code-path>/pom.xml clean compile
+```
+
+Update IMPLEMENTATION_MASTER.md: mark scaffolding as COMPLETED.
+
+### Phase 3: Implementation (Per Module)
+
+For each module in execution order:
+
+#### Step 3.1: Initialize Module Tracking
+
+Create `<app_folder>/context/develop/<module-slug>/IMPLEMENTATION_MODULE.md`:
+
+```markdown
+# Implementation - <Module Name>
+
+**Module**: <Module Name>
+**Layer**: <Layer>
+**Status**: IN PROGRESS
+**Started**: <date>
+
+---
+
+## Resources
+
+| Resource | Path |
+|----------|------|
+| User Stories | <IDs from PRD.md> |
+| Bug Fixes | <IDs from PRD.md `### Bug` section, if any> |
+| Model | `model/<module-slug>/model.md` |
+| Specification | `specification/<module-slug>/SPEC.md` |
+| Test Spec | `test/<module-slug>/TEST_SPEC.md` |
+| Mockup | `mockup/<role>/content/<screen>.html` |
+
+---
+
+## Implementation Checklist
+
+### UI Layer
+
+- [ ] 1. Read and analyze module resources
+- [ ] 2. Implement module model (entities/documents)
+- [ ] 3. Implement repository layer
+- [ ] 4. Implement service layer
+- [ ] 5. Implement controller layer
+- [ ] 6. Implement view templates (list, detail, form pages)
+- [ ] 7. Write Playwright E2E tests (UI scenarios)
+- [ ] 8. Run E2E tests and verify
+
+### User Stories
+
+<For each user story ID from the module's SPEC.md traceability section, add a checklist item:>
+- [ ] USxxxx: <description>
+
+### Non-Functional Requirements
+
+<For each NFR ID from the module's SPEC.md traceability section, add a checklist item:>
+- [ ] NFRxxxx: <description>
+
+### Messaging Pipeline (if applicable — include only if module has messaging NFRs)
+
+- [ ] Implement message consumer
+- [ ] Implement message validator
+- [ ] Implement ACK publisher
+- [ ] Implement forward publisher
+- [ ] Implement queue configuration
+- [ ] Implement module events
+- [ ] Write E2E tests for message processing flow
+
+### Scheduled Jobs (if applicable — include only if module has scheduling NFRs)
+
+- [ ] Implement scheduled job
+- [ ] Write E2E tests for scheduled job
+
+### Visual Consistency
+
+- [ ] Visual consistency testing (mockup vs application)
+- [ ] Fix visual deviations (if any)
+
+---
+
+## Implementation Log
+
+### Step 1: Analyze Module Resources
+<timestamp> - Started
+- Read model.md, SPEC.md, TEST_SPEC.md, mockup HTML
+- Key findings: ...
+```
+
+#### Step 3.2: Analyze Module Resources
+
+Read ALL module-specific resources:
+- `model/<module-slug>/model.md` — document structure, collections, fields
+- `model/<module-slug>/schemas.json` — JSON schema examples
+- `specification/<module-slug>/SPEC.md` — full technical specification
+- `test/<module-slug>/TEST_SPEC.md` — test scenarios, seeding scripts, assertions
+- `mockup/<role>/content/<module_screen>.html` — UI mockup for visual reference
+- Relevant entries from `PRD.md` — user stories for this module
+- `### Bug` section from `PRD.md` for this module (if present) — previously fixed bugs
+- Relevant message files from `reference/message/` if applicable
+
+**Bug Regression Awareness (Redo/Redevelop Scenario):**
+If the module has a `### Bug` section in PRD.md, this means the application was previously
+developed and users reported bugs that were fixed. During redevelopment, these bug fixes MUST
+be incorporated into the implementation to prevent the same bugs from reappearing:
+- Read each bug entry (e.g., `[BUG-024] Fixed Message ID link...`) to understand what was broken and how it was fixed
+- Treat each bug fix as an implicit requirement — the implementation must produce behavior consistent with the fix description
+- If a bug fix contradicts or supplements a user story or NFR, the bug fix takes precedence (it reflects the latest validated behavior)
+
+Update IMPLEMENTATION_MODULE.md: mark step 1 complete with findings summary.
+
+#### Step 3.3: Implement Module Code
+
+Follow the module SPEC.md to implement, in order:
+1. **Entity/Document classes** — from model.md + schemas.json
+2. **Repository interfaces** — from SPEC.md data access section
+3. **Service classes** — business logic from SPEC.md
+4. **Mappers** — if specified in SPEC.md
+5. **Controller classes** — routes, request handling from SPEC.md
+6. **View templates** — from SPEC.md view section + mockup HTML
+7. **Message listeners** — from SPEC.md messaging section (if applicable)
+8. **Scheduled jobs** — from SPEC.md scheduling section (if applicable)
+
+**Traceability comment (MANDATORY)** — Every newly created source file (entity, repository,
+service, mapper, controller, view template, listener, scheduled job, configuration class)
+MUST begin with a top-of-file comment listing the requirement codes it implements.
+Extract the codes verbatim from the module's `SPEC.md` traceability section. Use the
+9-character codes emitted by `util-ustagger` — DO NOT invent or reformat the codes:
+
+| Category | Pattern | Example (`HM` initials) |
+|---|---|---|
+| User Story | `US<II><5-digit#>` | `USHM00003` |
+| Non-Functional Requirement | `NFR<II><4-digit#>` | `NFRHM0003` |
+| Constraint | `CONS<II><3-digit#>` | `CONSHM003` |
+| Reference | `REF<II><4-digit#>` | `REFHM0003` |
+
+Where `<II>` is the application's 2-letter initials (e.g., `HM` for Hub Middleware).
+The actual codes in any given file come from the module's `SPEC.md` traceability section,
+NOT from this template — never invent codes that do not appear in PRD.md.
+
+Use the language's native doc-comment style — Javadoc / PHPDoc / JSDoc (`/** ... */`)
+for code files, `{{-- ... --}}` for Blade, `@* ... *@` for JTE, `<!-- ... -->` for HTML,
+`# ...` for YAML / `.env` / `.properties`.
+
+Example (Java service for the Employer module of an app with initials `HM`):
+```java
+/**
+ * Implements: USHM00003, USHM00006
+ * NFR: NFRHM0003 (audit logging), NFRHM0006 (pagination)
+ * Constraints: CONSHM003
+ */
+public class EmployerService { ... }
+```
+
+This makes `git blame`, IDE symbol search, and downstream audits trace every line back to
+PRD.md directly — IMPLEMENTATION_MODULE.md is a transient tracking file and is not the
+system of record for traceability.
+
+After each major component, update IMPLEMENTATION_MODULE.md checklist.
+
+#### Step 3.4: Implement Playwright E2E Tests
+
+From the module's TEST_SPEC.md:
+
+1. **Create test file**: `<source-code-path>/e2e/tests/<module-slug>.spec.ts`
+2. **Implement data seeding**: Use the seeding scripts from TEST_SPEC.md Section 4.
+   All seeding helper functions MUST read paths, credentials, and connection strings
+   from `process.env.*` (loaded via `dotenv` from `<source-code-path>/e2e/.env`).
+   **NEVER hardcode** machine-specific values (file paths, CLI tool locations, database
+   hosts/passwords, SSO admin credentials) in TypeScript source code.
+3. **Implement test scenarios**: Convert each scenario from TEST_SPEC.md Section 5 into Playwright tests
+4. **DO NOT implement cleanup scripts** — test data must persist for downstream modules
+
+Pattern for shared config helper (`e2e/helpers/config.ts`) — **single source of truth**
+for all infrastructure configuration. Every other helper and spec file imports from here
+instead of reading `process.env` directly or hardcoding values:
+```typescript
+import 'dotenv/config';  // loads .env from e2e/ directory
+
+// Application
+export const APP_BASE_URL = process.env.TEST_APP_BASE_URL!;
+
+// Database (include only what exists in CLAUDE.md)
+export const DB_URI = process.env.TEST_DB_URI!;           // MongoDB
+// OR for MySQL/PostgreSQL:
+// export const DB_HOST = process.env.TEST_DB_HOST!;
+// export const DB_PORT = process.env.TEST_DB_PORT!;
+// export const DB_USER = process.env.TEST_DB_USER!;
+// export const DB_PASSWORD = process.env.TEST_DB_PASSWORD!;
+// export const DB_NAME = process.env.TEST_DB_NAME!;
+
+// Message Queue (include only if MQ exists in CLAUDE.md)
+export const MQ_HOST = process.env.TEST_MQ_HOST!;
+export const MQ_PORT = process.env.TEST_MQ_PORT!;
+export const MQ_USER = process.env.TEST_MQ_USER!;
+export const MQ_PASSWORD = process.env.TEST_MQ_PASSWORD!;
+export const MQ_VHOST = process.env.TEST_MQ_VHOST!;
+export const MQ_URL = process.env.TEST_MQ_URL!;
+
+// SSO / Auth (include only if SSO exists in CLAUDE.md)
+export const SSO_HOST = process.env.TEST_SSO_HOST!;
+export const SSO_ADMIN_USER = process.env.TEST_SSO_ADMIN_USER!;
+export const SSO_ADMIN_PASSWORD = process.env.TEST_SSO_ADMIN_PASSWORD!;
+export const SSO_CLI_PATH = process.env.TEST_SSO_CLI_PATH!;
+export const SSO_REALM = process.env.TEST_SSO_REALM!;
+```
+
+Pattern for domain-specific helper (e.g., `e2e/helpers/keycloak.ts`) — imports config
+from `config.ts`, never reads `process.env` directly:
+```typescript
+import { execSync } from 'child_process';
+import { SSO_CLI_PATH, SSO_HOST, SSO_ADMIN_USER, SSO_ADMIN_PASSWORD, SSO_REALM } from './config';
+
+function runKcadm(command: string): string {
+  try {
+    return execSync(`"${SSO_CLI_PATH}" ${command}`, { encoding: 'utf-8', timeout: 30000 });
+  } catch (error: any) {
+    return error.stdout || error.stderr || error.message || '';
+  }
+}
+
+export function kcadmConfig(): void {
+  runKcadm(`config credentials --server ${SSO_HOST} --realm master --user ${SSO_ADMIN_USER} --password ${SSO_ADMIN_PASSWORD}`);
+}
+// ... remaining helper functions use the config imports above
+```
+
+**No hardcoded config in spec files**: If a spec file needs infrastructure values (e.g.,
+database connection for direct seeding, MQ host for publishing, mail server URL), it MUST
+import them from `helpers/config.ts` — never hardcode them inline in the spec. This applies
+to ALL spec files, not just those with dedicated helper modules.
+
+**Test naming convention (MANDATORY)** — Every test name MUST be prefixed with the
+**scenario ID from TEST_SPEC.md Section 4** so test output (CI logs, reports) is traceable
+to TEST_SPEC.md without consulting IMPLEMENTATION_MODULE.md. The scenario IDs are emitted
+by `testgen-functional` and follow the pattern `<TYPE>-<MODULE-PREFIX>-<NNN>`, where
+`<TYPE>` is one of `NAV`, `SRCH`, `VIEW`, `CRUD`, `VAL`, `MAP`, `TOG`, `HIST`, `RAW`,
+`PAGE`, `REG`, or `TSTI`, and `<MODULE-PREFIX>` is the 3-letter module prefix from the
+module model (e.g., `LIN` for Location Information, `EMP` for Employer, `QUO` for Quota).
+
+Format: `'<scenario-id>: <scenario-name>'` — copied verbatim from TEST_SPEC.md Section 4.
+Do NOT invent IDs; do NOT collapse or reformat them.
+
+Each test MUST also carry a JSDoc traceability comment listing the source codes from
+the scenario's **Source** field in TEST_SPEC.md — these are the same `USHM#####`,
+`NFRHM####`, `CONSHM###`, `TSTHM####`, and `[BUG-XXX]` codes that link the scenario back
+to PRD.md. Copy them verbatim.
+
+Pattern for test file:
+```typescript
+import { test, expect } from '@playwright/test';
+import { DB_URI, MQ_URL } from '../helpers/config';  // import what this spec needs
+
+/**
+ * Module: <Module Name>
+ * Implements scenarios: NAV-LIN-001, SRCH-LIN-001, CRUD-LIN-001, CRUD-LIN-002
+ *   (copied verbatim from TEST_SPEC.md Section 4)
+ */
+test.describe('<Module Name>', () => {
+  // Data seeding (runs once before all tests in this module)
+  test.beforeAll(async () => {
+    // Execute seeding script from TEST_SPEC.md Section 4
+    // All infrastructure values come from helpers/config.ts — never hardcode
+  });
+
+  // DO NOT add afterAll cleanup — data persists for dependent modules
+
+  /**
+   * Covers: USHM00003, USHM00006
+   * NFR: NFRHM0003
+   * Bug regression: [BUG-024]   // include only if scenario covers a previously-fixed bug
+   */
+  test('NAV-LIN-001: Navigate to Location Information screen', async ({ page }) => {
+    // Steps from the matching TEST_SPEC.md Section 4 scenario
+  });
+});
+```
+
+#### Step 3.5: Run E2E Tests
+
+```bash
+cd <source-code-path>/e2e && npx playwright test tests/<module-slug>.spec.ts
+```
+
+- If tests pass: proceed to visual consistency testing (Step 3.6)
+- If tests fail: analyze failures, fix code, re-run (do NOT clean test data unless re-seeding is required for retest)
+
+#### Step 3.6: Visual Consistency Testing (Mockup vs Application)
+
+After functional E2E tests pass, compare the UI output of the application against the approved HTML mockup screens. The goal is to verify **aesthetic consistency** — colors, alignment, padding, margins, font sizes, layout structure — NOT content (data values will differ).
+
+**Process:**
+
+1. **Identify mockup screens** for this module from `<app_folder>/context/mockup/<role>/content/` that correspond to the implemented views.
+
+2. **Capture mockup baselines** (if not already captured during scaffolding):
+   - Start the shared Mockup Hub: `cd <root>/mockup && npm start` (no npm install needed)
+   - Navigate to each screen for the module at
+     `http://localhost:<hub_port>/<app_slug>/<role>/<page>` and capture a screenshot
+   - Save to `<source-code-path>/e2e/visual-baselines/<module-slug>/<screen-name>.png`
+   - Stop the Mockup Hub
+
+3. **Create visual comparison test**: `<source-code-path>/e2e/tests/<module-slug>.visual.spec.ts`
+   - For each screen in the module, navigate to the corresponding application page
+   - Capture a screenshot of the application output
+   - Use Playwright's `toHaveScreenshot()` with a **threshold** to allow content differences while catching layout/styling deviations
+   - Compare against the mockup baseline
+
+4. **Visual test pattern**:
+```typescript
+import { test, expect } from '@playwright/test';
+import { loginAs } from '../helpers/auth';
+import path from 'path';
+
+test.describe('<Module Name> - Visual Consistency', () => {
+  test('<screen-name> matches mockup layout', async ({ page }) => {
+    await loginAs(page, '<role>');
+    await page.goto('<app-route-for-screen>');
+    await page.waitForLoadState('networkidle');
+
+    // Compare against mockup baseline — threshold allows content differences
+    // but catches color, alignment, padding, margin, and layout deviations
+    await expect(page).toHaveScreenshot('<module-slug>-<screen-name>.png', {
+      maxDiffPixelRatio: 0.15,   // Allow up to 15% pixel difference (content varies)
+      threshold: 0.3,            // Per-pixel color threshold (0-1, higher = more lenient)
+      animations: 'disabled',
+    });
+  });
+});
+```
+
+5. **On first run**, Playwright generates actual screenshots. Manually review them:
+   - If the layout aesthetics match the mockup (colors, spacing, alignment), approve by updating the snapshots
+   - If deviations are found, fix the templates / CSS and re-run
+
+6. **What to check** (aesthetic consistency):
+   - Color scheme matches (backgrounds, borders, text colors, button colors)
+   - Spacing and alignment (padding, margins, gaps between elements)
+   - Layout structure (grid/flex arrangement, sidebar/header/content proportions)
+   - Typography (font sizes, weights, line heights — relative, not exact)
+   - Component styling (buttons, tables, forms, cards, badges)
+   - Responsive breakpoints if applicable
+
+7. **What to ignore** (content differences are expected):
+   - Actual text content / data values
+   - Number of rows in tables
+   - Dynamic timestamps, IDs, or generated values
+
+Update IMPLEMENTATION_MODULE.md: mark visual consistency testing step complete with findings.
+
+- If visual tests pass: update IMPLEMENTATION_MODULE.md status to COMPLETED
+- If visual tests reveal layout issues: fix templates/CSS, re-run both functional and visual tests
+
+### Phase 4: Post-Implementation (Per Module)
+
+After each module completes:
+
+1. Update `<app_folder>/context/develop/<module-slug>/IMPLEMENTATION_MODULE.md`:
+   - Set Status to COMPLETED
+   - Record completion date
+   - Record test results summary
+
+2. Update `<app_folder>/context/develop/IMPLEMENTATION_MASTER.md`:
+   - Update module row: Status = COMPLETED, Completed = date
+   - Add notes about any issues encountered
+
+3. **Check module and version completion**:
+   - Scan the Module Implementation Status table in IMPLEMENTATION_MASTER.md
+   - If there are still PENDING modules for the **current version**:
+     - **IMMEDIATELY proceed to the next module** in execution order — do NOT stop
+     - Continue implementing until context limits force a natural stop
+     - The Ralph Loop will re-feed the prompt, and the next iteration will resume via Phase 0
+   - If ALL modules for the **current version** are COMPLETED:
+     - Update the Version Processing Order table: mark current version as `COMPLETED`, record date
+     - Check if there are MORE versions in the resolved version list:
+       - If YES → perform a **version increment** (update app version in manifest, reset affected
+         modules to PENDING with the new version) and **IMMEDIATELY proceed to Phase 3** for the
+         next version's modules. Do NOT stop between versions.
+       - If NO (this was the last version) → **Proceed to Phase 5 (Generate README.md)**
+         before outputting the completion promise
+
+### Phase 5: Generate README.md
+
+After ALL modules are COMPLETED, generate a `README.md` file in the application root folder
+(`<source-code-path>/README.md`). This file serves as the primary documentation for developers
+to understand the application architecture, navigate the codebase, and run the application.
+
+**If `<source-code-path>/README.md` already exists, OVERWRITE it completely.** The existing
+README may have been auto-generated by the project scaffolding tool (e.g., Laravel, Spring
+Initializr) and does not reflect the actual implemented application. Phase 5 always produces
+a fresh README based on the specification and the final implementation state.
+
+**CRITICAL**: The README content MUST be derived from `SPECIFICATION.md` — the technical
+specification generated by the chosen `specgen-*` skill. Do NOT invent or assume technology
+details. Extract all architecture, stack, configuration, and run instructions directly from
+the specification document.
+
+#### Step 5.1: Read SPECIFICATION.md
+
+Read `<app_folder>/context/specification/SPECIFICATION.md` and extract:
+- **Technology stack** — framework, language, template engine, CSS framework, JS libraries, database, auth provider, messaging, scheduling
+- **Application architecture** — packaging structure (e.g., Spring Modulith, Laravel Modules), layer conventions (controller, service, repository, view), shared infrastructure components
+- **Configuration** — environment variables, config files, database connection, auth provider setup, message queue setup
+- **Build and run commands** — how to install dependencies, compile, run the application, run tests
+
+#### Step 5.2: Generate README.md
+
+Create `<source-code-path>/README.md` with the following structure:
+
+```markdown
+# <Application Name>
+
+<One-paragraph description from SPECIFICATION.md project overview>
+
+## Technology Stack
+
+<Table of technologies, versions, and purposes — extracted from SPECIFICATION.md technology stack section>
+
+| Technology | Version | Purpose |
+|-----------|---------|---------|
+| ... | ... | ... |
+
+## Architecture
+
+<Description of the application architecture from SPECIFICATION.md — packaging approach,
+layer conventions, module organization. Include a text-based or Mermaid diagram if the
+specification describes the architecture visually.>
+
+## Folder Structure
+
+<Tree representation of the actual source code folder structure as implemented. Use the
+real directory layout from `<source-code-path>/`, excluding `context/`, `node_modules/`,
+`.git/`, and other non-essential directories. Annotate key directories with their purpose.>
+
+```
+<source-code-path>/
+  app/                    # (Laravel) Application core
+  Modules/                # (Laravel) Feature modules
+  resources/              # (Laravel) Views, CSS, JS
+  src/                    # (Spring) Java source
+  e2e/                    # Playwright E2E tests
+  ...
+```
+
+## Prerequisites
+
+<List of software prerequisites needed to run the application — JDK, PHP, Composer, Maven,
+Node.js, database, message queue, auth provider, etc. Extracted from SPECIFICATION.md.>
+
+## Getting Started
+
+### Installation
+
+<Step-by-step instructions to install dependencies — e.g., `composer install`, `mvn clean install`,
+`npm install`. Derived from SPECIFICATION.md build configuration section.>
+
+### Configuration
+
+<Instructions for setting up configuration — .env file, application.yml, database setup,
+auth provider configuration. Reference the specific config files and environment variables
+from SPECIFICATION.md.>
+
+### Running the Application
+
+<Commands to start the application — e.g., `php artisan serve`, `mvn spring-boot:run`.
+Include the default URL where the application will be accessible.>
+
+### Running Tests
+
+<Commands to run the Playwright E2E test suite:>
+
+```bash
+cd e2e && npx playwright test
+```
+
+<Any additional test commands — unit tests, integration tests — if applicable from the spec.>
+
+## Modules
+
+<Table listing all implemented modules, their layer classification, and a brief description.
+Extracted from IMPLEMENTATION_MASTER.md execution order and module details.>
+
+| Module | Layer | Description |
+|--------|-------|-------------|
+| ... | ... | ... |
+
+```
+
+**Adapt the template above** to match the actual technology stack from SPECIFICATION.md:
+- For **Spring Boot** apps: use Maven/Gradle commands, `src/main/java` paths, `application.yml` config
+- For **Laravel** apps: use Composer/Artisan commands, `app/` paths, `.env` config
+- For **REST API** apps: omit view/template sections, focus on API endpoints and Swagger/OpenAPI docs
+- Include only sections that are relevant to the actual specification — do NOT add sections for
+  features that are not part of the spec (e.g., skip messaging section if no messaging is configured)
+
+#### Step 5.3: Generate Traceability Matrix
+
+After the README is generated and BEFORE finalizing tracking, regenerate the requirement-to-code
+traceability matrix so every PRD requirement ID is linked to the source code that now implements it
+(the per-file `Implements:` / `NFR:` / `Constraints:` comments written in Step 3.3 are the source
+of the links).
+
+1. Invoke the traceability generator (pass the resolved app folder and the version just completed):
+   ```
+   Skill(skill: "co2-skills:tracegen-matrix", args: "<app_folder> version:<current-version>")
+   ```
+   - If a `module` filter was active for this run, pass it through: append ` module:<module>`.
+   - When processing multiple versions, invoke once after the LAST version (the matrix reflects the
+     full current code state); a per-version invocation is also acceptable.
+2. Wait for it to complete. It writes/updates `<app_folder>/context/TRACEABILITY.md` and appends its
+   own `CHANGELOG.md` row.
+3. This step does **not** require the codebase-memory MCP — `tracegen-matrix` resolves links from
+   the in-source traceability comments, falling back to name-based source scanning, and only uses
+   codebase-memory for extra precision when it happens to be installed.
+
+#### Step 5.4: Update Tracking and Complete
+
+1. Update IMPLEMENTATION_MASTER.md:
+   - Set top-level `**Status**:` to `COMPLETED`
+   - Add a note: `README.md generated at <source-code-path>/README.md`
+2. Append entries to `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`) — **one entry per version processed**:
+   - Read `<app_folder>/CHANGELOG.md`. If it does not exist, create it with context header.
+   - For EACH version in the resolved version list (ascending order):
+     - Search for a `## {version}` heading matching this version.
+     - If the section **exists**: append a new row to its table.
+     - If the section **does not exist**: insert a new section after the `---` below the context header and before any existing `## vX.Y.Z` section (newest-first ordering), with a new table header and the first row.
+     - Row format: `| {YYYY-MM-DD} | {application_name} | conductor-feature-develop | {module or "All"} | Implemented modules for {version} — {count} modules |`
+   - **Never modify or delete existing rows.**
+3. Output the Ralph Loop completion promise: `<promise>ALL MODULES IMPLEMENTED</promise>`
+4. This signals the Ralph Loop to exit
+
+## Mockup Interpretation Guide (CRITICAL)
+
+The HTML mockups in `<app_folder>/context/mockup/` are organized into **role-based subfolders**
+(e.g., `hub_administrator/content/`, `hub_operation_support/content/`). This folder structure
+represents which screens each role can access — it does **NOT** dictate URL patterns or imply
+that URLs should contain role names.
+
+### Rule: Module-Based URLs, NOT Role-Based URLs
+
+**WRONG** (role in URL — NEVER do this):
+```
+/hub-administrator/employer
+/hub-operation-support/quota
+/hub-administrator/industrial-classification/create
+```
+
+**CORRECT** (module-based URL):
+```
+/employer
+/quota
+/industrial-classification/create
+```
+
+Controllers MUST use module-based `@RequestMapping` paths. Role enforcement is handled via
+`@PreAuthorize` annotations on the controller class or method level — NOT through URL segregation.
+
+### Template Strategy for Role-Based UI Differences
+
+When a module's mockup exists under multiple role folders, the screens may differ. Follow this
+decision framework to determine the template strategy:
+
+#### Step 1: Classify Each Screen
+
+For each screen in the module, compare the mockup versions across roles and classify:
+
+| Classification | Description | Example |
+|---------------|-------------|---------|
+| **Role-Exclusive** | Screen exists under only ONE role folder | `audit_trail.html` (admin only), `job_demand.html` (ops only) |
+| **Shared — Minor Differences** | Same layout and structure, but some elements are shown/hidden per role (e.g., action buttons, edit toggles, "Add" button) | `document_classification.html` — admin has toggles + edit; ops has read-only badges |
+| **Shared — Major Differences** | Fundamentally different layout, columns, or purpose despite same module name | `occupation_classification.html` — admin sees CRUD list; ops sees corridor mapping view |
+
+#### Step 2: Apply the Appropriate Strategy
+
+**A. Role-Exclusive Screens → Single template, single controller method**
+
+One template, one route. Only the authorized role can access it. No conditional logic needed.
+
+**B. Shared — Minor Differences → Single template with role-based conditionals**
+
+Use **one template** with conditional blocks to show/hide elements based on the user's role.
+This is the preferred approach when the page layout is structurally the same but some UI
+elements (buttons, action columns, edit controls, banners) differ.
+
+The controller method is accessible to both roles with appropriate authorization annotations.
+
+**C. Shared — Major Differences → Separate templates, controller selects at runtime**
+
+When the two role versions have **fundamentally different layouts, columns, or purposes**
+(not just show/hide of a few elements), create separate templates and let the controller
+choose which to render based on the authenticated user's role.
+
+#### Step 3: Document the Decision
+
+In `IMPLEMENTATION_MODULE.md`, under the analysis step, record the template strategy chosen
+for each screen and why:
+
+```markdown
+### Template Strategy
+
+| Screen | Roles | Classification | Strategy |
+|--------|-------|---------------|----------|
+| employer list | ops-only | Role-Exclusive | Single template |
+| document_classification | both | Minor Differences | Single template + conditional |
+| occupation_classification | both | Major Differences | Separate templates |
+```
+
+### How to Read Mockups During Implementation
+
+When implementing a module (Step 3.2 — Analyze Module Resources):
+
+1. **List all mockup files** for this module across ALL role folders:
+   ```
+   mockup/<role1>/content/<module>*.html
+   mockup/<role2>/content/<module>*.html
+   ```
+
+2. **Read each version** and compare structure, columns, buttons, and layout
+
+3. **Classify** each screen using the framework above
+
+4. **Extract visual design** (colors, spacing, components) from the mockup but
+   **ignore the URL paths** embedded in the mockup HTML (e.g., `href="/hub_administrator/..."`)
+   — these are mockup navigation links, NOT the actual application routes
+
+5. **Map mockup URLs to module URLs**:
+   - Mockup: `/hub_administrator/employer` → App: `/employer`
+   - Mockup: `/hub_operation_support/quota_allocation` → App: `/quota-allocation`
+
+## Critical Rules
+
+1. **CLAUDE.md is the source of truth for all tool commands** — CLAUDE.md is automatically
+   loaded into context. Use the exact JDK path, Maven path, database credentials,
+   message queue credentials, Keycloak CLI path, and all other infrastructure details from
+   CLAUDE.md. NEVER hardcode, guess, or use generic paths like `./mvnw` or `java`.
+
+2. **No test data cleanup** — DO NOT clean up test data after module tests pass. Test data
+   from earlier modules is required as seed data for downstream modules. Only clean up if
+   you need to re-seed for a retest.
+
+3. **Context window awareness (Ralph Loop handles recovery)** — If approaching context limits,
+   save progress gracefully:
+   - Update IMPLEMENTATION_MODULE.md with current progress (mark completed steps, log findings)
+   - Update IMPLEMENTATION_MASTER.md with current status
+   - The Ralph Loop will automatically re-feed the prompt, and the next iteration will resume
+     from exactly where you left off via Phase 0 resume check
+   - Do NOT worry about "losing work" — the tracking files ARE your persistence mechanism
+
+4. **Usage limit handling** — If you hit API usage limits, wait and resume. The tracking
+   files ensure no work is lost. Ralph Loop will re-feed the prompt on next iteration.
+
+5. **Module order is strict, version order is strict** — Follow the execution order from
+   TEST_PLAN.md exactly within each version. When processing multiple versions, ALL modules
+   for version N must be COMPLETED before ANY module from version N+1 begins. Dependencies
+   mean earlier modules must complete before later ones can start within the same version.
+
+6. **Track everything** — Every action should be logged in IMPLEMENTATION_MODULE.md so
+   that any future session (or Ralph Loop iteration) can understand what was done and what
+   remains. This is CRITICAL for Ralph Loop — without accurate tracking, iterations will
+   repeat already-completed work.
+
+7. **Test-driven** — Implementation is guided by TEST_SPEC.md. The test spec defines
+   what the code must do. The SPEC.md defines how to build it.
+
+8. **Mockup fidelity** — View templates MUST match the approved HTML mockup screens aesthetically.
+   Use the mockup as the visual reference for layout, components, and styling. After functional
+   E2E tests pass, run visual consistency tests comparing app screenshots against mockup
+   baselines to verify colors, alignment, padding, margins, and layout structure match. Content
+   differences (data values, row counts) are expected and acceptable — only aesthetic deviations
+   should be flagged and fixed.
+
+9. **Specification compliance** — Follow the SPECIFICATION.md shared infrastructure sections
+   for all cross-cutting concerns (security, theming, pagination, error handling, etc.).
+
+10. **Module-based URLs only** — NEVER use role names in URL paths. Mockup folder structure
+    is for organizing mockups by role visibility, NOT for defining URL routes. All controllers
+    use module-based paths. Role enforcement is via authorization annotations. See the
+    "Mockup Interpretation Guide" section above for the full template strategy framework.
+
+11. **Ralph Loop discipline — NEVER stop prematurely** — After completing a module, IMMEDIATELY
+    check for the next pending module and start it. After completing all modules for a version,
+    IMMEDIATELY perform the version increment and start the next version's modules. Do NOT
+    output the completion promise (`<promise>ALL MODULES IMPLEMENTED</promise>`) until EVERY
+    module for EVERY version is COMPLETED. Do NOT stop "to let the user review" — Ralph Loop
+    handles multi-iteration execution automatically. The only valid reasons to stop within an
+    iteration are: (a) context window approaching limit, (b) all modules for all versions
+    completed (output promise), or (c) an unrecoverable error requiring user input.
+
+12. **Complete implementation per module** — Each module must have ALL of these before marking
+    COMPLETED: (a) all source files (entities, repositories, services, controllers, mappers),
+    (b) all view templates (page + fragments), (c) E2E test file with all scenarios from TEST_SPEC,
+    (d) all E2E tests passing, (e) ALL user stories checked off in IMPLEMENTATION_MODULE.md,
+    (f) ALL NFRs checked off in IMPLEMENTATION_MODULE.md. Do NOT mark a module COMPLETED with
+    partial implementation or failing tests — this would cause the next Ralph Loop iteration to
+    skip it. If a module has messaging/async NFRs that cannot be implemented yet (e.g., upstream
+    adapter not available), mark the module as **PARTIALLY COMPLETED** and leave the unchecked
+    NFR items visible in the checklist. Only mark COMPLETED when every user story AND every NFR
+    is implemented and tested.
+
+13. **Auto-start Ralph Loop** — When this skill is triggered, the FIRST action (Phase 0, Step 0)
+    MUST be to check if Ralph Loop is active (`.claude/ralph-loop.local.md` exists). If not active,
+    invoke `Skill(skill: "ralph-loop:ralph-loop", args: "...")` with the full orchestrator prompt
+    and `--completion-promise "ALL MODULES IMPLEMENTED" --max-iterations 100`. Do NOT proceed
+    with any implementation work until Ralph Loop is confirmed active.
+
+14. **NO creative alternatives for 3rd party applications (CRITICAL)** — You MUST use the EXACT
+    methods, connection strings, CLIs, and credentials described in `CLAUDE.md` for
+    accessing all external infrastructure. This includes but is not limited to:
+
+    **NEVER do any of the following:**
+    - Connect to databases via Docker (`docker exec`, `docker run`, CLI inside a container)
+    - Start or restart services with alternative databases
+    - Spin up services via Docker Compose or Docker run
+    - Use `docker exec` to access any service that is described as running natively in CLAUDE.md
+    - Install or use alternative CLI tools when CLAUDE.md specifies a different access method
+    - Assume services run in Docker when CLAUDE.md says they run natively (or vice versa)
+    - Use embedded/in-memory databases as substitutes for the actual configured database
+    - Guess connection strings, ports, or credentials — ALWAYS read them from CLAUDE.md
+
+    **ALWAYS do the following:**
+    - Use database connection strings EXACTLY as specified in CLAUDE.md
+    - Use service instances EXACTLY as configured in CLAUDE.md
+    - Use CLIs at the EXACT paths specified in CLAUDE.md
+    - For E2E test data seeding, connect to the database using the EXACT connection details from
+      CLAUDE.md
+    - For E2E test helper classes and seeding utilities, store ALL machine-specific values
+      (CLI paths, connection strings, credentials) in `<source-code-path>/e2e/.env` and read
+      them via `process.env.*` using `dotenv`. Populate `.env` with values from CLAUDE.md
+      for the current machine, but NEVER hardcode these values in TypeScript source files.
+      Commit `.env.example` (with placeholder descriptions) and ensure `e2e/.env` is in
+      `.gitignore` so that credentials and machine-specific paths are never committed.
+
+    **WHY**: Creative alternatives (Docker containers, alternative databases, alternative CLIs) connect to
+    DIFFERENT data stores or service instances than the ones the application is configured to use.
+    This produces wrong test results, missing data, and phantom failures. Hardcoding CLAUDE.md values
+    directly in TypeScript source code makes tests non-portable — other developers with different
+    machine setups cannot run the tests without modifying source files. Using `.env` files allows
+    each developer to configure their own paths and credentials once without touching committed code.
+
+15. **Source code goes directly in `<source-code-path>/` — NO nested subdirectories (CRITICAL)** —
+    The `<source-code-path>` (which defaults to `<app_folder>`) already contains a `context/` folder
+    with all generated artifacts. Source code files MUST be placed directly alongside `context/` in the same
+    directory — NOT inside a nested project subfolder. When using project scaffolding tools,
+    these tools create a new subdirectory by default. You MUST work around this by:
+    - Creating the project in a temporary subdirectory (e.g., `<source-code-path>/_temp_scaffold`)
+    - Moving ALL files (including dotfiles) up to `<source-code-path>/`
+    - Removing the empty temporary directory
+    - Verifying the `context/` folder was NOT overwritten or deleted
+
+    **WHY**: The folder structure convention is that `<app_folder>` contains both `context/` (artifacts)
+    and source code at the same level. A nested subdirectory breaks all relative paths, makes the
+    project structure confusing, and separates context from code unnecessarily.
+
+16. **Context artifacts must pre-exist** — This skill does NOT generate context artifacts. If
+    module models, mockups, specifications, or test specs are missing, stop and instruct the
+    user to run `/conductor-feature-prepare` first. Do NOT attempt to generate artifacts inline.
+
+17. **README.md is mandatory before completion** — After ALL modules are COMPLETED,
+    Phase 5 (Generate README.md) MUST run before outputting the completion promise.
+    Phase 5 generates the README with content derived from SPECIFICATION.md — do NOT
+    invent stack details, run commands, or architecture descriptions. Deployment
+    artifacts (Dockerfile, Kubernetes manifests) are NOT generated by this skill —
+    run `/depgen-k8s` independently after development is complete.
+
+18. **Spring Boot `app:` namespace for application-specific configuration (CRITICAL)** —
+    When the application stack is Spring Boot, ALL application-owned configuration in
+    `application.yml` MUST be placed under the top-level `app:` key. NEVER place
+    application-specific keys at the YAML root (e.g., top-level `notification:`,
+    `batch-job:`, `audit-trail:`) and NEVER place them under Spring framework namespaces
+    (`spring.*`, `server.*`, `management.*`, `logging.*`, `springdoc.*`).
+
+    **Grouping:**
+    - Cross-cutting values (version, CORS, shared security, shared messaging, shared
+      object-storage) sit directly under `app.*` with no module prefix.
+    - Per-module values MUST be grouped under `app.<module-kebab-case>.*`, one block
+      per module. A single config value per module still gets its own block.
+
+    **Binding:** every `app.*` subtree MUST be bound once via a `@ConfigurationProperties`
+    record in the owning module's `config` subpackage (or in the application-level
+    `config` subpackage for cross-cutting values). NEVER inject individual values via
+    `@Value("${app....}")` scattered across beans. Use kebab-case in YAML; Spring Boot's
+    relaxed binding maps to camelCase Java fields automatically. See SPECIFICATION.md
+    section "Application-Specific Configuration (`app:` namespace)" for the authoritative
+    rules and examples.
+
+19. **Code-level traceability is MANDATORY** — Every newly created source file (entity,
+    repository, service, mapper, controller, view template, listener, scheduled job,
+    configuration class, test file) MUST carry a top-of-file comment listing the
+    requirement codes it implements. The codes follow the formats emitted by
+    `util-ustagger` and `testgen-functional` — extract them verbatim from the module's
+    `SPEC.md` and `TEST_SPEC.md` traceability sections, never invent or reformat:
+
+    | Source | Code Pattern | Example |
+    |---|---|---|
+    | PRD.md → User Story | `US<II><5-digit#>` | `USHM00003` |
+    | PRD.md → NFR | `NFR<II><4-digit#>` | `NFRHM0003` |
+    | PRD.md → Constraint | `CONS<II><3-digit#>` | `CONSHM003` |
+    | PRD.md → Reference | `REF<II><4-digit#>` | `REFHM0003` |
+    | PRD.md → Test instruction | `TST<II><4-digit#>` | `TSTHM0003` |
+    | TEST_SPEC.md → Scenario | `<TYPE>-<MODULE-PREFIX>-<NNN>` | `NAV-LIN-001`, `CRUD-EMP-002`, `REG-QUO-001` |
+
+    `<II>` is the application's 2-letter initials. `<TYPE>` is one of `NAV`, `SRCH`,
+    `VIEW`, `CRUD`, `VAL`, `MAP`, `TOG`, `HIST`, `RAW`, `PAGE`, `REG`, `TSTI`.
+    `<MODULE-PREFIX>` is the 3-letter module prefix from the module model.
+
+    Use the language's native doc-comment style (Javadoc / PHPDoc / JSDoc / `{{-- --}}` /
+    `@* *@` / `<!-- -->` / `#`). Test names MUST be prefixed with the scenario ID copied
+    verbatim from TEST_SPEC.md Section 4 (e.g., `'NAV-LIN-001: Navigate to Location
+    Information screen'`) so test output is traceable to TEST_SPEC.md without consulting
+    IMPLEMENTATION_MODULE.md.
+
+    **Why**: `git blame`, IDE symbol search, and downstream audits must trace every line
+    of code back to a PRD.md requirement or a TEST_SPEC.md scenario directly.
+    IMPLEMENTATION_MODULE.md is a transient tracking file and is not the system of record
+    for traceability — the source code itself must be self-describing. This rule applies
+    to fresh creation; bug fixes layer additional `[BUG-XXX]` markers as defined by
+    `conductor-defect`.