@ngxtm/devkit 3.13.0 → 3.15.0

package/SKILLS_INDEX.md

@@ -1,6 +1,6 @@
 # Skills Index
 
-> Auto-generated index of 768 available skills.
+> Auto-generated index of 769 available skills.
 > Use this to discover skills without loading all files into context.
 >
 > **To use a skill**: Read the full skill at `~/.claude/skills/<skill-name>/SKILL.md`
@@ -17,7 +17,7 @@
 | Testing | 27 |
 | Python | 23 |
 | Security | 21 |
-| Frontend Frameworks | 19 |
+| Frontend Frameworks | 20 |
 | TypeScript/JavaScript | 19 |
 | Databases | 19 |
 | API Design | 10 |
@@ -3544,6 +3544,11 @@ Expert integration of Supabase Auth with Next.js App Router Use when: supabase a
 
 React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React...
 
+### react-doctor
+`skills/react-doctor`
+
+Run react-doctor to scan React codebase for health issues. Diagnose security, performance, correctness, architecture problems with 0-100 score.
+
 ### react-expert
 `skills/react-expert`
 

package/merged-commands/learn.md

@@ -4,9 +4,9 @@ description: Guided project building — you code, AI mentors. Build your own pr
 argument-hint: [topic]
 ---
 
-# Learn Mode v3.0
+# Learn Mode v3.1
 
-> Build your product. Write every line. Understand every decision.
+> Build your product. Design the architecture. Write every line. Understand every decision.
 
 ## Activation
 
@@ -93,11 +93,69 @@ Update frontmatter: `phase: LEARN`
 
 ---
 
-## Phase 3: BUILD (core phase)
+## Phase 3: DESIGN (Socratic architecture thinking)
 
-1. **Plan steps**: Break implementation into 3-7 verifiable steps. Show plan to user.
+> User thinks first, AI guides — not the other way around.
 
