codeninja 2.0.0 → 3.1.0

package/README.md

@@ -1,293 +1,164 @@
-# Code Ninja Agent System
+# codeninja
 
-AI-powered agentic scaffolding and development assistant for your project.
+AI agent scaffolding system for Node.js, React, and PostgreSQL projects.
+
+**v3.0** — IDE-aware installer. Automatically sets up the right agent structure
+for Antigravity, Cursor, or VS Code / GitHub Copilot.
 
 ---
 
-## Folder Structure
+## Install
 
+```bash
+npx codeninja init
 ```
-.codeninja/agent/
-  global-agent.md               ← Master orchestrator
-  nodejs-agent.md               ← NodeJS backend expert
-  reactjs-agent.md              ← ReactJS frontend expert
-  database-agent.md             ← Database architect (PostgreSQL / MySQL / MongoDB)
-  designs/                      ← @design output files (auto-created)
-
-.codeninja/commands/
-  initialize-project.workflow.md
-  create-api.workflow.md
-  design.workflow.md
-  audit.workflow.md
-  test.workflow.md
-  refactor.workflow.md
-  sync.workflow.md
-  modularize.workflow.md
-  validate-page.workflow.md
-  integrate-api.workflow.md
-  db-create-table.workflow.md
-  db-modify-table.workflow.md
-  db-add-index.workflow.md
-  db-drop-table.workflow.md
-  db-seed.workflow.md
-  db-sync.workflow.md
-
-.codeninja/tasks/
-  ── Project Info ──────────────────────────────
-  ask-project-info-doc.task.md
-  ask-project-scope-of-work.task.md
-  ask-project-figma.task.md
-
-  ── Repository & Init ─────────────────────────
-  detect-repository-state.task.md
-  ask-project-type.task.md
-  ask-service-name.task.md
-  ask-service-port.task.md
-  ask-service-description.task.md
-  ask-package-name.task.md
-  ask-package-author.task.md
-  ask-api-key.task.md
-  ask-encryption-key.task.md
-  ask-encryption-iv.task.md
-  ask-redis-host.task.md
-  ask-redis-port.task.md
-  ask-redis-config.task.md
-  show-init-summary.task.md
-  ask-client-type.task.md
-  ask-encrypted-transport.task.md
-  ask-supported-languages.task.md
-  ask-init-mode.task.md
-  generate-fast-defaults.task.md
-
-  ── Database Config ───────────────────────────
-  ask-database-type.task.md
-  ask-database-name.task.md
-  ask-database-host.task.md
-  ask-database-port.task.md
-  ask-database-user.task.md
-  ask-database-config.task.md
-
-  ── Database Table Operations ─────────────────
-  ask-table-purpose.task.md
-  ask-table-name.task.md
-  ask-table-file-number.task.md
-  ask-table-needs-status.task.md
-  ask-table-needs-soft-delete.task.md
-  ask-table-indexes.task.md
-  ask-table-seed-data.task.md
-  show-db-table-summary.task.md
-
-  ── Column Operations ─────────────────────────
-  ask-column-name.task.md
-  ask-column-type.task.md
-  ask-column-is-enum.task.md
-  ask-column-enum-values.task.md
-  ask-column-position.task.md
-  ask-old-column-name.task.md
-  ask-new-column-name.task.md
-  ask-modify-operation.task.md
-
-  ── Index Operations ──────────────────────────
-  ask-index-columns.task.md
-  ask-index-sort-order.task.md
-  ask-index-type.task.md
-  ask-index-file-placement.task.md
-
-  ── Seed Data ─────────────────────────────────
-  ask-seed-rows-count.task.md
-  ask-seed-row-values.task.md
-
-  ── API & Module Operations ───────────────────
-  ask-target-service.task.md
-  ask-react-target-service.task.md
-  ask-module-name.task.md
-  ask-http-method.task.md
-  ask-route-path.task.md
-  ask-route-description.task.md
-  ask-primary-table.task.md
-  ask-requires-auth.task.md
-  ask-api-version.task.md
-
-  ── ReactJS Page Operations ───────────────────
-  ask-page-path.task.md
-  ask-modularize-scope.task.md
-  ask-validation-library.task.md
-  ask-api-integration-scope.task.md
-
-  ── Design & Refactor ─────────────────────────
-  ask-design-target.task.md
-  ask-feature-name.task.md
-  ask-design-description.task.md
-  ask-refactor-type.task.md
-  ask-table-name.task.md
-  ask-new-table-name.task.md
-
-  ── Test ──────────────────────────────────────
-  ask-test-type.task.md
-
-  ── Output & Context ──────────────────────────
-  write-context.task.md
-  show-final-summary.task.md
-
-  ── Utilities Generation ──────────────────────────────
-  generate-encryption.task.md
-  generate-response.task.md
-  generate-validator.task.md
-  generate-headerValidator.task.md
-  generate-logging.task.md
-  generate-app.task.md
-  generate-rateLimiter.task.md
-  generate-route-manager.task.md
-  generate-constants.task.md
-  generate-database.task.md
-  generate-template.task.md
-  generate-language-en.task.md
-  generate-ioRedis.task.md
-  generate-notification.task.md
-  generate-common.task.md
-  generate-route.task.md
-  generate-model.task.md
-  generate-enc-dec-html.task.md
-  generate-enc-dec-php.task.md
-  generate-package-json.task.md
-  generate-readme.task.md
-  generate-gitignore.task.md
-  generate-swagger.task.md
-
-── System Tables ─────────────────────────
-  generate-tbl-user-deviceinfo.task.md
-
-.codeninja/context/
-  context.json                  ← Shared memory for all agents (auto-managed)
+
+Auto-detects your IDE. Force a specific one with `--ide`:
+
+```bash
+npx codeninja init --ide=antigravity   # Google Antigravity IDE
+npx codeninja init --ide=cursor        # Cursor
+npx codeninja init --ide=vscode        # VS Code + GitHub Copilot
+npx codeninja init --ide=all           # All three
 ```
 
 ---
 
