codeninja 3.1.0 → 3.2.0

package/ide/antigravity/.agents/workflows/codeninja-db-drop.md

@@ -2,10 +2,86 @@
 slash_command: /codeninja:db:drop
 personas: [global-orchestrator, database-architect]
 skills: [mcp-and-context, database]
-description: Drop a table with a DROP migration file
+description: Generate a DROP TABLE migration. Never deletes the original setup file.
 ---
+
 # /codeninja:db:drop
-Delegates to: `.codeninja/commands/db-drop-table.workflow.md`
-Before: `context_read`, `migration_next_number`.
-WARN user: "This is destructive. Confirm you want to DROP [table]?"
-After: `context_write` — remove table from context.db.schema.
+
+## Before Running
+1. Call `context_read` — load `context.db.schema`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Target
+
+**Step 1.** Ask: "Which table to drop?" (list from `context.db.schema.tables`)
+- Store: `context.current_db.table_name`
+
+---
+
+### Phase 2 — Impact Analysis
+
+**Step 2.** Agent scans context:
+- Check `context.api_routes` for routes referencing this table as `primary_table`
+- Check `context.services` for modules using this table
+- Check `context.db.schema.tables` for FK columns pointing to this table
+
+**Step 3.** If references found, display warning:
+```
+⚠ WARNING: This table is referenced by:
+  - [service]/modules/[Module] (primary_table)
+  - tbl_<other_table>.<col> → <this_table> (FK dependency)
+
+Dropping this table will break these references.
+Make sure to update or remove dependent code first.
+```
+Ask: "Do you still want to proceed? (yes / no)"
+If no → abort.
+
+**Step 4.** Final confirmation:
+Ask: "Type the table name to confirm the drop."
+Must match exactly — if wrong → abort.
+
+---
+
+### Phase 3 — File Numbering
+
+**Step 5.** Ask: "Migration file number?" (suggest next available)
+- Store: `context.current_db.file_number`
+
+---
+
+### Phase 4 — Generate
+
+**Step 6.** Delegate to database-agent:
+Generate: `<repo_root>/database/<db_type>/migrations/<number>-drop-tbl-<n>.sql`
+
+```sql
+-- Drop tbl_<table_name>
+-- Migration: <number>-drop-tbl-<n>.sql
+-- Generated: <ISO date>
+-- WARNING: This migration is irreversible in production.
+-- Original table definition: <original_setup_file>
+
+BEGIN;
+
+DROP TABLE IF EXISTS public.<table_name> CASCADE;
+
+COMMIT;
+```
+
+Update `create-schema.sql`:
+- Keep the original `\i <setup_file>` entry
+- Add the drop file entry AFTER it (never remove original)
+
+**Step 7.** Call `context_write`:
+- Snapshot full column list before removing from active tables
+- Append to `context.db.schema.change_log`:
+  `{ type: "table_dropped", table: "<n>", snapshot: { full column list }, file: "<path>" }`
+- Remove table from `context.db.schema.tables`
+- Clear `context.current_db`
+
+**Step 8.** Call `context_clear_scratchpad` with keys: ["current_db"]
+
+**Step 9.** Show final summary.

package/ide/antigravity/.agents/workflows/codeninja-db-index.md

@@ -2,10 +2,69 @@
 slash_command: /codeninja:db:index
 personas: [global-orchestrator, database-architect]
 skills: [mcp-and-context, database]
-description: Add a new index to an existing table with migration file
+description: Add a new index to an existing table.
 ---
+
 # /codeninja:db:index
