codymaster 4.1.0

package/skills/cm-project-bootstrap/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: cm-project-bootstrap
+description: Use when starting any new project from scratch. Asks for project identity (name, GitHub org, Cloudflare account), detects project type, sets up design system, staging+production, i18n from day 1, SEO foundation, AGENTS.md manifest, test infrastructure, 8-gate deploy pipeline, and disciplined development workflows. Prevents wrong deploys, redundant repos, and technical debt from day 0.
+---
+
+# CodyMaster Project Bootstrap v2.0
+
+> **Every project starts here. No exceptions.**
+
+## Core Principles
+
+- ASK FIRST. BUILD SECOND. NEVER ASSUME IDENTITY.
+- STAGING IS MANDATORY. PRODUCTION IS EARNED.
+- I18N FROM DAY 1. DESIGN SYSTEM BEFORE COMPONENTS.
+- SEO IS INFRASTRUCTURE. EVERY PROJECT GETS AN AGENTS.MD.
+
+## 11-Phase Bootstrap Process
+
+| Phase | Name | Purpose |
+|-------|------|---------|
+| 0 | Identity Lock | WHO are you deploying as? |
+| 0.5 | Security Foundation | HOW to prevent secret leaks? (calls `cm-secret-shield`) |
+| 1 | Project Type Detection | WHAT kind of project? |
+| 2 | Repository & Environments | WHERE does code live? |
+| 3 | Design System Foundation | HOW does it look? |
+| 4 | i18n From Day 1 | WHICH languages? |
+| 5 | SEO Foundation | HOW will people find it? |
+| 6 | AGENTS.md + Git Safety | HOW do agents collaborate? |
+| 7 | Test Infrastructure | HOW do we catch bugs? |
+| 8 | Deploy Pipeline (8 Gates) | HOW does code ship? |
+| 9 | Development Workflow | HOW do we work daily? |
+
+---
+
+## Phase 0: Identity Lock 🔐
+
+> **MANDATORY. Cannot proceed without this.**
+
+1. Check `~/.cm-identity-history.json` for previous identities → suggest pre-fill
+2. Ask 6 questions (with suggestions from history):
+   - Project name (kebab-case), GitHub org, Cloudflare ID, Domain, Primary language, Target languages
+3. Verify identity with user confirmation
+4. Create `.project-identity.json` with all config
+5. Save to `~/.cm-identity-history.json` for future projects
+6. Call `cm-identity-guard` to verify git config matches
+
+## Phase 0.5: Security Foundation 🛡️
+
+> Calls `cm-secret-shield` for setup.
+
+1. Create `.gitleaks.toml` with Supabase + generic high-entropy rules
+2. Setup pre-commit hook (`.git/hooks/pre-commit`) — scans staged files
+3. Add `security:scan` script to `package.json`
+4. Create `.dev.vars.example` template (committed). `.dev.vars` = real secrets (gitignored)
+
+## Phase 1: Project Type Detection 🔍
+
+> Default UI: shadcn/ui + Tailwind. Default layout: Mobile-first.
+
+| Type | Stack |
+|------|-------|
+| A. Static Website | HTML + vanilla JS + CSS |
+| B. SPA (Vite) | Vite + React + TS + shadcn/ui |
+| C. Cloudflare Workers | Hono + wrangler + TS |
+| D. Fullstack | Hono + Vite + React + shadcn/ui |
+| E. Content Site | Astro + MDX |
+
+Scaffold based on type, install `vitest` for all. Enforce mobile-first base styles.
+
+## Phase 2: Repository & Environments 🏠
+
+1. `git init` + `main` (staging) + `production` branches
+2. Configure Cloudflare Pages: `npx wrangler pages project create`
+3. Add `deploy:staging` and `deploy:production` scripts
+4. Create hardened `.gitignore` (secrets, env files, build output)
+
+## Phase 3: Design System Foundation 🎨
+
+> Design tokens BEFORE components. shadcn/ui as default. Mobile-first always.
+
+1. Check `~/.cm-design-profiles/{org}.json` for existing brand profile → reuse
+2. If no profile: ask brand context (name, industry, style, primary color, dark mode)
+3. Create design tokens (CSS custom properties for shadcn/ui or vanilla)
+4. Install base shadcn/ui components: button, input, label, card, dialog, dropdown-menu, toast, skeleton
+5. Add mobile-first base styles (44px touch targets, responsive container, safe-area)
+6. Save design profile to `~/.cm-design-profiles/`
+
+## Phase 4: i18n From Day 1 🌍
+
+1. Create i18n engine (vanilla `i18n.js` or `react-i18next`)
+2. Create language files: primary (source of truth) + targets
+3. Rules: ALL strings via `t()` or `data-i18n`. MAX 30 strings per batch. Run i18n-sync test after every batch.
+
+## Phase 5: SEO Foundation 🔍
+
+Every page must have: title (<60 chars), meta description (150-160 chars), exactly ONE h1, heading hierarchy (no skipping), semantic HTML, alt attributes, canonical URL, Open Graph, lang attribute, unique IDs.
+
+## Phase 6: AGENTS.md + Git Safety 🤖
+
+1. Create `AGENTS.md` at root — project overview, commands, structure, conventions, rules
+2. Enforce conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `chore:`, `i18n:`
+3. Branch protection: main (staging, no force push), production (merge from main only)
+4. Create PR template (`.github/pull_request_template.md`)
+
+## Phase 7: Test Infrastructure 🧪
+
+1. Create `vitest.config.js`
+2. Create `tests/unit/frontend-safety.test.js` — HTML structure, JS syntax, CSS tokens, AGENTS.md exists
+3. Create `tests/unit/i18n-sync.test.js` — key parity across languages
+4. Wire up `test:gate` in package.json
+
+## Phase 8: Deploy Pipeline (8 Gates) 🚀
+
+Gates run sequentially: Identity → Branch → Test → Build → i18n → Lint → Accessibility → Performance.
+See `cm-safe-deploy` for the full 9-gate pipeline details.
+
+## Phase 9: Development Workflow 🔄
+
+Daily loop: Plan → Branch → TDD → Build → Test → Review → Commit → Deploy staging → Verify → Merge production.
+
+Deploy rules: `deploy` = staging. `deploy production` = requires staging verified first.
+
+## Phase 9.5: Working Memory Init 🧠
+
+1. Create `.cm/CONTINUITY.md` from `cm-continuity` template
+2. Add `.cm/` to `.gitignore` (local working memory)
+3. Reference in AGENTS.md
+
+## Adaptive Skills Discovery 🧠
+
+When agent encounters unknown task:
+1. DETECT gap → 2. `npx skills find "{keyword}"` → 3. REVIEW SKILL.md → 4. ASK user → 5. INSTALL → 6. USE → 7. LOG to `.cm-skills-log.json`
+
+Safety: always show user before installing, prefer known repos, install project-level, log every install.
+
+## Output Checklist ✅
+
+After bootstrap, project MUST have: `.project-identity.json`, `AGENTS.md`, `.gitignore` (hardened), `.gitleaks.toml`, pre-commit hook, `.dev.vars.example`, `package.json` (with deploy/test scripts), design tokens/shadcn, i18n files, SEO meta tags, test files, main + production branches, `.cm/CONTINUITY.md`.
+
+## Template Files (load on-demand with view_file)
+
+| Template | Use When |
+|----------|----------|
+| `templates/vitest.config.js` | Phase 7: Setting up test infrastructure |
+| `templates/frontend-safety.test.js` | Phase 7: Creating frontend safety tests |
+| `templates/i18n-sync.test.js` | Phase 7: Creating i18n sync tests |
+| `templates/project-identity.json` | Phase 0: Creating .project-identity.json |
+| `templates/AGENTS.md` | Phase 6: Creating AGENTS.md |
+| `templates/pr-template.md` | Phase 6: Creating PR template |
+
+## Anti-Patterns ❌
+
+| Anti-Pattern | Prevention |
+|-------------|------------|
+| Skip identity lock | Phase 0 is MANDATORY |
+| No staging branch | Always 2 branches |
+| i18n "later" | Phase 4 from day 1 |
+| Raw hex colors | Design tokens only |
+| No AGENTS.md | Phase 6 creates it |
+| deploy = production | deploy = staging default |
+| 600 i18n strings at once | MAX 30 per batch |

