@morsa/guidance-bank 0.2.0

package/dist/core/projects/createBankDeriveGuidance/stacks/nextjs.js

@@ -0,0 +1,220 @@
+export const NEXTJS_DERIVE_GUIDANCE = `## Next.js Guidance
+
+Focus on Next.js-specific patterns: router mode, server/client boundaries, data fetching and caching strategy, route handlers, middleware, metadata, and runtime constraints.
+Apply React component/hook conventions from observed project patterns where relevant.
+
+## Codebase Exploration Before Generating
+
+### Structure Discovery
+
+1. List root folders.
+2. Identify Next.js source roots (\`app/\`, \`pages/\`, \`src/app/\`, \`src/pages/\`, \`components/\`, \`lib/\`).
+3. Detect route/layout structure 2-3 levels deep.
+4. Record the exact folder names and paths you found.
+
+### Router Mode Detection (Critical)
+
+Determine which routing model is actually used:
+- App Router (\`app/\`, route segments, \`layout.tsx\`, \`page.tsx\`, \`route.ts\`)
+- Pages Router (\`pages/\`, \`_app.tsx\`, \`_document.tsx\`, \`pages/api\`)
+- Mixed migration state
+
+Do not generate rules until router mode is explicit with file-path evidence.
+
+### Pattern Extraction (Read Real Files)
+
+For each category, read 2-3 representative files and extract reusable decisions:
+
+| Category | What to Find | What to Extract |
+|----------|--------------|-----------------|
+| Routing/Layout | Route segments and layouts | Route organization, segment conventions, nesting boundaries |
+| Server/Client split | \`use client\`, server components, client hooks | Boundary rules for where logic can run |
+| Data fetching/cache | \`fetch\`, cache/revalidate usage | Caching model, revalidation strategy, dynamic/static behavior |
+| API layer | \`route.ts\` or \`pages/api\` handlers | Request/response structure, auth/error handling, service usage |
+| Actions/mutations | Server actions/forms/mutations | Mutation flow and boundaries |
+| Middleware/Auth | \`middleware.ts\`, auth wrappers | Access control flow, redirect patterns, edge/runtime constraints |
+| Metadata/SEO | metadata exports and head patterns | Canonical metadata structure and ownership |
+| Styling/UI | CSS Modules/Tailwind/SCSS/design tokens | Styling conventions and composition patterns |
+| Testing | test setup and specs | Test location, mocking strategy, critical coverage expectations |
+
+### Config and Tooling Analysis (Next.js-Specific)
+
+Read these files if present:
+- package.json and lockfile
+- \`next.config.js\` / \`next.config.mjs\` / \`next.config.ts\`
+- \`middleware.ts\`
+- \`app/layout.tsx\`, \`app/page.tsx\`, nested segment files
+- \`pages/_app.tsx\`, \`pages/_document.tsx\`, \`pages/api/**\` (if Pages Router)
+- eslint config and formatting config
+- deployment/runtime config (edge/node settings if present)
+- monorepo config (\`nx.json\`, \`turbo.json\`, workspace manifests)
+
+### Version and Feature Gate (Next.js)
+
+Before turning patterns into rules, verify what is actually used in this codebase:
+- Next.js version from dependencies.
+- Router mode: App Router, Pages Router, or mixed.
+- Runtime target per area: Node.js runtime, Edge runtime, or mixed.
+- Use Server Actions only when App Router usage and code evidence support them.
+- Use \`route.ts\` handler conventions only when App Router API routes are present.
+- Use \`pages/api\` conventions only when Pages Router API routes are present.
+- Preserve observed caching model (\`revalidate\`, dynamic/static behavior, cache tags) instead of introducing new defaults.
+
+### Red Flag Detection (Next.js-Specific)
+
+Search for recurring issues that should become explicit rules:
+- mixed App Router and Pages Router patterns without clear boundaries
+- server/client boundary violations (client hooks in server components, server-only logic in client components)
+- inconsistent caching/revalidation strategy across similar routes
+- duplicated request/response logic across route handlers and services
+- heavy business logic in middleware
+- direct secret/runtime-dependent usage in client-side code
+- inconsistent error/not-found/redirect handling across route modules
+
+### Analysis Checklist (Next.js Project)
+
+Document these with file path evidence:
+
+- Router mode and route organization model.
+- Server/client component boundaries.
+- Data fetching and caching/revalidation strategy.
+- API route pattern and service integration.
+- Middleware/auth flow and runtime boundaries.
+- Metadata/SEO pattern and ownership.
+- Testing strategy and helper usage.
+- Styling mode and constraints.
+- Main recurring anti-patterns and where they appear.
+
+Before final output, gather concrete evidence for each applicable item.
+If evidence remains partial, continue conservatively and mark uncertainty with \`[VERIFY: ...]\` instead of blocking output.
+
+### Generation Locks (Prevent Architecture Drift)
+
+Apply these constraints when generating rules and skills:
+- Preserve detected router mode (App Router / Pages Router / mixed); do not migrate architecture implicitly.
+- Preserve server/client split boundaries; do not move logic across boundaries without evidence.
+- Preserve detected runtime targets and deployment assumptions (Node/Edge).
+- Preserve detected data fetching and caching model; avoid introducing incompatible defaults.
+- Preserve detected styling mode and monorepo boundaries when present.
+
+## Skill Candidates (Next.js)
+
+Generate these skills with actual project paths and Next.js-specific workflow steps:
+Generate only skills that have clear project evidence and practical value.
+For small/low-confidence projects, 2-4 core skills are usually enough.
+
+### adding-route
+- Include actual route segment or pages structure from this project.
+- Show how to add page/layout/route wiring using existing conventions.
+- Include data-loading and error/not-found handling integration where applicable.
+
+### adding-api-route
+- Include existing API route style (\`app/**/route.ts\` or \`pages/api/**\`).
+- Show request parsing, validation, service usage, and error response flow.
+- Include test or verification strategy used in this project.
+
+### code-review
+- Include Next.js-specific review checklist based on project patterns.
+- Cover router mode consistency, server/client boundaries, caching strategy, and runtime correctness.
+
+### common-anti-patterns
+- Include recurring Next.js anti-patterns from this project.
+- Pair each anti-pattern with preferred local alternative.
+
+### troubleshooting
+- Include common build/runtime/hydration/cache issues for this codebase.
+- Include where to inspect first when these issues happen.
+
+### [framework-specific]
+Generate 1-3 extra skills based on actual stack usage:
+- app-router-patterns (if App Router is primary)
+- pages-router-patterns (if Pages Router is primary)
+- server-actions-patterns (if Server Actions are primary)
+- middleware-auth-workflows (if middleware/auth is central)
+- monorepo-workflows (if apps/libs pattern exists)
+
+### enrichment-tasks (optional)
+- Generate this only when the user explicitly asks for enrichment, or when analysis shows a clear gap in the existing rule/skill bank.
+
+## Rule Generation Requirements
+
+### What NOT to Include
+
+- Do not invent generic philosophy ("clean code", "think about user").
+- Do not duplicate what linters/formatters fully enforce.
+- Do not add rules without evidence from codebase patterns.
+- Do not repeat the same rule across multiple rule topics.
+- Do not mix App Router and Pages Router conventions unless mixed mode is confirmed in this project.
+
+### Rule Content Requirements
+
+Keep this section Next.js-specific:
+- Capture decisions tied to router mode, server/client boundaries, caching strategy, API layer, and runtime model.
+- Use Next.js-native terminology aligned with observed project structure.
+- Highlight recurring Next.js anti-patterns and safer local alternatives.
+
+## Algorithm: Analysis -> Rules (Next.js)
+
+Follow this systematic approach for Next.js projects:
+
+**Router Structure -> Architecture Rules:**
+1. Determine router mode and segment organization.
+2. Define placement rules for pages/layouts/route handlers.
+3. Document allowed dependency directions between route modules and shared layers.
+
+**Server/Client Boundaries -> Runtime Rules:**
+1. Identify where server and client logic currently lives.
+2. Extract repeated boundary decisions for hooks, secrets, and side effects.
+3. Generate concise rules preserving those boundaries.
+
+**Data/API -> Flow Rules:**
+1. Identify fetching, caching, mutation, and API response patterns.
+2. Extract repeated error handling and validation conventions.
+3. Generate rules that keep data flow predictable across routes.
+
+**Configs -> Constraints Rules:**
+1. Inspect Next config, middleware, runtime/deployment settings.
+2. Promote only meaningful architectural constraints.
+3. Avoid restating trivial formatter/linter-only behavior.
+
+**Tests -> Testing Rules:**
+1. Identify where tests live and which module types are covered.
+2. Extract common test patterns and helper usage.
+3. Require tests for module types that are consistently tested in this project.
+
+## Recommended Rule Topics (Next.js Project)
+
+Split by topic:
+Generate only topics that are supported by concrete project evidence.
+
+| Topic | Covers (Next.js-Specific) |
+|------|----------------------------|
+| \`architecture\` | route/module boundaries, placement, dependency direction |
+| \`routing\` | App Router/Pages Router conventions, segments/pages/layouts |
+| \`server-client-boundaries\` | server vs client component boundaries and constraints |
+| \`data-fetching-cache\` | fetching model, cache/revalidate strategy, dynamic/static behavior |
+| \`api-routes\` | route handlers or pages/api conventions, request/response patterns |
+| \`middleware-auth\` | middleware flow, access control, redirects/runtime constraints |
+| \`components\` | UI composition patterns and file organization |
+| \`styling\` | CSS strategy, token usage, naming conventions |
+| \`testing\` | test placement, helpers, minimum critical checks |
+| \`error-handling\` | error mapping, not-found/redirect behavior, retry/logging boundaries |
+| \`i18n\` | localization key usage and routing integration (if applicable) |
+
+## Context-to-Rule/Skill Mapping (Next.js)
+
+Use this mapping to decide what files to generate:
+Generate only skills that are supported by concrete project evidence.
+
+| Found in Next.js Codebase | Generate Rule Topic | Generate Skill |
+|---------------------------|---------------------|----------------|
+| App Router segments/layouts | \`routing\`, \`architecture\` | \`adding-route\`, \`app-router-patterns\` |
+| Pages Router structure | \`routing\`, \`architecture\` | \`adding-route\`, \`pages-router-patterns\` |
+| Server/client boundary conventions | \`server-client-boundaries\` | \`code-review\` |
+| Structured fetch/cache/revalidate usage | \`data-fetching-cache\` | \`troubleshooting\` |
+| API route layer with shared services | \`api-routes\`, \`services-data\` | \`adding-api-route\` |
+| Middleware-driven auth/routing | \`middleware-auth\` | \`middleware-auth-workflows\` |
+| Monorepo boundary rules | \`architecture\` | \`monorepo-workflows\` |
+| Repeated runtime/hydration/cache issues | \`error-handling\` | \`troubleshooting\` |
+| Repeated unsafe patterns | \`error-handling\` | \`common-anti-patterns\` |
+`;

