brainforge-ai 1.1.1 → 1.2.1

package/README.md

@@ -1,420 +1,863 @@
-# ⚡ BrainForge
-
-> Transform any idea into a structured, AI-assisted project — with agents, slash commands, a phase roadmap, persistent memory, and a live dashboard.
-
-[![npm version](https://img.shields.io/npm/v/brainforge-ai.svg)](https://www.npmjs.com/package/brainforge-ai)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Node.js >= 16](https://img.shields.io/badge/node-%3E%3D16-brightgreen)](https://nodejs.org)
-
-```bash
-npx brainforge-ai init
-```
-
----
-
-## What is BrainForge?
-
-BrainForge is a CLI that installs a **structured AI development system** into any project directory.
-
-Instead of vibing and hoping the AI does the right thing, BrainForge forces a clean workflow:
-
-```
-Idea → Plan → Research → Execute → Test → Review → Commit → Repeat
-```
-
-It works with any AI tool: **Claude Code**, **GitHub Copilot**, **Gemini CLI**, **Codex**, **Cursor**, **OpenCode**.
-
----
-
-## Why use it?
-
-| Without BrainForge | With BrainForge |
-|--------------------|-----------------|
-| AI codes everything at once | AI follows a phase plan |
-| No memory between sessions | Persistent project memory |
-| Hard to explain your code | `/explain-my-code` generates your defense speech |
-| Code looks too AI-perfect | Code Level Engine adapts to your real level |
-| No tests | `/write-tests` generates the right tests for your level |
-| No version history | Automatic git checkpoints |
-| Lost in files | Live dashboard with auto-reload |
-
----
-
-## Installation
-
-### Run directly (no install needed)
-
-```bash
-npx brainforge-ai init
-```
-
-### Install globally
-
-```bash
-npm install -g brainforge-ai
-brainforge init
-```
-
----
-
-## Quick Start
-
-### 1. Initialize BrainForge in your project
-
-```bash
-mkdir my-project
-cd my-project
-npx brainforge-ai init
-```
-
-Answer the questions:
-- Project name and description
-- Project type (web app, API, fullstack, mobile…)
-- Stack (React, Node.js, PostgreSQL…)
-- Your actual coding level
-- Target code level
-- Whether it's a school project
-
-BrainForge generates the full structure and makes the first git commit automatically.
-
----
-
-### 2. Open your AI tool and start working
-
-Open **Claude Code**, **Cursor**, or any AI tool in the project folder.
-
-The AI reads `AGENTS.md` automatically and knows the rules.
-
----
-
-### 3. Follow the workflow with slash commands
-
-#### Step 1 — Document the project
-```
-/start-project
-```
-Describe your idea. The AI asks questions and fills in `.brainforge/project.md`.
-
-#### Step 2 — Create the roadmap
-```
-/create-roadmap
-```
-Breaks the project into phases with tasks and checklists.
-
-#### Step 3 — Prepare a phase (before coding)
-```
-/initiate-phase 1
-```
-Research + planning. The AI proposes an approach and waits for your confirmation.
-
-#### Step 4 — Execute the phase
-```
-/execute-phase 1
-```
-The AI codes **only what was planned**. Nothing more.
-
-#### Step 5 — Write tests
-```
-/write-tests
-```
-Generates tests adapted to your stack and code level.
-
-#### Step 6 — Review the phase
-```
-/review-phase 1
-```
-Checks for bugs, dead code, complexity, and level-appropriateness.
-
-#### Step 7 — Save your progress
-```
-/checkpoint
-```
-Creates a local git commit. Never pushes automatically.
-
-#### Step 8 — Watch the dashboard update live
-```bash
-brainforge serve
-```
-Opens `localhost:3000` — reloads automatically as you work.
-
-Repeat steps 3–8 for each phase.
-
----
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `brainforge init` | Initialize BrainForge in the current directory |
-| `brainforge serve` | Live dashboard on localhost:3000 (auto-reloads) |
-| `brainforge dashboard` | Open the static HTML dashboard in the browser |
-| `brainforge update-dashboard` | Refresh dashboard data from project state |
-| `brainforge doctor` | Health check — verify all files and setup |
-| `brainforge guide` | Show all CLI and slash commands with project status |
-| `brainforge version` | Show version info |
-
----
-
-## Slash Commands
-
-These are prompt files in `.brainforge/commands/` — paste the command name into your AI tool.
-
-### Project Setup
-
-| Command | What it does |
-|---------|-------------|
-| `/start-project` | Document your idea and gather all project info |
-| `/create-roadmap` | Break project into phases (Epic › Feature › Task) |
-
-### Phase Workflow
-
-| Command | What it does |
-|---------|-------------|
-| `/initiate-phase N` | Research + plan phase N before any coding |
-| `/execute-phase N` | Code phase N following the plan exactly |
-| `/review-phase N` | Quality review — bugs, level check, academic check |
-| `/checkpoint` | Local git commit (never pushes automatically) |
-
-### Code Quality
-
-| Command | What it does |
-|---------|-------------|
-| `/write-tests` | Generate tests for a file, function, or phase |
-| `/humanize-code` | Adapt code to match your real coding level |
-| `/debug-issue` | Systematic bug analysis and fix |
-
-### Student Tools
-
-| Command | What it does |
-|---------|-------------|
-| `/explain-my-code` | Generate an explanation for your professor or team |
-| `/professor-check` | Detect code that looks suspiciously AI-generated |
-| `/generate-report` | Generate an academic report template |
-
-### Documentation & UI
-
-| Command | What it does |
-|---------|-------------|
-| `/design-system` | Create a UI/UX design system guide |
-| `/generate-docs` | Generate README and docs/ folder |
-| `/update-dashboard` | Refresh the HTML dashboard data |
-
----
-
-## The Live Dashboard
-
-Run `brainforge serve` to open a live dashboard at `localhost:3000`.
-
-It **auto-reloads** every time a file in `.brainforge/` changes — no manual refresh needed.
-
-```bash
-brainforge serve              # localhost:3000
-brainforge serve --port 4000  # custom port
-```
-
-It shows:
-- Project name, description, stack, and level
-- Phase progress bar
-- Status of each phase (pending / in-progress / done)
-- Recent git commits
-- Known bugs
-- Last architecture decisions
-- Git status
-- A green dot in the corner when live reload is active
-
----
-
-## Code Level Engine
-
-BrainForge adapts all generated and reviewed code to your target level:
-
-| Level | Who it's for | What it produces |
-|-------|-------------|-----------------|
-| `beginner` | First year students | Simple functions, direct logic, FR comments |
-| `intermediate` | 1-3 years experience | Clean structure, reusable components |
-| `academic-realistic` | School / PFA projects | Credible student code — clean but explainable |
-| `professional` | Production projects | Typed, tested, secure, scalable |
-
-### The `academic-realistic` level
-
-The most important level for students. It produces code that:
-
-- ✅ Is clean enough to get a good grade
-- ✅ Is simple enough to explain line by line in an oral defense
-- ✅ Has no enterprise patterns that would raise suspicion
-- ✅ Looks like it was written by a good student, not a senior engineer
-- ✅ Has natural comments — not AI-generated-sounding ones
-
----
-
-## `/write-tests` — Test Generator
-
-The `/write-tests` command generates tests adapted to your project:
-
-- **Detects the right framework** automatically (Jest, Vitest, pytest, PHPUnit…)
-- **Adapts test complexity** to your code level
-- **Beginner:** 2-3 tests per function, happy path only, no mocks
-- **Academic-realistic:** happy path + edge cases, mocks for external services, readable names
-- **Professional:** full coverage, integration tests, all error paths
-
-```
-/write-tests src/auth/login.ts
-/write-tests the login feature
-/write-tests phase 2
-```
-
----
-
-## Project Structure
-
-After `brainforge init`, your project contains:
-
-```
-.brainforge/
-  config.json              ← project config (level, stack, phases…)
-  project.md               ← project definition
-  questions.md             ← answered questions from init
-  decisions.md             ← architecture decision log
-  roadmap.md               ← full roadmap
-  memory/
-    architecture.md        ← technical notes (updated each phase)
-    coding-style.md        ← code level rules
-    known-bugs.md          ← bug tracker
-    glossary.md            ← project vocabulary
-    design-system.md       ← UI/UX guide
-  phases/
-    phase-01.md            ← plan + checklist for phase 1
-    phase-02.md
-  agents/
-    architect.md           ← Architect agent
-    researcher.md          ← Researcher agent
-    planner.md             ← Planner agent
-    coder.md               ← Coder agent
-    reviewer.md            ← Reviewer agent
-    teacher.md             ← Teacher agent (for students)
-    git-agent.md           ← Git Agent
-    dashboard-agent.md     ← Dashboard Agent
-  commands/
-    start-project.md       ← /start-project
-    create-roadmap.md      ← /create-roadmap
-    initiate-phase.md      ← /initiate-phase
-    execute-phase.md       ← /execute-phase
-    review-phase.md        ← /review-phase
-    write-tests.md         ← /write-tests
-    humanize-code.md       ← /humanize-code
-    explain-my-code.md     ← /explain-my-code
-    professor-check.md     ← /professor-check
-    checkpoint.md          ← /checkpoint
-    debug-issue.md         ← /debug-issue
-    design-system.md       ← /design-system
-    generate-docs.md       ← /generate-docs
-    generate-report.md     ← /generate-report
-    update-dashboard.md    ← /update-dashboard
-  dashboard/
-    index.html             ← visual dashboard
-    style.css
-    data.json
-AGENTS.md                  ← instructions for all AI agents
-CLAUDE.md                  ← Claude Code specific config
-GEMINI.md                  ← Gemini CLI specific config
-OPENAI.md                  ← OpenAI / Codex specific config
-```
-
----
-
-## Multi-AI Compatibility
-
-BrainForge generates config files for every major AI tool:
-
-| File | Tool |
-|------|------|
-| `CLAUDE.md` | Claude Code |
-| `GEMINI.md` | Gemini CLI |
-| `OPENAI.md` | Codex / ChatGPT |
-| `AGENTS.md` | All tools (universal) |
-
-Each file tells the AI: what the project is, what code level to use, how to follow the workflow, what files to update, and git rules (never push).
-
----
-
-## Git Rules
-
-| Action | Status |
-|--------|--------|
-| `git init` | ✅ Auto on first init |
-| `git add` + `git commit` | ✅ Via `/checkpoint` |
-| `git push` | ❌ Never automatic |
-| `git push --force` | ❌ Never |
-
-You always control when and where you push.
-
----
-
-## Example Use Cases
-
-### School / PFA project
-```bash
-npx brainforge-ai init
-# → choose "academic-realistic" code level
-# → choose "yes" for academic project
-# → /start-project → /create-roadmap → phases
-# → /write-tests before each review
-# → /professor-check before submission
-# → /generate-report for the written report
-```
-
-### Personal MVP
-```bash
-npx brainforge-ai init
-# → choose "intermediate" or "professional"
-# → brainforge serve  ← keep the dashboard open while you build
-```
-
-### Learning a new stack
-```bash
-npx brainforge-ai init
-# → choose "beginner" or "intermediate"
-# → /explain-my-code after each phase to understand what was built
-```
-
----
-
-## Requirements
-
-- Node.js >= 16
-- Git (optional but recommended)
-- An AI tool: Claude Code, Cursor, Copilot, Gemini CLI, Codex…
-
----
-
-## Development
-
-```bash
-git clone https://github.com/MEHDImp4/brainforge-ai
-cd brainforge-ai
-npm install
-npm run build
-npm link
-
-# Test locally
-brainforge init
-brainforge guide
-brainforge serve
-brainforge doctor
-```
-
----
-
-## Contributing
-
-Issues and PRs welcome on [GitHub](https://github.com/MEHDImp4/brainforge-ai).
-
----
-
-## License
-
-MIT — free to use, modify, and share.
-
----
-
-*Built for students and developers who want structure before they start vibing.*
+# ⚡ BrainForge
+
+> Transform any idea into a structured, AI-assisted project — with agents, slash commands, a phase roadmap, persistent memory, a live dashboard, and **83 Claude Code skills** pre-wired for every task.
+
+[![npm version](https://img.shields.io/npm/v/brainforge-ai.svg)](https://www.npmjs.com/package/brainforge-ai)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Node.js >= 16](https://img.shields.io/badge/node-%3E%3D16-brightgreen)](https://nodejs.org)
+
+```bash
+npx brainforge-ai init
+```
+
+---
+
+## Dashboard Preview
+
+![BrainForge dashboard preview](./assets/screenshots/dashboard.png)
+
+---
+
+## What is BrainForge?
+
+BrainForge is a CLI that installs a **structured AI development system** into any project directory.
+
+Instead of vibing and hoping the AI does the right thing, BrainForge forces a clean workflow:
+
+```
+Idea → Plan → Research → Execute → Test → Review → Commit → Repeat
+```
+
+It works with any AI tool: **Claude Code**, **GitHub Copilot**, **Gemini CLI**, **Codex**, **Cursor**, **OpenCode**.
+
+---
+
+## Why use it?
+
+| Without BrainForge | With BrainForge |
+|--------------------|-----------------|
+| AI codes everything at once | AI follows a phase plan |
+| No memory between sessions | Persistent project memory |
+| Hard to explain your code | `/explain-my-code` generates your defense speech |
+| Code looks too AI-perfect | Code Level Engine adapts to your real level |
+| No tests | `/write-tests` generates the right tests for your level |
+| No version history | Automatic git checkpoints |
+| Lost in files | Live dashboard with auto-reload |
+| AI ignores best practices | 83 skills enforce the right patterns per task |
+
+---
+
+## Installation
+
+### Run directly (no install needed)
+
+```bash
+npx brainforge-ai init
+```
+
+### Install globally
+
+```bash
+npm install -g brainforge-ai
+brainforge init
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize BrainForge in your project
+
+```bash
+mkdir my-project
+cd my-project
+npx brainforge-ai init
+```
+
+Answer the questions:
+- Project name and description
+- Project type (web app, API, fullstack, mobile…)
+- Stack (React, Node.js, PostgreSQL…)
+- Your actual coding level
+- Target code level
+- Whether it's a school project
+
+BrainForge generates the full structure and makes the first git commit automatically.
+
+**Non-interactive mode** — skip all prompts with defaults:
+
+```bash
+npx brainforge-ai init --yes
+npx brainforge-ai init --preset student --yes
+```
+
+Useful for CI pipelines, automated tests, or quick demos.
+
+---
+
+### 2. Open your AI tool and start working
+
+Open **Claude Code**, **Cursor**, or any AI tool in the project folder.
+
+The AI reads `AGENTS.md` and `CLAUDE.md` automatically, which includes a mandatory skills table telling it exactly which skill file to load for every type of task.
+
+---
+
+### 3. Follow the workflow with slash commands
+
+#### Step 1 — Document the project
+```
+/start-project
+```
+Describe your idea. The AI asks questions and fills in `.brainforge/project.md`.
+
+#### Step 2 — Create the roadmap
+```
+/create-roadmap
+```
+Breaks the project into phases with tasks and checklists.
+
+#### Step 3 — Prepare a phase (before coding)
+```
+/initiate-phase 1
+```
+Research + planning. The AI proposes an approach and waits for your confirmation.
+
+#### Step 4 — Execute the phase
+```
+/execute-phase 1
+```
+The AI codes **only what was planned**. Nothing more.
+
+#### Step 5 — Write tests
+```
+/write-tests
+```
+Generates tests adapted to your stack and code level.
+
+#### Step 6 — Review the phase
+```
+/review-phase 1
+```
+Checks for bugs, dead code, complexity, and level-appropriateness.
+
+#### Step 7 — Save your progress
+```
+/checkpoint
+```
+Creates a local git commit. Never pushes automatically.
+
+#### Step 8 — Watch the dashboard update live
+```bash
+brainforge serve
+```
+Opens `localhost:3000` — reloads automatically as you work.
+
+Repeat steps 3–8 for each phase.
+
+---
+
+## What BrainForge actually generates
+
+After `brainforge init`, here is the core structure you really get:
+
+```text
+project-root/
+  .brainforge/
+    config.json
+    project.md
+    brain.md           ← master context file, load this at session start
+    roadmap.md
+    memory/            ← 8 persistent memory files
+    phases/
+    agents/            ← 41 specialized AI agents
+    commands/          ← 15+ slash command prompt files
+    reports/           ← generated reports (professor-check, simplify…)
+    dashboard/
+  .claude/
+    skills/            ← 83 Claude Code skill files
+  AGENTS.md
+  CLAUDE.md
+  GEMINI.md
+  OPENAI.md
+```
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `brainforge init` | Initialize BrainForge in the current directory |
+| `brainforge init --yes` | Non-interactive init with student defaults |
+| `brainforge status` | Show compact project summary (phases, git, features) |
+| `brainforge simplify` | Generate a prompt to simplify code to your level |
+| `brainforge professor-check` | Generate a prompt to detect AI-looking code patterns |
+| `brainforge update` | Refresh all agents, commands, and skills to latest version |
+| `brainforge serve` | Live dashboard on localhost:3000 (auto-reloads) |
+| `brainforge dashboard` | Open the static HTML dashboard in the browser |
+| `brainforge update-dashboard` | Refresh dashboard data from project state |
+| `brainforge doctor` | Health check — verify all files and setup |
+| `brainforge guide` | Show all CLI and slash commands with project status |
+| `brainforge version` | Show version info |
+
+---
+
+## `brainforge status`
+
+Get a quick read on your project without opening a browser:
+
+```bash
+brainforge status
+```
+
+Shows:
+- Project name, type, stack, code level, academic flag
+- Phase progress bar and status of each phase (pending / in-progress / done)
+- Enabled features (Docker, database, auth…)
+- Recent git commits and working tree state
+- Created / updated timestamps
+
+---
+
+## `brainforge simplify`
+
+Generates a structured simplification workflow for your current project:
+
+```bash
+brainforge simplify
+```
+
+This command does **two things**:
+
+1. Prints a context-aware prompt you can paste into Claude / Codex / Gemini to simplify your code to match your declared code level.
+2. Writes workflow files into your project brain:
+   - `.brainforge/commands/simplify-codebase.md` — the `/simplify-codebase` slash command
+   - `.brainforge/reports/simplify-plan.md` — a report template the AI fills in
+
+**Important:** `brainforge simplify` does not rewrite your code by itself. It generates the instructions your AI tool needs to do the simplification correctly, with the right rules for your level.
+
+Then in your AI tool:
+```
+/simplify-codebase
+```
+
+---
+
+## `brainforge professor-check`
+
+Generates an academic explainability review workflow:
+
+```bash
+brainforge professor-check
+```
+
+This command does **two things**:
+
+1. Prints a prompt you can paste into your AI tool to detect code that looks suspiciously over-engineered or AI-generated.
+2. Writes workflow files into your project brain:
+   - `.brainforge/commands/professor-check.md` — the `/professor-check` slash command
+   - `.brainforge/reports/professor-check.md` — a scored report template
+
+**Important:** This command does not fake authorship or encourage academic dishonesty. It checks whether your code is understandable and defensible at your declared level — so you can walk a professor through it confidently.
+
+Then in your AI tool:
+```
+/professor-check
+```
+
+The AI fills in the report with a realism score, flagged files, suspicious patterns, suggested simplifications, and likely oral defense questions with suggested answers.
+
+---
+
+## Claude Code Skills — 83 Pre-Wired Best-Practice Guides
+
+Every project initialized with BrainForge gets **83 skill files** installed in `.claude/skills/`. Claude Code reads these automatically when you trigger a matching task.
+
+Every agent and the `CLAUDE.md` instruction file include a mandatory skills table — Claude **must** read the relevant skill before starting any task. No exceptions.
+
+### How it works
+
+```
+You type: /execute-phase 1  (which involves React + TypeScript + API)
+         ↓
+Coder agent reads its skills table
+         ↓
+Loads: react-best-practices.md + typescript-patterns.md + api-design.md
+         ↓
+Codes with enforced best practices for all three technologies
+```
+
+### Skills by Category
+
+#### Core Engineering
+| Skill | What it enforces |
+|-------|-----------------|
+| `software-architecture` | System design, folder structure, module boundaries |
+| `typescript-patterns` | Strict typing, generics, discriminated unions |
+| `ag-clean-code` | SOLID principles, naming conventions, refactoring |
+| `ag-systematic-debugging` | Hypothesis-driven, evidence-first debugging |
+| `error-handling` | Result types, typed errors, retry logic |
+| `environment-config` | `.env` management, secrets, Zod validation |
+| `logging-observability` | Structured logging, tracing, OpenTelemetry |
+| `static-analysis` | ESLint, Semgrep, CodeQL, CVE scanning |
+
+#### Frontend & UI
+| Skill | What it enforces |
+|-------|-----------------|
+| `react-best-practices` | Components, hooks, state management patterns |
+| `next-best-practices` | Routing, SSR, caching, server actions |
+| `tailwind-css` | Utility classes, responsive design, dark mode |
+| `ag-tailwind-v4` | Tailwind v4 specifics, new API surface |
+| `web-performance` | Core Web Vitals, bundle size, lazy loading |
+| `accessibility` | WCAG 2.1, ARIA, keyboard navigation |
+| `ag-frontend-design` | Component layout, UX patterns |
+| `ag-web-design-guidelines` | Visual hierarchy, spacing, typography rules |
+| `figma-to-code` | Design handoff, CSS mapping from Figma |
+| `seo-optimization` | Meta tags, schema markup, Open Graph |
+| `internationalization` | i18n, locale detection, date/currency formatting |
+| `svelte-sveltekit` | Svelte 5, SvelteKit routes and actions |
+| `vue-nuxt` | Vue 3, Nuxt 3, Pinia, composables |
+| `angular-development` | Angular 17+, signals, standalone components |
+| `ag-mobile-design` | Mobile UI, React Native, Expo patterns |
+
+#### Backend & APIs
+| Skill | What it enforces |
+|-------|-----------------|
+| `api-design` | REST API design, OpenAPI, status codes |
+| `ag-api-patterns` | REST/RPC patterns, versioning, contracts |
+| `ag-nodejs-best-practices` | Node.js streams, modules, async patterns |
+| `ag-python-patterns` | Python packaging, type hints, idioms |
+| `ag-rust-pro` | Rust ownership, lifetimes, async, traits |
+| `graphql-api` | GraphQL schema, Apollo, DataLoader |
+| `websockets-realtime` | WebSockets, SSE, real-time architecture |
+| `event-driven-arch` | Pub/sub, message queues, BullMQ |
+| `rate-limiting` | Throttling, abuse prevention strategies |
+| `file-uploads` | S3, multipart, image processing |
+| `email-service` | Transactional email, Resend, templates |
+| `caching-redis` | Redis, TTL strategies, cache invalidation |
+| `monorepo` | Turborepo, pnpm workspaces, shared packages |
+
+#### Database
+| Skill | What it enforces |
+|-------|-----------------|
+| `database-queries` | Queries, migrations, ORM patterns |
+| `ag-database-design` | Schema design, normalization, ER modeling |
+| `postgres-best-practices` | PostgreSQL, indexes, RLS, query optimization |
+
+#### Security & Auth
+| Skill | What it enforces |
+|-------|-----------------|
+| `security-review` | Auth, access control, input validation |
+| `authentication-oauth` | JWT, OAuth2, session flows |
+| `better-auth` | Better Auth setup, OAuth providers, 2FA |
+| `ag-vulnerability-scanner` | OWASP Top 10, CVE scanning, threat modeling |
+| `ag-red-team-tactics` | Threat modeling, adversarial testing |
+
+#### Testing
+| Skill | What it enforces |
+|-------|-----------------|
+| `test-driven-development` | TDD cycles, test structure, coverage |
+| `ag-tdd-workflow` | Red-green-refactor discipline |
+| `ag-testing-patterns` | Mocks, fixtures, factories, coverage |
+| `webapp-testing` | Browser/UI testing, Playwright |
+| `api-testing` | Integration tests, Supertest patterns |
+| `property-based-testing` | Fuzz testing, generative test cases |
+
+#### DevOps & Deployment
+| Skill | What it enforces |
+|-------|-----------------|
+| `docker-devops` | Docker, compose, multi-stage builds |
+| `terraform-infrastructure` | IaC, Terraform, cloud provisioning |
+| `ag-deployment-procedures` | Deployment runbooks, rollback plans |
+| `ag-server-management` | nginx, systemd, server hardening |
+| `vercel-deployment` | Vercel deployment, edge middleware |
+| `netlify-deployment` | Netlify functions, forms, deployment |
+| `cloudflare-workers` | Cloudflare Workers, KV, Wrangler |
+| `github-workflow` | GitHub PRs, code review, CI/CD |
+
+#### Cloud Services & SaaS
+| Skill | What it enforces |
+|-------|-----------------|
+| `supabase` | Supabase auth, DB, storage, realtime |
+| `stripe-integration` | Stripe payments, subscriptions, webhooks |
+| `openai-integration` | OpenAI API, embeddings, tool use |
+| `huggingface-ml` | Hugging Face models, inference |
+| `sentry-monitoring` | Error tracking, alerts, performance |
+| `sanity-cms` | Sanity CMS, GROQ queries, schema |
+| `web-scraping` | Firecrawl, Playwright extraction |
+| `connect` | Third-party API integration patterns |
+| `composio-connect` | 1000+ SaaS integrations via Composio |
+
+#### Documentation & Process
+| Skill | What it enforces |
+|-------|-----------------|
+| `documentation` | Inline docs, README, JSDoc |
+| `content-writing` | Technical writing, copywriting |
+| `ag-documentation-templates` | Spec templates, ADR format |
+| `changelog` | Changelog format, release notes |
+| `deep-research` | Multi-step research with citations |
+| `prompt-engineering` | AI prompt crafting, optimization |
+| `subagent-development` | Parallel agents, task decomposition |
+
+#### Architecture & Planning
+| Skill | What it enforces |
+|-------|-----------------|
+| `ag-architecture` | High-level architecture decisions, ADRs |
+| `ag-app-builder` | Full app scaffolding, feature planning |
+| `ag-plan-writing` | Technical specs, scope documents |
+| `ag-intelligent-routing` | Agent routing, task delegation |
+| `ag-parallel-agents` | Parallel task splitting, fan-out patterns |
+| `ag-brainstorming` | Idea generation, creative problem solving |
+
+#### Language & Platform Specific
+| Skill | What it enforces |
+|-------|-----------------|
+| `ag-bash-linux` | Bash scripting, Linux CLI, shell automation |
+| `ag-powershell-windows` | PowerShell scripting, Windows automation |
+| `ag-mcp-builder` | MCP server and tool building |
+| `ag-game-development` | Game loops, physics, entity systems |
+| `ag-geo-fundamentals` | GIS, coordinates, spatial queries |
+| `ag-performance-profiling` | Flame graphs, APM, bottleneck analysis |
+| `code-review` | Code review process and quality gates |
+| `git-workflow` | Git operations, branching, commit conventions |
+| `ag-lint-and-validate` | Linting pipelines, formatting enforcement |
+| `ag-code-review-checklist` | PR checklists, review standards |
+| `ag-behavioral-modes` | Agent persona and mode switching |
+
+---
+
+## 41 Specialized Agents
+
+BrainForge installs **41 agent files** in `.brainforge/agents/`. Every agent has a `## Skills — Read BEFORE Starting` section that specifies exactly which skill files to load before starting work.
+
+### Core Workflow Agents
+
+| Agent | Role |
+|-------|------|
+| `architect` | System design, folder structure, architecture decisions |
+| `researcher` | Pre-implementation technical research |
+| `planner` | Phase planning and task breakdown |
+| `coder` | Implementation — reads 40+ skills based on task type |
+| `reviewer` | Code review — bugs, security, level-appropriateness |
+| `teacher` | Explain code, prepare for presentations/defenses |
+| `git-agent` | Local commits and checkpoints (never pushes) |
+| `dashboard-agent` | Keep the live dashboard up to date |
+
+### Advanced Agents (brainforge-*)
+
+These agents handle complex workflows: atomic code fixes, adversarial reviews, AI framework selection, UI auditing, security verification, and more.
+
+| Agent | Role |
+|-------|------|
+| `brainforge-advisor-researcher` | Research gray-area decisions — returns comparison tables |
+| `brainforge-ai-researcher` | AI/LLM framework implementation guidance |
+| `brainforge-assumptions-analyzer` | Extract codebase assumptions with evidence |
+| `brainforge-code-fixer` | Atomic fix application with rollback and verification |
+| `brainforge-code-reviewer` | Adversarial review → structured REVIEW.md |
+| `brainforge-codebase-mapper` | Analyze codebase: tech, arch, quality, concerns |
+| `brainforge-debug-session-manager` | Multi-cycle debug session orchestration |
+| `brainforge-debugger` | Scientific root cause investigation |
+| `brainforge-doc-classifier` | Classify planning docs: ADR/PRD/SPEC/DOC/UNKNOWN |
+| `brainforge-doc-synthesizer` | Merge classified docs, surface conflicts |
+| `brainforge-doc-verifier` | Verify doc claims against live codebase |
+| `brainforge-doc-writer` | Codebase-verified documentation writing |
+| `brainforge-domain-researcher` | AI system domain and eval criteria research |
+| `brainforge-eval-auditor` | Retroactive AI evaluation coverage audit |
+| `brainforge-eval-planner` | AI evaluation strategy design |
+| `brainforge-executor` | Atomic PLAN.md execution with TDD support |
+| `brainforge-framework-selector` | AI/LLM framework selection interview |
+| `brainforge-integration-checker` | Verify cross-phase wiring end-to-end |
+| `brainforge-intel-updater` | Generate structured codebase intel files |
+| `brainforge-nyquist-auditor` | Adversarial test gap closure |
+| `brainforge-pattern-mapper` | Map new files to existing code analogs |
+| `brainforge-phase-researcher` | Pre-planning domain investigation |
+| `brainforge-plan-checker` | 12-dimension plan verification |
+| `brainforge-planner` | Goal-backward phase plan creation |
+| `brainforge-project-researcher` | Ecosystem research before roadmap |
+| `brainforge-research-synthesizer` | Synthesize parallel researcher outputs |
+| `brainforge-roadmapper` | Requirements → phase roadmap |
+| `brainforge-security-auditor` | Threat model mitigation verification |
+| `brainforge-ui-auditor` | 6-pillar frontend implementation audit |
+| `brainforge-ui-checker` | UI-SPEC.md quality gate |
+| `brainforge-ui-researcher` | UI design contract creation |
+| `brainforge-user-profiler` | Analyze developer behavior across 8 dimensions |
+| `brainforge-verifier` | Goal-backward phase completion verification |
+
+---
+
+## Slash Commands
+
+These are prompt files in `.brainforge/commands/` — paste the command name into your AI tool.
+
+### Project Setup
+
+| Command | What it does |
+|---------|-------------|
+| `/start-project` | Document your idea and gather all project info |
+| `/create-roadmap` | Break project into phases (Epic › Feature › Task) |
+
+### Phase Workflow
+
+| Command | What it does |
+|---------|-------------|
+| `/initiate-phase N` | Research + plan phase N before any coding |
+| `/execute-phase N` | Code phase N following the plan exactly |
+| `/review-phase N` | Quality review — bugs, level check, academic check |
+| `/checkpoint` | Local git commit (never pushes automatically) |
+
+### Code Quality
+
+| Command | What it does |
+|---------|-------------|
+| `/write-tests` | Generate tests for a file, function, or phase |
+| `/humanize-code` | Adapt code to match your real coding level |
+| `/debug-issue` | Systematic bug analysis and fix |
+
+### Student Tools
+
+| Command | What it does |
+|---------|-------------|
+| `/explain-my-code` | Generate an explanation for your professor or team |
+| `/professor-check` | Detect code that looks suspiciously AI-generated |
+| `/generate-report` | Generate an academic report template |
+
+### Documentation & UI
+
+| Command | What it does |
+|---------|-------------|
+| `/design-system` | Create a UI/UX design system guide |
+| `/generate-docs` | Generate README and docs/ folder |
+| `/update-dashboard` | Refresh the HTML dashboard data |
+
+---
+
+## The Live Dashboard
+
+Run `brainforge serve` to open a live dashboard at `localhost:3000`.
+
+It **auto-reloads** every time a file in `.brainforge/` changes — no manual refresh needed.
+
+```bash
+brainforge serve              # localhost:3000
+brainforge serve --port 4000  # custom port
+```
+
+It shows:
+- Project name, description, stack, and level
+- Phase progress bar
+- Status of each phase (pending / in-progress / done)
+- Recent git commits
+- Known bugs
+- Last architecture decisions
+- Git status
+- A green dot in the corner when live reload is active
+
+---
+
+## Code Level Engine
+
+BrainForge adapts all generated and reviewed code to your target level:
+
+| Level | Who it's for | What it produces |
+|-------|-------------|-----------------|
+| `beginner` | First year students | Simple functions, direct logic, FR comments |
+| `intermediate` | 1-3 years experience | Clean structure, reusable components |
+| `academic-realistic` | School / PFA projects | Credible student code — clean but explainable |
+| `professional` | Production projects | Typed, tested, secure, scalable |
+
+### The `academic-realistic` level
+
+The most important level for students. It produces code that:
+
+- ✅ Is clean enough to get a good grade
+- ✅ Is simple enough to explain line by line in an oral defense
+- ✅ Has no enterprise patterns that would raise suspicion
+- ✅ Looks like it was written by a good student, not a senior engineer
+- ✅ Has natural comments — not AI-generated-sounding ones
+
+---
+
+## `/write-tests` — Test Generator
+
+The `/write-tests` command generates tests adapted to your project:
+
+- **Detects the right framework** automatically (Jest, Vitest, pytest, PHPUnit…)
+- **Adapts test complexity** to your code level
+- **Beginner:** 2-3 tests per function, happy path only, no mocks
+- **Academic-realistic:** happy path + edge cases, mocks for external services, readable names
+- **Professional:** full coverage, integration tests, all error paths
+
+```
+/write-tests src/auth/login.ts
+/write-tests the login feature
+/write-tests phase 2
+```
+
+---
+
+## Project Structure
+
+After `brainforge init`, your project contains:
+
+```
+.brainforge/
+  config.json              ← project config (level, stack, phases…)
+  project.md               ← project definition
+  questions.md             ← answered questions from init
+  decisions.md             ← architecture decision log
+  roadmap.md               ← full roadmap
+  memory/
+    architecture.md        ← technical notes (updated each phase)
+    coding-style.md        ← code level rules
+    known-bugs.md          ← bug tracker
+    glossary.md            ← project vocabulary
+    design-system.md       ← UI/UX guide
+    project-context.md     ← long-term context the AI should not forget
+    constraints.md         ← technical, code level, and academic constraints
+    learning-notes.md      ← concepts learned, bugs fixed, things to review
+  phases/
+    phase-01.md            ← plan + checklist for phase 1
+    phase-02.md
+  agents/                  ← 41 specialized AI agents
+    architect.md
+    researcher.md
+    planner.md
+    coder.md
+    reviewer.md
+    teacher.md
+    git-agent.md
+    dashboard-agent.md
+    brainforge-advisor-researcher.md
+    brainforge-ai-researcher.md
+    brainforge-assumptions-analyzer.md
+    brainforge-code-fixer.md
+    brainforge-code-reviewer.md
+    brainforge-codebase-mapper.md
+    brainforge-debug-session-manager.md
+    brainforge-debugger.md
+    brainforge-doc-classifier.md
+    brainforge-doc-synthesizer.md
+    brainforge-doc-verifier.md
+    brainforge-doc-writer.md
+    brainforge-domain-researcher.md
+    brainforge-eval-auditor.md
+    brainforge-eval-planner.md
+    brainforge-executor.md
+    brainforge-framework-selector.md
+    brainforge-integration-checker.md
+    brainforge-intel-updater.md
+    brainforge-nyquist-auditor.md
+    brainforge-pattern-mapper.md
+    brainforge-phase-researcher.md
+    brainforge-plan-checker.md
+    brainforge-planner.md
+    brainforge-project-researcher.md
+    brainforge-research-synthesizer.md
+    brainforge-roadmapper.md
+    brainforge-security-auditor.md
+    brainforge-ui-auditor.md
+    brainforge-ui-checker.md
+    brainforge-ui-researcher.md
+    brainforge-user-profiler.md
+    brainforge-verifier.md
+  commands/
+    start-project.md
+    create-roadmap.md
+    initiate-phase.md
+    execute-phase.md
+    review-phase.md
+    write-tests.md
+    humanize-code.md
+    explain-my-code.md
+    professor-check.md     ← generated by brainforge professor-check
+    simplify-codebase.md   ← generated by brainforge simplify
+    checkpoint.md
+    debug-issue.md
+    design-system.md
+    generate-docs.md
+    generate-report.md
+    update-dashboard.md
+  reports/
+    README.md              ← index of generated reports
+    professor-check.md     ← filled by AI after /professor-check
+    simplify-plan.md       ← filled by AI after /simplify-codebase
+  dashboard/
+    index.html             ← visual dashboard
+    style.css
+    data.json
+.claude/
+  skills/                  ← 83 Claude Code skill files (auto-loaded by agents)
+    software-architecture.md
+    typescript-patterns.md
+    react-best-practices.md
+    next-best-practices.md
+    api-design.md
+    database-queries.md
+    security-review.md
+    git-workflow.md
+    test-driven-development.md
+    code-review.md
+    … (83 total)
+AGENTS.md                  ← instructions for all AI agents
+CLAUDE.md                  ← Claude Code config + mandatory skills table
+GEMINI.md                  ← Gemini CLI config
+OPENAI.md                  ← OpenAI / Codex config
+```
+
+---
+
+## Screenshots
+
+### `.brainforge/` snapshot
+![.brainforge snapshot](./assets/screenshots/brainforge-tree.png)
+
+### `CLAUDE.md` snapshot
+![CLAUDE.md snapshot](./assets/screenshots/claude-md.png)
+
+### `AGENTS.md` snapshot
+![AGENTS.md snapshot](./assets/screenshots/agents-md.png)
+
+### Dashboard snapshot
+![Dashboard snapshot](./assets/screenshots/dashboard.png)
+
+---
+
+## Keeping Skills & Agents Up to Date
+
+Run `brainforge update` at any time to refresh all agent files, skill files, and slash commands to the latest version — without touching your project data (project.md, phases/, memory/, decisions.md are never modified).
+
+```bash
+brainforge update
+```
+
+---
+
+## Multi-AI Compatibility
+
+BrainForge generates config files for every major AI tool:
+
+| File | Tool |
+|------|------|
+| `CLAUDE.md` | Claude Code (with full 83-skill mandatory table) |
+| `GEMINI.md` | Gemini CLI |
+| `OPENAI.md` | Codex / ChatGPT |
+| `AGENTS.md` | All tools (universal) |
+
+Each file tells the AI: what the project is, what code level to use, how to follow the workflow, what files to update, and git rules (never push).
+
+---
+
+## Git Rules
+
+| Action | Status |
+|--------|--------|
+| `git init` | ✅ Auto on first init |
+| `git add` + `git commit` | ✅ Via `/checkpoint` |
+| `git push` | ❌ Never automatic |
+| `git push --force` | ❌ Never |
+
+You always control when and where you push.
+
+---
+
+## Example Use Cases
+
+### School / PFA project
+```bash
+npx brainforge-ai init --yes       # or run init and answer questions
+# → /start-project → /create-roadmap → phases
+# → /write-tests before each review
+# → brainforge simplify            # clean up before submission
+# → brainforge professor-check     # check for suspicious patterns
+# → /professor-check               # paste into AI to get the full report
+# → /generate-report               # generate the written report template
+# → brainforge status              # quick sanity check before handing in
+```
+
+### Personal MVP
+```bash
+npx brainforge-ai init
+# → choose "intermediate" or "professional"
+# → brainforge serve  ← keep the dashboard open while you build
+```
+
+### Learning a new stack
+```bash
+npx brainforge-ai init
+# → choose "beginner" or "intermediate"
+# → /explain-my-code after each phase to understand what was built
+```
+
+### AI system / LLM feature
+```bash
+npx brainforge-ai init
+# → brainforge-framework-selector picks your AI framework
+# → brainforge-ai-researcher writes implementation guidance
+# → brainforge-eval-planner designs the evaluation strategy
+# → brainforge-eval-auditor verifies it was actually implemented
+```
+
+---
+
+## Limitations
+
+BrainForge improves consistency and quality, but it does **not** fully control your AI assistant behavior.
+
+- It guides Claude/Cursor/Codex/Gemini with structure, prompts, and files.
+- The model can still ignore instructions, hallucinate, or take shortcuts.
+- You must review code, run tests, and validate security before shipping.
+- BrainForge is a workflow guardrail, not an autopilot guarantee.
+
+---
+
+## Requirements
+
+- Node.js >= 16
+- Git (optional but recommended)
+- An AI tool: Claude Code, Cursor, Copilot, Gemini CLI, Codex…
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/MEHDImp4/brainforge-ai
+cd brainforge-ai
+npm install
+npm run build
+npm link
+
+# Run the test suite
+npm test
+
+# End-to-end install verification (init → file check → doctor → status)
+npm run test:install
+
+# Verify the npm package contents
+npm run test:pack
+
+# Manual smoke test
+brainforge init --yes
+brainforge status
+brainforge simplify
+brainforge professor-check
+brainforge doctor
+brainforge serve
+```
+
+---
+
+## Contributing
+
+Issues and PRs welcome on [GitHub](https://github.com/MEHDImp4/brainforge-ai).
+
+---
+
+## License
+
+MIT — free to use, modify, and share.
+
+---
+
+*Built for students and developers who want structure, best practices, and 83 skill guides — before they start vibing.*