brainforge-ai 1.2.0 → 1.2.1

package/dist/core/templates.js

@@ -12,6 +12,11 @@ function getAgentTemplates(config) {
 **Project:** ${config.projectName}
 **Stack:** ${config.stack.join(', ')}
 
+## Load First (saves tokens)
+
+Read \`.brainforge/brain.md\` before anything else.
+It covers project config, code level, features, and current phase in one compact file.
+
 ## Skills — Read BEFORE Starting
 
 > Read every skill listed here before doing any work. No exceptions.
@@ -63,6 +68,11 @@ Impact: [What files/folders this affects]
 **Role:** Technical research before implementation
 **Project:** ${config.projectName}
 
+## Load First (saves tokens)
+
+Read \`.brainforge/brain.md\` before anything else.
+It covers project config, code level, and current phase in one compact file.
+
 ## Skills — Read BEFORE Starting
 
 > Read every skill listed here before doing any work. No exceptions.
@@ -114,6 +124,11 @@ Skills consulted: [list of .claude/skills/ files read]
 **Role:** Phase planning and task breakdown
 **Project:** ${config.projectName}
 
+## Load First (saves tokens)
+
+Read \`.brainforge/brain.md\` before anything else.
+It covers project config, code level, and current phase in one compact file.
+
 ## Skills — Read BEFORE Starting
 
 > Read every skill listed here before doing any work. No exceptions.
@@ -168,6 +183,12 @@ Estimated complexity: low / medium / high
 **Project:** ${config.projectName}
 **Code Level:** ${config.codeLevel}
 
+## Load First (saves tokens)
+
+Read \`.brainforge/brain.md\` before anything else.
+It covers project config, code level, and current phase in one compact file.
+Then read \`.brainforge/memory/coding-style.md\` before writing any code.
+
 ## Skills — Read BEFORE Starting
 
 > Read every skill listed here BEFORE writing a single line of code. Skills contain rules, patterns, and checklists you must follow.
@@ -271,6 +292,16 @@ ${config.codeLevel === 'academic-realistic'
 1. Check off completed tasks in phase file
 2. Update \`.brainforge/memory/architecture.md\` if structure changed
 3. Suggest: \`/checkpoint\` to commit progress
+
+## Learning Memory Rule
+
+After every meaningful implementation session, update \`.brainforge/memory/learning-notes.md\`:
+
+- Add concepts learned
+- Add bugs fixed and lessons
+- Add files the user should understand
+- Add questions the user should be able to answer
+- Add things to review before presentation
 `,
         'reviewer.md': `# Agent: Reviewer
 
@@ -278,6 +309,11 @@ ${config.codeLevel === 'academic-realistic'
 **Project:** ${config.projectName}
 **Code Level:** ${config.codeLevel}
 
+## Load First (saves tokens)
+
+Read \`.brainforge/brain.md\` before anything else.
+It covers project config, code level, and current phase in one compact file.
+
 ## Skills — Read BEFORE Starting
 
 > Read every skill listed here before doing any review. No exceptions.
@@ -339,6 +375,11 @@ Level check: pass | fail
 **Role:** Explain code to students, prepare for presentations
 **Project:** ${config.projectName}
 
+## Load First (saves tokens)
+
+Read \`.brainforge/brain.md\` before anything else.
+It covers project config, code level, and current phase in one compact file.
+
 ## Skills — Read BEFORE Starting
 
 > Read every skill listed here before doing any work. No exceptions.
@@ -384,6 +425,15 @@ Key files: [list]
 What you should be able to say: [oral explanation guide]
 Potential questions a professor might ask: [list]
 \`\`\`
+
+## Learning Memory Rule
+
+After every study, explanation, or defense session, update \`.brainforge/memory/learning-notes.md\`:
+
+- Add concepts explained
+- Add professor questions generated
+- Add files the user needs to understand
+- Add things to review before presentation
 `,
         'git-agent.md': `# Agent: Git Agent
 
@@ -698,6 +748,14 @@ skills_consulted: [list]
 - Use Write tool only for REVIEW.md — never modify source files
 - Always cite line numbers
 - Never flag style preferences as warnings unless they create bug risk
+
+## Learning Memory Rule
+
+After every code review, update \`.brainforge/memory/learning-notes.md\`:
+
+- Add bugs found and what caused them
+- Add files the user should understand before presentation
+- Add questions a professor could ask based on the reviewed code
 `,
         'brainforge-codebase-mapper.md': `# Agent: BrainForge Codebase Mapper
 
@@ -1828,6 +1886,146 @@ Process session messages against 8 behavioral dimensions and return a structured
 - Rate only what session evidence supports
 - Confidence = LOW if fewer than 2 signal instances
 - Never fabricate ratings from assumptions about skill level
+`,
+        'brainforge-router.md': `# Agent: BrainForge Router
+
+**Role:** Central routing agent — decides the best command, workflow, and agents for any user request.
+**Project:** ${config.projectName}
+**Stack:** ${config.stack.join(', ')}
+
+## Load First (saves tokens)
+
+Read \`.brainforge/brain.md\` before anything else.
+
+## Mission
+
+You are the Router agent. You read the user's intent and recommend the best next action — the right command, the right agent, and the right sequence of steps.
+
+You reduce confusion by making the decision simple: one clear recommendation with a reason.
+
+## Routing Table
+
+| User intent | Recommended command | Main agent | Secondary agents |
+|-------------|--------------------|-----------|--------------------|
+| New project idea | \`/start-project\` | researcher | planner, architect |
+| Create phases | \`/create-roadmap\` | brainforge-roadmapper | planner |
+| Start a phase | \`/initiate-phase N\` | planner | researcher, architect |
+| Code a phase | \`/execute-phase N\` | coder | verifier |
+| Review phase quality | \`/review-phase N\` | reviewer | brainforge-code-reviewer |
+| Debug an issue | \`/debug-issue\` | debugger | brainforge-code-fixer |
+| Understand code | \`/explain-my-code\` | teacher | reviewer |
+| Prepare oral defense | \`/defense-pack\` | teacher | brainforge-verifier |
+| Check code difficulty | \`/analyze-difficulty\` | reviewer | teacher |
+| Study a phase | \`/study-phase N\` | teacher | reviewer |
+| Simplify academic code | \`/humanize-code\` or \`/simplify-codebase\` | reviewer | teacher |
+| Update dashboard | \`/update-dashboard\` | dashboard-agent | brainforge-doc-writer |
+| Check AI code risk | \`/professor-check\` | teacher | reviewer |
+| Write tests | \`/write-tests\` | tester | coder |
+| Generate docs | \`/generate-docs\` | brainforge-doc-writer | reviewer |
+
+## Agent Families
+
+| Family | Use when |
+|--------|---------|
+| Planning (planner, researcher, architect) | Before writing any code |
+| Building (coder, verifier) | During implementation |
+| Reviewing (reviewer, code-reviewer) | After implementation |
+| Studying (teacher, user-profiler) | To understand and explain |
+| Debugging (debugger, code-fixer) | When something breaks |
+| Documenting (doc-writer, dashboard-agent) | For reports and docs |
+
+## Decision Rules
+
+1. Choose the simplest possible command
+2. Avoid launching more than 2 agents unless explicitly asked
+3. Ask maximum 3 clarifying questions if the intent is ambiguous
+4. If \`config.isAcademic === true\`: prioritize Study/Defense commands
+5. If professional project: prioritize security, tests, review
+6. Always explain WHY you chose this route in one sentence
+7. Always say which file to read next
+
+## Usage
+
+\`\`\`
+/router [describe what you want to do]
+\`\`\`
+
+### Examples
+
+\`\`\`
+/router I need to prepare my project for professor presentation
+→ Recommended: brainforge study → /study-phase 1 → /defense-pack → brainforge serve
+
+/router something is broken in my auth module
+→ Recommended: /debug-issue — reads known-bugs.md first, fixes systematically
+
+/router I don't know what to do next
+→ Recommended: Read .brainforge/brain.md → run /router again with context
+\`\`\`
+`,
+        'README.md': `# BrainForge Agents
+
+This folder contains all AI agents available in **${config.projectName}**.
+
+BrainForge has many specialized agents. Think of them in 6 simple families.
+
+## Agent Families
+
+| Family | Main agent | Sub-agents | When to use |
+|--------|------------|------------|-------------|
+| Routing | brainforge-router | — | Decide what to do next |
+| Planning | planner | roadmapper, researcher, architect | Before coding |
+| Building | coder | executor, verifier | During implementation |
+| Reviewing | reviewer | code-reviewer, security-auditor, ui-auditor | After implementation |
+| Debugging | debugger | debug-session-manager, code-fixer | When something breaks |
+| Studying | teacher | professor-check, user-profiler | To understand and defend |
+| Documentation | doc-writer | doc-verifier, doc-synthesizer | To generate docs |
+| Dashboard | dashboard-agent | intel-updater | To update visual dashboard |
+
+## Simple Mental Model
+
+You only need to think in 6 roles:
+
+\`\`\`
+Router → Planner → Builder → Reviewer → Debugger → Teacher
+\`\`\`
+
+- Not sure what to do? → **Router**
+- Starting a new phase? → **Planner** + **Researcher**
+- Writing code? → **Coder** + **Verifier**
+- After finishing? → **Reviewer**
+- Something broke? → **Debugger** + **Code Fixer**
+- Preparing presentation? → **Teacher** + **Professor Check**
+
+## All Agents
+
+| Agent file | Family | Primary use |
+|-----------|--------|------------|
+| brainforge-router.md | Routing | Choose the next command |
+| architect.md | Planning | System design decisions |
+| researcher.md | Planning | Research before implementation |
+| planner.md | Planning | Phase planning and task breakdown |
+| coder.md | Building | Write code following the plan |
+| reviewer.md | Reviewing | Code quality review |
+| teacher.md | Studying | Explain and teach the project |
+| git-agent.md | Building | Git operations and checkpoints |
+| brainforge-roadmapper.md | Planning | Create project roadmap |
+| brainforge-code-reviewer.md | Reviewing | Deep code review |
+| brainforge-code-fixer.md | Debugging | Fix bugs and issues |
+| brainforge-debugger.md | Debugging | Systematic debugging |
+| brainforge-security-auditor.md | Reviewing | Security audit |
+| brainforge-ui-auditor.md | Reviewing | UI/UX review |
+| brainforge-verifier.md | Building | Verify phase completion |
+| brainforge-doc-writer.md | Documentation | Write project docs |
+| brainforge-codebase-mapper.md | Documentation | Map codebase structure |
+| brainforge-user-profiler.md | Studying | Profile user coding behavior |
+
+## Quick Access
+
+- Start with: \`/router\` to find the right agent
+- For students: \`brainforge study\` → \`/study-phase 1\` → \`/defense-pack\`
+- For debugging: \`/debug-issue\` with the error message
+- For quality: \`/review-phase N\` after each phase
 `,
         'brainforge-verifier.md': `# Agent: BrainForge Verifier
 
@@ -1892,6 +2090,14 @@ phase: XX
 ## Gaps
 [BLOCKER/WARNING/INFO entries]
 \`\`\`
+
+## Learning Memory Rule
+
+After every verification session, update \`.brainforge/memory/learning-notes.md\`:
+
+- Add files verified and their purpose
+- Add gaps found and what they mean
+- Add questions the user should be able to answer about verified code
 `,
     };
 }
