@plainconceptsplatform/workflows 0.1.2 → 0.1.5

package/README.md

@@ -1,4 +1,4 @@
-# Platform workflows
+# Workflows CLI
 
 Install and update shared GitHub Agentic Workflows for Plain Concepts Platform repositories.
 
@@ -9,22 +9,40 @@ Before installing workflows, install and configure [`PlainConceptsPlatform/openc
 For one-off use, prefer:
 
 ```bash
-npx @plainconceptsplatform/workflows@latest platform-workflows init
-npx @plainconceptsplatform/workflows@latest platform-workflows add
-npx @plainconceptsplatform/workflows@latest platform-workflows update
+npx @plainconceptsplatform/workflows@latest init
+npx @plainconceptsplatform/workflows@latest add
+npx @plainconceptsplatform/workflows@latest update
 ```
 
 For a project-local development dependency:
 
 ```bash
 pnpm add -D @plainconceptsplatform/workflows
-pnpm exec platform-workflows init
-pnpm exec platform-workflows add
+pnpm exec workflows init
+pnpm exec workflows add
 ```
 
-`init` detects the repository stack and visibility, creates `.github/workflows/shared/repo-config.md` when absent, and records managed workflow state. Complete the consumer configuration before compiling workflows.
+`init` inspects the repository and reports its stack and visibility. It does not create or manage repository configuration or a manifest.
 
-`add` installs missing package-owned files. It stops when a managed file differs. Use `pnpm exec platform-workflows update --force` only when you intend to replace managed workflow files. It never overwrites `repo-config.md`.
+`add` installs package-owned files. It stops when a managed file differs. Use `pnpm exec workflows update --force` only when you intend to replace managed workflow files.
+
+Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-maintenance`, `app-ci-dotnet-next`, and `app-ci-node-monorepo`. CI templates are stack-specific copies, not a combined template. Edit their top-level `env:` values for repository paths, package names, and commands.
+
+## List and search
+
+List all available workflows, routes, and templates with install status:
+
+```bash
+npx --yes --package @plainconceptsplatform/workflows@latest workflows list
+```
+
+Each entry is marked `[x]` when the corresponding `.github/workflows/agent-*.md` file already exists in the current directory, or `[ ]` when it is not yet installed.
+
+Search by name or description:
+
+```bash
+npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci"
+```
 
 ## Manual installation
 
@@ -32,10 +50,10 @@ The package includes `loops/`, a copyable equivalent of `.github/`:
 
 - `loops/actions/` maps to `.github/actions/`
 - `loops/workflows/` maps to `.github/workflows/`
-- `loops/aw/repo-config.md` maps to `.github/workflows/shared/repo-config.md`
 - `loops/scripts/` maps to `scripts/`
 
-Copy these files manually if you do not use the CLI. Keep `repo-config.md` consumer-owned.
+Copy these files manually if you do not use the CLI. Each worker is self-contained. Edit its
+top-level `env:` defaults directly for consumer-specific endpoint, model, labels, paths, and checks.
 
 ## Compile
 

package/dist/catalog-installation.d.ts

@@ -1,4 +1,4 @@
-import { repositoryConfigRelativePath } from "./repository-state.js";
+import { type TemplateName } from "./workflow-catalog.js";
 export interface CatalogInstallResult {
     readonly installed: readonly string[];
     readonly conflicts: readonly string[];
@@ -9,4 +9,5 @@ export interface CatalogInstallOptions {
 }
 export declare function catalogSourcePath(modulePath?: string): string;
 export declare function installCatalog(repositoryPath: string, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
-export { repositoryConfigRelativePath };
+export declare function installTemplate(repositoryPath: string, template: TemplateName, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
+export declare function isTemplateName(value: string): value is TemplateName;

package/dist/catalog-installation.js

@@ -2,7 +2,7 @@ import { access, copyFile, mkdir, readFile, readdir } from "node:fs/promises";
 import { constants } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { repositoryConfigRelativePath } from "./repository-state.js";
+import { catalogTemplates, templateNames } from "./workflow-catalog.js";
 const sourceMappings = [
     ["actions", ".github/actions"],
     ["workflows", ".github/workflows"],
@@ -30,6 +30,31 @@ export async function installCatalog(repositoryPath, options = {}) {
     }));
     return { installed: files.map((file) => file.target), conflicts };
 }
+export async function installTemplate(repositoryPath, template, options = {}) {
+    const sourcePath = options.sourcePath ?? catalogSourcePath();
+    const meta = catalogTemplateMeta(template);
+    const source = join(sourcePath, "templates", meta.directory, meta.file);
+    const target = meta.target;
+    const destination = join(repositoryPath, target);
+    const conflicts = await exists(destination) && !(await filesMatch(source, destination)) ? [target] : [];
+    if (conflicts.length > 0 && !options.force)
+        return { installed: [], conflicts };
+    await mkdir(dirname(destination), { recursive: true });
+    await copyFile(source, destination);
+    return { installed: [target], conflicts };
+}
+export function isTemplateName(value) {
+    return templateNames.includes(value);
+}
+function catalogTemplateMeta(template) {
+    const entry = catalogTemplates.find((item) => item.name === template);
+    if (entry === undefined)
+        throw new Error(`Unknown template: ${template}`);
+    const directory = template.startsWith("opencode") ? "opencode" : template.startsWith("app-ci-") ? "ci" : "agentics";
+    const isWorkflow = entry.file.endsWith(".yml");
+    const target = isWorkflow ? `.github/workflows/${entry.file}` : entry.file;
+    return { directory, file: entry.file, target };
+}
 async function catalogFiles(sourcePath) {
     const files = [];
     for (const [sourceDirectory, targetDirectory] of sourceMappings) {
@@ -43,10 +68,6 @@ async function catalogFiles(sourcePath) {
             });
         }
     }
-    const repositoryConfigSource = join(sourcePath, "aw", "repo-config.md");
-    if (await exists(repositoryConfigSource)) {
-        files.push({ source: repositoryConfigSource, target: repositoryConfigRelativePath, managed: false });
-    }
     return files.sort((left, right) => left.target.localeCompare(right.target));
 }
 function isGeneratedFile(file) {
@@ -77,4 +98,3 @@ async function exists(path) {
         return false;
     }
 }
