codeninja 3.2.0 → 4.0.0

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

@@ -1,216 +1,334 @@
+This workflow runs when user invokes /codeninja:modularize
+
 ---
-slash_command: /codeninja:modularize
-personas: [global-orchestrator, reactjs-frontend]
-skills: [mcp-and-context, reactjs, code-intelligence]
+type: workflow
+name: modularize
 description: >
-  Scan ReactJS pages, extract repeated layout blocks into reusable components
-  under src/components/, and update each page to import and use them.
-  Layout structure only — never touches business logic, state, or API calls.
+  Scans one or all ReactJS pages, extracts repeated layout blocks
+  (header, footer, sidebar, navbar, etc.) into reusable components,
+  and rewrites each page to import and use those components. Reuses
+  existing components when they already exist. Never rewrites component
+  logic — layout structure only.
 ---
 
-# /codeninja:modularize
+# Workflow: @modularize
 
-## Before Running
-1. Call `context_check_stale`
-2. Call `context_read` — load `context.services` to find ReactJS services
-3. Call `service_scan` — verify ReactJS service exists on disk
+## Goal
+Identify repeated structural blocks across pages, create shared components
+for them under `src/components/`, and update each page to use the new
+components. Result: zero duplicated layout HTML across the project.
 
 ## Rules
 - Read ALL target pages fully before creating any component
-- NEVER create a component that already exists in `src/components/` — reuse it
-- NEVER modify business logic, state, API calls, or event handlers in any page
+- NEVER create a component that already exists under `src/components/`
+  — reuse it instead
+- NEVER modify business logic, state, API calls, or event handlers
+  in any page file — layout structure only
 - NEVER break existing imports or prop flows
 - ONE confirmation before any file is written
-- After writing files → call `context_write`
+- After writing files → run task: `write-context`
 
 ---
 
-## Execution — Full Step-by-Step
+## Step-by-Step Execution
+
+---
 
 ### Phase 1 — Target Selection
 
-**Step 1.** Ask: "Which ReactJS service?" (list ReactJS services from `context.services`)
-- Store: `context.current_action.service_name`
+1. Run task: `ask-react-target-service`
+   Stores: `context.current_action.service_name`
 
-**Step 2.** Ask: "What scope?"
-1. All pages — scan every page in `src/pages/` and `src/views/`
-2. Specific page — I'll provide the path
-- Store: `context.current_action.modularize_scope`
-- If specific → also ask: "Page path?" → Store: `context.current_action.page_path`
+2. Run task: `ask-modularize-scope`
+   Stores: `context.current_action.modularize_scope`
+   If scope == "specific" → also stores `context.current_action.page_path`
 
 ---
 
 ### Phase 2 — Inventory Existing Components
 
-Before scanning any pages, inventory what already exists:
+Before scanning pages, inventory what already exists:
 
-**Step 1.** Scan `src/components/` in the target service.
-For each subdirectory → record component name and file path.
+1. Scan `src/components/` in the target service.
+   For each subdirectory → record the component name and its file path.
+   Example findings:
+     - `src/components/Header/index.jsx` → component: Header
+     - `src/components/Sidebar/index.jsx` → component: Sidebar
+     - `src/components/layout/Navbar/index.jsx` → component: Navbar
 
-**Step 2.** For each existing component:
-- Read the file
-- Identify structural role: header, footer, sidebar, navbar, modal wrapper, card shell, breadcrumbs, etc.
-- Record: `{ name, path, role, props_accepted }`
+2. For each existing component:
+   - Read the file
+   - Identify what structural role it plays (header, footer, sidebar,
+     navbar, modal wrapper, card shell, breadcrumbs, etc.)
+   - Record: `{ name, path, role, props_accepted }`
 
-Store this as the "existing components registry" — the source of truth for reuse decisions.
+3. Store the full inventory as the "existing components registry" in memory.
+   This is the source of truth for the reuse decision in Phase 4.
 
 ---
 
 ### Phase 3 — Scan Target Pages
 
 #### If scope == "all":
