brainforge-ai 1.0.0 → 1.0.1

package/README.md

@@ -2,6 +2,10 @@
 
 > Transform any idea into a structured, AI-assisted project — with agents, slash commands, a phase roadmap, persistent memory, and a live HTML 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
 ```
@@ -10,71 +14,123 @@ npx brainforge-ai init
 
 ## What is BrainForge?
 
-BrainForge is a CLI that installs a complete **structured AI development system** into any project directory.
-
-It gives you:
+BrainForge is a CLI that installs a **structured AI development system** into any project directory.
 
-- **8 specialized AI agents** (Architect, Coder, Reviewer, Researcher, Planner, Teacher, Git Agent, Dashboard Agent)
-- **15 slash commands** (`/start-project`, `/create-roadmap`, `/execute-phase`, `/humanize-code`, `/professor-check`…)
-- **Project memory** (architecture, coding style, known bugs, glossary, decisions)
-- **Phase-based roadmap** with validation checklists
-- **HTML dashboard** showing progress, commits, bugs, and decisions
-- **Git checkpoints** (local only — never pushes)
-- **Multi-AI compatibility** files (Claude Code, Codex, Gemini CLI, OpenCode, Cursor)
-- **Code Level Engine** (beginner / intermediate / academic-realistic / professional)
+Instead of vibing and hoping the AI does the right thing, BrainForge forces a clean workflow:
 
-### Who is it for?
+```
+Idea → Plan → Research → Execute → Review → Commit → Repeat
+```
 
-- Students building school or PFA projects
-- Beginners doing vibe-coding
-- Developers using Claude Code, Codex, Gemini CLI, Cursor, or Copilot
-- Anyone who wants structure before they start coding
+It works with any AI tool: **Claude Code**, **GitHub Copilot**, **Gemini CLI**, **Codex**, **Cursor**, **OpenCode**.
 
 ---
 
-## The Workflow
-
-```
-Idea / PRD
-→ /start-project     (document the project)
-→ /create-roadmap    (break into phases)
-→ /initiate-phase    (research + plan)
-→ /execute-phase     (code only what's planned)
-→ /review-phase      (quality check)
-→ /checkpoint        (local git commit)
-→ /update-dashboard  (refresh the dashboard)
-→ repeat per phase
-```
+## Why use it?
 
-**Rule:** The AI never codes without a plan. Always plan before executing.
+| 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 version history | Automatic git checkpoints |
+| Lost in files | Live HTML dashboard |
 
 ---
 
-## Installation & Usage
+## Installation
 
-### Option 1 — Run directly with npx (no install)
+### Run directly (no install needed)
 
 ```bash
 npx brainforge-ai init
 ```
 
-### Option 2 — Global install
+### Install globally
 
 ```bash
 npm install -g brainforge-ai
 brainforge init
 ```
 
-### Option 3 — Local development / npm link
+---
+
+## Quick Start
+
+### 1. Initialize BrainForge in your project
 
 ```bash
-git clone https://github.com/yourusername/brainforge-ai
-cd brainforge-ai
-npm install
-npm run build
-npm link
-brainforge init
+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 will generate the full structure and make the first git commit.
+
+---
+
+### 2. Open your AI tool and start working
+
+Open **Claude Code**, **Cursor**, or any AI tool in the project folder.
+
+The AI will automatically read `AGENTS.md` and know the rules.
+
+---
+
+### 3. Follow the workflow with slash commands
+
+#### Step 1 — Document the project
+```
+/start-project
+```
+Describe your idea. The AI asks questions, 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 — Review the phase
+```
+/review-phase 1
 ```
+Checks for bugs, dead code, complexity, and level-appropriateness.
+
+#### Step 6 — Save your progress
+```
+/checkpoint
+```
+Creates a local git commit. Never pushes.
+
+#### Step 7 — Update the dashboard
+```
+brainforge update-dashboard
+brainforge dashboard
+```
+
+Repeat steps 3–7 for each phase.
 
 ---
 
@@ -83,171 +139,239 @@ brainforge init
 | Command | Description |
 |---------|-------------|
 | `brainforge init` | Initialize BrainForge in the current directory |
-| `brainforge doctor` | Health check — verify all files and dependencies |
-| `brainforge dashboard` | Open the HTML dashboard in your browser |
-| `brainforge update-dashboard` | Refresh dashboard data from current project state |
+| `brainforge doctor` | Health check — verify all files and setup |
+| `brainforge dashboard` | Open the HTML dashboard in the browser |
+| `brainforge update-dashboard` | Refresh dashboard data from project state |
 | `brainforge version` | Show version info |
 
 ---
 
-## Generated Structure
+## Slash Commands
 
-After `brainforge init`, your project will contain:
+These are prompt files in `.brainforge/commands/` — paste the command name into your AI tool.
+
+| Command | What it does |
+|---------|-------------|
+| `/start-project` | Document your idea, gather all project info |
+| `/create-roadmap` | Break project into phases (Epic > Feature > Task) |
+| `/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 |
+| `/humanize-code` | Adapt code to match your real coding level |
+| `/explain-my-code` | Generate an explanation for a professor or team |
+| `/professor-check` | Detect code that looks suspiciously AI-generated |
+| `/checkpoint` | Local git commit (never pushes automatically) |
+| `/debug-issue` | Systematic bug analysis and fix |
+| `/design-system` | Create a UI/UX design system guide |
+| `/generate-docs` | Generate README and docs/ folder |
+| `/generate-report` | Generate an academic report template |
+| `/update-dashboard` | Refresh the HTML dashboard |
+
+---
+
+## Code Level Engine
+
+BrainForge adapts all generated 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
+
+This is the most important level for students. It produces code that:
+
+- ✅ Is clean enough to get a good grade
+- ✅ Is simple enough to explain 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
+
+---
+
+## Project Structure
+
+After `brainforge init`, your project contains:
 
 ```
 .brainforge/
-  config.json              ← project configuration
+  config.json              ← project config (level, stack, phases…)
   project.md               ← project definition
-  questions.md             ← Q&A from init
-  decisions.md             ← architecture decisions log
-  roadmap.md               ← full phase roadmap
+  questions.md             ← answered questions from init
+  decisions.md             ← architecture decision log
+  roadmap.md               ← full roadmap
   memory/
-    architecture.md        ← technical architecture notes
+    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 guidelines
+    design-system.md       ← UI/UX guide
   phases/
-    phase-01.md            ← phase plan + checklist
+    phase-01.md            ← plan + checklist for phase 1
     phase-02.md
   agents/
-    architect.md           ← Architect agent instructions
-    researcher.md
-    planner.md
-    coder.md
-    reviewer.md
-    teacher.md
-    git-agent.md
-    dashboard-agent.md
+    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 slash command
-    create-roadmap.md
-    initiate-phase.md
-    execute-phase.md
-    review-phase.md
-    humanize-code.md
-    explain-my-code.md
-    professor-check.md
-    checkpoint.md
-    debug-issue.md
-    design-system.md
-    generate-docs.md
-    generate-report.md
-    update-dashboard.md
+    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
+    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
+    index.html             ← visual dashboard (open in browser)
     style.css
     data.json
 AGENTS.md                  ← instructions for all AI agents
-CLAUDE.md                  ← Claude Code specific instructions
-GEMINI.md                  ← Gemini CLI specific instructions
-OPENAI.md                  ← OpenAI / Codex specific instructions
+CLAUDE.md                  ← Claude Code specific config
+GEMINI.md                  ← Gemini CLI specific config
+OPENAI.md                  ← OpenAI / Codex specific config
 ```
 
 ---
 
-## Code Level Engine
+## The Dashboard
 
-BrainForge adapts the generated and reviewed code to your target level:
+The dashboard is a static HTML file at `.brainforge/dashboard/index.html`.
 
-| Level | Description |
-|-------|-------------|
-| `beginner` | Simple, direct, few files, comments in French |
-| `intermediate` | Clean structure, reusable, good practices |
-| `academic-realistic` | Credible student code — clean but not enterprise-perfect, easy to explain |
-| `professional` | Strict typing, tests, security, scalable architecture |
+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 decisions
+- Git status
 
-The `academic-realistic` level is especially useful for school projects — it produces code that's professional enough to pass but natural enough to explain in an oral defense.
+To open it:
+
+```bash
+brainforge dashboard
+```
+
+To refresh its data:
+
+```bash
+brainforge update-dashboard
+```
 
 ---
 
-## Slash Commands Reference
+## Multi-AI Compatibility
 
-| Command | Purpose |
-|---------|---------|
-| `/start-project` | Document your idea, gather project info |
-| `/create-roadmap` | Break project into phases (Epic > Feature > Task) |
-| `/initiate-phase N` | Research + plan phase N before coding |
-| `/execute-phase N` | Implement phase N following the plan |
-| `/review-phase N` | Code review for quality and level-appropriateness |
-| `/humanize-code` | Adapt code to match the user's real level |
-| `/explain-my-code` | Generate an explanation for professors or teams |
-| `/professor-check` | Detect code that looks "too AI-generated" |
-| `/checkpoint` | Local git commit (never pushes) |
-| `/debug-issue` | Systematic bug analysis and fix |
-| `/design-system` | Create UI/UX design system |
-| `/generate-docs` | Generate README and docs/ |
-| `/generate-report` | Generate academic report template |
-| `/update-dashboard` | Refresh the HTML dashboard |
+BrainForge generates configuration 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 read and update
+- Git rules (never push)
 
 ---
 
-## Stack
+## Git Rules
+
+BrainForge manages git for you — safely:
 
-Built with:
+| Action | Allowed |
+|--------|---------|
+| `git init` | ✅ Auto on first init |
+| `git add` + `git commit` | ✅ Via `/checkpoint` |
+| `git push` | ❌ Never automatic |
+| `git push --force` | ❌ Never |
 
-- **Node.js** + **TypeScript**
-- **Commander.js** — CLI framework
-- **Inquirer** — interactive prompts
-- **Chalk** — terminal colors
-- **Ora** — spinners
-- **simple-git** — Git operations
-- **fs-extra** — file system utilities
+You always control when and where you push.
 
 ---
 
-## Development
+## Example Use Cases
 
+### School / PFA project
 ```bash
-# Install dependencies
-npm install
+npx brainforge-ai init
+# → choose "academic-realistic" code level
+# → choose "yes" for academic project
+# → follow workflow with /start-project → /create-roadmap → phases
+# → use /professor-check before submission
+# → use /generate-report for the written report
+```
 
-# Build TypeScript
-npm run build
+### Personal MVP
+```bash
+npx brainforge-ai init
+# → choose "intermediate" or "professional"
+# → define your stack and features during /start-project
+# → build phase by phase
+```
 
-# Run in dev mode (ts-node)
-npm run dev -- init
+### Learning a new stack
+```bash
+npx brainforge-ai init
+# → choose "beginner" or "intermediate"
+# → use /explain-my-code after each phase to understand what was built
+```
 
-# Link globally for local testing
-npm link
-brainforge init
+---
 
-# Unlink
-npm unlink
-```
+## Requirements
+
+- Node.js >= 16
+- Git (optional but recommended)
+- An AI tool: Claude Code, Cursor, Copilot, Gemini CLI, Codex…
 
 ---
 
-## Publishing to npm
+## Development
 
 ```bash
-# Make sure you're logged in
-npm login
-
-# Dry run to check what will be published
-npm publish --dry-run
+git clone https://github.com/MEHDImp4/brainforge-ai
+cd brainforge-ai
+npm install
+npm run build
+npm link
 
-# Publish
-npm publish
+# Test locally
+brainforge init
+brainforge doctor
 ```
 
 ---
 
-## Roadmap
+## Contributing
 
-- [ ] `brainforge checkpoint` — standalone git checkpoint command
-- [ ] `brainforge phase` — phase management (status, list, activate)
-- [ ] `brainforge memory` — view and search project memory
-- [ ] AI model integration for auto-generating roadmaps
-- [ ] Export report to PDF
-- [ ] VS Code extension
-- [ ] Web-based dashboard with live reload
+Issues and PRs welcome on [GitHub](https://github.com/MEHDImp4/brainforge-ai).
 
 ---
 
 ## License
 
-MIT — feel free to use, modify, and share.
+MIT — free to use, modify, and share.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainforge-ai",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "CLI to transform a vague idea into a structured, AI-assisted project with agents, slash commands, memory, and a live dashboard",
   "keywords": [
     "ai",
@@ -14,9 +14,9 @@
     "vibe-coding",
     "brainforge"
   ],
-  "homepage": "https://github.com/mehdidiouri17/brainforge-ai#readme",
+  "homepage": "https://github.com/MEHDImp4/brainforge-ai#readme",
   "bugs": {
-    "url": "https://github.com/mehdidiouri17/brainforge-ai/issues"
+    "url": "https://github.com/MEHDImp4/brainforge-ai/issues"
   },
   "license": "MIT",
   "author": "Mehdi Diouri <mehdidiouri17@gmail.com>",