@minhpnq1807/contextos 0.6.3 → 0.6.5

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.6.5
+
+- **Generated skill frontmatter:** Fixed `ctx doctor --fix` starter `SKILL.md` output so generated project skills include YAML frontmatter with `name` and `description`. This prevents invalid-skill warnings after generated skills are synced through skillshare.
+
+## 0.6.4
+
+- **Project context generator:** Added `ctx doctor --fix` and `ctx setup --generate-project-context` to explicitly scaffold starter project skills and a primary workflow when a repository has rules but is missing ContextOS-ready skills/workflows. Generation is repo-scoped, does not run from `npm install`, and does not overwrite existing files unless `--force` is passed to `ctx doctor --fix`.
+
 ## 0.6.3
 
 - **Launch benchmark wording:** Clarified that `ctx leaderboard --hallucination` is an offline deterministic benchmark comparing a raw heuristic baseline with ContextOS evidence-based context selection, while live agent results remain pending external CLI environments.

package/README.md

@@ -1,109 +1,45 @@
 # ContextOS
 
-Stop coding agents from ignoring repo rules, guessing the wrong path, and reading random files.
+Same prompt. Same model. Different context.
 
-ContextOS gives the agent the right rules, files, skills, workflows, and evidence before it writes code.
+ContextOS stops coding agents from ignoring repo rules, guessing the wrong path, and reading random files.
 
 [![npm version](https://img.shields.io/npm/v/@minhpnq1807/contextos.svg)](https://www.npmjs.com/package/@minhpnq1807/contextos)
 [![CI](https://github.com/khovan123/contextOS/actions/workflows/ci.yml/badge.svg)](https://github.com/khovan123/contextOS/actions/workflows/ci.yml)
-[![ContextOS Ready](https://img.shields.io/badge/ContextOS-Ready_Gold-2ea44f)](#contextos-ready)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ```text
-Problem: Agents ignore project rules.
-Fix: ContextOS puts the relevant AGENTS.md rules in front of the agent for this task.
+Prompt:
+Fix deployment
 
-Problem: Agents choose the wrong deployment path.
-Fix: ContextOS checks repo evidence before suggesting skills like EAS, Vercel, Docker, or CI/CD.
+Raw Agent:
+❌ Vercel
+❌ Docker
+❌ Railway
 
-Problem: Agents grep random files.
-Fix: ContextOS suggests the files and workflows to check first.
+ContextOS:
+✅ EAS
+✅ Mobile Deployment
+✅ GitHub Actions
 ```
 
-ContextOS is not another `AGENTS.md` loader. It is a pre-flight context layer for coding agents: it turns repo rules, project signals, skills, workflows, and evidence into a compact task brief before the agent starts editing.
+ContextOS reads the repo before the agent starts: project rules, repo evidence, suggested files, skills, workflows, and post-task proof.
 
 Published package: [`@minhpnq1807/contextos`](https://www.npmjs.com/package/@minhpnq1807/contextos)
 
-## Demo
-
-![ContextOS demo: same prompt, different repo, correct skills](docs/demo/same-prompt-different-context.gif)
-
-Same prompt. Same model. Different context.
-
-```bash
-ctx skills doctor -- "fix deployed"
-```
-
-| Repo evidence | What ContextOS tells the agent |
-| --- | --- |
-| `eas.json`, `expo`, `react-native` | `eas`, `mobile-deployment`, `github-actions-ci-cd` |
-| `vercel.json`, `next`, GitHub workflow | `vercel-deployment`, `github-actions-ci-cd`, `env-secret-management` |
-| ContextOS repo with no app deploy evidence | no deployment skill selected |
-
-More 10-second demos:
-
-| Demo | GIF |
-| --- | --- |
-| AGENTS.md Lost In The Middle | [docs/demo/agents-lost-middle.gif](docs/demo/agents-lost-middle.gif) |
-| ContextOS Ready Gold | [docs/demo/contextos-ready.gif](docs/demo/contextos-ready.gif) |
-
-Regenerate the GIFs from real local `ctx` command output:
-
-```bash
-npm run demo:capture
-```
-
-## Wrong Path Benchmark
+## Hallucination Leaderboard
 
-Generic agents often guess deployment tooling from the prompt alone:
+Offline deterministic benchmark:
 
-```text
-Prompt: Fix deployment
-Raw agent guess: Vercel, Docker, Railway
-```
-
-ContextOS checks the repo first:
-
-```text
-Detected evidence:
-- eas.json
-- expo dependency
-- GitHub workflow
-
-Selected skills:
-- eas
-- mobile-deployment
-- github-actions-ci-cd
-```
-
-That is the core launch demo: same prompt, same model, different repo, correct next step.
-
-Internal fixture benchmark:
-
-| Metric | Result |
+| System | Correct context choice |
 | --- | ---: |
-| Cases | 52 |
-| Top-1 Accuracy | 94.2% |
-| Top-3 Recall | 94.2% |
-| False Positive Rate | 0.0% |
-| Confidence Calibration | 100.0% |
-| Negative Gate Accuracy | 100.0% |
-
-This is an internal fixture benchmark, not an external real-world benchmark. It is designed to prove that ContextOS changes its suggestions from repo evidence across controlled Expo/EAS, Next/Vercel, Docker, Railway/Render, Firebase, auth, database, testing, mobile, and adversarial negative cases.
-
-Offline hallucination leaderboard:
+| Raw heuristic baseline | 10.0% |
+| ContextOS evidence benchmark | 80.0% |
 
 ```bash
 ctx leaderboard --hallucination
 ```
 
-Current deterministic result across 20 fixture tasks and 12 repo contexts:
-
-| System | Correct context choice |
-| --- | ---: |
-| Raw heuristic baseline | 10.0% |
-| ContextOS evidence benchmark | 80.0% |
-
 This means ContextOS improves deterministic context routing from 10% to 80% on the offline hallucination task set. It does not claim ContextOS beats Codex, Gemini, Claude Code, or Cursor in live runs.
 
 Live agent benchmark support exists, but results are pending an external environment with working CLI auth/session access:
@@ -122,7 +58,36 @@ Live benchmark tracking:
 - [Run Gemini CLI live benchmark](https://github.com/khovan123/contextOS/issues/4)
 - [Run Cursor live benchmark](https://github.com/khovan123/contextOS/issues/2)
 
-Example hook context injected before the agent works:
+## Why People Star ContextOS
+
+- Agents ignore `AGENTS.md`.
+- Agents choose the wrong deployment path.
+- Agents grep random files before understanding the repo.
+- ContextOS fixes all three before coding starts.
+
+## Demo
+
+![ContextOS demo: same prompt, different repo, correct skills](docs/demo/same-prompt-different-context.gif)
+
+```bash
+ctx skills doctor -- "fix deployed"
+```
+
+| Repo evidence | What ContextOS tells the agent |
+| --- | --- |
+| `eas.json`, `expo`, `react-native` | `eas`, `mobile-deployment`, `github-actions-ci-cd` |
+| `vercel.json`, `next`, GitHub workflow | `vercel-deployment`, `github-actions-ci-cd`, `env-secret-management` |
+| ContextOS repo with no app deploy evidence | no deployment skill selected |
+
+More 10-second demo:
+
+| Demo | GIF |
+| --- | --- |
+| AGENTS.md Lost In The Middle | [docs/demo/agents-lost-middle.gif](docs/demo/agents-lost-middle.gif) |
+
+## What The Agent Sees
+
+ContextOS injects a compact brief before the agent works:
 
 ```text
 ## Critical ContextOS rules
@@ -148,6 +113,27 @@ Rule outcomes: 8 followed, 0 ignored, 0 unknown
 Runtime evidence: project graph was used before file search
 ```
 
+Regenerate the GIFs from real local `ctx` command output:
+
+```bash
+npm run demo:capture
+```
+
+## Internal Benchmark
+
+Skill selection fixture benchmark:
+
+| Metric | Result |
+| --- | ---: |
+| Cases | 52 |
+| Top-1 Accuracy | 94.2% |
+| Top-3 Recall | 94.2% |
+| False Positive Rate | 0.0% |
+| Confidence Calibration | 100.0% |
+| Negative Gate Accuracy | 100.0% |
+
+This is an internal fixture benchmark, not an external real-world benchmark. It is designed to prove that ContextOS changes its suggestions from repo evidence across controlled Expo/EAS, Next/Vercel, Docker, Railway/Render, Firebase, auth, database, testing, mobile, and adversarial negative cases.
+
 ## Quick Install
 
 Install in 30 seconds:
@@ -164,6 +150,13 @@ Scriptable setup:
 ```bash
 ctx setup --yes
 ctx setup --yes --agents codex,claude,agy
+ctx setup --yes --generate-project-context
+```
+
+If `ctx doctor` reports missing project skills/workflows, generate starter project context explicitly:
+
+```bash
+ctx doctor --fix
 ```
 
 No global install:
@@ -188,27 +181,6 @@ ctx install agy
 
 Restart the agent after setup. Then use the agent normally.
 
-## Why ContextOS Exists
-
-Developers put real operating instructions in `AGENTS.md`: use this graph tool before reading files, run these tests, follow this architecture boundary, avoid this migration path.
-
-The problem is not that agents cannot read `AGENTS.md`. The problem is that large context windows bury the important rule in the middle, where attention is weak.
-
-The same thing happens with project structure:
-
-- A deployment prompt says "fix deploy", and the agent guesses Vercel in an Expo repo.
-- A backend error mentions Fastify, and the agent loads frontend skills.
-- A feature request names one route, and the agent starts with broad grep instead of the files that matter.
-
-ContextOS fixes those three failures before the agent starts work.
-
-The next visible demo is not another feature. It is showing the pain in a few seconds:
-
-```text
-Raw agent: guesses from the prompt.
-ContextOS: checks repo evidence first.
-```
-
 ## What ContextOS Does
 
 | Agent failure | ContextOS behavior |
@@ -290,6 +262,7 @@ The score checks project `AGENTS.md` rules, project skill packs under `.codex/sk
 | `ctx setup` | Recommended first-run install flow. |
 | `ctx debug -- "Recheck authen flow"` | Preview what ContextOS would inject. |
 | `ctx doctor` | Score repository readiness for the `ContextOS Ready` badge. |
+| `ctx doctor --fix` | Generate starter project skills and workflow when the repo is missing them. |
 | `ctx report` | Show the last task's compliance summary. |
 | `ctx evidence` | Show why each rule was marked followed/ignored/unknown. |
 | `ctx stats` | Show workspace-level usage and effectiveness metrics. |
@@ -611,12 +584,14 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx install --copy` | Copies only the plugin payload to `$CODEX_HOME/plugins/ctx`. | Legacy local development or manual plugin experiments. | Does not sync the active marketplace, rebuild indexes, register MCP, or install global hooks. Prefer `ctx refresh` for active local updates. |
 | `ctx setup` | Runs the first-run setup wizard. | You want the recommended onboarding flow after `npm install -g @minhpnq1807/contextos`. | Installs selected agents, optionally syncs Ruler rules/MCP and skillshare skills, asks which prompt sections to show, then prints next steps. |
 | `ctx setup --yes` | Runs setup with defaults non-interactively. | You want scriptable Codex setup. | Uses `codex`, enables injection, syncs rules, syncs skills, skips interactive community-skill installation when no TTY is available, and passes `--yes` to dependency setup prompts. Use `--agents codex,claude,agy` for multi-agent setup. |
+| `ctx setup --generate-project-context` | Generates starter project skills and workflow during setup. | Your repo has rules but `ctx doctor` reports missing skills/workflows. | Creates `.codex/skills/<detected-skill>/SKILL.md`, matching `skill.yaml`, and `.codex/workflows/primary.md` without overwriting existing files. |
 | `ctx setup --agents <list>` | Runs setup for selected agents. | You want only part of the default set. | Accepts comma-separated `codex`, `claude`, `agy`, or `antigravity`. |
 | `ctx setup --no-rules` | Skips Ruler sync during setup. | You only want hooks/MCP install and maybe skill sync. | Does not run `ctx sync --rules`. |
 | `ctx setup --no-skills` | Skips skillshare sync during setup. | You do not want shared skills configured. | Does not run `ctx sync --skills`. |
 | `ctx setup --quiet` | Runs setup in measurement-only mode. | You want reports/stats without visible injected prompt context. | Installs hooks with prompt context injection disabled. |
 | `ctx debug -- "task"` | Runs the scheduler locally for a fake prompt. | You want to see which AGENTS.md rules and files ContextOS would inject before using Codex. | Prints rule scores, scoring reasons, suggested files, and final `additionalContext`. |
 | `ctx doctor` | Scores repository ContextOS readiness. | You want to add or verify a `ContextOS Ready` badge. | Prints Rules, Skills, Workflows, Overall tier, evidence, and next recommendations. |
+| `ctx doctor --fix` | Generates starter ContextOS project context. | `ctx doctor` says skills/workflows are missing and you want explicit local scaffolding. | Detects package/config evidence, creates up to three starter project skills plus `.codex/workflows/primary.md`, then prints the updated readiness score. |
 | `ctx report` | Shows the last Stop-hook compliance report for the current workspace. | An agent task has finished and you want the summary again. | Prints sectioned tables for summary, rule outcomes, suggested files, and runtime telemetry from `~/.ctx/contextos/workspaces/<workspace-id>/last-report.json`. |
 | `ctx evidence` | Shows detailed evidence behind the last report for the current workspace. | You want to inspect why a rule was marked `followed`, `ignored`, `unknown`, or `unmeasurable`. | Prints a compact evidence table plus per-rule detail tables. |
 | `ctx stats` | Shows aggregate runtime metrics for the current workspace. | You want to know whether ContextOS is active and useful over time. | Prints sectioned tables for prompt/report counts, injection rate, efficiency, rule outcomes, hook events, last prompt, and last report. |

package/bin/ctx.js

@@ -44,6 +44,7 @@ import { fetchSkillsForAgents, printSkillRecommendations, getAllLibraries, getIn
 import { invalidateCtxMcpSocket } from "../plugins/ctx/lib/ctx-mcp-client.js";
 import { runPrefixedCommand } from "../plugins/ctx/lib/shell-runner.js";
 import { formatContextOSReady, inspectContextOSReady } from "../plugins/ctx/lib/certification.js";
+import { formatProjectContextGeneration, generateProjectContext } from "../plugins/ctx/lib/project-context-generator.js";
 
 /**
  * Run a shell command with all output lines prefixed by │  
@@ -189,11 +190,14 @@ Usage:
   ctx setup                                         Interactive full setup wizard
   ctx setup --yes                                   Auto-confirm all setup prompts
   ctx setup --agents <names>                        Pre-select agents to install
+  ctx setup --generate-project-context              Generate starter project skills/workflow
   ctx setup --no-rules                              Skip AGENTS.md rule sync
   ctx setup --no-skills                             Skip skill sync
   ctx setup --quiet                                 Quiet mode (minimal output)
   ctx debug -- "task"                               Debug a task with ContextOS tracing
   ctx doctor                                       Score repository ContextOS readiness
+  ctx doctor --fix                                 Generate starter project skills/workflow
+  ctx doctor --fix --force                         Regenerate starter project context files
   ctx report                                        Show last ContextOS compliance report
   ctx evidence                                      Show evidence from last report
   ctx stats                                         Show workspace statistics
@@ -880,6 +884,22 @@ async function setup({ args = [], cwd = process.cwd() } = {}) {
     });
   }
 
+  if (interactive && !options.generateProjectContext) {
+    const readiness = inspectContextOSReady({ cwd });
+    if (readiness.skills.score < 50 || readiness.workflows.score < 50) {
+      const rl = readline.createInterface({ input, output });
+      try {
+        options.generateProjectContext = await askSetupYesNo(
+          rl,
+          "Generate starter project skills and workflow?",
+          true
+        );
+      } finally {
+        rl.close();
+      }
+    }
+  }
+
   console.log("");
   console.log("◇ Ready to setup:");
   for (const line of setupSummaryLines({
@@ -892,6 +912,13 @@ async function setup({ args = [], cwd = process.cwd() } = {}) {
 
   if (!options.agents.length) throw new Error("No agents selected. Use --agents codex,claude,antigravity,copilot.");
 
+  if (options.generateProjectContext) {
+    console.log("◇ Generating starter project context...");
+    const generated = generateProjectContext({ cwd });
+    for (const line of formatProjectContextGeneration(generated).split("\n")) console.log(`│  ${line}`);
+    console.log("");
+  }
+
   for (const agent of options.agents) {
     console.log(`◇ Setting up ${agent}...`);
     await streamSetupOutput(() => install({ agent, copy: false }));
@@ -1022,7 +1049,14 @@ try {
     if (!task.trim()) throw new Error('Usage: ctx debug -- "task"');
     await debug(task);
   } else if (command === "doctor") {
-    console.log(formatContextOSReady(inspectContextOSReady({ cwd: process.cwd() })));
+    if (args.includes("--fix")) {
+      const generated = generateProjectContext({ cwd: process.cwd(), force: args.includes("--force") });
+      console.log(formatProjectContextGeneration(generated));
+      console.log("");
+      console.log(formatContextOSReady(inspectContextOSReady({ cwd: process.cwd() })));
+    } else {
+      console.log(formatContextOSReady(inspectContextOSReady({ cwd: process.cwd() })));
+    }
   } else if (command === "refresh") {
     await refresh();
   } else if (command === "autowarm") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "description": "Inject task-relevant AGENTS.md rules into Codex through plugin hooks.",
   "author": {
     "name": "ContextOS"

package/plugins/ctx/lib/certification.js

@@ -68,6 +68,9 @@ export function formatContextOSReady(result) {
   if (next.length) {
     lines.push("", "Next:");
     for (const item of [...new Set(next)].slice(0, 5)) lines.push(`- ${item}`);
+    if (result.skills.score < 50 || result.workflows.score < 50) {
+      lines.push("- Run `ctx doctor --fix` to generate starter project skills and workflow.");
+    }
   }
 
   return lines.join("\n");

package/plugins/ctx/lib/project-context-generator.js

@@ -0,0 +1,394 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { clearSkillScanCache } from "./skill-discoverer.js";
+
+const STARTER_SKILL_LIMIT = 3;
+
+export function generateProjectContext({ cwd = process.cwd(), force = false } = {}) {
+  const root = findProjectRoot(cwd);
+  const profile = detectProjectProfile(root);
+  const skills = selectStarterSkills(profile).slice(0, STARTER_SKILL_LIMIT);
+  const created = [];
+  const skipped = [];
+
+  for (const skill of skills) {
+    const dir = path.join(root, ".codex", "skills", skill.id);
+    const skillPath = path.join(dir, "SKILL.md");
+    const yamlPath = path.join(dir, "skill.yaml");
+    fs.mkdirSync(dir, { recursive: true });
+    writeFile({ filePath: skillPath, content: renderSkillMarkdown(skill), force, created, skipped });
+    writeFile({ filePath: yamlPath, content: renderSkillYaml(skill), force, created, skipped });
+  }
+
+  const workflowPath = path.join(root, ".codex", "workflows", "primary.md");
+  fs.mkdirSync(path.dirname(workflowPath), { recursive: true });
+  writeFile({
+    filePath: workflowPath,
+    content: renderPrimaryWorkflow(profile, skills),
+    force,
+    created,
+    skipped
+  });
+  clearSkillScanCache();
+
+  return {
+    root,
+    profile,
+    skills: skills.map((skill) => skill.id),
+    created,
+    skipped
+  };
+}
+
+export function formatProjectContextGeneration(result) {
+  const lines = [
+    "Project context generated",
+    "",
+    `Root: ${result.root}`,
+    `Detected: ${result.profile.summary}`,
+    `Skills: ${result.skills.join(", ") || "(none)"}`,
+    "",
+    "Created:"
+  ];
+  if (result.created.length) {
+    for (const filePath of result.created) lines.push(`- ${path.relative(result.root, filePath)}`);
+  } else {
+    lines.push("- none");
+  }
+  if (result.skipped.length) {
+    lines.push("", "Skipped existing files:");
+    for (const filePath of result.skipped) lines.push(`- ${path.relative(result.root, filePath)}`);
+  }
+  lines.push("", "Next:");
+  lines.push("- Review generated skills/workflow and edit project-specific wording.");
+  lines.push("- Run: ctx doctor");
+  lines.push("- Run: ctx debug -- \"your task\"");
+  return lines.join("\n");
+}
+
+function detectProjectProfile(root) {
+  const packageFiles = findPackageJsonFiles(root);
+  const packages = packageFiles.map((filePath) => ({
+    filePath,
+    json: safeJson(filePath)
+  })).filter((item) => item.json);
+  const dependencies = new Set();
+  const scripts = new Set();
+  for (const item of packages) {
+    for (const section of ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"]) {
+      for (const name of Object.keys(item.json[section] || {})) dependencies.add(name);
+    }
+    for (const name of Object.keys(item.json.scripts || {})) scripts.add(name);
+  }
+  const files = new Set([
+    ...findExisting(root, [
+      "eas.json",
+      "app.json",
+      "app.config.js",
+      "app.config.ts",
+      "vercel.json",
+      "Dockerfile",
+      "docker-compose.yml",
+      "compose.yml",
+      "railway.json",
+      "render.yaml",
+      "firebase.json",
+      "prisma/schema.prisma",
+      "jest.config.js",
+      "jest.config.ts",
+      "playwright.config.ts",
+      ".github/workflows"
+    ])
+  ]);
+
+  const has = (name) => dependencies.has(name);
+  const hasFile = (name) => files.has(name);
+  const platforms = [];
+  if (has("expo") || has("react-native") || hasFile("eas.json")) platforms.push("expo-mobile");
+  if (has("next") || hasFile("vercel.json")) platforms.push("next-web");
+  if (has("@nestjs/core")) platforms.push("nestjs-backend");
+  if (has("express")) platforms.push("express-backend");
+  if (has("prisma") || has("@prisma/client") || hasFile("prisma/schema.prisma")) platforms.push("prisma");
+  if (has("redis") || has("ioredis")) platforms.push("redis");
+  if (hasFile("Dockerfile") || hasFile("docker-compose.yml")) platforms.push("docker");
+  if (hasFile(".github/workflows")) platforms.push("github-actions");
+  if (has("jest") || has("vitest") || hasFile("jest.config.js") || hasFile("playwright.config.ts")) platforms.push("testing");
+
+  const summary = platforms.length
+    ? platforms.join(", ")
+    : packages.length
+      ? `${packages.length} package.json file(s)`
+      : "generic repository";
+
+  return {
+    root,
+    packageFiles,
+    dependencies,
+    scripts,
+    files,
+    platforms,
+    summary
+  };
+}
+
+function selectStarterSkills(profile) {
+  const skills = [];
+  const hasPlatform = (platform) => profile.platforms.includes(platform);
+  if (hasPlatform("expo-mobile")) {
+    skills.push(skill({
+      id: "mobile-deployment",
+      name: "Mobile Deployment",
+      description: "Use for Expo, React Native, EAS build, QR/dev-client, Android/iOS preview, and mobile release tasks.",
+      prompts: ["expo", "react native", "eas", "mobile", "qr", "android", "ios", "preview", "production", "deploy"],
+      files: ["eas.json", "app.json", "app.config.ts", ".github/workflows/*"],
+      dependencies: ["expo", "react-native", "eas-cli"],
+      negatives: ["vercel", "serverless web deployment"]
+    }));
+  }
+  if (hasPlatform("next-web")) {
+    skills.push(skill({
+      id: "nextjs-web",
+      name: "Next.js Web",
+      description: "Use for Next.js routes, App Router, server/client component boundaries, Vercel deploys, and web UI tasks.",
+      prompts: ["next", "nextjs", "app router", "route", "page", "component", "vercel", "webapp"],
+      files: ["app/**", "pages/**", "next.config.*", "vercel.json"],
+      dependencies: ["next", "react"],
+      negatives: ["expo", "eas", "android", "ios"]
+    }));
+  }
+  if (hasPlatform("nestjs-backend") || hasPlatform("express-backend")) {
+    skills.push(skill({
+      id: "backend-api",
+      name: "Backend API",
+      description: "Use for backend services, API endpoints, validation, auth, controllers/routes, and service-layer changes.",
+      prompts: ["api", "backend", "service", "controller", "route", "auth", "validation", "fastify", "express", "nestjs"],
+      files: ["services/**", "src/**", "apps/**", "libs/**"],
+      dependencies: ["@nestjs/core", "express", "fastify", "zod", "class-validator"],
+      negatives: ["pure css", "static copy"]
+    }));
+  }
+  if (hasPlatform("prisma")) {
+    skills.push(skill({
+      id: "database-prisma",
+      name: "Database Prisma",
+      description: "Use for Prisma schema, migrations, query performance, repositories, and database-backed tests.",
+      prompts: ["prisma", "database", "migration", "query", "schema", "seed", "transaction"],
+      files: ["prisma/schema.prisma", "prisma/**", "src/**/repository*", "services/**/repository*"],
+      dependencies: ["prisma", "@prisma/client"],
+      negatives: ["frontend-only", "css-only"]
+    }));
+  }
+  if (hasPlatform("redis")) {
+    skills.push(skill({
+      id: "redis-cache",
+      name: "Redis Cache",
+      description: "Use for cache, queues, sessions, rate limits, Redis clients, and invalidation behavior.",
+      prompts: ["redis", "cache", "queue", "session", "rate limit", "invalidation"],
+      files: ["src/**/cache*", "services/**/cache*", "libs/**/cache*"],
+      dependencies: ["redis", "ioredis", "bullmq"],
+      negatives: ["static page"]
+    }));
+  }
+  if (hasPlatform("docker") || hasPlatform("github-actions")) {
+    skills.push(skill({
+      id: "ci-deployment",
+      name: "CI Deployment",
+      description: "Use for Docker, GitHub Actions, build logs, deploy failures, environment variables, and release pipelines.",
+      prompts: ["ci", "github actions", "docker", "deploy", "build failed", "pipeline", "environment", "secret"],
+      files: [".github/workflows/*", "Dockerfile", "docker-compose.yml", "railway.json", "render.yaml"],
+      dependencies: [],
+      negatives: ["local ui styling only"]
+    }));
+  }
+  if (hasPlatform("testing")) {
+    skills.push(skill({
+      id: "project-testing",
+      name: "Project Testing",
+      description: "Use for unit, integration, e2e, Jest, Vitest, Playwright, and focused verification tasks.",
+      prompts: ["test", "jest", "vitest", "playwright", "e2e", "coverage", "failing test"],
+      files: ["test/**", "__tests__/**", "*.spec.*", "*.test.*", "playwright.config.ts"],
+      dependencies: ["jest", "vitest", "@playwright/test"],
+      negatives: ["docs-only"]
+    }));
+  }
+  while (skills.length < STARTER_SKILL_LIMIT) {
+    const fallback = [
+      skill({
+        id: "project-implementation",
+        name: "Project Implementation",
+        description: "Use for normal feature work, bug fixes, and scoped implementation tasks in this repository.",
+        prompts: ["implement", "fix", "add", "update", "refactor", "bug"],
+        files: ["src/**", "apps/**", "services/**", "libs/**"],
+        dependencies: [],
+        negatives: ["release notes only"]
+      }),
+      skill({
+        id: "project-debugging",
+        name: "Project Debugging",
+        description: "Use for runtime errors, failed commands, logs, CI failures, and root-cause analysis.",
+        prompts: ["error", "failed", "timeout", "debug", "logs", "cannot", "fix"],
+        files: ["package.json", ".github/workflows/*", "src/**", "services/**"],
+        dependencies: [],
+        negatives: ["new feature with no failure"]
+      }),
+      skill({
+        id: "project-documentation",
+        name: "Project Documentation",
+        description: "Use for README, changelog, architecture notes, specs, and project documentation updates.",
+        prompts: ["readme", "docs", "documentation", "changelog", "spec", "guide"],
+        files: ["README.md", "docs/**", "CHANGELOG.md", "AGENTS.md"],
+        dependencies: [],
+        negatives: ["runtime bug"]
+      })
+    ].find((item) => !skills.some((existing) => existing.id === item.id));
+    if (!fallback) break;
+    skills.push(fallback);
+  }
+  return dedupeById(skills);
+}
+
+function skill({ id, name, description, prompts, files, dependencies, negatives }) {
+  return { id, name, description, prompts, files, dependencies, negatives };
+}
+
+function renderSkillMarkdown(skill) {
+  return [
+    "---",
+    `name: ${skill.id}`,
+    `description: ${skill.description}`,
+    "---",
+    "",
+    `# ${skill.name}`,
+    "",
+    skill.description,
+    "",
+    "Use this skill when the prompt and project evidence match the metadata in `skill.yaml`.",
+    "",
+    "Before editing:",
+    "",
+    "1. Read the relevant project rules.",
+    "2. Inspect the suggested files and nearby tests.",
+    "3. Keep the change scoped to the task.",
+    "4. Run the focused verification command before final response.",
+    ""
+  ].join("\n");
+}
+
+function renderSkillYaml(skill) {
+  return [
+    `id: ${skill.id}`,
+    `name: ${skill.name}`,
+    `description: ${skill.description}`,
+    "positive_triggers:",
+    "  prompts:",
+    ...skill.prompts.map((item) => `    - ${quoteYaml(item)}`),
+    "  files:",
+    ...skill.files.map((item) => `    - ${quoteYaml(item)}`),
+    "  dependencies:",
+    ...(skill.dependencies.length ? skill.dependencies.map((item) => `    - ${quoteYaml(item)}`) : ["    - package.json"]),
+    "evidence:",
+    "  files:",
+    ...skill.files.slice(0, 4).map((item) => `    - ${quoteYaml(item)}`),
+    "  dependencies:",
+    ...(skill.dependencies.length ? skill.dependencies.map((item) => `    - ${quoteYaml(item)}`) : ["    - package.json"]),
+    "negative_triggers:",
+    "  prompts:",
+    ...skill.negatives.map((item) => `    - ${quoteYaml(item)}`),
+    "workflow:",
+    "  - Inspect repo evidence before choosing an implementation path.",
+    "  - Read the suggested files and nearest tests.",
+    "  - Implement the smallest scoped change.",
+    "  - Run focused verification and summarize evidence.",
+    ""
+  ].join("\n");
+}
+
+function renderPrimaryWorkflow(profile, skills) {
+  return [
+    "# Primary Workflow",
+    "",
+    `Use this workflow for common tasks in this repository. Detected project context: ${profile.summary}.`,
+    "",
+    "planner -> tester -> code-reviewer -> docs-manager",
+    "",
+    "1. Read the task and relevant AGENTS.md rules.",
+    "2. Check ContextOS suggested files and skills.",
+    "3. Inspect project config before choosing a deployment/framework path.",
+    "4. Implement the smallest scoped change.",
+    "5. Run focused tests or the closest available verification.",
+    "6. Summarize files changed, verification, and any remaining risk.",
+    "",
+    "Starter skills:",
+    ...skills.map((skill) => `- ${skill.id}: ${skill.description}`),
+    ""
+  ].join("\n");
+}
+
+function writeFile({ filePath, content, force, created, skipped }) {
+  if (fs.existsSync(filePath) && !force) {
+    skipped.push(filePath);
+    return;
+  }
+  fs.writeFileSync(filePath, content, "utf8");
+  created.push(filePath);
+}
+
+function findPackageJsonFiles(root) {
+  const files = [];
+  walk(root, files, (filePath) => path.basename(filePath) === "package.json", 0);
+  return files.slice(0, 20);
+}
+
+function findExisting(root, relativePaths) {
+  return relativePaths.filter((relativePath) => fs.existsSync(path.join(root, relativePath)));
+}
+
+function walk(directory, files, predicate, depth) {
+  if (depth > 4) return;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".ctx") continue;
+    const filePath = path.join(directory, entry.name);
+    if (entry.isDirectory()) walk(filePath, files, predicate, depth + 1);
+    else if (entry.isFile() && predicate(filePath)) files.push(filePath);
+  }
+}
+
+function safeJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function findProjectRoot(cwd) {
+  let current = path.resolve(cwd);
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(cwd);
+    current = parent;
+  }
+}
+
+function dedupeById(skills) {
+  const seen = new Set();
+  const result = [];
+  for (const skill of skills) {
+    if (seen.has(skill.id)) continue;
+    seen.add(skill.id);
+    result.push(skill);
+  }
+  return result;
+}
+
+function quoteYaml(value) {
+  return JSON.stringify(String(value));
+}

package/plugins/ctx/lib/setup-wizard.js

@@ -19,7 +19,8 @@ export function parseSetupArgs(args = []) {
     yes,
     quiet: args.includes("--quiet"),
     syncRules: !args.includes("--no-rules"),
-    syncSkills: !args.includes("--no-skills")
+    syncSkills: !args.includes("--no-skills"),
+    generateProjectContext: args.includes("--generate-project-context")
   };
 }
 