-Delegates to: `.codeninja/commands/db-add-index.workflow.md`
-Before: `context_read`, `migration_next_number`.
-Show existing indexes from context.db.schema before suggesting new ones.
-After: `context_write` with updated index list.
+
+## Before Running
+1. Call `context_read` — load `context.db.schema`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Target Table
+
+**Step 1.** Ask: "Which table?" (list from `context.db.schema.tables`)
+- Store: `context.current_db.table_name`
+
+### Phase 2 — Index Columns
+
+**Step 2.** Ask: "Which column(s) for this index?"
+- List available columns from `context.db.schema.tables[<table>].columns`
+- Allow one or multiple (compound index)
+- Store: `context.current_db.index_columns[]`
+
+**Step 3.** Ask: "Should any column be sorted DESC?" (common: `created_at DESC`, `time DESC`)
+- If yes → ask which column(s)
+- Store: `context.current_db.index_desc_columns[]`
+
+**Step 4.** Ask: "Standard or partial index?"
+- Standard: covers all rows
+- Partial: only rows matching a WHERE condition — if partial, ask for WHERE clause
+- Store: `context.current_db.index_where_clause`
+
+### Phase 3 — File Placement
+
+**Step 5.** Ask: "Where should this index be defined?"
+1. In the table's own setup file (for new/just-created tables)
+2. In `111-setup-database-indexes.sql` (for existing tables — auto-suggested)
+- Store: `context.current_db.index_file`
+
+### Phase 4 — Generate
+
+**Step 6.** Agent auto-generates index name:
+- In table file: `idx_<table_without_tbl_prefix>_<columns_joined>`
+- In shared file: `idx_tbl_<table_without_tbl_prefix>_<columns_joined>`
+- Show: "Index will be named: <name> — OK? (yes / rename)"
+
+**Step 7.** Confirm: "Generate this index? (yes / no)"
+
+**Step 8.** Delegate to database-agent:
+```sql
+--
+-- Name: <index_name>; Type: INDEX; Schema: public
+--
+CREATE INDEX <index_name> ON public.<table_name> (<col> [DESC], ...)
+  [WHERE <where_clause>];
+```
+Append to correct file (table setup file OR `111-setup-database-indexes.sql`).
+
+**Step 9.** Call `context_write`:
+- Append index to `context.db.schema.tables[<table>].indexes`
+- Append to `context.db.schema.change_log`
+- Clear `context.current_db`
+
+**Step 10.** Call `context_clear_scratchpad` with keys: ["current_db"]
+
+**Step 11.** Show final summary.

package/ide/antigravity/.agents/workflows/codeninja-db-modify.md

@@ -2,10 +2,105 @@
 slash_command: /codeninja:db:modify
 personas: [global-orchestrator, database-architect]
 skills: [mcp-and-context, database]
-description: Add, rename, or drop a column via ALTER migration
+description: Modify an existing table via a numbered ALTER migration file.
 ---
+
 # /codeninja:db:modify