package/dist/core/projects/createBankDeriveGuidance/stacks/nodejs.js

@@ -0,0 +1,221 @@
+export const NODEJS_DERIVE_GUIDANCE = `## Node.js Backend Guidance
+
+Focus on Node.js backend patterns: HTTP/API architecture, service and data layers, validation, auth, error handling, background processing, and runtime/ops boundaries.
+Apply TypeScript guidance from the shared section only when the project uses TypeScript.
+
+## Codebase Exploration Before Generating
+
+### Structure Discovery
+
+1. List root folders.
+2. Identify backend source roots (for example: \`src/\`, \`apps/\`, \`services/\`, \`modules/\`, \`server/\`).
+3. Map API/module hierarchy 2-3 levels deep.
+4. Record exact folder names and paths.
+
+### Runtime and Framework Detection (Critical)
+
+Determine what backend style is actually used:
+- Express / Fastify / NestJS / Koa / custom HTTP server
+- Monolith service vs modular services
+- REST / RPC / GraphQL / mixed
+- ESM / CJS runtime mode (if relevant)
+
+Do not generate framework-specific rules until runtime/framework mode is explicit with file-path evidence.
+
+### Pattern Extraction (Read Real Files)
+
+For each category, read 2-3 representative files and extract reusable decisions:
+
+| Category | What to Find | What to Extract |
+|----------|--------------|-----------------|
+| Entry/bootstrap | server startup and app wiring | initialization order, middleware setup, module loading |
+| Routing/controllers | endpoint modules and handlers | handler structure, request/response flow, route organization |
+| Services/use-cases | business logic orchestration | service boundaries, dependency flow, transaction patterns |
+| Data layer | ORM/query/repository usage | data access boundaries, mapping, consistency rules |
+| Validation | request/input validation | schema location, validation timing, error shape |
+| Auth/security | auth guards/middleware | token/session flow, permission checks, sensitive-path handling |
+| Error handling/logging | global handlers and logger usage | error normalization, log structure, observability patterns |
+| Async/jobs/events | queues, workers, schedulers | job boundaries, retry/error handling, idempotency patterns |
+| Testing | test setup and suite structure | test location, integration/unit split, mocking style |
+
+### Config and Tooling Analysis (Node.js-Specific)
+
+Read these files if present:
+- package.json and lockfile
+- runtime config and env files (\`.env.example\`, config modules, secrets loading)
+- framework config (Nest config, Fastify plugins, Express wiring, GraphQL config, etc.)
+- DB/migration config (Prisma/TypeORM/Knex/Sequelize or equivalent)
+- queue/worker config (BullMQ, agenda, cron jobs, message consumers)
+- eslint and formatting config
+- deployment/runtime files (Dockerfile, compose, process manager config, CI scripts)
+- monorepo config (\`nx.json\`, \`turbo.json\`, workspace manifests)
+
+### Version and Feature Gate (Node.js)
+
+Before turning patterns into rules, verify what is actually used in this codebase:
+- Node.js version and module/runtime mode.
+- Backend framework mode and routing style.
+- Data layer style (ORM/query builder/raw SQL/repository wrappers).
+- Validation strategy and where it is enforced.
+- Auth strategy and boundary points.
+- Background processing model (queues/workers/schedulers), if present.
+- Do not introduce framework conventions not present in the project.
+
+### Red Flag Detection (Node.js-Specific)
+
+Search for recurring issues that should become explicit rules:
+- missing or inconsistent request validation on public endpoints
+- duplicated business logic between handlers/controllers
+- direct DB access from handlers when service/repository layer exists
+- inconsistent error responses across similar endpoints
+- logging sensitive fields or credentials
+- missing auth/permission checks on protected routes
+- long synchronous/blocking operations in request path
+- inconsistent transaction boundaries or partial failure handling
+- duplicated job/retry logic across workers
+
+### Analysis Checklist (Node.js Project)
+
+Document these with file path evidence:
+
+- Framework/runtime model and module organization.
+- Routing/controller conventions.
+- Service/data-layer boundaries and mapping style.
+- Validation and auth flow.
+- Error/logging standards.
+- Async/jobs/events architecture (if present).
+- Testing strategy and helper usage.
+- Deployment/runtime constraints.
+- Main recurring anti-patterns and where they appear.
+
+Before final output, gather concrete evidence for each applicable item.
+If evidence remains partial, continue conservatively and mark uncertainty with \`[VERIFY: ...]\` instead of blocking output.
+
+### Generation Locks (Prevent Architecture Drift)
+
+Apply these constraints when generating rules and skills:
+- Preserve detected framework/runtime mode; do not migrate architecture implicitly.
+- Preserve routing style and handler layering.
+- Preserve service/data boundaries and transaction model.
+- Preserve validation/auth/error contracts already used across endpoints.
+- Preserve async/job processing model when present.
+- Preserve deployment/runtime assumptions and monorepo boundaries when present.
+
+## Skill Candidates (Node.js)
+
+Generate these skills with actual project paths and Node.js-specific workflow steps:
+Generate only skills that have clear project evidence and practical value.
+For small/low-confidence projects, 2-4 core skills are usually enough.
+
+### adding-endpoint
+- Include actual route/controller/handler structure from this project.
+- Show validation, auth checks, service call, and response pattern based on local conventions.
+- Include verification or tests according to existing practices.
+
+### adding-service
+- Include actual service and data access structure used in this project.
+- Show dependency wiring, transaction/error handling, and integration points.
+- Include test/mocking strategy used for services in this codebase.
+
+### code-review
+- Include Node.js backend review checklist based on project patterns.
+- Cover validation, auth boundaries, error contracts, data layer boundaries, and logging hygiene.
+
+### common-anti-patterns
+- Include recurring backend anti-patterns from this project.
+- Pair each anti-pattern with preferred local alternative.
+
+### troubleshooting
+- Include common runtime/data/integration issues for this codebase.
+- Include where to inspect first when these issues happen.
+
+### [framework-specific]
+Generate 1-3 extra skills based on actual stack usage:
+- nestjs-patterns (if NestJS is primary)
+- express-fastify-patterns (if Express/Fastify style is primary)
+- data-access-patterns (if ORM/repository complexity is central)
+- jobs-workers-patterns (if queues/workers are central)
+- monorepo-workflows (if apps/libs pattern exists)
+
+### enrichment-tasks (optional)
+- Generate this only when the user explicitly asks for enrichment, or when analysis shows a clear gap in the existing rule/skill bank.
+
+## Rule Generation Requirements
+
+### What NOT to Include
+
+- Do not invent generic philosophy ("clean code", "think about user").
+- Do not duplicate what linters/formatters fully enforce.
+- Do not add rules without evidence from codebase patterns.
+- Do not repeat the same rule across multiple rule topics.
+- Do not introduce framework APIs or architectural layers not used in this backend.
+
+### Rule Content Requirements
+
+Keep this section Node.js-backend-specific:
+- Capture decisions tied to request flow, service/data boundaries, validation/auth, and error/logging contracts.
+- Use runtime/framework terminology aligned with observed project structure.
+- Highlight recurring backend anti-patterns and safer local alternatives.
+
+## Algorithm: Analysis -> Rules (Node.js)
+
+Follow this systematic approach for Node.js backends:
+
+**Structure -> Architecture Rules:**
+1. Identify repeated module and request-flow structures.
+2. Define placement rules for handlers/controllers, services, and data modules.
+3. Document allowed dependency directions.
+
+**Request Flow -> API Rules:**
+1. Scan representative route/controller/handler files.
+2. Extract repeated patterns for validation, auth, response shape, and error mapping.
+3. Convert repeated high-quality patterns into concise rules.
+
+**Service/Data -> Boundary Rules:**
+1. Identify service orchestration and data access boundaries.
+2. Extract transaction and error-handling conventions.
+3. Generate rules preserving those boundaries.
+
+**Async/Jobs -> Reliability Rules:**
+1. Inspect workers/queues/schedulers where present.
+2. Extract retry/idempotency and failure-handling patterns.
+3. Generate rules for reliable async processing.
+
+**Configs -> Runtime Constraints:**
+1. Inspect runtime/framework/deployment config files.
+2. Promote only meaningful architectural constraints.
+3. Avoid restating trivial formatter/linter-only behavior.
+
+## Recommended Rule Topics (Node.js Project)
+
+Split by topic:
+Generate only topics supported by concrete project evidence.
+
+| Topic | Covers (Node.js-Specific) |
+|------|----------------------------|
+| \`architecture\` | module boundaries, placement, dependency direction |
+| \`api-handlers\` | route/controller/handler organization and request flow |
+| \`services\` | business logic boundaries and orchestration patterns |
+| \`data-access\` | repositories/ORM/query layer patterns and transaction boundaries |
+| \`validation-auth\` | input validation and permission/auth boundaries |
+| \`error-logging\` | error normalization, logging patterns, observability boundaries |
+| \`jobs-workers\` | queue/worker/scheduler behavior and retry/idempotency |
+| \`testing\` | test placement, helper usage, minimum critical checks |
+| \`runtime-deploy\` | runtime assumptions, env/config boundaries, deployment constraints |
+
+## Context-to-Rule/Skill Mapping (Node.js)
+
+Use this mapping to decide what files to generate:
+Generate only skills that are supported by concrete project evidence.
+
+| Found in Node.js Codebase | Generate Rule Topic | Generate Skill |
+|---------------------------|---------------------|----------------|
+| Clear handler -> service -> repository flow | \`api-handlers\`, \`services\`, \`data-access\` | \`adding-endpoint\`, \`adding-service\` |
+| Strong validation/auth middleware usage | \`validation-auth\` | \`code-review\` |
+| Centralized error mapper/logger | \`error-logging\` | \`troubleshooting\` |
+| Worker/queue architecture | \`jobs-workers\` | \`jobs-workers-patterns\` |
+| NestJS module/controller/provider patterns | \`architecture\`, \`api-handlers\` | \`nestjs-patterns\` |
+| Express/Fastify route plugins and handlers | \`api-handlers\`, \`architecture\` | \`express-fastify-patterns\` |
+| Monorepo boundary rules | \`architecture\`, \`runtime-deploy\` | \`monorepo-workflows\` |
+| Repeated unsafe patterns | \`error-logging\` | \`common-anti-patterns\` |
+`;

