@jigyasudham/veto 0.8.0

package/src/skills/development/skill-crud.ts

@@ -0,0 +1,209 @@
+// Skill: crud — complete CRUD implementation guide
+
+export interface SkillInput {
+  task: string;
+  context?: string;
+  options?: Record<string, unknown>;
+}
+
+export interface SkillOutput {
+  skill: string;
+  template?: string;
+  checklist: string[];
+  patterns: string[];
+  gotchas: string[];
+  resources: string[];
+}
+
+const TEMPLATE = `
+// ── 1. Model (src/models/item.ts) ─────────────────────────────────────────
+export interface Item {
+  id: string;
+  name: string;
+  description?: string;
+  userId: string;       // ownership field — always include
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CreateItemInput {
+  name: string;
+  description?: string;
+}
+
+export interface UpdateItemInput {
+  name?: string;
+  description?: string;
+}
+
+// ── 2. Repository (src/repositories/item.repository.ts) ──────────────────
+export interface ItemRepository {
+  findById(id: string): Promise<Item | null>;
+  findAllByUser(userId: string): Promise<Item[]>;
+  create(userId: string, input: CreateItemInput): Promise<Item>;
+  update(id: string, input: UpdateItemInput): Promise<Item>;
+  delete(id: string): Promise<void>;
+}
+
+// PrismaItemRepository implements ItemRepository
+export class PrismaItemRepository implements ItemRepository {
+  constructor(private readonly db: PrismaClient) {}
+
+  async findById(id: string): Promise<Item | null> {
+    return this.db.item.findUnique({ where: { id } });
+  }
+
+  async findAllByUser(userId: string): Promise<Item[]> {
+    return this.db.item.findMany({ where: { userId }, orderBy: { createdAt: 'desc' } });
+  }
+
+  async create(userId: string, input: CreateItemInput): Promise<Item> {
+    return this.db.item.create({ data: { ...input, userId } });
+  }
+
+  async update(id: string, input: UpdateItemInput): Promise<Item> {
+    return this.db.item.update({ where: { id }, data: input });
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.db.item.delete({ where: { id } });
+  }
+}
+
+// ── 3. Service (src/services/item.service.ts) ────────────────────────────
+export class ItemService {
+  constructor(private readonly repo: ItemRepository) {}
+
+  async getItem(id: string, requestingUserId: string): Promise<Item> {
+    const item = await this.repo.findById(id);
+    if (!item) throw new NotFoundError('Item not found');
+    if (item.userId !== requestingUserId) throw new ForbiddenError('Access denied');
+    return item;
+  }
+
+  async listItems(userId: string): Promise<Item[]> {
+    return this.repo.findAllByUser(userId);
+  }
+
+  async createItem(userId: string, input: CreateItemInput): Promise<Item> {
+    return this.repo.create(userId, input);
+  }
+
+  async updateItem(id: string, input: UpdateItemInput, requestingUserId: string): Promise<Item> {
+    await this.getItem(id, requestingUserId); // throws if not found or not owned
+    return this.repo.update(id, input);
+  }
+
+  async deleteItem(id: string, requestingUserId: string): Promise<void> {
+    await this.getItem(id, requestingUserId); // ownership check
+    return this.repo.delete(id);
+  }
+}
+
+// ── 4. Controller (src/controllers/item.controller.ts) ───────────────────
+export class ItemController {
+  constructor(private readonly service: ItemService) {}
+
+  // GET /items
+  list = async (req: Request, res: Response): Promise<void> => {
+    const items = await this.service.listItems(req.user.id);
+    res.json({ data: items });
+  };
+
+  // GET /items/:id
+  get = async (req: Request, res: Response): Promise<void> => {
+    const item = await this.service.getItem(req.params.id, req.user.id);
+    res.json({ data: item });
+  };
+
+  // POST /items
+  create = async (req: Request, res: Response): Promise<void> => {
+    const item = await this.service.createItem(req.user.id, req.body);
+    res.status(201).json({ data: item });
+  };
+
+  // PATCH /items/:id
+  update = async (req: Request, res: Response): Promise<void> => {
+    const item = await this.service.updateItem(req.params.id, req.body, req.user.id);
+    res.json({ data: item });
+  };
+
+  // DELETE /items/:id
+  delete = async (req: Request, res: Response): Promise<void> => {
+    await this.service.deleteItem(req.params.id, req.user.id);
+    res.status(204).send();
+  };
+}
+
+// ── 5. Routes (src/routes/items.ts) ─────────────────────────────────────
+import { Router } from 'express';
+import { z } from 'zod';
+
+const CreateItemSchema = z.object({
+  name: z.string().min(1).max(100),
+  description: z.string().max(500).optional(),
+});
+
+const UpdateItemSchema = z.object({
+  name: z.string().min(1).max(100).optional(),
+  description: z.string().max(500).optional(),
+}).refine(obj => Object.keys(obj).length > 0, { message: 'At least one field required' });
+
+export function createItemRouter(controller: ItemController): Router {
+  const router = Router();
+  router.get('/', controller.list);
+  router.get('/:id', controller.get);
+  router.post('/', validate(CreateItemSchema), controller.create);
+  router.patch('/:id', validate(UpdateItemSchema), controller.update);
+  router.delete('/:id', controller.delete);
+  return router;
+}
+`.trim();
+
+export function run(input: SkillInput): SkillOutput {
+  return {
+    skill: 'crud',
+    template: TEMPLATE,
+    checklist: [
+      'Define TypeScript model interface with id, ownership field (userId), createdAt, updatedAt',
+      'Define separate CreateInput and UpdateInput types (no id, no userId, all update fields optional)',
+      'Create repository interface — program to the interface, not the implementation',
+      'Implement repository with Prisma/Drizzle/raw queries; keep DB logic isolated here',
+      'Implement service layer: all ownership and business rule checks happen here',
+      'Add service method getById that always checks ownership before returning data',
+      'Implement controller: parse request → call service → format response; no DB access',
+      'Create Zod schemas for create and update request bodies',
+      'Add validate middleware that runs Zod schema and returns 400 on failure',
+      'Register routes: GET / (list), GET /:id, POST / (create), PATCH /:id, DELETE /:id',
+      'Mount routes behind auth middleware so req.user is always populated',
+      'Add 204 No Content for successful DELETE (no body)',
+      'Add 201 Created with Location header for successful POST',
+      'Write unit tests for service layer (mock the repository)',
+      'Write integration tests covering happy path, 404, 403 (wrong user), 400 (bad input)',
+      'Add pagination to the list endpoint: limit/offset or cursor-based',
+      'Add filtering and sorting parameters to the list endpoint',
+      'Document all endpoints with JSDoc or OpenAPI comments',
+    ],
+    patterns: [
+      'Controller → Service → Repository three-layer architecture',
+      'Repository pattern: data access is behind an interface for testability',
+      'Ownership check in every service read/write operation (prevents IDOR)',
+      'Zod schema validation at the route boundary',
+      'Error-first service methods: throw typed errors, not returning null for auth failures',
+    ],
+    gotchas: [
+      'Forgetting ownership check in the service — returns any user\'s data via IDOR',
+      'Putting DB queries directly in controllers — bypasses repository layer and breaks tests',
+      'Not returning 404 before 403 — leaks resource existence to unauthorised users (use 404 for both)',
+      'Updating with empty body — add a Zod refine check that at least one field is present for PATCH',
+      'Not invalidating caches after update/delete — stale data returned to other users',
+      'Using findMany without a userId filter on list — returns all users\' data',
+    ],
+    resources: [
+      'https://www.prisma.io/docs/concepts/components/prisma-client/crud',
+      'https://zod.dev/',
+      'https://owasp.org/www-project-api-security/ (API4:2023 Broken Object Level Authorization)',
+      'https://expressjs.com/en/guide/routing.html',
+    ],
+  };
+}

