codeninja 3.2.0 → 4.0.1

package/ide/antigravity/.agents/workflows/codeninja-init.md

@@ -1,336 +1,526 @@
+This workflow runs when user invokes /codeninja:init
+
 ---
-slash_command: /codeninja:init
-personas: [global-orchestrator, nodejs-backend, reactjs-frontend, database-architect]
-skills: [mcp-and-context, api-builder, reactjs, database]
+type: workflow
+name: initialize-project
 description: >
-  Bootstrap a new NodeJS service, ReactJS app, or database-only project.
-  Collects project information first, then service details, then generates
-  ALL files in one pass after a single confirmation.
+  Interactive bootstrap workflow for a new service. Collects project
+  information first, then service details one value at a time, then scaffolds
+  database folder and service baseline. Single confirmation before generation —
+  no per-file prompts after that.
 ---
 
-# /codeninja:init
+# Workflow: @initialize-project
+
+## Goal
+Scaffold a new service (NodeJS API, ReactJS frontend, or Database-only) with
+full context recorded in `.codeninja/context/context.json`.
+
+## Rules
+- Phase 0 runs ONCE per repository — skip entirely if `context.project_info` already populated.
+- Confirm the full summary ONCE before creating any file.
+- After confirmation → generate ALL files using wave structure, no further per-file prompts.
+- Always scaffold database folder at REPOSITORY ROOT before any service
+  code. The database/ folder is always at the same level as service
+  folders, never inside one.
+- After completion → run task: `write-context` then task: `show-final-summary`
+
+## Init Mode Rules
+- Fast mode: ask only essential questions. Auto-generate all technical
+  config silently. Show everything in summary for review.
+- Manual mode: ask every value individually, one at a time.
+- In BOTH modes: the summary shows ALL values and ALL are editable
+  before confirmation. Fast mode is not a shortcut around review —
+  it is a shortcut around data entry.
+- Auto-generated security values (api_key, encryption_key) are
+  cryptographically random and production-safe.
+  encryption_iv is always the first 16 characters of encryption_key —
+  never randomly generated independently.
+  The user does not need to provide them unless they have specific
+  requirements.
+
+---
 
-## Before Running
-1. Call `context_check_stale` — resolve any stale scratchpad keys first
-2. Call `context_read` — if context_version > 0, load existing context
-3. Call `service_scan` — detect existing service directories
+## Step-by-Step Execution
 
-## Execution — Full Step-by-Step
+---
 
 ### Phase 0 — Project Information (runs ONCE per repo)
+
 Check `context.project_info` — if already populated, skip Phase 0 entirely.
 
-**0a.** Ask: "Do you have a project information document or requirement document?"
-- Options: Yes (provide URL or paste) / No
-- Store: `context.project_info.has_doc`, `.doc_url` or `.doc_content`, `.from_doc`
+0a. Run task: `ask-project-info-doc`
+    Stores: `context.project_info.has_doc`, `.doc_url` or `.doc_content`, `.from_doc`
 
-**0b.** Ask: "Do you have a scope of work document?"
-- Options: Yes (provide URL or paste) / No
-- Store: `context.project_info.has_sow`, `.sow_url` or `.sow_content`, `.from_sow`
+0b. Run task: `ask-project-scope-of-work`
+    Stores: `context.project_info.has_sow`, `.sow_url` or `.sow_content`, `.from_sow`
 
-**0c.** Ask: "Do you have a Figma design URL?"
-- Options: Yes (provide URL) / No
-- Store: `context.project_info.has_figma`, `.figma_url`, `.from_figma`
+0c. Run task: `ask-project-figma`
+    Stores: `context.project_info.has_figma`, `.figma_url`, `.from_figma`
 
-After all three: synthesize `context.project_info.summary` (150–200 words covering
-what the project does, key features, entities/modules, tech preferences,
-third-party integrations) and `context.project_info.detected_entities[]`.
-Use this summary for all suggestions throughout the session.
+After all three tasks:
+  Agent synthesizes all collected information and builds:
+  `context.project_info.summary` — 150–200 word plain text summary including:
+    - What the project does
+    - Key features identified
+    - Entities/modules detected
+    - Tech preferences mentioned
+    - Third-party integrations noted
 
----
+  `context.project_info.detected_entities[]` — flat list of data entities found
+    Example: ["users", "admins", "bots", "orders", "products"]
 
