@valentia-ai-skills/framework 2.0.1 → 2.0.3

package/README.md

@@ -1,7 +1,6 @@
 # AI Skills Framework
 
-Centralized coding standards, security patterns, and SOPs for AI-assisted development.
-Welcome to Version 1.0.2 Dated 20th March 2026
+Centralized coding standards, security patterns, agents, commands, hooks, rules, and MCP server configs for AI-assisted development — distributed as a single npm package.
 
 **One install. All AI tools. Every team follows the same rules.**
 
@@ -11,30 +10,93 @@ Welcome to Version 1.0.2 Dated 20th March 2026
 # Install
 npm install --save-dev @valentia-ai-skills/framework
 
-# Setup (auto-detects your AI tools)
+# Setup (auto-detects your AI tools + project languages)
 npx ai-skills setup
 
 # Done. Your AI tools now follow your org's standards.
 ```
 
-## What It Does
+Setup will ask for your work email, send a verification code, then fetch and install your team's full toolkit.
 
-This package installs your organization's coding standards into whatever AI coding tool your team uses:
+---
 
+## What Gets Installed
 
-| AI Tool | What Gets Created |
-|---------|------------------|
-| **Claude Code** | Individual skill folders in `.claude/skills/` |
-| **Cursor** | Merged rules file at `.cursor/rules/ai-skills.mdc` |
-| **GitHub Copilot** | Merged rules at `.github/copilot-instructions.md` |
-| **Windsurf** | Merged rules at `.windsurfrules` |
-| **Any other tool** | Generic `.ai-rules` file |
+The framework delivers **6 entity types** to your project, managed centrally through the Skills Console:
 
-The CLI auto-detects which tools you're using and installs the right format.
+| Entity | What It Is | Claude Code Location | Other Tools |
+|--------|-----------|---------------------|-------------|
+| **Skills** | Coding standards & patterns (markdown instructions) | `.claude/skills/{name}/SKILL.md` | Merged into rules file |
+| **Agents** | Pre-configured AI agent definitions with model, tools, instructions | `.claude/agents/{name}.md` | `ai-agents.mdc` |
+| **Commands** | Slash commands (`/command-name`) for common workflows | `.claude/commands/{name}.md` | `ai-commands.mdc` |
+| **Hooks** | Event-driven scripts that run on tool actions (pre/post) | `.claude/settings.local.json` + `.ai-skills/hooks/` | Claude Code only |
+| **Rules** | Language-specific coding rules (auto-detected by project) | `.claude/rules/{name}.md` | `ai-rules.mdc` |
+| **MCP Configs** | MCP server configurations (npx, docker, uvx) | `.claude/mcp-servers.json` | `ai-mcp-configs.md` |
 
-## Included Skills
+---
 
-### Global (all teams)
+## Supported AI Tools
+
+The CLI auto-detects which tools you're using and writes the correct format:
+
+| AI Tool | Format | Output Path |
+|---------|--------|-------------|
+| **Claude Code** | Individual files per entity | `.claude/skills/`, `.claude/agents/`, `.claude/commands/`, `.claude/rules/`, `.claude/settings.local.json`, `.claude/mcp-servers.json` |
+| **Cursor** | Merged rules files | `.cursor/rules/ai-skills.mdc`, `.cursor/rules/ai-agents.mdc`, etc. |
+| **GitHub Copilot** | Merged rules files | `.github/copilot-instructions.md` + related files |
+| **Windsurf** | Merged rules file | `.windsurfrules` |
+| **Any other tool** | Generic fallback | `.ai-rules` |
+
+---
+
+## CLI Commands
+
+```bash
+npx ai-skills setup          # First-time setup — email verification → install toolkit
+npx ai-skills update         # Re-fetch and reinstall latest toolkit from your team
+npx ai-skills status         # Show installed entities, team info, detected tools
+npx ai-skills list           # List locally bundled skills
+npx ai-skills analyze        # Analyze staged/last commit against active skills
+npx ai-skills analyze --last # Analyze the most recent commit
+npx ai-skills doctor         # Health check (config, API, tools, entity counts)
+npx ai-skills help           # Show help
+```
+
+#### Legacy Codebase Intelligence Scanner
+
+```bash
+# Upload a legacy codebase intelligence package to your team's Skills Console
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/
+
+# Validate the package payload without uploading (dry run)
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --dry-run
+
+# Supply an explicit auth token instead of going through OTP
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --token <your-token>
+```
+
+The `--path` directory must contain a `manifest.json` file. See the [Legacy Scanner](#legacy-codebase-intelligence-scanner) section below for the required format.
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `AI_SKILLS_API_URL` | Override the Supabase Edge Function URL |
+| `AI_SKILLS_ANALYZE_URL` | Override the analyze commit function URL |
+| `AI_SKILLS_SCAN_URL` | Override the scan results function URL |
+| `AI_SKILLS_UPLOAD_LEGACY_URL` | Override the upload-legacy-scan Edge Function URL |
+
+---
+
+## Entity Types in Detail
+
+### Skills
+
+Markdown-based coding standards that tell AI tools what conventions to follow. They never touch your application code.
+
+**Scopes:** `global` (all teams), `stack` (tech-specific), `project` (single project)
+
+**Bundled global skills:**
 - **code-standards** — Naming, file structure, formatting, error handling
 - **git-workflow** — Branching, commits, PRs, releases
 - **security-baseline** — Auth, validation, secrets, XSS, SQL injection
@@ -43,50 +105,115 @@ The CLI auto-detects which tools you're using and installs the right format.
 - **documentation** — READMEs, API docs, ADRs, changelogs, runbooks
 - **deployment** — CI/CD, Docker, environments, rollback, feature flags
 
-### Stack-specific
+**Bundled stack skills:**
 - **react** — Components, hooks, state management, performance
 - **react-native** — Navigation, FlatList, offline-first, platform code
 - **node-backend** — Layered architecture, DI, error handling, health checks
 - **python-backend** — FastAPI, Pydantic, async patterns, pytest
 - **devops** — Terraform, Kubernetes, monitoring, SLOs, alerting
 
-## Commands
+### Agents
 
-```bash
-npx ai-skills setup    # First-time setup
-npx ai-skills update   # Update to latest skills
-npx ai-skills status   # Check what's installed
-npx ai-skills list     # Show all available skills
-npx ai-skills doctor   # Health check
+Pre-configured AI agent definitions with model preferences, allowed tools, max turns, and detailed instructions.
+
+```
+# Example: installed to .claude/agents/code-reviewer.md
+---
+name: code-reviewer
+description: Senior code reviewer agent
+model: opus
+tools: ["Read", "Grep", "Glob"]
+max_turns: 10
+---
+
+Review the code for security vulnerabilities, performance issues...
 ```
 