package/src/skills/development/skill-scaffold.ts

@@ -0,0 +1,323 @@
+// Skill: scaffold — generates project scaffold structure for detected project type
+
+export interface SkillInput {
+  task: string;
+  context?: string;
+  options?: Record<string, unknown>;
+}
+
+export interface SkillOutput {
+  skill: string;
+  template?: string;
+  checklist: string[];
+  patterns: string[];
+  gotchas: string[];
+  resources: string[];
+}
+
+type ProjectType = 'rest-api' | 'full-stack' | 'cli' | 'library' | 'generic';
+
+function detectProjectType(task: string): ProjectType {
+  const t = task.toLowerCase();
+  if (/\bcli\b|command[\s-]?line|commander|yargs|oclif/.test(t)) return 'cli';
+  if (/\blibrary\b|npm\s+package|sdk|module|publishable/.test(t)) return 'library';
+  if (/\bfull[\s-]?stack\b|next\.?js|nuxt|remix|frontend\s*\+\s*backend/.test(t)) return 'full-stack';
+  if (/\bapi\b|rest(?:ful)?|express|fastify|hono|koa|endpoint/.test(t)) return 'rest-api';
+  return 'generic';
+}
+
+const TEMPLATES: Record<ProjectType, string> = {
+  'rest-api': `
+my-api/
+├── src/
+│   ├── index.ts              # Entry point — creates and starts the server
+│   ├── app.ts                # Express/Fastify app factory (no listen call)
+│   ├── config/
+│   │   └── env.ts            # Typed env validation with zod
+│   ├── routes/
+│   │   ├── index.ts          # Route aggregator
+│   │   └── health.ts         # GET /health — liveness probe
+│   ├── controllers/          # HTTP layer: parse request, call service, send response
+│   ├── services/             # Business logic — no HTTP types
+│   ├── repositories/         # Data access layer — DB queries only
+│   ├── middleware/
+│   │   ├── auth.ts           # JWT / session verification
+│   │   ├── validate.ts       # Zod request schema validation
+│   │   └── error-handler.ts  # Centralised error → HTTP response mapping
+│   ├── models/               # TypeScript interfaces / Prisma types
+│   └── utils/
+│       ├── logger.ts         # Pino / Winston structured logger
+│       └── errors.ts         # Typed application error classes
+├── tests/
+│   ├── unit/                 # Service and utility unit tests
+│   ├── integration/          # Route-level supertest tests
+│   └── fixtures/             # Test data factories
+├── .env.example              # Template with all required env keys (no real values)
+├── .gitignore
+├── .eslintrc.json
+├── .prettierrc
+├── tsconfig.json
+├── jest.config.ts            # Or vitest.config.ts
+├── Dockerfile
+├── docker-compose.yml
+└── package.json
+`.trim(),
+
+  'full-stack': `
+my-app/
+├── apps/
+│   ├── web/                  # Frontend (React / Next.js / Astro)
+│   │   ├── src/
+│   │   │   ├── app/          # Next.js App Router pages
+│   │   │   ├── components/   # Shared UI components
+│   │   │   ├── hooks/        # Custom React hooks
+│   │   │   ├── lib/          # API client, utilities
+│   │   │   └── styles/       # Global CSS / Tailwind config
+│   │   └── package.json
+│   └── api/                  # Backend (Express / Fastify)
+│       ├── src/
+│       │   ├── routes/
+│       │   ├── services/
+│       │   └── repositories/
+│       └── package.json
+├── packages/
+│   ├── ui/                   # Shared component library
+│   ├── types/                # Shared TypeScript types between frontend and backend
+│   └── config/               # Shared ESLint, tsconfig base
+├── infra/                    # IaC (Terraform / Pulumi / CDK)
+├── .env.example
+├── pnpm-workspace.yaml       # Or turbo.json for Turborepo
+├── turbo.json
+└── package.json
+`.trim(),
+
+  cli: `
+my-cli/
+├── src/
+│   ├── index.ts              # Entry point — calls main()
+│   ├── cli.ts                # Commander / yargs setup, command registration
+│   ├── commands/
+│   │   ├── index.ts          # Command exports
+│   │   └── init.ts           # Example: "my-cli init" command
+│   ├── config/
+│   │   ├── loader.ts         # Reads ~/.my-cli/config.json or XDG config
+│   │   └── schema.ts         # Zod schema for config validation
+│   ├── utils/
+│   │   ├── logger.ts         # Chalk-powered coloured console output
+│   │   ├── spinner.ts        # Ora spinner wrapper
+│   │   └── prompt.ts         # Inquirer / clack prompt helpers
+│   └── errors.ts             # CLI-specific error classes with exit codes
+├── tests/
+│   ├── commands/             # Command unit tests
+│   └── integration/          # Full CLI invocation tests via execa
+├── bin/
+│   └── my-cli.js             # Executable shim (#!/usr/bin/env node)
+├── .env.example
+├── .gitignore
+├── tsconfig.json
+├── tsconfig.build.json       # Excludes test files from build output
+├── package.json              # "bin" field pointing to dist/index.js
+└── README.md
+`.trim(),
+
+  library: `
+my-library/
+├── src/
+│   ├── index.ts              # Public API barrel — re-exports only the public surface
+│   ├── core/                 # Core implementation modules
+│   ├── types/
+│   │   └── index.ts          # Exported TypeScript types and interfaces
+│   └── utils/                # Internal utilities (not exported)
+├── tests/
+│   ├── unit/
+│   └── snapshots/
+├── examples/                 # Runnable usage examples
+├── scripts/
+│   └── build.ts              # Build script (tsup / rollup / esbuild)
+├── .env.example
+├── .gitignore
+├── .eslintrc.json
+├── .prettierrc
+├── tsconfig.json
+├── tsup.config.ts            # Bundles CJS + ESM + type declarations
+├── vitest.config.ts
+├── CHANGELOG.md
+└── package.json              # "exports", "main", "module", "types" fields
+`.trim(),
+
+  generic: `
+my-project/
+├── src/
+│   ├── index.ts              # Entry point
+│   └── lib/                  # Core modules
+├── tests/
+├── .env.example
+├── .gitignore
+├── tsconfig.json
+└── package.json
+`.trim(),
+};
+
+const CHECKLISTS: Record<ProjectType, string[]> = {
+  'rest-api': [
+    'Run: npm init -y && git init && echo "node_modules" > .gitignore',
+    'Install TypeScript: npm install -D typescript ts-node @types/node && npx tsc --init',
+    'Configure tsconfig.json: strict:true, outDir:dist, rootDir:src, target:ES2022',
+    'Install framework: npm install express && npm install -D @types/express',
+    'Install security middleware: npm install helmet express-rate-limit cors',
+    'Install validation: npm install zod',
+    'Install logger: npm install pino && npm install -D pino-pretty',
+    'Set up database ORM: npm install prisma && npx prisma init',
+    'Configure ESLint and Prettier: npm install -D eslint @typescript-eslint/parser prettier',
+    'Install testing: npm install -D vitest supertest @types/supertest',
+    'Create .env.example with all required variables; add .env to .gitignore',
+    'Write src/app.ts factory and src/index.ts entry point',
+    'Add npm scripts: dev (ts-node-dev), build (tsc), start (node dist/index.js), test, lint',
+    'Write a Dockerfile with multi-stage build: builder + production runner',
+    'Set up GitHub Actions CI: install → lint → test → build on every PR',
+    'Add docker-compose.yml for local development with database service',
+  ],
+  'full-stack': [
+    'Initialise monorepo: npm install -D turbo && pnpm init (or use create-turbo)',
+    'Create pnpm-workspace.yaml listing apps/* and packages/*',
+    'Scaffold frontend: pnpm create next-app apps/web --typescript',
+    'Scaffold backend: follow rest-api checklist in apps/api',
+    'Create packages/types with shared TypeScript interfaces',
+    'Create packages/config with shared tsconfig.base.json and eslint config',
+    'Configure Turborepo pipeline in turbo.json: build, test, lint tasks',
+    'Set up shared environment: turbo.env or dotenv in each app',
+    'Install Tailwind CSS and shadcn/ui in apps/web',
+    'Set up API client in apps/web/src/lib/api.ts using fetch with typed responses',
+    'Configure CORS in apps/api to allow the web origin in development',
+    'Add Prettier and ESLint configs in packages/config; extend in each app',
+    'Write GitHub Actions matrix workflow that tests each app independently',
+    'Write docker-compose.yml that starts both apps and their dependencies',
+  ],
+  cli: [
+    'npm init -y && git init',
+    'Install TypeScript: npm install -D typescript @types/node && npx tsc --init',
+    'Install CLI framework: npm install commander && npm install -D @types/commander',
+    'Install UX tools: npm install chalk ora inquirer && npm install -D @types/inquirer',
+    'Install build tool: npm install -D tsup',
+    'Configure package.json: add "bin" field, "files" field, and build/dev scripts',
+    'Create bin/my-cli.js shim with #!/usr/bin/env node pointing to dist/index.js',
+    'Set "prepublishOnly" script to run build and tests before npm publish',
+    'Create src/cli.ts with the Commander program definition',
+    'Add at least one example command in src/commands/',
+    'Write integration tests using execa to invoke the compiled CLI binary',
+    'Set up ESLint and Prettier',
+    'Add GitHub Actions workflow: test on push + publish to npm on release tag',
+    'Write README.md with installation and usage examples',
+  ],
+  library: [
+    'npm init -y && git init',
+    'Install TypeScript and tsup: npm install -D typescript tsup',
+    'Configure tsconfig.json with strict:true, declaration:true, declarationMap:true',
+    'Configure tsup.config.ts: entry src/index.ts, formats [cjs, esm], dts:true',
+    'Set package.json "exports", "main", "module", "types" fields for dual CJS/ESM',
+    'Add "files" field to package.json to only publish src + dist, not tests',
+    'Install vitest for testing: npm install -D vitest',
+    'Install Changesets for versioning: npm install -D @changesets/cli && npx changeset init',
+    'Write public API in src/index.ts; keep internal modules unexported',
+    'Write tests covering edge cases, error paths, and type narrowing',
+    'Add ESLint with @typescript-eslint and prettier',
+    'Create examples/ directory with a working usage example',
+    'Set up GitHub Actions: test → build → publish on changeset release',
+    'Add CHANGELOG.md and seed first version with npx changeset',
+  ],
+  generic: [
+    'npm init -y && git init',
+    'Install TypeScript: npm install -D typescript && npx tsc --init',
+    'Add strict TypeScript configuration',
+    'Set up ESLint and Prettier',
+    'Install testing framework (vitest or jest)',
+    'Create .env.example and add .env to .gitignore',
+    'Add CI workflow (GitHub Actions)',
+    'Write README with purpose, setup, and usage',
+  ],
+};
+
+const PATTERNS_MAP: Record<ProjectType, string[]> = {
+  'rest-api': ['Controller → Service → Repository layered architecture', 'Middleware chain for cross-cutting concerns', 'Dependency injection via constructor parameters'],
+  'full-stack': ['Turborepo monorepo with shared packages', 'Type-sharing between frontend and backend via shared package', 'API contract-first development'],
+  cli: ['Commander subcommand pattern', 'Config file with XDG base directory spec', 'Spinner + prompt UX pattern'],
+  library: ['Barrel export pattern (src/index.ts as public API surface)', 'Dual CJS/ESM build with tsup', 'Semantic versioning with Changesets'],
+  generic: ['Separation of concerns', 'Environment-based configuration', 'Test-driven development'],
+};
+
+const GOTCHAS: Record<ProjectType, string[]> = {
+  'rest-api': [
+    'Not separating app factory from server listen — makes supertest integration tests impossible',
+    'Importing from .ts paths instead of .js in ESM projects — Node requires .js extensions at runtime',
+    'Forgetting to handle unhandled promise rejections: process.on("unhandledRejection")',
+    'Not setting NODE_ENV=production in Docker — some libraries skip optimisations',
+  ],
+  'full-stack': [
+    'pnpm hoisting rules differ from npm — some packages require explicit workspace installation',
+    'Turbo caches outputs — always define "outputs" in turbo.json or caching will miss files',
+    'Next.js Server Actions run on the server but are bundled client-side if marked incorrectly',
+    'CORS in development must allow the exact origin including port number',
+  ],
+  cli: [
+    'bin script must have chmod +x and #!/usr/bin/env node shebang — otherwise it won\'t run on Unix',
+    'Using process.exit() inside async code without await — unhandled async errors go silently',
+    'Global config paths differ per OS — use the "env-paths" package for cross-platform XDG dirs',
+    'Not handling SIGINT / SIGTERM — CLI leaves terminal in bad state on Ctrl+C',
+  ],
+  library: [
+    'Publishing src/ instead of dist/ — consumers get TypeScript source, not compiled output',
+    'Missing "exports" field in package.json — prevents dual CJS/ESM consumers from working',
+    'Exporting internal implementation details — breaks semver compatibility on refactors',
+    'Not testing the built package locally with "npm link" before publishing',
+  ],
+  generic: [
+    'Committing .env files — always add to .gitignore before the first commit',
+    'Missing tsconfig strict mode — allows silent type errors',
+    'No CI from the start — technical debt accumulates quickly without automated checks',
+  ],
+};
+
+const RESOURCES: Record<ProjectType, string[]> = {
+  'rest-api': [
+    'https://expressjs.com/en/advanced/best-practice-security.html',
+    'https://www.prisma.io/docs/getting-started',
+    'https://vitest.dev/guide/',
+    'https://docs.npmjs.com/cli/v10/configuring-npm/package-json#main',
+  ],
+  'full-stack': [
+    'https://turbo.build/repo/docs',
+    'https://nextjs.org/docs',
+    'https://pnpm.io/workspaces',
+    'https://ui.shadcn.com/docs',
+  ],
+  cli: [
+    'https://www.npmjs.com/package/commander',
+    'https://www.npmjs.com/package/ora',
+    'https://www.npmjs.com/package/inquirer',
+    'https://tsup.egoist.dev/',
+  ],
+  library: [
+    'https://tsup.egoist.dev/',
+    'https://github.com/changesets/changesets',
+    'https://www.typescriptlang.org/docs/handbook/declaration-files/dts-from-js.html',
+    'https://nodejs.org/api/packages.html#package-entry-points',
+  ],
+  generic: [
+    'https://www.typescriptlang.org/docs/handbook/tsconfig-json.html',
+    'https://vitest.dev/guide/',
+    'https://eslint.org/docs/latest/use/getting-started',
+  ],
+};
+
+export function run(input: SkillInput): SkillOutput {
+  const projectType = detectProjectType(input.task);
+
+  return {
+    skill: 'scaffold',
+    template: TEMPLATES[projectType],
+    checklist: CHECKLISTS[projectType],
+    patterns: PATTERNS_MAP[projectType],
+    gotchas: GOTCHAS[projectType],
+    resources: RESOURCES[projectType],
+  };
+}