-### Phase 1 — Init Mode and Project Type
-
-**Step 0.** Ask: "How would you like to set up this service?"
-- Option 1: Fast setup — auto-generate secure values, only 9 essential questions
-- Option 2: Manual setup — walk through every value one at a time (22 questions)
-- Store: `context.current_init.init_mode` ("fast" | "manual")
-
-**Step 1.** Ask: "What are you initializing?"
-- Option 1: NodeJS API service
-- Option 2: ReactJS frontend app
-- Option 3: Database only (no service code)
-- Store: `context.current_init.project_type` ("nodejs" | "reactjs" | "database-only")
-
-**Step 1b.** If `project_type == nodejs`:
-- Ask: "What type of client will consume this API?"
-  - Options: ReactJS web app / Mobile app
-  - Store: `context.current_init.client_type` ("reactjs" | "app")
-- Ask: "Does this service use encrypted transport (AES response wrapping)?"
-  - Options: Yes / No
-  - Store: `context.current_init.encrypted_transport` (true | false)
-- Ask: "Which languages should this service support?"
-  - Show options + allow multi-select (en always included)
-  - Store: `context.current_init.supported_languages[]`
-
-**Step 2.** If `project_type == reactjs`:
-- Check `context.services` for any NodeJS services.
-  If none exist → ABORT: "A ReactJS service requires an existing NodeJS backend.
-  Run /codeninja:init first to create a NodeJS service."
-- Ask: "Which NodeJS service should this ReactJS app connect to?"
-  - List available NodeJS services from `context.services`
-- Store: `context.current_init.linked_service`
-- Store: `context.current_init.linked_service_port` (read from context)
-- Auto-inherit from the linked service (never ask user):
-  - `context.current_init.encryption_key`
-  - `context.current_init.encryption_iv`
-  - `context.current_init.api_key`
-- Skip Phase 2 (no DB), skip Phase 4 (no package questions), skip Phase 5 (no security questions)
-- Jump directly to Phase 3
-
-**Step 3.** If `project_type == nodejs` or `database-only` → continue to Phase 2.
+  Agent uses this summary for ALL remaining suggestions in this and future workflows.
 
 ---
 
-### Phase 2 — Database (nodejs and database-only only)
-
-**Step 4.** Ask: "Which database type?"
-- Options: PostgreSQL / MySQL / MongoDB
-- If `context.db.type` already exists → ask: use existing or configure new?
-- Store: `context.db.type`
-
-**Step 5.** If `init_mode == manual`:
-- Ask: "Database name?", "Database host?", "Database port?", "Database user?" (grouped display)
-- Store: `context.db.name`, `context.db.host`, `context.db.port`, `context.db.user`
-
-If `init_mode == fast`:
-- Ask: "Database name?" only
-- Ask: "Database user?" only
-- (host and port auto-set by generate-fast-defaults)
-- Store: `context.db.name`, `context.db.user`
-
-**Step 9.** Delegate to database-agent — generate database folder at REPOSITORY ROOT
-(not inside the service folder — always a sibling).
-
-Check if `<repo_root>/database/<db_type>/` already exists:
-- If NOT exists → generate:
-  - `database/<db_type>/migrations/` (empty)
-  - `database/<db_type>/create-schema.sql`
-  - `database/<db_type>/setup-database.sh`
-  - `database/<db_type>/setup-database.ps1`
-  - `database/<db_type>/reset-database.sh`
-  - `database/<db_type>/seeds/` (with .gitkeep)
-  - `database/README.md`
-  - Then generate `tbl_user_deviceinfo` migration (nodejs projects only)
-- If ALREADY exists → skip generation entirely. Inform user.
-  Then check if `migrations/1-setup-tbl-user-deviceinfo.sql` exists:
-  - If NO and project_type == nodejs → generate it
-  - Otherwise → skip
-
-**Step 10.** Inform: "Database folder initialized. You can run /codeninja:db:create to add tables."
-
-**Step 11.** If `project_type == database-only` → skip Phases 3–5, jump to Phase 6.
+### Phase 1 — Project Type
 
----
+0. Run task: `ask-init-mode`
+   - Stores: `context.current_init.init_mode`
+   - Values: "fast" | "manual"
 
-### Phase 3 — Service Identity
+1. Run task: `ask-project-type`
+   - Stores: `context.current_init.project_type`
+   - Valid values: `nodejs`, `reactjs`, `database-only`
 
