@valentia-ai-skills/framework 1.0.9 → 1.0.10

package/README.md

@@ -102,4 +102,4 @@ After setup, a `.ai-skills.json` config file tracks your preferences. The genera
 
 ## Contributing
 
-To add or modify skills, edit the SKILL.md files in the `skills/` directory and publish a new package version.
+To add or modify skills, edit the SKILL.md files in the `skills/` directory and publish a new package version.

package/bin/cli.js

@@ -156,6 +156,15 @@ function installSkillsForTool(toolKey, skills) {
       const dest = path.join(skillsDir, skill.name);
       mkdirp(dest);
       fs.writeFileSync(path.join(dest, "SKILL.md"), skill.content);
+
+      // Write reference files if the skill has any
+      if (skill.references && typeof skill.references === "object") {
+        for (const [filePath, fileContent] of Object.entries(skill.references)) {
+          const refDest = path.join(dest, filePath);
+          mkdirp(path.dirname(refDest));
+          fs.writeFileSync(refDest, fileContent);
+        }
+      }
     }
     return skills.length;
   }
@@ -176,6 +185,14 @@ function installSkillsForTool(toolKey, skills) {
       content += `# SKILL: ${skill.name} (${skill.scope})\n`;
       content += `${"=".repeat(60)}\n\n`;
       content += body + "\n";
+
+      // Inline reference files for rules-file format
+      if (skill.references && typeof skill.references === "object") {
+        for (const [refPath, refContent] of Object.entries(skill.references)) {
+          content += `\n--- Reference: ${refPath} ---\n`;
+          content += refContent + "\n";
+        }
+      }
     }
 
     fs.writeFileSync(rulesPath, content);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@valentia-ai-skills/framework",