package/skills/cm-project-bootstrap/templates/AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md — {{PROJECT_NAME}}
+
+> AI agents: Read this file FIRST before any task.
+
+## Project Identity
+- **Name**: {{PROJECT_NAME}}
+- **Type**: {{PROJECT_TYPE}} (Cloudflare Pages)
+- **Primary Language**: {{PRIMARY_LANG}}
+- **Tech Stack**: {{TECH_STACK}}
+
+## Commands
+- `npm run dev` — Start local dev server
+- `npm run test` — Run all tests
+- `npm run test:gate` — Run pre-deploy test gate
+- `npm run deploy:staging` — Deploy to staging
+- `npm run deploy:production` — Deploy to production
+
+## Project Structure
+```
+public/           — Static files served directly
+  static/css/     — Stylesheets (design-tokens.css, style.css)
+  static/js/      — JavaScript (app.js, i18n.js)
+  static/i18n/    — Language files (vi.json, en.json, ...)
+src/              — Backend source (if applicable)
+tests/            — Test files
+docs/plans/       — Implementation plans
+```
+
+## Code Conventions
+- **i18n**: ALL user-facing strings must use t() or data-i18n. vi.json is source of truth.
+- **CSS**: Use design tokens only. Never raw hex colors or arbitrary spacing.
+- **Commits**: Conventional format — `feat:`, `fix:`, `docs:`, `test:`, `chore:`
+- **Branches**: `main` = staging, `production` = production only
+- **Deploy**: Always staging first. Production requires explicit request.
+
+## Important Rules
+1. Run `cm-identity-guard` before any git push
+2. Never force push to main or production
+3. i18n extraction: MAX 30 strings per batch
+4. Run test:gate before every deploy
+5. Check `.project-identity.json` for deploy targets
+6. Read `.cm/CONTINUITY.md` at the start of every session for context