-Delegates to: `.codeninja/commands/db-modify-table.workflow.md`
-Before: `context_read`, `migration_next_number`.
-Show existing columns from context.db.schema before asking which to change.
-After: `context_write` with updated column list.
+
+## Before Running
+1. Call `context_read` — load `context.db.schema` fully
+2. Call `context_check_stale`
+3. Call `migration_next_number` to get next sequential number
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Target
+
+**Step 1.** Ask: "Which table?" (list from `context.db.schema.tables`)
+- Store: `context.current_db.table_name`
+
+**Step 2.** Ask: "What operation?"
+1. Add a new column
+2. Rename a column
+3. Drop a column
+4. Change a column type
+5. Add a CHECK constraint to an existing column
+6. Add a new index → route to /codeninja:db:index instead
+- Store: `context.current_db.modify_operation`
+
+---
+
+### Phase 2 — Operation Details
+
+#### If "Add a new column":
+- Ask: "New column name?" (snake_case, lowercase)
+- Ask: "Column type?" (show type suggestions from naming patterns — same as db:create)
+- Ask: "Is this an enum column?" — if yes, collect allowed values
+- Ask: "Add column after which existing column?" (list current columns from context)
+- SQL generated: `ALTER TABLE public.<table> ADD COLUMN <col> <type> NOT NULL DEFAULT <default>;`
+
+#### If "Rename a column":
+- Ask: "Which column to rename?" (list current columns from context)
+- Ask: "New column name?" (snake_case)
+- SQL generated: `ALTER TABLE public.<table> RENAME COLUMN <old> TO <new>;`
+
+#### If "Drop a column":
+- Ask: "Which column to drop?" (list current columns)
+- WARN: "This will generate a DROP COLUMN migration. This is irreversible in production.
+  Make sure you have removed all code references first."
+- Ask: "Confirm dropping column '<col>'? (yes/no)"
+- SQL generated: `ALTER TABLE public.<table> DROP COLUMN IF EXISTS <col>;`
+
+#### If "Change a column type":
+- Ask: "Which column?" (list current columns)
+- Ask: "New type?" (warn about potential data loss for narrower types)
+- SQL generated: `ALTER TABLE public.<table> ALTER COLUMN <col> TYPE <new_type> USING <col>::<new_type>;`
+
+#### If "Add CHECK constraint":
+- Ask: "Which column?" (list current columns)
+- Ask: "Allowed values?" (comma-separated)
+- SQL generated: `ALTER TABLE public.<table> ADD CONSTRAINT chk_<table>_<col> CHECK (<col> IN (<values>));`
+  Plus: `COMMENT ON COLUMN public.<table>.<col> IS '<enum explanation>';`
+
+---
+
+### Phase 3 — File Numbering
+
+**Step 7.** Ask: "Migration file number?" (agent suggests next available)
+- Store: `context.current_db.file_number`
+
+---
+
+### Phase 4 — Confirm and Generate
+
+**Step 8.** Show the exact SQL that will be generated. Ask: "Generate? (yes / no)"
+
+**Step 9.** Delegate to database-agent:
+Generate: `<repo_root>/database/<db_type>/migrations/<number>-alter-tbl-<n>-<description>.sql`
+
+Full file structure:
+```sql
+-- Alter tbl_<table>: <description>
+-- Migration: <number>-alter-tbl-<n>-<description>.sql
+-- Generated: <ISO date>
+
+BEGIN;
+
+ALTER TABLE public.<table_name>
+  <operation>;
+
+-- COMMENT ON COLUMN if enum/flag column
+-- CREATE INDEX if new column needs one
+
+COMMIT;
+```
+Update: `database/<db_type>/create-schema.sql`
+
+**Step 10.** Call `context_write`:
+- Update `context.db.schema.tables[<table>].columns`
+- Append to `context.db.schema.change_log`
+- Clear `context.current_db`
+
+**Step 11.** Call `context_clear_scratchpad` with keys: ["current_db"]
+
+**Step 12.** Show final summary.

package/ide/antigravity/.agents/workflows/codeninja-db-seed.md

@@ -2,9 +2,75 @@
 slash_command: /codeninja:db:seed
 personas: [global-orchestrator, database-architect]
 skills: [mcp-and-context, database]
-description: Add or update seed data for a table
+description: Add seed/initial data to a table.
 ---
+
 # /codeninja:db:seed
