claudeos-core 1.6.2 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeos-core",
-  "version": "1.6.2",
+  "version": "1.7.0",
   "description": "Auto-generate Claude Code documentation from your actual source code — Standards, Rules, Skills, and Guides tailored to your project",
   "main": "bin/cli.js",
   "bin": {

package/pass-prompts/templates/common/pass3-footer.md

@@ -1,3 +1,23 @@
-
-After completion, run the following commands in order:
-1. npx claudeos-core health
+
+CRITICAL — No Hallucination Guard:
+You may ONLY reference technologies that are explicitly present in the two files you read:
+project-analysis.json (stack detection results) and pass2-merged.json (code analysis results).
+If a library, framework, tool, or pattern does NOT appear in either of these files,
+you MUST NOT mention it, generate code examples for it, or assume it exists — not in
+standards, rules, skills, guides, database docs, or CLAUDE.md.
+Do NOT infer or guess technologies from other detected technologies.
+Examples of violations:
+- Writing "React Query caching" when pass2-merged.json has no TanStack Query / React Query entry
+- Adding "Zustand store pattern" when pass2-merged.json has no Zustand usage
+- Generating "Prisma schema" examples when project-analysis.json ORM is not Prisma
+- Assuming React Query exists because Orval was detected (inference is NOT detection)
+When in doubt, omit. Missing content is fixable; hallucinated content erodes trust.
+
+CRITICAL — Skill Orchestrator Completeness:
+The orchestrator file (e.g., 01.scaffold-page-feature.md, 01.scaffold-crud-feature.md)
+MUST list ALL sub-skill files in its execution order table with no gaps.
+Every sub-skill file generated in the scaffold directory MUST have a corresponding row.
+Do NOT skip any number in the sequence.
+
+After completion, run the following commands in order:
+1. npx claudeos-core health

package/pass-prompts/templates/node-vite/pass1.md

@@ -0,0 +1,117 @@
+Read claudeos-core/generated/project-analysis.json and
+perform a deep analysis of the following domains only: {{DOMAIN_GROUP}}
+
+For each domain, select one representative file per layer, read its code, and analyze it.
+Prioritize files with the richest patterns.
+
+Analysis items (per domain):
+
+1. Page/Routing Patterns
+   - Client-side routing (React Router, TanStack Router, custom)
+   - Route definition approach (file-based, config-based, lazy loading)
+   - Layout structure (nested layouts, outlet, wrapper components)
+   - Dynamic routes and route parameters
+   - Route guards and authentication redirects
+   - Error/404 handling
+
+2. Component Patterns
+   - Component structure (functional, forwardRef, memo)
+   - Props type definition (interface vs type, Generic usage)
+   - State management (useState, useReducer, external libraries)
+   - Styling approach and exact import paths (e.g., `import styles from './index.module.scss'`, `import { cn } from '@/lib/utils'`)
+   - Styling utility functions: record the EXACT import path used in source code
+   - UI library and exact package names (e.g., `@mui/material`, `antd`, `@shadcn/ui`)
+   - Component classification (UI, Feature, Layout, Page)
+   - Component entry file pattern: is the main file `index.tsx` or `ComponentName.tsx`? Record exactly.
+   - Directory structure pattern: record exact convention
+   - export pattern: default export vs named export in component files
+   - Reuse patterns (composition, compound components, render props)
+   - Accessibility (ARIA, semantic HTML, keyboard navigation)
+
+3. Data Fetching Patterns
+   - Client-side data fetching (TanStack Query, SWR, useEffect, axios)
+   - API client configuration (base URL, interceptors, error handling)
+   - Request/response typing
+   - Caching strategy (query keys, stale time, refetch)
+   - Error/loading state handling
+   - Optimistic updates
+   - Pagination/infinite scroll patterns
+
+4. State Management Patterns
+   - Global state (Zustand, Redux Toolkit, Jotai, Recoil, Context)
+   - Server state (TanStack Query, SWR)
+   - URL state (searchParams, useNavigate)
+   - Form state (React Hook Form, Formik)
+   - Local component state patterns
+
+5. Configuration/Environment Patterns
+   - Environment variable management (VITE_ prefix convention, .env separation)
+   - vite.config settings (proxy, aliases, plugins)
+   - Build optimization (chunk splitting, dynamic imports)
+   - Path aliases (@/, src/)
+
+6. Logging/Monitoring Patterns
+   - Client error tracking (Sentry, DataDog RUM)
+   - Performance monitoring
+   - Analytics tools (Google Analytics, PostHog, Mixpanel)
+
+7. Testing Patterns
+   - Test framework (Vitest, Jest, Playwright, Cypress)
+   - Component testing (React Testing Library, Storybook)
+   - E2E testing strategy
+   - Mocking strategy (MSW, vi.mock)
+   - Test naming conventions
+
+8. Domain-Specific Patterns
+   - Authentication/authorization (session, token, OAuth)
+   - Internationalization (i18next, react-intl)
+   - File upload patterns
+   - Real-time features (WebSocket, SSE)
+   - API versioning strategy
+
+9. Anti-patterns / Inconsistencies
+   - Patterns inconsistent with other domains
+   - Performance issues (unnecessary re-renders, bundle size)
+   - Type safety issues
+   - Accessibility issues
+   - Security issues (XSS, CSRF)
+
+Do not create or modify source files. Analysis only.
+Save results to claudeos-core/generated/pass1-{{PASS_NUM}}.json in the following format:
+
+{
+  "analyzedAt": "ISO timestamp",
+  "passNum": {{PASS_NUM}},
+  "domains": ["auth", "dashboard", "settings", "shared"],
+  "analysisPerDomain": {
+    "dashboard": {
+      "representativeFiles": {
+        "page": "src/pages/dashboard/index.tsx",
+        "component": "src/components/dashboard/StatsCard.tsx",
+        "hook": "src/hooks/useDashboardData.ts",
+        "api": "src/api/dashboard.ts"
+      },
+      "patterns": {
+        "page": { ... },
+        "component": {
+          "entryFilePattern": "index.tsx or ComponentName.tsx",
+          "exportPattern": "default export or named export",
+          "stylingImport": "exact import statement used for styling utility",
+          "uiLibraryImport": "exact import statement for UI components",
+          ...
+        },
+        "dataFetching": { ... },
+        "stateManagement": { ... },
+        "config": { ... },
+        "logging": { ... },
+        "testing": { ... }
+      },
+      "specialPatterns": [],
+      "antiPatterns": []
+    }
+  },
+  "crossDomainCommon": {
+    "description": "Patterns commonly used across domains in this group",
+    "patterns": []
+  }
+}

package/pass-prompts/templates/node-vite/pass2.md

@@ -0,0 +1,78 @@
+Read all pass1-*.json files from the claudeos-core/generated/ directory and
+merge all domain analysis results into a single unified report.
+
+Merge items:
+
+1. Universal Patterns (shared by 100% of all domains)
+   - Page/routing structure (React Router / TanStack Router / custom)
+   - Component writing conventions (functional, Props types, styling)
+   - Data fetching strategy (TanStack Query, SWR, axios patterns)
+   - State management approach
+   - Error/loading handling patterns
+   - Route guard/protection patterns
+
+2. Majority Patterns (shared by 50%+ of domains)
+   - Specify which domains share them
+
+3. Domain-Specific Patterns (unique to a single domain)
+   - Auth: which domain
+   - Real-time features: which domain
+   - File upload: which domain
+   - i18n: which domain
+
+4. Anti-pattern Summary
+   - Consolidate all inconsistencies found across domains
+   - Classify by severity (CRITICAL / HIGH / MEDIUM / LOW)
+
+5. Naming Conventions Summary
+   - File/directory naming (kebab-case, PascalCase)
+   - Component entry file pattern (index.tsx vs ComponentName.tsx — pick ONE that the project actually uses)
+   - Component export pattern (default export vs named export)
+   - Hook naming (use* prefix)
+   - API function patterns
+
+6. Shared Types/Components List
+   - Common UI components with EXACT import paths
+   - Shared hooks with exact import paths
+   - Utility functions with EXACT import paths
+   - Path aliases used in the project (e.g., `@/` -> `src/`)
+   - Environment variable types
+   - Constants/Enum management
+
+7. Security/Authentication Patterns
+   - Authentication approach (JWT, session, OAuth)
+   - Route protection strategy
+   - CSRF/XSS prevention
+   - Environment variable management (VITE_ convention)
+
+8. Database Patterns
+   - API endpoint conventions
+   - Request/response format
+   - Error response handling
+
+9. Testing Strategy Summary
+   - Test coverage level
+   - Test classification system (unit/component/E2E)
+   - Mocking strategy (MSW, vi.mock)
+   - Storybook usage
+   - Test naming conventions
+
+10. Logging/Monitoring Strategy
+    - Error tracking approach (Sentry, DataDog)
+    - Analytics tools
+    - Performance monitoring
+
+11. Performance Patterns
+    - Code splitting strategy (lazy, Suspense)
+    - Bundle optimization (chunk splitting, tree shaking)
+    - Image optimization
+    - Caching strategy
+
+12. Code Quality Tools
+    - Lint/Format tools (ESLint, Prettier, Biome)
+    - Pre-commit hooks (husky, lint-staged)
+    - TypeScript strict mode
+    - CI integration status
+
+Do not generate code. Merge only.
+Save results to claudeos-core/generated/pass2-merged.json.

package/pass-prompts/templates/node-vite/pass3.md

@@ -0,0 +1,103 @@
+Read claudeos-core/generated/project-analysis.json and
+claudeos-core/generated/pass2-merged.json, then
+generate all ClaudeOS-Core files based on the analysis results.
+
+Do not read the original source code again. Reference only the analysis results.
+
+CRITICAL — Package Manager Consistency:
+Check `stack.packageManager` in project-analysis.json (e.g., "pnpm", "yarn", "npm").
+ALL generated files MUST use ONLY that detected package manager's commands.
+NEVER mix npm/yarn/pnpm commands. Also check `scripts` field in the project's package.json
+for actual script names.
+
+CRITICAL — Cross-file Consistency:
+Rules (.claude/rules/) and Standards (claudeos-core/standard/) MUST NOT contradict each other.
+
+CRITICAL — Code Example Accuracy:
+ALL code examples in rules and standards MUST use EXACT method names, class names,
+and signatures from pass2-merged.json analysis data.
+Do NOT paraphrase, rename, or infer API names.
+
+CRITICAL — CLAUDE.md Reference Table Completeness:
+The reference table in CLAUDE.md MUST list ALL generated standard files.
+
+Generation targets:
+
+1. CLAUDE.md (project root)
+   - Role definition (based on detected stack — Vite + React SPA)
+   - Build & Run Commands (use ONLY the detected packageManager)
+   - Core architecture diagram (client-side SPA, routing, state management)
+   - Directory structure description
+   - Standard/Skills/Guide reference table
+
+2. claudeos-core/standard/ (active domains only)
+   - 00.core/01.project-overview.md — Stack, routing approach, deployment environment
+   - 00.core/02.architecture.md — SPA structure, component hierarchy, data flow
+   - 00.core/03.naming-conventions.md — File/component/hook/type naming conventions
+   - 20.frontend-ui/01.component-patterns.md — Component writing rules, Props patterns, reuse
+   - 20.frontend-ui/02.page-routing-patterns.md — Client-side routing, layouts, route guards, lazy loading
+   - 20.frontend-ui/03.data-fetching.md — API client, TanStack Query/SWR, caching, error handling
+   - 20.frontend-ui/04.state-management.md — Global/server/URL/form state management
+   - 20.frontend-ui/05.styling-patterns.md — Styling rules, theming, responsive, accessibility
+   - 30.security-db/01.security-auth.md — Auth patterns, token management, route protection, environment variables
+   - 40.infra/01.environment-config.md — Environment variables (VITE_ prefix), vite.config, build optimization
+   - 40.infra/02.logging-monitoring.md — Error tracking, analytics tools, performance monitoring
+   - 40.infra/03.cicd-deployment.md — CI/CD, static hosting deployment (Nginx, S3, Vercel, Netlify)
+   - 50.verification/01.development-verification.md — Build, startup, dev server
+   - 50.verification/02.testing-strategy.md — Testing strategy (Vitest, RTL, E2E, Storybook)
+
+   Each file MUST include:
+   - Correct examples (code blocks)
+   - Incorrect examples (code blocks)
+   - Key rules summary table
+
+3. .claude/rules/ (active domains only)
+   - Write the full rule content directly in each file (self-contained, no external references)
+   - Include 5-15 lines of key rules with concrete examples
+   - Do NOT use @import — it is not a Claude Code feature and does not work
+   - Each rule file MUST end with a `## Reference` section linking to the corresponding standard file(s):
+     ```
+     ## Reference
+     > For detailed patterns and examples, Read: claudeos-core/standard/20.frontend-ui/01.component-patterns.md
+     ```
+   - `paths:` frontmatter per rule category:
+     - `00.core/*` rules: `paths: ["**/*"]`
+     - `20.frontend/*` rules: `paths: ["**/*"]`
+     - `30.security-db/*` rules: `paths: ["**/*"]`
+     - `40.infra/*` rules: `paths: ["**/*.json", "**/*.env*", "**/vite.config.*", "**/Dockerfile*", "**/*.yml", "**/*.yaml"]`
+     - `50.sync/*` rules: `paths: ["**/claudeos-core/**", "**/.claude/**"]`
+   - MUST generate `.claude/rules/00.core/00.standard-reference.md` — directory of all standard files.
+
+4. .claude/rules/50.sync/ (3 sync rules)
+   - 01.standard-sync.md — Remind AI to update plan/10 when standard is modified
+   - 02.rules-sync.md — Remind AI to update plan/20 when rules is modified
+   - 03.skills-sync.md — Remind AI to update plan/30 when skills is modified
+
+5. claudeos-core/skills/ (active domains only)
+   - 20.frontend-page/01.scaffold-page-feature.md (orchestrator)
+   - 20.frontend-page/scaffold-page-feature/01~08 (sub-skills: page, layout, component, hook, api-client, test, style, index)
+   - 00.shared/MANIFEST.md (skill registry)
+
+6. claudeos-core/guide/ (all)
+   - 01.onboarding/01.overview.md
+   - 01.onboarding/02.quickstart.md
+   - 01.onboarding/03.glossary.md
+   - 02.usage/01.faq.md
+   - 02.usage/02.real-world-examples.md
+   - 02.usage/03.do-and-dont.md
+   - 03.troubleshooting/01.troubleshooting.md
+   - 04.architecture/01.file-map.md
+   - 04.architecture/02.pros-and-cons.md
+
+7. claudeos-core/plan/ (Master Plan)
+   - 10.standard-master.md — CLAUDE.md + all standard/ files as <file> blocks
+   - 20.rules-master.md — All rules/ (except sync) as <file> blocks
+   - 21.sync-rules-master.md — All sync rules (code block format)
+   - 30.frontend-skills-master.md — All frontend skills as <file> blocks
+   - 40.guides-master.md — All guide/ files as <file> blocks
+
+8. claudeos-core/database/
+   - 01.schema-overview.md — API endpoint catalog, request/response schemas (if applicable)
+
+9. claudeos-core/mcp-guide/
+   - 01.mcp-overview.md — List of MCP servers in use, integration methods

package/plan-installer/domain-grouper.js

@@ -1,73 +1,75 @@
-/**
- * ClaudeOS-Core — Domain Grouper
- *
- * Splits domains into analysis groups, determines active domains,
- * and selects appropriate templates based on detected stack.
- */
-
-function splitDomainGroups(domains, type, template) {
-  const MAX_FILES_PER_GROUP = 40;
-  const MAX_DOMAINS_PER_GROUP = 4;
-  const groups = [];
-  let current = [];
-  let fileCount = 0;
-
-  for (const d of domains) {
-    // Flush current group before adding if it would exceed limits
-    if (current.length > 0 && (fileCount + d.totalFiles > MAX_FILES_PER_GROUP || current.length >= MAX_DOMAINS_PER_GROUP)) {
-      groups.push({ type, template, domains: [...current], estimatedFiles: fileCount });
-      current = [];
-      fileCount = 0;
-    }
-    current.push(d.name);
-    fileCount += d.totalFiles;
-  }
-  if (current.length > 0) {
-    groups.push({ type, template, domains: [...current], estimatedFiles: fileCount });
-  }
-
-  return groups;
-}
-
-// ─── Determine active domains ───────────────────────────────────
-function determineActiveDomains(stack) {
-  const isBackend = !!stack.framework;
-  return {
-    "00.core": true,
-    "10.backend": !!isBackend,
-    "20.frontend": !!stack.frontend,
-    "30.security-db": !!(stack.database || stack.framework),
-    "40.infra": true,
-    "50.verification": true,
-    "90.optional": true,
-  };
-}
-
-// ─── Template selection (multi-stack) ──────────────────────────────
-function selectTemplates(stack) {
-  const templates = { backend: null, frontend: null };
-
-  // Backend template (requires a backend framework; language-only fallback skipped for pure frontend projects)
-  if (stack.language === "kotlin") templates.backend = "kotlin-spring";
-  else if (stack.language === "java") templates.backend = "java-spring";
-  else if (stack.framework === "nestjs") templates.backend = "node-nestjs";
-  else if (stack.framework === "express") templates.backend = "node-express";
-  else if (stack.framework === "fastify") templates.backend = "node-fastify";
-  else if (stack.framework === "django") templates.backend = "python-django";
-  else if (stack.framework === "fastapi" || stack.framework === "flask") templates.backend = "python-fastapi";
-  else if ((stack.language === "typescript" || stack.language === "javascript") && stack.framework) templates.backend = "node-express";
-  else if (stack.language === "python" && stack.framework) templates.backend = "python-fastapi";
-
-  // Frontend template
-  if (stack.frontend === "nextjs" || stack.frontend === "react") {
-    templates.frontend = "node-nextjs";
-  } else if (stack.frontend === "vue") {
-    templates.frontend = "vue-nuxt";
-  } else if (stack.frontend === "angular") {
-    templates.frontend = "angular";
-  }
-
-  return templates;
-}
-
-module.exports = { splitDomainGroups, determineActiveDomains, selectTemplates };
+/**
+ * ClaudeOS-Core — Domain Grouper
+ *
+ * Splits domains into analysis groups, determines active domains,
+ * and selects appropriate templates based on detected stack.
+ */
+
+function splitDomainGroups(domains, type, template) {
+  const MAX_FILES_PER_GROUP = 40;
+  const MAX_DOMAINS_PER_GROUP = 4;
+  const groups = [];
+  let current = [];
+  let fileCount = 0;
+
+  for (const d of domains) {
+    // Flush current group before adding if it would exceed limits
+    if (current.length > 0 && (fileCount + d.totalFiles > MAX_FILES_PER_GROUP || current.length >= MAX_DOMAINS_PER_GROUP)) {
+      groups.push({ type, template, domains: [...current], estimatedFiles: fileCount });
+      current = [];
+      fileCount = 0;
+    }
+    current.push(d.name);
+    fileCount += d.totalFiles;
+  }
+  if (current.length > 0) {
+    groups.push({ type, template, domains: [...current], estimatedFiles: fileCount });
+  }
+
+  return groups;
+}
+
+// ─── Determine active domains ───────────────────────────────────
+function determineActiveDomains(stack) {
+  const isBackend = !!stack.framework && stack.framework !== "vite";
+  return {
+    "00.core": true,
+    "10.backend": !!isBackend,
+    "20.frontend": !!stack.frontend,
+    "30.security-db": !!(stack.database || isBackend || stack.frontend),
+    "40.infra": true,
+    "50.verification": true,
+    "90.optional": true,
+  };
+}
+
+// ─── Template selection (multi-stack) ──────────────────────────────
+function selectTemplates(stack) {
+  const templates = { backend: null, frontend: null };
+
+  // Backend template (requires a backend framework; language-only fallback skipped for pure frontend projects)
+  if (stack.language === "kotlin") templates.backend = "kotlin-spring";
+  else if (stack.language === "java") templates.backend = "java-spring";
+  else if (stack.framework === "nestjs") templates.backend = "node-nestjs";
+  else if (stack.framework === "express") templates.backend = "node-express";
+  else if (stack.framework === "fastify") templates.backend = "node-fastify";
+  else if (stack.framework === "django") templates.backend = "python-django";
+  else if (stack.framework === "fastapi" || stack.framework === "flask") templates.backend = "python-fastapi";
+  else if ((stack.language === "typescript" || stack.language === "javascript") && stack.framework && stack.framework !== "vite") templates.backend = "node-express";
+  else if (stack.language === "python" && stack.framework) templates.backend = "python-fastapi";
+
+  // Frontend template
+  if (stack.frontend === "nextjs") {
+    templates.frontend = "node-nextjs";
+  } else if (stack.frontend === "react") {
+    templates.frontend = stack.framework === "vite" ? "node-vite" : "node-nextjs";
+  } else if (stack.frontend === "vue") {
+    templates.frontend = "vue-nuxt";
+  } else if (stack.frontend === "angular") {
+    templates.frontend = "angular";
+  }
+
+  return templates;
+}
+
+module.exports = { splitDomainGroups, determineActiveDomains, selectTemplates };