package/skills/cm-project-bootstrap/templates/frontend-safety.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+describe('Frontend Safety', () => {
+  // Test 1: HTML files have proper structure
+  it('index.html has required meta tags', () => {
+    const html = readFileSync('public/index.html', 'utf-8');
+    expect(html).toContain('<meta charset=');
+    expect(html).toContain('<meta name="viewport"');
+    expect(html).toContain('<title');
+    expect(html).toContain('lang=');
+  });
+
+  // Test 2: No syntax errors in JS files
+  it('JavaScript files parse without errors', () => {
+    const jsDir = 'public/static/js';
+    if (!existsSync(jsDir)) return;
+    const files = readdirSync(jsDir).filter(f => f.endsWith('.js'));
+    files.forEach(file => {
+      const content = readFileSync(join(jsDir, file), 'utf-8');
+      expect(() => new Function(content)).not.toThrow();
+    });
+  });
+
+  // Test 3: CSS files reference design tokens (not raw values)
+  it('stylesheets use design tokens', () => {
+    const cssFile = 'public/static/css/style.css';
+    if (!existsSync(cssFile)) return;
+    const css = readFileSync(cssFile, 'utf-8');
+    const rawColors = css.match(/#[0-9a-fA-F]{3,8}(?!.*design-tokens)/g);
+    if (rawColors && rawColors.length > 0) {
+      console.warn(`⚠️ Found ${rawColors.length} raw color values. Use design tokens instead.`);
+    }
+  });
+
+  // Test 4: Design tokens file exists
+  it('design-tokens.css exists', () => {
+    expect(existsSync('public/static/css/design-tokens.css')).toBe(true);
+  });
+
+  // Test 5: AGENTS.md exists
+  it('AGENTS.md exists at project root', () => {
+    expect(existsSync('AGENTS.md')).toBe(true);
+  });
+
+  // Test 6: .project-identity.json exists
+  it('.project-identity.json exists', () => {
+    expect(existsSync('.project-identity.json')).toBe(true);
+  });
+});

package/skills/cm-project-bootstrap/templates/i18n-sync.test.js

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join } from 'path';
+
+describe('i18n Sync', () => {
+  const i18nDir = 'public/static/i18n';
+
+  it('primary language file exists', () => {
+    expect(existsSync(join(i18nDir, 'vi.json'))).toBe(true);
+  });
+
+  it('all language files have same keys as primary', () => {
+    if (!existsSync(i18nDir)) return;
+    const primaryKeys = getAllKeys(
+      JSON.parse(readFileSync(join(i18nDir, 'vi.json'), 'utf-8'))
+    );
+
+    const langFiles = readdirSync(i18nDir)
+      .filter(f => f.endsWith('.json') && f !== 'vi.json');
+
+    langFiles.forEach(file => {
+      const langKeys = getAllKeys(
+        JSON.parse(readFileSync(join(i18nDir, file), 'utf-8'))
+      );
+      const missing = primaryKeys.filter(k => !langKeys.includes(k));
+      expect(missing, `${file} missing keys: ${missing.join(', ')}`).toEqual([]);
+    });
+  });
+});
+
+function getAllKeys(obj, prefix = '') {
+  return Object.entries(obj).flatMap(([key, val]) => {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    return typeof val === 'object' && val !== null
+      ? getAllKeys(val, fullKey)
+      : [fullKey];
+  });
+}