-**Step 12.** Ask: "Service name?"
-- Must be unique across `context.services`
-- Agent suggests based on `context.project_info.detected_entities`
-- Store: `context.current_init.service_name`
+    1b. If `project_type == nodejs`:
+    - Run task: `ask-client-type`
+      Stores: `context.current_init.client_type`
 
-**Step 13.** If `init_mode == manual`:
-- Ask: "Port number?" (must not conflict with existing services)
-- Store: `context.current_init.port`
+    - Run task: `ask-encrypted-transport`
+      Stores: `context.current_init.encrypted_transport`
 
-**Step 14.** Ask: "Short description of this service?"
-- Store: `context.current_init.description`
+    - Run task: `ask-language-type`
+      Stores: `context.current_init.language`
+      Only runs for project_type == nodejs. Skipped for reactjs and database-only.
 
----
+    - Run task: `ask-supported-languages`
+      Stores: `context.current_init.supported_languages[]`
 
-### Phase 4 — Package Info (nodejs + manual mode only)
+2. If `project_type == reactjs`:
+   - Run task: `ask-linked-service`
+     This enforces the backend requirement. If no NodeJS service exists,
+     the task aborts the workflow with instructions. Otherwise it:
+     - Stores: `context.current_init.linked_service`
+     - Stores: `context.current_init.linked_service_port`
+     - Inherits and stores: `encryption_key`, `encryption_iv`, `api_key`
+       from the selected backend service into `context.current_init`
+   - Skip Phase 2 (no DB questions for frontend)
+   - Skip Phase 4 (no package author/name questions — handled by fast defaults)
+   - Skip Phase 5 (no api-key, encryption-key, redis questions — inherited
+     from linked backend, never asked from user)
+   - Jump directly to Phase 3 (service identity)
 
-**Step 15.** If `init_mode == manual`:
-- Ask: "Package name?" (default: service_name)
-- Store: `context.current_init.package_name`
-
-**Step 16.** If `init_mode == manual`:
-- Ask: "Author name?"
-- Store: `context.current_init.author`
+3. If `project_type == nodejs` or `database-only`:
+   - Continue to Phase 2
 
 ---
 
-### Phase 5 — Runtime Config (nodejs + manual mode only)
-
-**Step 17.** If `init_mode == manual`:
-- Ask: "API key?" (auto-suggest 32 random chars)
-- Store: `context.current_init.api_key`
+### Phase 2 — Database (for nodejs and database-only)
+
+4. Run task: `ask-database-type`
+   - If `context.db.type` already exists → inform user and ask:
+     use existing or configure new?
+   - Stores: `context.db.type`
+
+4.5. Run task: `ask-orm-type`
+     - Stores: `context.db.orm`
+     - Fast mode: silently sets orm = "none"
+
+5. If `init_mode == "manual"`:
+   Run task: `ask-database-config`
+   - Collects: name, host, port, user in one grouped display
+   - Stores: `context.db.name`, `context.db.host`,
+     `context.db.port`, `context.db.user`
+
+   If `init_mode == "fast"`:
+   Run task: `ask-database-name`
+   - Stores: `context.db.name`
+   Run task: `ask-database-user`
+   - Stores: `context.db.user`
+   (host and port will be auto-populated by generate-fast-defaults)
+
+9. Delegate to `database-agent` — generate database folder at the
+   REPOSITORY ROOT — not inside the service folder.
+   The database/ directory is always a sibling of service folders,
+   never a child. All services share the same database directory.
+
+   Path anchor: all paths below are relative to repository root.
+
+   ## Database Folder Existence Check (CRITICAL)
+
+   Before generating ANY database files, check whether
+   `<repo_root>/database/<db_type>/` already exists on disk.
+
+   ### If database folder does NOT exist → generate everything:
+   - <repo_root>/database/<db_type>/migrations/ (empty, ready for table files)
+   - <repo_root>/database/<db_type>/create-schema.sql (header only)
+   - <repo_root>/database/<db_type>/setup-database.sh (Linux/Mac runner)
+   - <repo_root>/database/<db_type>/setup-database.ps1 (Windows runner)
+   - <repo_root>/database/<db_type>/reset-database.sh (dev-only reset)
+   - <repo_root>/database/<db_type>/seeds/ (empty with .gitkeep)
+   - <repo_root>/database/README.md
+
+   Then run task: generate-tbl-user-deviceinfo
+   (only for nodejs projects — not database-only)
+
+   ### If database folder ALREADY exists → skip folder generation entirely:
+   Inform user:
+   "Database folder already exists at database/<db_type>/. Skipping
+   folder generation — your existing migrations are untouched."
+
+   Then check: does `database/<db_type>/migrations/1-setup-tbl-user-deviceinfo.sql`
+   already exist on disk?
+   - If YES → skip generate-tbl-user-deviceinfo entirely.
+     Inform user: "tbl_user_deviceinfo migration already exists. Skipping."
+   - If NO AND project_type == nodejs → run task: generate-tbl-user-deviceinfo.
+     This handles the case where database-only was initialized first
+     and the NodeJS system table was never created.
+   - If NO AND project_type == database-only → skip. This table is
+     not needed for database-only projects.
+
+10. Inform user:
+    "Database folder initialized. You can now run @db:create-table
+    to add your first table, or continue to scaffold your service below."
+
+11. If `project_type == database-only`:
+    - Skip Phases 3–5 entirely
+    - Jump directly to Phase 6 (confirmation and final summary)
 