package/dist/core/projects/createBankDeriveGuidance/stacks/other.js

@@ -0,0 +1,34 @@
+export const OTHER_DERIVE_GUIDANCE = `## Unknown or Mixed Stack Guidance
+
+The stack is not confidently identified or does not match known stack routes.
+Build stack-aware guidance without forcing unsupported framework assumptions.
+
+## Stack Identification Pass
+
+Infer the most likely stack from project fingerprints:
+- runtime/platform markers (for example: \`package.json\`, \`pyproject.toml\`, \`go.mod\`, \`pom.xml\`, \`*.csproj\`, \`Gemfile\`)
+- framework markers (dependencies, CLI configs, routing/bootstrap entry files)
+- build/test/tooling markers (linters, test runners, bundlers, CI scripts)
+
+Classify confidence explicitly:
+- high confidence: one dominant stack is clearly supported by code/config evidence
+- medium confidence: multiple plausible stacks or mixed architecture
+- low confidence: minimal or conflicting evidence
+
+## Stack-Specific Fallback Strategy
+
+- If confidence is high and trusted docs are helpful, use them only as a secondary source for best-practice alignment.
+- Keep project evidence as the primary source; external guidance should refine, not override, observed project patterns.
+- If confidence is medium/low, prefer conservative, technology-neutral rules and avoid stack-specific APIs not proven in the repository.
+
+## Output Size by Evidence Strength
+
+- High confidence + sufficient codebase: generate a normal stack-oriented set.
+- Medium confidence: generate a smaller set focused on stable cross-cutting decisions visible in code.
+- Low confidence or near-empty project: generate only a minimal scaffold that can evolve (baseline structure rules + a small core skill set).
+
+## Ambiguity Markers
+
+- Mark uncertain stack decisions with \`[VERIFY: what to confirm]\`.
+- Keep each uncertain point scoped and actionable for future refinement.
+`;