package/skills/cm-project-bootstrap/templates/pr-template.md

@@ -0,0 +1,12 @@
+## What Changed
+<!-- Brief description -->
+
+## Test Plan
+- [ ] Tests pass (`npm run test:gate`)
+- [ ] Staging verified
+- [ ] i18n keys present in all languages
+- [ ] No raw strings in UI
+
+## Deploy
+- [ ] Ready for staging
+- [ ] Ready for production (requires staging verification)

package/skills/cm-project-bootstrap/templates/project-identity.json

@@ -0,0 +1,29 @@
+{
+  "project": {
+    "name": "{{PROJECT_NAME}}",
+    "type": "{{PROJECT_TYPE}}",
+    "primaryLanguage": "{{PRIMARY_LANG}}",
+    "targetLanguages": ["{{TARGET_LANGS}}"]
+  },
+  "github": {
+    "org": "{{GITHUB_ORG}}",
+    "repo": "{{GITHUB_ORG}}/{{PROJECT_NAME}}"
+  },
+  "cloudflare": {
+    "accountId": "{{CF_ACCOUNT_ID}}",
+    "projectName": "{{PROJECT_NAME}}",
+    "customDomain": "{{DOMAIN}}"
+  },
+  "deploy": {
+    "staging": {
+      "branch": "main",
+      "url": "https://{{PROJECT_NAME}}.pages.dev"
+    },
+    "production": {
+      "branch": "production",
+      "url": "https://{{DOMAIN}}"
+    }
+  },
+  "createdAt": "{{ISO_DATE}}",
+  "createdBy": "cm-project-bootstrap v2.0"
+}

package/skills/cm-project-bootstrap/templates/vitest.config.js

@@ -0,0 +1,10 @@
+// vitest.config.js (or vitest.config.ts)
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/**/*.test.{js,ts}'],
+  },
+});