-## Updating
+### Commands
 
-```bash
-# Update the package
-npm update @valentia-ai-skills/framework
+Slash commands that developers can invoke (e.g., `/review-pr`, `/generate-tests`). Each command has instructions and can optionally reference an agent.
+
+```
+# Example: installed to .claude/commands/review-pr.md
+---
+name: review-pr
+description: Review the current pull request
+agent: code-reviewer
+---
+
+Analyze the current PR diff and provide feedback on...
+```
+
+### Hooks
+
+Event-driven scripts for Claude Code that run before or after specific tool actions. Supports all Claude Code hook events:
+
+| Event | When It Fires |
+|-------|--------------|
+| `PreToolUse` | Before a tool is executed |
+| `PostToolUse` | After a tool completes |
+| `Notification` | When a notification is sent |
+| `Stop` | When the agent stops |
+| `SubagentStop` | When a subagent stops |
+| `PreCompact` | Before context compaction |
+| `PostCompact` | After context compaction |
+
+Hooks are installed to `.claude/settings.local.json` with scripts saved to `.ai-skills/hooks/`.
+
+### Rules
+
+Language-specific coding rules that are **auto-detected** based on your project. The CLI scans for language markers (e.g., `tsconfig.json` for TypeScript, `go.mod` for Go) and only installs rules matching your detected languages.
+
+**Supported languages for auto-detection:** TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, Swift, PHP, C#, C++
 
-# Refresh the installed skills
-npx ai-skills update
 ```