-Scan `src/pages/` — each subdirectory with `index.jsx` or `index.js` = one page.
+Scan `src/pages/` — for each subdirectory containing `index.jsx` or
+`index.js`, add it to the pages list.
 Also scan `src/views/` if it exists.
 
 #### If scope == "specific":
 Pages list = [ context.current_action.page_path ]
 
-For each page:
+For each page in the pages list:
+
+1. Read the full file content.
+
+2. Parse the JSX structure to identify the top-level layout blocks.
+   A layout block is a JSX subtree that:
+   - Appears at the top level of the return statement (not inside
+     a conditional or a list map)
+   - Has a clear structural role in the visual layout
+   - Does NOT contain unique per-page business logic
+
+3. Classify each block using these roles (in priority order):
+   - **header** — contains site logo, navigation links, user avatar/menu,
+     search bar. Typically rendered at the very top of every page.
+   - **footer** — copyright text, footer links, social icons. Bottom.
+   - **sidebar** — vertical navigation panel, collapsible menu, drawer.
+   - **navbar** — horizontal navigation bar, tab bar, breadcrumbs.
+   - **topbar** — page title row with action buttons (e.g. "Users | + Add New")
+   - **page-wrapper** — the outer container div that sets max-width,
+     padding, or background — wraps all page content.
+   - **card** — a bordered/shadowed container used for data display.
+     Only extract as a component if it appears in 2+ pages unchanged.
+   - **modal-shell** — the backdrop + centered box wrapper for modals.
+     Only extract if used in 2+ pages unchanged.
+
+4. Record for each block:
+   - Role (from list above)
+   - Exact JSX tree content
+   - Props/variables it references from the parent page scope
+   - Which pages it appears in (identical or near-identical)
+
+---
+
+### Phase 4 — Decide: Create vs Reuse vs Skip
+
+For each block found across all pages, make one of three decisions:
 
-**Step 1.** Read the full file content.
+**REUSE** — an existing component from Phase 2 already covers this role.
+  Condition: an existing component has the same `role` AND its structure
+  matches the block (same element types, same general layout — minor
+  class name differences are acceptable).
+  Action: the page will import the existing component. No new file created.
 
-**Step 2.** Identify all structural blocks (layout HTML — NOT business logic):
-- Look for repeated layout patterns: `<header>`, `<nav>`, `<footer>`, `<aside>`, sidebar wrappers
-- Look for structural patterns repeated across pages: top nav bars, breadcrumb areas, page wrappers
-- Record each structural block as: `{ block_type, jsx_content, props_needed }`
+**CREATE** — no existing component covers this role.
+  Condition: no match in existing components registry.
+  Additional condition: the block appears in at least ONE page
+  (for header/footer/sidebar/navbar/topbar/page-wrapper — always create
+  even if seen on only one page, because they are foundational layout).
+  For card/modal-shell → only create if seen on 2+ pages unchanged.
+  Action: a new component will be created.
 
-**Step 3.** Cross-check against existing components registry:
-- Does a component already exist that covers this block?
-- If YES → mark as "reuse existing: <ComponentName>"
-- If NO → mark as "new component needed: <ComponentName>"
+**SKIP** — the block is too unique to extract.
+  Condition: the block contains page-specific state, API calls, or
+  dynamic content that cannot be expressed as simple props.
+  Example: a sidebar that renders a different menu depending on user role
+  and reads from a page-specific hook → SKIP.
+  Action: leave the block inline in the page. Note it in the report.
 
 ---
 
-### Phase 4 — Deduplicate Across Pages
+### Phase 5 — Build Component Plan
+
+For each block decided as CREATE, determine:
 
-After scanning all pages:
+1. **Component name** — PascalCase of the role.
+   Examples: Header, Footer, Sidebar, Navbar, PageTopbar, PageWrapper,
+   DataCard, ModalShell.
+   If a more specific name is obvious from the content
+   (e.g. the sidebar contains "Admin Menu") → use AdminSidebar.
 
-**Step 1.** Group blocks by structural similarity across pages.
-- If the same header JSX appears in 3+ pages → one shared Header component
-- If a sidebar appears in 2+ pages → one shared Sidebar component
-- If a block appears in only 1 page → do NOT extract it (no duplication benefit)
+2. **File path** — `src/components/<ComponentName>/index.jsx`
+   and `src/components/<ComponentName>/<ComponentName>.module.css`
 
