Skip to content

MEHDImp4/brainforge-ai

BranchesTags

Repository files navigation

⚡ BrainForge AI

npm version CI License: MIT Node.js >= 16

BrainForge AI gives you GSD-like workflow discipline, but simplified for students, juniors, and developers who need to understand and defend their code.

Whether you are writing a school project, working as a junior developer, or building a personal app — BrainForge keeps your AI tool focused, structured, and produces code you can explain.

What is BrainForge AI?

BrainForge AI is a CLI that installs a structured workflow into any project directory. It gives your AI coding tool (Claude, Cursor, Copilot, Gemini, Codex…) everything it needs to plan before coding, respect your level, and stay focused on one task at a time.

It is not a clone of GSD. GSD is powerful and professional. BrainForge AI takes the same workflow discipline and applies it for students, juniors, and builders who need to understand and explain every line.

BrainForge AI = GSD-level discipline + student control + professor check + oral defense prep − the complexity

Why it exists

AI tools often cause the same recurring problems:

  • jumping straight into code without planning
  • generating code that is too complex or too perfect for the declared level
  • losing project context between sessions
  • producing code the student cannot defend in an oral exam
  • rewriting files that were not supposed to change

BrainForge solves this with a simple workflow: discuss → map → plan → build → verify → professor-check → defend.

How it differs from GSD

GSD BrainForge AI
Target audience Professional teams Students, juniors, solo builders
Setup complexity Advanced Simple — one init command
Code level control Not the focus Core feature — enforced at every step
Academic integrity check No Yes — professor-check and defend
Oral defense prep No Yes — defend generates DEFENSE.md
Agent infrastructure Heavy Minimal — slash commands + prompt templates
State files Rich structured system Simple Markdown files
Learning curve Steep Gentle

Installation

Use with npx (recommended, no install needed)

npx brainforge-ai init

Install globally

npm install -g brainforge-ai
brainforge init

brainforge-ai is the npm package name. brainforge is the CLI command.

Requirements: Node.js >= 16

Quick start

npx brainforge-ai init
brainforge discuss
brainforge map
brainforge plan "add authentication"
brainforge build
brainforge verify
brainforge professor-check
brainforge defend
brainforge dashboard

Academic workflow (student / school project)

This is the main workflow for academic projects.

# 1. Initialize BrainForge
brainforge init

# 2. Answer questions about your project and professor requirements
brainforge discuss

# 3. Scan your existing codebase (if you have one)
brainforge map

# 4. Plan a specific task
brainforge plan "add appointment management"

# 5. Get a ready-to-paste coding prompt for your AI tool
brainforge build

# → Paste the prompt into Claude, Cursor, Gemini, etc.
# → Implement the task
# → Come back to BrainForge when done

# 6. Check the implementation
brainforge verify

# 7. Run a professor-style review
brainforge professor-check

# 8. Prepare your oral defense
brainforge defend

# 9. Open the dashboard to see your project status
brainforge dashboard

Existing codebase workflow

If you are adding BrainForge to a project that already has code:

# 1. Initialize BrainForge (non-destructive, will not touch your code)
brainforge init

# 2. Set up your project context
brainforge discuss

# 3. Scan the codebase and generate CODEBASE_MAP.md
brainforge map

# 4. Plan your next task
brainforge plan "refactor the user module"

# 5. Get the coding prompt and paste into your AI tool
brainforge build

# 6. Verify the changes
brainforge verify

Commands

