codeninja 3.1.0 → 4.0.0

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

@@ -1,12 +1,96 @@
+This workflow runs when user invokes /codeninja:debug
+
 ---
-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
+type: workflow
+name: debug
+description: >
+  Diagnose and fix bugs using full project context — DB schema, middleware
+  chain, service config, and established patterns. Traces the exact failure
+  path and produces a concrete fix.
 ---
-# /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.
+
+# Workflow: @debug / /codeninja:debug
+
+## Goal
+Find the root cause of a bug and produce a concrete fix using actual project
+context. Never guess — trace the real code path.
+
+## Rules
+- Trace the full request path before concluding anything
+- Cross-reference context.db.schema before assuming a DB mismatch
+- Check middleware chain order before assuming an auth issue
+- One question at a time when gathering information
+
+---
+
+## Step-by-Step Execution
+
+### Step 1 — Gather Error Information
+Ask (one at a time if not already 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 to happen vs what actually happened?"
+4. "What changed recently before this error appeared?"
+
+### Step 2 — Load Context
+1. Call `context_read` — load services, DB schema, project config
+2. Call `fs_read` on the relevant route.js
+3. Call `fs_read` on the relevant _model.js
+4. 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:
+```
+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)
+  → Response formatter
+```
+
+Mark the exact step where the error occurs.
+
+### 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 query, 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 one 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,68 @@
+This workflow runs when user invokes /codeninja:design
+
+---
+type: workflow
+name: design
+description: >
+  Plan a feature, API contract, or database change before writing any code.
+  Produces a design document and optionally updates context with the planned
+  schema or routes for other agents to reference.
 ---
-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
+
+# Workflow: @design
+
+## Goal
+Think before coding. Produce a structured design plan that becomes the
+contract for `@create-api`, `@initialize-project`, or manual implementation.
+
+## Rules
+- No files are generated unless user explicitly confirms
+- Design output is stored in `.codeninja/agent/designs/<feature_name>.design.md`
+- Approved designs update context with planned routes and schema
+
 ---
 
-# /codeninja:design
+## Step-by-Step Execution
+
+### Phase 1 — Scope
+1. Run task: `ask-design-target`
+   - Options: new feature, new API endpoint, database change, full module
+   - Stores: `context.current_design.type`
+
+2. Run task: `ask-feature-name`
+   - Stores: `context.current_design.feature_name`
 
-Delegates to: `.codeninja/commands/design.workflow.md`
+3. Run task: `ask-design-description`
+   - Free text: what should this feature do?
+   - Stores: `context.current_design.description`
 
-## 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)
+---
+
+### Phase 2 — Database Design (if applicable)
+4. If design involves data storage:
+   - Delegate to `database-agent`
+   - Design table structure, column types, indexes, relationships
+   - Present schema proposal to user for feedback
+   - Allow user to request changes (one change at a time)
+
+---
+
+### Phase 3 — API Design (if applicable)
+5. If design involves API endpoints:
+   - Delegate to `nodejs-agent`
+   - Propose: method, path, request body, response shape, auth requirement
+   - Present to user for feedback
+
+---
 
-## 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.
+### Phase 4 — Output
+6. Generate `.codeninja/agent/designs/<feature_name>.design.md` containing:
+   - Feature summary
+   - DB schema proposal (tables, columns)
+   - API contracts (method, path, request, response)
+   - Open questions / decisions needed
 
-## After Running
-Call `context_write` with design notes stored in `context.current_design`.
+7. Ask: "Save this design and mark planned routes/schema in context? (yes/no)"
+8. If yes → run task: `write-context` with operation = "design"
+   Then call: context_clear_scratchpad with keys: ["current_design"]
+9. Run task: `show-final-summary`

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

@@ -1,11 +1,61 @@
+This workflow runs when user invokes /codeninja:explain
+
 ---
-slash_command: /codeninja:explain
-personas: [global-orchestrator, context-aware]
-skills: [mcp-and-context, code-intelligence]
-description: Explain any file, function, pattern, or concept with full project context
+type: workflow
+name: explain
+description: >
+  Explain any file, function, pattern, or architectural concept in this project
+  using full project context. Useful for onboarding, code review, and exam prep.
 ---
-# /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.
+
+# Workflow: @explain / /codeninja:explain
+
+## Goal
+Give a clear, context-aware explanation of any part of the codebase.
+Reference real file names, table names, service names — never placeholders.
+
+## Rules
+- Always read the actual file before explaining it
+- Use `context.db.schema` to reference real table/column names
+- Use `context.services` to reference real service names and ports
+- Explain the "why" not just the "what"
+
+---
+
+## Step-by-Step Execution
+
+### 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 MCP tool `context_read`
+2. Call MCP tool `fs_read` on the target file (if a file was specified)
+3. Read 1 related file to understand how the target fits in the system
+
+### Step 3 — Explain
+
+Structure the explanation as:
+
+**What it is** (1–2 sentences — plain English)
+> This is the route handler for the leaderboard endpoint. It validates the
+> incoming request, calls the model to fetch ranked scores, and returns them
+> in the project's standard response format.
+
+**How it works** (step-by-step walkthrough of the key logic)
+> 1. The `apiKeyMiddleware` checks the `api-key` header against the env value
+> 2. `validatorjs` ensures `weekId` is present and a non-empty string
+> 3. `LeaderboardModel.getTopScores(weekId)` runs the DENSE_RANK query
+> 4. The result is wrapped in `{ status: 1, message: lang.success, data: rows }`
+
+**Why this way** (the architectural decision)
+> We use DENSE_RANK instead of RANK because tied scores should get the same
+> position without gaps — position 3 should follow position 2, even with ties.
+
+**Where it connects** (related files/functions)
+> - Model: `modules/v1/Leaderboard/leaderboard_model.js`
+> - Language strings: `languages/en.js` → `leaderboard_success`
+> - Route registration: `modules/v1/route_manager.js` line ~45
+
+### Step 4 — Offer Follow-up
+End with: "Want me to explain any part in more detail, or show how to modify it?"