@@ -42,6 +43,7 @@ export function setupSummaryLines({
   agents = DEFAULT_AGENTS,
   syncRules = true,
   syncSkills = true,
+  generateProjectContext = false,
   promptSections = null,
   promptLimits = null
 } = {}) {
@@ -50,7 +52,8 @@ export function setupSummaryLines({
     `Agents: ${agents.join(", ") || "(none)"}`,
     `Prompt context injection: always enabled`,
     `Ruler rule/MCP sync: ${syncRules ? "enabled" : "skipped"}`,
-    `skillshare skill sync: ${syncSkills ? "enabled" : "skipped"}`
+    `skillshare skill sync: ${syncSkills ? "enabled" : "skipped"}`,
+    `Project context generation: ${generateProjectContext ? "enabled" : "skipped"}`
   ];
   if (promptSections !== null) lines.push(`Prompt sections shown: ${promptSections}`);
   if (promptLimits !== null) lines.push(`Prompt suggest limits: ${promptLimits}`);

package/plugins/ctx/lib/skill-discoverer.js

@@ -20,6 +20,10 @@ const DEFAULT_ROUTER_THRESHOLD = 0.35;
 
 const scanCache = new Map();
 
+export function clearSkillScanCache() {
+  scanCache.clear();
+}
+
 export function skillSearchRoots({ cwd = process.cwd(), home = os.homedir() } = {}) {
   return [
     path.join(cwd, ".codex", "skills"),