{
  "markdown": "# Cortex — SDLC Automation Engine\n\n**Forge Production-Ready Software — From Idea to Deployment**\n\nBuilt by [Alpha AI Service Pvt Ltd](https://www.alphaaiservice.com)\n\n```\nPlugin         : Cortex v1.3.1\nCommands       : 54 slash commands\nAgents         : 13 specialized subagents\nSkills         : 27 auto-invoked skills (13 domain + 5 analysis + 5 meta-process + 3 design/media + 1 integration)\nHooks          : 7 event-driven automations\nReference Docs : 16 progressive-disclosure references\nValidator      : scripts/validate-plugin.sh (CI on every push)\nLicense        : MIT\n```\n\n---\n\n## Table of Contents\n\n- [What Is This?](#what-is-this)\n- [Setup Guide](#setup-guide)\n  - [Prerequisites](#prerequisites)\n  - [Step 1: Clone the Plugin](#step-1-clone-the-plugin)\n  - [Step 2: Choose a Loading Method](#step-2-choose-a-loading-method)\n  - [Step 3: Configure Permissions](#step-3-configure-permissions)\n  - [Step 4: Enable Agent Teams (Optional)](#step-4-enable-agent-teams-optional)\n  - [Step 5: Verify Installation](#step-5-verify-installation)\n- [Quick Start](#quick-start)\n- [All 54 Commands](#all-54-commands)\n- [Subagents](#subagents)\n- [Auto-Invoked Skills](#auto-invoked-skills)\n- [Hooks](#hooks)\n- [Enforced Tech Stack](#enforced-tech-stack)\n- [Architecture](#architecture)\n- [Usage Examples](#usage-examples)\n- [Agent Teams](#agent-teams)\n- [Configuration](#configuration)\n- [Troubleshooting](#troubleshooting)\n- [Uninstall](#uninstall)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## What Is This?\n\nCortex is a **Claude Code plugin** that automates every phase of the software development lifecycle:\n\n```\nIdea -> PRD -> Sprint Plan -> Scaffold -> Build -> Test -> Review -> Ship -> Deploy -> Monitor -> Maintain\n |       |         |            |          |       |        |        |       |         |          |\n v       v         v            v          v       v        v        v       v         v          v\n/gen-prd /sprint-plan /init-project /auto-build /gen-tests /code-review /ship /deploy /monitoring /dep-update\n```\n\nIt enforces **Alpha AI's engineering standards** across every project, supporting **3 backend languages**:\n\n- **Backend**: Python/FastAPI | Node.js/NestJS | Java/Spring Boot (auto-detected or `--lang` flag)\n- **Auth**: JWT in HTTP-Only Cookies (NEVER localStorage) — same rules, all languages\n- **Databases**: MySQL + ORM (SQLAlchemy | Prisma | Spring Data JPA), MongoDB, Redis\n- **Payments**: Razorpay (India SaaS with GST, credit points, subscriptions)\n- **Frontend**: Next.js 15+ TypeScript + Tailwind\n- **Mobile**: React Native + Expo SDK 55+ (New Architecture)\n- **GenAI**: LiteLLM | Vercel AI SDK | Spring AI + Qdrant RAG\n- **Open Standards**: MCP Protocol, A2A Protocol, Agent Skills\n\nThe plugin includes a **fully autonomous build system** (Ralph Loop) that can take a PRD and build the entire product — backend, frontend, auth, payments, tests, docs, CI/CD — with zero human intervention.\n\n---\n\n## Setup Guide\n\nComplete step-by-step guide to set up the Cortex plugin on your machine.\n\n### Prerequisites\n\nBefore you begin, make sure you have:\n\n| Requirement | Version | Check Command |\n|-------------|---------|---------------|\n| **Claude Code CLI** | v2.0+ | `claude --version` |\n| **Node.js** | 18+ | `node --version` |\n| **Git** | any | `git --version` |\n| **OS** | macOS, Linux, or WSL2 | — |\n\n```bash\n# Verify Claude Code is installed and authenticated\nclaude --version\n# Should show: 2.x.x (Claude Code)\n\n# If not installed, install it first:\nnpm install -g @anthropic-ai/claude-code\nclaude login\n```\n\n### Step 1: Clone the Plugin\n\n```bash\n# Clone the repository\ngit clone https://github.com/alphaaiservice/cortex.git\n\n# Or clone to a specific location\ngit clone https://github.com/alphaaiservice/cortex.git ~/claude-plugins/cortex\n\n# Enter the directory\ncd cortex\n\n# Make all hook scripts executable (REQUIRED)\nchmod +x scripts/*.sh\n```\n\n### Step 2: Choose a Loading Method\n\nYou have **3 options** to load the plugin. Pick the one that fits your workflow.\n\n#### Option A: Persistent Settings (Recommended)\n\nAdd the plugin directory to your global Claude Code settings so it loads **automatically in every session**.\n\nEdit `~/.claude/settings.json` and add the `plugins.directories` entry:\n\n```json\n{\n  \"plugins\": {\n    \"directories\": [\n      \"/absolute/path/to/cortex\"\n    ]\n  }\n}\n```\n\n**Example for macOS:**\n\n```json\n{\n  \"plugins\": {\n    \"directories\": [\n      \"/Users/yourname/claude-plugins/cortex\"\n    ]\n  }\n}\n```\n\nAfter saving, **every new Claude Code session** automatically loads all 54 commands, 13 agents, 27 skills, and 7 hooks.\n\n> **Important:** Use the **absolute path** (not `~` or relative paths).\n\n#### Option B: CLI Flag (Per-Session)\n\nLoad the plugin for a single session using the `--plugin-dir` flag:\n\n```bash\nclaude --plugin-dir /path/to/cortex\n```\n\n**Tip:** Create a shell alias so you don't have to type the full path every time:\n\n```bash\n# Add to ~/.zshrc or ~/.bashrc\nalias cortex='claude --plugin-dir /path/to/cortex'\n\n# Reload your shell\nsource ~/.zshrc\n\n# Now just run:\ncortex\n```\n\n#### Option C: Local Marketplace Install\n\nInstall via the built-in marketplace system for a permanent installation without editing settings files.\n\n```bash\n# Inside a Claude Code session:\n/plugin marketplace add alphaaiservice/cortex\n/plugin install cortex@alphaai\n```\n\nAfter installation, the plugin loads automatically in every session.\n\n### Step 3: Configure Permissions\n\nThe plugin needs permissions to read/write files and run bash commands. Add these to your `~/.claude/settings.json`:\n\n```json\n{\n  \"permissions\": {\n    \"allow\": [\n      \"Bash\",\n      \"Read\",\n      \"Edit\",\n      \"Write\",\n      \"Glob\",\n      \"Grep\",\n      \"WebFetch\",\n      \"Agent\",\n      \"MCP\"\n    ]\n  }\n}\n```\n\n> **What each permission does:**\n> - `Bash` — Run shell commands (builds, tests, git, linters)\n> - `Read` / `Edit` / `Write` — Read and modify project files\n> - `Glob` / `Grep` — Search files by name and content\n> - `WebFetch` — Fetch web content (for `/market-research`, `/gen-prd`)\n> - `Agent` — Spawn subagents for parallel work\n> - `MCP` — Use MCP server tools\n\nIf you skip this step, Claude Code will ask for permission on each tool call during the session.\n\n### Step 4: Enable Agent Teams (Optional)\n\nAgent Teams enables **true multi-agent parallelism** — multiple Claude Code instances working as teammates with shared task lists and inter-agent messaging. This is used by `/auto-build`, `/code-review`, and `/debug` for faster execution.\n\nAdd to your `~/.claude/settings.json`:\n\n```json\n{\n  \"env\": {\n    \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\"\n  }\n}\n```\n\n#### Full Recommended settings.json\n\nHere's the complete recommended `~/.claude/settings.json` with all options:\n\n```json\n{\n  \"env\": {\n    \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\"\n  },\n  \"permissions\": {\n    \"allow\": [\n      \"Bash\",\n      \"Read\",\n      \"Edit\",\n      \"Write\",\n      \"Glob\",\n      \"Grep\",\n      \"WebFetch\",\n      \"Agent\",\n      \"MCP\"\n    ]\n  },\n  \"plugins\": {\n    \"directories\": [\n      \"/absolute/path/to/cortex\"\n    ]\n  }\n}\n```\n\n> **Note:** If your `~/.claude/settings.json` already has other settings (like `enabledPlugins`), merge the keys above into your existing file. Don't overwrite the whole file.\n\n### Step 5: Verify Installation\n\nStart a new Claude Code session and verify everything loaded correctly:\n\n```bash\n# Start Claude Code (fresh session required after settings changes)\nclaude\n\n# You should see the Cortex banner on startup:\n#\n# +----------------------------------------------------------+\n# |                                                          |\n# |     ____           _                                     |\n# |    / ___|___  _ __| |_ _____  __                         |\n# |   | |   / _ \\| '__| __/ _ \\ \\/ /                         |\n# |   | |__| (_) | |  | ||  __/>  <                          |\n# |    \\____\\___/|_|   \\__\\___/_/\\_\\                         |\n# |                                                          |\n# |  Cortex v1.3.1 -- SDLC Automation Engine                 |\n# |  Forge Production-Ready Software                         |\n# |  Alpha AI Service Pvt Ltd                                |\n# |                                                          |\n# |  54 commands | 13 agents | 27 skills | 7 hooks           |\n# +----------------------------------------------------------+\n#\n# (Banner version + counts read dynamically from plugin.json\n#  at invocation time, so they never go stale.)\n```\n\n**Verification checklist:**\n\n```bash\n# 1. Check all commands are available\n/help\n# Should list all 54 slash commands\n\n# 2. Run a quick health check\n/health-check\n\n# 3. Test a simple command\n/gen-prd \"simple todo app\"\n# Should generate a PRD document\n\n# 4. Verify hooks are active\n/hooks\n# Should show 7 hooks (PreToolUse, SessionStart, PostToolUse for Write+Edit,\n# Stop, PreCompact, TeammateIdle, TaskCompleted)\n\n# 5. Run the plugin validator (catches drift between manifest and reality)\nbash scripts/validate-plugin.sh\n# Should report: Passed: 23, Warnings: 0, Failed: 0\n```\n\n### Team-Wide Setup\n\nTo share the plugin across your entire team:\n\n**Option A: Repository-level** — Add to your project's `.claude/settings.json`:\n\n```json\n{\n  \"plugins\": {\n    \"directories\": [\n      \"/shared/path/to/cortex\"\n    ]\n  }\n}\n```\n\n**Option B: Per-developer** — Each team member adds to their `~/.claude/settings.json`:\n\n```json\n{\n  \"plugins\": {\n    \"directories\": [\n      \"/Users/dev-name/claude-plugins/cortex\"\n    ]\n  }\n}\n```\n\n**Option C: GitHub Marketplace** (when published):\n\n```bash\n/plugin marketplace add alphaaiservice/cortex\n/plugin install cortex@alphaai\n```\n\n---\n\n## Quick Start\n\n### Build a Complete Product (Autonomous Mode)\n\n```bash\n# Step 1: Generate a PRD from an idea\n/gen-prd \"Build a multi-tenant SaaS project management tool with Kanban boards\"\n\n# Step 2: Launch fully autonomous build (zero human intervention)\n/auto-build ./PRD.md\n\n# The system will:\n# 1. Scaffold the project\n# 2. Create database models and migrations\n# 3. Build API endpoints\n# 4. Create frontend pages\n# 5. Add auth, payments, GenAI features\n# 6. Generate tests (>80% coverage)\n# 7. Write documentation\n# 8. Set up CI/CD and Docker\n# All automatically, with self-healing error recovery.\n```\n\n### Work on an Existing Project\n\n```bash\n# Step 1: Analyze your codebase\n/analyze-project\n\n# Step 2: Check compliance with Alpha AI standards\n/gap-analysis\n\n# Step 3: Add missing features one by one\n/retrofit jwt-cookies\n/retrofit razorpay\n/retrofit dark-mode\n\n# Or migrate your tech stack\n/migrate-stack PostgreSQL to MySQL\n```\n\n### Day-to-Day Development\n\n```bash\n# Plan sprints from a PRD\n/sprint-plan ./PRD.md --sprints=4 --team-size=3\n\n# Build a feature\n/feature Add user profile with avatar upload\n\n# Generate tests\n/gen-tests app/services/user_service.py\n\n# Debug an issue\n/debug \"TypeError: 'NoneType' object is not subscriptable in auth middleware\"\n\n# Code review\n/code-review --staged\n\n# Ship it\n/ship \"feat(profile): add avatar upload with S3 presigned URLs\"\n\n# Deploy\n/deploy staging\n```\n\n---\n\n## All 54 Commands\n\n### Planning and Research (4)\n\n| Command | Description |\n|---------|-------------|\n| `/gen-prd <idea>` | Generate a detailed PRD from a brief idea with web research |\n| `/gen-brand <name\\|prd-file>` | Generate SVG logos, color system, typography, and brand identity |\n| `/market-research <topic>` | Deep competitive analysis, market trends, pricing intelligence |\n| `/sprint-plan <prd-file>` | Break PRD into sprint-sized tasks with estimates and dependencies |\n\n### Design and Media (3) — *added v1.5.0*\n\n| Command | Description |\n|---------|-------------|\n| `/gen-mockup <idea\\|prd> [--fidelity] [--mobile]` | Clickable UI screen mockups/wireframes as self-contained HTML/Next.js — brand-consistent, no API key |\n| `/gen-pitch <prd> [--mode=investor\\|hackathon]` | Pitch/demo deck from PRD + research as Marp/Slidev markdown → PDF/HTML/PPTX |\n| `/gen-demo-video <prd> [--length] [--aspect]` | Product demo/marketing video as a Remotion project: script → TTS voiceover + captions → MP4 |\n\n### Project Setup (6)\n\n| Command | Description |\n|---------|-------------|\n| `/init-project <name> [--lang=python\\|nestjs\\|springboot] [--existing]` | Scaffold new or upgrade existing FastAPI/NestJS/Spring Boot project |\n| `/init-mcp-server <name> [--lang=python\\|typescript] [--with-tools]` | **NEW in v1.3.0** — Scaffold standalone MCP server (Python `mcp` SDK or TypeScript `@modelcontextprotocol/sdk`) |\n| `/init-claude-plugin <name> [--with-commands\\|agents\\|skills\\|hooks\\|mcp]` | **NEW in v1.3.0** — Scaffold a Claude Code plugin using Cortex's own structure as the template (dogfoods every plugin best practice) |\n| `/analyze-project [path]` | Scan existing codebase, detect tech stack, map architecture |\n| `/gap-analysis [path]` | Compare app against Alpha AI's 36 engineering standards |\n| `/seed-data [--count=100]` | Generate realistic seed data factories and database seeders |\n\n### Building (7)\n\n| Command | Description |\n|---------|-------------|\n| `/auto-build <prd-file>` | Fully autonomous product builder (12-phase, self-healing) |\n| `/resume-build` | Resume interrupted auto-build from last checkpoint |\n| `/feature <description>` | Guided feature development from spec to PR |\n| `/retrofit <feature-name>` | Add missing Alpha AI features to existing app (50+ features) |\n| `/migrate-stack <from> to <to>` | Safely migrate technology components (DB, auth, payments) |\n| `/refactor <file-or-module>` | AI-powered code refactoring (extract, decompose, rename, cleanup) |\n| `/debug <error-or-log>` | AI-powered debugging with root cause analysis and auto-fix |\n\n### Quality and Testing (8)\n\n| Command | Description |\n|---------|-------------|\n| `/code-review [--staged]` | Automated multi-agent code review (5 parallel analyzers) |\n| `/gen-tests <file>` | Auto-generate unit and integration tests |\n| `/e2e-test [flow-name\\|--all]` | Generate Playwright (web) and Detox (mobile) E2E tests |\n| `/perf-test [endpoint\\|all]` | Performance/load testing with k6 and Locust |\n| `/security-scan [--fix]` | SAST + DAST + secret detection + OWASP Top 10 audit |\n| `/accessibility [--fix]` | WCAG 2.1 AA compliance audit with auto-fix |\n| `/tech-debt [--fix-quick-wins]` | Scan and prioritize technical debt with scoring |\n| `/health-check` | Full project health audit with overall score |\n\n### Shipping and Release (5)\n\n| Command | Description |\n|---------|-------------|\n| `/ship <commit-message>` | Lint -> test -> commit -> push -> create PR |\n| `/release [major\\|minor\\|patch]` | Semver bump, changelog, git tag, GitHub Release |\n| `/changelog [--since=v1.0.0]` | Auto-generate CHANGELOG.md from git history |\n| `/deploy <environment>` | Deploy with pre-flight checks and safety validations |\n| `/gen-ci [github-actions\\|gitlab-ci]` | Generate CI/CD pipelines with caching, matrix testing, security |\n\n### Infrastructure and DevOps (9)\n\n| Command | Description |\n|---------|-------------|\n| `/gen-infra [docker\\|k8s\\|k3s\\|terraform\\|helm]` | Generate IaC: Docker Compose, Kubernetes, K3s (Hostinger VPS), Terraform, Helm |\n| `/db-migrate <action>` | Database migration management (generate, run, rollback) |\n| `/docker-clean` | Clean unused Docker containers, images, volumes, networks |\n| `/monitoring` | Set up Prometheus + Grafana monitoring stack |\n| `/runbook [--type=incident\\|all]` | Generate operational runbooks and incident playbooks |\n| `/backup-dr` | Automated backups, restore verification, DR runbooks (MySQL/MongoDB/Redis/S3) |\n| `/env-sync` | Environment parity checks, config drift detection, secret rotation |\n| `/feature-flags` | Feature flag system: MySQL + Redis cache + admin UI |\n| `/audit-setup` | Security audit logging, compliance trails, suspicious-activity alerts |\n\n### Documentation and People (3)\n\n| Command | Description |\n|---------|-------------|\n| `/gen-docs [--type=all]` | Generate README, Architecture, API Reference, Deployment Guide |\n| `/api-docs` | Auto-generate OpenAPI specs and endpoint documentation |\n| `/onboard-dev <name> (<role>)` | Generate personalized onboarding plan and starter tasks |\n\n### Analysis and Intelligence (5)\n\nAdded in v1.1.0 — codebase analysis and AI capability discovery.\n\n| Command | Description |\n|---------|-------------|\n| `/suggest-ai-features [path]` | Scan codebase, recommend where AI/ML adds value, generate AI_ENHANCEMENT_PLAN.md |\n| `/ai-upgrade <feature>` | Implementation counterpart to `/suggest-ai-features` — add AI to a specific feature |\n| `/trace-impact \"<change>\"` | Trace full-stack blast radius of a code change (DB → service → API → frontend) |\n| `/estimate-cost [\"scenario\"]` | Project infra + API costs at 100 / 1K / 10K / 100K users; compare service alternatives |\n| `/feature-map [feature]` | Build visual feature dependency map of the codebase as a Mermaid diagram |\n\n### Maintenance (1)\n\n| Command | Description |\n|---------|-------------|\n| `/dep-update [--security-only]` | Auto-update dependencies safely with test-after-each-bump |\n\n### Cortex Cloud (3)\n\n| Command | Description |\n|---------|-------------|\n| `/cortex-login` | Authenticate the plugin to Cortex Cloud via RFC 8628 device-grant login |\n| `/cortex-logout` | Log out — revoke and clear local Cortex Cloud credentials |\n| `/cortex-status` | Show Cortex Cloud connection + project status |\n\n---\n\n## Subagents\n\n13 specialized AI agents that can be spawned in parallel for faster execution:\n\n| Agent | Expertise |\n|-------|-----------|\n| **Architect** | Architecture analysis, design reviews, scalability assessment |\n| **Brand Designer** | SVG logo generation, color systems, typography, design tokens |\n| **Security Auditor** | Vulnerability scanning, secret detection, OWASP compliance |\n| **Onboarding Mentor** | Interactive codebase Q&A for new developers |\n| **Test Strategist** | Test coverage analysis and quality improvement |\n| **Parallel Builder** | Multi-agent parallel task execution for autonomous builds |\n| **Self-Healer** | Auto-diagnoses and fixes errors during auto-build |\n| **DB Optimizer** | Slow query analysis, missing indexes, N+1 detection |\n| **DevOps Engineer** | CI/CD pipelines, Docker, Kubernetes, Terraform, deployment |\n| **Performance Profiler** | API profiling, bottleneck analysis, load testing |\n| **Documentation Writer** | README, architecture docs, API reference, deployment guides |\n| **Feature Analyzer** (Priya Sharma 🇮🇳) — *new v1.1.0* | Dissects existing codebases, maps features to code, detects patterns and anti-patterns |\n| **AI Integration Specialist** (Marcus Chen 🇺🇸) — *new v1.1.0* | Designs LLM integration, vector search, semantic analysis with cost-awareness |\n\n---\n\n## Auto-Invoked Skills\n\n27 skills that automatically activate when Claude detects matching task context.\nSplit into five categories:\n\n**Domain enforcement** (13 — fire when writing code matching their domain):\n\n| Skill | Triggers When |\n|-------|---------------|\n| **alpha-architecture** | Writing ANY code — enforces tech stack and layer segregation |\n| **project-setup** | Initializing or scaffolding projects |\n| **onboarding** | Onboarding developers or explaining codebase |\n| **code-review** | Reviewing code changes |\n| **testing** | Generating or running tests |\n| **deployment** | Deploying or configuring releases |\n| **security** | Writing auth code, handling user input, managing secrets |\n| **devops** | Creating Docker files, CI/CD pipelines, K8s manifests |\n| **performance** | Writing database queries, caching logic, async code |\n| **frontend** *(v1.5.0)* | Writing any UI — Next.js/React, Tailwind/shadcn, React Native, Chrome extensions; enforces the production bar (fonts, OKLCH tokens, real data, polish, friendly errors) |\n| **genai** *(v1.5.0)* | Writing LLM/RAG/agent code — enforces LiteLLM gateway, guardrails, cost caps, structured output, observability, evals |\n| **accessibility** *(v1.5.0)* | Writing UI — enforces WCAG 2.1 AA at authoring time (semantic HTML, ARIA, contrast, keyboard nav, focus) |\n| **database** *(v1.5.0)* | Schema/migration/model code — enforces safe reversible zero-downtime migrations, datastore selection, repository boundary |\n\n**Analysis & advisory** (5 — added v1.1.0):\n\n| Skill | Triggers When |\n|-------|---------------|\n| **cost-estimator** | User asks about costs, pricing, budgets, infrastructure estimates |\n| **dependency-mapper** | Architecture planning, refactor planning, \"what depends on what\" |\n| **feature-impact-analysis** | Schema changes, migrations, feature removal, API deprecation |\n| **metric-recommender** | Adding new features, setting up monitoring, KPI discussions |\n| **smart-retrofit** | \"Add AI to X\", \"make X smarter\", \"integrate AI\", \"enhance X\" |\n\n**Meta-process** (5 — added v1.2.0, makes Cortex self-contained — no Superpowers dependency):\n\n| Skill | Triggers When |\n|-------|---------------|\n| **cortex-brainstorming** | Before creating any new feature/product — runs the 5-question FEATURE_PROFILE builder |\n| **cortex-planning** | Before any multi-step implementation (3+ files OR 30+ min OR multi-layer OR hard-to-reverse) |\n| **cortex-tdd** | Before writing any implementation code — enforces red→green→refactor per language |\n| **cortex-debugging** | On any bug/failure/regression — enforces systematic reproduce→isolate→fix-at-right-layer loop |\n| **cortex-verification** | Before any \"done/fixed/complete\" claim — runs the language-specific verify suite |\n\n**Design & media** (3 — added v1.5.0, paired with /gen-mockup, /gen-pitch, /gen-demo-video):\n\n| Skill | Triggers When |\n|-------|---------------|\n| **mockup** | \"Mock up / wireframe / prototype this screen\" — brand-consistent screens as self-contained HTML/Next.js before building |\n| **pitch-deck** | \"Make a pitch deck / slides / investor presentation\" — Marp/Slidev markdown → PDF/HTML/PPTX, proven narrative arc |\n| **video-producer** | \"Make a demo / marketing video\" — Remotion (React) project: script → TTS voiceover + captions → branded MP4 |\n\n**Integration** (1 — added v1.4.0):\n\n| Skill | Triggers When |\n|-------|---------------|\n| **jira-integration** | Any Jira work — bidirectional sync via the Atlassian MCP server (no command; the skill is the whole surface) |\n\n---\n\n## Hooks\n\n7 event-driven automations that run automatically. Every hook is a real\nscript under `scripts/` (no inline bash — extracted in v1.1.2 for testability):\n\n| Hook | Event | Script | What It Does |\n|------|-------|--------|--------------|\n| **Safe Bash** | `PreToolUse` (Bash) | `safe-bash-check.sh` | Blocks dangerous commands (`rm -rf /`, `mkfs.`, fork bombs, etc.) |\n| **Session Context** | `SessionStart` | `session-context.sh` | Loads project context, git status, plugin banner |\n| **Auto-Format** | `PostToolUse` (Write + Edit) | `auto-format.sh` | Auto-formats per language (ruff/black for Python, prettier for JS/TS, google-java-format for Java) |\n| **Build Guard** | `Stop` | `auto-build-stop-hook.sh` | Blocks exit during `/auto-build` until product is complete |\n| **PreCompact Checkpoint** *(v1.1.x)* | `PreCompact` | `precompact-checkpoint.sh` | Snapshots `AUTO_BUILD_STATE.json` + auto-commits dirty changes before compaction |\n| **Teammate Reassign** *(experimental)* | `TeammateIdle` | `teammate-idle-reassign.sh` | Agent Teams: reassigns pending tasks to idle teammates |\n| **Task Gate** *(experimental, v1.3.1 secrets fix)* | `TaskCompleted` | `task-completed-quality-gate.sh` | Agent Teams: rejects task output with unresolved TODOs, skipped tests, or hardcoded secrets |\n\n---\n\n## Enforced Tech Stack\n\nThe plugin enforces these technologies across all projects. Backend language is auto-detected or set via `--lang` flag.\n\n### Backend Stack (per language)\n\n| Component | Python/FastAPI | Node.js/NestJS | Java/Spring Boot |\n|-----------|---------------|----------------|------------------|\n| Framework | FastAPI + Python 3.11+ | NestJS 11+ + TypeScript | Spring Boot 3.4+ + Java 21 |\n| ORM | SQLAlchemy 2.0 async | Prisma | Spring Data JPA + Hibernate 6 |\n| Auth lib | python-jose + passlib | @nestjs/jwt + bcryptjs | jjwt-api + Spring Security |\n| Email | fastapi-mail + Celery | @nestjs-modules/mailer + BullMQ | spring-boot-starter-mail + @Async |\n| Queue | Celery + Redis | BullMQ | Spring @Async + @Scheduled |\n| Linter | ruff | ESLint + Prettier | Checkstyle + SpotBugs |\n| Types | mypy (strict) | TypeScript (built-in) | Java compiler (built-in) |\n| Tests | pytest + pytest-asyncio | Jest + supertest | JUnit 5 + Mockito + MockMvc |\n| Migrations | Alembic | Prisma migrate | Flyway |\n| Package | pip + requirements.txt | pnpm + package.json | Gradle (Kotlin DSL) |\n| Docker base | python:3.11-slim | node:22-alpine | eclipse-temurin:21-jre-alpine |\n| GenAI | LiteLLM + Google ADK | Vercel AI SDK + LangChain.js | Spring AI + LangChain4j |\n\n### Shared Stack (all languages)\n\n| Layer | Technology |\n|-------|-----------|\n| Auth | JWT in HTTP-Only Cookies + CSRF double-submit |\n| Social Login | Google OAuth2 (server-side Authorization Code Grant) |\n| SQL Database | MySQL 8.0 + ORM per language |\n| NoSQL Database | MongoDB 7 |\n| Cache | Redis 7 |\n| Payments | Razorpay (Subscriptions + Credit Points + GST) |\n| Frontend Web | Next.js 15+ + TypeScript + Tailwind CSS |\n| Frontend Mobile | React Native 0.83+ + Expo SDK 55+ + NativeWind |\n| Themes | Light + Dark + System Auto |\n| Search | Meilisearch (full-text search) |\n| File Storage | S3/MinIO + presigned URL uploads |\n| Real-Time | WebSocket + Redis pub/sub |\n| Push Notifications | FCM via firebase-admin |\n| Error Tracking | Sentry (backend + frontend + mobile) |\n| Analytics | PostHog (self-hosted) |\n| RAG Pipeline | Qdrant + text-embedding-3-large + semantic chunking |\n| AI Observability | Langfuse or LangSmith (LLM tracing) |\n| MCP Protocol | MCP server (tools + prompts + resources) |\n| A2A Protocol | Agent Card discovery + task lifecycle |\n\n---\n\n## Architecture\n\n```\ncortex/\n|\n|-- .claude-plugin/\n|   |-- plugin.json                  # Plugin metadata\n|   +-- marketplace.json             # Marketplace catalog for distribution\n|\n|-- commands/                        # 37 SLASH COMMANDS\n|   |\n|   |  # Planning & Research\n|   |-- gen-prd.md                   # /gen-prd\n|   |-- gen-brand.md                 # /gen-brand\n|   |-- market-research.md           # /market-research\n|   |-- sprint-plan.md               # /sprint-plan\n|   |\n|   |  # Design & Media (v1.5.0)\n|   |-- gen-mockup.md                 # /gen-mockup\n|   |-- gen-pitch.md                  # /gen-pitch\n|   |-- gen-demo-video.md            # /gen-demo-video\n|   |\n|   |  # Project Setup\n|   |-- init-project.md              # /init-project\n|   |-- analyze-project.md           # /analyze-project\n|   |-- gap-analysis.md              # /gap-analysis\n|   |-- seed-data.md                 # /seed-data\n|   |\n|   |  # Building\n|   |-- auto-build.md                # /auto-build (CORE)\n|   |-- resume-build.md              # /resume-build\n|   |-- feature.md                   # /feature\n|   |-- retrofit.md                  # /retrofit\n|   |-- migrate-stack.md             # /migrate-stack\n|   |-- refactor.md                  # /refactor\n|   |-- debug.md                     # /debug\n|   |\n|   |  # Quality & Testing\n|   |-- code-review.md               # /code-review\n|   |-- gen-tests.md                 # /gen-tests\n|   |-- e2e-test.md                  # /e2e-test\n|   |-- perf-test.md                 # /perf-test\n|   |-- security-scan.md             # /security-scan\n|   |-- accessibility.md             # /accessibility\n|   |-- tech-debt.md                 # /tech-debt\n|   |-- health-check.md              # /health-check\n|   |\n|   |  # Shipping & Release\n|   |-- ship.md                      # /ship\n|   |-- release.md                   # /release\n|   |-- changelog.md                 # /changelog\n|   |-- deploy.md                    # /deploy\n|   |-- gen-ci.md                    # /gen-ci\n|   |\n|   |  # Infrastructure & DevOps\n|   |-- gen-infra.md                 # /gen-infra\n|   |-- db-migrate.md                # /db-migrate\n|   |-- docker-clean.md              # /docker-clean\n|   |-- monitoring.md                # /monitoring\n|   |-- runbook.md                   # /runbook\n|   |\n|   |  # Documentation & People\n|   |-- gen-docs.md                  # /gen-docs\n|   |-- api-docs.md                  # /api-docs\n|   |-- onboard-dev.md               # /onboard-dev\n|   |\n|   |  # Maintenance\n|   |-- dep-update.md                # /dep-update\n|   |\n|   |  # Cortex Cloud (auth + telemetry)\n|   |-- cortex-login.md              # /cortex-login\n|   |-- cortex-logout.md             # /cortex-logout\n|   +-- cortex-status.md             # /cortex-status\n|\n|-- agents/                          # 11 SUBAGENTS\n|   |-- architect.md                 # Architecture analysis\n|   |-- brand-designer.md            # SVG logos & brand identity\n|   |-- security-auditor.md          # Vulnerability scanning\n|   |-- onboarding-mentor.md         # Developer Q&A\n|   |-- test-strategist.md           # Test coverage\n|   |-- parallel-builder.md          # Parallel execution\n|   |-- self-healer.md               # Auto error fixing\n|   |-- db-optimizer.md              # Database optimization\n|   |-- devops-engineer.md           # CI/CD and infrastructure\n|   |-- performance-profiler.md      # Performance analysis\n|   +-- documentation-writer.md      # Documentation generation\n|\n|-- skills/                          # 27 AUTO-INVOKED SKILLS\n|   |-- alpha-architecture/\n|   |   |-- SKILL.md                 # Tech stack enforcement\n|   |   +-- references/              # CODE_PATTERNS_* per language + frontend + genai (progressive disclosure)\n|   |-- project-setup/SKILL.md\n|   |-- onboarding/SKILL.md\n|   |-- code-review/SKILL.md\n|   |-- testing/SKILL.md\n|   |-- deployment/SKILL.md\n|   |-- security/SKILL.md            # OWASP, auth, secrets enforcement\n|   |-- devops/SKILL.md              # Docker, CI/CD, K8s enforcement\n|   |-- performance/SKILL.md         # DB, caching, async enforcement\n|   |-- frontend/SKILL.md            # Frontend production bar (fonts, OKLCH tokens, real data, friendly errors)\n|   |-- genai/SKILL.md               # LLM gateway, guardrails, cost caps, RAG, evals\n|   |-- accessibility/SKILL.md       # WCAG 2.1 AA at authoring time\n|   |-- database/SKILL.md            # Safe migrations, datastore selection, repo boundary\n|   |-- mockup/SKILL.md              # UI screen mockups/wireframes as code (paired with /gen-mockup)\n|   |-- pitch-deck/SKILL.md          # Pitch/demo decks via Marp/Slidev (paired with /gen-pitch)\n|   |-- video-producer/SKILL.md      # Demo/marketing video via Remotion (paired with /gen-demo-video)\n|   |-- cost-estimator/ dependency-mapper/ feature-impact-analysis/   # analysis & advisory\n|   |-- metric-recommender/ smart-retrofit/\n|   |-- cortex-brainstorming/ cortex-planning/ cortex-tdd/            # meta-process\n|   |-- cortex-debugging/ cortex-verification/\n|   +-- jira-integration/SKILL.md    # bidirectional Jira sync via Atlassian MCP\n|\n|-- hooks/\n|   +-- hooks.json                   # 6 event-driven hooks\n|\n|-- scripts/\n|   |-- auto-loop.sh                 # Persistent autonomous loop runner\n|   |-- auto-build-stop-hook.sh      # Prevents exit during auto-build\n|   |-- session-context.sh           # Session initialization\n|   +-- safe-bash-check.sh           # Dangerous command detection\n|\n|-- .gitignore                       # Git ignore rules\n|-- CLAUDE.md                        # Plugin development context\n|-- README.md                        # This file\n+-- LICENSE                          # MIT License\n```\n\n---\n\n## Usage Examples\n\n### Fully Autonomous Product Build\n\n```bash\n# Generate PRD from an idea\n/gen-prd \"Build a SaaS invoicing platform for Indian freelancers with GST compliance\"\n\n# Build the entire product autonomously\n/auto-build ./PRD.md\n\n# If interrupted, resume from where it left off\n/resume-build\n\n# Or use the shell script for persistent execution\n./scripts/auto-loop.sh ./PRD.md --max-iterations 100\n```\n\n### Migrate an Existing Project\n\n```bash\n# Step 1: Understand the existing codebase\n/analyze-project ./my-existing-app\n\n# Step 2: Check what's missing vs Alpha AI standards\n/gap-analysis\n\n# Step 3: Migrate technology stack\n/migrate-stack PostgreSQL to MySQL\n/migrate-stack localStorage JWT to HTTP-Only Cookie JWT\n/migrate-stack Stripe to Razorpay\n\n# Step 4: Add missing features\n/retrofit jwt-cookies\n/retrofit google-oauth\n/retrofit razorpay\n/retrofit credit-points\n/retrofit dark-mode\n/retrofit meilisearch\n/retrofit sentry\n```\n\n### Generate Complete CI/CD and Infrastructure\n\n```bash\n# Generate CI/CD pipeline\n/gen-ci github-actions\n\n# Generate Infrastructure as Code\n/gen-infra docker          # Docker Compose (dev + prod + test)\n/gen-infra k8s             # Kubernetes manifests with Kustomize\n/gen-infra k3s             # K3s manifests for Hostinger VPS (Traefik IngressRoute)\n/gen-infra terraform       # AWS Terraform modules\n/gen-infra helm            # Helm chart\n\n# Generate operational runbooks\n/runbook --type=all\n```\n\n### Security and Quality Audit\n\n```bash\n# Full security scan\n/security-scan --full\n\n# Auto-fix security issues\n/security-scan --fix\n\n# Check accessibility\n/accessibility --fix\n\n# Scan technical debt\n/tech-debt --fix-quick-wins\n\n# Performance testing\n/perf-test all --users=100 --duration=60s\n\n# End-to-end tests\n/e2e-test --all --visual\n```\n\n### Release Management\n\n```bash\n# Auto-generate changelog\n/changelog\n\n# Create a release (auto-detects version bump from commits)\n/release patch\n/release minor\n/release major\n\n# Dry run first\n/release minor --dry-run\n\n# Update dependencies safely\n/dep-update                  # All updates\n/dep-update --security-only  # Only security patches\n/dep-update --dry-run        # Preview what would change\n```\n\n### Documentation\n\n```bash\n# Generate all documentation\n/gen-docs --type=all\n\n# Generate specific docs\n/gen-docs --type=readme\n/gen-docs --type=architecture\n/gen-docs --type=api\n/gen-docs --type=deployment\n/gen-docs --type=contributing\n\n# Generate Docusaurus site\n/gen-docs --type=all --format=docusaurus\n```\n\n---\n\n## Agent Teams\n\nAgent Teams is an **experimental feature** that enables true multi-agent parallelism. When enabled, commands like `/auto-build`, `/code-review`, and `/debug` spawn multiple Claude Code instances that work as coordinated teammates.\n\n### How It Works\n\n```\nTeam Lead (you/Arjun)\n├── Creates team with TeamCreate\n├── Spawns teammates (each is a full Claude instance)\n├── Creates shared tasks with TaskCreate\n├── Assigns tasks with TaskUpdate\n└── Coordinates via SendMessage\n\nTeammates (viktor, yuki, marcus, liam, oleksiy, sofia, ...)\n├── Check TaskList for assigned tasks\n├── Work on tasks independently (true parallelism)\n├── Communicate with SendMessage\n├── Mark tasks completed with TaskUpdate\n└── Auto-unblock dependent tasks\n```\n\n### Enabling Agent Teams\n\nAdd to `~/.claude/settings.json`:\n\n```json\n{\n  \"env\": {\n    \"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\"\n  }\n}\n```\n\n### Agent Teams Hooks\n\nThe plugin includes 2 hooks for Agent Teams coordination:\n\n| Hook | What It Does |\n|------|--------------|\n| **TeammateIdle** | When a teammate finishes and goes idle, checks for pending tasks and reassigns (exit code 2 = keep working) |\n| **TaskCompleted** | Quality gate — validates task output before accepting |\n\n### Fallback\n\nWhen Agent Teams is **not enabled**, all commands automatically fall back to standard Agent subagents. No configuration changes needed — the plugin detects the setting and adapts.\n\n---\n\n## Configuration\n\n### Disabling the Plugin\n\n```bash\n# If installed via marketplace\n/plugin disable cortex@alphaai\n\n# If using settings.json, remove the directory entry:\n# Remove from ~/.claude/settings.json → plugins.directories\n\n# If using --plugin-dir, just stop passing the flag\nclaude  # without --plugin-dir\n```\n\n### Development Mode\n\nFor plugin development and testing:\n\n```bash\n# Load with --plugin-dir (changes take effect immediately, no reinstall)\nclaude --plugin-dir /path/to/cortex\n\n# Check loaded commands\n/help\n\n# Check loaded agents\n/agents\n\n# Check loaded hooks\n/hooks\n```\n\n---\n\n## Uninstall\n\n```bash\n# If installed via marketplace\n/plugin uninstall cortex@alphaai\n\n# If using --plugin-dir, just stop passing the flag\nclaude  # without --plugin-dir\n```\n\n---\n\n## Troubleshooting\n\n### Plugin not loading / No banner on startup\n\n1. **Check the path is absolute** in `~/.claude/settings.json` — relative paths and `~` don't work\n2. **Verify plugin.json exists**: `ls /path/to/cortex/.claude-plugin/plugin.json`\n3. **Restart Claude Code** — plugins load at session start, not mid-session\n4. **Check settings.json is valid JSON**: `cat ~/.claude/settings.json | python3 -m json.tool`\n\n### Commands not showing in /help\n\n1. Verify plugin directory has `commands/` folder with `.md` files\n2. Check each command file has valid YAML frontmatter (starts with `---`)\n3. Restart Claude Code after any command file changes\n\n### Hooks not firing\n\n1. **Scripts must be executable**: `chmod +x scripts/*.sh`\n2. **Restart required** — hooks load at session start only\n3. **Validate hooks.json**: `cat hooks/hooks.json | python3 -m json.tool`\n4. **Check script paths** — hooks.json uses `${CLAUDE_PLUGIN_ROOT}` which resolves at runtime\n\n### Auto-build stops unexpectedly\n\n1. Check rate limits — the auto-loop script handles rate limit pauses\n2. Use `/resume-build` to continue from the last checkpoint\n3. For persistent execution: `./scripts/auto-loop.sh ./PRD.md`\n4. Verify `AUTO_BUILD_STATE.json` exists in project root during active builds\n\n### Agent Teams not working\n\n1. **Verify the env flag**: Check `~/.claude/settings.json` has `\"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS\": \"1\"` under `env`\n2. **Restart Claude Code** — env vars load at session start\n3. **Check permissions**: Agent Teams requires `Agent` in the `permissions.allow` list\n4. **Teammates not responding**: Teammates go idle between turns — this is normal. Send them a message to wake them up\n\n### Permission prompts on every action\n\nAdd the required permissions to `~/.claude/settings.json` → `permissions.allow` (see [Step 3: Configure Permissions](#step-3-configure-permissions))\n\n### \"command not found\" errors in hooks\n\n1. Ensure `jq` is installed: `brew install jq` (macOS) or `apt install jq` (Linux)\n2. Ensure `ruff` or `black` is installed for Python auto-formatting: `pip install ruff`\n\n---\n\n## Contributing\n\n1. Fork this repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Make changes following the plugin architecture (see `CLAUDE.md`)\n4. Test locally: `claude --plugin-dir .`\n5. Commit with conventional commits: `git commit -m \"feat: add my feature\"`\n6. Push and open a Pull Request\n\n### Adding a New Command\n\n1. Create `commands/my-command.md` with YAML frontmatter\n2. Add `description` and `allowed-tools` fields\n3. Write the instruction body\n4. Update `CLAUDE.md` directory structure\n5. Test with `--plugin-dir`\n\n### Adding a New Agent\n\n1. Create `agents/my-agent.md` with YAML frontmatter\n2. Write the system prompt\n3. Reference from commands using the Agent tool\n\n### Adding a New Skill\n\n1. Create `skills/my-skill/SKILL.md` with YAML frontmatter\n2. Set the `description` as a trigger condition\n3. Claude auto-invokes it when task context matches\n\n---\n\n## License\n\nMIT License - See [LICENSE](LICENSE) for details.\n\nCopyright (c) 2025-2026 Alpha AI Service Pvt Ltd\n\n---\n\n**Built by Alpha AI Service Pvt Ltd** | [alphaaiservice.com](https://alphaaiservice.com)\n# cortex\n",
  "bytes": 39502,
  "sha": "30ab908f99c88ecd99d540b2506119ff04373f67f9e99a4794ac7106a7ff6ffa",
  "repo_slug": "alphaaiservice/cortex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_alphaaiservice_cortex_cortex_df80d911/readme"
}