-**Step 18.** If `init_mode == manual`:
-- Ask: "Encryption key?" (must be exactly 32 characters)
-- Store: `context.current_init.encryption_key`
-
-**Step 19.** If `init_mode == manual`:
-- Auto-set `encryption_iv` = first 16 chars of `encryption_key`
-- Show derived value: "Encryption IV auto-derived: [first 16 chars of key]"
-- Store: `context.current_init.encryption_iv`
+---
 
-**Step 20.** If `init_mode == manual`:
-- Ask: "Redis host and port?" (grouped)
-- Store: `context.current_init.redis_host`, `context.current_init.redis_port`
+### Phase 3 — Service Identity
 
----
+12. Run task: `ask-service-name`
+    - Must be unique across `context.services`
+    - Agent suggests name from `context.project_info.detected_entities`
+      if relevant
+    - Stores: `context.current_init.service_name`
 
-### Phase 5b — Auto-populate Defaults (fast mode, nodejs only)
+13. If `init_mode == "manual"`:
+    Run task: `ask-service-port`
+    - Must not conflict with existing ports in `context.services`
+    - Stores: `context.current_init.port`
 
-If `init_mode == fast` AND `project_type == nodejs`:
-- `context.db.host` → "localhost" (if not set)
-- `context.db.port` → 5432 / 3306 / 27017 based on db type
-- Port: scan all `context.services` ports → highest + 1 → minimum 1001
-- `package_name` → same as `service_name`
-- `author` → ""
-- `api_key` → 32 cryptographically random alphanumeric chars
-- `encryption_key` → exactly 32 cryptographically random alphanumeric chars
-- `encryption_iv` → first 16 chars of `encryption_key` (always derived, never random)
-- `redis_host` → "localhost"
-- `redis_port` → 6379
-- All done silently — values shown in summary for review
+14. Run task: `ask-service-description`
+    - Stores: `context.current_init.description`
 
 ---
 
-### Phase 6 — Single Confirmation, Then Generate Everything
+### Phase 4 — Package Info (nodejs only, manual mode only — skipped for reactjs)
 
-**Step 22.** Show init summary — ALL collected values including auto-generated ones.
-Run pre-generation validation BEFORE displaying:
-- BLOCKER: service name conflict
-- BLOCKER: port conflict
-- BLOCKER: encryption_key not 32 chars (nodejs)
-- BLOCKER: encryption_iv not 16 chars (nodejs)
-- BLOCKER: required fields missing
-- BLOCKER: no linked service (reactjs)
-- WARNING: port below 1024
-- WARNING: service name has uppercase
-
-Resolve all BLOCKERs interactively before showing summary.
-Show the 5-wave generation plan.
-Ask ONE question: "Confirm and generate all files? (yes / no / change a value)"
-- If yes → generate immediately, NO further confirmations
-- If no → abort
-- If change → re-run specific ask-* task → re-validate → return to summary
+15. If `init_mode == "manual"`:
+    Run task: `ask-package-name`
+    - Default: service_name
+    - Stores: `context.current_init.package_name`
+
+16. If `init_mode == "manual"`:
+    Run task: `ask-package-author`
+    - Stores: `context.current_init.author`
 
 ---
 
