dev-booster 1.5.0 → 1.7.0

package/README.md

@@ -23,6 +23,7 @@ Unlike generic agent folders, **Dev Booster** uses a manual, activation-first mo
 - most boosters use lazy loading instead of loading the full kit immediately
 - context is pulled only when the task, artifact, or pain point actually requires it
 - each booster has a distinct operational role, instead of behaving like a generic prompt blob
+- many boosters act as continuous document generators (Artifact Engine), maintaining structured state files in the background to prevent context loss during long conversations
 
 This gives the kit a stronger product identity and helps avoid unnecessary context bloat.
 
@@ -31,20 +32,36 @@ After running the command, your project gets:
 ```
 .devbooster/
 ├── MANIFEST.md          ← inventory of all agents, skills, and boosters
-├── boosters/            ← 25 expert activators (debug, review, design, deploy...)
+├── boosters/            ← 26 expert activators (debug, review, design, deploy...)
 ├── hub/                 ← 40+ skills and operational scripts
 └── rules/
     ├── PROTOCOL.md      ← governance and conduct rules
     ├── PROJECT.md       ← whitelabel → auto-fills with your architecture
     ├── FRONTEND.md      ← whitelabel → auto-fills with your frontend stack
     ├── BACKEND.md       ← whitelabel → auto-fills with your backend stack
-    ├── COMERCIAL.md     ← whitelabel → auto-fills with your business model
+    ├── COMMERCIAL.md     ← whitelabel → auto-fills with your business model
     └── USER_PREFERENCES.md
 DEVBOOSTER_INIT.md                  ← bootstrap orchestrator (read below)
 ```
 
 ---
 
+## Safe Testing (`--dry-run`)
+
+If you want to see exactly what Dev Booster will install or update in your project without actually making any changes, you can use the `--dry-run` flag:
+
+```bash
+npx dev-booster --dry-run
+```
+For updates:
+```bash
+npx dev-booster update --dry-run
+```
+
+This will run a full simulation of the command and print a detailed report of which files would be created, updated, or preserved, giving you complete peace of mind before executing the real installation.
+
+---
+
 ## Bootstrap: DEVBOOSTER_INIT.md
 
 After installation, open your AI assistant and say:
@@ -92,7 +109,8 @@ Boosters are expert activators you invoke manually during development.
 | `internal-documentation.md` | Internal project map with absolute paths, files, assets, scripts, and edit boundaries |
 | `discovery.md` | Product brainstorm |
 | `performance.md` | Core Web Vitals / bundle issues |
-| + 13 more | See `.devbooster/MANIFEST.md` |
+| `code-audit.md` | Strict Code Auditor (Syntax, React Doctor) before PR |
+| + 14 more | See `.devbooster/MANIFEST.md` |
 
 The practical activation flow is simple:
 - drag a booster file into the chat
@@ -106,11 +124,42 @@ Many boosters now use a two-step flow:
 
 ---
 
+## The Artifact Engine
+
+Dev Booster operates an internal **Artifact Engine** (Shadow Memory). As boosters execute, they automatically generate and update machine-readable `.md` files in the background to track history, audits, and architectural decisions. 
+
+This creates a persistent "paper trail" that ensures the AI never loses context, even if you continue the work in a brand new chat session.
+
+Files are systematically organized in the `@booster-generated/` root directory:
+- `@booster-generated/contexts/` (Continuous save state for conversation continuity)
+- `@booster-generated/plans/` (Implementation roadmaps and risk mapping)
+- `@booster-generated/troubleshooting/` (Systematic RCA and bug fix logs)
+- `@booster-generated/audits/` (Security, accessibility, and performance reports)
+
+### Manual Triggers
+
+While the AI updates these files automatically, you can also take manual control at any time using explicit Chat Triggers:
+
+- **`@SaveState`**: Forces the AI to instantly summarize the current conversation context and update the active booster's state file. Perfect for explicitly bookmarking complex decisions before continuing in a fresh chat.
+- **`@SavePattern`**: Instructs the AI to extract a newly resolved technical rule or code pattern and persist it to `.devbooster/rules/USER_PREFERENCES.md`.
+- **`@LogTask`**: Tells the AI to capture a pending technical task mentioned in the chat and document it systematically in your operational backlog at `@booster-generated/tasks.md`.
+
+---
+
 ## Smart Usage Patterns
 
 One of the main strengths of Dev Booster is that boosters can be used in sequence, not just in isolation.
 