-## Available Commands
+## What gets installed
 
-### Project Initialization
-| Command | Description |
-|---|---|
-| `@initialize-project` | Bootstrap a new NodeJS service, ReactJS app, or database |
+### Core (all IDEs)
 
-### API & Service Development
-| Command | Description |
-|---|---|
-| `@create-api` | Add a new API module to an existing service |
-| `@design` | Plan a feature or schema before writing code |
-| `@audit` | Review a service for security, quality, and consistency |
-| `@test` | Generate or run tests for a module |
-| `@refactor` | Rename or restructure code with full change tracking |
-| `@sync` | Scan the entire repo and rebuild context.json |
-
-### Database Commands
-| Command | Description |
-|---|---|
-| `@db:create-table` | Design and generate a new table following all conventions |
-| `@db:modify-table` | Add/rename/drop a column via ALTER migration file |
-| `@db:add-index` | Add a new index to an existing table |
-| `@db:drop-table` | Generate a DROP migration and clean up context |
-| `@db:seed` | Add or update seed data for a table |
-| `@db:sync` | Scan migration files and rebuild context.db.schema |
+```
+.codeninja/
+├── agent/          ← Agent personas (global, nodejs, reactjs, database)
+├── commands/       ← Workflow files (one per slash command)
+├── tasks/          ← Atomic task files referenced by workflows
+├── context/        ← context.json (project memory, gitignored)
+└── mcp-server.js   ← MCP server (context_read, context_write, tools)
+```
 
----
+### Antigravity IDE
+
+```
+.agents/
+├── rules/
+│   └── codeninja-persona.md     ← Senior architect persona (auto-loaded)
+├── skills/
+│   └── codeninja/
+│       └── SKILL.md             ← Technical standards (auto-loaded)
+└── workflows/
+    └── codeninja-*.md           ← One file per /codeninja:* slash command
+```
 