-Delegates to: `.codeninja/commands/db-seed.workflow.md`
-Before: `context_read` — load context.db.schema for real column names.
-After: `context_write` to record seed file location.
+
+## Before Running
+1. Call `context_read` — load `context.db.schema`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Target
+
+**Step 1.** Ask: "Which table?" (list from `context.db.schema.tables`)
+- Store: `context.current_db.table_name`
+
+### Phase 2 — Seed File Type
+
+**Step 2.** Determine seed target:
+- Reference tables (seed goes IN setup file): lookup tables, master/config tables
+- All other tables: standalone seed file in seeds/
+
+Ask: "Where should this seed data go?"
+1. Append to the table's setup file (for reference/master data)
+2. Create standalone seed file in seeds/ (for dev/test data)
+- Store: `context.current_db.seed_target`
+
+### Phase 3 — Data Collection
+
+**Step 3.** Show column list from context (excluding `id` and `created_at` — auto-generated).
+
+**Step 4.** Ask: "How many rows do you want to seed?"
+- Store: `context.current_db.seed_count`
+
+**Step 5.** For each row (repeat seed_count times):
+- Ask value for each column one at a time
+- If column is `password` → warn: "Enter the encrypted/hashed value only. Never store plaintext."
+- If column has CHECK constraint → show allowed values
+- If column has DEFAULT → offer to use default (press Enter to skip)
+- Append to: `context.current_db.seed_rows[]`
+
+### Phase 4 — Generate
+
+**Step 6.** Show full INSERT preview. Ask: "Generate this seed data? (yes / no)"
+
+**Step 7.** Delegate to database-agent:
+
+If appending to setup file → append after the GRANT line:
+```sql
+INSERT INTO public.<table_name> (<col1>, <col2>, ...) VALUES
+(<val1a>, <val2a>, ...),
+(<val1b>, <val2b>, ...);
+```
+
+If standalone seed file → generate `database/<db_type>/seeds/<table_name>_seed.sql`:
+```sql
+-- Seed data for <table_name>
+-- Environment: development
+-- Generated: <ISO date>
+
+INSERT INTO public.<table_name> (<col1>, <col2>, ...) VALUES
+(<val1a>, <val2a>, ...),
+(<val1b>, <val2b>, ...);
+```
+
+**Step 8.** Call `context_write`:
+- Append to `context.db.schema.change_log`: `{ type: "seed_added", table: "<n>", rows: <count> }`
+- Clear `context.current_db`
+
+**Step 9.** Call `context_clear_scratchpad` with keys: ["current_db"]
+
+**Step 10.** Show final summary.

package/ide/antigravity/.agents/workflows/codeninja-db-sync.md

@@ -2,11 +2,69 @@
 slash_command: /codeninja:db:sync
 personas: [global-orchestrator, database-architect]
 skills: [mcp-and-context, database]
-description: Scan migration files and rebuild context.db.schema
+description: Scan all migration files and rebuild context.db.schema from actual file contents.
 ---
+
 # /codeninja:db:sync
-Delegates to: `.codeninja/commands/db-sync.workflow.md`
-Before: `context_read`, `fs_list` all migration files.
-Compare files on disk vs context.db.schema — surface all gaps.
-User approves before context is updated.
-After: `context_write` with fully rebuilt context.db.schema.
+
+## Before Running
+1. Call `context_read`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Locate Files
+
+**Step 1.** Read `context.db.type` → find `<repo_root>/database/<db_type>/migrations/`
+**Step 2.** List all `.sql` files, sort by numeric prefix (1, 2, 3… 111)
+**Step 3.** Categorize:
+- setup files: `*-setup-tbl-*.sql`
+- alter files: `*-alter-tbl-*.sql`
+- drop files: `*-drop-tbl-*.sql`
+- index file: `111-setup-database-indexes.sql`
+
+### Phase 2 — Parse Each File
+
+For each setup file (in order):
+- Extract table name from CREATE TABLE
+- Extract all column names and types
+- Extract CHECK constraints and COMMENT ON COLUMN lines (enum descriptions)
+- Extract per-file CREATE INDEX lines
+- Note if table has `status`, `is_deleted`, `created_at`
+
+For each alter file (in order after its setup file):
+- ADD COLUMN → add to that table's columns
+- RENAME COLUMN → update name, record in change_log
+- DROP COLUMN → remove from columns
+- ADD CONSTRAINT → update column constraint info
+
+For each drop file: mark table as dropped.
+
+For the index file: parse all CREATE INDEX, associate each with its table.
+
+### Phase 3 — Rebuild Context
+
+For each discovered table (not dropped):
+- Compare with existing `context.db.schema.tables[<table>]`
+- Add tables not already in context
+- Add columns not already tracked
+- Add indexes not already tracked
+- For renames in ALTER files → append to change_log if not already there
+
+For dropped tables:
+- If still in `context.db.schema.tables` → move to change_log snapshot, remove from active tables
+
+### Phase 4 — Rebuild create-schema.sql
+
+- Re-read all filenames in correct numeric order
+- Rewrite `create-schema.sql` to match actual files on disk
+- Report: any `\i` entries in create-schema.sql missing from disk (stale)
+- Report: any files on disk not in create-schema.sql (missing)
+
+### Phase 5 — Finalize
+
+**Step 5.** Show sync report: tables synced, columns added, indexes added, stale entries, missing files.
+
+**Step 6.** Call `context_write` with rebuilt `context.db.schema`.
+
+**Step 7.** Show final summary.

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