package/src/skills/intelligence/skill-complexity-score.ts

@@ -0,0 +1,69 @@
+// Skill: complexity-score — how to write task descriptions that route correctly
+
+export interface SkillInput { task: string; context?: string; options?: Record<string, unknown>; }
+export interface SkillOutput { skill: string; template?: string; checklist: string[]; patterns: string[]; gotchas: string[]; resources: string[]; }
+
+export function run(input: SkillInput): SkillOutput {
+  return {
+    skill: 'complexity-score',
+    template: `
+// ── Complexity Scoring Cheat Sheet ───────────────────────────────────────
+//
+// The router scores 0–100 from five factors:
+//
+// Factor 1: Word count        0–20 pts  (1 pt per 3 words, cap 20)
+// Factor 2: Tech keywords     0–30 pts  HIGH +5, MEDIUM +2
+// Factor 3: Task depth        0–20 pts  conjunctions, commas, length
+// Factor 4: Files affected    0–20 pts  3 pts per file
+// Factor 5: Council bonus     +10 pts   security/auth/migration keywords
+//
+// Tier thresholds (defaults, adjusted by learning loop):
+//   Tier 1: score 0–30   → Haiku / Flash  (fast, cheap)
+//   Tier 2: score 31–70  → Sonnet / Pro   (daily coding)
+//   Tier 3: score 71+    → Sonnet / Advanced  (hard problems)
+//
+// To get a higher tier: add detail, technical keywords, or pass files_affected
+// To get a lower tier: simplify the description or scope down the task
+//
+// Example — under-scored:
+//   "write tests"  →  score 9  →  Tier 1  (too short)
+//
+// Example — correctly scored:
+//   "write unit and integration tests for the JWT auth middleware, covering
+//    token expiry, refresh rotation, and concurrent request edge cases"
+//   →  score 47  →  Tier 2
+//
+// Example — correctly scored, high complexity:
+//   "migrate user authentication from session cookies to JWT with refresh
+//    token rotation — update middleware, session store, and all auth tests"
+//   →  score 78  →  Tier 3 (contains 'migrate', 'authentication', 'jwt')
+`.trim(),
+    checklist: [
+      'Call veto_route_task to see the current score before submitting a task',
+      'If the score is too low: add technical keywords and more specific detail to the description',
+      'If the score is too high: simplify the description or split into sub-tasks',
+      'Pass files_affected if the task touches multiple files — adds 3 pts per file',
+      'Use force_council=true to bypass scoring and go straight to Tier 3',
+      'After completing a task: call veto_record_outcome with the actual quality (0–100)',
+      'After 20+ outcomes: call veto_learning_apply to update the router thresholds',
+    ],
+    patterns: [
+      'Specificity → score: more specific descriptions score higher and route to better models',
+      'Keyword density: security/auth/migration keywords add +5 each and trigger council',
+      'files_affected multiplier: 5 files = +12 pts — use this for multi-file refactors',
+      'Outcome feedback: recording actuals enables the learning loop to tune thresholds over time',
+    ],
+    gotchas: [
+      'Short task descriptions under-score — "fix auth bug" scores ~9, Tier 1 is almost certainly wrong for auth',
+      'The learning loop needs 20 outcomes before it adjusts thresholds — the router is static until then',
+      'force_council=true always routes to Tier 3 regardless of score — use sparingly',
+      'Council auto-triggers on: architecture, security, auth, migration, drop table — you cannot suppress this',
+    ],
+    resources: [
+      'veto_route_task — score a task and see the tier before submitting',
+      'veto_record_outcome — record output quality to feed the learning loop',
+      'veto_learning_apply — apply learned thresholds after 20+ recorded outcomes',
+      'veto_learning_stats — see current tier distribution and suggested thresholds',
+    ],
+  };
+}