package/skills/cm-quality-gate/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: cm-quality-gate
+description: "Use before any deployment or completion claim. Enforces test gates, evidence-based verification, and frontend safety checks. No deploy without passing. No claims without evidence."
+---
+
+# Quality Gate — Test + Verify + Ship Safe
+
+> **Role: QA Lead** — You enforce test gates, evidence-based verification, and frontend safety. No deploy without passing you.
+
+> **Three checkpoints, one skill:** Pre-deploy testing, evidence verification, frontend safety.
+
+## The Iron Laws
+1. **NO DEPLOY** without passing `test:gate`.
+2. **NO CLAIMS** without fresh verification output.
+3. **NO FRAGILE FRONTEND** — safety tests are mandatory.
+
+---
+
+## Phase 0: Infrastructure Setup
+> **Goal:** Identify the framework and install the correct testing dependencies.
+
+1.  **Detect Stack:** Check `package.json` for framework (React, Vue, Astro, etc.) and `wrangler.json(c)`.
+2.  **Install Deps:** `npm install -D vitest jsdom acorn`
+3.  **Configure:** Create `vitest.config.ts` or `vite.config.ts` with `environment: 'jsdom'`.
+4.  **Wire Scripts:**
+    ```json
+    {
+      "scripts": {
+        "test:gate": "vitest run --reporter=verbose"
+      }
+    }
+    ```
+
+---
+
+## Phase 1: The 4 Core Test Layers
+Do not combine these files. They form the "Quality Gate."
+
+### Layer 1: Frontend Safety (`test/frontend-safety.test.ts`)
+Prevents white screens, template corruption, and syntax errors.
+```javascript
+test('app.js does not contain catastrophic corruption', () => {
+    const code = fs.readFileSync('public/static/app.js', 'utf-8');
+    expect(code).not.toMatch(/=\s*'[^']*\$\{t\(/); // Bug #1
+    expect(code).not.toMatch(/<\s+[a-zA-Z]/); // Bug #2
+});
+```
+
+### Layer 2: API Routes (`test/api-routes.test.ts`)
+Ensures backend endpoints respond correctly.
+
+### Layer 3: Business Logic (`test/business-logic.test.ts`)
+Tests pure functions, validations, and transformations.
+
+### Layer 4: i18n Synchronization (`test/i18n-sync.test.ts`)
+Guarantees all language files have identical key counts.
+
+---
+
+## Phase 2: Execution (The Gates)
+
+### Gate 1: Pre-Deploy Testing
+**ALWAYS** run `npm run test:gate` before deploying. 0 failures required.
+
+### Protocol
+
+1.  **Check for skip override** (explicit user words only):
+    -   ✅ "skip tests", "skip testing", "deploy without testing"
+    -   ❌ "deploy", "quick deploy", "just push it" (= tests required)
+
+2.  **Run test gate:**
+    ```bash
+    npm run test:gate
+    ```
+
+3.  **Parse results:** total files, total tests, failures, duration
+
+4.  **Gate decision:**
+    -   0 failures → proceed to deploy
+    -   Any failures → **STOP. Fix first. Do NOT deploy.**
+
+### Anti-Patterns
+
+| DON'T | DO |
+|-------|-----|
+| Deploy then test | Test then deploy |
+| "Tests passed earlier" | Run fresh test:gate NOW |
+| Skip for "small changes" | Every change gets tested |
+| Run test + deploy parallel | Sequential: test → gate → deploy |
+
+### Gate 2: Evidence Before Claims
+**ALWAYS** run the proving command before saying "fixed" or "done."
+
+### The Gate Function
+
+```
+1. IDENTIFY → What command proves this claim?
+2. RUN → Execute the FULL command (fresh)
+3. READ → Full output, check exit code
+4. VERIFY → Does output confirm the claim?
+5. ONLY THEN → Make the claim
+```
+
+### Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test output: 0 failures | "Should pass", previous run |
+| Build succeeds | Build: exit 0 | Linter passing |
+| Bug fixed | Test symptom: passes | Code changed, assumed fixed |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+### Red Flags — STOP
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification
+- Trusting agent success reports
+- ANY wording implying success without running verification
+
+### Gate 3: Frontend Integrity
+Automated via Layer 1 above.
+
+### When
+Setting up or enhancing test suites for projects with frontend JavaScript/TypeScript.
+
+### The 7 Layers
+
+| Layer | What it checks | Priority |
+|-------|---------------|----------|
+| 1. Syntax Validation | JS parses without errors (via acorn) | **CRITICAL** |
+| 2. Function Integrity | Named functions exist and are callable | Required |
+| 3. Template Safety | HTML templates have matching tags | Required |
+| 4. Asset References | Referenced files actually exist | Required |
+| 5. Corruption Patterns | Known bad patterns (empty functions, truncation) | Required |
+| 6. Import/Export | Module references resolve | Recommended |
+| 7. CSS Validation | CSS files parse correctly | Recommended |
+
+### Setup
+
+```bash
+npm install -D vitest acorn
+```
+
+### Layer 1: Syntax Check (Most Critical)
+
+```javascript
+import { parse } from 'acorn';
+import { readFileSync } from 'fs';
+
+test('app.js has valid syntax', () => {
+  const code = readFileSync('public/static/app.js', 'utf-8');
+  expect(() => parse(code, { ecmaVersion: 2022, sourceType: 'script' })).not.toThrow();
+});
+```
+
+> This single test would have prevented the March 2026 white-screen incident.
+
+---
+
+### Gate 4: Update Working Memory
+
+Per `_shared/helpers.md#Update-Continuity`
+
+After ALL gates pass → record `✅ Quality gate passed: [test count] tests, 0 failures`
+
+After ANY gate fails → **FIRST run Memory Integrity Check:**
+1. List active learnings/decisions for the failing module
+2. Ask: "Did AI follow a learning/decision that caused this failure?"
+3. If YES → HEAL memory (invalidate/correct/scope-reduce) BEFORE recording new learning
+4. Record meta-learning in `.cm/meta-learnings.json` if memory was the cause
+
+---
+
+### Gate 5: Quality Score Report
+
+After all gates execute, output a numeric quality score:
+
+```
+🎯 Gate Score: 87/100
+├── Secret Scan:      10/10 ✅
+├── Syntax:           10/10 ✅
+├── Tests:             8/10 ⚠️  (2 skipped tests)
+├── i18n Parity:      10/10 ✅
+├── Build:            10/10 ✅
+├── Dist Verify:      10/10 ✅
+├── Frontend Safety:   9/10 ✅
+└── Coverage:          7/10 ⚠️  (75% vs 80% target)
+```
+
+**Scoring Rules:**
+| Component | Max | How to Score |
+|-----------|-----|-------------|
+| Secret Scan | 10 | 10 = clean, 0 = any secret found |
+| Syntax | 10 | 10 = no errors, 0 = parse fails |
+| Tests | 15 | 15 = all pass, −2 per failure, −1 per skip |
+| i18n | 10 | 10 = parity, −5 per mismatch |
+| Build | 15 | 15 = clean build, 0 = build fails |
+| Dist Verify | 10 | 10 = all files present, −2 per missing |
+| Frontend Safety | 15 | 15 = all layers pass, −3 per failure |
+| Coverage | 15 | 15 = ≥80%, scale down linearly |
+
+**Thresholds:**
+- **≥80** → ✅ **PASS** — safe to deploy
+- **60-79** → ⚠️ **WARN** — deploy with caution, document risks
+- **<60** → ❌ **FAIL** — fix before deploy
+
+---
+
+## Integration
+| Skill | Relationship |
+|-------|-------------|
+| `cm-safe-deploy` | Quality gate is the primary blocker for the deploy pipeline |
+| `cm-identity-guard` | Verify identity before using quality gate to ship |
+| `cm-tdd` | TDD creates the logic for Layer 3 |
+| `cm-safe-i18n` | Leverages Layer 4 for parity checks |
+
+## The Bottom Line
+
+**Test before deploy. Evidence before claims. Safety before shipping. Non-negotiable.**