Conductor Feature Develop

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>]

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

Version Resolution

The version: argument supports four forms:

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:

# 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
5. Security configuration: Keycloak/OAuth2 or other auth provider setup
6. Shared layouts: Blade / JTE / other template layout files (header, footer, sidebar)
7. Shared components: UI components (Tailwind), JS structure, CSS
8. Data access layer: Base repository / model configuration
9. Error handling: Global exception handlers
10. Theming: Theme configuration from spec
11. Pagination: Shared pagination support
12. Messaging: Message queue configuration if applicable
13. Scheduling: Scheduled task configuration if applicable
14. 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).
15. 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:

# 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:

# 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:

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):

/**
 * 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:

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:

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>

…(truncated)