package/src/skills/intelligence/skill-cost-track.ts

@@ -0,0 +1,39 @@
+// Skill: cost-track — monitor and reduce AI token spend and infrastructure costs
+
+export interface SkillInput { task: string; context?: string; options?: Record<string, unknown>; }
+export interface SkillOutput { skill: string; checklist: string[]; patterns: string[]; gotchas: string[]; resources: string[]; }
+
+export function run(input: SkillInput): SkillOutput {
+  return {
+    skill: 'cost-track',
+    checklist: [
+      'Call veto_learning_stats to see the current Tier 1/2/3 distribution',
+      'A healthy distribution is roughly 40% T1 / 45% T2 / 15% T3 — more T3 than this is expensive',
+      'Identify tasks that are routed to Tier 3 but could be Tier 2 with a better description',
+      'Call veto_rate_status to check current daily usage % per platform',
+      'If Claude is above 70%: T1/T2 tasks are already auto-routing to Gemini — verify this is working',
+      'Call veto_agent_performance_stats to identify agents with low quality scores — they waste tokens on retries',
+      'Record task outcomes via veto_record_outcome — this is the only way to measure actual cost/quality ratio',
+      'After 20+ outcomes: call veto_learning_apply — learned thresholds reduce over-routing to expensive tiers',
+      'Monthly: export veto_memory_export and review knowledge base size — prune irrelevant entries',
+    ],
+    patterns: [
+      'Tier distribution monitoring: T3% × avg_T3_tokens = the main cost driver',
+      'Outcome recording: quality data enables threshold calibration which directly reduces cost',
+      'Rate limit utilisation: 70–90% is healthy; under 30% means you are paying for unused capacity',
+      'Context compression: veto_route_task with context= returns a compression plan — use it',
+    ],
+    gotchas: [
+      'Not recording outcomes — the learning loop cannot calibrate without quality data',
+      'Treating all Tier 3 tasks as justified — many are there because of a short description, not actual complexity',
+      'Ignoring context compression — a 15,000 token context costs 10× more than a compressed 1,500 token context',
+      'Optimising AI cost while ignoring developer time — developer time is almost always the larger cost',
+    ],
+    resources: [
+      'veto_learning_stats — current tier distribution and suggested thresholds',
+      'veto_rate_status — daily usage % per platform',
+      'veto_learning_apply — apply learned thresholds to reduce over-routing',
+      'veto_record_outcome — record output quality to feed the cost/quality calibration loop',
+    ],
+  };
+}