+# Example: installed to .claude/rules/typescript-strict.md
+Use strict TypeScript — avoid `any`, prefer explicit return types...
+```
+
+### MCP Configs
+
+MCP (Model Context Protocol) server configurations. Templates are merged into `.claude/mcp-servers.json` without overwriting existing user configs.
+
+**Server types:** `npx`, `node`, `uvx`, `docker`, `command`
+
+```json
+// Example: merged into .claude/mcp-servers.json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": { "GITHUB_TOKEN": "{{GITHUB_TOKEN}}" }
+    }
+  }
+}
+```
+
+Required environment variables are flagged during installation — you must fill in `{{PLACEHOLDER}}` values.
+
+---
 
 ## How It Works
 
 1. **Install** — `npm install` adds the package to your project
-2. **Setup** — `npx ai-skills setup` detects your AI tools and writes config files
-3. **Code** — When you use any AI coding tool, it reads those config files and follows the rules
-4. **Update** — `npm update` + `npx ai-skills update` refreshes everything
+2. **Setup** — `npx ai-skills setup` asks for your email, verifies via OTP, fetches your team's toolkit
+3. **Install** — The CLI detects your AI tools and project languages, then writes config files in the correct format
+4. **Code** — When you use any AI coding tool, it reads those config files and follows the rules
+5. **Update** — `npm update` + `npx ai-skills update` re-verifies and refreshes everything
 
-The skills never touch your application code. They only tell AI tools what conventions to follow.
+The toolkit is managed centrally through the **Skills Console** (admin dashboard). Team leads assign which entities each team gets.
+
+---
 
 ## For Team Leads
 
-Add this to your project's `package.json` so every developer gets the skills on `npm install`:
+Add this to your project's `package.json` so every developer gets the toolkit on `npm install`:
 
 ```json
 {
   "devDependencies": {
-    "@valentia-ai-skills/framework": "^1.0.0"
+    "@valentia-ai-skills/framework": "^2.0.0"
   },
   "scripts": {
     "postinstall": "npx ai-skills setup"
@@ -94,12 +221,161 @@ Add this to your project's `package.json` so every developer gets the skills on
 }
 ```
 
-Now every `git clone` + `npm install` automatically configures AI skills.
+Now every `git clone` + `npm install` automatically configures the full AI toolkit.
+
+---
+
+## Configuration
+
+After setup, a `.ai-skills.json` config file tracks your preferences:
+
+```json
+{
+  "version": "2.0.0",
+  "email": "dev@company.com",
+  "team": "frontend-team",
+  "project": "my-app",
+  "source": "supabase",
+  "detectedLanguages": ["typescript", "javascript"],
+  "tools": ["claude-code", "cursor"],
+  "skills": [{ "name": "code-standards", "scope": "global", "version": "1.0" }],
+  "agents": [{ "name": "code-reviewer", "scope": "global", "version": "1.0" }],
+  "commands": [{ "name": "review-pr", "scope": "global", "version": "1.0" }],
+  "hooks": [{ "name": "lint-check", "scope": "global", "version": "1.0" }],
+  "rules": [{ "name": "ts-strict", "scope": "stack", "version": "1.0", "language": "typescript" }],
+  "mcpConfigs": [{ "name": "github", "scope": "global", "version": "1.0" }]
+}
+```
+
+The generated config files can be committed to git so the whole team shares the same setup.
+
+---
+
+## Commit Analysis
+
+The framework includes AI-powered commit analysis that scores your code against active skills:
+
+```bash
+# Analyze staged changes or last commit
+npx ai-skills analyze
+
+# Analyze the most recent commit explicitly
+npx ai-skills analyze --last
+```
+
+Results include per-skill scores, passed/failed checks, and improvement suggestions.
+
+A post-commit git hook is automatically installed during setup to run analysis after each commit.
+
+---
+
+## Legacy Codebase Intelligence Scanner
+
+The framework supports ingesting intelligence packages generated by legacy codebase scanners. Once uploaded, the extracted skills, architecture diagrams, and reports become reviewable in the **Skills Console** under the **Legacy Scanners** section.
+
+### How It Works
+
+1. **Scan** — A compatible scanner tool analyses an existing codebase and produces an intelligence folder
+2. **Upload** — `npx ai-skills upload-legacy-scan --path <folder>` packages and ships the output to your team's console
+3. **Review** — Tech leads review auto-generated skills, approve or request revisions per skill, and publish approved skills into the active toolkit
+4. **Rescan** — Re-running the upload on the same project name appends a new version, preserving history
+
+### Intelligence Package Format
+
+The folder passed to `--path` must follow this layout:
+
+```
+my-project-intelligence/
+├── manifest.json          # Required — project metadata + statistics
+├── skills/                # Required — one SKILL.md per extracted skill
+│   ├── auth-patterns.md
+│   ├── api-conventions.md
+│   └── ...
+├── diagrams/              # Optional — Mermaid (.mmd) architecture diagrams
+│   ├── system-overview.mmd
+│   └── data-flow.mmd
+└── reports/               # Optional — markdown reports
+    ├── api-registry.md
+    ├── business-rules.md
+    ├── risk-assessment.md
+    └── reproduction-guide.md
+```
+
+**`manifest.json` schema:**
+
+```json
+{
+  "project_name": "legacy-billing-service",
+  "tech_stack": ["Node.js", "PostgreSQL", "React"],
+  "statistics": {
+    "module_count": 24,
+    "total_endpoints": 68,
+    "total_business_rules": 142,
+    "completeness_score": 78
+  }
+}
+```
+
+### Skills Console — Legacy Scanners View
+
+After upload, each project appears in the **Legacy Scanners** section of the Skills Console with:
 
-## Customization
+- **Overview** — project stats, completeness score, tech stack
+- **Modules** — per-skill approval workflow (approve / needs revision)
+- **API Registry** — searchable endpoint documentation
+- **Business Rules** — searchable rule catalogue
+- **Architecture** — interactive Mermaid diagrams
+- **Risk Report** — severity-categorised risk sections
+- **Reproduction Guide** — interactive onboarding checklist
 
-After setup, a `.ai-skills.json` config file tracks your preferences. The generated rules files can be committed to git so the whole team shares the same setup.
+Approved skills are promoted into the team's standard toolkit and distributed on the next `npx ai-skills update`.
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      Skills Console                           │
+│  Admin Dashboard — Skills, Agents, Commands, Hooks,          │
+│  Rules, MCP Configs, Legacy Scanners                         │
+│  Teams → assign entities → per-team toolkit                   │
+└────────────────┬────────────────────────┬────────────────────┘
+                 │ lookup-team            │ upload-legacy-scan
+                 │ (Edge Function)        │ (Edge Function)
+                 ▼                        ▼
+┌────────────────────────────┐   ┌────────────────────────────┐
+│   CLI (npx ai-skills)      │   │  Legacy Codebase Scanner   │
+│  Email OTP → fetch toolkit │   │  Scans codebase → produces │
+│  → install to AI tools     │   │  intelligence package      │
+└──────────────┬─────────────┘   └──────────────┬─────────────┘
+               │                                 │
+               │          npx ai-skills          │
+               │      upload-legacy-scan         │
+               ▼                                 ▼
+  ┌────────────────────────┐   Skills Console → Review → Approve
+  │   Claude Code          │   → promoted into team toolkit
+  │   Cursor               │
+  │   GitHub Copilot       │
+  │   Windsurf             │
+  └────────────────────────┘
+```
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- Zero runtime dependencies — the CLI is pure Node.js
+
+---
 
 ## 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 version. For full entity management (agents, commands, hooks, rules, MCP configs), use the Skills Console.
+
+---
+
+## License
+
+MIT — Valentia AI