-**Step 2.** For each component to create, decide:
-- Component name (PascalCase, descriptive: `PageHeader`, `AppSidebar`, `MainFooter`)
-- Props needed (what varies between pages: title, navLinks, userName, etc.)
-- File location: `src/components/<ComponentName>/index.jsx` and `<ComponentName>.module.css`
+3. **Props** — anything the block references from the parent scope
+   that varies between pages must become a prop.
+   Examples:
+   - Page title → `title` prop
+   - Active nav item → `activeItem` prop
+   - User display name in header → `userName` prop
+   Common static content (logo, copyright text, link list) → hardcoded
+   inside the component, not a prop.
+
+4. **CSS extraction** — any inline styles or style classes that belong
+   only to this block are moved to the component's `.module.css` file.
+   Classes shared with the rest of the page remain in the page's own
+   `.module.css`. Do not break existing page styles.
 
 ---
 
-### Phase 5 — Show Extraction Plan
+### Phase 6 — Show Plan and Confirm
 
-Display the plan before writing anything:
+Display the modularization plan:
 
 ```
-┌─────────────────────────────────────────────────────┐
-│           MODULARIZE PLAN                           │
-├─────────────────────────────────────────────────────┤
-│ Service  : [service_name]                           │
-│ Scope    : [all pages | specific page]              │
-│ Pages    : [n] scanned                              │
-├─────────────────────────────────────────────────────┤
-│ COMPONENTS TO CREATE                                │
-│  ✦ AppHeader — appears in [n] pages                 │
-│    Props: title (string)                            │
-│    File:  src/components/AppHeader/index.jsx        │
-│                                                     │
-│  ✦ MainSidebar — appears in [n] pages               │
-│    Props: activeRoute (string)                      │
-│    File:  src/components/MainSidebar/index.jsx      │
-├─────────────────────────────────────────────────────┤
-│ COMPONENTS REUSED (already exist)                   │
-│  ✓ Footer — src/components/Footer/index.jsx         │
-├─────────────────────────────────────────────────────┤
-│ PAGES TO UPDATE                                     │
-│  → src/pages/Dashboard/index.jsx                   │
-│  → src/pages/Profile/index.jsx                     │
-│  → src/pages/Settings/index.jsx                    │
-└─────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────┐
+│              MODULARIZATION PLAN                     │
+├──────────────────────────────────────────────────────┤
+│ Service     : [service_name]                         │
+│ Pages scanned: [n]                                   │
+├──────────────────────────────────────────────────────┤
+│ COMPONENTS TO CREATE                                 │
+│  → src/components/Header/index.jsx                   │
+│    Props: userName, activeItem                       │
+│    Used by: Login, Dashboard, Profile (3 pages)      │
+│                                                      │
+│  → src/components/Footer/index.jsx                   │
+│    Props: none                                       │
+│    Used by: all 3 pages                              │
+├──────────────────────────────────────────────────────┤
+│ COMPONENTS TO REUSE (already exist)                  │
+│  → src/components/Sidebar/index.jsx [existing]       │
+│    Will be imported into: Dashboard, Profile         │
+├──────────────────────────────────────────────────────┤
+│ BLOCKS SKIPPED (too page-specific to extract)        │
+│  → Dashboard hero banner — contains dynamic API data │
+├──────────────────────────────────────────────────────┤
+│ PAGES TO UPDATE                                      │
+│  → src/pages/Login/index.jsx                         │
+│  → src/pages/Dashboard/index.jsx                     │
+│  → src/pages/Profile/index.jsx                       │
+└──────────────────────────────────────────────────────┘
 ```
 
-Ask: "Apply this plan? (yes / no / adjust)"
-- If yes → proceed to Phase 6
-- If no → abort, nothing written
-- If adjust → ask what to change → re-display plan
+Ask exactly this question:
+"Proceed with this modularization plan? (yes / no / adjust)"
 
----
+- If yes → proceed to Phase 7 immediately
+- If no → abort. Nothing is created.
+- If adjust → ask: "What would you like to change?"
+  Allow the user to exclude a component, rename one, or change a
+  prop assignment. Apply the adjustment and re-display the plan.
 
