@codemcp/ade-core 0.0.2

package/src/catalog/facets/practices.ts

@@ -0,0 +1,173 @@
+import type { Facet } from "../../types.js";
+
+export const practicesFacet: Facet = {
+  id: "practices",
+  label: "Practices",
+  description:
+    "Composable development practices — mix and match regardless of stack",
+  required: false,
+  multiSelect: true,
+  options: [
+    {
+      id: "conventional-commits",
+      label: "Conventional Commits",
+      description:
+        "Structured commit messages following the Conventional Commits specification",
+      recipe: [
+        {
+          writer: "skills",
+          config: {
+            skills: [
+              {
+                name: "conventional-commits",
+                description:
+                  "Conventional Commits specification for structured commit messages",
+                body: [
+                  "# Conventional Commits",
+                  "",
+                  "## Format",
+                  "```",
+                  "<type>[optional scope]: <description>",
+                  "",
+                  "[optional body]",
+                  "",
+                  "[optional footer(s)]",
+                  "```",
+                  "",
+                  "## Types",
+                  "- `feat`: A new feature (correlates with MINOR in SemVer)",
+                  "- `fix`: A bug fix (correlates with PATCH in SemVer)",
+                  "- `docs`: Documentation only changes",
+                  "- `style`: Changes that do not affect the meaning of the code",
+                  "- `refactor`: A code change that neither fixes a bug nor adds a feature",
+                  "- `perf`: A code change that improves performance",
+                  "- `test`: Adding missing tests or correcting existing tests",
+                  "- `chore`: Changes to the build process or auxiliary tools",
+                  "",
+                  "## Rules",
+                  "- Subject line must not exceed 72 characters",
+                  '- Use imperative mood in the subject line ("add" not "added")',
+                  "- Do not end the subject line with a period",
+                  "- Separate subject from body with a blank line",
+                  "- Use the body to explain what and why, not how",
+                  "- `BREAKING CHANGE:` footer or `!` after type/scope for breaking changes"
+                ].join("\n")
+              }
+            ]
+          }
+        }
+      ],
+      docsets: [
+        {
+          id: "conventional-commits-spec",
+          label: "Conventional Commits Spec",
+          origin:
+            "https://github.com/conventional-commits/conventionalcommits.org.git",
+          description: "The Conventional Commits specification"
+        }
+      ]
+    },
+    {
+      id: "tdd-london",
+      label: "TDD (London Style)",
+      description:
+        "Test-Driven Development using the London school (mockist) approach",
+      recipe: [
+        {
+          writer: "skills",
+          config: {
+            skills: [
+              {
+                name: "tdd-london",
+                description:
+                  "London-school TDD methodology with outside-in design",
+                body: [
+                  "# TDD — London Style (Mockist)",
+                  "",
+                  "## Core Cycle",
+                  "1. **Red** — Write a failing test for the next behavior",
+                  "2. **Green** — Write the minimum code to make the test pass",
+                  "3. **Refactor** — Improve the code while keeping tests green",
+                  "",
+                  "## London School Principles",
+                  "- Work **outside-in**: start from the outermost layer (API / UI) and drive inward",
+                  "- **Mock collaborators**: each unit test isolates the unit under test by mocking its direct dependencies",
+                  "- Discover interfaces through tests — let the test define the collaborator contract before implementing it",
+                  "- Prefer **role-based interfaces** over concrete classes",
+                  "",
+                  "## Test Structure",
+                  "- **Arrange**: Set up mocks and the unit under test",
+                  "- **Act**: Call the method being tested",
+                  "- **Assert**: Verify the unit's output and interactions with mocks",
+                  "",
+                  "## Guidelines",
+                  "- One logical assertion per test",
+                  '- Test names describe behavior, not methods (e.g. "notifies user when order is placed")',
+                  "- Only mock types you own — wrap third-party APIs in adapters and mock those",
+                  "- Use the test doubles: stubs for queries, mocks for commands",
+                  "- Do not test implementation details — test observable behavior",
+                  "- Refactor step is mandatory, not optional"
+                ].join("\n")
+              }
+            ]
+          }
+        }
+      ]
+    },
+    {
+      id: "adr-nygard",
+      label: "ADR (Nygard)",
+      description:
+        "Architecture Decision Records following Michael Nygard's template",
+      recipe: [
+        {
+          writer: "skills",
+          config: {
+            skills: [
+              {
+                name: "adr-nygard",
+                description:
+                  "Architecture Decision Records following Nygard's lightweight template",
+                body: [
+                  "# Architecture Decision Records (Nygard)",
+                  "",
+                  "## When to Write an ADR",
+                  "- When making a significant architectural decision",
+                  "- When choosing between multiple viable options",
+                  "- When the decision will be hard to reverse",
+                  '- When future developers will ask "why did we do this?"',
+                  "",
+                  "## Template",
+                  "Store ADRs in `docs/adr/` as numbered markdown files: `NNNN-title-with-dashes.md`",
+                  "",
+                  "```markdown",
+                  "# N. Title",
+                  "",
+                  "## Status",
+                  "Proposed | Accepted | Deprecated | Superseded by [ADR-NNNN]",
+                  "",
+                  "## Context",
+                  "What is the issue that we're seeing that is motivating this decision or change?",
+                  "",
+                  "## Decision",
+                  "What is the change that we're proposing and/or doing?",
+                  "",
+                  "## Consequences",
+                  "What becomes easier or more difficult to do because of this change?",
+                  "```",
+                  "",
+                  "## Rules",
+                  "- ADRs are immutable once accepted — supersede, don't edit",
+                  "- Keep context focused on forces at play at the time of the decision",
+                  "- Write consequences as both positive and negative impacts",
+                  "- Number sequentially, never reuse numbers",
+                  '- Title should be a short noun phrase (e.g. "Use PostgreSQL for persistence")'
+                ].join("\n")
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+};

package/src/catalog/facets/process.ts

@@ -0,0 +1,50 @@
+import type { Facet } from "../../types.js";
+
+export const processFacet: Facet = {
+  id: "process",
+  label: "Process",
+  description: "How your AI agent receives and executes tasks",
+  required: true,
+  options: [
+    {
+      id: "codemcp-workflows",
+      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"
+          }
+        },
+        {
+          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: "native-agents-md",
+      label: "Native agents.md",
+      description: "Use a plain agents.md instruction file",
+      recipe: [
+        {
+          writer: "instruction",
+          config: {
+            text: "Read AGENTS.md for project conventions and task instructions."
+          }
+        }
+      ]
+    }
+  ]
+};

package/src/catalog/index.ts

@@ -0,0 +1,86 @@
+import type { Catalog, Facet, Option } from "../types.js";
+import { processFacet } from "./facets/process.js";
+import { architectureFacet } from "./facets/architecture.js";
+import { practicesFacet } from "./facets/practices.js";
+import { backpressureFacet } from "./facets/backpressure.js";
+
+export function getDefaultCatalog(): Catalog {
+  return {
+    facets: [processFacet, architectureFacet, practicesFacet, backpressureFacet]
+  };
+}
+
+export function getFacet(catalog: Catalog, id: string): Facet | undefined {
+  return catalog.facets.find((f) => f.id === id);
+}
+
+export function getOption(facet: Facet, id: string): Option | undefined {
+  return facet.options.find((o) => o.id === id);
+}
+
+/**
+ * Topologically sort facets so that dependency facets come before dependent ones.
+ * Uses Kahn's algorithm. Throws if a cycle is detected.
+ */
+export function sortFacets(catalog: Catalog): Facet[] {
+  const facets = catalog.facets;
+  const idToFacet = new Map(facets.map((f) => [f.id, f]));
+
+  // Build in-degree and adjacency (dependsOn edge: dep → dependent)
+  const inDegree = new Map<string, number>(facets.map((f) => [f.id, 0]));
+  const dependents = new Map<string, string[]>(facets.map((f) => [f.id, []]));
+
+  for (const facet of facets) {
+    for (const dep of facet.dependsOn ?? []) {
+      if (idToFacet.has(dep)) {
+        inDegree.set(facet.id, (inDegree.get(facet.id) ?? 0) + 1);
+        dependents.get(dep)!.push(facet.id);
+      }
+    }
+  }
+
+  const queue: Facet[] = facets.filter((f) => (inDegree.get(f.id) ?? 0) === 0);
+  const result: Facet[] = [];
+
+  while (queue.length > 0) {
+    const facet = queue.shift()!;
+    result.push(facet);
+    for (const depId of dependents.get(facet.id) ?? []) {
+      const newDegree = (inDegree.get(depId) ?? 0) - 1;
+      inDegree.set(depId, newDegree);
+      if (newDegree === 0) {
+        queue.push(idToFacet.get(depId)!);
+      }
+    }
+  }
+
+  if (result.length !== facets.length) {
+    throw new Error("Cycle detected in facet dependsOn graph");
+  }
+
+  return result;
+}
+
+/**
+ * Returns only the options of a facet that are visible given the current choices.
+ * Options without an `available()` function are always visible.
+ */
+export function getVisibleOptions(
+  facet: Facet,
+  choices: Record<string, string | string[]>,
+  catalog: Catalog
+): Option[] {
+  return facet.options.filter((option) => {
+    if (!option.available) return true;
+    const deps: Record<string, Option | undefined> = {};
+    for (const depFacetId of facet.dependsOn ?? []) {
+      const depFacet = getFacet(catalog, depFacetId);
+      const choiceVal = choices[depFacetId];
+      deps[depFacetId] =
+        depFacet && typeof choiceVal === "string"
+          ? getOption(depFacet, choiceVal)
+          : undefined;
+    }
+    return option.available(deps);
+  });
+}

package/src/config.spec.ts

@@ -0,0 +1,165 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtemp, rm, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+
+import {
+  readUserConfig,
+  writeUserConfig,
+  readLockFile,
+  writeLockFile
+} from "./config.js";
+
+import type { UserConfig, LockFile } from "./types.js";
+
+describe("config", () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "ade-config-test-"));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describe("UserConfig roundtrip", () => {
+    it("write then read produces identical data", async () => {
+      const config: UserConfig = {
+        choices: {
+          language: "typescript",
+          framework: "react"
+        }
+      };
+
+      await writeUserConfig(tempDir, config);
+      const result = await readUserConfig(tempDir);
+
+      expect(result).toEqual(config);
+    });
+
+    it("returns null when config.yaml does not exist", async () => {
+      const result = await readUserConfig(tempDir);
+      expect(result).toBeNull();
+    });
+
+    it("multi-select choices (string[]) survive roundtrip", async () => {
+      const config: UserConfig = {
+        choices: {
+          language: "typescript",
+          plugins: ["eslint", "prettier", "vitest"]
+        }
+      };
+
+      await writeUserConfig(tempDir, config);
+      const result = await readUserConfig(tempDir);
+
+      expect(result).toEqual(config);
+      expect(Array.isArray(result!.choices.plugins)).toBe(true);
+      expect(result!.choices.plugins).toEqual(["eslint", "prettier", "vitest"]);
+    });
+
+    it("custom section with mcp_servers and instructions survives roundtrip", async () => {
+      const config: UserConfig = {
+        choices: {
+          language: "python"
+        },
+        custom: {
+          mcp_servers: [
+            {
+              ref: "my-server",
+              command: "npx",
+              args: ["-y", "my-mcp-server"],
+              env: { API_KEY: "test-key" }
+            }
+          ],
+          instructions: ["Always use type hints", "Follow PEP 8 style guide"]
+        }
+      };
+
+      await writeUserConfig(tempDir, config);
+      const result = await readUserConfig(tempDir);
+
+      expect(result).toEqual(config);
+      expect(result!.custom!.mcp_servers).toHaveLength(1);
+      expect(result!.custom!.mcp_servers![0].ref).toBe("my-server");
+      expect(result!.custom!.instructions).toEqual([
+        "Always use type hints",
+        "Follow PEP 8 style guide"
+      ]);
+    });
+  });
+
+  describe("LockFile roundtrip", () => {
+    it("write then read produces identical data", async () => {
+      const lock: LockFile = {
+        version: 1,
+        generated_at: "2026-03-14T00:00:00.000Z",
+        choices: {
+          language: "typescript",
+          framework: "react"
+        },
+        logical_config: {
+          mcp_servers: [
+            {
+              ref: "typescript-server",
+              command: "npx",
+              args: ["-y", "ts-server"],
+              env: {}
+            }
+          ],
+          instructions: ["Use strict TypeScript"],
+          cli_actions: [
+            {
+              command: "npm",
+              args: ["install"],
+              phase: "install"
+            }
+          ],
+          knowledge_sources: [
+            {
+              name: "ts-docs",
+              origin: "https://typescriptlang.org",
+              description: "TypeScript documentation"
+            }
+          ],
+          skills: [],
+          git_hooks: [],
+          setup_notes: []
+        }
+      };
+
+      await writeLockFile(tempDir, lock);
+      const result = await readLockFile(tempDir);
+
+      expect(result).toEqual(lock);
+    });
+
+    it("returns null when config.lock.yaml does not exist", async () => {
+      const result = await readLockFile(tempDir);
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("YAML validity", () => {
+    it("config file written is valid YAML", async () => {
+      const config: UserConfig = {
+        choices: {
+          language: "typescript",
+          tools: ["eslint", "prettier"]
+        },
+        custom: {
+          instructions: ["Be concise"]
+        }
+      };
+
+      await writeUserConfig(tempDir, config);
+
+      const raw = await readFile(join(tempDir, "config.yaml"), "utf-8");
+      const parsed = parseYaml(raw);
+
+      expect(parsed).toEqual(config);
+    });
+  });
+});

package/src/config.ts

@@ -0,0 +1,39 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+import type { UserConfig, LockFile } from "./types.js";
+
+const CONFIG_FILE = "config.yaml";
+const LOCK_FILE = "config.lock.yaml";
+
+export async function readUserConfig(dir: string): Promise<UserConfig | null> {
+  try {
+    const raw = await readFile(join(dir, CONFIG_FILE), "utf-8");
+    return parse(raw) as UserConfig;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeUserConfig(
+  dir: string,
+  config: UserConfig
+): Promise<void> {
+  await writeFile(join(dir, CONFIG_FILE), stringify(config), "utf-8");
+}
+
+export async function readLockFile(dir: string): Promise<LockFile | null> {
+  try {
+    const raw = await readFile(join(dir, LOCK_FILE), "utf-8");
+    return parse(raw) as LockFile;
+  } catch {
+    return null;
+  }
+}
+
+export async function writeLockFile(
+  dir: string,
+  lock: LockFile
+): Promise<void> {
+  await writeFile(join(dir, LOCK_FILE), stringify(lock), "utf-8");
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export {
+  type Catalog,
+  type Facet,
+  type Option,
+  type Provision,
+  type DocsetDef
+} from "./types.js";
+export {
+  type LogicalConfig,
+  type McpServerEntry,
+  type CliAction,
+  type KnowledgeSource,
+  type SkillDefinition,
+  type InlineSkill,
+  type ExternalSkill,
+  type GitHook
+} from "./types.js";
+export { type ResolutionContext, type ResolvedFacet } from "./types.js";
+export { type UserConfig, type LockFile } from "./types.js";
+export { type ProvisionWriter } from "./types.js";
+export {
+  readUserConfig,
+  writeUserConfig,
+  readLockFile,
+  writeLockFile
+} from "./config.js";
+export {
+  type ProvisionWriterDef,
+  type AgentWriterDef,
+  type WriterRegistry
+} from "./types.js";
+export {
+  createRegistry,
+  registerProvisionWriter,
+  getProvisionWriter,
+  registerAgentWriter,
+  getAgentWriter,
+  createDefaultRegistry
+} from "./registry.js";
+export { resolve, collectDocsets } from "./resolver.js";
+export {
+  getDefaultCatalog,
+  getFacet,
+  getOption,
+  sortFacets,
+  getVisibleOptions
+} from "./catalog/index.js";
+export { skillsWriter } from "./writers/skills.js";
+export { knowledgeWriter } from "./writers/knowledge.js";