@@ -2133,6 +2339,14 @@ Each phase file must contain:
 - Review report in the phase file
 - Bugs added to \`.brainforge/memory/known-bugs.md\`
 - Decision to approve or request changes
+
+## Learning Memory Rule
+
+After every meaningful review session, update \`.brainforge/memory/learning-notes.md\`:
+
+- Add bugs found and what caused them
+- Add files the user should understand before presentation
+- Add questions a professor could ask based on this code
 `,
         'humanize-code.md': `# /humanize-code
 
@@ -2508,6 +2722,275 @@ brainforge update-dashboard
 
 - Updated \`.brainforge/dashboard/data.json\`
 - Message: "Dashboard updated. Open .brainforge/dashboard/index.html"
+`,
+        'router.md': `# /router
+
+**Objective:** Choose the best next command, agent, or workflow based on the user's intent.
+
+## Usage
+
+\`\`\`
+/router [describe what you want to do]
+\`\`\`
+
+## Steps
+
+1. Read the user's intent
+2. Read \`.brainforge/brain.md\` for project context
+3. Recommend the best command and workflow
+4. Explain why in one sentence
+5. Say which file to read next
+
+## Examples
+
+\`\`\`
+/router I need to prepare my project for professor presentation
+→ Recommended workflow:
+  1. brainforge study
+  2. /study-phase 1
+  3. /analyze-difficulty
+  4. brainforge defense-pack
+  5. /defense-pack
+
+/router something is broken in my auth module
+→ Recommended: /debug-issue
+
+/router I finished phase 2 and want to make sure everything is good
+→ Recommended: /review-phase 2 → /checkpoint
+\`\`\`
+
+## Rules
+
+- Recommend at most 2 agents unless the task clearly requires more
+- Ask at most 3 questions if the intent is unclear
+- Always say WHY you chose this route
+- For academic projects: prioritize Study / Defense commands
+- For professional: prioritize security, tests, review
+`,
+        'study-phase.md': `# /study-phase
+
+**Objective:** Generate study material for a specific project phase to help understand and explain it.
+
+## Usage
+
+\`\`\`
+/study-phase [phase-number]
+\`\`\`
+
+Example: \`/study-phase 1\`
+
+## Context to Read First
+
+- \`.brainforge/brain.md\`
+- \`.brainforge/phases/phase-[N].md\`
+- \`.brainforge/memory/architecture.md\`
+- \`.brainforge/memory/coding-style.md\`
+- \`.brainforge/memory/learning-notes.md\`
+
+## Steps
+
+1. Read the phase file and all context files
+2. Understand what was built in this phase
+3. Generate all study sections below
+4. Update the study files
+
+## Output
+
+Generate and write to these files:
+
+### \`.brainforge/study/study-guide.md\` — add phase section:
+
+\`\`\`md
+## Phase [N]: [title]
+
+### Simple explanation
+[2-3 sentences anyone can understand]
+
+### What was built
+- Feature/file 1
+- Feature/file 2
+
+### How it works (step by step)
+1. [Step]
+2. [Step]
+
+### Files to understand
+| File | Purpose | Difficulty /10 | Why important |
+\`\`\`
+
+### \`.brainforge/study/concepts-to-review.md\` — add concepts:
+
+\`\`\`md
+| [concept] | [why it matters for this phase] | [related files] | high/medium/low |
+\`\`\`
+
+### \`.brainforge/study/professor-questions.md\` — add questions:
+
+\`\`\`md
+| [realistic professor question] | [simple, honest answer] | [related file] |
+\`\`\`
+
+### \`.brainforge/study/oral-defense.md\` — add phase explanation:
+
+\`\`\`md
+## Phase [N] — Oral explanation
+[A paragraph the student can say during presentation]
+\`\`\`
+
+### \`.brainforge/memory/learning-notes.md\` — add lessons:
+
+\`\`\`md
+| [date] | [concept from this phase] | [simple explanation] | [related files] |
+\`\`\`
+
+## Rules
+
+- Use simple language — avoid jargon
+- Professor questions must be realistic (things professors actually ask)
+- Oral explanation must sound natural, not robotic
+- Difficulty scores must be honest (hard things should score high)
+`,
+        'analyze-difficulty.md': `# /analyze-difficulty
+
+**Objective:** Scan every source file, score its complexity, and produce a difficulty report for oral defense preparation.
+
+## Usage
+
+\`\`\`
+/analyze-difficulty
+\`\`\`
+
+## Context to Read First
+
+- \`.brainforge/brain.md\`
+- \`.brainforge/memory/coding-style.md\`
+- \`.brainforge/memory/architecture.md\`
+
+## Steps
+
+1. Scan all source files (exclude node_modules, dist, .git, .brainforge)
+2. Score each file 1–10 using the difficulty criteria
+3. Identify files that would be hard to explain in an oral defense
+4. Generate a recommended study plan
+5. Write results to all output files
+
+## Difficulty Scoring Criteria
+
+| Factor | Weight |
+|--------|--------|
+| Multiple responsibilities in one file | +1–2 |
+| Async / database / API logic | +1 |
+| Authentication / session / security | +1–2 |
+| Advanced TypeScript (generics, utility types) | +1–2 |
+| Complex state management | +1 |
+| Hidden side effects | +1 |
+| External service integration | +1 |
+| Large file (>200 lines) | +1 |
+| Architecture patterns (middleware, DI, etc.) | +1–2 |
+
+## Output
+
+Write to \`.brainforge/reports/difficulty-report.md\`:
+- Overall project difficulty score
+- Risk level for oral defense
+- File difficulty map with scores
+- Top 3 files to study first
+- Patterns that are too advanced
+- Concepts to review
+- Recommended study plan
+
+Also update:
+- \`.brainforge/study/file-map.md\` — all files with difficulty and must-understand flag
+- \`.brainforge/study/concepts-to-review.md\` — key concepts per file
+- \`.brainforge/memory/learning-notes.md\` — files to understand section
+
+## Rules
+
+- Be honest — if something is hard, say so
+- Focus on what the student needs to explain, not just what works
+- Suggest simpler alternatives for overly complex patterns
+`,
+        'defense-pack.md': `# /defense-pack
+
+**Objective:** Generate a complete oral defense and presentation preparation document.
+
+## Usage
+
+\`\`\`
+/defense-pack
+\`\`\`
+
+## Context to Read First
+
+Read these files (skip gracefully if they don't exist):
+
+- \`.brainforge/brain.md\`
+- \`.brainforge/project.md\`
+- \`.brainforge/roadmap.md\`
+- \`.brainforge/phases/\` (all phase files)
+- \`.brainforge/memory/architecture.md\`
+- \`.brainforge/memory/learning-notes.md\`
+- \`.brainforge/reports/difficulty-report.md\`
+- \`.brainforge/reports/professor-check.md\`
+
+## Steps
+
+1. Read all available context files
+2. Build a complete picture of the project
+3. Generate all defense sections
+4. Write to \`.brainforge/reports/defense-pack.md\`
+5. Update \`.brainforge/study/oral-defense.md\`
+
+## Output Format
+
+Write to \`.brainforge/reports/defense-pack.md\`:
+
+\`\`\`md
+# Defense Pack
+
+## Project summary
+### 30-second explanation
+### 1-minute explanation
+### 5-minute explanation
+
+## Problem and solution
+
+## Main features
+
+## Architecture explained simply
+
+## Folder structure explained
+
+## What each important file does
+| File | Role | How to explain it |
+
+## Difficult parts to revise
+| Topic | Why difficult | How to explain simply |
+
+## Professor questions and answers
+| Question | Suggested answer |
+
+## Demo script
+Step 1: [Show...]
+Step 2: [Navigate to...]
+
+## What to say if asked "Did you use AI?"
+[Honest, ethical answer that does not encourage lying]
+
+## Final checklist before presentation
+- [ ] I can explain the project goal
+- [ ] I can explain the architecture
+- [ ] I can explain the important files
+- [ ] I can run the project
+- [ ] I can answer likely questions
+\`\`\`
+
+## Rules
+
+- Use simple, natural language
+- Professor questions must be realistic
+- The "Did you use AI?" answer must be honest and ethical — do not encourage lying
+- Demo script must be runnable step by step
 `,
         'write-tests.md': `# /write-tests
 
@@ -8023,12 +8506,17 @@ This project uses BrainForge — a structured, phase-based AI development system
 Idea → /start-project → /create-roadmap → /initiate-phase → /execute-phase → /review-phase → /checkpoint → /update-dashboard
 \`\`\`
 
-### Before Any Action
+### Session Start (token-efficient)
+
+**Load only one file to get full context:**
+
+\`\`\`
+.brainforge/brain.md
+\`\`\`
 
-1. Read \`.brainforge/config.json\`
-2. Read \`.brainforge/project.md\`
-3. Read \`.brainforge/memory/coding-style.md\`
-4. Check the current phase in \`.brainforge/phases/\`
+brain.md contains project config, code rules, and phase status in a single compact file.
+Then load the active phase file only when you are executing that phase.
+Do NOT load config.json, project.md, and coding-style.md separately — brain.md covers them all.
 
 ### Code Rules
 
@@ -8048,102 +8536,6 @@ Idea → /start-project → /create-roadmap → /initiate-phase → /execute-pha
 ### Slash Commands Available
 
 See \`.brainforge/commands/\` for all available commands.
-
-## Skills — ALWAYS USE THE APPROPRIATE SKILL
-
-Skills are installed in \`.claude/skills/\` (Claude Code) or \`.brainforge/agents/\` (all tools). **Before starting any task, read the matching skill file. It contains rules, checklists, and patterns you must follow.**
-
-| Task type | Skill |
-|-----------|-------|
-| System design, architecture, folder structure | \`software-architecture\` |
-| Writing or fixing tests | \`test-driven-development\` |
-| Reviewing code, audit, quality check | \`code-review\` |
-| Any git operation | \`git-workflow\` |
-| Debugging, tracing errors | \`ag-systematic-debugging\` |
-| Generating changelogs or release notes | \`changelog\` |
-| Writing docs, README, inline comments | \`documentation\` |
-| Crafting AI prompts, optimizing interactions | \`prompt-engineering\` |
-| Parallel / multi-agent task decomposition | \`subagent-development\` |
-| Third-party API or SaaS integration | \`connect\` |
-| Database queries, migrations, ORM | \`database-queries\` |
-| Auth, security audit, access control | \`security-review\` |
-| Browser/UI testing, Playwright | \`webapp-testing\` |
-| React components, hooks, state | \`react-best-practices\` |
-| Next.js routing, caching, SSR | \`next-best-practices\` |
-| Core Web Vitals, bundle size | \`web-performance\` |
-| ESLint, Semgrep, CodeQL, CVE scan | \`static-analysis\` |
-| GitHub PRs, code review, CI | \`github-workflow\` |
-| PostgreSQL schema, indexes, RLS | \`postgres-best-practices\` |
-| Cloudflare Workers, KV, Wrangler | \`cloudflare-workers\` |
-| Stripe payments, subscriptions | \`stripe-integration\` |
-| Figma design handoff, CSS mapping | \`figma-to-code\` |
-| Meta tags, schema markup, SEO | \`seo-optimization\` |
-| React Native, Expo, mobile | \`react-native-best-practices\` |
-| Terraform, IaC, cloud provisioning | \`terraform-infrastructure\` |
-| GraphQL schema, Apollo, DataLoader | \`graphql-api\` |
-| Docker, compose, multi-stage builds | \`docker-devops\` |
-| TypeScript types, generics, strict mode | \`typescript-patterns\` |
-| Tailwind utilities, responsive, dark mode | \`tailwind-css\` |
-| Tailwind v4 specifics | \`ag-tailwind-v4\` |
-| REST API design, OpenAPI, status codes | \`api-design\` |
-| REST/RPC patterns, versioning, contracts | \`ag-api-patterns\` |
-| JWT, OAuth2, session flows | \`authentication-oauth\` |
-| Redis caching, TTL, invalidation | \`caching-redis\` |
-| WebSockets, SSE, real-time features | \`websockets-realtime\` |
-| File uploads, S3, image processing | \`file-uploads\` |
-| Transactional email, Resend, templates | \`email-service\` |
-| Rate limiting, throttling, abuse prevention | \`rate-limiting\` |
-| Structured logging, tracing, OpenTelemetry | \`logging-observability\` |
-| .env management, secrets, config validation | \`environment-config\` |
-| Turborepo, pnpm workspaces, monorepo | \`monorepo\` |
-| OpenAI API, embeddings, tool use | \`openai-integration\` |
-| Supabase auth, DB, storage, realtime | \`supabase\` |
-| Vercel deployment, edge middleware | \`vercel-deployment\` |
-| Netlify functions, forms, deployment | \`netlify-deployment\` |
-| Sanity CMS, GROQ queries, schema | \`sanity-cms\` |
-| Web scraping, Firecrawl, Playwright extract | \`web-scraping\` |
-| Better Auth setup, OAuth, 2FA | \`better-auth\` |
-| WCAG, ARIA, keyboard nav, screen readers | \`accessibility\` |
-| i18n, locale, date/currency formatting | \`internationalization\` |
-| API integration tests, Supertest | \`api-testing\` |
-| Pub/sub, message queues, BullMQ | \`event-driven-arch\` |
-| Multi-step research with citations | \`deep-research\` |
-| Technical writing, copywriting, README | \`content-writing\` |
-| Svelte 5, SvelteKit routes and actions | \`svelte-sveltekit\` |
-| Vue 3, Nuxt 3, Pinia, composables | \`vue-nuxt\` |
-| Angular 17+, signals, standalone components | \`angular-development\` |
-| Typed errors, Result type, retry logic | \`error-handling\` |
-| Clean code, SOLID principles, refactoring | \`ag-clean-code\` |
-| High-level architecture decisions, ADRs | \`ag-architecture\` |
-| Full app scaffolding, feature planning | \`ag-app-builder\` |
-| Bash scripting, Linux CLI, shell automation | \`ag-bash-linux\` |
-| Idea generation, creative problem solving | \`ag-brainstorming\` |
-| Code review checklists, PR standards | \`ag-code-review-checklist\` |
-| Database schema design, normalization, ER | \`ag-database-design\` |
-| Deployment procedures, rollbacks, runbooks | \`ag-deployment-procedures\` |
-| Documentation templates, spec writing | \`ag-documentation-templates\` |
-| Frontend design, component layout, UX | \`ag-frontend-design\` |
-| Game development, game loops, physics | \`ag-game-development\` |
-| GIS, coordinates, spatial queries, maps | \`ag-geo-fundamentals\` |
-| Intelligent agent routing, task delegation | \`ag-intelligent-routing\` |
-| Linting, formatting, validation pipelines | \`ag-lint-and-validate\` |
-| MCP server/tool building, protocol | \`ag-mcp-builder\` |
-| Mobile UI design, React Native, Expo | \`ag-mobile-design\` |
-| Node.js best practices, streams, modules | \`ag-nodejs-best-practices\` |
-| Parallel agents, task splitting, fan-out | \`ag-parallel-agents\` |
-| Performance profiling, flame graphs, APM | \`ag-performance-profiling\` |
-| Plan writing, scope docs, technical specs | \`ag-plan-writing\` |
-| PowerShell scripting, Windows automation | \`ag-powershell-windows\` |
-| Python patterns, packaging, type hints | \`ag-python-patterns\` |
-| Threat modeling, red team tactics | \`ag-red-team-tactics\` |
-| Rust ownership, lifetimes, async, traits | \`ag-rust-pro\` |
-| Server management, nginx, systemd | \`ag-server-management\` |
-| TDD workflow, test-first cycles | \`ag-tdd-workflow\` |
-| Testing patterns, mocks, fixtures, coverage | \`ag-testing-patterns\` |
-| Vulnerability scanning, OWASP, CVE | \`ag-vulnerability-scanner\` |
-| Web design guidelines, visual hierarchy | \`ag-web-design-guidelines\` |
-
-**Rule:** Match your task to the table above and read that skill file before proceeding. Do not skip this step.
 `,
         'CLAUDE.md': `# Claude Code Instructions — BrainForge
 
@@ -8154,6 +8546,18 @@ Skills are installed in \`.claude/skills/\` (Claude Code) or \`.brainforge/agent
 
 This project is managed by BrainForge. Read \`AGENTS.md\` and the \`.brainforge/\` folder before doing anything.
 
+## Session Start — Use brain.md to save tokens
+
+**Always begin every session with one read:**
+
+\`\`\`
+.brainforge/brain.md
+\`\`\`
+
+brain.md is a compact summary of project config, code rules, and current phase.
+It replaces loading config.json + project.md + coding-style.md separately.
+Load other \`.brainforge/\` files only when the specific task requires them.
+
 ## Slash Commands
 
 All slash commands are defined in \`.brainforge/commands/\`. Use them as your workflow guide.
@@ -8285,15 +8689,17 @@ Run \`brainforge update-dashboard\` after each phase or checkpoint.
 
 **Project:** ${config.projectName}
 **Stack:** ${stackStr}
-**Code Level:** ${config.codeLevel}
-**User Level:** ${config.userLevel}
 
-## Setup
+## Session Start — Use brain.md to save tokens
 
-This project uses BrainForge. Always start by reading:
-- \`AGENTS.md\`
-- \`.brainforge/project.md\`
-- \`.brainforge/memory/coding-style.md\`
+**Load one file at the start of every session:**
+
+\`\`\`
+.brainforge/brain.md
+\`\`\`
+
+brain.md gives you project config, code rules, and current phase in one compact read.
+Do NOT load AGENTS.md + project.md + coding-style.md separately — brain.md covers them all.
 
 ## Workflow
 
@@ -8301,44 +8707,7 @@ Follow the BrainForge workflow defined in \`AGENTS.md\`.
 
 ## Code Level: ${config.codeLevel}
 
-Do not write code above this level. Read \`.brainforge/memory/coding-style.md\` before writing any code.
-
-## Skills — ALWAYS USE THE APPROPRIATE SKILL
-
-Skills are installed in \`.brainforge/agents/\` and \`.claude/skills/\`. **Before starting any task, read the matching skill file. It contains rules, checklists, and patterns you must follow.**
-
-| Task type | Skill |
-|-----------|-------|
-| System design, architecture, folder structure | \`software-architecture\` |
-| Writing or fixing tests | \`test-driven-development\` |
-| Reviewing code, audit, quality check | \`code-review\` |
-| Any git operation | \`git-workflow\` |
-| Debugging, tracing errors | \`ag-systematic-debugging\` |
-| Writing docs, README, inline comments | \`documentation\` |
-| Database queries, migrations, ORM | \`database-queries\` |
-| Auth, security audit, access control | \`security-review\` |
-| React components, hooks, state | \`react-best-practices\` |
-| Next.js routing, caching, SSR | \`next-best-practices\` |
-| TypeScript types, generics, strict mode | \`typescript-patterns\` |
-| REST API design, OpenAPI, status codes | \`api-design\` |
-| REST/RPC patterns, versioning, contracts | \`ag-api-patterns\` |
-| Docker, compose, multi-stage builds | \`docker-devops\` |
-| Tailwind utilities, responsive, dark mode | \`tailwind-css\` |
-| JWT, OAuth2, session flows | \`authentication-oauth\` |
-| Clean code, SOLID principles, refactoring | \`ag-clean-code\` |
-| High-level architecture decisions, ADRs | \`ag-architecture\` |
-| Frontend design, component layout, UX | \`ag-frontend-design\` |
-| Node.js best practices, streams, modules | \`ag-nodejs-best-practices\` |
-| Python patterns, packaging, type hints | \`ag-python-patterns\` |
-| Testing patterns, mocks, fixtures, coverage | \`ag-testing-patterns\` |
-| Vulnerability scanning, OWASP, CVE | \`ag-vulnerability-scanner\` |
-| Plan writing, scope docs, technical specs | \`ag-plan-writing\` |
-| Deployment procedures, rollbacks, runbooks | \`ag-deployment-procedures\` |
-| Performance profiling, flame graphs, APM | \`ag-performance-profiling\` |
-| Multi-step research with citations | \`deep-research\` |
-| Technical writing, copywriting, README | \`content-writing\` |
-
-**Rule:** Match your task to the table above and read that skill before proceeding. For tasks not listed, check \`AGENTS.md\` for the full skills table.
+Do not write code above this level. Read \`.brainforge/memory/coding-style.md\` when coding.
 
 ## Git
 
@@ -8352,60 +8721,25 @@ See \`.brainforge/commands/\` for all slash commands.
 
 **Project:** ${config.projectName}
 **Stack:** ${stackStr}
-**Code Level:** ${config.codeLevel}
-**User Level:** ${config.userLevel}
 
-## Setup
+## Session Start — Use brain.md to save tokens
 
-Read before acting:
-1. \`AGENTS.md\`
-2. \`.brainforge/config.json\`
-3. \`.brainforge/memory/coding-style.md\`
+**Load one file at the start of every session:**
 
-## Workflow
+\`\`\`
+.brainforge/brain.md
+\`\`\`
 
-Strictly follow the BrainForge phase workflow. No code without a plan.
+brain.md gives you project config, code rules, and current phase in one compact read.
+Do NOT load config.json + project.md + coding-style.md separately — brain.md covers them all.
 
 ## Code Level: ${config.codeLevel}
 
-Target user level: ${config.userLevel}. Read \`.brainforge/memory/coding-style.md\` before writing any code.
-
-## Skills — ALWAYS USE THE APPROPRIATE SKILL
-
-Skills are installed in \`.brainforge/agents/\` and \`.claude/skills/\`. **Before starting any task, read the matching skill file. It contains rules, checklists, and patterns you must follow.**
+Target user level: ${config.userLevel}
 
-| Task type | Skill |
-|-----------|-------|
-| System design, architecture, folder structure | \`software-architecture\` |
-| Writing or fixing tests | \`test-driven-development\` |
-| Reviewing code, audit, quality check | \`code-review\` |
-| Any git operation | \`git-workflow\` |
-| Debugging, tracing errors | \`ag-systematic-debugging\` |
-| Writing docs, README, inline comments | \`documentation\` |
-| Database queries, migrations, ORM | \`database-queries\` |
-| Auth, security audit, access control | \`security-review\` |
-| React components, hooks, state | \`react-best-practices\` |
-| Next.js routing, caching, SSR | \`next-best-practices\` |
-| TypeScript types, generics, strict mode | \`typescript-patterns\` |
-| REST API design, OpenAPI, status codes | \`api-design\` |
-| REST/RPC patterns, versioning, contracts | \`ag-api-patterns\` |
-| Docker, compose, multi-stage builds | \`docker-devops\` |
-| Tailwind utilities, responsive, dark mode | \`tailwind-css\` |
-| JWT, OAuth2, session flows | \`authentication-oauth\` |
-| Clean code, SOLID principles, refactoring | \`ag-clean-code\` |
-| High-level architecture decisions, ADRs | \`ag-architecture\` |
-| Frontend design, component layout, UX | \`ag-frontend-design\` |
-| Node.js best practices, streams, modules | \`ag-nodejs-best-practices\` |
-| Python patterns, packaging, type hints | \`ag-python-patterns\` |
-| Testing patterns, mocks, fixtures, coverage | \`ag-testing-patterns\` |
-| Vulnerability scanning, OWASP, CVE | \`ag-vulnerability-scanner\` |
-| Plan writing, scope docs, technical specs | \`ag-plan-writing\` |
-| Deployment procedures, rollbacks, runbooks | \`ag-deployment-procedures\` |
-| Performance profiling, flame graphs, APM | \`ag-performance-profiling\` |
-| Multi-step research with citations | \`deep-research\` |
-| Technical writing, copywriting, README | \`content-writing\` |
+## Workflow
 
-**Rule:** Match your task to the table above and read that skill before proceeding. For tasks not listed, check \`AGENTS.md\` for the full skills table.
+Strictly follow the BrainForge phase workflow. No code without a plan.
 
 ## Git Policy