claudeos-core 0.0.1 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [1.0.0] — 2025
+
+### Added
+- 3-Pass pipeline: Deep analysis → Merge → Generate
+- 5 stack templates: Java/Spring Boot, Node/Express/NestJS, Next.js/React, Python/Django, Python/FastAPI
+- Multi-stack support: Backend + Frontend analyzed simultaneously with separate prompts
+- 6 verification tools: manifest-generator, import-linter, plan-validator, sync-checker, content-validator, pass-json-validator
+- Master Plan backup/restore system (3 modes: check, refresh, execute)
+- Node.js CLI (`bin/cli.js`): init, health, validate, refresh, restore commands
+- Legacy bash support (`bootstrap.sh`)
+- Cross-platform compatibility via `CLAUDEOS_ROOT` environment variable
+- Auto-scaling: domain groups split by project size (5–18min)
+- English README + Korean README (separate)

package/CONTRIBUTING.md

@@ -0,0 +1,48 @@
+# Contributing to ClaudeOS-Core
+
+Thank you for your interest in contributing! Here's how you can help.
+
+## Areas Where Help Is Needed
+
+- **New stack templates** — Ruby/Rails, Go/Gin, PHP/Laravel, Rust/Axum
+- **Monorepo deep support** — Separate sub-project roots, workspace detection
+- **Test coverage** — Unit tests for verification tools
+- **Localization** — README translations (Chinese, Japanese, Spanish, etc.)
+
+## How to Contribute
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes
+4. Run the health checker: `node bin/cli.js health`
+5. Commit: `git commit -m "feat: your feature description"`
+6. Push: `git push origin feature/your-feature`
+7. Open a Pull Request
+
+## Adding a New Stack Template
+
+1. Create a new directory under `pass-prompts/templates/your-stack/`
+2. Add `pass1.md`, `pass2.md`, `pass3.md` following the existing template structure
+3. Update `selectTemplates()` in `plan-installer/index.js`
+4. Update `scanStructure()` to detect the new stack's domains
+5. Update `README.md` Supported Stacks table
+
+## Code Style
+
+- Node.js CommonJS (`require`/`module.exports`)
+- 2-space indentation
+- Semicolons required
+- `const` over `let` where possible
+
+## Commit Message Convention
+
+```
+feat: add Ruby/Rails template
+fix: correct Vue domain scanning
+docs: update README for new stack
+refactor: simplify splitDomainGroups
+```
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the ISC License.

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 claudeos-core
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.de.md

