Add TypeScript project topology skill

README.md

@@ -24,10 +24,10 @@ running package installs.
 ## Workflow Skills
 
 DevNexus TypeScript ships baseline workflow skills for TypeScript diagnosis,
-bounded refactoring, test hygiene, API boundary review, and dry-run codemod
-planning. The plugin config declares them as `projected_skill` capabilities, and
-the package also exports DevNexus skill definitions for projects that
-materialize package-owned skills:
+bounded refactoring, project topology, test hygiene, API boundary review, and
+dry-run codemod planning. The plugin config declares them as `projected_skill`
+capabilities, and the package also exports DevNexus skill definitions for
+projects that materialize package-owned skills:
 
 ```ts
 import {

skills/typescript-project-topology/REFERENCES.md

@@ -0,0 +1,8 @@
+# References
+
+- TypeScript `rootDir`: https://www.typescriptlang.org/tsconfig/rootDir.html
+- TypeScript `outDir`: https://www.typescriptlang.org/tsconfig/outDir.html
+- TypeScript `include`: https://www.typescriptlang.org/tsconfig/include.html
+- Vitest test `include`: https://main.vitest.dev/config/include
+- Vitest coverage config: https://vitest.dev/config/coverage.html
+- npm `package.json` `files`: https://docs.npmjs.com/cli/v7/configuring-npm/package-json#files

skills/typescript-project-topology/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: typescript-project-topology
+description: TypeScript project topology workflow for separating source, tests, build output, package files, and domain folders without changing behavior. Use when Codex must audit, design, or adjust TypeScript repository layout, especially src/test structure, package publish boundaries, or module grouping.
+---
+
+# TypeScript Project Topology
+
+Use this skill when a TypeScript or JavaScript project layout is being audited,
+designed, or changed.
+
+1. Classify the project first: library, CLI, app, monorepo package, or test-only
+   fixture. Let package scripts, `exports`, `main`, `types`, and `files` define
+   the published surface.
+2. Keep buildable implementation under a clear compiler root such as `src`, and
+   keep generated output under an ignored output directory such as `dist`.
+3. For published packages and CLIs, prefer a central `test` tree that mirrors
+   source domains. This keeps test files out of emitted declarations, package
+   exports, and npm publish artifacts.
+4. Colocated `*.test.ts` files are acceptable for small apps or local-only
+   packages when `tsconfig`, bundler, coverage, and package publish config all
+   exclude them reliably.
+5. Avoid a flat source root once the package has durable domains. Group modules
+   by ownership, for example `cli`, `git`, `project`, `providers`, `automation`,
+   `publication`, `mcp`, and `shared`.
+6. Mirror source domains in tests when using a central `test` tree. Prefer
+   `test/<domain>/...` over one flat test directory for large packages.
+7. Move topology in bounded mechanical steps. Preserve public imports and package
+   entrypoints, update internal imports, then run focused tests before full
+   package checks.
+8. Do not move files solely for cosmetic symmetry. Use topology changes to
+   improve ownership, packaging safety, import locality, or test discoverability.

skills/typescript-project-topology/dev-nexus.skill.json

@@ -0,0 +1,14 @@
+{
+  "id": "typescript-project-topology",
+  "name": "typescript-project-topology",
+  "description": "TypeScript project topology workflow for separating source, tests, build output, package files, and domain folders without changing behavior. Use when Codex must audit, design, or adjust TypeScript repository layout, especially src/test structure, package publish boundaries, or module grouping.",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "source": {
+    "type": "local",
+    "uri": "@evref-bl/dev-nexus-typescript/skills/typescript-project-topology"
+  },
+  "supportedAgents": ["codex", "claude"],
+  "materialization": "copy",
+  "sourceControl": "support"
+}

src/devNexusTypeScriptPlugin.test.ts

@@ -111,6 +111,7 @@ describe("DevNexus TypeScript plugin", () => {
       "node-modules",
       "skill-typescript-diagnose",
       "skill-typescript-refactor",
+      "skill-typescript-project-topology",
       "skill-typescript-test-hygiene",
       "skill-typescript-api-boundaries",
       "skill-typescript-codemod-planning",
@@ -192,6 +193,13 @@ describe("DevNexus TypeScript plugin", () => {
         skillId: "typescript-refactor",
         targetAgents: ["codex", "claude"],
       },
+      {
+        kind: "projected_skill",
+        id: "skill-typescript-project-topology",
+        description: "Project the TypeScript project directory topology workflow skill.",
+        skillId: "typescript-project-topology",
+        targetAgents: ["codex", "claude"],
+      },
       {
         kind: "projected_skill",
         id: "skill-typescript-test-hygiene",
@@ -227,6 +235,7 @@ describe("DevNexus TypeScript plugin", () => {
     ).toEqual([
       "typescript-diagnose",
       "typescript-refactor",
+      "typescript-project-topology",
       "typescript-test-hygiene",
       "typescript-api-boundaries",
       "typescript-codemod-planning",
@@ -377,7 +386,7 @@ describe("DevNexus TypeScript plugin", () => {
         pluginId: "dev-nexus-typescript",
         pluginName: "DevNexus TypeScript",
         version: devNexusTypeScriptPluginVersion,
-        capabilityCount: 11,
+        capabilityCount: 12,
       },
     ]);
     expect(projected[0]!.capabilities.map((capability) => capability.kind)).toEqual([
@@ -387,6 +396,7 @@ describe("DevNexus TypeScript plugin", () => {
       "projected_skill",
       "projected_skill",
       "projected_skill",
+      "projected_skill",
       "mcp_server",
       "mcp_server",
       "mcp_server",
@@ -405,6 +415,7 @@ describe("DevNexus TypeScript plugin", () => {
       "node-modules",
       "skill-typescript-diagnose",
       "skill-typescript-refactor",
+      "skill-typescript-project-topology",
       "skill-typescript-test-hygiene",
       "skill-typescript-api-boundaries",
       "skill-typescript-codemod-planning",

src/typeScriptWorkflowSkills.test.ts

@@ -9,6 +9,7 @@ describe("DevNexus TypeScript workflow skills", () => {
     expect(devNexusTypeScriptWorkflowSkillIds).toEqual([
       "typescript-diagnose",
       "typescript-refactor",
+      "typescript-project-topology",
       "typescript-test-hygiene",
       "typescript-api-boundaries",
       "typescript-codemod-planning",
@@ -19,6 +20,7 @@ describe("DevNexus TypeScript workflow skills", () => {
     expect(definitions.map((definition) => definition.manifest.id)).toEqual([
       "typescript-diagnose",
       "typescript-refactor",
+      "typescript-project-topology",
       "typescript-test-hygiene",
       "typescript-api-boundaries",
       "typescript-codemod-planning",
@@ -47,5 +49,15 @@ describe("DevNexus TypeScript workflow skills", () => {
         `"id": "${definition.manifest.id}"`,
       );
     }
+    expect(
+      definitions.find(
+        (definition) => definition.manifest.id === "typescript-project-topology",
+      )!.files["SKILL.md"],
+    ).toContain("prefer a central `test` tree that mirrors");
+    expect(
+      definitions.find(
+        (definition) => definition.manifest.id === "typescript-project-topology",
+      )!.files["REFERENCES.md"],
+    ).toContain("https://www.typescriptlang.org/tsconfig/rootDir.html");
   });
 });

src/typeScriptWorkflowSkills.ts

@@ -10,6 +10,7 @@ import type {
 export const devNexusTypeScriptWorkflowSkillIds = [
   "typescript-diagnose",
   "typescript-refactor",
+  "typescript-project-topology",
   "typescript-test-hygiene",
   "typescript-api-boundaries",
   "typescript-codemod-planning",
@@ -26,6 +27,8 @@ const projectedSkillDescriptions: Record<
     "Project the TypeScript compiler/runtime diagnosis workflow skill.",
   "typescript-refactor":
     "Project the bounded TypeScript refactoring workflow skill.",
+  "typescript-project-topology":
+    "Project the TypeScript project directory topology workflow skill.",
   "typescript-test-hygiene": "Project the TypeScript test hygiene workflow skill.",
   "typescript-api-boundaries":
     "Project the TypeScript API boundary review workflow skill.",