-### 1. Investigate before implementation
+### 1. Use Advisor when you are unsure
+
+If you do not know which booster should come first:
+1. activate `advisor.md`
+2. describe the task in one message
+3. let it recommend the smallest effective booster path
+
+The advisor recommends boosters only, keeping the path clean and focused.
+
+### 2. Investigate before implementation
 
 Use this when the repository is complex and you do not want the AI to jump straight into coding.
 
@@ -126,7 +175,7 @@ What this gives you:
 - the right implementation template (`simple`, `standard`, or `heavy`)
 - a stronger validation pass at the end
 
-### 2. Product idea to executable plan
+### 3. Product idea to executable plan
 
 Use this when the idea is still being shaped.
 
@@ -140,7 +189,7 @@ What this gives you:
 - clarification of business rules and gaps
 - a structured path into execution only after the context is mature
 
-### 3. Mature context to global technical documentation
+### 4. Mature context to global technical documentation
 
 Use this after discovery or investigation has already produced enough context.
 
@@ -155,7 +204,7 @@ What this gives you:
 
 For repository-specific internal maps with absolute paths, use `internal-documentation.md` instead of `global-documentation.md`.
 
-### 4. Safe review in a fresh chat
+### 5. Safe review in a fresh chat
 
 Use this when you want a stronger validation pass with minimal prior bias.
 
@@ -169,7 +218,7 @@ What this gives you:
 - artifact-first review
 - skill/persona loading only after the review target is provided
 
-### 5. Release note generation from real Git state
+### 6. Release note generation from real Git state
 
 Use this when you want changelogs based on what actually changed, not on memory.
 
@@ -186,7 +235,7 @@ What this gives you:
   - `C` = technical
 - always includes changed files and changed lines
 
-### 6. Domain mode plus execution mode
+### 7. Domain mode plus execution mode
 
 Boosters can also be combined by role.
 
@@ -199,15 +248,6 @@ This works well when:
 - you know the task belongs to a domain
 - but you still want alignment and execution discipline before building
 
-### 7. Use Advisor when you are unsure
-
-If you do not know which booster should come first:
-1. activate `advisor.md`
-2. describe the task in one message
-3. let it recommend the smallest effective booster path
-
-The advisor recommends boosters only, keeping the path clean and focused.
-
 ---
 
 ## Requirements

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-booster",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Reusable AI development kit with manual boosters, governance, and project bootstrap",
   "type": "module",
   "scripts": {

package/src/index.js

@@ -72,21 +72,27 @@ function isUpdateMode() {
   return args.includes('--update') || args.includes('update')
 }
 
+function isDryRunMode() {
+  return args.includes('--dry-run') || args.includes('dry-run')
+}
+
 function ensureTrailingNewline(content) {
   return content.endsWith('\n') ? content : `${content}\n`
 }
 
-function appendUniqueBlock(filePath, blockLines, marker) {
+function appendUniqueBlock(filePath, blockLines, marker, dryRun = false) {
   const existing = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : ''
   if (existing.includes(marker)) {
     return false
   }
 
-  const trimmedEnd = existing.replace(/\s*$/, '')
-  const prefix = trimmedEnd.length > 0 ? `${trimmedEnd}\n\n` : ''
-  const nextContent = `${prefix}${blockLines.join('\n')}\n`
-  fs.mkdirSync(path.dirname(filePath), { recursive: true })
-  fs.writeFileSync(filePath, nextContent)
+  if (!dryRun) {
+    const trimmedEnd = existing.replace(/\s*$/, '')
+    const prefix = trimmedEnd.length > 0 ? `${trimmedEnd}\n\n` : ''
+    const nextContent = `${prefix}${blockLines.join('\n')}\n`
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, nextContent)
+  }
   return true
 }
 
@@ -113,7 +119,7 @@ async function askYesNo(question, defaultYes = true) {
   }
 }
 
