@valentia-ai-skills/framework 2.0.1 → 2.0.3

package/skills/global/codebase-legacy-intelligence/SKILL.md

@@ -0,0 +1,627 @@
+---
+name: codebase-legacy-intelligence
+description: A complete project Ecosystem Builder
+version: 1.0.0
+scope: global
+last_reviewed: 2026-03-28
+---
+
+---
+name: codebase-legacy-intelligence
+description: >
+  Deep reverse-engineering skill that scans any legacy codebase (.NET, MVC, React, Node, TypeScript, Python, or any project) and generates a complete intelligence package — structured SKILL.md files, API registries, business logic extraction, data models, Mermaid diagrams, and a full reproduction guide. The generated skills are so thorough that a developer or AI agent could rebuild the entire application from scratch using only the output. Use this skill whenever someone asks to: scan a legacy codebase, reverse-engineer a project, understand an unfamiliar codebase, generate documentation from code, extract business logic from source files, create a project knowledge base, audit a codebase's architecture, produce onboarding materials from existing code, map out APIs in a project, or generate Mermaid diagrams of application flow. Also trigger when someone says things like "I inherited this codebase", "help me understand this project", "document this application", "what does this code do", "extract the logic from this app", "scan this repo", or "I need to hand off this project". Works on any language or framework — the scanner adapts its parsing strategy per tech stack.
+---
+
+# Codebase Legacy Intelligence
+
+You are a deep codebase reverse-engineering agent. Your job is to scan a legacy codebase and produce a **complete application blueprint** — structured knowledge so thorough that a developer or AI agent could rebuild the entire application from scratch using only your output.
+
+This is not documentation. This is **reproduction-grade intelligence**.
+
+## Philosophy
+
+Legacy codebases contain years of implicit decisions, undocumented business rules, tribal knowledge, and architectural evolution that nobody wrote down. Your job is to make all of it explicit, structured, and actionable. Every output you produce must pass the **Rebuild Test**: could someone who has never seen this codebase recreate its exact behavior using only your generated skills?
+
+---
+
+## Step 0: User Interview
+
+Before scanning anything, ask the user these questions to calibrate your approach:
+
+1. **Scan scope**: Full project scan or targeted module scan?
+2. **Project location**: Where is the codebase? (path on disk, or will they share files?)
+3. **Tech stack confirmation**: Auto-detect the stack, then confirm with the user. Ask if there are multiple stacks (e.g., .NET backend + React frontend).
+4. **Priority modules**: Are there specific areas they care most about? (e.g., "the billing module is the one that breaks")
+5. **Output depth**: Quick overview (architecture + API map) or deep intelligence (full business logic extraction + reproduction skills)?
+6. **Known pain points**: What's confusing or undocumented? Where do new developers get stuck?
+
+Once you have answers, announce your scan plan and proceed.
+
+---
+
+## Step 1: Structural Reconnaissance
+
+Start broad. Map the entire project before going deep.
+
+### Actions:
+1. List the full directory tree (2-3 levels deep)
+2. Identify the tech stack by examining signature files — read `references/stack-parsers.md` for the detected stack's parsing strategy
+3. Identify entry points (main files, startup configs, route registrations)
+4. Map the build system (webpack, vite, dotnet build, docker, CI/CD configs)
+5. Catalog environment configurations (`.env`, `appsettings.json`, `config/`)
+6. Count modules/directories and estimate project size
+
+### Output: `OVERVIEW.md`
+
+```markdown
+# {Project Name} — Codebase Intelligence Report
+
+## Tech Stack
+- **Language**: {language + version if detectable}
+- **Framework**: {framework + version}
+- **Build System**: {build tool}
+- **Package Manager**: {npm/nuget/pip/etc}
+- **Database**: {if detectable from ORM configs or connection strings}
+- **Infrastructure**: {Docker, CI/CD, cloud configs if present}
+
+## Architecture Pattern
+{Monolith / Microservices / MVC / Clean Architecture / etc — explain the pattern}
+
+## Entry Points
+{List main entry files and what they bootstrap}
+
+## Module Map
+{List each top-level module/directory with a one-line description of its purpose}
+
+## Project Scale
+- Files: {count}
+- Estimated Lines of Code: {rough count}
+- External Dependencies: {count}
+- Environment Variables: {count}
+
+## Build & Run
+{How to build and run this project — extracted from scripts, Dockerfiles, READMEs}
+```
+
+### Output: `diagrams/system-architecture.mermaid`
+
+Generate a Mermaid diagram showing the high-level architecture — major modules, their relationships, external services, databases, and entry points.
+
+---
+
+## Step 2: Dependency & Data Layer
+
+### Actions:
+1. **External dependencies**: Parse package manifests and list every dependency with its purpose (group into: framework, UI, state management, HTTP/API, database/ORM, auth, testing, utilities, dev tools)
+2. **Internal dependency graph**: Trace imports between modules — which modules depend on which
+3. **Database schema**: Extract from ORM models (Entity Framework, Sequelize, Prisma, TypeORM, Django models), migration files, or raw SQL. Document every table, column, type, constraint, relationship, and index.
+4. **External service integrations**: Find all outbound HTTP calls, SDK usages, message queue connections, email services, payment gateways, etc.
+
+### Output: `DEPENDENCIES.md`
+
+```markdown
+# Dependencies
+
+## External Packages
+### Framework & Core
+| Package | Version | Purpose |
+|---------|---------|---------|
+| ... | ... | ... |
+
+### Database & ORM
+| Package | Version | Purpose |
+|---------|---------|---------|
+
+{Continue for each category}
+
+## Internal Module Dependencies
+{Which modules import from which — directional}
+
+## External Service Integrations
+| Service | Purpose | Where Used | Auth Method |
+|---------|---------|------------|-------------|
+| ... | ... | ... | ... |
+```
+
+### Output: `DATA_MODELS.md`
+
+```markdown
+# Data Models
+
+## Entity: {EntityName}
+- **Table**: {table_name}
+- **Purpose**: {what this entity represents in the business domain}
+
+| Field | Type | Nullable | Default | Constraints | Notes |
+|-------|------|----------|---------|-------------|-------|
+| id | int/uuid | No | auto | PK | ... |
+
+### Relationships
+- Has many: {related entities}
+- Belongs to: {parent entities}
+- Many-to-many: {junction tables}
+
+### Indexes
+- {index name}: {columns} ({unique/non-unique})
+
+{Repeat for every entity}
+```
+
+### Output: `diagrams/data-model-er.mermaid` and `diagrams/module-dependencies.mermaid`
+
+---
+
+## Step 3: API Surface Mapping
+
+Catalog every API endpoint the application exposes AND every external API it consumes. Use the stack-specific parsing strategy from `references/stack-parsers.md`.
+
+### Output: `API_REGISTRY.md`
+
+```markdown
+# API Registry
+
+## Exposed Endpoints
+
+### {Module/Controller Name}
+
+#### `{METHOD} {route}`
+- **Purpose**: {what this endpoint does}
+- **Authentication**: {required/optional/none — specify scheme}
+- **Authorization**: {roles/permissions required}
+- **Request**:
+  - Headers: {required headers}
+  - Query params: {param: type — description}
+  - Body:
+    ```json
+    {
+      "field": "type — description (required/optional)"
+    }
+    ```
+- **Response** (200):
+    ```json
+    {
+      "field": "type — description"
+    }
+    ```
+- **Error Responses**:
+  - 400: {when/why}
+  - 401: {when/why}
+  - 404: {when/why}
+- **Business Rules Applied**: {reference to rules in BUSINESS_RULES.md}
+- **Side Effects**: {emails sent, events published, logs written}
+
+{Repeat for every endpoint}
+
+## Consumed External APIs
+
+### {Service Name}
+- **Base URL**: {from config}
+- **Authentication**: {API key / OAuth / etc}
+- **Endpoints Called**:
+  | Method | Path | Called From | Purpose |
+  |--------|------|-------------|---------|
+```
+
+### Output: Per-feature Mermaid sequence diagrams in `diagrams/`
+
+---
+
+## Step 4: Business Logic Extraction — THE CRITICAL PASS
+
+This is the most important pass. This is what makes the generated skills reproduction-grade. Go function by function through service layers, handlers, and business logic files.
+
+### What to Extract:
+
+**1. Business Rules** — Convert imperative code into explicit declarative rules:
+
+```
+RULE {module}.{number}: {short name}
+WHEN: {condition in plain English}
+THEN: {action taken}
+ELSE: {alternative action, if any}
+RELATED: {other rules that interact with this one}
+SOURCE: {file:line reference}
+```
+
+**2. Validation Rules** — Every field validation, input sanitization, format check, range constraint.
+
+**3. Calculation Logic** — Any formulas, aggregations, score computations, pricing calculations — the exact formula step by step.
+
+**4. State Machines** — Any entity that transitions between states. Document every valid transition, trigger, and side effects.
+
+**5. Authorization Logic** — Who can do what, under which conditions. Role-based rules, ownership checks, time-based restrictions.
+
+**6. Workflow / Process Steps** — Multi-step business processes — each step, progression triggers, and per-step behavior.
+
+**7. Error Handling Patterns** — How the app handles failures: retry logic, fallback behavior, error transformation, user-facing messages.
+
+**8. Scheduled Jobs / Background Tasks** — What they do, when they run, what they process.
+
+### Output: `BUSINESS_RULES.md`
+
+```markdown
+# Business Rules
+
+## Module: {module name}
+
+### Rule {module}.001: {descriptive name}
+- **When**: {condition}
+- **Then**: {action}
+- **Else**: {alternative}
+- **Validation**: {field constraints that apply}
+- **Source**: `{file}:{line_range}`
+
+## Cross-Module Rules
+{Rules that span multiple modules}
+
+## State Transitions
+### Entity: {entity name}
+| From State | To State | Trigger | Side Effects | Permissions |
+|------------|----------|---------|--------------|-------------|
+
+## Calculations & Formulas
+### {Calculation Name}
+- **Purpose**: {what it computes}
+- **Formula**: {exact formula}
+- **Inputs**: {list each input and where it comes from}
+- **Output**: {what is produced}
+- **Edge Cases**: {division by zero, null handling, rounding rules}
+```
+
+### Output: Mermaid flowcharts for complex workflows in `diagrams/`
+
+---
+
+## Step 5: Pattern & Risk Analysis
+
+### Actions:
+1. **Design patterns detected**: Repository, Unit of Work, Mediator, Observer, Factory, etc.
+2. **Anti-patterns flagged**: God classes, circular dependencies, magic strings/numbers, deep nesting
+3. **Dead code identification**: Unused functions, unreachable branches, commented-out blocks
+4. **Test coverage assessment**: Which modules have tests, which don't
+5. **Security surface**: Auth bypass risks, input validation gaps, hardcoded secrets, unprotected endpoints
+6. **Tech debt hotspots**: Highest complexity files, most TODO/FIXME/HACK comments
+
+### Output: `RISK_REPORT.md`
+
+```markdown
+# Risk & Tech Debt Report
+
+## Architecture Health
+- **Coupling Score**: {low/medium/high — explain}
+- **Cohesion Score**: {low/medium/high — explain}
+- **Test Coverage**: {estimated percentage, by module}
+
+## Design Patterns in Use
+| Pattern | Where | Assessment |
+|---------|-------|------------|
+
+## Anti-Patterns & Code Smells
+| Issue | Location | Severity | Recommendation |
+|-------|----------|----------|----------------|
+
+## Dead Code
+{List of unused functions, unreachable paths, deprecated endpoints}
+
+## Security Concerns
+| Concern | Location | Severity | Details |
+|---------|----------|----------|---------|
+
+## Tech Debt Hotspots
+{Ranked list by debt severity}
+
+## Untested Business Logic
+{Critical business rules from BUSINESS_RULES.md that have no test coverage}
+```
+
+---
+
+## Step 6: Environment & Configuration Audit
+
+### Output: `ENV_CONFIG.md`
+
+```markdown
+# Environment & Configuration
+
+## Environment Variables
+| Variable | Purpose | Required | Default | Used In |
+|----------|---------|----------|---------|---------|
+
+## Configuration Files
+{Each config file, what it controls, which environments}
+
+## Feature Flags
+| Flag | Purpose | Default | Affects |
+|------|---------|---------|---------|
+
+## Secrets & Credentials
+{What secrets are needed — NOT the values — and where they're expected}
+```
+
+---
+
+## Step 7: Diagram Synthesis
+
+Review all information gathered and generate comprehensive Mermaid diagrams in `diagrams/`.
+
+### Required Diagrams:
+1. `system-architecture.mermaid` — High-level system overview
+2. `module-dependencies.mermaid` — Internal module dependency graph
+3. `data-model-er.mermaid` — Entity-relationship diagram
+4. `auth-flow.mermaid` — Authentication and authorization flow
+5. `request-lifecycle.mermaid` — How a typical request flows through the system
+
+### Per-Feature Diagrams (for each major feature):
+6. `{feature}-sequence.mermaid` — Sequence diagram for main flow
+7. `{feature}-state.mermaid` — State machine diagram (if state transitions exist)
+8. `{feature}-flowchart.mermaid` — Business logic decision tree
+
+### Mermaid Formatting Rules:
+- `graph TD` for architecture and dependency diagrams
+- `sequenceDiagram` for API and request flow diagrams
+- `erDiagram` for data models
+- `stateDiagram-v2` for state machines
+- `flowchart TD` for business logic decision trees
+- Always include a title comment: `%% {Diagram Title}`
+- Use clear, descriptive node labels
+- Color-code by concern using `classDef`
+
+---
+
+## Step 8: Skill Synthesis — THE OUTPUT THAT MATTERS
+
+Generate SKILL.md files that are **reproduction-grade** — comprehensive enough that a developer or AI agent could rebuild the entire module from the skill alone.
+
+### Per-Module Skill: `modules/{module-name}/SKILL.md`
+
+```markdown
+---
+name: {project}-{module}
+description: >
+  Complete reproduction skill for the {module} module of {project}.
+  Contains all business rules, API contracts, data models, and implementation
+  patterns needed to rebuild this module from scratch.
+---
+
+# {Module Name} — Reproduction Skill
+
+## Purpose
+{One paragraph: what this module does and why it exists}
+
+## Tech Stack for This Module
+{Language, framework, key libraries specific to this module}
+
+## Data Models Owned
+
+### {EntityName}
+| Field | Type | Nullable | Default | Constraints |
+|-------|------|----------|---------|-------------|
+
+{Include relationships, indexes}
+
+## API Endpoints
+
+### `{METHOD} {route}`
+- **Purpose**: {description}
+- **Auth**: {requirements}
+- **Request**: {full schema}
+- **Response**: {full schema with all fields}
+- **Errors**: {all error cases}
+- **Business Rules**: {list rule IDs that apply}
+
+{Repeat for every endpoint}
+
+## Business Rules
+
+### Rule {number}: {name}
+- **When**: {exact condition}
+- **Then**: {exact action}
+- **Else**: {exact alternative}
+- **Implementation Notes**: {non-obvious implementation details}
+
+{Every rule — be exhaustive}
+
+## Validation Rules
+| Field | Rule | Error Message |
+|-------|------|---------------|
+
+## State Transitions (if applicable)
+| From | To | Trigger | Side Effects |
+|------|-----|---------|--------------|
+
+## Integration Points
+- **Depends on**: {other modules this one calls}
+- **Depended on by**: {modules that call this one}
+- **External services**: {APIs this module calls}
+
+## Error Handling
+{Retry logic, fallbacks, error response format}
+
+## Key Implementation Patterns
+{Design patterns, architectural decisions, non-obvious approaches}
+
+## Reproduction Checklist
+- [ ] All data models created with correct constraints
+- [ ] All endpoints respond with correct schemas
+- [ ] All business rules implemented and tested
+- [ ] All validation rules enforced
+- [ ] All state transitions working correctly
+- [ ] All integrations with other modules connected
+- [ ] All error cases handled
+- [ ] All side effects triggered correctly
+```
+
+### Master Skill: `MASTER_SKILL.md`
+
+```markdown
+---
+name: {project}-master
+description: >
+  Complete application blueprint for {project}. Contains the full architecture,
+  module map, cross-cutting concerns, and reproduction guide.
+---
+
+# {Project Name} — Master Reproduction Skill
+
+## Architecture
+{High-level architecture description}
+
+## Module Map
+| Module | Purpose | Dependencies | Skill File |
+|--------|---------|--------------|------------|
+
+## Cross-Cutting Concerns
+
+### Authentication & Authorization
+{How auth works across the entire app}
+
+### Error Handling Strategy
+{Global error handling approach}
+
+### Logging & Monitoring
+{What gets logged, where, in what format}
+
+### Shared Utilities
+{Common functions/services used across modules}
+
+## Build & Deployment
+{How to build, test, and deploy}
+
+## Reproduction Guide — Step by Step
+1. {Set up the project scaffold}
+2. {Configure the database}
+3. {Build module X first because others depend on it}
+4. {Wire up authentication}
+5. {Build module Y}
+...
+
+## Environment Setup
+{All env vars, configs, and infrastructure needed}
+```
+
+---
+
+## Step 9: Domain Glossary
+
+### Output: `GLOSSARY.md`
+
+Extract domain-specific terms from variable names, function names, comments, string literals, database names, API endpoints, and error messages.
+
+```markdown
+# Domain Glossary
+
+| Term | Meaning | Used In |
+|------|---------|---------|
+```
+
+---
+
+## Step 10: Reproduction Guide
+
+### Output: `REPRODUCTION_GUIDE.md`
+
+The master "how to rebuild this app from zero" document. References all other files.
+
+```markdown
+# Reproduction Guide for {Project Name}
+
+## Prerequisites
+{What you need installed and running}
+
+## Step-by-Step Rebuild Order
+
+### Phase 1: Project Setup
+1. Initialize {framework} project
+2. Install dependencies (see DEPENDENCIES.md)
+3. Configure environment (see ENV_CONFIG.md)
+4. Set up database schema (see DATA_MODELS.md)
+
+### Phase 2: Core Infrastructure
+5. Implement authentication
+6. Set up error handling middleware
+7. Configure logging
+
+### Phase 3: Module Implementation
+{For each module, in dependency order:}
+8. Build {module A} (see modules/{module-a}/SKILL.md)
+   - Create data models
+   - Implement endpoints
+   - Apply business rules
+   - Wire up integrations
+
+### Phase 4: Integration & Testing
+
+### Phase 5: Deployment
+
+## Verification Checklist
+{Comprehensive checklist to verify the rebuild matches the original}
+```
+
+---
+
+## Final Output Folder Structure
+
+```
+{project-name}-intelligence/
+├── MASTER_SKILL.md
+├── OVERVIEW.md
+├── API_REGISTRY.md
+├── DATA_MODELS.md
+├── BUSINESS_RULES.md
+├── DEPENDENCIES.md
+├── ENV_CONFIG.md
+├── RISK_REPORT.md
+├── GLOSSARY.md
+├── REPRODUCTION_GUIDE.md
+├── diagrams/
+│   ├── system-architecture.mermaid
+│   ├── module-dependencies.mermaid
+│   ├── data-model-er.mermaid
+│   ├── auth-flow.mermaid
+│   ├── request-lifecycle.mermaid
+│   └── {feature}-*.mermaid
+└── modules/
+    ├── {module-name}/
+    │   ├── SKILL.md
+    │   └── diagrams/
+    │       └── *.mermaid
+    └── ...
+```
+
+---
+
+## Targeted Module Scan Mode
+
+If the user selected targeted scan:
+1. Ask which module(s) to scan
+2. Run Steps 2-4 only on those modules
+3. Generate module-level SKILL.md and diagrams
+4. Still produce a lightweight OVERVIEW.md for project context
+
+---
+
+## Quality Gate: The Rebuild Test
+
+After generating all output, self-evaluate each module skill:
+
+- [ ] **Data completeness**: Every entity field, type, and constraint documented
+- [ ] **API completeness**: Every endpoint has full request/response schemas and error cases
+- [ ] **Logic completeness**: Every business rule extracted with explicit conditions
+- [ ] **Validation completeness**: Every validation rule listed with error message
+- [ ] **State completeness**: Every state transition documented with triggers and side effects
+- [ ] **Integration completeness**: All inter-module and external dependencies mapped
+- [ ] **Reproduction clarity**: Rebuild steps in correct order with no circular dependencies
+
+If any item fails, go back and enrich before delivering.
+
+---
+
+## Handling Very Large Codebases
+
+If the project has more than ~50 files or ~10,000 lines:
+1. Complete Step 1 (structural) for the entire project
+2. Present the module map to the user
+3. Ask them to prioritize which modules to deep-scan first
+4. Process priority modules through Steps 2-8
+5. Generate lightweight stubs for remaining modules
+6. Offer to deep-scan additional modules on demand

package/skills/global/project-scanner/SKILL.md

@@ -11,7 +11,7 @@ description: Reverse-engineer any codebase into AI-ready skill files. Use this s
   auto-trigger.
 version: 1.0.0
 scope: global
-last_reviewed: 2026-03-27
+last_reviewed: 2026-03-28
 ---
 
 # Project Scanner

package/skills/global/viteapp-core-workflows/SKILL.md

@@ -3,7 +3,7 @@ name: viteapp/core-workflows
 description: No description
 version: 1.0.0
 scope: project
-last_reviewed: 2026-03-27
+last_reviewed: 2026-03-28
 ---
 
 # Skill Name