-## How It Works
+### Cursor
 
-1. **You run a command** — e.g. `@initialize-project`
-2. **Global agent activates** — reads `.codeninja/context/context.json` for full awareness
-3. **Project info is collected first (once)** — document, SOW, Figma link → builds project summary
-4. **Workflow runs** — routes to the right agent (NodeJS, ReactJS, Database)
-5. **Tasks execute one at a time** — each asks exactly one question
-6. **Single confirmation** — you approve the summary once, then all files are generated
-7. **Context is updated** — every action recorded in `context.json`
+```
+.cursor/
+├── rules/
+│   └── codeninja.mdc            ← Project rules (auto-loaded for all files)
+└── mcp.json                     ← MCP server config
+```
+
+### VS Code / GitHub Copilot
+
+```
+.github/
+└── copilot-instructions.md      ← Copilot context (auto-loaded in Agent Mode)
+.vscode/
+└── mcp.json                     ← MCP server config (uses workspaceFolder)
+```
 
 ---
 
-## Key Design Principles
+## Available commands
 
-### One Question Per Task
-Every `ask-*` task collects exactly one value. No multi-field forms.
+### Project and service
 
-### Single Confirmation Per Operation
-After collecting all required values, a summary is shown once.
-You confirm once → everything generates. No per-file prompts.
+| Command | Description |
+|---|---|
+| `/codeninja:init` | Bootstrap a new Node.js service, React app, or database |
+| `/codeninja:api` | Add a new API endpoint (full 5-step SOP) |
+| `/codeninja:design` | Plan a feature before coding |
+| `/codeninja:audit` | Security and quality review |
+| `/codeninja:test` | Generate Jest + Supertest tests |
+| `/codeninja:refactor` | Rename with full context tracking |
+| `/codeninja:sync` | Scan repo and rebuild context |
 
-### Context is the Brain
-`.codeninja/context/context.json` is the shared memory for all agents.
-- Every service, route, table, column, and change is stored here
-- All agents read it before making any decision
-- The `change_log` gives a full history of every structural change
+### Code intelligence (new in v3)
 
-### Database First
-During `@initialize-project`, the database folder is always scaffolded
-before any application service code. This ensures NodeJS services are
-generated with accurate DB config and column awareness.
+| Command | Description |
+|---|---|
+| `/codeninja:explain` | Explain any file, function, or pattern with full context |
+| `/codeninja:review` | Code review — severity-ranked findings with exact fixes |
+| `/codeninja:debug` | Diagnose a bug by tracing the actual code path |
+| `/codeninja:optimize` | Find performance bottlenecks with concrete fixes and impact |
 
-### Project Info Awareness
-When you provide a project document, SOW, or Figma link during initialization,
-the agent extracts entities, features, and tech preferences. Every subsequent
-command uses this context to make smarter suggestions.
+### Database
 
----
+| Command | Description |
+|---|---|
+| `/codeninja:db:create` | Design and generate a new table with migration |
+| `/codeninja:db:modify` | Add, rename, or drop a column |
+| `/codeninja:db:index` | Add a new index |
+| `/codeninja:db:drop` | Drop a table with migration file |
+| `/codeninja:db:seed` | Add seed data |
+| `/codeninja:db:sync` | Rebuild DB schema in context |
 
-## Database File Convention
+### React
 
-Every table follows this structure:
-```
-database/
-  <db_type>/
-    migrations/
-      1-setup-tbl-<name>.sql    ← One file per table, numbered
-      2-setup-tbl-<name>.sql
-      ...
-      111-setup-database-indexes.sql  ← Shared indexes, always last
-    seeds/
-      <table>_seed.sql          ← Standalone seed files
-    create-schema.sql           ← Auto-generated runner (do not edit)
-    setup-database.sh           ← Linux/Mac setup script
-    setup-database.ps1          ← Windows setup script
-    reset-database.sh           ← Dev-only full reset (dangerous)
-  README.md
-```
+| Command | Description |
+|---|---|
+| `@modularize` | Extract layout blocks into reusable components |
+| `@validate-page` | Add client-side form validation |
+| `@integrate-api` | Wire forms to API handler functions |
 