-### Phase 6 — Generate Components
-
-For each new component:
-
-**Step 1.** Generate `src/components/<ComponentName>/index.jsx`:
-```jsx
-/**
- * <ComponentName> — <one-line description of structural role>.
- *
- * @param {Object} props
- * @param {string} props.<propName> - <description>
- * @returns {JSX.Element}
- */
-function <ComponentName>({ <props> }) {
-  return (
-    <extracted JSX block, using props where values varied>
-  );
-}
-
-export default <ComponentName>;
-```
+---
 
-**Step 2.** Generate `src/components/<ComponentName>/<ComponentName>.module.css`:
-- Extract any inline styles or className references that were in the original block
-- Create CSS classes for them
-- If no styles → empty file with a comment: `/* <ComponentName> styles */`
+### Phase 7 — Generate Components
+
+For each component in the CREATE list:
+
+#### Generate `src/components/<ComponentName>/index.jsx`
+
+Structure:
+- JSDoc block above the component:
+  ```
+  /**
+   * [Role] component shared across all pages.
+   *
+   * @param {Object} props
+   * @param {string} [props.<propName>] - [description]  ← one line per prop
+   * @returns {JSX.Element}
+   */
+  ```
+- Import React at the top
+- Import CSS module: `import styles from './<ComponentName>.module.css'`
+- Functional component with props destructured in the signature
+- JSX extracted verbatim from the source page, with parent-scope
+  variable references replaced by the corresponding prop name
+- Default export
+
+#### Generate `src/components/<ComponentName>/<ComponentName>.module.css`
+
+- Move all CSS classes that belong exclusively to this component's
+  block from the source page's `.module.css`
+- If no specific classes are used → generate an empty file with a
+  comment: `/* Styles for <ComponentName> */`
 
 ---
 
-### Phase 7 — Update Pages
+### Phase 8 — Update Pages
 
-For each page that used the extracted block:
+For each page in the pages list that references at least one component
+(created or reused):
 
-**Step 1.** Read the current page file.
+Read the current page file. Apply these surgical edits:
 
-**Step 2.** Apply changes surgically:
-1. Add import at top of file:
+1. **Add imports** at the top of the file, after existing imports:
    ```jsx
-   import <ComponentName> from '../../components/<ComponentName>';
+   import Header from '../../components/Header';
+   import Footer from '../../components/Footer';
    ```
-   (adjust relative path based on page depth)
+   Use the correct relative path from the page file's location to
+   `src/components/`. Always use `../../components/` from the standard
+   `src/pages/<PageName>/` depth.
 
-2. Replace the extracted JSX block with the component:
-   ```jsx
-   <ComponentName <prop>={<value>} />
-   ```
+2. **Replace the extracted JSX block** with the component tag.
+   Pass any required props using the values that were previously
+   inline in the page.
+   Example:
+   Before: `<header className={styles.header}><nav>...</nav></header>`
+   After:  `<Header activeItem="dashboard" userName={user.name} />`
+
+3. **Remove orphaned imports** — if the original block used an import
+   that is no longer referenced in the page after extraction
+   (e.g. a logo image import that moved into the Header component) →
+   remove it from the page's import list.
 
-3. Remove any now-unused imports that were only used by the extracted block.
+4. **Clean up orphaned CSS classes** — if classes were moved to the
+   component's CSS module, remove them from the page's `.module.css`.
 
-4. Remove any CSS classes in the page's `.module.css` that are now handled by the component's own CSS file.
+Never modify:
+  - Business logic functions (state, useEffect, API calls)
+  - The page's own JSX content outside the extracted blocks
+  - Event handlers, form logic, any non-layout code
 
-**Step 3.** Write the updated file.
+> **Multi-agent:** Delegate to `reactjs-frontend` via Task invocation for parallel execution.
+> Read `.codeninja/tasks/` before generating each component and updating pages.
 
 ---
 
-### Phase 8 — Finalize
+### Phase 9 — Write Context and Report
 
-**Step 1.** Call `context_write`:
+Run task: `write-context` with:
 - Append to `context.services[<service_name>].components`:
-  `{ name, path, role, props_accepted, used_in: [list of page paths] }`
+  For each new component created:
+  `{ name, path, role, props, used_by: [page_names], created_by: "modularize" }`
 - Set `last_command` = "modularize"
-- Append to `change_log`: `{ timestamp, command: "modularize", action: "Created [n] component(s) from [n] pages" }`
+- Append to top-level `change_log`:
+  `{ timestamp, command: "modularize", action: "Created [n] components, updated [n] pages", affected_files: [...] }`
+- After write-context → call MCP tool `context_clear_scratchpad` with keys: ["current_action"]
 
-**Step 2.** Call `context_clear_scratchpad` with keys: ["current_action"]
+Display the modularization report:
 
-**Step 3.** Show completion report:
 ```
-/codeninja:modularize Complete
+@modularize Complete
 ─────────────────────────────────────────
 Components created : [n]
 Components reused  : [n]
 Pages updated      : [n]
+Blocks skipped     : [n]
 ─────────────────────────────────────────
-[list created files]
-[list modified files]
+Created:
+  ✓ src/components/Header/index.jsx
+  ✓ src/components/Header/Header.module.css
+  ✓ src/components/Footer/index.jsx
+  ✓ src/components/Footer/Footer.module.css
+
+Updated:
+  ✓ src/pages/Login/index.jsx
+  ✓ src/pages/Dashboard/index.jsx
+  ✓ src/pages/Profile/index.jsx
 ─────────────────────────────────────────
-Next: /codeninja:validate-page to add validation
-      /codeninja:integrate-api to wire forms to backend
 ```
+
+Run task: `show-final-summary`
+
+---
+
+## What This Workflow Does NOT Do
+
+- Does not create page-level components (forms, tables, charts) —
+  only layout/structural shell components
+- Does not add routing — components are not registered in App.jsx
+- Does not touch any backend files
+- Does not modify apiHandler.js or apiClient.js
+- Does not add state management (Redux, Context API)
+- Does not install any new npm packages

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

@@ -1,17 +1,30 @@
+This workflow runs when user invokes /codeninja:optimize
+
 ---
-slash_command: /codeninja:optimize
-personas: [global-orchestrator, nodejs-backend, database-architect]
-skills: [mcp-and-context, api-builder, database, code-intelligence]
-description: Analyse and improve performance using real project context.
+type: workflow
+name: optimize
+description: >
+  Analyse and improve performance of a route, query, or service using real
+  project context — actual table sizes, existing indexes, query patterns, and
+  middleware overhead. Produces ranked recommendations with concrete code.
 ---
 
-# /codeninja:optimize
+# Workflow: @optimize / /codeninja:optimize
 
-## Before Running
-1. Call `context_read` — load `context.db.schema`, `context.services`
-2. Call `context_check_stale`
+## Goal
+Find real performance bottlenecks using actual project data. Every
+recommendation includes a concrete fix and an estimated impact.
+No generic advice — only changes grounded in this codebase.
+
+## Rules
+- Check context.db.schema for existing indexes before recommending new ones
+- Reference real table names and column names from context
+- Estimate impact where possible (e.g., "seq scan → index scan on 2M rows")
+- Rank by impact: HIGH → MED → LOW
+
+---
 
-## Execution — Full Step-by-Step
+## Step-by-Step Execution
 
 ### Step 1 — Identify Target
 If not specified, ask:
@@ -22,8 +35,9 @@ If not specified, ask:
 (d) Something else — describe it"
 
 ### Step 2 — Load Context
-1. Call `fs_read` on the relevant files (route.js, _model.js)
-2. For DB queries: list existing indexes from `context.db.schema.<table>.indexes`
+1. Call `context_read` — load `context.db.schema`, `context.services`
+2. Call `fs_read` on the relevant files (route.js, _model.js)
+3. For DB queries: list existing indexes from `context.db.schema.<table>.indexes`
 
 ### Step 3A — Database Query Analysis
 
@@ -31,54 +45,82 @@ For each query in the target:
 
 **Check 1 — Missing Indexes**
 Compare WHERE / JOIN / ORDER BY columns against existing indexes.