-2. **For each step, follow the teaching mode**:
+1. **Frame the problem**: AI presents the high-level problem to solve:
+   > "We need to build {topic}. Before I suggest anything — how would YOU approach this? What components or pieces do you think we need?"
+
+   Ask via `AskUserQuestion`. Let user think and answer.
+
+2. **Build on user's answer**:
+   - If user's approach is solid → acknowledge strengths, refine together
+   - If user's approach has gaps → ask guiding questions: "What about {concern}? How would you handle that?"
+   - If user has no idea → break it down: "Let's start smaller — what's the first thing a user would do with this feature?"
+
+3. **Explore alternatives**: Present 2-3 different approaches with trade-offs:
+   > "Your approach uses X. Another option is Y. Here's how they compare:"
+
+   | Aspect | Approach A (user's) | Approach B | Approach C |
+   |--------|-------------------|-----------|-----------|
+   | Complexity | ... | ... | ... |
+   | Scalability | ... | ... | ... |
+   | Learning value | ... | ... | ... |
+
+   Ask user to choose via `AskUserQuestion`. Explain WHY each trade-off matters.
+
+4. **Architecture decisions**: For the chosen approach, walk through key decisions:
+   - Data flow: how data moves through the system
+   - File/module structure: where code lives and why
+   - Dependencies: what libraries/tools and why those specifically
+   - Patterns: which design patterns and why (not just "use MVC" but why MVC fits here)
+
+   For each decision, ask user: "Does this make sense? Any concerns?"
+
+5. **Write to tutorial file**: Record the design discussion, chosen approach, and rationale.
+
+Update frontmatter: `phase: DESIGN`
+
+---
+
+## Phase 4: PLAN (concrete implementation steps)
+
+1. **Break down the chosen design** into 3-7 concrete, verifiable steps. Each step should:
+   - Have a clear goal (what's done when this step is complete)
+   - Build on previous steps (incremental, testable progress)
+   - Be small enough to verify immediately
+
+2. **Show plan to user** with rationale for the ordering:
+   > "Here's the build order. We start with X because Y depends on it. Step 3 before Step 4 because..."
+
+3. **User validates**: Ask via `AskUserQuestion`:
+   > "Does this plan make sense? Want to reorder anything or add/remove steps?"
+
+   Adjust plan based on user feedback.
+
+4. **Write plan to tutorial file**: Each step with goal, files involved, and acceptance criteria.
+
+Update frontmatter: `phase: PLAN`, `total_steps: {N}`
+
+---
+
+## Phase 5: BUILD (core phase)
+
+1. **For each step from the PLAN phase, follow the teaching mode**:
 
 ### Guided Mode (user codes everything)
 
@@ -171,7 +229,7 @@ Update frontmatter: `phase: LEARN`
 
 ---
 
-## Phase 4: WRAP-UP
+## Phase 6: WRAP-UP
 
 1. **Summary**: What was built, key takeaways (3-5 points)
 
@@ -209,6 +267,7 @@ Display: `Tutorial saved: learn/{filename}.md`
 
 ## Version History
 
+- **3.1.0** - Added DESIGN phase (Socratic architecture) and PLAN phase (concrete steps). Full flow: INIT → LEARN → DESIGN → PLAN → BUILD → WRAP-UP
 - **3.0.0** - Teaching modes (guided/scaffolded/demonstrated), best-practice review, explain-back checkpoints, user-codes-first philosophy
 - **2.0.0** - Rewrite: adaptive difficulty via codingLevel, 4 phases, WebSearch, Socratic method, resume support, tiered verify, 17 languages, codebase-aware
 - **1.0.0** - Initial release

package/merged-commands/react-doctor.md

@@ -0,0 +1,141 @@
+---
+name: react-doctor
+description: Run react-doctor to scan React codebase for health issues. Diagnose security, performance, correctness, architecture problems with 0-100 score.
+upstream: https://github.com/millionco/react-doctor
+upstream-version: "0.0.0"
+triggers:
+  - react-doctor
+  - react health
+  - react scan
+  - react lint
+  - code health
+  - react audit
+  - react score
+role: tool
+scope: diagnostics
+output-format: analysis
+---
+
+# React Doctor
+
+Scan React codebase for security, performance, correctness, and architecture issues. Outputs a 0-100 health score with actionable diagnostics.
+
+## When to Use
+
+- After making React changes (catch issues early)
+- During code review or PR review
+- Finishing a feature before merge
+- Periodic codebase health check
+- Setting up CI quality gates
+
+## Quick Start
+
+```bash
+# Full scan with file details
+npx -y react-doctor@latest . --verbose
+
+# Scan only changed files (vs base branch)
+npx -y react-doctor@latest . --verbose --diff
+
+# Score only (for CI)
+npx -y react-doctor@latest . --score
+```
+
+## How It Works
+
+Detects framework (Next.js, Vite, Remix, etc.), React version, and compiler setup, then runs two parallel passes:
+
+1. **Lint** — 60+ rules across 8 categories
+2. **Dead code** — unused files, exports, types, duplicates
+
+## Rule Categories
+
+| Category | Examples |
+|----------|----------|
+| State & Effects | missing deps, stale closures, unnecessary re-renders |
+| Performance | unoptimized renders, missing memoization, large bundles |
+| Architecture | circular deps, prop drilling, god components |
+| Bundle Size | unused imports, heavy dependencies |
+| Security | dangerouslySetInnerHTML, XSS vectors |
+| Correctness | key prop misuse, effect cleanup, race conditions |
+| Accessibility | missing ARIA, no-autofocus, semantic HTML |
+| Framework-specific | Next.js patterns, React Native issues |
+
+## CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `--verbose` | Show file details and line numbers per rule |
+| `--no-lint` | Skip linting |
+| `--no-dead-code` | Skip dead code detection |
+| `--score` | Output only the score |
+| `--diff [base]` | Scan only files changed vs base branch |
+| `--project <name>` | Select workspace project (comma-separated) |
+| `-y, --yes` | Skip prompts, scan all workspace projects |
+| `--fix` | Open Ami to auto-fix all issues |
+
+## Configuration
+
+Create `react-doctor.config.json` at project root:
+
+```json
+{
+  "ignore": {
+    "rules": ["react/no-danger", "knip/exports"],
+    "files": ["src/generated/**"]
+  }
+}
+```
+
+Or use `"reactDoctor"` key in `package.json`. Config file takes precedence.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `ignore.rules` | `string[]` | `[]` | Rules to suppress (`plugin/rule` format) |
+| `ignore.files` | `string[]` | `[]` | File globs to exclude |
+| `lint` | `boolean` | `true` | Enable/disable lint checks |
+| `deadCode` | `boolean` | `true` | Enable/disable dead code detection |
+| `verbose` | `boolean` | `false` | Show file details per rule |
+| `diff` | `boolean\|string` | — | Force diff mode or pin base branch |
+
+## Node.js API
+
+```js
+import { diagnose } from "react-doctor/api";
+const result = await diagnose(".", { lint: true, deadCode: true });
+// result.score    → { score: 82, label: "Good" }
+// result.diagnostics → Array of { filePath, plugin, rule, severity, message, help, line, column, category }
+```
+
+## Workflow
+
+1. **Run scan** → `npx -y react-doctor@latest . --verbose`
+2. **Read score** → 75+ Great, 50-74 Needs work, <50 Critical
+3. **Fix errors first** → errors weigh more than warnings
+4. **Re-run** → verify score improved
+5. **Iterate** → address warnings if time permits
+
+## Scoring
+
+- **75-100** — Great health
+- **50-74** — Needs work
+- **0-49** — Critical issues
+- Errors weigh more than warnings in score calculation
+
+## GitHub Actions
+
+```yaml
+- uses: millionco/react-doctor@main
+  with:
+    diff: main
+    verbose: true
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Posts findings as PR comment when `github-token` is set on `pull_request` events.
+
+## Related Skills
+
+- **react-expert** — Fix identified React issues
+- **code-review** — Include react-doctor scan in reviews
+- **test-master** — Dead code findings inform test coverage gaps

package/merged-commands/skill/sync.md

@@ -1,108 +1,176 @@
 ---
-description: Sync new skills from upstream repos with AI evaluation
-argument-hint: [options]
+description: Sync skills, rules, and external-skills from upstream repos with AI evaluation
+argument-hint: [--auto] [--dry-run]
 ---
 
-# Sync Skills from Upstream
+# Sync from Upstream
 
-> AI-assisted upstream skill sync: fetch, evaluate, select, build.
+> AI-driven upstream sync: fetch, evaluate new+updated skills/rules/external-skills, apply, build, commit.
 
-## Workflow
+## Arguments
 
-### Step 1: Pre-flight Check
+Parse `$ARGUMENTS` for flags:
+- `--auto`: Fully autonomous — sync all useful new items, accept all updates, no user questions
+- `--dry-run`: Show report only, don't copy or commit anything
 
-Verify clean working directory:
-```bash
-git status --porcelain
-```
-If not clean → ask user to commit or stash first.
+## Workflow
 
-### Step 2: Fetch Upstream
+### Step 1: Pre-flight
 
-Run the sync script to clone upstream repos and get a report:
+Check git status:
 ```bash
-npm run sync:upstream
+git status --porcelain
 ```
 
-This creates a sync branch and clones repos to temp directory.
+- If **clean** → proceed
+- If **dirty + `--auto`** → run `git stash push -m "devkit-sync-stash"`
+- If **dirty + interactive** → ask user to commit/stash or continue with stash
 
-### Step 3: Evaluate New Skills
+Remember if stash was created (for restore later).
 
-After the script runs, it shows which skills are new. For each **new** skill:
+### Step 2: Fetch & Report
 
-1. Read its `SKILL.md` from the temp directory
-2. Evaluate:
-   - **Useful**: Skill covers a distinct domain not already well-covered
-   - **Duplicate**: Similar skill already exists in the local collection
-   - **Irrelevant**: Too niche or low quality
+Run the sync script with JSON output:
+```bash
+node scripts/manual-sync.js --no-branch --json
+```
 
-3. Present summary to user:
+Parse the JSON output. It contains:
+```json
+{
+  "tempDir": "/tmp/devkit-sync",
+  "skills": { "new": [...], "updated": [...], "unchanged": N },
+  "rules": { "new": [...], "updated": [...], "unchanged": N },
+  "external-skills": [{ "name": "...", "localExists": bool, "upstreamVersion": "...", "localVersion": "...", "checkFiles": [...], "tempPath": "..." }]
+}
 ```
-Upstream sync found N new skills:
 
-✅ Useful (X):
-  - skill-name: short reason
-  - skill-name: short reason
+If all categories have 0 new and 0 updated → report "Already up to date" and stop.
 
-⚠️ Possibly duplicate (Y):
-  - skill-name: overlaps with existing-skill
+### Step 3: Evaluate New Skills
 
-❌ Skip (Z):
-  - skill-name: reason
+For each item in `skills.new`:
+1. Read its `SKILL.md` from the `path` field in the report
+2. Classify:
+   - **Useful**: Covers a distinct domain, well-structured, actionable content
+   - **Duplicate**: Similar skill already exists (check by name/description against skills-compact.json)
+   - **Skip**: Too niche, low quality, or just "be a senior X engineer" with no real content
+3. In `--auto` mode: sync all useful, skip duplicates and low quality
+4. In interactive mode: present summary and ask user using `AskUserQuestion`
 
-Sync options:
-  1. Sync all useful (X skills)
-  2. Sync all useful + duplicates (X+Y skills)
-  3. Let me choose manually
+Summary format:
 ```
+Upstream sync found N new skills:
 
-### Step 4: Copy Selected Skills
-
-Use `AskUserQuestion` to get user's choice. Then for selected skills:
-
-```bash
-cp -r /tmp/devkit-sync/{source}/{skill-name} ./skills/{skill-name}
+✅ Useful (X): skill-a, skill-b, ...
+⚠️ Duplicate (Y): skill-c (overlaps existing-skill), ...
+❌ Skip (Z): skill-d (reason), ...
 ```
 
-### Step 5: Rebuild Indexes
+### Step 3.5: Evaluate Updated Skills
+
+For each item in `skills.updated`:
+1. Read **both** upstream SKILL.md (from tempDir) and local SKILL.md
+2. Compare and summarize what changed
+3. Classify:
+   - **Accept**: Upstream adds substantial new content (new sections, patterns, commands)
+   - **Skip**: Changes are trivial (formatting only) or local version is superior/customized
+4. In `--auto` mode: accept all non-trivial updates
+5. In interactive mode: present changes summary and ask user
+
+### Step 4: Evaluate External Skills
+
+For each item in `external-skills`:
+1. Check if local skill exists (`localExists` field)
+2. If exists:
+   a. Read `UPSTREAM.md` from `skills/{name}/UPSTREAM.md` for sync guide
+   b. Read the relevant `checkFiles` from `tempPath` in the report
+   c. Compare with local `SKILL.md`
+   d. Check version: if `upstreamVersion` differs from `localVersion` → needs update
+   e. Follow UPSTREAM.md guide: preserve devkit-specific sections, update upstream-derived content
+   f. Update `upstream-version` in SKILL.md frontmatter to `upstreamVersion` value
+3. If not exists: report it as available but don't auto-create (manual setup needed)
+4. In `--auto` mode: apply all detected changes following UPSTREAM.md rules
+5. In interactive mode: show what changed and ask user
+
+### Step 5: Evaluate Rules
+
+For each item in `rules.new`:
+1. Read the rule content from `path` field
+2. Classify: useful (covers new pattern) or skip (duplicate/too generic)
+3. In `--auto` mode: sync all useful
+4. In interactive mode: ask user
+
+For each item in `rules.updated`:
+1. Compare upstream and local content
+2. Accept meaningful updates, skip trivial ones
+
+### Step 6: Apply Changes
+
+If `--dry-run` → skip this step, just show what would be done.
+
+For selected items:
+- **New skills**: `node scripts/manual-sync.js --copy <name>` for each
+- **Updated skills**: Read upstream SKILL.md, use Write tool to update local SKILL.md (preserve local customizations if any)
+- **New rules**: `node scripts/manual-sync.js --copy <name>` for each
+- **Updated rules**: Use Write tool to update local rule files
+- **External skills**: Use Write tool to edit SKILL.md following UPSTREAM.md guide
+
+### Step 7: Rebuild & Verify
 
 ```bash
 npm run build
 ```
 
-This regenerates all indexes (merged-commands, rules-index, skills-index, skills-compact).
+- If **success** → proceed to commit
+- If **failure** → rollback ALL changes:
+  ```bash
+  git checkout -- .
+  ```
+  If stash was created: `git stash pop`
+  Report the build error and stop.
 
-### Step 6: Review & Commit
+### Step 8: Commit
 
-Show summary of changes:
+Stage and commit the changes:
 ```bash
-git diff --stat
+git add skills/ rules/ merged-commands/ SKILLS_INDEX.md skills-index.json skills-compact.json rules-index.json
 ```
 
-Ask user if they want to commit:
-```bash
-git add skills/ merged-commands/ SKILLS_INDEX.md skills-index.json skills-compact.json rules-index.json
-git commit -m "feat(skills): sync N new skills from upstream"
+Commit message format:
+```
+feat(skills): sync N new, M updated skills from upstream
 ```
 
-## Options
+Adjust the message based on what was actually synced (skills, rules, external-skills).
 
-- `$ARGUMENTS` can specify:
-  - `--auto`: Skip evaluation, sync all new skills automatically
-  - `--dry-run`: Only show report, don't copy anything
-  - A specific upstream name to sync from (e.g., `antigravity` or `agent-assistant`)
+If stash was created earlier: `git stash pop` to restore user's changes.
 
 ## Evaluation Criteria
 
-When evaluating skills, consider:
-- Does it cover a technology the project uses or might use?
-- Is there already a similar skill? (check by name and description)
-- Is the SKILL.md well-structured with actionable content?
-- Is it too generic (just says "be a senior X engineer")?
+### New Skills
+- **Useful**: Covers distinct domain, well-structured SKILL.md, actionable patterns/commands
+- **Duplicate**: Similar name or description to existing skill in skills-compact.json
+- **Skip**: Too niche, low quality, just "be a senior X engineer" boilerplate
+
+### Updated Skills
+- **Accept**: Upstream adds substantial new content (new sections, patterns, examples)
+- **Skip**: Changes are trivial (whitespace, formatting) or local version is customized and superior
+
+### External Skills
+- Follow UPSTREAM.md guide in each skill directory
+- Always update version tracking
+- Never overwrite devkit-specific frontmatter (`triggers`, `role`, `scope`, `output-format`)
+
+### Rules
+- **Accept**: Rule covers useful pattern not in existing rules
+- **Skip**: Duplicate or too generic
 
 ## Important
 
-- **NEVER** auto-sync without user confirmation (unless `--auto` flag)
-- **ALWAYS** run `npm run build` after copying skills
-- Keep the sync branch for PR review if needed
-- The temp directory is at the path shown by the sync script output
+- In interactive mode, **ALWAYS** ask before applying changes
+- In `--auto` mode, proceed fully autonomously
+- **ALWAYS** run `npm run build` after applying changes
+- **ALWAYS** rollback on build failure via `git checkout -- .`
+- Use `node scripts/manual-sync.js --copy` or Write tool for file operations — **NEVER** use `cp -r` (Windows incompatible)
+- The temp directory path is in the JSON report's `tempDir` field

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngxtm/devkit",
-  "version": "3.13.0",
+  "version": "3.15.0",
   "description": "Per-project AI skills with smart tech detection - lightweight and context-optimized",
   "main": "cli/index.js",
   "bin": {

package/rules-index.json

@@ -1,6 +1,6 @@
 {
   "version": "1.0.0",
-  "generatedAt": "2026-02-19T07:09:25.835Z",
+  "generatedAt": "2026-02-23T08:59:47.559Z",
   "templates": {
     "dart": {
       "path": "templates/dart/rules",

package/skills/learn/SKILL.md

@@ -4,9 +4,9 @@ description: Guided project building — you code, AI mentors. Build your own pr
 argument-hint: [topic]
 ---
 
-# Learn Mode v3.0
+# Learn Mode v3.1
 
-> Build your product. Write every line. Understand every decision.
+> Build your product. Design the architecture. Write every line. Understand every decision.
 
 ## Activation
 
@@ -93,11 +93,69 @@ Update frontmatter: `phase: LEARN`
 
 ---
 
-## Phase 3: BUILD (core phase)
+## Phase 3: DESIGN (Socratic architecture thinking)
 
-1. **Plan steps**: Break implementation into 3-7 verifiable steps. Show plan to user.
+> User thinks first, AI guides — not the other way around.
 
-2. **For each step, follow the teaching mode**:
+1. **Frame the problem**: AI presents the high-level problem to solve:
+   > "We need to build {topic}. Before I suggest anything — how would YOU approach this? What components or pieces do you think we need?"
+
+   Ask via `AskUserQuestion`. Let user think and answer.
+
+2. **Build on user's answer**:
+   - If user's approach is solid → acknowledge strengths, refine together
+   - If user's approach has gaps → ask guiding questions: "What about {concern}? How would you handle that?"
+   - If user has no idea → break it down: "Let's start smaller — what's the first thing a user would do with this feature?"
+
+3. **Explore alternatives**: Present 2-3 different approaches with trade-offs:
+   > "Your approach uses X. Another option is Y. Here's how they compare:"
+
+   | Aspect | Approach A (user's) | Approach B | Approach C |
+   |--------|-------------------|-----------|-----------|
+   | Complexity | ... | ... | ... |
+   | Scalability | ... | ... | ... |
+   | Learning value | ... | ... | ... |
+
+   Ask user to choose via `AskUserQuestion`. Explain WHY each trade-off matters.
+
+4. **Architecture decisions**: For the chosen approach, walk through key decisions:
+   - Data flow: how data moves through the system
+   - File/module structure: where code lives and why
+   - Dependencies: what libraries/tools and why those specifically
+   - Patterns: which design patterns and why (not just "use MVC" but why MVC fits here)
+
+   For each decision, ask user: "Does this make sense? Any concerns?"
+
+5. **Write to tutorial file**: Record the design discussion, chosen approach, and rationale.
+
+Update frontmatter: `phase: DESIGN`
+
+---
+
+## Phase 4: PLAN (concrete implementation steps)
+
+1. **Break down the chosen design** into 3-7 concrete, verifiable steps. Each step should:
+   - Have a clear goal (what's done when this step is complete)
+   - Build on previous steps (incremental, testable progress)
+   - Be small enough to verify immediately
+
+2. **Show plan to user** with rationale for the ordering:
+   > "Here's the build order. We start with X because Y depends on it. Step 3 before Step 4 because..."
+
+3. **User validates**: Ask via `AskUserQuestion`:
+   > "Does this plan make sense? Want to reorder anything or add/remove steps?"
+
+   Adjust plan based on user feedback.
+
+4. **Write plan to tutorial file**: Each step with goal, files involved, and acceptance criteria.
+
+Update frontmatter: `phase: PLAN`, `total_steps: {N}`
+
+---
+
+## Phase 5: BUILD (core phase)
+
+1. **For each step from the PLAN phase, follow the teaching mode**:
 
 ### Guided Mode (user codes everything)
 
@@ -171,7 +229,7 @@ Update frontmatter: `phase: LEARN`
 
 ---
 
-## Phase 4: WRAP-UP
+## Phase 6: WRAP-UP
 
 1. **Summary**: What was built, key takeaways (3-5 points)
 
@@ -209,6 +267,7 @@ Display: `Tutorial saved: learn/{filename}.md`
 
 ## Version History
 
+- **3.1.0** - Added DESIGN phase (Socratic architecture) and PLAN phase (concrete steps). Full flow: INIT → LEARN → DESIGN → PLAN → BUILD → WRAP-UP
 - **3.0.0** - Teaching modes (guided/scaffolded/demonstrated), best-practice review, explain-back checkpoints, user-codes-first philosophy
 - **2.0.0** - Rewrite: adaptive difficulty via codingLevel, 4 phases, WebSearch, Socratic method, resume support, tiered verify, 17 languages, codebase-aware
 - **1.0.0** - Initial release

package/skills/react-doctor/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: react-doctor
+description: Run react-doctor to scan React codebase for health issues. Diagnose security, performance, correctness, architecture problems with 0-100 score.
+upstream: https://github.com/millionco/react-doctor
+upstream-version: "0.0.0"
+triggers:
+  - react-doctor
+  - react health
+  - react scan
+  - react lint
+  - code health
+  - react audit
+  - react score
+role: tool
+scope: diagnostics
+output-format: analysis
+---
+
+# React Doctor
+
+Scan React codebase for security, performance, correctness, and architecture issues. Outputs a 0-100 health score with actionable diagnostics.
+
+## When to Use
+
+- After making React changes (catch issues early)
+- During code review or PR review
+- Finishing a feature before merge
+- Periodic codebase health check
+- Setting up CI quality gates
+
+## Quick Start
+
+```bash
+# Full scan with file details
+npx -y react-doctor@latest . --verbose
+
+# Scan only changed files (vs base branch)
+npx -y react-doctor@latest . --verbose --diff
+
+# Score only (for CI)
+npx -y react-doctor@latest . --score
+```
+
+## How It Works
+
+Detects framework (Next.js, Vite, Remix, etc.), React version, and compiler setup, then runs two parallel passes:
+
+1. **Lint** — 60+ rules across 8 categories
+2. **Dead code** — unused files, exports, types, duplicates
+
+## Rule Categories
+
+| Category | Examples |
+|----------|----------|
+| State & Effects | missing deps, stale closures, unnecessary re-renders |
+| Performance | unoptimized renders, missing memoization, large bundles |
+| Architecture | circular deps, prop drilling, god components |
+| Bundle Size | unused imports, heavy dependencies |
+| Security | dangerouslySetInnerHTML, XSS vectors |
+| Correctness | key prop misuse, effect cleanup, race conditions |
+| Accessibility | missing ARIA, no-autofocus, semantic HTML |
+| Framework-specific | Next.js patterns, React Native issues |
+
+## CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `--verbose` | Show file details and line numbers per rule |
+| `--no-lint` | Skip linting |
+| `--no-dead-code` | Skip dead code detection |
+| `--score` | Output only the score |
+| `--diff [base]` | Scan only files changed vs base branch |
+| `--project <name>` | Select workspace project (comma-separated) |
+| `-y, --yes` | Skip prompts, scan all workspace projects |
+| `--fix` | Open Ami to auto-fix all issues |
+
+## Configuration
+
+Create `react-doctor.config.json` at project root:
+
+```json
+{
+  "ignore": {
+    "rules": ["react/no-danger", "knip/exports"],
+    "files": ["src/generated/**"]
+  }
+}
+```
+
+Or use `"reactDoctor"` key in `package.json`. Config file takes precedence.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `ignore.rules` | `string[]` | `[]` | Rules to suppress (`plugin/rule` format) |
+| `ignore.files` | `string[]` | `[]` | File globs to exclude |
+| `lint` | `boolean` | `true` | Enable/disable lint checks |
+| `deadCode` | `boolean` | `true` | Enable/disable dead code detection |
+| `verbose` | `boolean` | `false` | Show file details per rule |
+| `diff` | `boolean\|string` | — | Force diff mode or pin base branch |
+
+## Node.js API
+
+```js
+import { diagnose } from "react-doctor/api";
+const result = await diagnose(".", { lint: true, deadCode: true });
+// result.score    → { score: 82, label: "Good" }
+// result.diagnostics → Array of { filePath, plugin, rule, severity, message, help, line, column, category }
+```
+
+## Workflow
+
+1. **Run scan** → `npx -y react-doctor@latest . --verbose`
+2. **Read score** → 75+ Great, 50-74 Needs work, <50 Critical
+3. **Fix errors first** → errors weigh more than warnings
+4. **Re-run** → verify score improved
+5. **Iterate** → address warnings if time permits
+
+## Scoring
+
+- **75-100** — Great health
+- **50-74** — Needs work
+- **0-49** — Critical issues
+- Errors weigh more than warnings in score calculation
+
+## GitHub Actions
+
+```yaml
+- uses: millionco/react-doctor@main
+  with:
+    diff: main
+    verbose: true
+    github-token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Posts findings as PR comment when `github-token` is set on `pull_request` events.
+
+## Related Skills
+
+- **react-expert** — Fix identified React issues
+- **code-review** — Include react-doctor scan in reviews
+- **test-master** — Dead code findings inform test coverage gaps

package/skills/react-doctor/UPSTREAM.md

@@ -0,0 +1,68 @@
+# React Doctor — Upstream Sync Guide
+
+## Source
+
+- Repo: https://github.com/millionco/react-doctor
+- NPM: `react-doctor`
+- Key files: `install-skill.sh`, `README.md`, `package.json`
+
+## What to Check During Sync
+
+### 1. Version bump
+- Check `package.json` → `version` field in cloned repo
+- Compare with `upstream-version` in `SKILL.md` frontmatter
+- If changed → update frontmatter
+
+### 2. Skill content changes
+- Read `install-skill.sh` → find `SKILL_CONTENT` heredoc block
+- Compare with our `SKILL.md` body sections
+- If they added new instructions → integrate into relevant section
+
+### 3. New rules or categories
+- Read `README.md` "How it works" section
+- Check if rule count changed (currently 60+)
+- Check if new categories added beyond current 8
+- Update "Rule Categories" table if changed
+
+### 4. CLI flag changes
+- Read `README.md` "Options" section
+- Compare with "CLI Flags" table in SKILL.md
+- Add/remove/update flags as needed
+
+### 5. Config format changes
+- Read `README.md` "Configuration" section
+- Compare with "Configuration" section in SKILL.md
+- Check for new config keys
+
+### 6. GitHub Actions changes
+- Read `README.md` "GitHub Actions" section
+- Compare with "GitHub Actions" section in SKILL.md
+
+## What to Preserve (Never Overwrite from Upstream)
+
+- YAML frontmatter: `triggers`, `role`, `scope`, `output-format`
+- "When to Use" section (devkit-tailored context)
+- "Related Skills" section (devkit-specific references)
+- "Workflow" section (devkit-enhanced steps)
+
+## What to Update (From Upstream)
+
+- `upstream-version` in frontmatter
+- CLI flags if changed
+- Rule categories if new ones added
+- Config format if changed
+- Quick Start commands if changed
+- GitHub Actions usage if changed
+- Node.js API if changed
+
+## Update Checklist
+
+1. `npm run sync:upstream` — clones react-doctor repo to temp
+2. Check report output for react-doctor section
+3. Read cloned files listed in report
+4. Compare with current `SKILL.md` using sections above
+5. Update `SKILL.md` if changes found
+6. Update `upstream-version` in frontmatter
+7. `npm run build` — rebuild indexes
+8. Verify: `react-doctor` still in `skills-compact.json`
+9. Commit and push

package/skills-index.json

@@ -2734,6 +2734,11 @@
     "path": "skills/react-best-practices",
     "description": "React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patter"
   },
+  {
+    "name": "react-doctor",
+    "path": "skills/react-doctor",
+    "description": "Run react-doctor to scan React codebase for health issues. Diagnose security, performance, correctness, architecture problems with 0-100 score."
+  },
   {
     "name": "react-expert",
     "path": "skills/react-expert",