-async function maybeAddDevBoosterToGitignore() {
+async function maybeAddDevBoosterToGitignore(dryRun) {
   const shouldIgnore = await askYesNo('Add Dev Booster to your .gitignore?', true)
 
   if (!shouldIgnore) {
@@ -123,11 +129,11 @@ async function maybeAddDevBoosterToGitignore() {
   }
 
   const gitignorePath = path.join(TARGET_DIR, '.gitignore')
-  const changed = appendUniqueBlock(gitignorePath, GITIGNORE_BLOCK, GITIGNORE_MARKER)
+  const changed = appendUniqueBlock(gitignorePath, GITIGNORE_BLOCK, GITIGNORE_MARKER, dryRun)
 
   console.log('▸ .gitignore')
   if (changed) {
-    console.log('  status: updated')
+    console.log(`  status: ${dryRun ? 'would be updated' : 'updated'}`)
     console.log('  entries: # DEV-BOOSTER, .devbooster/, DEVBOOSTER_INIT.md\n')
   } else {
     console.log('  status: already configured')
@@ -148,28 +154,28 @@ function clearIdeBridgeFallbackFlag() {
   }
 }
 
-function setupIdeBridgeFiles() {
+function setupIdeBridgeFiles(dryRun) {
   const touchedFiles = []
 
   for (const relativeTarget of IDE_BRIDGE_TARGETS) {
     const targetPath = path.join(TARGET_DIR, relativeTarget)
     if (!fs.existsSync(targetPath)) continue
 
-    appendUniqueBlock(targetPath, IDE_BRIDGE_BLOCK, IDE_BRIDGE_MARKER)
-    touchedFiles.push(relativeTarget)
+    const wouldChange = appendUniqueBlock(targetPath, IDE_BRIDGE_BLOCK, IDE_BRIDGE_MARKER, dryRun)
+    if (wouldChange) touchedFiles.push(relativeTarget)
   }
 
   console.log('▸ IDE bridge files')
   if (touchedFiles.length > 0) {
-    clearIdeBridgeFallbackFlag()
-    console.log('  status: bridge instructions appended where applicable')
+    if (!dryRun) clearIdeBridgeFallbackFlag()
+    console.log(`  status: bridge instructions ${dryRun ? 'would be appended' : 'appended'} where applicable`)
     console.log(`  files: ${touchedFiles.join(', ')}\n`)
     return
   }
 
-  writeIdeBridgeFallbackFlag()
+  if (!dryRun) writeIdeBridgeFallbackFlag()
   console.log('  status: no known IDE instruction file found')
-  console.log('  action: bootstrap fallback flag created for DEVBOOSTER_INIT.md\n')
+  console.log(`  action: bootstrap fallback flag ${dryRun ? 'would be created' : 'created'} for DEVBOOSTER_INIT.md\n`)
 }
 
 function printHeader(subtitle) {
@@ -182,7 +188,9 @@ function printHeader(subtitle) {
 }
 
 async function runInstall() {
+  const dryRun = isDryRunMode()
   printHeader('agentic kit installer')
+  if (dryRun) console.log('🔍 [DRY RUN MODE] No real changes will be made.\n')
 
   // 1. Copy the full .devbooster/ kit to the user's project
   const agentSrc = path.join(TEMPLATE_DIR, '.devbooster')
@@ -194,9 +202,9 @@ async function runInstall() {
     console.log('  action: copy skipped to avoid overwrite')
     console.log('  tip: rename or remove the folder if you want a fresh install\n')
   } else {
-    copyDir(agentSrc, agentDest)
+    if (!dryRun) copyDir(agentSrc, agentDest)
     console.log('▸ .devbooster/')
-    console.log('  status: installed successfully\n')
+    console.log(`  status: ${dryRun ? 'would be installed' : 'installed successfully'}\n`)
   }
 
   // 2. Drop DEVBOOSTER_INIT.md at the root of the user's project
@@ -208,13 +216,13 @@ async function runInstall() {
     console.log('  status: already exists in this project')
     console.log('  action: creation skipped\n')
   } else {
-    fs.copyFileSync(initSrc, initDest)
+    if (!dryRun) fs.copyFileSync(initSrc, initDest)
     console.log('▸ DEVBOOSTER_INIT.md')
-    console.log('  status: created at project root\n')
+    console.log(`  status: ${dryRun ? 'would be created' : 'created'} at project root\n`)
   }
 
-  await maybeAddDevBoosterToGitignore()
-  setupIdeBridgeFiles()
+  await maybeAddDevBoosterToGitignore(dryRun)
+  setupIdeBridgeFiles(dryRun)
 
   console.log(`
 ╭──────────────────────────────────────────────╮
@@ -230,7 +238,9 @@ The kit will configure itself based on your project's stack.
 }
 
 function runUpdate() {
+  const dryRun = isDryRunMode()
   printHeader('safe kit update')
+  if (dryRun) console.log('🔍 [DRY RUN MODE] No real changes will be made.\n')
 
   const kitRoot = path.join(TARGET_DIR, '.devbooster')
   const templateRoot = path.join(TEMPLATE_DIR, '.devbooster')
@@ -247,16 +257,31 @@ function runUpdate() {
     { name: 'hub', src: path.join(templateRoot, 'hub'), dest: path.join(kitRoot, 'hub') },
   ]
 
+  const coreFiles = [
+    { name: 'MANIFEST.md', src: path.join(templateRoot, 'MANIFEST.md'), dest: path.join(kitRoot, 'MANIFEST.md') },
+    { name: 'rules/GUIDE.md', src: path.join(templateRoot, 'rules', 'GUIDE.md'), dest: path.join(kitRoot, 'rules', 'GUIDE.md') },
+    { name: 'rules/PROTOCOL.md', src: path.join(templateRoot, 'rules', 'PROTOCOL.md'), dest: path.join(kitRoot, 'rules', 'PROTOCOL.md') },
+  ]
+
   for (const target of updateTargets) {
-    syncDir(target.src, target.dest)
+    if (!dryRun) syncDir(target.src, target.dest)
     console.log(`▸ .devbooster/${target.name}/`)
-    console.log('  status: updated successfully')
+    console.log(`  status: ${dryRun ? 'would be updated' : 'updated successfully'}`)
+  }
+
+  for (const file of coreFiles) {
+    if (!dryRun && fs.existsSync(file.src)) {
+      fs.mkdirSync(path.dirname(file.dest), { recursive: true })
+      fs.copyFileSync(file.src, file.dest)
+    }
+    console.log(`▸ .devbooster/${file.name}`)
+    console.log(`  status: ${dryRun ? 'would be updated' : 'updated successfully'}`)
   }
 
   console.log('')
-  console.log('▸ rules/')
+  console.log('▸ rules/ (Whitelabel files)')
   console.log('  status: preserved')
-  console.log('  action: no local files were overwritten')
+  console.log('  action: user-customized rules were not overwritten')
   console.log('')
   console.log('▸ DEVBOOSTER_INIT.md')
   console.log('  status: preserved')

package/template/.devbooster/MANIFEST.md

@@ -109,7 +109,8 @@
 | `internal-documentation.md` | Generates repository-specific internal documentation with absolute paths and file/asset maps. |
 | `atomic.md` | Surgical, single-step implementation spec (final execution stage). |
 | `advisor.md` | Hub Consultant — recommends the best booster path for the user's task. |
-| `review.md` | Elite Auditor — multi-agent orchestration for plan validation. |
+| `review.md` | Elite Auditor — multi-agent orchestration for plan and architecture validation. |
+| `code-audit.md` | Strict Code Auditor — syntax, linting, and React Doctor diagnostics for the codebase. |
 | `debug.md` | Systematic Root Cause Analysis with hypothesis engine. |
 | `discovery.md` | Strategic Product Consultant — 3-path brainstorm protocol. |
 | `investigation.md` | Context Pre-Orchestrator — no-code analysis before implementation. |
@@ -177,3 +178,24 @@ When the user asks "How can the kit help?", the Advisor MUST:
 1. Scan requirements.
 2. Recommend the best **Booster** entry point for the task.
 3. Suggest supporting boosters only when the task clearly spans multiple phases or domains.
+
+---
+
+## 📂 7. ARTIFACT ENGINE (SHADOW MEMORY)
+Dev Booster acts as a continuous document generator. As boosters execute, they MUST write their history, findings, audits, and implementation plans into a structured, machine-readable format. This avoids context loss in long AI conversations and builds a tangible paper trail for the developer.
+
+**Target Root Path:** `@booster-generated/`
+
+### Artifact Mapping by Domain:
+- `@booster-generated/contexts/` → Managed by `context.md` (Save State for conversation continuity).
+- `@booster-generated/plans/` → Managed by `planning.md` (Implementation roadmap and risk mapping).
+- `@booster-generated/implementations/` → Managed by `frontend.md`, `backend.md`, `mobile.md`, `atomic.md`.
+- `@booster-generated/advisory/` → Managed by `advisor.md` (Architectural decisions and mentorship notes).
+- `@booster-generated/discoveries/` → Managed by `investigation.md`, `discovery.md` (Brainstorms, flow mapping).
+- `@booster-generated/troubleshooting/` → Managed by `debug.md` (Root Cause Analysis and bug fixes).
+- `@booster-generated/audits/` → Managed by `security.md`, `performance.md`, `accessibility.md`, `seo.md`.
+- `@booster-generated/reviews/` → Managed by `review.md` (Code review feedback, React Doctor JSON diagnostics).
+- `@booster-generated/changelogs/` → Managed by `changelog.md` (Release notes drafts).
+- `@booster-generated/rollouts/` → Managed by `deploy.md` (Pre-flight checks and deployment history).
+
+When a booster mandates `ARTIFACT GENERATION & STATE BACKUP`, the AI MUST respect this mapping and maintain the `.md` file continuously in the background.

package/template/.devbooster/boosters/advisor.md

@@ -65,4 +65,9 @@ Analyze the user's request or the current task and recommend only the best boost
 - Do NOT expose skills, personas, or agents in the user-facing answer.
 - Do NOT execute any plan, only advise.
 
+## ARTIFACT GENERATION & STATE BACKUP
+During your execution, you MUST create or update a machine-readable state file at `@booster-generated/advisory/<slug-name>.md`. 
+This file must continuously track the history, decisions, rules, and outcomes related to this booster's execution in a dense, non-conversational format.
+You must update this file silently in the background as the context evolves or when explicitly commanded by the user.
+
 **Reply:** On activation only, use the armed-mode banner above, always following the global language configured for the active LLM/environment. When the user shares an idea or task, read the manifest, classify the need, and recommend the best booster path without executing it.

package/template/.devbooster/boosters/code-audit.md

@@ -0,0 +1,83 @@
+# 🧹 BOOSTER: CODE AUDIT (QUALITY & SYNTAX)
+You are the Strict Code Auditor. Your mission is to scan, validate, and clean the codebase syntax and project standards before it is shipped or merged.
+
+## 0. DEV BOOSTER ACTIVATION CONTRACT
+This booster behaves as a code quality inspection mode, not as an execution or logical architecture review.
+
+If the user invokes this booster alone, or uses it only to activate the mode:
+- Do NOT start auditing immediately.
+- **CRITICAL PRE-FLIGHT CHECK**: Immediately check `git diff --name-only` to see if there are uncommitted changes.
+- Inform the user if the working tree has uncommitted changes or if it is clean.
+- Explicitly ask: "How many commits back do you want to analyze for this audit?"
+- **PAUSE EXECUTION**: You MUST wait for the user to provide a number (e.g., 0, 1, 2) before proceeding.
+- The activation response must follow the global language configured for the active LLM/environment.
+
+Use this activation response format:
+
+```md
+## 🤖 [DEV BOOSTER // CODE AUDIT]
+
+[Localized mode label]: Code Audit
+[Localized status label]: Awaiting Git Scope
+
+[Localized text reporting the current git diff state]
+[Localized question asking how many commits back to analyze]
+```
+
+Formatting rules for this activation:
+- `Mode` and `Status` must always be rendered on separate lines.
+- Do NOT merge labels into a single sentence or paragraph.
+- Keep each activation block on its own line.
+
+Only switch to execution mode after the user provides the commit scope.
+
+## 1. ALLOWED INVENTORY
+- **Deep Context & Local Rules (Highest Priority):**
+  - `.devbooster/rules/FRONTEND.md` (If applicable)
+  - `.devbooster/rules/BACKEND.md` (If applicable)
+  - `.devbooster/rules/USER_PREFERENCES.md`
+- **Personas (Load based on Stack Discovery):**
+  - `.devbooster/hub/personas/agent_frontend-specialist.md` (If frontend stack)
+  - `.devbooster/hub/personas/agent_backend-specialist.md` (If backend stack)
+- **Quality Skills:**
+  - `.devbooster/hub/personas/skill_clean-code.md`
+  - `.devbooster/hub/personas/skill_lint-and-validate.md`
+
+## 2. AUDIT PHILOSOPHY: LOCAL RULES OVERRIDE GLOBAL STANDARDS
+1. **The Dev Booster Soul:** The custom rules written in `FRONTEND.md`, `BACKEND.md`, and `USER_PREFERENCES.md` represent the developer's unique project identity. They are the absolute source of truth.
+2. **Conflict Resolution:** If generic `clean-code` or `lint` standards dictate pattern X, but the developer's local files mandate pattern Y, **Pattern Y ALWAYS wins**.
+3. **Consultative Warning:** When this override happens, do NOT mark it as an error. Instead, approve the code and add a consultative note: *"This code follows your custom architecture (Pattern Y). Note: Standard generic convention suggests X, but your local override was respected."* This ensures the developer is fully aware of architectural divergences and retains total control over the codebase style.
+
+## 3. PRE-FLIGHT (MANDATORY)
+1. Use repository-relative paths directly from `.devbooster/` and `.devbooster/hub/`.
+2. **STACK DISCOVERY:** Quickly read `package.json` or `PROJECT.md` to determine the project's technology stack (e.g., React, Angular, Vue, Node.js).
+3. **Run Operational Audit Scripts:**
+    - **Mandatory when relevant:** `security_scan.py`, `type_coverage.py`, `lint_runner.py` (if they exist).
+4. **React/Next.js Frontend Triage (3-Phase Flow):** ONLY IF the project uses React/Next.js:
+    - **Execute & Wait**: Run `npx -y react-doctor@latest --json --diff <scope> --yes > @booster-generated/diagnostics/<slug-name-audit>.json` synchronously. You MUST wait for the command to fully complete before moving to the next step. Do not run it in the background.
+    - **Timeout Safety**: If the command hangs for more than 120 seconds, manually abort it (Kill/Ctrl+C) and proceed with the rest of the audit, gracefully skipping the React Doctor step.
+    - **Filter (Python)**: Run `.devbooster/hub/scripts/doctor_parser.py @booster-generated/diagnostics/<slug-name-audit>.json` to process the JSON.
+    - **Report & Decide**: Present "Immediate Actions" (Critical errors) in detail by line. Present "Cosmetic Debt" (Style rules) as a grouped numerical summary. Append "Content extracted from diagnostics.json".
+    - **ZERO Auto-Fix**: Do NOT modify code automatically. Ask the user: "Do you want to fix only the critical recommendations, everything, or specific items?" and wait for authorization.
+
+## 4. OUTPUT STRUCTURE (MANDATORY)
+Your response MUST be an **Audit Report**:
+
+### 🧹 Code Audit Report: [Scope]
+
+**1. Syntax & Types (Lint/TypeScript/Framework)**
+- [Findings based on the project's specific stack (React, Angular, Vue, etc.)]
+
+**2. Specialized Diagnostics**
+- *(If React)*: [React Doctor Findings (Critical Issues by Line & Cosmetic Debt Summary)]
+- *(If Non-React)*: [Framework-specific standard violations or architectural anti-patterns]
+
+**3. Action Plan**
+- [Waiting for user permission to apply fixes]
+
+## ARTIFACT GENERATION & STATE BACKUP
+During your execution, you MUST create or update a machine-readable state file at `@booster-generated/audits/<slug-name>.md`. 
+This file must continuously track the history, decisions, rules, and outcomes related to this booster's execution in a dense, non-conversational format.
+You must update this file silently in the background as the context evolves or when explicitly commanded by the user.
+
+**Reply:** On activation only, use the armed-mode banner above and ask for the commit scope. After the user provides the scope, load the necessary scripts, perform the audit, and answer in the global language configured for the active LLM/environment.

package/template/.devbooster/boosters/context.md

@@ -43,15 +43,16 @@ When the first real assimilation request arrives:
 - **NO UNSOLICITED ADVICE:** You MUST NOT suggest refactorings, point out technical debt, or critique the existing architecture/clean code patterns.
 - **ZERO CODE OUTPUT:** Your role is purely receptive and structural.
 - **MEMORIZATION ONLY:** Read the files, map their imports, trace the data flow (inputs, outputs, side effects, APIs), and store this representation in your active context memory.
+- **CONTINUOUS STATE BACKUP:** During your memorization, you MUST create or update a context state file at `@booster-generated/contexts/<context-name>.md`. This file must be written in dense, machine-readable format (e.g., explicit blocks like `[CURRENT_GOAL]`, `[ACTIVE_FILES]`, `[PENDING_TASKS]`, `[DECISIONS]`) with NO conversational filler. You must continuously update this file in the background as the context evolves or when explicitly commanded.
 
 ## 3. CONFIRMATION PROTOCOL
-Once you have fully read, parsed, and mapped the flow of the requested files:
+Once you have fully read, parsed, mapped the flow, AND updated the state backup file:
 1. Clear your output of any technical jargon, file contents, code snippets, or rules explanations.
 2. Respond with an ultra-short, highly professional 1-to-2 line acknowledgment in the user's active conversation language.
-3. Confirm that the context is fully mapped and memorized.
+3. Confirm that the context is fully mapped and backed up to the file.
 4. **NO PROACTIVITY:** Do NOT ask follow-up questions, do NOT suggest next steps, and do NOT ask what to do next. Simply state that the context has been absorbed and wait silently for the user's next command.
 
 Example response:
-> *"Fluxo mapeado com sucesso a partir dos arquivos fornecidos. O contexto técnico está armazenado na memória."*
+> *"Fluxo mapeado com sucesso. O contexto técnico está armazenado na memória e com backup ativo em `@booster-generated/contexts/<nome-do-contexto>.md`. Manterei este arquivo atualizado automaticamente conforme avançamos."*
 
-**Reply:** On activation only, use the armed-mode banner above. On the first real task, load the allowed explorer and archaeologist personas silently, read the requested files, map the flow internally, and reply with the non-proactive, ultra-short acknowledgment protocol.
+**Reply:** On activation only, use the armed-mode banner above. On the first real task, load the allowed personas silently, read the files, create/update the context backup file, map the flow internally, and reply with the non-proactive, ultra-short acknowledgment protocol.

package/template/.devbooster/boosters/debug.md

@@ -53,3 +53,8 @@ Your response MUST use this exact format:
 ---
 
 **Response: "Elite Debugger Mode Activated. Diagnostic tools and Hypothesis engine online. Please provide the error logs and where it's happening."**
+## ARTIFACT GENERATION & STATE BACKUP
+During your execution, you MUST create or update a machine-readable state file at `@booster-generated/troubleshooting/<slug-name>.md`. 
+This file must continuously track the history, decisions, rules, and outcomes related to this booster's execution in a dense, non-conversational format.
+You must update this file silently in the background as the context evolves or when explicitly commanded by the user.
+

package/template/.devbooster/boosters/deploy.md

@@ -9,3 +9,8 @@ Activating Infrastructure and Continuous Delivery Specialist.
 - `.devbooster/hub/personas/skill_server-management.md`
 
 **Reply: "Deploy & DevOps Mode Activated. Production launch or infra maintenance? What do we need to run?"**
+## ARTIFACT GENERATION & STATE BACKUP
+During your execution, you MUST create or update a machine-readable state file at `@booster-generated/rollouts/<slug-name>.md`. 
+This file must continuously track the history, decisions, rules, and outcomes related to this booster's execution in a dense, non-conversational format.
+You must update this file silently in the background as the context evolves or when explicitly commanded by the user.
+

package/template/.devbooster/boosters/discovery.md

@@ -72,4 +72,9 @@ After presenting the options, ask the user:
 1. Which direction aligns best with your current priority?
 2. Are there any specific constraints we should consider for the chosen path?
 
+## ARTIFACT GENERATION & STATE BACKUP
+During your execution, you MUST create or update a machine-readable state file at `@booster-generated/discoveries/<slug-name>.md`. 
+This file must continuously track the history, decisions, rules, and outcomes related to this booster's execution in a dense, non-conversational format.
+You must update this file silently in the background as the context evolves or when explicitly commanded by the user.
+
 **Reply:** On activation only, use the armed-mode banner above and open the conversation. After the first real idea arrives, load the minimum required discovery context and continue with the discovery flow in the global language configured for the active LLM/environment.

package/template/.devbooster/boosters/investigation.md

@@ -93,4 +93,9 @@ Organize your response as follows:
 - Initially, analyze ONLY the `package.json` to understand the project structure and stack.
 - Do NOT be proactive in execution. Your goal is certainty and lack of ambiguity.
 
+## ARTIFACT GENERATION & STATE BACKUP
+During your execution, you MUST create or update a machine-readable state file at `@booster-generated/discoveries/<slug-name>.md`. 
+This file must continuously track the history, decisions, rules, and outcomes related to this booster's execution in a dense, non-conversational format.
+You must update this file silently in the background as the context evolves or when explicitly commanded by the user.
+
 **Reply:** On activation only, use the armed-mode banner above with a professional investigation opening. After the first real request arrives, load the minimum required investigation context and continue in the global language configured for the active LLM/environment.

package/template/.devbooster/boosters/planning.md

@@ -89,4 +89,9 @@ On activation only:
 
 Only after the user confirms should this booster continue the alignment process and determine whether the task is ready for implementation.
 
+## ARTIFACT GENERATION & STATE BACKUP
+During your execution, you MUST create or update a machine-readable state file at `@booster-generated/plans/<slug-name>.md`. 
+This file must continuously track the history, decisions, rules, and outcomes related to this booster's execution in a dense, non-conversational format.
+You must update this file silently in the background as the context evolves or when explicitly commanded by the user.
+
 **Reply:** On activation only, review the current conversation context, summarize what is already defined, identify risks and gaps, and ask whether the user wants to proceed with planner alignment. Do not emit the final readiness verdict until the user confirms. Always answer in the global language configured for the active LLM/environment.

package/template/.devbooster/boosters/review.md

@@ -8,7 +8,6 @@ If the user invokes this booster alone, or uses it only to activate the mode:
 - Do NOT start the review immediately.
 - Do NOT load personas, skills, or scripts yet.
 - Do NOT assume the review target is already available in the conversation.
-- Ask the user to provide or reference the documentation or implementation to be reviewed.
 - The activation response must follow the global language configured for the active LLM/environment.
 
 Use this activation response format:

package/template/.devbooster/boosters/security.md

@@ -57,4 +57,9 @@ Rules:
 - `.devbooster/hub/skills/vulnerability-scanner/SKILL.md`
 - `.devbooster/hub/skills/red-team-tactics/SKILL.md`
 
+## ARTIFACT GENERATION & STATE BACKUP
+During your execution, you MUST create or update a machine-readable state file at `@booster-generated/audits/<slug-name>.md`. 
+This file must continuously track the history, decisions, rules, and outcomes related to this booster's execution in a dense, non-conversational format.
+You must update this file silently in the background as the context evolves or when explicitly commanded by the user.
+
 **Reply:** On activation only, use the armed-mode banner above. On the first real task, load the minimum required security context based on the user's pain, then execute.

package/template/.devbooster/hub/scripts/doctor_parser.py

@@ -0,0 +1,77 @@
+import json
+import sys
+import os
+from collections import defaultdict
+
+def parse_diagnostics(file_path):
+    if not os.path.exists(file_path):
+        print(f"Relatório não encontrado em {file_path}.")
+        return
+
+    try:
+        with open(file_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+    except Exception as e:
+        print(f"Erro ao ler JSON: {e}")
+        return
+
+    # O React Doctor pode colocar 'diagnostics' na raiz ou dentro de 'projects'
+    diagnostics = data.get('diagnostics', [])
+    if not diagnostics and 'projects' in data and len(data['projects']) > 0:
+        diagnostics = data['projects'][0].get('diagnostics', [])
+
+    if not diagnostics:
+        print("Nenhum erro encontrado no relatório. Árvore limpa!")
+        return
+
+    # Categorias consideradas essenciais para o funcionamento/performance
+    CRITICAL_CATEGORIES = {"Correctness", "Performance", "Security", "Next.js", "Bundle Size"}
+    
+    # Regras que são puramente estéticas/opcionais (mesmo que caiam em Architecture)
+    COSMETIC_RULES_PREFIXES = ("design-", "no-pure-black-")
+
+    critical_items = defaultdict(list)
+    cosmetic_counts = defaultdict(int)
+
+    for diag in diagnostics:
+        rule = diag.get('rule', 'unknown')
+        category = diag.get('category', 'Unknown')
+        severity = diag.get('severity', 'warning')
+        
+        is_cosmetic = any(rule.startswith(prefix) for prefix in COSMETIC_RULES_PREFIXES)
+
+        # Se for error de verdade ou uma categoria crítica (e não for puramente cosmético)
+        if (severity == 'error' or category in CRITICAL_CATEGORIES) and not is_cosmetic:
+            filepath = diag.get('filePath', 'unknown file')
+            critical_items[filepath].append(diag)
+        else:
+            # Tudo o resto entra no débito de padronização
+            cosmetic_counts[rule] += 1
+
+    # === GERAÇÃO DO RELATÓRIO MOLDADO ===
+    
+    print("### 🔴 AÇÃO IMEDIATA (Erros Críticos)")
+    if not critical_items:
+        print("Nenhum erro crítico de performance ou lógica encontrado nas alterações.\n")
+    else:
+        for filepath, issues in critical_items.items():
+            print(f"**{filepath}**")
+            for issue in issues:
+                line = issue.get('line', '?')
+                rule = issue.get('rule', '')
+                msg = issue.get('message', '')
+                print(f"- `[Linha {line}] {rule}`: {msg}")
+            print("")
+
+    print("### 🎨 DÉBITO DE PADRONIZAÇÃO (Cosmético/Opcional)")
+    if not cosmetic_counts:
+        print("Nenhum débito cosmético pendente.")
+    else:
+        for rule, count in sorted(cosmetic_counts.items(), key=lambda x: x[1], reverse=True):
+            print(f"- `{rule}`: {count} ocorrência(s)")
+    
+    print("\n*Rodapé: Conteúdo extraído do relatório gerado diagnostics.json*")
+
+if __name__ == "__main__":
+    target_file = sys.argv[1] if len(sys.argv) > 1 else "@booster-generated/diagnostics/review.json"
+    parse_diagnostics(target_file)