-Generate `CREATE INDEX CONCURRENTLY` for missing ones.
+```
+Table: tbl_scores
+Query: WHERE week_id = $1 ORDER BY score DESC
+Indexes on tbl_scores: [id, user_id]   ← week_id NOT indexed
+Fix: CREATE INDEX CONCURRENTLY idx_scores_week_id_score
+       ON tbl_scores(week_id, score DESC);
+Impact: HIGH — seq scan on every leaderboard call → index scan
+```
 
 **Check 2 — SELECT * Anti-Pattern**
-Replace with explicit column list. Show before/after.
+```
+Before: SELECT * FROM tbl_users WHERE user_id = $1
+After:  SELECT id, user_id, display_name, status FROM tbl_users WHERE user_id = $1
+Why: Eliminates unused column transfer; avoids fetching large text/jsonb columns
+```
 
 **Check 3 — N+1 Query Pattern**
-Flag any loop calling a DB function per iteration. Suggest single query with IN or JOIN.
+Flag any loop that calls a DB function per iteration.
+Suggest: single query with IN clause or JOIN.
 
 **Check 4 — Window Function Choice**
-- `RANK()` → gaps after ties (wrong for leaderboards)
-- `DENSE_RANK()` → no gaps (correct for leaderboards)
-- `ROW_NUMBER()` → unique position (correct for pagination)
+```
+RANK()        → gaps after ties (positions: 1, 2, 2, 4)  ← usually wrong for leaderboards
+DENSE_RANK()  → no gaps (positions: 1, 2, 2, 3)          ← correct for leaderboards
+ROW_NUMBER()  → unique position per row (1, 2, 3, 4)      ← correct for pagination
+```
 
 **Check 5 — Duplicate Row Prevention**
-Flag duplicate rows from missing dedup. Suggest `MIN(id) GROUP BY user_id`.
+```
+-- Symptom: same user appears multiple times in results
+-- Fix: dedup using MIN(id) GROUP BY user_id before joining
+SELECT MIN(id) as id, user_id FROM tbl_users GROUP BY user_id
+```
 
 **Check 6 — Functional Index Trap**
-Flag `DATE(created_at) = '...'` → suggest range form for index usage.
+```
+-- BAD: DATE(created_at) = '2026-04-13' prevents index use
+-- GOOD: created_at >= '2026-04-13' AND created_at < '2026-04-14'
+```
 
 **Check 7 — work_mem for Sort Operations**
-If EXPLAIN shows external merge disk sort → suggest `SET work_mem = '64MB'`.
+If EXPLAIN shows "Sort Method: external merge  Disk:", recommend:
+```sql
+SET work_mem = '64MB';  -- session-level, before the heavy query
+```
 
 ### Step 3B — API Route Analysis
 
-- Is heavy middleware on lightweight routes?
-- Synchronous blocking in request path?
+Check middleware chain for overhead:
+- Is heavy middleware applied to lightweight routes?
+- Any synchronous blocking in the request path?
 - Repeated DB lookups that could be cached in Redis?
-- Pagination missing on list endpoints?
+
+Check response size:
+- Is pagination applied to list endpoints?
+- Any large JSON blobs being serialized unnecessarily?
 
 ### Step 4 — Output Recommendations
 
 ```
 [HIGH | MED | LOW] — Impact label
 
-Target: what's being optimised
+Target: describe what's being optimised
 Root cause: why it's slow right now
 Fix:
   [exact SQL or code change]
 Estimated gain: concrete estimate
-Side effects: anything developer should know
+Side effects: anything the developer should know
 ```
 
-List all, highest impact first.
+List all recommendations, highest impact first.
 
 ### Step 5 — Offer to Apply
 "I've found [N] optimisations. Want me to apply them?
 I'll implement each one and show you the change before writing."
 
-For index changes → generate `NNN_add_index_<n>.sql` migration file.
-For code changes → edit the relevant model or route file surgically.
-Always call `context_write` after applying index additions.
+For index changes: generate `NNN_add_index_<name>.sql` migration file.
+For code changes: edit the relevant model or route file surgically.
+Always call `context_write` after applying index additions to update schema.