-### Running the Database
-```bash
-# Linux/Mac — creates DB and runs all migrations
-cd database/<db_type>
-bash setup-database.sh
+---
 
-# Windows
-cd database/<db_type>
-.\setup-database.ps1
-```
+## Architecture: 5-Step SOP
+
+Every new API endpoint follows this order, enforced by the agent:
+
+1. **ROUTING** — register in `route_manager.js` (append only, never rewrite)
+2. **VALIDATION** — validatorjs schema in `route.js`
+3. **CONTROLLER** — model call + error boundary in `route.js`
+4. **MODEL** — parameterized SQL in `_model.js` via shared pg pool
+5. **LOCALIZE** — all strings in `languages/en.js`, never hardcoded
 
 ---
 
-## Multi-Service Projects
+## Claude Desktop (manual setup)
+
+Add to your Claude Desktop config:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+- Linux: `~/.config/claude/claude_desktop_config.json`
 
-Each service gets its own entry in `context.services`:
 ```json
 {
-  "services": {
-    "auth":    { "type": "nodejs",  "port": 1001 },
-    "ledger":  { "type": "nodejs",  "port": 1002 },
-    "frontend":{ "type": "reactjs", "port": 3000 }
+  "mcpServers": {
+    "codeninja": {
+      "command": "node",
+      "args": ["/absolute/path/to/your/project/.codeninja/mcp-server.js"]
+    }
   }
 }
 ```
 
-All services share the same `context.db` — they reference the same database
-schema and the same table/column names.
+---
+
+## Requirements
+
+- Node.js 18+
+- npm
 
 ---
 
-## Getting Started
+## What is new in v3.0
 
-1. Run `@initialize-project`
-2. Answer Phase 0 questions (project doc, SOW, Figma) — once per repo
-3. Choose project type (NodeJS, ReactJS, Database)
-4. Configure database
-5. Name your service and configure it
-6. Confirm once → everything is generated
-7. Run `@db:create-table` to start adding your first table
+- **IDE-aware installer** — detects Antigravity, Cursor, or VS Code automatically
+- **Antigravity slash commands** — full `.agents/` structure with `/codeninja:*` commands
+- **Cursor rules** — `.cursor/rules/codeninja.mdc` auto-loaded for every file
+- **VS Code Copilot** — `.github/copilot-instructions.md` for Agent Mode
+- **4 new commands** — `explain`, `review`, `debug`, `optimize`
+- **`--ide` flag** — force any IDE or install for all three with `--ide=all`

package/agent/global-agent.md

@@ -92,6 +92,10 @@ When activated, always run these steps in order:
 | `@test` | Generate or run tests for a module |
 | `@refactor` | Rename or restructure code with full change tracking |
 | `@sync` | Scan the entire repo and rebuild context.json |
+| `@explain` | Explain any file, function, or pattern with full context |
+| `@review` | Code review with severity-ranked findings and fixes |
+| `@debug` | Diagnose and fix a bug using the real code path |
+| `@optimize` | Find and fix performance bottlenecks with impact estimates |
 
 ### ReactJS Commands
 | Command | Description |
@@ -145,6 +149,10 @@ repository root. Always use these exact paths — never guess or infer.
 | `@db:drop-table` | `.codeninja/commands/db-drop-table.workflow.md` |
 | `@db:seed` | `.codeninja/commands/db-seed.workflow.md` |
 | `@db:sync` | `.codeninja/commands/db-sync.workflow.md` |
+| `@explain` | `.codeninja/commands/explain.workflow.md` |
+| `@review` | `.codeninja/commands/review.workflow.md` |
+| `@debug` | `.codeninja/commands/debug.workflow.md` |
+| `@optimize` | `.codeninja/commands/optimize.workflow.md` |
 
 ## Routing Rules