@@ -2,11 +2,81 @@
 slash_command: /codeninja:debug
 personas: [global-orchestrator, nodejs-backend]
 skills: [mcp-and-context, api-builder, code-intelligence]
-description: Diagnose and fix a bug by tracing the actual request code path
+description: Diagnose and fix bugs using full project context and code path tracing.
 ---
+
 # /codeninja:debug
-Delegates to: `.codeninja/commands/debug.workflow.md`
-Before: `context_read`. Gather: error + stack, endpoint, expected vs actual, recent changes.
-Trace full request lifecycle. Find exact failure step.
-Output: root cause + before/after fix. Confirm before applying.
-Suggest one guard to prevent recurrence.
+
+## Before Running
+1. Call `context_read` — load services, DB schema, project config
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Step 1 — Gather Error Information (ask one at a time if not provided)
+1. "Paste the full error message and stack trace."
+2. "Which endpoint or operation triggered it? (e.g., POST /v1/scores/submit)"
+3. "What did you expect vs what actually happened?"
+4. "What changed recently before this error appeared?"
+
+### Step 2 — Load Context
+1. Call `fs_read` on the relevant `route.js`
+2. Call `fs_read` on the relevant `_model.js`
+3. Call `fs_exists` on the migration file for any table mentioned in the error
+
+### Step 3 — Trace the Failure Path
+
+Walk the request lifecycle in order — mark the exact step where failure occurs:
+```
+Request received
+  → Language middleware (extracts Accept-Language)
+  → API key middleware (validates api-key header)
+  → Auth middleware (validates JWT if protected)
+  → Validation (validatorjs schema)
+  → Route handler (calls model)
+  → Model function (executes query)
+  → Database (pg pool / mysql2 / mongoose)
+  → Response formatter
+```
+
+### Step 4 — Check Common Root Causes
+
+| Symptom | Check |
+|---|---|
+| `column does not exist` | context.db.schema vs actual column names in model.js |
+| `undefined is not a function` | wrong import path or missing export in model |
+| `Cannot read property of undefined` | missing null check after DB query returns 0 rows |
+| `401 Unauthorized` | middleware order — apiKey middleware applied? header name correct? |
+| `500 Internal Server Error` | missing try/catch around async DB call |
+| `Wrong number of rows` | missing dedup, RANK vs DENSE_RANK, missing WHERE clause |
+| `Migration not applied` | table exists in code but not in DB — run migration |
+| Stale context data | context.db.schema out of date — suggest /codeninja:db:sync |
+
+### Step 5 — Produce Fix
+
+```
+Root cause: [one sentence — be precise]
+
+Fix:
+File: path/to/file.js
+
+Before:
+[the buggy code]
+
+After:
+[the corrected code]
+
+Why this fixes it: [one sentence]
+```
+
+If multiple files need changes, show each in order.
+
+### Step 6 — Verify Plan
+
+"Before I apply this fix, confirm: does this match what you're seeing?
+Once confirmed, I'll make the changes."
+
+### Step 7 — Prevent Recurrence
+
+After fixing: suggest one guard that prevents this class of bug in the future.
+(e.g., a missing index, an added null check helper, a context convention)

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

@@ -1,21 +1,54 @@
 ---
 slash_command: /codeninja:design