Command Description
init Initialize BrainForge — creates all workflow files and directories
discuss Answer questions to set up project context (PROJECT.md, STUDENT_LEVEL.md, PROFESSOR_RULES.md, STATE.md)
map Scan and map the codebase — generates CODEBASE_MAP.md and a /map-project AI prompt
plan <task> Create a focused implementation plan. Reads real file paths from CODEBASE_MAP.md first, uses semantic aliases (login→auth, register→user) before falling back to generic suggestions
build Generate a ready-to-paste coding prompt from the current task plan
verify Check your implementation: imports, complexity, violations, and undeclared package deps. Outputs SAFE_TO_CONTINUE, REVIEW_BEFORE_SUBMISSION, or MUST_FIX_BEFORE_SUBMISSION
professor-check Scan the codebase locally for advanced patterns (language-specific: Python, Java, PHP, Ruby, C#), suspicious style, large files. Writes .brainforge/PROFESSOR_CHECK.md
defend Generate an oral defense pack (DEFENSE.md) with questions, answers, and a checklist
dashboard Open the interactive project dashboard in the browser
serve Start a live dashboard server with auto-reload on localhost:3000
status Show a compact summary of the current project state
study Initialize Study Mode files for understanding the project
difficulty Generate a difficulty analysis workflow
defense-pack Generate a full oral defense preparation workflow (extended version)
simplify Generate a prompt to simplify code to match the project level
doctor Check BrainForge health and project status
update Update agents, commands, and templates without touching your data
guide Show all CLI and slash commands with project status

Generated files

When you run brainforge init, BrainForge creates:

my-project/
  .brainforge/
    PROJECT.md          ← project name, type, stack, features, constraints
    STATE.md            ← current phase, task, last verification, next action
    STUDENT_LEVEL.md    ← selected code level, rules, forbidden complexity
    PROFESSOR_RULES.md  ← what professor/client asked, allowed/forbidden tech
    CURRENT_TASK.md     ← goal, plan, what not to do (updated by brainforge plan)
    CODEBASE_MAP.md     ← codebase scan output (updated by brainforge map)
    VERIFY_REPORT.md    ← verification results (updated by brainforge verify)
    DEFENSE.md          ← oral defense pack (updated by brainforge defend)
    CHECKPOINTS/        ← checkpoint artifacts
    PROMPTS/            ← generated AI coding prompts
    brain.md            ← master context file for AI tools
    project.md          ← project spec (legacy format)
    roadmap.md          ← phase roadmap
    memory/             ← architecture, coding style, bugs, glossary…
    phases/             ← phase files
    agents/             ← AI agent instruction files
    commands/           ← slash command templates
    dashboard/          ← local HTML dashboard files
    reports/            ← generated reports
  .claude/
    skills/             ← 95+ expert skill files for Claude Code
  AGENTS.md
  CLAUDE.md
  GEMINI.md
  OPENAI.md

What each workflow file does

File Written by Purpose
PROJECT.md init, discuss Project name, type, stack, features, status
STATE.md init, discuss, verify Current phase, task, next action
STUDENT_LEVEL.md init, discuss Code level rules, forbidden patterns
PROFESSOR_RULES.md init, discuss Professor/client requirements and constraints
CODEBASE_MAP.md map Scanned structure, entry points, models, routes
CURRENT_TASK.md plan Task goal, implementation plan, what not to do
PROMPTS/build-current-task.md plan, build Ready-to-paste AI coding prompt
VERIFY_REPORT.md verify Errors, warnings, violations, final recommendation
PROFESSOR_CHECK.md professor-check Local scan report: risk level, score, suspicious patterns
DEFENSE.md defend Defense pack, questions, answers, checklist
PROMPTS/defend.md defend AI prompt for a richer file-by-file defense pack

BrainForge v2 source of truth vs legacy files

BrainForge v2 uses these files as the primary source of truth:

.brainforge/
  PROJECT.md           ← project context
  STATE.md             ← current phase, task, last verification, next action
  STUDENT_LEVEL.md     ← code level rules
  PROFESSOR_RULES.md   ← professor/client constraints
  CURRENT_TASK.md      ← active task plan (updated by brainforge plan)
  CODEBASE_MAP.md      ← scanned file tree (updated by brainforge map)
  VERIFY_REPORT.md     ← verification results (updated by brainforge verify)
  PROFESSOR_CHECK.md   ← local scan report (updated by brainforge professor-check)
  DEFENSE.md           ← oral defense pack (updated by brainforge defend)
  PROMPTS/             ← generated AI coding prompts

Legacy folders are kept for compatibility with older BrainForge workflows and AI tool prompts:

  brain.md, project.md, roadmap.md   ← legacy context files
  memory/                             ← legacy memory files
  phases/                             ← legacy phase files
  agents/                             ← AI agent instruction files
  commands/                           ← slash command templates
  reports/                            ← legacy report files

New commands write to v2 files. Legacy files are not deleted or modified by v2 commands.

Example: Java academic project

Scenario: second-year university project, Spring Boot + MySQL, oral defense in two weeks.

brainforge init
brainforge discuss
# → Project type: Academic
# → Stack: Java, Spring Boot, MySQL
# → Code level: academic-realistic
# → Comments: French
# → Professor asked: REST API with authentication, MVC pattern required
# → Forbidden: Spring Security (too advanced)
# → Report required: Yes
# → Oral defense: Yes

brainforge map
# → Scans the project, generates CODEBASE_MAP.md with MVC structure detected

brainforge plan "add patient management CRUD"
# → Detects likely files: PatientController, PatientService, Patient.java
# → Writes CURRENT_TASK.md with MVC implementation steps

brainforge build
# → Outputs prompt that tells the AI to respect the academic-realistic level,
#    add French comments, stay in MVC, and not rewrite unrelated files

# → Paste the prompt into Claude or Cursor → implement the feature

brainforge verify
# → Checks for broken imports, enterprise patterns (Singleton, Factory, DI containers),
#    forbidden technologies, large files

brainforge professor-check
# → Generates audit prompt: checks for AI-generated style, too-perfect code,
#    enterprise patterns a second-year student cannot justify

brainforge defend
# → Generates DEFENSE.md with Spring MVC explanation, possible questions
#    ("What is a controller?", "Why did you use a service layer?"),
#    simple answers, weak points, and a last-minute checklist

Example: Django school project

Scenario: Python web dev course, Django + SQLite, grade depends on oral questions.

brainforge init
brainforge discuss
# → Project type: Academic
# → Stack: Python, Django
# → Code level: beginner
# → Comments: French
# → Professor asked: CRUD web app with Django views and templates
# → Forbidden: Django REST Framework (not covered in course)

brainforge plan "add product catalog page"
# → Implementation plan: Model → View → Template → URL config
# → Warns not to use class-based views if declarerd beginner level

brainforge build
# → Prompt tells AI to use function-based views, Django ORM,
#    add French comments, keep templates simple

brainforge verify
# → Flags any import that does not resolve, any use of DRF or advanced patterns

brainforge defend
# → Generates Django-specific explanation: MTV architecture,
#    how models map to database tables, what a view does,
#    possible professor questions about ORM, template tags, migrations

Example: Personal / SaaS project

Scenario: building a side project with Node.js and React, intermediate level.

brainforge init
brainforge discuss
# → Project type: Personal
# → Stack: Node.js, Express, React, PostgreSQL
# → Code level: intermediate
# → No professor constraints

brainforge map
brainforge plan "add user authentication with JWT"
brainforge build

# → Paste prompt into Cursor or Claude Code
# → Implement authentication

brainforge verify
# → Checks auth route imports, flags suspiciously enterprise-level patterns,
#    counts TODO markers

brainforge dashboard
# → Visual overview of project state, phase progress, recent commits

AI tool compatibility

BrainForge generates context files and prompts that work with any AI coding tool:

  • Claude — Claude Code CLI, Claude Desktop, claude.ai
  • Cursor — paste prompts in Chat or Composer
  • GitHub Copilot — paste slash commands in Copilot Chat
  • ChatGPT / OpenAI — paste prompts in the chat
  • Gemini — paste prompts via Google AI Studio or IDE extension
  • Any tool that can read a markdown prompt

Included skills (95+)

BrainForge installs 95+ expert skill files to .claude/skills/ for Claude Code users. These guide AI behavior for specific stacks, frameworks, and tasks.

View all skills
Skill Skill Skill
database-queries security-review webapp-testing
react-best-practices next-best-practices web-performance
static-analysis sentry-monitoring github-workflow
postgres-best-practices cloudflare-workers stripe-integration
huggingface-ml figma-to-code seo-optimization
property-based-testing react-native-best-practices terraform-infrastructure
graphql-api docker-devops composio-connect
typescript-patterns tailwind-css api-design
authentication-oauth caching-redis websockets-realtime
file-uploads email-service rate-limiting
logging-observability environment-config monorepo
openai-integration supabase vercel-deployment
netlify-deployment sanity-cms web-scraping
better-auth accessibility internationalization
api-testing event-driven-arch deep-research
content-writing svelte-sveltekit vue-nuxt
angular-development error-handling ag-clean-code
ag-api-patterns ag-app-builder ag-architecture
ag-bash-linux ag-behavioral-modes ag-brainstorming
ag-code-review-checklist ag-database-design ag-deployment-procedures
ag-documentation-templates ag-frontend-design ag-game-development
ag-geo-fundamentals ag-intelligent-routing ag-lint-and-validate
ag-mcp-builder ag-mobile-design ag-nodejs-best-practices
ag-parallel-agents ag-performance-profiling ag-plan-writing
ag-powershell-windows ag-python-patterns ag-red-team-tactics
ag-rust-pro ag-server-management ag-systematic-debugging
ag-tailwind-v4 ag-tdd-workflow ag-testing-patterns
ag-vulnerability-scanner ag-web-design-guidelines design-taste-frontend
high-end-visual-design minimalist-ui industrial-brutalist-ui
stitch-design-taste image-to-code full-output-enforcement

Roadmap

  • Project memory system (.brainforge/ structure)
  • Phase-based workflow with slash commands
  • Live dashboard with phase tracking
  • Academic-realistic code level enforcement
  • discuss — interactive project context setup
  • plan — focused task planning with CURRENT_TASK.md
  • build — paste-ready AI coding prompt generation
  • verify — import checking, complexity detection, student-level validation
  • defend — oral defense pack with stack-aware questions and answers
  • CODEBASE_MAP.md — enriched map with entry points, models, routes
  • professor-check — real local codebase scan (no AI needed for the scan)
  • verify — SAFE_TO_CONTINUE / REVIEW_BEFORE_SUBMISSION / MUST_FIX recommendation
  • plan — uses real files from CODEBASE_MAP.md before falling back to generic suggestions
  • Dashboard v2 workflow status section
  • plan — semantic aliases (login→auth, register→user, payment→billing, refresh→jwt…)
  • professor-check — language-specific pattern detection (Python metaclasses, Java Spring, PHP traits, Ruby metaprogramming, C# async/LINQ)
  • verify — undeclared package import check against package.json
  • Dashboard — v2 file content embedded in data.json for offline file:// viewing
  • brainforge check-imports — stricter cross-file import resolution
  • Auto-update STATE.md phase on checkpoint
  • VS Code extension for dashboard and command palette
  • Multi-language support (French UI mode)

What BrainForge is not

  • It is not an AI model. It is a workflow framework that sits alongside your existing AI tools.
  • It is not an auto-coder. You prompt your AI — BrainForge makes those prompts structured and level-aware.
  • It is not GSD. GSD is for professional teams. BrainForge is for students, juniors, and solo builders.

License

MIT — see LICENSE.

About

Transform any idea into a structured, AI-assisted project

mehdimp4.github.io/brainforge-ai/

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

5 tags

Packages

 
 
 

Contributors

Languages