cortex CLAUDE.md

CLAUDE.md — Cortex Plugin Development Context

What Is This Project?

This is a Claude Code Plugin called cortex (Cortex) built by Alpha AI Service Pvt Ltd. It automates the entire software development lifecycle — from project scaffolding to autonomous product building — with zero human intervention.

The plugin enforces Alpha AI's engineering standards across 3 backend languages: Python/FastAPI, Node.js/NestJS, Java/Spring Boot — plus JWT+HTTP-Only Cookies (NEVER localStorage/sessionStorage), MySQL+ORM, MongoDB, Redis, and strict layer segregation.

---

Plugin Architecture

This is NOT a regular Python/Node project. It is a Claude Code Plugin — a collection of Markdown instruction files, bash scripts, and JSON configs that extend Claude Code's capabilities.

Directory Structure

cortex/
│
├── .claude-plugin/
│   ├── plugin.json              # Plugin metadata (name, version, author)
│   └── marketplace.json         # Marketplace catalog (for distribution via alphaaiservice/cortex)
│
├── commands/                     # SLASH COMMANDS — user invokes with /command-name (55 total)
│   │
│   │  # ── Planning & Research ──
│   ├── gen-prd.md               # /gen-prd — Generate PRD from brief idea
│   ├── gen-brand.md             # /gen-brand — SVG logo & brand identity generation
│   ├── market-research.md       # /market-research — Deep competitive analysis
│   ├── sprint-plan.md           # /sprint-plan — Break PRD into sprint tasks with estimates
│   │
│   │  # ── Design & Media (v1.5.0) ──
│   ├── gen-mockup.md            # /gen-mockup — UI screen mockups/wireframes as self-contained HTML/Next.js (brand-consistent, no API key)
│   ├── gen-pitch.md             # /gen-pitch — Pitch/demo deck from PRD+research as Marp/Slidev markdown → PDF/HTML/PPTX
│   ├── gen-demo-video.md        # /gen-demo-video — Product demo/marketing video as a Remotion project (script→TTS+captions→MP4)
│   │
│   │  # ── Project Setup ──
│   ├── init-project.md          # /init-project — Scaffold new OR upgrade existing FastAPI/NestJS/Spring Boot project
│   ├── init-mcp-server.md       # /init-mcp-server — Scaffold standalone MCP server (Python or TypeScript)
│   ├── init-claude-plugin.md    # /init-claude-plugin — Scaffold a Claude Code plugin (dogfoods Cortex's own patterns)
│   ├── analyze-project.md       # /analyze-project — Scan existing codebase, map architecture
│   ├── gap-analysis.md          # /gap-analysis — Compare existing app vs Alpha AI 36 standards
│   ├── seed-data.md             # /seed-data — Generate realistic seed/test data factories
│   │
│   │  # ── Building ──
│   ├── auto-build.md            # /auto-build — Fully autonomous product builder (CORE)
│   ├── resume-build.md          # /resume-build — Resume interrupted auto-build
│   ├── feature.md               # /feature — Guided feature development
│   ├── retrofit.md              # /retrofit — Add missing features to existing app
│   ├── migrate-stack.md         # /migrate-stack — Safely migrate tech stack components
│   ├── refactor.md              # /refactor — AI-powered code refactoring
│   ├── debug.md                 # /debug — AI-powered debugging and troubleshooting
│   │
│   │  # ── Quality & Testing ──
│   ├── code-review.md           # /code-review — Automated multi-agent code review
│   ├── gen-tests.md             # /gen-tests — Auto-generate unit/integration tests
│   ├── e2e-test.md              # /e2e-test — Generate Playwright/Detox end-to-end tests
│   ├── perf-test.md             # /perf-test — Performance/load testing with k6/Locust
│   ├── security-scan.md         # /security-scan — SAST, DAST, secret detection, OWASP Top 10
│   ├── accessibility.md         # /accessibility — WCAG 2.1 AA compliance audit
│   ├── tech-debt.md             # /tech-debt — Scan and prioritize technical debt
│   ├── health-check.md          # /health-check — Project health audit
│   │
│   │  # ── Shipping & Release ──
│   ├── ship.md                  # /ship — Lint → test → commit → push → create PR
│   ├── release.md               # /release — Semver bump, changelog, git tag, GitHub Release
│   ├── changelog.md             # /changelog — Auto-generate CHANGELOG.md from git history
│   ├── deploy.md                # /deploy — Deploy with pre-flight checks
│   ├── gen-ci.md                # /gen-ci — Generate CI/CD pipelines (GitHub Actions/GitLab/Bitbucket)
│   │
│   │  # ── Infrastructure & DevOps ──
│   ├── gen-infra.md             # /gen-infra — Generate IaC (Docker, K8s, Terraform, Helm)
│   ├── db-migrate.md            # /db-migrate — Database migration helper
│   ├── docker-clean.md          # /docker-clean — Clean unused Docker resources
│   ├── monitoring.md            # /monitoring — Prometheus + Grafana setup
│   ├── runbook.md               # /runbook — Generate operational runbooks and playbooks
│   ├── backup-dr.md             # /backup-dr — Automated backups, restore testing, DR runbooks
│   ├── env-sync.md              # /env-sync — Environment parity checks, config drift, secret rotation
│   ├── feature-flags.md         # /feature-flags — Feature flag system with MySQL + Redis + admin UI
│   ├── audit-setup.md           # /audit-setup — Security audit logging, compliance, suspicious activity alerts
│   │
│   │  # ── Documentation & People ──
│   ├── gen-docs.md              # /gen-docs — Generate README, Architecture, API, Deployment docs
│   ├── api-docs.md              # /api-docs — Generate API documentation
│   ├── onboard-dev.md           # /onboard-dev — Onboard new developer
│   │
│   │  # ── Analysis & Intelligence ──
│   ├── suggest-ai-features.md   # /suggest-ai-features — Scan codebase, recommend AI/ML enhancements
│   ├── trace-impact.md          # /trace-impact — Trace blast radius of a code change across full stack
│   ├── estimate-cost.md         # /estimate-cost — Estimate infra + API costs at 3 scales
│   ├── feature-map.md           # /feature-map — Build visual feature dependency map with Mermaid
│   ├── standup.md               # /standup — Comprehensive task status across agents/teammates, background jobs, auto-build, sprint+Jira (READ-ONLY snapshot)
│   ├── ai-upgrade.md            # /ai-upgrade — Implement AI capabilities on an existing feature
│   │
│   │  # ── Maintenance ──
│   ├── dep-update.md            # /dep-update — Auto-update dependencies safely
│   │
│   │  # ── Cortex Cloud (auth + telemetry) ──
│   ├── cortex-login.md          # /cortex-login — Authenticate plugin to Cortex Cloud (RFC 8628 device grant)
│   ├── cortex-logout.md         # /cortex-logout — Revoke + clear local Cortex Cloud credentials
│   └── cortex-status.md         # /cortex-status — Show Cortex Cloud connection + project status
│
├── agents/                       # SUBAGENTS — spawned via Agent tool for parallel work (13 total)
│   ├── architect.md             # Architecture analysis and design reviews
│   ├── brand-designer.md        # SVG logo generation, color systems, brand identity
│   ├── security-auditor.md      # Vulnerability scanning, secret detection
│   ├── onboarding-mentor.md     # Interactive codebase Q&A for new devs
│   ├── test-strategist.md       # Test coverage analysis and quality
│   ├── parallel-builder.md      # Orchestrates parallel Agent subagents for speed
│   ├── self-healer.md           # Auto-diagnoses and fixes errors during auto-build
│   ├── db-optimizer.md          # Slow query analysis, missing indexes, N+1 detection
│   ├── devops-engineer.md       # CI/CD, Docker, K8s, Terraform, deployment automation
│   ├── performance-profiler.md  # API profiling, N+1 detection, bottleneck analysis
│   ├── documentation-writer.md  # README, architecture docs, API reference, guides
│   ├── feature-analyzer.md      # Codebase analysis, feature discovery, dependency mapping
│   └── ai-integration-specialist.md # AI/ML integration, LLM setup, vector search, cost tracking
│
├── skills/                       # SKILLS — auto-invoked by Claude (Agent Skills open standard, 24 total)
│   ├── alpha-architecture/      # ⭐ MOST IMPORTANT — enforces tech stack + layer rules
│   │   ├── SKILL.md
│   │   └── references/
│   │       ├── CODE_PATTERNS_PYTHON.md     # Python/FastAPI code patterns
│   │       ├── CODE_PATTERNS_NESTJS.md     # NestJS/TypeScript code patterns
│   │       ├── CODE_PATTERNS_SPRINGBOOT.md # Java/Spring Boot code patterns
│   │       ├── CODE_PATTERNS_FRONTEND_PRODUCTION.md # ⭐ Frontend production bar: Fonts & Color (next/font + OKLCH tokens), Real data, Visual polish, Perf/A11y, Friendly errors (no HTTP codes/exceptions)
│   │       ├── CODE_PATTERNS_FRONTEND_CORE.md  # Frontend Part 1: Dir structure, App Router, Routes, Providers, Middleware, Page State
│   │       ├── CODE_PATTERNS_FRONTEND_PAGES.md # Frontend Part 2: Dashboard Layout, 6 Page Templates (List/Detail/Form/Settings/Dashboard/Auth)
│   │       ├── CODE_PATTERNS_FRONTEND_UX.md    # Frontend Part 3: Components, Responsive, Skeletons, SEO, Animations, Dark Mode, Cmd+K
│   │       ├── CODE_PATTERNS_CHROME_EXTENSION.md # Chrome Extension: MV3, Service Worker, Content Scripts, Messages, Storage, Security, AI Providers, Testing
│   │       ├── CODE_PATTERNS_GENAI.md      # GenAI/LLM: LiteLLM gateway, prompts, agents, structured output, guardrails, caching (used by the genai skill)
│   │       ├── RAG_BEST_PRACTICES.md       # RAG: chunking, embeddings, retrieval, re-ranking, agentic RAG, eval (used by the genai skill)
│   │       ├── LANG_PROFILE_PYTHON.md      # Python stack: deps, dirs, configs, Docker
│   │       ├── LANG_PROFILE_NESTJS.md      # NestJS stack: deps, dirs, configs, Docker
│   │       ├── LANG_PROFILE_SPRINGBOOT.md  # Spring Boot stack: deps, dirs, configs, Docker
│   │       └── INFRA_HOSTINGER_K3S.md      # Hostinger VPS + K3s: 4-node arch, Traefik, CI/CD, templates
│   ├── project-setup/
│   │   └── SKILL.md
│   ├── onboarding/
│   │   └── SKILL.md
│   ├── code-review/
│   │   └── SKILL.md
│   ├── testing/
│   │   └── SKILL.md
│   ├── deployment/
│   │   └── SKILL.md
│   ├── security/                # 🔒 Auto-enforces OWASP Top 10, auth, input validation, secrets
│   │   └── SKILL.md
│   ├── devops/                  # 🐳 Auto-enforces Docker, CI/CD, K8s, monitoring standards
│   │   └── SKILL.md
│   ├── performance/             # ⚡ Auto-enforces DB optimization, caching, async patterns
│   │   └── SKILL.md
│   ├── frontend/                # 🎨 Auto-enforces the frontend production bar (fonts, OKLCH tokens, real data, polish, friendly errors) — refs CODE_PATTERNS_FRONTEND_*
│   │   └── SKILL.md
│   ├── genai/                   # 🤖 Auto-enforces AI engineering (LiteLLM gateway, guardrails, cost caps, structured output, RAG, evals) — refs CODE_PATTERNS_GENAI + RAG_BEST_PRACTICES
│   │   └── SKILL.md
│   ├── accessibility/           # ♿ Auto-enforces WCAG 2.1 AA at authoring time (semantic HTML, ARIA, contrast, keyboard nav, focus)
│   │   └── SKILL.md
│   ├── database/                # 🗄️ Auto-enforces safe reversible zero-downtime migrations, datastore selection, repository boundary
│   │   └── SKILL.md
│   ├── mockup/                  # 🖼️ Auto-invoked on "mock up / wireframe a screen" — brand-consistent screens as code (paired with /gen-mockup)
│   │   └── SKILL.md
│   ├── pitch-deck/             # 📊 Auto-invoked on "pitch deck / slides / presentation" — Marp/Slidev → PDF/HTML/PPTX (paired with /gen-pitch)
│   │   └── SKILL.md
│   ├── video-producer/         # 🎬 Auto-invoked on "demo / marketing video" — Remotion project, TTS voiceover + captions (paired with /gen-demo-video)
│   │   └── SKILL.md
│   │   # (also: cost-estimator, dependency-mapper, feature-impact-analysis, metric-recommender, smart-retrofit — analysis & advisory;
│   │   #         cortex-brainstorming, cortex-planning, cortex-tdd, cortex-debugging, cortex-verification — meta-process)
│   └── jira-integration/        # 🟦 Auto-invoked on Jira work — bidirectional sync via Atlassian MCP (NO command)
│       └── SKILL.md
│
├── .mcp.json                     # MCP SERVERS Cortex CONSUMES — atlassian (Jira/Confluence) via official remote MCP
│
├── hooks/                        # HOOKS — event-driven automation
│   └── hooks.json               # Defines when hooks fire and what they do
│
├── scripts/                      # BASH SCRIPTS — executed by hooks or standalone
│   ├── auto-loop.sh             # Persistent Ralph Loop runner (shell-level)
│   ├── auto-build-stop-hook.sh  # Stop hook: prevents exit during auto-build
│   ├── session-context.sh       # SessionStart hook: loads project context + emits the SKILL PRECEDENCE directive (see below)
│   └── safe-bash-check.sh       # PreToolUse hook: warns on dangerous commands
│
├── README.md
├── LICENSE
└── CLAUDE.md                     # ← THIS FILE