-export { repositoryConfigRelativePath };

package/dist/catalog-installation.test.js

@@ -2,7 +2,7 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
-import { catalogSourcePath, installCatalog, repositoryConfigRelativePath } from "./catalog-installation.js";
+import { catalogSourcePath, installCatalog, installTemplate } from "./catalog-installation.js";
 const temporaryDirectories = [];
 afterEach(async () => {
     await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })));
@@ -15,13 +15,12 @@ describe("catalog installation", () => {
         });
         expect(catalogSourcePath(join(packageDirectory, "dist", "catalog-installation.js"))).toBe(join(packageDirectory, "loops"));
     });
-    it("installs package-owned loops files and initializes repository config", async () => {
+    it("installs package-owned loops files", async () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "name: Check\n",
             "workflows/agent-check.md": "# Check\n",
             "workflows/shared/defaults.md": "defaults\n",
             "scripts/compile.mjs": "console.log('compile');\n",
-            "aw/repo-config.md": "# Repository configuration\n",
             "workflows/agent-check.lock.yml": "generated\n",
             "actions/actions-lock.json": "generated\n",
         });
@@ -31,12 +30,25 @@ describe("catalog installation", () => {
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
                 ".github/workflows/shared/defaults.md",
-                repositoryConfigRelativePath,
                 "scripts/compile.mjs",
             ],
             conflicts: [],
         });
