@codemcp/ade 0.5.0 → 0.6.1

package/packages/core/src/catalog/facets/process.ts

@@ -11,6 +11,42 @@ export const processFacet: Facet = {
       label: "CodeMCP Workflows",
       description:
         "Use @codemcp/workflows to drive agent tasks with structured engineering workflows",
+      recipe: [
+        {
+          writer: "workflows",
+          config: {
+            package: "@codemcp/workflows-server@latest",
+            ref: "workflows",
+            // env: {
+            //   VIBE_WORKFLOW_DOMAINS: "skilled"
+            // },
+            allowedTools: [
+              "whats_next",
+              "conduct_review",
+              "list_workflows",
+              "get_tool_info"
+            ]
+          }
+        },
+        {
+          writer: "instruction",
+          config: {
+            text: [
+              "You are an AI assistant that helps users develop software features using the workflows server.",
+              "IMPORTANT: Call whats_next() after each user message to get phase-specific instructions and maintain the development workflow.",
+              'Each tool call returns a JSON response with an "instructions" field. Follow these instructions immediately after you receive them.',
+              "Use the development plan which you will retrieve via whats_next() to record important insights and decisions as per the structure of the plan.",
+              "Do not use your own task management tools."
+            ].join("\n")
+          }
+        }
+      ]
+    },
+    {
+      id: "codemcp-workflows-skilled",
+      label: "CodeMCP Workflows (Skilled)",
+      description:
+        "Use @codemcp/workflows with domain-specific skills for starting projects, architecture, design, coding and testing",
       recipe: [
         {
           writer: "workflows",
@@ -28,6 +64,144 @@ export const processFacet: Facet = {
             ]
           }
         },
+        {
+          writer: "skills",
+          config: {
+            skills: [
+              {
+                name: "starting-project",
+                description:
+                  "Conventions and tooling to expect when starting a new project",
+                body: [
+                  "# Starting a New Project",
+                  "",
+                  "## Project Setup",
+                  "- Check for an existing README, architecture doc, or requirements doc before doing anything else",
+                  "- Prefer monorepo tooling (pnpm workspaces, nx, turborepo) for multi-package projects",
+                  "- Use a `.editorconfig` and a linter/formatter config (ESLint + Prettier, Biome, etc.) from day one",
+                  "- Store secrets in environment variables — never commit them; provide a `.env.example`",
+                  "",
+                  "## Conventions",
+                  "- Follow the language/framework conventions already present in the project",
+                  "- If no conventions exist yet, propose them and document them before writing code",
+                  "- Prefer explicit over implicit: clear naming, documented interfaces, typed APIs",
+                  "",
+                  "## First Steps Checklist",
+                  "1. Read all existing documentation",
+                  "2. Understand the intended architecture (ask if unclear)",
+                  "3. Confirm the tech stack and tooling",
+                  "4. Set up the development environment and verify it works",
+                  "5. Identify and create the initial project skeleton if needed"
+                ].join("\n")
+              },
+              {
+                name: "architecture",
+                description:
+                  "Architectural conventions and decision-making guidelines",
+                body: [
+                  "# Architecture",
+                  "",
+                  "## Principles",
+                  "- Prefer simple, proven architectural patterns over novel ones",
+                  "- Separate concerns: domain logic, infrastructure, and presentation must not be mixed",
+                  "- Design for testability: business logic must be testable without I/O",
+                  "- Apply the dependency rule: inner layers must not depend on outer layers",
+                  "",
+                  "## Decision Making",
+                  "- Document significant architecture decisions as ADRs (Architecture Decision Records)",
+                  "- Evaluate alternatives before committing to an approach",
+                  "- Consider non-functional requirements: scalability, maintainability, operability",
+                  "",
+                  "## Boundaries",
+                  "- Define clear module/package boundaries with explicit public APIs",
+                  "- Avoid circular dependencies between modules",
+                  "- Keep infrastructure concerns (DB, HTTP, queues) behind interfaces"
+                ].join("\n")
+              },
+              {
+                name: "application-design",
+                description:
+                  "Design patterns for authentication, routing, error handling, and forms",
+                body: [
+                  "# Application Design",
+                  "",
+                  "## Authentication & Authorization",
+                  "- Authenticate at the edge (middleware/guard) — never inside business logic",
+                  "- Use short-lived tokens (JWT or session) with refresh strategies",
+                  "- Apply the principle of least privilege for all role/permission checks",
+                  "",
+                  "## Routing",
+                  "- Use declarative, file-based or configuration-driven routing where available",
+                  "- Protect routes with auth guards rather than ad-hoc checks",
+                  "- Keep route handlers thin — delegate to services immediately",
+                  "",
+                  "## Error Handling",
+                  "- Distinguish between operational errors (expected) and programmer errors (bugs)",
+                  "- Return structured error responses with consistent shape (code, message, details)",
+                  "- Log errors with context (request id, user id, stack trace) for observability",
+                  "- Never expose internal stack traces or sensitive data to clients",
+                  "",
+                  "## Forms & Validation",
+                  "- Validate input at the boundary (schema-first with Zod, Yup, Joi, etc.)",
+                  "- Show inline, field-level validation errors in the UI",
+                  "- Prevent double-submission by disabling submit controls during in-flight requests"
+                ].join("\n")
+              },
+              {
+                name: "coding",
+                description:
+                  "Code style, patterns, and implementation conventions",
+                body: [
+                  "# Coding",
+                  "",
+                  "## Style",
+                  "- Follow the project's existing code style and linter rules unconditionally",
+                  "- Write self-documenting code: prefer expressive names over comments that explain *what*",
+                  "- Use comments only to explain *why* when the reason is non-obvious",
+                  "",
+                  "## Patterns",
+                  "- Prefer pure functions and immutable data structures",
+                  "- Keep functions small and focused on a single responsibility",
+                  "- Avoid deep nesting — use early returns, guard clauses, and extraction",
+                  "- Prefer composition over inheritance",
+                  "",
+                  "## Quality Gates",
+                  "- Run the linter and type-checker before declaring a task done",
+                  "- Fix all warnings, not just errors",
+                  "- Ensure the build passes end-to-end before moving on"
+                ].join("\n")
+              },
+              {
+                name: "testing",
+                description:
+                  "Testing strategy, patterns, and execution conventions",
+                body: [
+                  "# Testing",
+                  "",
+                  "## Strategy",
+                  "- Follow the test pyramid: many unit tests, fewer integration tests, fewest E2E tests",
+                  "- Write tests alongside the code — not as an afterthought",
+                  "- Each test must be independent: no shared mutable state between tests",
+                  "",
+                  "## Unit Tests",
+                  "- Test one unit of behavior per test case",
+                  "- Use descriptive test names that read as specifications",
+                  "- Mock only direct dependencies, not transitive ones",
+                  "",
+                  "## Integration & E2E Tests",
+                  "- Test real interactions between components (DB, HTTP, queue) in integration tests",
+                  "- Use realistic data and environments — avoid fake setups that hide real issues",
+                  "- Clean up test data after each test to keep tests isolated",
+                  "",
+                  "## Execution",
+                  "- All tests must pass before committing",
+                  "- Run the full test suite after refactoring, even if only small changes were made",
+                  "- Treat a flaky test as a bug — fix or delete it, never ignore it"
+                ].join("\n")
+              }
+            ]
+          }
+        },
         {
           writer: "instruction",
           config: {

package/packages/core/src/catalog/index.ts

@@ -1,4 +1,4 @@
-import type { Catalog, Facet, Option } from "../types.js";
+import type { Catalog, Facet, Option, AdeExtensions } from "../types.js";
 import { processFacet } from "./facets/process.js";
 import { architectureFacet } from "./facets/architecture.js";
 import { practicesFacet } from "./facets/practices.js";
@@ -91,3 +91,40 @@ export function getVisibleOptions(
     return option.available(deps);
   });
 }
+
+/**
+ * Merges extension contributions into a catalog, returning a new catalog
+ * without mutating the original.
+ *
+ * - `extensions.facetContributions`: appends new options to existing facets
+ *   (silently ignores contributions for unknown facet ids)
+ * - `extensions.facets`: appends entirely new facets
+ */
+export function mergeExtensions(
+  catalog: Catalog,
+  extensions: AdeExtensions
+): Catalog {
+  // Deep-clone the facets array (shallow-clone each facet with a new options array)
+  let facets: Facet[] = catalog.facets.map((f) => ({
+    ...f,
+    options: [...f.options]
+  }));
+
+  // Append contributed options to existing facets
+  for (const [facetId, newOptions] of Object.entries(
+    extensions.facetContributions ?? {}
+  )) {
+    const facet = facets.find((f) => f.id === facetId);
+    if (facet) {
+      facet.options = [...facet.options, ...newOptions];
+    }
+    // Unknown facet ids are silently ignored
+  }
+
+  // Append entirely new facets
+  if (extensions.facets && extensions.facets.length > 0) {
+    facets = [...facets, ...extensions.facets];
+  }
+
+  return { facets };
+}

package/packages/core/src/extensions.spec.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect } from "vitest";
+import type { AdeExtensions } from "./types.js";
+import { AdeExtensionsSchema } from "./types.js";
+import { mergeExtensions } from "./catalog/index.js";
+import { getDefaultCatalog, getFacet, getOption } from "./catalog/index.js";
+
+// ─── AdeExtensionsSchema (Zod validation) ──────────────────────────────────
+
+describe("AdeExtensionsSchema", () => {
+  it("accepts an empty object (all fields optional)", () => {
+    const result = AdeExtensionsSchema.safeParse({});
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a valid facetContributions map", () => {
+    const ext: AdeExtensions = {
+      facetContributions: {
+        architecture: [
+          {
+            id: "sap",
+            label: "SAP",
+            description: "SAP BTP ABAP development",
+            recipe: [{ writer: "skills", config: { skills: [] } }]
+          }
+        ]
+      }
+    };
+    const result = AdeExtensionsSchema.safeParse(ext);
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a valid facets array (new facets)", () => {
+    const ext: AdeExtensions = {
+      facets: [
+        {
+          id: "custom-facet",
+          label: "Custom",
+          description: "A custom facet",
+          required: false,
+          options: []
+        }
+      ]
+    };
+    const result = AdeExtensionsSchema.safeParse(ext);
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts harnessWriters", () => {
+    const ext: AdeExtensions = {
+      harnessWriters: [
+        {
+          id: "my-harness",
+          label: "My Harness",
+          description: "Custom harness",
+          install: async () => {}
+        }
+      ]
+    };
+    const result = AdeExtensionsSchema.safeParse(ext);
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects an invalid facetContributions value (wrong type)", () => {
+    const result = AdeExtensionsSchema.safeParse({
+      facetContributions: "not-an-object"
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects a facetContributions option missing required fields", () => {
+    const result = AdeExtensionsSchema.safeParse({
+      facetContributions: {
+        architecture: [
+          { id: "sap" } // missing label, description, recipe
+        ]
+      }
+    });
+    expect(result.success).toBe(false);
+  });
+});
+
+// ─── mergeExtensions ────────────────────────────────────────────────────────
+
+describe("mergeExtensions", () => {
+  it("returns the original catalog unchanged when extensions is empty", () => {
+    const original = getDefaultCatalog();
+    const merged = mergeExtensions(original, {});
+    expect(merged.facets).toHaveLength(original.facets.length);
+    expect(merged.facets.map((f) => f.id)).toEqual(
+      original.facets.map((f) => f.id)
+    );
+  });
+
+  it("adds new options to an existing facet via facetContributions", () => {
+    const catalog = getDefaultCatalog();
+    const sapOption = {
+      id: "sap",
+      label: "SAP BTP / ABAP",
+      description: "SAP BTP ABAP development",
+      recipe: [{ writer: "skills" as const, config: { skills: [] } }]
+    };
+
+    const merged = mergeExtensions(catalog, {
+      facetContributions: { architecture: [sapOption] }
+    });
+
+    const arch = getFacet(merged, "architecture")!;
+    expect(arch).toBeDefined();
+    const sap = getOption(arch, "sap");
+    expect(sap).toBeDefined();
+    expect(sap!.label).toBe("SAP BTP / ABAP");
+  });
+
+  it("does not mutate the original catalog", () => {
+    const catalog = getDefaultCatalog();
+    const originalArchOptionCount = getFacet(catalog, "architecture")!.options
+      .length;
+
+    mergeExtensions(catalog, {
+      facetContributions: {
+        architecture: [
+          {
+            id: "sap",
+            label: "SAP",
+            description: "SAP",
+            recipe: [{ writer: "skills" as const, config: { skills: [] } }]
+          }
+        ]
+      }
+    });
+
+    expect(getFacet(catalog, "architecture")!.options).toHaveLength(
+      originalArchOptionCount
+    );
+  });
+
+  it("appends entirely new facets from extensions.facets", () => {
+    const catalog = getDefaultCatalog();
+    const newFacet = {
+      id: "sap-specific",
+      label: "SAP Specific",
+      description: "SAP-specific choices",
+      required: false,
+      options: []
+    };
+
+    const merged = mergeExtensions(catalog, { facets: [newFacet] });
+    expect(merged.facets.map((f) => f.id)).toContain("sap-specific");
+    expect(merged.facets).toHaveLength(catalog.facets.length + 1);
+  });
+
+  it("ignores facetContributions for unknown facet ids (no crash)", () => {
+    const catalog = getDefaultCatalog();
+    const merged = mergeExtensions(catalog, {
+      facetContributions: {
+        "totally-unknown-facet": [
+          {
+            id: "x",
+            label: "X",
+            description: "X",
+            recipe: [{ writer: "skills" as const, config: { skills: [] } }]
+          }
+        ]
+      }
+    });
+    // Should not throw; catalog unchanged
+    expect(merged.facets).toHaveLength(catalog.facets.length);
+  });
+});

package/packages/core/src/index.ts

@@ -45,8 +45,10 @@ export {
   getFacet,
   getOption,
   sortFacets,
-  getVisibleOptions
+  getVisibleOptions,
+  mergeExtensions
 } from "./catalog/index.js";
+export { type AdeExtensions, AdeExtensionsSchema } from "./types.js";
 export { skillsWriter } from "./writers/skills.js";
 export { knowledgeWriter } from "./writers/knowledge.js";
 export { permissionPolicyWriter } from "./writers/permission-policy.js";

package/packages/core/src/types.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 // --- Catalog types ---
 
 export interface Catalog {
@@ -157,3 +159,72 @@ export interface WriterRegistry {
   provisions: Map<string, ProvisionWriterDef>;
   agents: Map<string, AgentWriterDef>;
 }
+
+// --- Extension types ---
+
+/**
+ * Runtime validation helpers for extension file loading.
+ *
+ * We use z.custom<T>() for Option, Facet, HarnessWriter and ProvisionWriterDef
+ * because their TypeScript interfaces contain function types that Zod cannot
+ * faithfully represent without losing the concrete signature. z.custom<T>
+ * gives us the correct TS type while still letting us write a runtime check.
+ */
+const OptionSchema = z.custom<Option>(
+  (val) =>
+    typeof val === "object" &&
+    val !== null &&
+    typeof (val as Record<string, unknown>).id === "string" &&
+    typeof (val as Record<string, unknown>).label === "string" &&
+    typeof (val as Record<string, unknown>).description === "string" &&
+    Array.isArray((val as Record<string, unknown>).recipe),
+  { message: "Option must have id, label, description and recipe fields" }
+);
+
+const FacetSchema = z.custom<Facet>(
+  (val) =>
+    typeof val === "object" &&
+    val !== null &&
+    typeof (val as Record<string, unknown>).id === "string" &&
+    typeof (val as Record<string, unknown>).label === "string" &&
+    typeof (val as Record<string, unknown>).description === "string" &&
+    typeof (val as Record<string, unknown>).required === "boolean" &&
+    Array.isArray((val as Record<string, unknown>).options),
+  { message: "Facet must have id, label, description, required and options" }
+);
+
+const HarnessWriterSchema = z.custom<
+  AgentWriterDef & { label: string; description: string }
+>(
+  (val) =>
+    typeof val === "object" &&
+    val !== null &&
+    typeof (val as Record<string, unknown>).id === "string" &&
+    typeof (val as Record<string, unknown>).label === "string" &&
+    typeof (val as Record<string, unknown>).description === "string" &&
+    typeof (val as Record<string, unknown>).install === "function",
+  { message: "HarnessWriter must have id, label, description and install()" }
+);
+
+const ProvisionWriterDefSchema = z.custom<ProvisionWriterDef>(
+  (val) =>
+    typeof val === "object" &&
+    val !== null &&
+    typeof (val as Record<string, unknown>).id === "string" &&
+    typeof (val as Record<string, unknown>).write === "function",
+  { message: "ProvisionWriterDef must have id and write()" }
+);
+
+export const AdeExtensionsSchema = z.object({
+  /** Add new options to existing facets, keyed by facet id */
+  facetContributions: z.record(z.string(), z.array(OptionSchema)).optional(),
+  /** Add entirely new facets */
+  facets: z.array(FacetSchema).optional(),
+  /** Add new provision writers */
+  provisionWriters: z.array(ProvisionWriterDefSchema).optional(),
+  /** Add new harness writers */
+  harnessWriters: z.array(HarnessWriterSchema).optional()
+});
+
+/** The shape of a consumer's `ade.extensions.mjs` default export. */
+export type AdeExtensions = z.infer<typeof AdeExtensionsSchema>;

package/packages/harnesses/package.json

@@ -40,5 +40,5 @@
     "typescript": "catalog:",
     "vitest": "catalog:"
   },
-  "version": "0.5.0"
+  "version": "0.6.1"
 }

package/packages/harnesses/src/index.spec.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from "vitest";
-import { allHarnessWriters, getHarnessWriter, getHarnessIds } from "./index.js";
+import {
+  allHarnessWriters,
+  getHarnessWriter,
+  getHarnessIds,
+  buildHarnessWriters
+} from "./index.js";
+import type { HarnessWriter } from "./types.js";
 
 describe("harness registry", () => {
   it("exports all harness writers", () => {
@@ -43,3 +49,44 @@ describe("harness registry", () => {
     }
   });
 });
+
+describe("buildHarnessWriters", () => {
+  it("returns all built-in writers when no extensions provided", () => {
+    const writers = buildHarnessWriters({});
+    expect(writers).toHaveLength(allHarnessWriters.length);
+    expect(writers.map((w) => w.id)).toEqual(
+      allHarnessWriters.map((w) => w.id)
+    );
+  });
+
+  it("appends extension harness writers after built-ins", () => {
+    const customWriter: HarnessWriter = {
+      id: "sap-copilot",
+      label: "SAP Copilot",
+      description: "SAP internal Copilot harness",
+      install: async () => {}
+    };
+
+    const writers = buildHarnessWriters({ harnessWriters: [customWriter] });
+    expect(writers).toHaveLength(allHarnessWriters.length + 1);
+    expect(writers.map((w) => w.id)).toContain("sap-copilot");
+    // built-ins come first
+    expect(writers[0].id).toBe("universal");
+    expect(writers[writers.length - 1].id).toBe("sap-copilot");
+  });
+
+  it("does not mutate allHarnessWriters", () => {
+    const originalLength = allHarnessWriters.length;
+    buildHarnessWriters({
+      harnessWriters: [
+        {
+          id: "ephemeral",
+          label: "Ephemeral",
+          description: "Should not persist",
+          install: async () => {}
+        }
+      ]
+    });
+    expect(allHarnessWriters).toHaveLength(originalLength);
+  });
+});

package/packages/harnesses/src/index.ts

@@ -45,3 +45,13 @@ export function getHarnessWriter(id: string): HarnessWriter | undefined {
 export function getHarnessIds(): string[] {
   return allHarnessWriters.map((w) => w.id);
 }
+
+/**
+ * Returns the full list of harness writers: built-ins first, then any
+ * additional writers contributed via extensions. Does not mutate allHarnessWriters.
+ */
+export function buildHarnessWriters(extensions: {
+  harnessWriters?: HarnessWriter[];
+}): HarnessWriter[] {
+  return [...allHarnessWriters, ...(extensions.harnessWriters ?? [])];
+}

package/pnpm-workspace.yaml

@@ -17,3 +17,5 @@ catalog:
   rimraf: "^6.1.3"
   tsx: "^4.19.0"
   tsup: "^8.3.0"
+  # Runtime
+  zod: "4.3.6"