brainforge-ai

⚡ BrainForge AI

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.

This site is open source. Improve this page.