@@ -0,0 +1,301 @@
+# ClaudeOS-Core
+
+**Ein Befehl. Ihre gesamte Claude Code Dokumentation — automatisch aus Ihrem Quellcode generiert.**
+
+```bash
+npx claudeos-core init
+```
+
+ClaudeOS-Core liest Ihre Codebasis, extrahiert jedes Muster und generiert einen vollständigen Satz von Standards, Rules, Skills und Guides, die auf _Ihr_ Projekt zugeschnitten sind. Danach, wenn Sie Claude Code sagen „Erstelle ein CRUD für Bestellungen", erzeugt es Code, der exakt Ihren bestehenden Mustern entspricht.
+
+[🇺🇸 English](./README.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇪🇸 Español](./README.es.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇫🇷 Français](./README.fr.md) · [🇰🇷 한국어](./README.ko.md)
+
+---
+
+## Das Problem
+
+Claude Code ist leistungsstark, aber es kennt nicht die Konventionen _Ihres_ Projekts. Das manuelle Schreiben einer `CLAUDE.md`, dutzender Regeln und Scaffolding-Skills dauert Stunden — und sie veralten, sobald sich Ihre Codebasis weiterentwickelt.
+
+## Die Lösung
+
+ClaudeOS-Core automatisiert den gesamten Prozess:
+
+1. **Scannt** Ihr Projekt — erkennt automatisch Stack, Domänen, ORM, Datenbank, Paketmanager
+2. **Analysiert** Ihren Quellcode tiefgehend — Controller-Muster, Service-Schichten, Namenskonventionen, Fehlerbehandlung, Sicherheit, Tests und 50+ Kategorien
+3. **Generiert** ein vollständiges Dokumentationsökosystem — `CLAUDE.md`, Standards (15–17 Dateien), Rules, Skills, Guides (9 Dateien), Master Plans, DB-Dokumentation und MCP-Leitfaden
+4. **Validiert** alles — 6 integrierte Verifizierungstools gewährleisten Konsistenz
+
+Gesamtzeit: **5–18 Minuten**, abhängig von der Projektgröße. Null manuelle Konfiguration.
+
+---
+
+## Unterstützte Stacks
+
+| Stack | Erkennung | Analysetiefe |
+|---|---|---|
+| **Java / Spring Boot** | `build.gradle`, `pom.xml` | 10 Kategorien, 59 Unterpunkte |
+| **Node.js / Express / NestJS** | `package.json` | 9 Kategorien, 57 Unterpunkte |
+| **Next.js / React / Vue** | `package.json` (next, react, vue) | 9 Kategorien, 55 Unterpunkte |
+| **Python / Django** | `requirements.txt`, `pyproject.toml` | 10 Kategorien, 55 Unterpunkte |
+| **Python / FastAPI** | `requirements.txt`, `pyproject.toml` | 10 Kategorien, 58 Unterpunkte |
+
+Automatisch erkannt: Sprache und Version, Framework und Version, ORM (MyBatis, JPA, Prisma, TypeORM, SQLAlchemy usw.), Datenbank (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), Paketmanager (Gradle, Maven, npm, yarn, pnpm, pip, poetry).
+
+**Sie müssen nichts angeben. Alles wird automatisch erkannt.**
+
+---
+
+## Schnellstart
+
+### Voraussetzungen
+
+- **Node.js** v18+
+- **Claude Code CLI** (installiert und authentifiziert)
+
+### Installation
+
+```bash
+cd /your/project/root
+
+# Option A: npx (empfohlen)
+npx claudeos-core init
+
+# Option B: git clone (für Entwicklung/Beiträge)
+git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
+bash claudeos-core-tools/bootstrap.sh
+```
+
+Das war's. Nach 5–18 Minuten ist die gesamte Dokumentation generiert und einsatzbereit.
+
+### Nutzung starten
+
+```
+# In Claude Code — einfach natürlich sprechen:
+"Erstelle ein CRUD für die Bestell-Domäne"
+"Füge eine Benutzer-Authentifizierungs-API hinzu"
+"Refaktoriere diesen Code nach den Projektmustern"
+
+# Claude Code referenziert automatisch Ihre generierten Standards, Rules und Skills.
+```
+
+---
+
+## Funktionsweise — 3-Pass-Pipeline
+
+```
+npx claudeos-core init
+    │
+    ├── [1] npm install                    ← Abhängigkeiten (~10s)
+    ├── [2] Verzeichnisstruktur            ← Ordner erstellen (~1s)
+    ├── [3] plan-installer (Node.js)       ← Projekt-Scan (~5s)
+    │       ├── Automatische Stack-Erkennung (Multi-Stack)
+    │       ├── Domänenliste extrahieren (Tags: backend/frontend)
+    │       ├── Aufteilung in Domänengruppen (nach Typ)
+    │       └── Stack-spezifische Prompts auswählen (nach Typ)
+    │
+    ├── [4] Pass 1 × N  (claude -p)       ← Tiefgehende Code-Analyse (~2-8 Min)
+    │       ├── ⚙️ Backend-Gruppen → Backend-Analyse-Prompt
+    │       └── 🎨 Frontend-Gruppen → Frontend-Analyse-Prompt
+    │
+    ├── [5] Pass 2 × 1  (claude -p)       ← Analyse zusammenführen (~1 Min)
+    │       └── ALLE Pass-1-Ergebnisse konsolidieren (Backend + Frontend)
+    │
+    ├── [6] Pass 3 × 1  (claude -p)       ← Alles generieren (~3-5 Min)
+    │       └── Kombinierter Prompt (Backend- + Frontend-Ziele)
+    │
+    └── [7] Verifizierung                  ← Health Checker automatisch ausführen
+```
+
+### Warum 3 Passes?
+
+**Pass 1** ist der einzige Pass, der Ihren Quellcode liest. Er wählt repräsentative Dateien pro Domäne aus und extrahiert Muster über 55–59 Analysekategorien (pro Stack). Bei großen Projekten wird Pass 1 mehrfach ausgeführt — einmal pro Domänengruppe. In Multi-Stack-Projekten (z.B. Java-Backend + React-Frontend) verwenden Backend und Frontend **unterschiedliche Analyse-Prompts**, die auf jeden Stack zugeschnitten sind.
+
+**Pass 2** führt alle Pass-1-Ergebnisse zu einer einheitlichen Analyse zusammen: gemeinsame Muster (100% geteilt), Mehrheitsmuster (50%+ geteilt), domänenspezifische Muster, Anti-Muster nach Schweregrad und Querschnittsthemen (Benennung, Sicherheit, DB, Tests, Logging, Performance).
+
+**Pass 3** nimmt die zusammengeführte Analyse und generiert das gesamte Datei-Ökosystem. Er liest niemals Quellcode — nur das Analyse-JSON. Im Multi-Stack-Modus kombiniert der Generierungs-Prompt Backend- und Frontend-Ziele, sodass beide Standardsätze in einem einzigen Pass generiert werden.
+
+---
+
+## Generierte Dateistruktur
+
+```
+your-project/
+│
+├── CLAUDE.md                          ← Claude Code Einstiegspunkt
+│
+├── .claude/
+│   └── rules/                         ← Glob-getriggerte Regeln
+│       ├── 00.core/
+│       ├── 10.backend/
+│       ├── 20.frontend/
+│       ├── 30.security-db/
+│       ├── 40.infra/
+│       └── 50.sync/                   ← Auto-Sync-Regeln
+│
+├── claudeos-core/                     ← Hauptausgabeverzeichnis
+│   ├── generated/                     ← Analyse-JSON + dynamische Prompts
+│   ├── standard/                      ← Code-Standards (15-17 Dateien)
+│   ├── skills/                        ← CRUD-Scaffolding-Skills
+│   ├── guide/                         ← Onboarding, FAQ, Fehlerbehebung (9 Dateien)
+│   ├── plan/                          ← Master Plans (Backup/Wiederherstellung)
+│   ├── database/                      ← DB-Schema, Migrationsanleitung
+│   └── mcp-guide/                     ← MCP-Server-Integrationsleitfaden
+│
+└── claudeos-core-tools/               ← Dieses Toolkit (nicht ändern)
+```
+
+Jede Standard-Datei enthält ✅ korrekte Beispiele, ❌ falsche Beispiele und eine Regelzusammenfassungstabelle — alles abgeleitet aus Ihren tatsächlichen Code-Mustern, nicht aus generischen Vorlagen.
+
+---
+
+## Automatische Skalierung nach Projektgröße
+
+| Größe | Domänen | Pass-1-Durchläufe | Gesamt `claude -p` | Geschätzte Zeit |
+|---|---|---|---|---|
+| Klein | 1–4 | 1 | 3 | ~5 Min |
+| Mittel | 5–8 | 2 | 4 | ~8 Min |
+| Groß | 9–16 | 3–4 | 5–6 | ~12 Min |
+| Sehr Groß | 17+ | 5+ | 7+ | ~18 Min+ |
+
+Bei Multi-Stack-Projekten (z.B. Java + React) werden Backend- und Frontend-Domänen zusammen gezählt. 6 Backend + 4 Frontend = 10 Domänen, skaliert als „Groß".
+
+---
+
+## Verifizierungstools
+
+ClaudeOS-Core enthält 6 integrierte Verifizierungstools, die nach der Generierung automatisch ausgeführt werden:
+
+```bash
+# Alle Prüfungen auf einmal ausführen (empfohlen)
+npx claudeos-core health
+
+# Einzelne Befehle
+npx claudeos-core validate     # Plan ↔ Festplatte Vergleich
+npx claudeos-core refresh      # Festplatte → Plan Synchronisation
+npx claudeos-core restore      # Plan → Festplatte Wiederherstellung
+```
+
+| Tool | Funktion |
+|---|---|
+| **manifest-generator** | Erstellt Metadaten-JSON (rule-manifest, import-graph, sync-map, plan-manifest) |
+| **import-linter** | Validiert `@import`-Pfade — erkennt defekte, doppelte und zirkuläre Imports (DFS) |
+| **plan-validator** | Vergleicht `<file>`-Blöcke des Master Plans mit der Festplatte — 3 Modi: check, refresh, restore |
+| **sync-checker** | Erkennt nicht registrierte Dateien (auf Festplatte, aber nicht im Plan) und verwaiste Einträge |
+| **content-validator** | Validiert Dateiqualität — leere Dateien, fehlende ✅/❌ Beispiele, erforderliche Abschnitte |
+| **pass-json-validator** | Validiert Pass-1–3-JSON-Struktur, erforderliche Schlüssel und Abschnittsvollständigkeit |
+
+---
+
+## Täglicher Arbeitsablauf
+
+### Nach der Installation
+
+```
+# Verwenden Sie Claude Code wie gewohnt — es referenziert Ihre Standards automatisch:
+"Erstelle ein CRUD für die Bestell-Domäne"
+"Füge eine API zur Benutzerprofil-Aktualisierung hinzu"
+"Refaktoriere diesen Code nach den Projektmustern"
+```
+
+### Nach manueller Bearbeitung der Standards
+
+```bash
+# Änderungen zum Master Plan synchronisieren
+npx claudeos-core refresh
+
+# Konsistenz überprüfen
+npx claudeos-core health
+```
+
+### Wenn Dokumente beschädigt sind
+
+```bash
+# Alles aus dem Master Plan wiederherstellen
+npx claudeos-core restore
+```
+
+### CI/CD-Integration
+
+```yaml
+# GitHub Actions Beispiel
+- run: npx claudeos-core validate
+# Exit-Code 1 blockiert den PR
+```
+
+---
+
+## Was ist anders?
+
+| | ClaudeOS-Core | SuperClaude | Manuelle CLAUDE.md | Generische Skills |
+|---|---|---|---|---|
+| **Liest Ihren Code** | ✅ Tiefenanalyse (55–59 Kategorien) | ❌ Verhaltensinjektion | ❌ Manuelles Schreiben | ❌ Vorgefertigte Vorlagen |
+| **Projektspezifische Ausgabe** | ✅ Jede Datei spiegelt Ihre Muster wider | ❌ Generische Befehle | Teilweise | ❌ Einheitsgröße |
+| **Multi-Stack** | ✅ Auto-Erkennung + separate Analyse | ❌ Stack-agnostisch | Manuell | Variiert |
+| **Selbstverifizierung** | ✅ 6 Validierungstools | ❌ | ❌ | ❌ |
+| **Backup / Wiederherstellung** | ✅ Master Plan System | ❌ | ❌ | ❌ |
+| **Einrichtungszeit** | ~5–18 Min (automatisch) | ~5 Min (manuelle Konfig) | Stunden–Tage | ~5 Min |
+
+---
+
+## FAQ
+
+**F: Ändert es meinen Quellcode?**
+Nein. Es werden nur `CLAUDE.md`, `.claude/rules/` und `claudeos-core/` erstellt. Ihr bestehender Code wird niemals geändert.
+
+**F: Was kostet es?**
+Ruft `claude -p` 3–7 Mal auf. Das liegt im normalen Claude Code Nutzungsbereich.
+
+**F: Sollte man die generierten Dateien in Git committen?**
+Empfohlen. Ihr Team kann die gleichen Claude Code Standards teilen. Erwägen Sie, `claudeos-core/generated/` zu `.gitignore` hinzuzufügen (Analyse-JSON ist regenerierbar).
+
+**F: Was ist mit Mixed-Stack-Projekten (z.B. Java-Backend + React-Frontend)?**
+Vollständig unterstützt. ClaudeOS-Core erkennt automatisch beide Stacks, taggt Domänen als `backend` oder `frontend` und verwendet stackspezifische Analyse-Prompts für jeden. Pass 2 führt alles zusammen, und Pass 3 generiert Backend- und Frontend-Standards in einem einzigen Pass.
+
+**F: Was passiert bei erneutem Ausführen?**
+Pass 1/2 werden übersprungen, wenn ihr JSON bereits existiert. Pass 3 wird immer erneut ausgeführt. Frühere Versionen können aus Master Plans wiederhergestellt werden.
+
+---
+
+## Template-Struktur
+
+```
+pass-prompts/templates/
+├── common/                  # Gemeinsamer Header/Footer
+├── java-spring/             # Java / Spring Boot
+├── node-express/            # Node.js / Express / NestJS
+├── node-nextjs/             # Next.js / React / Vue
+├── python-django/           # Python / Django (DRF)
+└── python-fastapi/          # Python / FastAPI
+```
+
+`plan-installer` erkennt automatisch Ihren Stack / Ihre Stacks und stellt typspezifische Prompts zusammen. Für Multi-Stack-Projekte werden `pass1-backend-prompt.md` und `pass1-frontend-prompt.md` separat generiert, während `pass3-prompt.md` die Generierungsziele beider Stacks kombiniert.
+
+---
+
+## Fehlerbehebung
+
+**"claude: command not found"** — Claude Code CLI ist nicht installiert oder nicht im PATH. Siehe [Claude Code Dokumentation](https://code.claude.com/docs/en/overview).
+
+**"npm install failed"** — Node.js-Version könnte zu niedrig sein. v18+ erforderlich.
+
+**"0 domains detected"** — Ihre Projektstruktur könnte nicht standardmäßig sein. Siehe die Erkennungsmuster in der [koreanischen Dokumentation](./README.ko.md#-문제-해결--troubleshooting) für Ihren Stack.
+
+---
+
+## Mitwirken
+
+Beiträge sind willkommen! Bereiche, in denen am meisten Hilfe benötigt wird:
+
+- **Neue Stack-Templates** — Ruby/Rails, Go/Gin, PHP/Laravel, Rust/Axum
+- **Tiefe Monorepo-Unterstützung** — Separate Unterprojekt-Roots, Workspace-Erkennung
+- **Testabdeckung** — Unit-Tests für alle Verifizierungstools
+
+---
+
+## Autor
+
+Erstellt von **claudeos-core** — [GitHub](https://github.com/claudeos-core) · [Email](mailto:claudeoscore@gmail.com)
+
+## Lizenz
+
+ISC

package/README.es.md

@@ -0,0 +1,301 @@
+# ClaudeOS-Core
+
+**Un solo comando. Toda la documentación de Claude Code — generada automáticamente desde tu código fuente.**
+
+```bash
+npx claudeos-core init
+```
+
+ClaudeOS-Core lee tu código fuente, extrae cada patrón que encuentra y genera un conjunto completo de Standards, Rules, Skills y Guides adaptados a _tu_ proyecto. Después, cuando le digas a Claude Code "Crea un CRUD para pedidos", generará código que coincide exactamente con tus patrones existentes.
+
+[🇺🇸 English](./README.md) · [🇨🇳 中文](./README.zh-CN.md) · [🇯🇵 日本語](./README.ja.md) · [🇻🇳 Tiếng Việt](./README.vi.md) · [🇮🇳 हिन्दी](./README.hi.md) · [🇷🇺 Русский](./README.ru.md) · [🇫🇷 Français](./README.fr.md) · [🇩🇪 Deutsch](./README.de.md) · [🇰🇷 한국어](./README.ko.md)
+
+---
+
+## El Problema
+
+Claude Code es potente, pero no conoce las convenciones de _tu_ proyecto. Escribir manualmente un `CLAUDE.md`, docenas de reglas y skills de scaffolding lleva horas — y se vuelven obsoletos en cuanto tu código evoluciona.
+
+## La Solución
+
+ClaudeOS-Core automatiza todo el proceso:
+
+1. **Escanea** tu proyecto — detecta automáticamente stack, dominios, ORM, base de datos y gestor de paquetes
+2. **Analiza** tu código fuente en profundidad — patrones de controladores, capas de servicio, convenciones de nombrado, manejo de errores, seguridad, testing y más de 50 categorías
+3. **Genera** un ecosistema documental completo — `CLAUDE.md`, Standards (15–17 archivos), Rules, Skills, Guides (9 archivos), Master Plans, documentación de BD y guía MCP
+4. **Valida** todo — 6 herramientas de verificación integradas garantizan la consistencia
+
+Tiempo total: **5–18 minutos**, según el tamaño del proyecto. Cero configuración manual.
+
+---
+
+## Stacks Soportados
+
+| Stack | Detección | Profundidad de Análisis |
+|---|---|---|
+| **Java / Spring Boot** | `build.gradle`, `pom.xml` | 10 categorías, 59 sub-ítems |
+| **Node.js / Express / NestJS** | `package.json` | 9 categorías, 57 sub-ítems |
+| **Next.js / React / Vue** | `package.json` (next, react, vue) | 9 categorías, 55 sub-ítems |
+| **Python / Django** | `requirements.txt`, `pyproject.toml` | 10 categorías, 55 sub-ítems |
+| **Python / FastAPI** | `requirements.txt`, `pyproject.toml` | 10 categorías, 58 sub-ítems |
+
+Detección automática: lenguaje y versión, framework y versión, ORM (MyBatis, JPA, Prisma, TypeORM, SQLAlchemy, etc.), base de datos (PostgreSQL, MySQL, Oracle, MongoDB, SQLite), gestor de paquetes (Gradle, Maven, npm, yarn, pnpm, pip, poetry).
+
+**No necesitas especificar nada. Todo se detecta automáticamente.**
+
+---
+
+## Inicio Rápido
+
+### Requisitos Previos
+
+- **Node.js** v18+
+- **Claude Code CLI** (instalado y autenticado)
+
+### Instalación
+
+```bash
+cd /your/project/root
+
+# Opción A: npx (recomendado)
+npx claudeos-core init
+
+# Opción B: git clone (para desarrollo/contribución)
+git clone https://github.com/claudeos-core/claudeos-core.git claudeos-core-tools
+bash claudeos-core-tools/bootstrap.sh
+```
+
+Eso es todo. Después de 5–18 minutos, toda la documentación estará generada y lista para usar.
+
+### Empieza a Usar
+
+```
+# En Claude Code — simplemente habla de forma natural:
+"Crea un CRUD para el dominio de pedidos"
+"Añade una API de autenticación de usuarios"
+"Refactoriza este código según los patrones del proyecto"
+
+# Claude Code referencia automáticamente tus Standards, Rules y Skills generados.
+```
+
+---
+
+## Cómo Funciona — Pipeline de 3 Pasadas
+
+```
+npx claudeos-core init
+    │
+    ├── [1] npm install                    ← Dependencias (~10s)
+    ├── [2] Estructura de directorios      ← Crear carpetas (~1s)
+    ├── [3] plan-installer (Node.js)       ← Escaneo del proyecto (~5s)
+    │       ├── Auto-detección de stack (multi-stack)
+    │       ├── Extracción de lista de dominios (etiquetados: backend/frontend)
+    │       ├── División en grupos de dominios (por tipo)
+    │       └── Selección de prompts específicos por stack (por tipo)
+    │
+    ├── [4] Pass 1 × N  (claude -p)       ← Análisis profundo de código (~2-8min)
+    │       ├── ⚙️ Grupos backend → prompt de análisis backend
+    │       └── 🎨 Grupos frontend → prompt de análisis frontend
+    │
+    ├── [5] Pass 2 × 1  (claude -p)       ← Fusión de análisis (~1min)
+    │       └── Consolidar TODOS los resultados de Pass 1 (backend + frontend)
+    │
+    ├── [6] Pass 3 × 1  (claude -p)       ← Generar todo (~3-5min)
+    │       └── Prompt combinado (objetivos backend + frontend)
+    │
+    └── [7] Verificación                   ← Ejecución automática del health checker
+```
+
+### ¿Por Qué 3 Pasadas?
+
+**Pass 1** es la única pasada que lee tu código fuente. Selecciona archivos representativos por dominio y extrae patrones en 55–59 categorías de análisis (por stack). Para proyectos grandes, Pass 1 se ejecuta múltiples veces — una por grupo de dominios. En proyectos multi-stack (ej: backend Java + frontend React), backend y frontend usan **prompts de análisis diferentes** adaptados a cada stack.
+
+**Pass 2** fusiona todos los resultados de Pass 1 en un análisis unificado: patrones comunes (100% compartidos), patrones mayoritarios (50%+ compartidos), patrones específicos de dominio, anti-patrones por severidad y preocupaciones transversales (nombrado, seguridad, BD, testing, logging, rendimiento).
+
+**Pass 3** toma el análisis fusionado y genera todo el ecosistema de archivos. Nunca lee código fuente — solo el JSON de análisis. En modo multi-stack, el prompt de generación combina los objetivos de backend y frontend para generar ambos conjuntos de estándares en una sola pasada.
+
+---
+
+## Estructura de Archivos Generados
+
+```
+your-project/
+│
+├── CLAUDE.md                          ← Punto de entrada de Claude Code
+│
+├── .claude/
+│   └── rules/                         ← Reglas activadas por Glob
+│       ├── 00.core/
+│       ├── 10.backend/
+│       ├── 20.frontend/
+│       ├── 30.security-db/
+│       ├── 40.infra/
+│       └── 50.sync/                   ← Reglas de sincronización automática
+│
+├── claudeos-core/                     ← Directorio principal de salida
+│   ├── generated/                     ← JSON de análisis + prompts dinámicos
+│   ├── standard/                      ← Estándares de código (15-17 archivos)
+│   ├── skills/                        ← Skills de scaffolding CRUD
+│   ├── guide/                         ← Onboarding, FAQ, troubleshooting (9 archivos)
+│   ├── plan/                          ← Master Plans (backup/restauración)
+│   ├── database/                      ← Esquema BD, guía de migración
+│   └── mcp-guide/                     ← Guía de integración de servidor MCP
+│
+└── claudeos-core-tools/               ← Este toolkit (no modificar)
+```
+
+Cada archivo de estándar incluye ejemplos ✅ correctos, ejemplos ❌ incorrectos y una tabla resumen de reglas — todo derivado de tus patrones de código reales, no de plantillas genéricas.
+
+---
+
+## Auto-escalado por Tamaño de Proyecto
+
+| Tamaño | Dominios | Ejecuciones Pass 1 | Total `claude -p` | Tiempo Est. |
+|---|---|---|---|---|
+| Pequeño | 1–4 | 1 | 3 | ~5min |
+| Mediano | 5–8 | 2 | 4 | ~8min |
+| Grande | 9–16 | 3–4 | 5–6 | ~12min |
+| Extra Grande | 17+ | 5+ | 7+ | ~18min+ |
+
+Para proyectos multi-stack (ej: Java + React), los dominios de backend y frontend se cuentan juntos. Un proyecto con 6 dominios backend + 4 frontend = 10 total, escalando como "Grande".
+
+---
+
+## Herramientas de Verificación
+
+ClaudeOS-Core incluye 6 herramientas de verificación integradas que se ejecutan automáticamente después de la generación:
+
+```bash
+# Ejecutar todas las verificaciones a la vez (recomendado)
+npx claudeos-core health
+
+# Comandos individuales
+npx claudeos-core validate     # Comparación Plan ↔ disco
+npx claudeos-core refresh      # Sincronización Disco → Plan
+npx claudeos-core restore      # Restauración Plan → Disco
+```
+
+| Herramienta | Función |
+|---|---|
+| **manifest-generator** | Construye JSON de metadatos (rule-manifest, import-graph, sync-map, plan-manifest) |
+| **import-linter** | Valida rutas `@import` — detecta imports rotos, duplicados y circulares (DFS) |
+| **plan-validator** | Compara bloques `<file>` del Master Plan con el disco — 3 modos: check, refresh, restore |
+| **sync-checker** | Detecta archivos no registrados (en disco pero no en plan) y entradas huérfanas |
+| **content-validator** | Valida calidad de archivos — archivos vacíos, ejemplos ✅/❌ faltantes, secciones requeridas |
+| **pass-json-validator** | Valida estructura JSON de Pass 1–3, claves requeridas y completitud de secciones |
+
+---
+
+## Flujo de Trabajo Diario
+
+### Después de la Instalación
+
+```
+# Usa Claude Code normalmente — referencia tus estándares automáticamente:
+"Crea un CRUD para el dominio de pedidos"
+"Añade una API de actualización de perfil de usuario"
+"Refactoriza este código según los patrones del proyecto"
+```
+
+### Después de Editar Estándares Manualmente
+
+```bash
+# Sincroniza tus cambios al Master Plan
+npx claudeos-core refresh
+
+# Verifica que todo sea consistente
+npx claudeos-core health
+```
+
+### Cuando los Documentos se Corrompen
+
+```bash
+# Restaura todo desde el Master Plan
+npx claudeos-core restore
+```
+
+### Integración CI/CD
+
+```yaml
+# Ejemplo de GitHub Actions
+- run: npx claudeos-core validate
+# Código de salida 1 bloquea el PR
+```
+
+---
+
+## ¿En Qué se Diferencia?
+
+| | ClaudeOS-Core | SuperClaude | CLAUDE.md Manual | Skills Genéricos |
+|---|---|---|---|---|
+| **Lee tu código** | ✅ Análisis profundo (55–59 categorías) | ❌ Inyección de comportamiento | ❌ Escritura manual | ❌ Plantillas predefinidas |
+| **Salida específica del proyecto** | ✅ Cada archivo refleja tus patrones | ❌ Comandos genéricos | Parcial | ❌ Talla única |
+| **Multi-stack** | ✅ Auto-detección + análisis separado | ❌ Agnóstico al stack | Manual | Variable |
+| **Auto-verificación** | ✅ 6 herramientas de validación | ❌ | ❌ | ❌ |
+| **Backup / Restauración** | ✅ Sistema Master Plan | ❌ | ❌ | ❌ |
+| **Tiempo de configuración** | ~5–18min (automático) | ~5min (config manual) | Horas–Días | ~5min |
+
+---
+
+## FAQ
+
+**P: ¿Modifica mi código fuente?**
+No. Solo crea `CLAUDE.md`, `.claude/rules/` y `claudeos-core/`. Tu código existente nunca se modifica.
+
+**P: ¿Cuánto cuesta?**
+Llama a `claude -p` entre 3–7 veces. Está dentro del uso normal de Claude Code.
+
+**P: ¿Debería hacer commit de los archivos generados a Git?**
+Sí, recomendado. Tu equipo puede compartir los mismos estándares de Claude Code. Considera añadir `claudeos-core/generated/` a `.gitignore` (el JSON de análisis es regenerable).
+
+**P: ¿Qué pasa con proyectos de stack mixto (ej: backend Java + frontend React)?**
+Totalmente soportado. ClaudeOS-Core auto-detecta ambos stacks, etiqueta dominios como `backend` o `frontend`, y usa prompts de análisis específicos para cada uno. Pass 2 fusiona todo, y Pass 3 genera los estándares de backend y frontend en una sola pasada.
+
+**P: ¿Qué pasa al re-ejecutar?**
+Pass 1/2 se omiten si su JSON ya existe. Pass 3 siempre se re-ejecuta. Las versiones anteriores pueden restaurarse desde los Master Plans.
+
+---
+
+## Estructura de Plantillas
+
+```
+pass-prompts/templates/
+├── common/                  # Encabezado/pie compartido
+├── java-spring/             # Java / Spring Boot
+├── node-express/            # Node.js / Express / NestJS
+├── node-nextjs/             # Next.js / React / Vue
+├── python-django/           # Python / Django (DRF)
+└── python-fastapi/          # Python / FastAPI
+```
+
+`plan-installer` auto-detecta tu(s) stack(s) y ensambla prompts específicos por tipo. Para proyectos multi-stack, se generan `pass1-backend-prompt.md` y `pass1-frontend-prompt.md` por separado, mientras que `pass3-prompt.md` combina los objetivos de generación de ambos stacks.
+
+---
+
+## Solución de Problemas
+
+**"claude: command not found"** — Claude Code CLI no está instalado o no está en el PATH. Consulta la [documentación de Claude Code](https://code.claude.com/docs/en/overview).
+
+**"npm install failed"** — La versión de Node.js puede ser demasiado baja. Se requiere v18+.
+
+**"0 domains detected"** — La estructura de tu proyecto puede ser no estándar. Consulta los patrones de detección en la [documentación en coreano](./README.ko.md#-문제-해결--troubleshooting) para tu stack.
+
+---
+
+## Contribuir
+
+¡Las contribuciones son bienvenidas! Áreas donde más se necesita ayuda:
+
+- **Nuevas plantillas de stack** — Ruby/Rails, Go/Gin, PHP/Laravel, Rust/Axum
+- **Soporte profundo para monorepos** — Raíces de sub-proyectos separadas, detección de workspaces
+- **Cobertura de tests** — Tests unitarios para todas las herramientas de verificación
+
+---
+
+## Autor
+
+Creado por **claudeos-core** — [GitHub](https://github.com/claudeos-core) · [Email](mailto:claudeoscore@gmail.com)
+
+## Licencia
+
+ISC