-### Phase 6b — Generation (nodejs)
-
-Read `nodejs-agent.md` persona. Execute ALL waves. Do NOT pause between waves.
-
-**Wave 1 — Foundation** (all simultaneously):
-- `package.json`
-- `.env` and `.env.example`
-- `.gitignore`
-- `README.md`
-- `config/constants.js`
-- `config/template.js`
-- `logger/logging.js`
-- `utilities/encryption.js`
-- `languages/<lang>.js` for each in supported_languages[]
-- `enc_dec.html` (if client_type == reactjs) OR `enc_dec.php` (if client_type == app)
-- `pem/` directory with .gitkeep
-- `images/` directory with .gitkeep
-- `logger/logs/` directory with .gitkeep
-
-**Wave 2 — Infrastructure**:
-- `config/database.js`
-- `utilities/ioRedis.js`
-- `utilities/response.js`
-
-**Wave 3 — Service Layer**:
-- `config/common.js`
-- `utilities/validator.js`
-- `utilities/notification.js`
-- `middleware/rateLimiter.js`
-
-**Wave 4 — Middleware and Business Layer** (all simultaneously):
-- `middleware/headerValidator.js`
-- `modules/v1/<ServiceName>/route.js`
-- `modules/v1/<ServiceName>/<service>_model.js`
-- `document/v1/swagger_doc.json` (skeleton)
-
-**Wave 5 — Orchestration Layer**:
-- `modules/v1/route_manager.js`
-- `app.js`
-
-**Wave 6 — Docker** (post-completion):
-- `Dockerfile`
-- `.dockerignore`
-
-COMPLETION GATE — before proceeding, verify these exist on disk:
-- `<service_name>/app.js`
-- `<service_name>/modules/v1/route_manager.js`
-- `<service_name>/modules/v1/<ServiceName>/route.js`
-- `<service_name>/modules/v1/<ServiceName>/<service>_model.js`
-- `<service_name>/document/v1/swagger_doc.json`
-If any missing → generate now before continuing.
+### Phase 5 — Runtime Config (nodejs only — skipped entirely for reactjs)
+
+17. If `init_mode == "manual"`:
+    Run task: `ask-api-key`
+    - Auto-generate suggestion (32 chars)
+    - Stores: `context.current_init.api_key`
+
+18. If `init_mode == "manual"`:
+    Run task: `ask-encryption-key`
+    - Enforce exactly 32 characters
+    - Auto-generate suggestion
+    - Stores: `context.current_init.encryption_key`
+
+19. If `init_mode == "manual"`:
+    Run task: `ask-encryption-iv`
+    - Enforce exactly 16 characters
+    - Auto-generate suggestion
+    - Stores: `context.current_init.encryption_iv`
+
+Note: KEY and IV are always generated regardless of encrypted_transport
+value. They are used for password encryption even when transport is
+not encrypted.
+
+20. If `init_mode == "manual"`:
+    Run task: `ask-redis-config`
+    - Collects: host and port in one grouped display
+    - Stores: `context.current_init.redis_host`,
+      `context.current_init.redis_port`
+    (If init_mode == "fast" → handled by generate-fast-defaults)
+
+21. If `init_mode == "manual"` AND `project_type == "nodejs"`:
+    Run task: `ask-hashing-library`
+    - Options: bcryptjs (recommended) / argon2
+    - Stores: `context.current_init.hashing_library`
 
 ---
 
-### Phase 6c — Generation (reactjs)
-
-Read `reactjs-frontend.md` persona. Execute ALL waves.
-
-**Wave 1 — Foundation**:
-- `package.json`
-- `.env` and `.env.example`
-- `.gitignore`
-- `README.md`
-- `public/index.html`
-- `public/assets/css/style.css`
-- `public/robots.txt`
-- `public/favicon.ico` (placeholder note)
-- `.htaccess` (root)
-- `public/.htaccess`
-
-**Wave 2 — API Layer**:
-- `src/api/apiClient.js`
-- `src/api/apiHandler.js`
-
-**Wave 3 — Application Shell**:
-- `src/pages/Welcome/index.jsx`
-- `src/pages/Welcome/Welcome.module.css`
-- `src/App.jsx`
-- `src/index.jsx`
-- `src/components/` (empty dir with .gitkeep)
-
-**Wave 4 — Docker**:
-- `Dockerfile`
-- `nginx.conf`
-- `.dockerignore`
-
-COMPLETION GATE — verify before proceeding:
-- `<service_name>/public/index.html`
-- `<service_name>/src/api/apiClient.js`
-- `<service_name>/src/api/apiHandler.js`
-- `<service_name>/src/App.jsx`
-- `<service_name>/src/index.jsx`
-- `<service_name>/.env`
+### Phase 5b — Auto-populate Defaults (fast mode, nodejs only)
+
+Run task: `generate-fast-defaults`
+- Condition: only runs if `context.current_init.init_mode == "fast"`
+  AND `context.current_init.project_type == "nodejs"`
+- For `project_type == "reactjs"` → skip entirely. All security values
+  were already inherited from the linked backend in ask-linked-service.
+  Only port and package defaults need auto-filling — see step 13.
+- Silently sets all values not yet in context.current_init
+- No output, no questions — values appear in summary
+- See task description for full list of what is auto-generated
+- `hashing_library` → "bcryptjs" (fast mode default — no native bindings, production-safe)
 
 ---
 
