brainforge-ai 1.2.1 → 1.2.3

package/README.md

@@ -1,863 +1,344 @@
-# ⚡ 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.*
+# ⚡ BrainForge
+
+> A CLI that gives your AI a structured workflow — so it plans before it codes, adapts to your level, and remembers everything between sessions.
+
+[![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?
+
+When you use an AI like Claude or Copilot to code, you quickly run into these problems:
+
+- The AI codes everything at once — the result is too complex to understand
+- It forgets context between sessions
+- The code looks like "senior engineer" code when you're a student
+- You couldn't explain it to your professor
+
+**BrainForge installs a structure in your project** that forces the AI to:
+
+1. Plan before coding
+2. Follow clear phases (Plan → Code → Test → Review)
+3. Adapt the code to **your actual level**
+4. Keep persistent memory between sessions
+
+```
+Without BrainForge : AI does everything, you understand nothing
+With BrainForge    : AI follows your instructions step by step
+```
+
+Works with any AI tool: **Claude Code**, **Cursor**, **GitHub Copilot**, **Gemini CLI**, **Codex**, **OpenCode**.
+
+---
+
+## Dashboard Preview
+
+![BrainForge dashboard preview](./assets/screenshots/dashboard.png)
+
+---
+
+## Requirements
+
+- **Node.js** >= 16 — [download here](https://nodejs.org)
+- **Git** — recommended for automatic checkpoints
+- An **AI tool**: Claude Code, Cursor, Copilot, Gemini CLI, or any other
+
+> Verify Node.js is installed: `node --version`
+
+---
+
+## Quick Start (5 minutes)
+
+### Step 1 — Initialize BrainForge in your project
+
+```bash
+mkdir my-project
+cd my-project
+npx brainforge-ai init
+```
+
+You'll be asked a few simple questions:
+- Project name and description
+- Project type (web app, API, mobile app…)
+- Your tech stack (React, Node.js, Python…)
+- Your current coding level
+- Whether it's a school project
+
+BrainForge then generates the full structure and makes the first git commit automatically.
+
+> **Want to skip the questions?** Use `--yes` to apply defaults instantly:
+> ```bash
+> npx brainforge-ai init --yes
+> ```
+
+---
+
+### Step 2 — Open your AI tool in the project folder
+
+Open **Claude Code**, **Cursor**, or your preferred tool in the folder you just created.
+
+The AI will automatically read the `AGENTS.md` and `CLAUDE.md` files generated by BrainForge — it knows exactly what to do and how to behave.
+
+---
+
+### Step 3 — Follow the workflow with slash commands
+
+Type these commands directly into your AI tool, in order:
+
+| Command | What it does |
+|---------|-------------|
+| `/start-project` | Describe your idea — the AI asks questions and fills in the project file |
+| `/create-roadmap` | The AI breaks your project into phases with precise tasks |
+| `/initiate-phase 1` | The AI plans phase 1 and waits for your approval before coding |
+| `/execute-phase 1` | The AI codes **only what was planned** — nothing more |
+| `/write-tests` | Generates tests adapted to your level and stack |
+| `/review-phase 1` | Checks for bugs, complexity, and AI-looking patterns |
+| `/checkpoint` | Saves your progress with a local git commit (never pushes automatically) |
+
+Repeat `/initiate-phase`, `/execute-phase`, `/review-phase`, `/checkpoint` for each phase.
+
+---
+
+### Step 4 — Watch your progress on the live dashboard
+
+```bash
+brainforge serve
+```
+
+Opens `localhost:3000` in your browser — auto-reloads as you work.
+
+---
+
+## Student Tools
+
+If you're submitting a school project, these commands are built for you:
+
+### `brainforge simplify`
+
+```bash
+brainforge simplify
+```
+
+Generates a prompt to **simplify your code** to match your declared level. Useful before submission so every line is explainable.
+
+Then in your AI tool:
+```
+/simplify-codebase
+```
+
+### `brainforge professor-check`
+
+```bash
+brainforge professor-check
+```
+
+Generates a prompt to **detect patterns that look suspiciously AI-generated**. The goal: make sure you can defend every line in front of your professor.
+
+Then in your AI tool:
+```
+/professor-check
+```
+
+The AI fills in a report with a realism score, flagged files, suspicious patterns, suggested simplifications, and likely oral defense questions with suggested answers.
+
+> These tools don't help you cheat — they help you make sure you understand your own code.
+
+---
+
+## Code Levels
+
+BrainForge adapts all generated and reviewed code to your declared level:
+
+| Level | Who it's for | What it produces |
+|-------|-------------|-----------------|
+| `beginner` | First year students | Simple functions, direct logic, readable comments |
+| `intermediate` | 1–3 years experience | Clean structure, reusable components |
+| `academic-realistic` | School / internship projects | Clean enough for a good grade, simple enough to explain line by line |
+| `professional` | Production projects | Typed, tested, secure, scalable |
+
+The **`academic-realistic`** level is the most useful for students: the code is clean enough to get a good grade, but simple enough to walk through in an oral defense without raising suspicion.
+
+---
+
+## CLI Reference
+
+```bash
+brainforge init              # Initialize BrainForge in the current directory
+brainforge init --yes        # Non-interactive init with student defaults
+brainforge status            # Quick project summary (phases, git, features)
+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 current project state
+brainforge simplify          # Generate a code simplification prompt
+brainforge professor-check   # Generate an academic authenticity review
+brainforge study             # Initialize Study Mode files for understanding the project
+brainforge difficulty        # Generate a difficulty analysis workflow
+brainforge defense-pack      # Generate a full oral defense preparation workflow
+brainforge update            # Update agents, skills, and commands to latest version
+brainforge update --force    # Update including root instruction files (CLAUDE.md etc.)
+brainforge doctor            # Health check — verify all files and setup
+brainforge guide             # Show all CLI and slash commands
+brainforge version           # Show version info
+```
+
+---
+
+## What BrainForge Generates
+
+After `brainforge init`, your project contains:
+
+```
+my-project/
+  .brainforge/
+    config.json          ← your settings (level, stack, phases…)
+    project.md           ← project definition
+    roadmap.md           ← phase-by-phase work plan
+    memory/              ← persistent memory (the AI remembers between sessions)
+      architecture.md    ← technical notes
+      known-bugs.md      ← bug tracker
+      coding-style.md    ← style rules adapted to your level
+    phases/              ← one file per phase with checklist
+    agents/              ← 41 specialized AI roles (architect, coder, reviewer…)
+    commands/            ← slash command prompt files
+    dashboard/           ← HTML dashboard
+  .claude/
+    skills/              ← 83 best-practice guides (auto-loaded by agents)
+  AGENTS.md              ← instructions for all AI tools
+  CLAUDE.md              ← Claude Code config + mandatory skills table
+  GEMINI.md              ← Gemini CLI config
+  OPENAI.md              ← Codex / ChatGPT config
+```
+
+---
+
+## Examples
+
+### School project / internship
+
+```bash
+npx brainforge-ai init
+# Choose "academic-realistic" as your level
+# In your AI tool:
+# → /start-project  → /create-roadmap  → /initiate-phase 1  → /execute-phase 1
+# → /write-tests    → /review-phase 1  → /checkpoint
+# Before submitting:
+# → brainforge simplify        (clean up code to your level)
+# → brainforge professor-check (flag suspicious AI patterns)
+# → /professor-check           (get the full scored report)
+```
+
+### Learning a new stack
+
+```bash
+npx brainforge-ai init
+# Choose "beginner" or "intermediate"
+# → /explain-my-code after each phase to understand what was built
+```
+
+### Personal project or MVP
+
+```bash
+npx brainforge-ai init
+# Choose "intermediate" or "professional"
+# → brainforge serve  ← keep the dashboard open while you build
+```
+
+---
+
+## Git Rules
+
+BrainForge uses git to save your work but **never pushes automatically**:
+
+| Action | Behavior |
+|--------|---------|
+| `git init` | Automatic on first `init` |
+| Commit (`/checkpoint`) | Local only |
+| Push to GitHub | ❌ Never automatic — you decide |
+| Force push | ❌ Never |
+
+---
+
+## Troubleshooting
+
+**BrainForge won't start?**
+```bash
+node --version     # Must show v16 or higher
+brainforge doctor  # Verify the installation
+```
+
+**The AI isn't following commands?**
+- Make sure you opened your AI tool in the correct folder (the one with `.brainforge/`)
+- Run `/start-project` first if you haven't yet
+
+**Update BrainForge:**
+```bash
+brainforge update
+```
+
+---
+
+## Limitations
+
+BrainForge guides your AI with files and prompts — but it doesn't **fully control** what the AI does.
+
+- The AI can still ignore instructions, hallucinate, or take shortcuts
+- You must always review the code, run tests, and validate before submitting
+- BrainForge is a workflow guardrail, not an autopilot guarantee
+
+---
+
+## Under the Hood
+
+<details>
+<summary>83 best-practice skill files</summary>
+
+Every BrainForge project gets 83 skill files installed in `.claude/skills/`. They cover: React, Next.js, TypeScript, Node.js, Python, Rust, PostgreSQL, Docker, Stripe, Supabase, testing, security, accessibility, and much more.
+
+The AI loads them automatically based on the current task — you don't need to do anything.
+
+</details>
+
+<details>
+<summary>41 specialized agents</summary>
+
+BrainForge installs 41 agent files in `.brainforge/agents/`. Each has a specific role: architect, coder, reviewer, debugger, teacher, and more.
+
+Advanced agents (`brainforge-*`) handle complex workflows: security audits, test coverage verification, AI framework selection, UI auditing, and more.
+
+</details>
+
+<details>
+<summary>Multi-AI compatibility</summary>
+
+BrainForge generates config files for all major AI tools:
+
+| 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 target, how to follow the workflow, what files to update, and git rules.
+
+</details>
+
+---
+
+## 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 and best practices — not just vibing and hoping the AI gets it right.*