brainforge-ai 1.2.1 → 1.2.2

package/README.md

@@ -1,863 +1,326 @@
-# ⚡ 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
+
+> Un outil qui aide ton IA à coder **correctement et dans l'ordre** — au lieu de tout faire d'un coup et n'importe comment.
+
+[![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)
+
+---
+
+## C'est quoi BrainForge ?
+
+Quand tu utilises une IA comme Claude ou Copilot pour coder, tu rencontres vite ces problèmes :
+
+- L'IA code tout en une seule fois, et le résultat est trop complexe pour toi
+- Elle oublie le contexte d'une session à l'autre
+- Le code ressemble à du "code de senior" alors que tu es étudiant
+- Tu ne saurais pas l'expliquer à ton prof
+
+**BrainForge installe une structure dans ton projet** qui force l'IA à :
+
+1. Planifier avant de coder
+2. Suivre des phases claires (Planifier → Coder → Tester → Réviser)
+3. Adapter le code à **ton niveau réel**
+4. Garder une mémoire persistante entre les sessions
+
+```
+Sans BrainForge : l'IA fait tout, tu comprends rien
+Avec BrainForge : l'IA suit tes instructions étape par étape
+```
+
+---
+
+## Aperçu du dashboard
+
+![BrainForge dashboard preview](./assets/screenshots/dashboard.png)
+
+---
+
+## Ce qu'il te faut avant de commencer
+
+- **Node.js** (version 16 ou plus) — [télécharger ici](https://nodejs.org)
+- **Git** — recommandé pour sauvegarder ton travail automatiquement
+- Un **outil IA** : Claude Code, Cursor, GitHub Copilot, Gemini CLI, ou autre
+
+> Tu peux vérifier si Node.js est installé en tapant `node --version` dans ton terminal.
+
+---
+
+## Démarrage rapide (5 minutes)
+
+### Étape 1 — Lance BrainForge dans ton projet
+
+```bash
+mkdir mon-projet
+cd mon-projet
+npx brainforge-ai init
+```
+
+L'outil va te poser quelques questions simples :
+- Nom et description du projet
+- Type de projet (site web, API, app mobile…)
+- Les technologies que tu utilises (React, Node.js, Python…)
+- Ton niveau de code actuel
+- Si c'est un projet scolaire
+
+Ensuite il génère tout automatiquement et fait le premier commit git.
+
+> **Pas envie de répondre aux questions ?** Utilise `--yes` pour tout passer avec les valeurs par défaut :
+> ```bash
+> npx brainforge-ai init --yes
+> ```
+
+---
+
+### Étape 2 — Ouvre ton outil IA dans le dossier du projet
+
+Ouvre **Claude Code**, **Cursor**, ou ton outil préféré dans le dossier que tu viens de créer.
+
+L'IA lira automatiquement les fichiers `AGENTS.md` et `CLAUDE.md` générés par BrainForge — elle sait donc quoi faire et comment se comporter.
+
+---
+
+### Étape 3 — Suis le workflow avec des commandes
+
+Tape ces commandes directement dans ton outil IA, dans l'ordre :
+
+| Commande | Ce que ça fait |
+|----------|---------------|
+| `/start-project` | Tu décris ton idée, l'IA pose des questions et remplit le fichier projet |
+| `/create-roadmap` | L'IA divise ton projet en phases avec des tâches précises |
+| `/initiate-phase 1` | L'IA planifie la phase 1 et attend ta validation avant de coder |
+| `/execute-phase 1` | L'IA code **uniquement ce qui était prévu** — rien de plus |
+| `/write-tests` | Génère des tests adaptés à ton niveau |
+| `/review-phase 1` | Vérifie les bugs, la complexité, et si le code est trop "AI-looking" |
+| `/checkpoint` | Sauvegarde ton travail avec git (ne pousse jamais automatiquement) |
+
+Répète `/initiate-phase`, `/execute-phase`, `/review-phase`, `/checkpoint` pour chaque phase.
+
+---
+
+### Étape 4 — Surveille ta progression avec le dashboard
+
+```bash
+brainforge serve
+```
+
+Ouvre `localhost:3000` dans ton navigateur — il se recharge automatiquement pendant que tu travailles.
+
+---
+
+## Commandes spéciales pour les étudiants
+
+Si tu rends un projet scolaire, ces commandes sont faites pour toi :
+
+### `brainforge simplify`
+
+```bash
+brainforge simplify
+```
+
+Génère un prompt pour **simplifier le code** à ton niveau réel. Utile avant de rendre un projet pour que le code soit expliquable.
+
+Ensuite dans ton outil IA :
+```
+/simplify-codebase
+```
+
+### `brainforge professor-check`
+
+```bash
+brainforge professor-check
+```
+
+Génère un prompt pour **détecter les patterns qui semblent trop AI-générés**. Le but : vérifier que tu peux défendre chaque ligne devant un prof.
+
+Ensuite dans ton outil IA :
+```
+/professor-check
+```
+
+> Ces outils ne t'aident pas à tricher — ils t'aident à t'assurer que tu comprends ton propre code.
+
+---
+
+## Les niveaux de code
+
+BrainForge adapte le code généré à ton niveau :
+
+| Niveau | Pour qui | Ce que ça produit |
+|--------|----------|------------------|
+| `beginner` | 1ère année | Fonctions simples, logique directe, commentaires en français |
+| `intermediate` | 1-3 ans d'expérience | Structure propre, composants réutilisables |
+| `academic-realistic` | Projets scolaires / PFA | Code propre mais expliquable ligne par ligne — pas de patterns "enterprise" |
+| `professional` | Projets de production | Typé, testé, sécurisé, scalable |
+
+Le niveau **`academic-realistic`** est le plus utile pour les étudiants : le code est assez propre pour avoir une bonne note, mais assez simple pour l'expliquer en soutenance.
+
+---
+
+## Toutes les commandes CLI
+
+```bash
+brainforge init              # Initialiser BrainForge dans le dossier actuel
+brainforge init --yes        # Init sans questions (valeurs par défaut)
+brainforge status            # Voir l'état du projet en un coup d'œil
+brainforge serve             # Dashboard live sur localhost:3000
+brainforge simplify          # Générer un prompt de simplification du code
+brainforge professor-check   # Générer une vérification académique
+brainforge update            # Mettre à jour les agents et skills à la dernière version
+brainforge doctor            # Vérifier que tout est bien installé
+brainforge guide             # Voir toutes les commandes disponibles
+```
+
+---
+
+## Ce que BrainForge génère dans ton projet
+
+Après `brainforge init`, tu obtiens cette structure :
+
+```
+mon-projet/
+  .brainforge/
+    config.json          ← tes paramètres (niveau, stack, phases…)
+    project.md           ← description de ton projet
+    roadmap.md           ← ton plan de travail par phases
+    memory/              ← mémoire persistante (l'IA s'en souvient entre sessions)
+      architecture.md    ← notes techniques
+      known-bugs.md      ← bugs connus
+      coding-style.md    ← règles de style adaptées à ton niveau
+    phases/              ← un fichier par phase avec la checklist
+    agents/              ← 41 rôles d'IA spécialisés (architecte, codeur, reviewer…)
+    commands/            ← les fichiers de commandes slash
+    dashboard/           ← le dashboard HTML
+  .claude/
+    skills/              ← 83 guides de bonnes pratiques (chargés automatiquement)
+  AGENTS.md              ← instructions pour tous les outils IA
+  CLAUDE.md              ← config Claude Code
+  GEMINI.md              ← config Gemini CLI
+  OPENAI.md              ← config Codex / ChatGPT
+```
+
+---
+
+## Exemples concrets
+
+### Projet scolaire / PFA
+
+```bash
+npx brainforge-ai init
+# Choisir "academic-realistic" comme niveau
+# Dans ton outil IA :
+# → /start-project  → /create-roadmap  → /initiate-phase 1  → /execute-phase 1
+# → /write-tests    → /review-phase 1  → /checkpoint
+# Avant de rendre :
+# → brainforge simplify        (simplifier le code)
+# → brainforge professor-check (vérifier l'authenticité)
+# → /professor-check           (rapport complet)
+```
+
+### Apprendre un nouveau langage
+
+```bash
+npx brainforge-ai init
+# Choisir "beginner" ou "intermediate"
+# → /explain-my-code après chaque phase pour comprendre ce qui a été construit
+```
+
+### Projet personnel
+
+```bash
+npx brainforge-ai init
+# Choisir "intermediate" ou "professional"
+# → brainforge serve  ← garder le dashboard ouvert pendant que tu codes
+```
+
+---
+
+## Règles git
+
+BrainForge utilise git pour sauvegarder ton travail, mais **ne pousse jamais automatiquement** :
+
+| Action | Comportement |
+|--------|-------------|
+| `git init` | Automatique au premier `init` |
+| Commit (`/checkpoint`) | Oui, local uniquement |
+| Push vers GitHub | ❌ Jamais automatique — c'est toi qui décides |
+
+---
+
+## Dépannage
+
+**BrainForge ne se lance pas ?**
+```bash
+node --version   # Doit afficher v16 ou plus
+brainforge doctor  # Vérifie l'installation
+```
+
+**L'IA ne suit pas les commandes ?**
+- Assure-toi d'avoir ouvert ton outil IA dans le bon dossier (celui avec `.brainforge/`)
+- Lance `/start-project` en premier si ce n'est pas encore fait
+
+**Mettre à jour BrainForge :**
+```bash
+brainforge update
+```
+
+---
+
+## Limitations à connaître
+
+BrainForge guide l'IA avec des fichiers et des prompts — mais il ne **contrôle pas** ce que l'IA fait à 100%.
+
+- L'IA peut parfois ignorer les instructions ou prendre des raccourcis
+- Tu dois toujours relire le code, lancer les tests, et vérifier avant de remettre
+- BrainForge est un garde-fou, pas un pilote automatique
+
+---
+
+## Infos techniques (pour les curieux)
+
+<details>
+<summary>83 guides de bonnes pratiques (skills)</summary>
+
+Chaque projet BrainForge reçoit 83 fichiers de bonnes pratiques dans `.claude/skills/`. Ils couvrent : React, Next.js, TypeScript, Node.js, Python, Rust, PostgreSQL, Docker, Stripe, Supabase, tests, sécurité, accessibilité, et bien plus.
+
+L'IA les charge automatiquement selon la tâche en cours — tu n'as rien à faire.
+
+</details>
+
+<details>
+<summary>41 agents spécialisés</summary>
+
+BrainForge installe 41 fichiers d'agents dans `.brainforge/agents/`. Chaque agent a un rôle précis : architecte, codeur, reviewer, debugger, enseignant, etc.
+
+Les agents avancés (`brainforge-*`) gèrent des tâches complexes comme l'audit de sécurité, la vérification de couverture de tests, ou la sélection de framework IA.
+
+</details>
+
+<details>
+<summary>Compatibilité multi-IA</summary>
+
+BrainForge génère des fichiers de config pour tous les outils populaires :
+
+| Fichier | Outil |
+|---------|-------|
+| `CLAUDE.md` | Claude Code |
+| `GEMINI.md` | Gemini CLI |
+| `OPENAI.md` | Codex / ChatGPT |
+| `AGENTS.md` | Tous les outils (universel) |
+
+</details>
+
+---
+
+## Contribuer
+
+Issues et PRs bienvenus sur [GitHub](https://github.com/MEHDImp4/brainforge-ai).
+
+## Licence
+
+MIT — libre d'utilisation, de modification et de partage.
+
+---
+
+*Fait pour les étudiants et développeurs qui veulent coder avec structure — pas juste "vibe coder" et espérer que ça marche.*