-personas: [global-orchestrator, nodejs-backend OR database-architect]
-skills: [mcp-and-context, api-builder OR database]
-description: Plan a feature, API contract, or DB change before writing any code
+personas: [global-orchestrator, nodejs-backend, database-architect]
+skills: [mcp-and-context, api-builder, database]
+description: Plan a feature, API contract, or database change before writing any code.
 ---
 
 # /codeninja:design
 
-Delegates to: `.codeninja/commands/design.workflow.md`
-
 ## Before Running
-1. Call `context_read` — load full project context
-2. Determine if this is an API design (nodejs-backend + api-builder) or DB design (database-architect + database)
+1. Call `context_read`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Phase 1 — Scope
+
+**Step 1.** Ask: "What are you designing?"
+- Options: new feature / new API endpoint / database change / full module
+- Store: `context.current_design.type`
+
+**Step 2.** Ask: "Feature or module name?"
+- Store: `context.current_design.feature_name`
+
+**Step 3.** Ask: "What should this feature do?" (free text)
+- Store: `context.current_design.description`
+
+### Phase 2 — Database Design (if applicable)
+
+**Step 4.** If design involves data storage:
+- Delegate to database-agent
+- Design table structure, column types, indexes, relationships
+- Present schema proposal for feedback
+- Allow changes one at a time
+
+### Phase 3 — API Design (if applicable)
+
+**Step 5.** If design involves API endpoints:
+- Delegate to nodejs-agent
+- Propose: method, path, request body, response shape, auth requirement
+- Present for feedback
+
+### Phase 4 — Output
+
+**Step 6.** Generate `.codeninja/agent/designs/<feature_name>.design.md`:
+- Feature summary
+- DB schema proposal (tables, columns, indexes, relationships)
+- API contracts (method, path, request, response shape)
+- Open questions / decisions needed
 
-## Execution
-Read and execute `design.workflow.md` step by step.
-Produce a written plan before any code is generated. User approves plan before execution begins.
+**Step 7.** Ask: "Save this design and mark planned routes/schema in context? (yes/no)"
+If yes → call `context_write` with operation "design", then `context_clear_scratchpad` ["current_design"]
 
-## After Running
-Call `context_write` with design notes stored in `context.current_design`.
+**Step 8.** Show final summary.

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

@@ -1,11 +1,40 @@
 ---
 slash_command: /codeninja:explain
-personas: [global-orchestrator, context-aware]
+personas: [global-orchestrator]
 skills: [mcp-and-context, code-intelligence]
-description: Explain any file, function, pattern, or concept with full project context
+description: Explain any file, function, pattern, or concept using full project context.
 ---
+
 # /codeninja:explain
-Delegates to: `.codeninja/commands/explain.workflow.md`
-Before: call `context_read`, `fs_read` on target.
-Structure: What it is → How it works → Why this way → Where it connects.
-Use real names from context. End with offer to explain further.
+
+## Before Running
+1. Call `context_read`
+2. Call `context_check_stale`
+
+## Execution — Full Step-by-Step
+
+### Step 1 — Identify Target
+If not specified, ask: "What would you like me to explain?
+(e.g., a file path, a function name, a pattern like 'the auth middleware',
+or a concept like 'why we use DENSE_RANK')"
+
+### Step 2 — Load Context
+1. Call `fs_read` on the target file (if a file was specified)
+2. Read 1 related file to understand how the target fits in the system
+3. Reference `context.db.schema` for any table/column mentions
+4. Reference `context.services` for service names and ports
+
+### Step 3 — Explain
+
+Structure every explanation as:
+
+**What it is** (1–2 sentences — plain English)
+
+**How it works** (step-by-step walkthrough of the key logic)
+
+**Why this way** (the architectural decision behind it)
+
+**Where it connects** (related files and functions in this project — use real names)
+
+### Step 4 — Offer Follow-up
+End with: "Want me to explain any part in more detail, or show how to modify it?"