-        await expect(readFile(join(repositoryPath, repositoryConfigRelativePath), "utf8")).resolves.toBe("# Repository configuration\n");
+    });
+    it("copies ownership headers for base workflows and selected templates", async () => {
+        const header = "# Managed by @plainconceptsplatform/workflows. Source: loops/workflows/agent-check.md. Update with `workflows update --force`; consumer edits may be overwritten.\n";
+        const templateHeader = "# Managed by @plainconceptsplatform/workflows. Source: loops/templates/agentics/agentics-checks.yml. Update with `workflows update --force`; consumer edits may be overwritten.\n";
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "# Managed by @plainconceptsplatform/workflows. Source: loops/actions/check/action.yml. Update with `workflows update --force`; consumer edits may be overwritten.\nname: Check\n",
+            "workflows/agent-check.md": `---\n${header}# Check\n`,
+            "scripts/compile.mjs": "// Managed by @plainconceptsplatform/workflows. Source: loops/scripts/compile.mjs. Update with `workflows update --force`; consumer edits may be overwritten.\n",
+            "templates/agentics/agentics-checks.yml": `${templateHeader}name: Agentics checks\n`,
+        });
+        const repositoryPath = await createDirectory({});
+        await installCatalog(repositoryPath, { sourcePath });
+        await installTemplate(repositoryPath, "agentics-checks", { sourcePath });
+        await expect(readFile(join(repositoryPath, ".github/workflows/agent-check.md"), "utf8")).resolves.toMatch(new RegExp(`^---\\n${escapeRegularExpression(header)}`));
+        await expect(readFile(join(repositoryPath, ".github/workflows/agentics-checks.yml"), "utf8")).resolves.toMatch(new RegExp(`^${escapeRegularExpression(templateHeader)}`));
     });
     it("does not report identical managed files as conflicts", async () => {
         const sourcePath = await createDirectory({
@@ -47,18 +59,35 @@ describe("catalog installation", () => {
         const repositoryPath = await createDirectory({ ".github/workflows/agent-check.md": "# Check\n" });
         await expect(installCatalog(repositoryPath, { sourcePath })).resolves.toMatchObject({ conflicts: [] });
     });
-    it("requires force for different managed files and preserves repository config", async () => {
+    it("does not manage legacy repository configuration files", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile.mjs": "compile\n",
+        });
+        const repositoryPath = await createDirectory({
+            ".github/workflows/shared/repo-config.md": "legacy consumer config\n",
+        });
+        await expect(installCatalog(repositoryPath, { sourcePath })).resolves.toMatchObject({
+            installed: [
+                ".github/actions/check/action.yml",
+                ".github/workflows/agent-check.md",
+                "scripts/compile.mjs",
+            ],
+            conflicts: [],
+        });
+        await expect(readFile(join(repositoryPath, ".github/workflows/shared/repo-config.md"), "utf8")).resolves.toBe("legacy consumer config\n");
+    });
+    it("requires force for different managed files", async () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "package action\n",
             "workflows/agent-check.md": "package workflow\n",
             "scripts/compile.mjs": "package script\n",
-            "aw/repo-config.md": "package config\n",
         });
         const repositoryPath = await createDirectory({
             ".github/actions/check/action.yml": "consumer action\n",
             ".github/workflows/agent-check.md": "consumer workflow\n",
             "scripts/compile.mjs": "consumer script\n",
-            [repositoryConfigRelativePath]: "consumer config\n",
         });
         await expect(installCatalog(repositoryPath, { sourcePath })).resolves.toEqual({
             installed: [],
@@ -76,11 +105,73 @@ describe("catalog installation", () => {
             ],
         });
         await expect(readFile(join(repositoryPath, ".github/actions/check/action.yml"), "utf8")).resolves.toBe("package action\n");
-        await expect(readFile(join(repositoryPath, repositoryConfigRelativePath), "utf8")).resolves.toBe("consumer config\n");
+    });
+    it("installs templates only when explicitly selected", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile.mjs": "compile\n",
+            "templates/agentics/agentics-checks.yml": "name: Agentics checks\n",
+            "templates/ci/app-ci-node-monorepo.yml": "name: Node CI\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        await installCatalog(repositoryPath, { sourcePath });
+        await expect(readFile(join(repositoryPath, ".github/workflows/agentics-checks.yml"), "utf8")).rejects.toThrow();
+        await expect(installTemplate(repositoryPath, "agentics-checks", { sourcePath })).resolves.toEqual({
+            installed: [".github/workflows/agentics-checks.yml"],
+            conflicts: [],
+        });
+        await expect(installTemplate(repositoryPath, "app-ci-node-monorepo", { sourcePath })).resolves.toEqual({
+            installed: [".github/workflows/app-ci-node-monorepo.yml"],
+            conflicts: [],
+        });
+    });
+    it("installs the opencode.ci.json template to the repository root", async () => {
+        const sourcePath = await createDirectory({
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        await expect(installTemplate(repositoryPath, "opencode.ci.json", { sourcePath })).resolves.toEqual({
+            installed: ["opencode.ci.json"],
+            conflicts: [],
+        });
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+    });
+    it("requires force to replace the opencode.ci.json template", async () => {
+        const sourcePath = await createDirectory({
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({
+            "opencode.ci.json": "{ \"model\": \"consumer-model\" }\n",
+        });
+        await expect(installTemplate(repositoryPath, "opencode.ci.json", { sourcePath })).resolves.toEqual({
+            installed: [],
+            conflicts: ["opencode.ci.json"],
+        });
+        await expect(installTemplate(repositoryPath, "opencode.ci.json", { force: true, sourcePath })).resolves.toMatchObject({
+            installed: ["opencode.ci.json"],
+        });
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+    });
+    it("requires force to replace a selected template", async () => {
+        const sourcePath = await createDirectory({
+            "templates/agentics/agentics-checks.yml": "package template\n",
+        });
+        const repositoryPath = await createDirectory({
+            ".github/workflows/agentics-checks.yml": "consumer template\n",
+        });
+        await expect(installTemplate(repositoryPath, "agentics-checks", { sourcePath })).resolves.toEqual({
+            installed: [],
+            conflicts: [".github/workflows/agentics-checks.yml"],
+        });
+        await expect(installTemplate(repositoryPath, "agentics-checks", { force: true, sourcePath })).resolves.toMatchObject({
+            installed: [".github/workflows/agentics-checks.yml"],
+        });
     });
 });
 async function createDirectory(files) {
-    const directory = await mkdtemp(join(tmpdir(), "platform-workflows-"));
+    const directory = await mkdtemp(join(tmpdir(), "workflows-"));
     temporaryDirectories.push(directory);
     await Promise.all(Object.entries(files).map(async ([relativePath, content]) => {
         const path = join(directory, relativePath);
@@ -90,3 +181,6 @@ async function createDirectory(files) {
     }));
     return directory;
 }
+function escapeRegularExpression(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/catalog-listing.d.ts

@@ -0,0 +1,13 @@
+export interface CatalogEntry {
+    readonly kind: "route" | "template";
+    readonly name: string;
+    readonly description: string;
+    readonly file: string;
+    readonly installed: boolean;
+}
+export interface ListOptions {
+    readonly installedPath?: string;
+}
+export declare function listCatalog(options?: ListOptions): Promise<readonly CatalogEntry[]>;
+export declare function searchCatalog(entries: readonly CatalogEntry[], query: string): readonly CatalogEntry[];
+export declare function formatCatalog(entries: readonly CatalogEntry[]): string;

package/dist/catalog-listing.js

@@ -0,0 +1,68 @@
+import { access, constants } from "node:fs/promises";
+import { join } from "node:path";
+import { catalogTemplates, workflowRoutes } from "./workflow-catalog.js";
+export async function listCatalog(options = {}) {
+    const basePath = options.installedPath ?? process.cwd();
+    const routes = await Promise.all(workflowRoutes.map(async (route) => ({
+        kind: "route",
+        name: route.name,
+        description: route.description,
+        file: route.worker,
+        installed: await isFileInstalled(basePath, route.worker),
+    })));
+    const templates = await Promise.all(catalogTemplates.map(async (template) => ({
+        kind: "template",
+        name: template.name,
+        description: template.description,
+        file: template.file,
+        installed: await isFileInstalled(basePath, template.file),
+    })));
+    return [...routes, ...templates];
+}
+export function searchCatalog(entries, query) {
+    const normalized = query.toLowerCase().trim();
+    if (normalized === "")
+        return [];
+    return entries.filter((entry) => entry.name.toLowerCase().includes(normalized) ||
+        entry.description.toLowerCase().includes(normalized));
+}
+export function formatCatalog(entries) {
+    if (entries.length === 0)
+        return "No workflows matched the search query.";
+    const routes = entries.filter((entry) => entry.kind === "route");
+    const templates = entries.filter((entry) => entry.kind === "template");
+    const lines = [];
+    if (routes.length > 0) {
+        lines.push("Workflows:");
+        for (const entry of routes) {
+            lines.push(formatEntry(entry));
+        }
+    }
+    if (templates.length > 0) {
+        if (lines.length > 0)
+            lines.push("");
+        lines.push("Templates:");
+        for (const entry of templates) {
+            lines.push(formatEntry(entry));
+        }
+    }
+    return lines.join("\n");
+}
+function formatEntry(entry) {
+    const mark = entry.installed ? "[x]" : "[ ]";
+    return `  ${mark} ${entry.name} — ${entry.description}`;
+}
+async function isFileInstalled(basePath, workerOrTemplateFile) {
+    const installedPath = templateInstallPath(basePath, workerOrTemplateFile);
+    try {
+        await access(installedPath, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function templateInstallPath(basePath, file) {
+    const isRootTemplate = file.endsWith(".json");
+    return isRootTemplate ? join(basePath, file) : join(basePath, ".github", "workflows", file);
+}

package/dist/catalog-listing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/catalog-listing.test.js

@@ -0,0 +1,137 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { formatCatalog, listCatalog, searchCatalog } from "./catalog-listing.js";
+import { workflowRoutes, catalogTemplates } from "./workflow-catalog.js";
+const temporaryDirectories = [];
+afterEach(async () => {
+    await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })));
+});
+describe("catalog listing", () => {
+    it("returns all routes and templates", async () => {
+        const repositoryPath = await createRepository({});
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        expect(entries).toHaveLength(workflowRoutes.length + catalogTemplates.length);
+        const routeNames = entries.filter((entry) => entry.kind === "route").map((entry) => entry.name);
+        const templateNames = entries.filter((entry) => entry.kind === "template").map((entry) => entry.name);
+        expect(routeNames).toEqual(["refine", "implement", "direct", "apply-review", "merge-gate", "audit", "propose"]);
+        expect(templateNames).toEqual(["agentics-checks", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "opencode.ci.json"]);
+    });
+    it("reports all entries as not installed in an empty repository", async () => {
+        const repositoryPath = await createRepository({});
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        expect(entries.every((entry) => entry.installed === false)).toBe(true);
+    });
+    it("marks a route as installed when its worker file exists", async () => {
+        const repositoryPath = await createRepository({
+            ".github/workflows/agent-refine.md": "# Refine",
+        });
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        const refineEntry = entries.find((entry) => entry.name === "refine");
+        expect(refineEntry).toBeDefined();
+        expect(refineEntry.installed).toBe(true);
+    });
+    it("marks a template as installed when its template file exists", async () => {
+        const repositoryPath = await createRepository({
+            ".github/workflows/agentics-checks.yml": "name: Agentics checks",
+        });
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        const checksEntry = entries.find((entry) => entry.name === "agentics-checks");
+        expect(checksEntry).toBeDefined();
+        expect(checksEntry.installed).toBe(true);
+    });
+    it("marks the opencode.ci.json template as installed when the file exists at repository root", async () => {
+        const repositoryPath = await createRepository({
+            "opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }",
+        });
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        const opencodeEntry = entries.find((entry) => entry.name === "opencode.ci.json");
+        expect(opencodeEntry).toBeDefined();
+        expect(opencodeEntry.installed).toBe(true);
+    });
+    it("reports mixed installed and uninstalled entries", async () => {
+        const repositoryPath = await createRepository({
+            ".github/workflows/agent-refine.md": "# Refine",
+            ".github/workflows/agent-audit.md": "# Audit",
+            ".github/workflows/app-ci-dotnet-next.yml": "name: CI",
+            "opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }",
+        });
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        expect(entries.filter((entry) => entry.installed).map((entry) => entry.name))
+            .toEqual(expect.arrayContaining(["refine", "audit", "app-ci-dotnet-next", "opencode.ci.json"]));
+        expect(entries.filter((entry) => !entry.installed)).toHaveLength(workflowRoutes.length + catalogTemplates.length - 4);
+    });
+});
+describe("searchCatalog", () => {
+    const sampleEntries = [
+        { kind: "route", name: "refine", description: "Refines an issue into a user story.", file: "agent-refine.md", installed: false },
+        { kind: "route", name: "audit", description: "Read-only repository audit.", file: "agent-audit.md", installed: true },
+        { kind: "template", name: "app-ci-dotnet-next", description: "App CI pipeline for .NET + Next.js.", file: "app-ci-dotnet-next.yml", installed: false },
+    ];
+    it("filters by name match", () => {
+        const results = searchCatalog(sampleEntries, "audit");
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe("audit");
+    });
+    it("filters by description match", () => {
+        const results = searchCatalog(sampleEntries, "user story");
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe("refine");
+    });
+    it("is case-insensitive", () => {
+        const results = searchCatalog(sampleEntries, "AUDIT");
+        expect(results).toHaveLength(1);
+        expect(results[0].name).toBe("audit");
+    });
+    it("returns empty array for no matches", () => {
+        const results = searchCatalog(sampleEntries, "nonexistent");
+        expect(results).toHaveLength(0);
+    });
+    it("returns empty array for empty query after trim", () => {
+        expect(searchCatalog(sampleEntries, "  ")).toHaveLength(0);
+    });
+    it("returns both routes and templates when the query matches both kinds", () => {
+        const entries = [
+            { kind: "route", name: "direct", description: "Executes a CI instruction.", file: "agent-direct.md", installed: false },
+            { kind: "template", name: "app-ci-dotnet-next", description: "App CI pipeline.", file: "app-ci-dotnet-next.yml", installed: true },
+        ];
+        const results = searchCatalog(entries, "CI");
+        expect(results).toHaveLength(2);
+    });
+});
+describe("formatCatalog", () => {
+    it("groups routes under Workflows and templates under Templates", () => {
+        const entries = [
+            { kind: "route", name: "refine", description: "Refines a story.", file: "agent-refine.md", installed: true },
+            { kind: "template", name: "app-ci-dotnet-next", description: "CI for .NET.", file: "app-ci-dotnet-next.yml", installed: false },
+        ];
+        const output = formatCatalog(entries);
+        expect(output).toContain("Workflows:");
+        expect(output).toContain("Templates:");
+        expect(output).toContain("[x] refine");
+        expect(output).toContain("[ ] app-ci-dotnet-next");
+    });
+    it("prints a no-match message for an empty result", () => {
+        expect(formatCatalog([])).toBe("No workflows matched the search query.");
+    });
+    it("prints only a Workflows section when no templates match", () => {
+        const entries = [
+            { kind: "route", name: "refine", description: "Refines.", file: "agent-refine.md", installed: false },
+        ];
+        const output = formatCatalog(entries);
+        expect(output).toContain("Workflows:");
+        expect(output).not.toContain("Templates:");
+    });
+});
+async function createRepository(files) {
+    const repositoryPath = await mkdtemp(join(tmpdir(), "workflows-"));
+    temporaryDirectories.push(repositoryPath);
+    await Promise.all(Object.entries(files).map(async ([relativePath, content]) => {
+        const path = join(repositoryPath, relativePath);
+        const { mkdir } = await import("node:fs/promises");
+        await mkdir(join(path, ".."), { recursive: true });
+        await writeFile(path, content, "utf8");
+    }));
+    return repositoryPath;
+}

package/dist/index.js

@@ -1,13 +1,49 @@
 #!/usr/bin/env node
 import { inspectRepository, parseVisibility, resolveVisibility } from "./repository-inspection.js";
-import { installCatalog } from "./catalog-installation.js";
-import { initializeRepository, readManifest, repositoryConfigRelativePath } from "./repository-state.js";
+import { installCatalog, installTemplate, isTemplateName } from "./catalog-installation.js";
+import { formatCatalog, listCatalog, searchCatalog } from "./catalog-listing.js";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+const HELP_TEXT = `Workflows CLI — install and manage Plain Concepts Platform agentic workflows.
+
+Usage: workflows <command> [options]
+
+Commands:
+  init                                        Inspect the repository and report its stack and visibility.
+  add                                         Install package-owned workflow files into .github/.
+  update                                      Alias for add. Use --force to overwrite managed files.
+  status                                      Print repository inspection as JSON.
+  list                                        List all available workflows and templates with install status.
+  search <query>                              Filter workflows and templates by name or description.
+
+Options:
+  --visibility public|private                 Override repository visibility (init only).
+  --template <name>                           Install a standalone template instead of the catalog.
+                                              Templates: agentics-checks, agentics-maintenance,
+                                              app-ci-dotnet-next, app-ci-node-monorepo,
+                                              opencode.ci.json.
+  --force                                     Overwrite managed files that differ from the package source.
+  -h, --help                                  Show this help text.
+
+Installed workflows are marked [x] when the corresponding .github/workflows/agent-*.md
+file exists relative to the current directory.`;
 export async function run(arguments_, repositoryPath = process.cwd()) {
     const [command, ...options] = arguments_;
     if (command === "--help" || command === "-h" || command === undefined) {
-        console.log("Usage: platform-workflows <init|add|update|status> [--visibility public|private] [--force]");
+        console.log(HELP_TEXT);
+        return 0;
+    }
+    if (command === "list") {
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        console.log(formatCatalog(entries));
+        return 0;
+    }
+    if (command === "search") {
+        if (options.length === 0 || options.length > 1)
+            return fail("search requires exactly one query argument.");
+        const allEntries = await listCatalog({ installedPath: repositoryPath });
+        const results = searchCatalog(allEntries, options[0]);
+        console.log(formatCatalog(results));
         return 0;
     }
     if (command === "init") {
@@ -16,21 +52,23 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
             return fail("--visibility must be public or private.");
         const inspection = await inspectRepository(repositoryPath);
         const resolvedVisibility = await resolveVisibility(repositoryPath, visibility);
-        const result = await initializeRepository(inspection, resolvedVisibility);
-        console.log(JSON.stringify({ command, ...result }, null, 2));
+        console.log(JSON.stringify({ command, inspection, visibility: resolvedVisibility }, null, 2));
         return 0;
     }
     if (command === "status") {
         const inspection = await inspectRepository(repositoryPath);
-        const manifest = await readManifest(repositoryPath);
-        console.log(JSON.stringify({ command, inspection, manifest, repositoryConfigPath: repositoryConfigRelativePath }, null, 2));
+        console.log(JSON.stringify({ command, inspection }, null, 2));
         return 0;
     }
     if (command === "add" || command === "update") {
-        if (options.some((option) => option !== "--force"))
-            return fail(`${command} accepts only --force.`);
-        const result = await installCatalog(repositoryPath, { force: options.includes("--force") });
-        if (result.conflicts.length > 0 && !options.includes("--force")) {
+        const template = readTemplateOption(options);
+        if (template === "invalid")
+            return fail(`${command} accepts only --force or --template agentics-checks|agentics-maintenance|app-ci-dotnet-next|app-ci-node-monorepo|opencode.ci.json.`);
+        const force = options.includes("--force");
+        const result = template === undefined
+            ? await installCatalog(repositoryPath, { force })
+            : await installTemplate(repositoryPath, template, { force });
+        if (result.conflicts.length > 0 && !force) {
             console.error(`Catalog conflicts found. Re-run with --force to overwrite package-managed files:\n${result.conflicts.join("\n")}`);
             return 1;
         }
@@ -46,6 +84,19 @@ function readVisibilityOption(options) {
         return "invalid";
     return parseVisibility(options[1]) ?? "invalid";
 }
+function readTemplateOption(options) {
+    const templateIndex = options.indexOf("--template");
+    if (templateIndex === -1)
+        return options.every((option) => option === "--force") ? undefined : "invalid";
+    if (templateIndex + 1 >= options.length || options.filter((option) => option === "--template").length !== 1)
+        return "invalid";
+    if (options.some((option, index) => option !== "--force" && index !== templateIndex && index !== templateIndex + 1))
+        return "invalid";
+    return templateNameFromOptions(options[templateIndex + 1]);
+}
+function templateNameFromOptions(value) {
+    return value !== undefined && isTemplateName(value) ? value : "invalid";
+}
 function fail(message) {
     console.error(message);
     return 1;

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};