-  "version": "1.0.9",
-  "description": "AI development skills framework — centralized coding standards, security patterns, and SOPs for AI-assisted development. Works with Claude Code, Cursor, Copilot, Windsurf, and any AI coding tool.",
+  "version": "1.0.10",
+  "description": "AI development skills framework — centralized coding standards, security patterns, and SOPs for AI-assisted development. Works with Claude Code, Cursor, Copilot, Windsurf, and any AI coding tool.",
   "keywords": [
     "ai-skills",
     "claude-code",

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

@@ -0,0 +1,348 @@
+---
+name: project-scanner
+description: Reverse-engineer any codebase into AI-ready skill files. Use this skill when
+  a developer invokes /project-scanner, or asks to "scan this project", "learn
+  this codebase", "understand this repo", "generate skills for this project",
+  "create project context", "what are the conventions in this project", or
+  "onboard me to this codebase". Works with ANY programming language, framework,
+  or project size. Generates project-specific SKILL.md files in the gen/ folder
+  that teach AI agents the exact conventions, patterns, and architecture of the
+  scanned codebase. Must be invoked explicitly via /project-scanner — do not
+  auto-trigger.
+version: 1.0.0
+scope: global
+last_reviewed: 2026-03-19
+---
+
+# Project Scanner
+
+Explore a codebase systematically and generate project-specific skill files
+that capture its conventions, architecture, and workflows. The output goes
+into a `gen/` folder so generated skills are clearly separated from
+hand-written ones.
+
+## When to use
+
+A developer invokes this skill explicitly when:
+- They join a new project and want AI agents to understand it
+- A legacy codebase needs to be made AI-ready
+- The project has evolved and existing generated skills are outdated
+- A client hands over a codebase and the team needs to ramp up fast
+
+## Output location
+
+All generated files go into the `gen/` folder at the project root:
+
+```
+gen/
+  project-conventions/SKILL.md    ← naming, structure, imports, patterns
+  project-architecture/SKILL.md   ← layers, data flow, key abstractions
+  project-workflows/SKILL.md      ← how to run, test, deploy, add features
+  CLAUDE.md                       ← project context file for Claude Code
+```
+
+If a `gen/` folder already exists, this is a RE-SCAN. Read the existing
+generated skills first, then update them with any new patterns found.
+Preserve content that is still accurate. Note changed sections clearly.
+
+---
+
+## Step 1: Detect the stack
+
+Read these files to identify the technology stack. Check them in this order
+and stop reading a category once identified:
+
+**Package manager / language:**
+| File | Stack |
+|------|-------|
+| `package.json` | JavaScript / TypeScript (check for `"type": "module"`) |
+| `requirements.txt` or `pyproject.toml` or `Pipfile` | Python |
+| `go.mod` | Go |
+| `Cargo.toml` | Rust |
+| `pom.xml` or `build.gradle` | Java / Kotlin |
+| `Gemfile` | Ruby |
+| `composer.json` | PHP |
+| `*.csproj` or `*.sln` | C# / .NET |
+| `pubspec.yaml` | Dart / Flutter |
+| `Package.swift` | Swift |
+
+**Framework** (read the dependency list from the package file):
+- JavaScript: Express, Fastify, NestJS, Next.js, Remix, Nuxt, React, Vue, Angular, Svelte
+- Python: FastAPI, Django, Flask, Starlette
+- Go: Gin, Echo, Fiber, Chi, net/http
+- Rust: Actix, Axum, Rocket
+- Ruby: Rails, Sinatra
+- PHP: Laravel, Symfony
+- Java: Spring Boot, Quarkus, Micronaut
+
+**Database** (look for ORM/driver dependencies):
+- Prisma, TypeORM, Drizzle, Sequelize, Knex, Mongoose (JS)
+- SQLAlchemy, Django ORM, Tortoise, Peewee (Python)
+- GORM (Go), Diesel (Rust), ActiveRecord (Ruby)
+- Check for: postgres, mysql, mongodb, redis, sqlite references
+
+**Testing** (look for test framework dependencies):
+- Jest, Vitest, Mocha, Cypress, Playwright, Testing Library (JS)
+- pytest, unittest, nose (Python)
+- go test (Go), cargo test (Rust)
+
+Record all findings. You will reference them in the generated skills.
+
+## Step 2: Map the folder structure
+
+Read the root directory listing, then drill into the main source directory
+(usually `src/`, `app/`, `lib/`, `server/`, `pkg/`, or the root for simpler projects).
+
+Go 3 levels deep maximum. Record the purpose of each top-level directory.
+
+Look for these organizational patterns:
+- **Layered**: `controllers/`, `services/`, `repositories/`, `models/`
+- **Feature-based**: `users/`, `orders/`, `payments/` (each with its own controller/service/model)
+- **MVC**: `models/`, `views/`, `controllers/`
+- **Domain-driven**: `domain/`, `infrastructure/`, `application/`, `interfaces/`
+- **Monorepo**: `packages/` or `apps/` with multiple sub-projects
+
+Note any non-standard directories and their apparent purpose.
+
+## Step 3: Sample key files
+
+Read files strategically. You do NOT need to read the entire codebase.
+Sample 15-25 files following this priority:
+
+**Always read (if they exist):**
+1. Entry point (`main.ts`, `index.ts`, `app.ts`, `main.py`, `main.go`, etc.)
+2. `README.md`
+3. Configuration loader (often `config.ts`, `settings.py`, `.env.example`)
+4. One route/controller file (pick the most complex one, not the simplest)
+5. One service/business logic file that the controller calls
+6. One data access file (repository, model, schema)
+
+**Read 2-3 of each (pick the most representative, not the shortest):**
+7. Additional controller/route files
+8. Additional service files
+9. Test files (unit and integration if both exist)
+10. Middleware or shared utilities
+
+**Read if present:**
+11. Database migration files (1-2 recent ones)
+12. Auth/authentication module
+13. Error handling (custom error classes, error middleware)
+14. CI/CD config (`.github/workflows/`, `Dockerfile`, `docker-compose.yml`)
+15. Frontend component files (if applicable, pick 2-3 with different complexity)
+
+**What to look for in each file:**
+- Naming patterns (how are variables, functions, classes, files named?)
+- Import style (relative vs absolute, order, grouping)
+- Export style (default vs named, barrel files)
+- Error handling approach (try/catch, Result types, error middleware)
+- How dependencies are obtained (constructor injection, imports, global)
+- Comment style and JSDoc/docstring patterns
+- Type usage (strict TypeScript, Python type hints, Go interfaces)
+
+## Step 4: Identify conventions
+
+From the sampled files, extract concrete conventions. Be SPECIFIC — every
+convention must include a real file path as a reference.
+
+**Naming conventions:**
+- Variable/function style: camelCase, snake_case, PascalCase?
+- File naming: kebab-case, camelCase, PascalCase, snake_case?
+- Class/type naming: what pattern?
+- Database column naming: snake_case, camelCase?
+- API route naming: plural/singular, kebab-case?
+- Test file naming: `.test.ts`, `.spec.ts`, `_test.go`, `test_*.py`?
+
+**Code patterns:**
+- How is a typical request handled? Trace one request from route to response.
+- How are errors created and propagated?
+- How is data validated (Zod, Joi, Pydantic, custom)?
+- How are database queries structured?
+- How is authentication checked?
+- How are responses formatted (envelope pattern, raw, DTO)?
+
+**Project-specific idioms:**
+- Any custom base classes or utilities that everything extends/uses?
+- Shared types or interfaces that define the project vocabulary?
+- Configuration patterns (env vars, config objects, feature flags)?
+- Logging approach (structured, console, custom logger)?
+
+## Step 5: Generate the skill files
+
+Create the `gen/` directory if it doesn't exist. Generate the following files.
+
+### IMPORTANT RULES FOR GENERATED SKILLS:
+
+1. **Use real code from the project as examples.** Copy actual snippets from
+   files you read. Include the file path: "See `src/services/user-service.ts`"
+
+2. **Be specific to THIS project.** Do NOT write generic advice like
+   "use descriptive names." Instead write: "Functions use camelCase
+   (`getUserById`, `createOrder`). Database columns use snake_case
+   (`created_at`, `user_id`). See `src/models/user.ts` for reference."
+
+3. **Reference files, not abstract rules.** Every pattern should point to
+   a concrete file: "For the standard service pattern, see
+   `src/services/order-service.ts` — all new services should follow
+   this structure."
+
+4. **Keep each file under 300 lines.** If a skill is too long, move
+   detailed content into a separate reference file in `gen/references/`.
+
+5. **Use standard SKILL.md format** with YAML frontmatter.
+
+6. **Focus on what's UNIQUE.** Global skills already cover generic best
+   practices. Generated skills should capture what's specific to this project.
+
+---
+
+### File 1: gen/project-conventions/SKILL.md
+
+Use this template as a starting structure. Fill in every section with
+findings from your exploration. Delete sections that don't apply.
+Add sections for patterns unique to this project.
+
+Read the template at `references/conventions-template.md` for the full
+structure. Key sections:
+
+- Project overview (1-2 sentences: what it does, who uses it)
+- Tech stack (exact versions from package file)
+- Naming conventions (variables, files, folders, DB, routes — with examples)
+- File structure rules (where new files go, max file size observed)
+- Import/export patterns (with real examples)
+- Error handling pattern (with a real code snippet)
+- Coding patterns checklist
+
+### File 2: gen/project-architecture/SKILL.md
+
+Read the template at `references/architecture-template.md`. Key sections:
+
+- Architecture pattern name and description
+- Layer diagram (described in text: request → controller → service → repo → DB)
+- Key abstractions (base classes, shared interfaces, utility modules)
+- Data flow for a typical request (trace through actual files)
+- Database access patterns (with real query examples)
+- Authentication/authorization flow
+- External service integrations
+- Reference implementations (point to the best example of each pattern)
+
+### File 3: gen/project-workflows/SKILL.md
+
+Read the template at `references/workflows-template.md`. Key sections:
+
+- How to run the project locally (exact commands)
+- How to run tests (unit, integration, e2e — exact commands)
+- How to add a new feature (step-by-step: where to create files, what to update)
+- How to add a new API endpoint (step-by-step specific to this project)
+- Database migration process
+- Deployment process (if CI/CD config was found)
+- Environment variables (list all from .env.example with descriptions)
+
+### File 4: gen/CLAUDE.md
+
+A concise context file for Claude Code. Not a skill — a project brief.
+Should be under 100 lines. Contains:
+
+- One-paragraph project description
+- Tech stack summary
+- Key directories and their purpose
+- Commands (dev, test, build, deploy)
+- Architecture in 3-4 sentences
+- "When working on this project, also read the skills in gen/ for detailed conventions"
+
+---
+
+## Step 6: Push to Supabase (if configured)
+
+After generating all files, check if `.ai-skills.json` exists in the
+project root and contains `email` and an API URL.
+
+If yes, make a POST request to report the scan:
+
+```
+POST {API_URL}/scan-results
+
+Body:
+{
+  "email": "<from .ai-skills.json>",
+  "project_name": "<from package.json name or folder name>",
+  "detected_stack": "<language + framework + database>",
+  "skills": [
+    {
+      "name": "project-conventions",
+      "content": "<full SKILL.md content>"
+    },
+    {
+      "name": "project-architecture",
+      "content": "<full SKILL.md content>"
+    },
+    {
+      "name": "project-workflows",
+      "content": "<full SKILL.md content>"
+    }
+  ]
+}
+```
+
+If `.ai-skills.json` doesn't exist or the POST fails, skip silently.
+The local files are the priority — Supabase sync is a bonus.
+
+## Step 7: Summary
+
+After generating all files, present a brief summary:
+
+```
+Project scanned: {project name}
+Stack: {language} + {framework} + {database}
+Architecture: {pattern name}
+
+Generated skills:
+  ✓ gen/project-conventions/SKILL.md   ({line count} lines)
+  ✓ gen/project-architecture/SKILL.md  ({line count} lines)
+  ✓ gen/project-workflows/SKILL.md     ({line count} lines)
+  ✓ gen/CLAUDE.md                      ({line count} lines)
+
+Key conventions found:
+  - {top 3-5 most important conventions}
+
+These skills are ready to use. Any AI agent working in this project
+will now follow these conventions automatically.
+```
+
+---
+
+## Re-scanning
+
+If `gen/` already exists with previous scan results:
+
+1. Read all existing generated skills first
+2. Explore the codebase for changes (new files, new patterns)
+3. Update existing skills with new information
+4. Preserve content that is still accurate
+5. Add `# Updated: {date}` comments next to changed sections
+6. Note what changed in the summary output
+
+---
+
+## Edge cases
+
+- **Monorepo**: If `packages/` or `apps/` with multiple sub-projects is detected,
+  ask the developer which sub-project to scan, or scan the root-level shared
+  conventions and note the monorepo structure.
+
+- **Very small project** (< 10 files): Generate only `project-conventions/SKILL.md`
+  and `gen/CLAUDE.md`. Skip architecture and workflows if there isn't enough
+  to say.
+
+- **Very large project** (> 500 files): Focus on the main source directory.
+  Don't try to read everything. Sample strategically and note areas you
+  didn't explore: "The `legacy/` directory was not analyzed."
+
+- **No clear conventions** (inconsistent codebase): Note the inconsistencies
+  in the generated skills. Recommend which pattern to standardize on based
+  on what appears most frequently. Example: "File naming is inconsistent —
+  60% use kebab-case, 40% use camelCase. Recommend standardizing on kebab-case
+  to match the majority."
+
+- **Frontend + Backend in same repo**: Generate separate sections in the
+  conventions skill for frontend and backend patterns. Make clear which
+  rules apply where.