-### Phase 7 — Post-Generation Steps
-
-**Step 23b.** Generate IDE configs (first init only):
-- Write `.vscode/mcp.json`
-- Write `.cursor/mcp.json`
-- Print Claude Desktop config snippet for manual addition
-
-**Step 23c.** Generate docker-compose.yml:
-- If does not exist → generate complete file at repo root
-- If exists → update by adding the new service
-- Also generate/update `.env.docker` and `.env.docker.example`
-
-**Step 24.** Call `context_write`:
-- Set `project_name` = service_name (top-level)
-- Set `initialized_at` = ISO now
-- Set `last_command` = "initialize-project"
-- Append new service to `context.services[<service_name>]`
-- For reactjs: store `linked_service` and `linked_service_port`
-- Update `context.project_info` with `initialized_at`
-- Clear `context.current_init`
-
-**Step 25.** Call `context_clear_scratchpad` with keys: ["current_init"]
-
-**Step 26.** Show final summary:
-- List all files created per wave
-- Show startup commands
-- Offer next steps: /codeninja:db:create, /codeninja:api, /codeninja:design
+### Phase 6 — Single Confirmation, Then Generate Everything
+
+22. Run task: `show-init-summary`
+    - Runs pre-generation validation before displaying anything
+    - Resolves any BLOCKERs interactively before showing the summary
+    - Displays all collected values with auto-generated markers
+    - Shows any non-blocking WARNINGs
+    - Shows the 5-wave generation plan
+    - Asks ONE question: "Confirm and generate all files?
+      (yes / no / change a value)"
+    - If yes → proceed immediately to step 23 — NO further confirmations
+    - If no → abort, nothing created
+    - If change → re-run that specific ask-* task → re-validate →
+      return to show-init-summary
+
+23. Branch on `context.current_init.project_type`:
+
+    ---
+
+    ## IF project_type == "nodejs"
+
+    Read `.codeninja/agent/nodejs-agent.md`.
+    Execute ALL generation steps below directly as the nodejs-agent.
+    Do NOT proceed to step 24 until every file listed in Waves 1–5
+    has been confirmed written to disk.
+
+    Pass values into generation:
+    - Full `context.current_init` + `context.db`
+    - `context.current_init.client_type`
+    - `context.current_init.encrypted_transport`
+    - `context.current_init.supported_languages`
+
+    Generation rules:
+    - Do NOT pause between waves
+    - Do NOT ask for confirmation on individual files or folders
+    - Do NOT skip any file — every file listed in every wave is required
+    - ALL paths below are relative to <service_name>/ — NOT repo root
+    - Step 24 MUST NOT run until ALL 5 waves are complete
+
+    ## COMPLETION GATE (nodejs)
+    Before proceeding to step 24, verify these files exist on disk:
+    - <service_name>/app.js
+    - <service_name>/modules/v1/route_manager.js
+    - <service_name>/modules/v1/<ServiceName>/route.js
+    - <service_name>/modules/v1/<ServiceName>/<service>_model.js
+    - <service_name>/document/v1/swagger_doc.json
+    If any of these are missing → generate them now before continuing.
+    Only proceed to step 24 when ALL are confirmed present.
+
+    ## Generation Wave Structure (nodejs)
+
+    ### Why waves exist
+    All files within a wave share zero generation-time dependencies on
+    each other — they all read only from context.current_init and
+    context.db which are fully loaded before Wave 1 begins.
+    Waves only exist where one file must know the output of another
+    file before it can be written correctly.
+
+    ### Wave 1 — Foundation (no dependencies, generate all simultaneously)
+    These files depend only on context values. None depend on each other.
+
+> **Multi-agent:** Delegate to `nodejs-backend` + `database-architect` (parallel) via Task invocation for parallel execution.
+> Read `.codeninja/tasks/generate-package-json.task.md`, `.codeninja/tasks/generate-hashing.task.md`, `.codeninja/tasks/generate-tsconfig.task.md` before generating each file.
+
+    - package.json → task: generate-package-json
+    - .env and .env.example → from context.current_init values
+    - .gitignore → task: generate-gitignore
+    - README.md → task: generate-readme
+    - config/constants.js → task: generate-constants
+    - config/template.js → task: generate-template
+    - logger/logging.js → task: generate-logging
+    - utilities/encryption.js → task: generate-encryption
+    - utilities/hashing.js (or .ts) → task: generate-hashing
+    - tsconfig.json → task: generate-tsconfig
+      (Only generated when language == "typescript")
+    - languages/<lang>.js for each in supported_languages[] → task: generate-language-en
+    - If `context.db.orm == "prisma"`:
+      - prisma/schema.prisma → task: generate-prisma-schema
+      - config/prisma.js (or .ts) → task: generate-prisma-client
+    - enc_dec.html OR enc_dec.php (based on client_type) → task: generate-enc-dec-html or generate-enc-dec-php
+    - <service_name>/pem/ directory with .gitkeep
+    - <service_name>/images/ directory with .gitkeep
+    - <service_name>/logger/logs/ directory with .gitkeep
+
+    ### Wave 2 — Infrastructure (depend on Wave 1 context, not on Wave 1 files)
+    These files reference logging.js and encryption.js at runtime but
+    their generation only needs context values — they can be written
+    while Wave 1 is still completing.
+
+    - config/database.js → task: generate-database
+      (Skipped when orm == "prisma" — Prisma client replaces it)
+    - utilities/ioRedis.js → task: generate-ioRedis
+    - utilities/response.js → task: generate-response
+
+    ### Wave 3 — Service Layer (depend on Wave 2 context)
+    These files reference database, ioRedis, and response at runtime.
+    Generation needs only context values.
+
+    - config/common.js → task: generate-common
+    - utilities/validator.js → task: generate-validator
+    - utilities/notification.js → task: generate-notification
+    - middleware/rateLimiter.js → task: generate-rateLimiter
+
+    ### Wave 4 — Middleware and Business Layer
+    headerValidator references encryption, response, ioRedis, and
+    all language files — all of which are complete by now.
+    route.js and model.js reference common, database, encryption,
+    response, validator — all complete by now.
+    swagger_doc.json skeleton needs no other generated files.
+    All four can be written simultaneously.
+
+    - middleware/headerValidator.js → task: generate-headerValidator
+    - modules/v1/<ServiceName>/route.js → task: generate-route
+    - modules/v1/<ServiceName>/<service>_model.js → task: generate-model
+    - document/v1/swagger_doc.json (skeleton) → task: generate-swagger (Mode 1)
+
+    ### Wave 5 — Orchestration Layer (must come last)
+    route_manager.js must know which module routes exist so it can
+    register them. It reads the module list from context.current_init
+    and the route files from Wave 4.
+    app.js must know the route_manager path.
+    Both depend on Wave 4 completing first. They can be written
+    simultaneously with each other.
+
+    - modules/v1/route_manager.js → task: generate-route-manager
+    - app.js → task: generate-app
+
+    ### Wave 6 — Docker Containerization (post-completion)
+    These files depend on the complete service being functional.
+    Can be written simultaneously.
+
+    - Dockerfile → task: generate-dockerfile
+    - .dockerignore → task: generate-dockerignore
+
+    ---
+
+    ## IF project_type == "reactjs"
+
+    Read `.codeninja/agent/reactjs-agent.md`.
+    Execute ALL generation steps below directly as the reactjs-agent.
+    Do NOT proceed to step 24 until every file listed in Waves 1–3
+    has been confirmed written to disk.
+
+    Pass values into generation:
+    - Full `context.current_init` including `linked_service`,
+      `linked_service_port`, `encryption_key`, `encryption_iv`, `api_key`
+
+    Generation rules:
+    - Do NOT pause between waves
+    - Do NOT ask for confirmation on individual files
+    - Do NOT skip any file — every file listed is required
+    - ALL paths are relative to <service_name>/ — NOT repo root
+    - Step 24 MUST NOT run until ALL 3 waves are complete
+
+    ## COMPLETION GATE (reactjs)
+    Before proceeding to step 24, verify these files exist on disk:
+    - <service_name>/public/index.html
+    - <service_name>/src/api/apiClient.js
+    - <service_name>/src/api/apiHandler.js
+    - <service_name>/src/App.jsx
+    - <service_name>/src/index.jsx
+    - <service_name>/.env
+    If any are missing → generate them now before continuing.
+    Only proceed to step 24 when ALL are confirmed present.
+
+    ## Generation Wave Structure (reactjs)
+
+    ### Wave 1 — Foundation (no dependencies)
+    All depend only on context values.
+
+    - package.json → task: generate-react-package-json
+    - .env and .env.example → task: generate-react-env
+      (values inherited from linked backend — no user input)
+    - .gitignore → task: generate-react-gitignore
+    - README.md → task: generate-readme
+      (agent adapts content for ReactJS: no Redis, no DB setup,
+      shows npm start instead of node app.js)
+    - public/index.html → task: generate-react-index-html
+    - public/assets/css/style.css → empty file with a reset comment
+    - public/robots.txt → standard disallow-all scaffold default
+    - public/favicon.ico → placeholder note (developer replaces)
+    - .htaccess (root) → task: generate-react-htaccess
+    - public/.htaccess → task: generate-react-htaccess
+
+    ### Wave 2 — API Layer
+    apiClient.js depends on .env values being defined (Wave 1).
+    apiHandler.js depends on apiClient.js being available.
+    Both can be written simultaneously since apiHandler only imports
+    from apiClient by reference — it does not read apiClient's content.
+
+    - src/api/apiClient.js → task: generate-react-api-client
+    - src/api/apiHandler.js → task: generate-react-api-handler
+
+    ### Wave 3 — Application Shell (must come last)
+    App.jsx must know which page components exist to import them.
+    index.jsx must import App.
+    Welcome page can be written alongside App.jsx since App only
+    imports it by reference.
+
+    - src/pages/Welcome/index.jsx → task: generate-react-welcome-page
+    - src/pages/Welcome/Welcome.module.css → task: generate-react-welcome-page
+    - src/App.jsx → task: generate-react-app-jsx
+    - src/index.jsx → task: generate-react-index-jsx
+    - src/components/ → create empty directory with .gitkeep
+
+    ### Wave 4 — Docker Containerization (post-completion)
+    These files depend on the complete React app being functional.
+    Can be written simultaneously.
+
+    - Dockerfile → task: generate-react-dockerfile
+    - nginx.conf → task: generate-react-dockerfile (same task generates both)
+    - .dockerignore → task: generate-dockerignore (reuse NodeJS task, adapted for React)
+
+23b. Run task: `generate-ide-configs`
+    - Condition: only on the FIRST @initialize-project run in this repo
+      (check: was context.initialized_at empty before this run started?)
+    - Writes: `.vscode/mcp.json` (VS Code)
+    - Writes: `.cursor/mcp.json` (Cursor)
+    - Prints: Claude Desktop config snippet for the user to add manually
+    - Skip silently if either config file already exists
+    - Do NOT block on the Claude Desktop step — it is print-only
+
+23c. Run task: `generate-docker-compose`
+    - Condition: ALWAYS run on every @initialize-project
+    - If docker-compose.yml does NOT exist at repo root → generate complete file
+    - If docker-compose.yml DOES exist → update it by adding the new service
+    - Also generate/update .env.docker and .env.docker.example at repo root
+    - Location: <repository_root>/docker-compose.yml (NOT inside service folder)
+
+24. Run task: `write-context`
+    - Set `project_name` = `context.current_init.service_name`
+      (top-level key — required for context.json to be valid)
+    - Set `initialized_at` = ISO now (top-level — first service init)
+    - Set `last_command` = "initialize-project"
+    - Append new service to `context.services[<service_name>]`
+      with all values from `context.current_init`
+    - For reactjs services: also store `linked_service` and
+      `linked_service_port` in the service entry so future commands
+      know which backend this frontend is bound to
+    - Update `context.project_info` with `initialized_at` timestamp
+    - Clear `context.current_init`
+
+25. Run task: `show-final-summary`
+    - Read `.codeninja/tasks/show-final-summary.task.md`
+    - List all files created in Waves 1–5
+    - Show startup commands
+    - Offer next steps: @db:create-table, @create-api, @design
+
+    NOTE: show-final-summary only runs AFTER step 24 (write-context)
+    completes successfully. Never show the final summary before
+    context.json has been written.