@plainconceptsplatform/workflows 0.1.5 → 0.2.0

package/README.md

@@ -2,11 +2,21 @@
 
 Install and update shared GitHub Agentic Workflows for Plain Concepts Platform repositories.
 
+## Quick start
+
+The primary entrypoint is the interactive TUI. Run it with no arguments:
+
+```bash
+npx @plainconceptsplatform/workflows
+```
+
+The TUI lists all routes and templates with install status. Arrow keys navigate, space toggles, Enter installs. Selecting any route installs the full managed catalog plus mandatory `opencode.ci.json` and `scripts/compile-agent-workflows.mjs`. Selecting only templates still installs those mandatory files.
+
 ## Install
 
 Before installing workflows, install and configure [`PlainConceptsPlatform/opencode-onboard`](https://github.com/PlainConceptsPlatform/opencode-onboard) in the consumer repository. Loop workers invoke the skills and commands it provides. Verify the required skills and commands are available before compiling workflows.
 
-For one-off use, prefer:
+For non-interactive use (advanced):
 
 ```bash
 npx @plainconceptsplatform/workflows@latest init
@@ -18,13 +28,14 @@ For a project-local development dependency:
 
 ```bash
 pnpm add -D @plainconceptsplatform/workflows
+pnpm exec workflows              # launch interactive TUI
 pnpm exec workflows init
 pnpm exec workflows add
 ```
 
 `init` inspects the repository and reports its stack and visibility. It does not create or manage repository configuration or a manifest.
 
-`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.
+`add` installs package-owned files including the mandatory `opencode.ci.json` and `scripts/compile-agent-workflows.mjs`. 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.
 

package/dist/catalog-installation.d.ts

@@ -7,7 +7,15 @@ export interface CatalogInstallOptions {
     readonly force?: boolean;
     readonly sourcePath?: string;
 }
+interface CatalogFile {
+    readonly source: string;
+    readonly target: string;
+    readonly managed: boolean;
+}
+export declare function mandatoryFileSpecs(sourcePath: string): CatalogFile[];
 export declare function catalogSourcePath(modulePath?: string): string;
 export declare function installCatalog(repositoryPath: string, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
 export declare function installTemplate(repositoryPath: string, template: TemplateName, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
+export declare function installMandatoryFiles(repositoryPath: string, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
 export declare function isTemplateName(value: string): value is TemplateName;
+export {};

package/dist/catalog-installation.js

@@ -2,33 +2,41 @@ 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 { catalogTemplates, templateNames } from "./workflow-catalog.js";
+import { catalogTemplates, mandatoryFiles, templateNames } from "./workflow-catalog.js";
 const sourceMappings = [
     ["actions", ".github/actions"],
     ["workflows", ".github/workflows"],
     ["scripts", "scripts"],
 ];
+export function mandatoryFileSpecs(sourcePath) {
+    return mandatoryFiles.map((spec) => ({
+        source: join(sourcePath, spec.source),
+        target: spec.target,
+        managed: true,
+    }));
+}
 export function catalogSourcePath(modulePath = fileURLToPath(import.meta.url)) {
     return resolve(dirname(modulePath), "..", "loops");
 }
 export async function installCatalog(repositoryPath, options = {}) {
     const sourcePath = options.sourcePath ?? catalogSourcePath();
-    const files = await catalogFiles(sourcePath);
-    const managedFiles = files.filter((file) => file.managed);
+    const files = [...await catalogFiles(sourcePath), ...mandatoryFileSpecs(sourcePath)];
+    const deduplicated = files.filter((file, index) => files.findIndex((f) => f.target === file.target) === index).sort((left, right) => left.target.localeCompare(right.target));
+    const managedFiles = deduplicated.filter((file) => file.managed);
     const conflicts = (await Promise.all(managedFiles.map(async (file) => {
         const destination = join(repositoryPath, file.target);
         return await exists(destination) && !(await filesMatch(file.source, destination)) ? file.target : undefined;
     }))).filter((file) => file !== undefined);
     if (conflicts.length > 0 && !options.force)
         return { installed: [], conflicts };
-    await Promise.all(files.map(async (file) => {
+    await Promise.all(deduplicated.map(async (file) => {
         const destination = join(repositoryPath, file.target);
         if (!file.managed && await exists(destination))
             return;
         await mkdir(dirname(destination), { recursive: true });
         await copyFile(file.source, destination);
     }));
-    return { installed: files.map((file) => file.target), conflicts };
+    return { installed: deduplicated.map((file) => file.target), conflicts };
 }
 export async function installTemplate(repositoryPath, template, options = {}) {
     const sourcePath = options.sourcePath ?? catalogSourcePath();
@@ -43,6 +51,22 @@ export async function installTemplate(repositoryPath, template, options = {}) {
     await copyFile(source, destination);
     return { installed: [target], conflicts };
 }
+export async function installMandatoryFiles(repositoryPath, options = {}) {
+    const sourcePath = options.sourcePath ?? catalogSourcePath();
+    const files = mandatoryFileSpecs(sourcePath).sort((left, right) => left.target.localeCompare(right.target));
+    const conflicts = (await Promise.all(files.map(async (file) => {
+        const destination = join(repositoryPath, file.target);
+        return await exists(destination) && !(await filesMatch(file.source, destination)) ? file.target : undefined;
+    }))).filter((file) => file !== undefined);
+    if (conflicts.length > 0 && !options.force)
+        return { installed: [], conflicts };
+    await Promise.all(files.map(async (file) => {
+        const destination = join(repositoryPath, file.target);
+        await mkdir(dirname(destination), { recursive: true });
+        await copyFile(file.source, destination);
+    }));
+    return { installed: files.map((file) => file.target), conflicts };
+}
 export function isTemplateName(value) {
     return templateNames.includes(value);
 }

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, installTemplate } from "./catalog-installation.js";
+import { catalogSourcePath, installCatalog, installMandatoryFiles, installTemplate } from "./catalog-installation.js";
 const temporaryDirectories = [];
 afterEach(async () => {
     await Promise.all(temporaryDirectories.splice(0).map((directory) => rm(directory, { force: true, recursive: true })));
@@ -15,12 +15,14 @@ describe("catalog installation", () => {
         });
         expect(catalogSourcePath(join(packageDirectory, "dist", "catalog-installation.js"))).toBe(join(packageDirectory, "loops"));
     });
-    it("installs package-owned loops files", async () => {
+    it("installs package-owned loops files including mandatory opencode.ci.json and compile script", 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",
+            "scripts/compile-agent-workflows.mjs": "console.log('compile');\n",
+            "scripts/compile.mjs": "console.log('old compile');\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
             "workflows/agent-check.lock.yml": "generated\n",
             "actions/actions-lock.json": "generated\n",
         });
@@ -30,6 +32,8 @@ describe("catalog installation", () => {
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
                 ".github/workflows/shared/defaults.md",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
                 "scripts/compile.mjs",
             ],
             conflicts: [],
@@ -41,7 +45,8 @@ describe("catalog installation", () => {
         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",
+            "scripts/compile-agent-workflows.mjs": "// Managed by @plainconceptsplatform/workflows. Source: loops/scripts/compile-agent-workflows.mjs. Update with `workflows update --force`; consumer edits may be overwritten.\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
             "templates/agentics/agentics-checks.yml": `${templateHeader}name: Agentics checks\n`,
         });
         const repositoryPath = await createDirectory({});
@@ -54,7 +59,8 @@ describe("catalog installation", () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "name: Check\n",
             "workflows/agent-check.md": "# Check\n",
-            "scripts/compile.mjs": "compile\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
         });
         const repositoryPath = await createDirectory({ ".github/workflows/agent-check.md": "# Check\n" });
         await expect(installCatalog(repositoryPath, { sourcePath })).resolves.toMatchObject({ conflicts: [] });
@@ -63,7 +69,8 @@ describe("catalog installation", () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "name: Check\n",
             "workflows/agent-check.md": "# Check\n",
-            "scripts/compile.mjs": "compile\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
         });
         const repositoryPath = await createDirectory({
             ".github/workflows/shared/repo-config.md": "legacy consumer config\n",
@@ -72,7 +79,8 @@ describe("catalog installation", () => {
             installed: [
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
-                "scripts/compile.mjs",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
             ],
             conflicts: [],
         });
@@ -82,26 +90,30 @@ describe("catalog installation", () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "package action\n",
             "workflows/agent-check.md": "package workflow\n",
-            "scripts/compile.mjs": "package script\n",
+            "scripts/compile-agent-workflows.mjs": "package script\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\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",
+            "scripts/compile-agent-workflows.mjs": "consumer script\n",
+            "opencode.ci.json": "{ \"model\": \"consumer-model\" }\n",
         });
         await expect(installCatalog(repositoryPath, { sourcePath })).resolves.toEqual({
             installed: [],
             conflicts: [
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
-                "scripts/compile.mjs",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
             ],
         });
         await expect(installCatalog(repositoryPath, { force: true, sourcePath })).resolves.toMatchObject({
             conflicts: [
                 ".github/actions/check/action.yml",
                 ".github/workflows/agent-check.md",
-                "scripts/compile.mjs",
+                "opencode.ci.json",
+                "scripts/compile-agent-workflows.mjs",
             ],
         });
         await expect(readFile(join(repositoryPath, ".github/actions/check/action.yml"), "utf8")).resolves.toBe("package action\n");
@@ -110,10 +122,10 @@ describe("catalog installation", () => {
         const sourcePath = await createDirectory({
             "actions/check/action.yml": "name: Check\n",
             "workflows/agent-check.md": "# Check\n",
-            "scripts/compile.mjs": "compile\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\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 });
@@ -127,6 +139,82 @@ describe("catalog installation", () => {
             conflicts: [],
         });
     });
+    it("installCatalog installs mandatory opencode.ci.json and compile script alongside catalog files", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        const result = await installCatalog(repositoryPath, { sourcePath });
+        expect(result.installed).toContain("opencode.ci.json");
+        expect(result.installed).toContain("scripts/compile-agent-workflows.mjs");
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+        await expect(readFile(join(repositoryPath, "scripts/compile-agent-workflows.mjs"), "utf8")).resolves.toBe("compile\n");
+    });
+    it("installMandatoryFiles installs opencode.ci.json and compile script without catalog files", async () => {
+        const sourcePath = await createDirectory({
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        const result = await installMandatoryFiles(repositoryPath, { sourcePath });
+        expect(result.installed).toEqual(["opencode.ci.json", "scripts/compile-agent-workflows.mjs"]);
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+        await expect(readFile(join(repositoryPath, "scripts/compile-agent-workflows.mjs"), "utf8")).resolves.toBe("compile\n");
+    });
+    it("installMandatoryFiles reports conflicts on differing files", async () => {
+        const sourcePath = await createDirectory({
+            "scripts/compile-agent-workflows.mjs": "package script\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({
+            "opencode.ci.json": "{ \"model\": \"consumer\" }\n",
+            "scripts/compile-agent-workflows.mjs": "consumer script\n",
+        });
+        await expect(installMandatoryFiles(repositoryPath, { sourcePath })).resolves.toEqual({
+            installed: [],
+            conflicts: ["opencode.ci.json", "scripts/compile-agent-workflows.mjs"],
+        });
+    });
+    it("installMandatoryFiles overwrites with force", async () => {
+        const sourcePath = await createDirectory({
+            "scripts/compile-agent-workflows.mjs": "package script\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({
+            "opencode.ci.json": "{ \"model\": \"consumer\" }\n",
+            "scripts/compile-agent-workflows.mjs": "consumer script\n",
+        });
+        await expect(installMandatoryFiles(repositoryPath, { force: true, sourcePath })).resolves.toMatchObject({
+            installed: ["opencode.ci.json", "scripts/compile-agent-workflows.mjs"],
+        });
+        await expect(readFile(join(repositoryPath, "opencode.ci.json"), "utf8")).resolves.toBe("{ \"model\": \"plainconcepts/glm-5-2\" }\n");
+    });
+    it("installMandatoryFiles does not install catalog workflow files", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile-agent-workflows.mjs": "compile\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        await installMandatoryFiles(repositoryPath, { sourcePath });
+        await expect(readFile(join(repositoryPath, ".github/workflows/agent-check.md"), "utf8")).rejects.toThrow();
+    });
+    it("installCatalog deduplicates compile script in both scripts/ and mandatory files", async () => {
+        const sourcePath = await createDirectory({
+            "actions/check/action.yml": "name: Check\n",
+            "workflows/agent-check.md": "# Check\n",
+            "scripts/compile-agent-workflows.mjs": "same compile script\n",
+            "templates/opencode/opencode.ci.json": "{ \"model\": \"plainconcepts/glm-5-2\" }\n",
+        });
+        const repositoryPath = await createDirectory({});
+        const result = await installCatalog(repositoryPath, { sourcePath });
+        const compileEntries = result.installed.filter((path) => path === "scripts/compile-agent-workflows.mjs");
+        expect(compileEntries).toHaveLength(1);
+    });
     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",

package/dist/index.js

@@ -2,13 +2,22 @@
 import { inspectRepository, parseVisibility, resolveVisibility } from "./repository-inspection.js";
 import { installCatalog, installTemplate, isTemplateName } from "./catalog-installation.js";
 import { formatCatalog, listCatalog, searchCatalog } from "./catalog-listing.js";
+import { runInteractive } from "./tui.js";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const HELP_TEXT = `Workflows CLI — install and manage Plain Concepts Platform agentic workflows.
 
+Run with no arguments to launch the interactive TUI, the primary way to select and install
+workflows and templates:
+
+  npx @plainconceptsplatform/workflows
+
+Advanced (non-interactive) commands:
+
 Usage: workflows <command> [options]
 
 Commands:
+  (default)                                   Launch the interactive TUI for selecting and installing items.
   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.
@@ -29,10 +38,14 @@ Installed workflows are marked [x] when the corresponding .github/workflows/agen
 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) {
+    if (command === "--help" || command === "-h") {
         console.log(HELP_TEXT);
         return 0;
     }
+    if (command === undefined) {
+        const force = options.includes("--force");
+        return runInteractive(repositoryPath, { force });
+    }
     if (command === "list") {
         const entries = await listCatalog({ installedPath: repositoryPath });
         console.log(formatCatalog(entries));

package/dist/tui.d.ts

@@ -0,0 +1,25 @@
+import { type CatalogEntry } from "./catalog-listing.js";
+export type SelectionStatus = "selecting" | "submitting" | "cancelled";
+export interface SelectionState {
+    readonly allItems: readonly CatalogEntry[];
+    readonly visibleItems: readonly CatalogEntry[];
+    readonly selected: ReadonlySet<string>;
+    readonly cursor: number;
+    readonly filter: string;
+    readonly status: SelectionStatus;
+}
+export interface InteractiveOptions {
+    readonly force?: boolean;
+}
+export declare function createSelectionState(entries: readonly CatalogEntry[]): SelectionState;
+export declare function fuzzyMatch(text: string, query: string): boolean;
+export declare function filterItems(items: readonly CatalogEntry[], filter: string): readonly CatalogEntry[];
+export declare function applyFilter(state: SelectionState, filter: string): SelectionState;
+export declare function clearFilter(state: SelectionState): SelectionState;
+export declare function moveCursorUp(state: SelectionState): SelectionState;
+export declare function moveCursorDown(state: SelectionState): SelectionState;
+export declare function toggleSelection(state: SelectionState): SelectionState;
+export declare function submitSelection(state: SelectionState): SelectionState;
+export declare function cancelSelection(state: SelectionState): SelectionState;
+export declare function getItemsToInstall(state: SelectionState, force?: boolean): readonly CatalogEntry[];
+export declare function runInteractive(repositoryPath: string, options?: InteractiveOptions): Promise<number>;

package/dist/tui.js

@@ -0,0 +1,254 @@
+import * as readline from "node:readline";
+import { formatCatalog, listCatalog } from "./catalog-listing.js";
+import { installCatalog, installMandatoryFiles, installTemplate, isTemplateName } from "./catalog-installation.js";
+const ANSI = {
+    clear: "\x1b[2J",
+    home: "\x1b[H",
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+    green: "\x1b[32m",
+    grey: "\x1b[90m",
+    white: "\x1b[37m",
+    hideCursor: "\x1b[?25l",
+    showCursor: "\x1b[?25h",
+};
+export function createSelectionState(entries) {
+    const selected = new Set(entries.filter((entry) => entry.installed).map((entry) => entry.name));
+    return {
+        allItems: entries,
+        visibleItems: entries,
+        selected,
+        cursor: 0,
+        filter: "",
+        status: "selecting",
+    };
+}
+export function fuzzyMatch(text, query) {
+    if (query === "")
+        return true;
+    const haystack = text.toLowerCase();
+    const needle = query.toLowerCase();
+    let needleIndex = 0;
+    for (let i = 0; i < haystack.length && needleIndex < needle.length; i++) {
+        if (haystack[i] === needle[needleIndex])
+            needleIndex++;
+    }
+    return needleIndex === needle.length;
+}
+export function filterItems(items, filter) {
+    if (filter === "")
+        return items;
+    return items.filter((entry) => fuzzyMatch(`${entry.name} ${entry.description}`, filter));
+}
+export function applyFilter(state, filter) {
+    const visibleItems = filterItems(state.allItems, filter);
+    const cursor = visibleItems.length === 0 ? 0 : Math.min(state.cursor, visibleItems.length - 1);
+    return { ...state, visibleItems, filter, cursor };
+}
+export function clearFilter(state) {
+    return applyFilter(state, "");
+}
+export function moveCursorUp(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const cursor = state.cursor === 0 ? state.visibleItems.length - 1 : state.cursor - 1;
+    return { ...state, cursor };
+}
+export function moveCursorDown(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const cursor = state.cursor === state.visibleItems.length - 1 ? 0 : state.cursor + 1;
+    return { ...state, cursor };
+}
+export function toggleSelection(state) {
+    if (state.visibleItems.length === 0)
+        return state;
+    const entry = state.visibleItems[state.cursor];
+    if (entry === undefined)
+        return state;
+    const selected = new Set(state.selected);
+    if (selected.has(entry.name)) {
+        selected.delete(entry.name);
+    }
+    else {
+        selected.add(entry.name);
+    }
+    return { ...state, selected };
+}
+export function submitSelection(state) {
+    return { ...state, status: "submitting" };
+}
+export function cancelSelection(state) {
+    return { ...state, status: "cancelled" };
+}
+export function getItemsToInstall(state, force = false) {
+    return state.allItems.filter((entry) => state.selected.has(entry.name) && (force || !entry.installed));
+}
+function renderEntry(entry, highlighted, checked) {
+    const indicator = highlighted ? `${ANSI.bold}${ANSI.white}>${ANSI.reset}` : " ";
+    if (checked) {
+        const checkbox = `${ANSI.green}[x]${ANSI.reset}`;
+        const name = highlighted ? `${ANSI.white}${ANSI.bold}${entry.name}${ANSI.reset}` : entry.name;
+        const desc = `${ANSI.dim} — ${entry.description}${ANSI.reset}`;
+        return `${indicator} ${checkbox} ${name}${desc}`;
+    }
+    const checkbox = `${ANSI.grey}[ ]${ANSI.reset}`;
+    const name = highlighted ? `${ANSI.white}${ANSI.bold}${entry.name}${ANSI.reset}` : entry.name;
+    const desc = `${ANSI.dim} — ${entry.description}${ANSI.reset}`;
+    return `${indicator} ${checkbox} ${name}${desc}`;
+}
+function render(state) {
+    const lines = [];
+    lines.push(`${ANSI.cyan}${ANSI.bold}Plain Concepts Platform — Agentic Workflows${ANSI.reset}`);
+    lines.push(`${ANSI.dim}Select items to install. Already-installed items are pre-checked.${ANSI.reset}`);
+    lines.push("");
+    if (state.filter) {
+        lines.push(`${ANSI.cyan}Filter:${ANSI.reset} ${state.filter}${ANSI.grey}█${ANSI.reset}`);
+    }
+    else {
+        lines.push(`${ANSI.dim}Type to filter, arrows to navigate, space to toggle, Enter to install${ANSI.reset}`);
+    }
+    lines.push("");
+    const routes = state.visibleItems.filter((entry) => entry.kind === "route");
+    const templates = state.visibleItems.filter((entry) => entry.kind === "template");
+    let index = 0;
+    if (routes.length > 0) {
+        lines.push(`${ANSI.cyan}Workflows${ANSI.reset}`);
+        for (const entry of routes) {
+            lines.push(renderEntry(entry, index === state.cursor, state.selected.has(entry.name)));
+            index++;
+        }
+        if (templates.length > 0)
+            lines.push("");
+    }
+    if (templates.length > 0) {
+        lines.push(`${ANSI.cyan}Templates${ANSI.reset}`);
+        for (const entry of templates) {
+            lines.push(renderEntry(entry, index === state.cursor, state.selected.has(entry.name)));
+            index++;
+        }
+    }
+    if (state.visibleItems.length === 0) {
+        lines.push(`${ANSI.grey}  No items match the filter.${ANSI.reset}`);
+    }
+    lines.push("");
+    lines.push(`${ANSI.grey}↑↓ navigate  space toggle  type to filter  Enter install  Esc clear filter  q quit${ANSI.reset}`);
+    process.stdout.write(`${ANSI.clear}${ANSI.home}${lines.join("\n")}\n`);
+}
+export async function runInteractive(repositoryPath, options = {}) {
+    const force = options.force ?? false;
+    if (process.stdin.isTTY !== true) {
+        const entries = await listCatalog({ installedPath: repositoryPath });
+        console.log(formatCatalog(entries));
+        console.log("");
+        console.log("Run with a TTY for an interactive selection screen, or use: workflows add [--template <name>] [--force]");
+        return 0;
+    }
+    const entries = await listCatalog({ installedPath: repositoryPath });
+    let state = createSelectionState(entries);
+    readline.emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdout.write(ANSI.hideCursor);
+    render(state);
+    return new Promise((resolve) => {
+        const onKeypress = (str, key) => {
+            if (key?.ctrl && key?.name === "c") {
+                cleanup();
+                resolve(0);
+                return;
+            }
+            if (str === "q" && state.filter === "" && !key?.ctrl && !key?.meta && !key?.shift) {
+                cleanup();
+                resolve(0);
+                return;
+            }
+            if (key?.name === "escape") {
+                state = clearFilter(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "up") {
+                state = moveCursorUp(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "down") {
+                state = moveCursorDown(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "space" || str === " ") {
+                state = toggleSelection(state);
+                render(state);
+                return;
+            }
+            if (key?.name === "return" || key?.name === "enter") {
+                cleanup();
+                void installSelected(state, repositoryPath, force).then((exitCode) => resolve(exitCode));
+                return;
+            }
+            if (key?.name === "backspace") {
+                state = applyFilter(state, state.filter.slice(0, -1));
+                render(state);
+                return;
+            }
+            if (str !== undefined &&
+                str.length === 1 &&
+                str >= " " &&
+                str <= "~" &&
+                !key?.ctrl &&
+                !key?.meta) {
+                state = applyFilter(state, state.filter + str);
+                render(state);
+            }
+        };
+        function cleanup() {
+            process.stdin.setRawMode(false);
+            process.stdin.pause();
+            process.stdout.write(`${ANSI.showCursor}${ANSI.reset}`);
+            process.stdin.removeListener("keypress", onKeypress);
+        }
+        process.stdin.on("keypress", onKeypress);
+    });
+}
+async function installSelected(state, repositoryPath, force) {
+    const items = getItemsToInstall(state, force);
+    const routes = items.filter((entry) => entry.kind === "route");
+    const templates = items.filter((entry) => entry.kind === "template");
+    const allConflicts = [];
+    const allInstalled = [];
+    if (routes.length > 0) {
+        const result = await installCatalog(repositoryPath, { force });
+        allConflicts.push(...result.conflicts);
+        allInstalled.push(...result.installed);
+    }
+    else {
+        const result = await installMandatoryFiles(repositoryPath, { force });
+        allConflicts.push(...result.conflicts);
+        allInstalled.push(...result.installed);
+    }
+    for (const template of templates) {
+        if (!isTemplateName(template.name))
+            continue;
+        const result = await installTemplate(repositoryPath, template.name, { force });
+        allConflicts.push(...result.conflicts);
+        allInstalled.push(...result.installed);
+    }
+    if (allConflicts.length > 0 && !force) {
+        console.error(`Conflicts found. Re-run with --force to overwrite:\n${allConflicts.join("\n")}`);
+        return 1;
+    }
+    if (allInstalled.length > 0) {
+        console.log(`Installed ${allInstalled.length} item(s):`);
+        for (const file of allInstalled) {
+            console.log(`  ${file}`);
+        }
+    }
+    else {
+        console.log("All selected items are already installed.");
+    }
+    return 0;
+}

package/dist/tui.test.d.ts

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

package/dist/tui.test.js

@@ -0,0 +1,246 @@
+import { describe, expect, it } from "vitest";
+import { applyFilter, cancelSelection, clearFilter, createSelectionState, filterItems, fuzzyMatch, getItemsToInstall, moveCursorDown, moveCursorUp, submitSelection, toggleSelection, } from "./tui.js";
+function makeEntry(name, kind, installed = false) {
+    return {
+        kind,
+        name,
+        description: `${name} description`,
+        file: `${name}.md`,
+        installed,
+    };
+}
+function makeEntries(installed = []) {
+    const routes = ["refine", "implement", "direct", "apply-review", "merge-gate", "audit", "propose"];
+    const templates = ["agentics-checks", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "opencode.ci.json"];
+    return [
+        ...routes.map((name) => makeEntry(name, "route", installed.includes(name))),
+        ...templates.map((name) => makeEntry(name, "template", installed.includes(name))),
+    ];
+}
+describe("createSelectionState", () => {
+    it("returns all items as visible initially", () => {
+        const entries = makeEntries();
+        const state = createSelectionState(entries);
+        expect(state.allItems).toHaveLength(12);
+        expect(state.visibleItems).toHaveLength(12);
+    });
+    it("pre-selects installed items", () => {
+        const entries = makeEntries(["refine", "agentics-checks"]);
+        const state = createSelectionState(entries);
+        expect(state.selected.has("refine")).toBe(true);
+        expect(state.selected.has("agentics-checks")).toBe(true);
+        expect(state.selected.has("implement")).toBe(false);
+    });
+    it("starts with no filter and cursor at 0", () => {
+        const state = createSelectionState(makeEntries());
+        expect(state.filter).toBe("");
+        expect(state.cursor).toBe(0);
+        expect(state.status).toBe("selecting");
+    });
+    it("pre-selects nothing when nothing is installed", () => {
+        const state = createSelectionState(makeEntries());
+        expect(state.selected.size).toBe(0);
+    });
+});
+describe("fuzzyMatch", () => {
+    it("returns true for empty query", () => {
+        expect(fuzzyMatch("anything", "")).toBe(true);
+    });
+    it("matches exact string", () => {
+        expect(fuzzyMatch("refine", "refine")).toBe(true);
+    });
+    it("matches subsequence characters", () => {
+        expect(fuzzyMatch("refine", "rfe")).toBe(true);
+    });
+    it("matches non-contiguous characters", () => {
+        expect(fuzzyMatch("app-ci-dotnet-next", "acdn")).toBe(true);
+    });
+    it("is case-insensitive", () => {
+        expect(fuzzyMatch("Refine", "REFINE")).toBe(true);
+        expect(fuzzyMatch("REFINE", "refine")).toBe(true);
+    });
+    it("returns false when characters are not in order", () => {
+        expect(fuzzyMatch("refine", "efinr")).toBe(false);
+    });
+    it("returns false when query has characters not in text", () => {
+        expect(fuzzyMatch("refine", "xyz")).toBe(false);
+    });
+    it("matches against full name + description with combined filter", () => {
+        const text = "agentics-checks Agentics checks: verifies generated agent lockfiles";
+        expect(fuzzyMatch(text, "acch")).toBe(true);
+    });
+});
+describe("filterItems", () => {
+    const entries = makeEntries();
+    it("returns all items when filter is empty", () => {
+        expect(filterItems(entries, "")).toHaveLength(12);
+    });
+    it("filters by name", () => {
+        const result = filterItems(entries, "refine");
+        expect(result).toHaveLength(1);
+        expect(result[0].name).toBe("refine");
+    });
+    it("filters by description", () => {
+        const result = filterItems(entries, "description");
+        expect(result).toHaveLength(12);
+    });
+    it("filters by fuzzy subsequence over name and description", () => {
+        const result = filterItems(entries, "acdn");
+        const names = result.map((e) => e.name);
+        expect(names).toContain("app-ci-dotnet-next");
+    });
+    it("returns empty when nothing matches", () => {
+        expect(filterItems(entries, "zzzzz")).toHaveLength(0);
+    });
+});
+describe("applyFilter", () => {
+    it("updates the filter and visibleItems", () => {
+        const state = createSelectionState(makeEntries());
+        const next = applyFilter(state, "refine");
+        expect(next.filter).toBe("refine");
+        expect(next.visibleItems.length).toBe(1);
+        expect(next.visibleItems[0].name).toBe("refine");
+    });
+    it("clamps cursor when result shrinks", () => {
+        const entries = makeEntries();
+        let state = createSelectionState(entries);
+        state = { ...state, cursor: 10 };
+        state = applyFilter(state, "ci");
+        expect(state.cursor).toBeLessThanOrEqual(Math.max(0, state.visibleItems.length - 1));
+        expect(state.cursor).toBeLessThan(state.visibleItems.length);
+    });
+    it("sets cursor to 0 when no results match", () => {
+        const state = applyFilter(createSelectionState(makeEntries()), "zzz");
+        expect(state.visibleItems).toHaveLength(0);
+        expect(state.cursor).toBe(0);
+    });
+    it("preserves selected set when filtering", () => {
+        const entries = makeEntries(["refine"]);
+        const state = applyFilter(createSelectionState(entries), "ref");
+        expect(state.selected.has("refine")).toBe(true);
+    });
+});
+describe("clearFilter", () => {
+    it("resets filter to empty and restores all items", () => {
+        let state = applyFilter(createSelectionState(makeEntries()), "ref");
+        state = clearFilter(state);
+        expect(state.filter).toBe("");
+        expect(state.visibleItems).toHaveLength(12);
+    });
+});
+describe("moveCursorUp / moveCursorDown", () => {
+    it("moves cursor down by one", () => {
+        const state = createSelectionState(makeEntries());
+        const next = moveCursorDown(state);
+        expect(next.cursor).toBe(1);
+    });
+    it("wraps cursor to top from bottom", () => {
+        const entries = makeEntries();
+        let state = createSelectionState(entries);
+        state = { ...state, cursor: entries.length - 1 };
+        state = moveCursorDown(state);
+        expect(state.cursor).toBe(0);
+    });
+    it("moves cursor up by one", () => {
+        const entries = makeEntries();
+        let state = createSelectionState(entries);
+        state = { ...state, cursor: 3 };
+        state = moveCursorUp(state);
+        expect(state.cursor).toBe(2);
+    });
+    it("wraps cursor to bottom from top", () => {
+        const state = moveCursorUp(createSelectionState(makeEntries()));
+        expect(state.cursor).toBe(11);
+    });
+    it("does not move when list is empty", () => {
+        const entries = [];
+        const state = createSelectionState(entries);
+        expect(moveCursorUp(state).cursor).toBe(0);
+        expect(moveCursorDown(state).cursor).toBe(0);
+    });
+    it("navigates within filtered results", () => {
+        let state = createSelectionState(makeEntries());
+        state = applyFilter(state, "ci");
+        state = moveCursorDown(state);
+        expect(state.cursor).toBe(1);
+        expect(state.cursor).toBeLessThan(state.visibleItems.length);
+    });
+});
+describe("toggleSelection", () => {
+    it("selects an unselected item at cursor", () => {
+        const state = createSelectionState(makeEntries());
+        expect(state.selected.has("refine")).toBe(false);
+        const next = toggleSelection(state);
+        expect(next.selected.has("refine")).toBe(true);
+    });
+    it("deselects a selected item at cursor", () => {
+        const entries = makeEntries(["refine"]);
+        const state = createSelectionState(entries);
+        expect(state.selected.has("refine")).toBe(true);
+        const next = toggleSelection(state);
+        expect(next.selected.has("refine")).toBe(false);
+    });
+    it("toggles the item at cursor position within filtered list", () => {
+        let state = createSelectionState(makeEntries());
+        state = applyFilter(state, "ci");
+        state = moveCursorDown(state);
+        const entryAtCursor = state.visibleItems[state.cursor];
+        const next = toggleSelection(state);
+        expect(next.selected.has(entryAtCursor.name)).toBe(true);
+    });
+    it("does nothing when list is empty", () => {
+        const state = createSelectionState([]);
+        const next = toggleSelection(state);
+        expect(next.selected.size).toBe(0);
+    });
+    it("does not change other selections", () => {
+        const entries = makeEntries(["refine", "audit"]);
+        const state = createSelectionState(entries);
+        const next = toggleSelection(state);
+        expect(next.selected.has("refine")).toBe(false);
+        expect(next.selected.has("audit")).toBe(true);
+    });
+});
+describe("submitSelection / cancelSelection", () => {
+    it("sets status to submitting", () => {
+        const state = submitSelection(createSelectionState(makeEntries()));
+        expect(state.status).toBe("submitting");
+    });
+    it("sets status to cancelled", () => {
+        const state = cancelSelection(createSelectionState(makeEntries()));
+        expect(state.status).toBe("cancelled");
+    });
+});
+describe("getItemsToInstall", () => {
+    it("returns empty when nothing is selected", () => {
+        const state = createSelectionState(makeEntries());
+        expect(getItemsToInstall(state)).toHaveLength(0);
+    });
+    it("returns only selected items that are not already installed", () => {
+        const entries = makeEntries(["refine"]);
+        let state = createSelectionState(entries);
+        state = { ...state, cursor: 1 };
+        state = toggleSelection(state);
+        const items = getItemsToInstall(state);
+        const names = items.map((e) => e.name);
+        expect(names).toContain("implement");
+        expect(names).not.toContain("refine");
+    });
+    it("returns already-installed items when force is true", () => {
+        const entries = makeEntries(["refine"]);
+        let state = createSelectionState(entries);
+        const items = getItemsToInstall(state, true);
+        const names = items.map((e) => e.name);
+        expect(names).toContain("refine");
+    });
+    it("includes both routes and templates", () => {
+        let state = createSelectionState(makeEntries());
+        state = toggleSelection(state);
+        state = { ...state, cursor: 7 };
+        state = toggleSelection(state);
+        const items = getItemsToInstall(state);
+        const kinds = items.map((e) => e.kind);
+        expect(kinds).toContain("route");
+        expect(kinds).toContain("template");
+    });
+});

package/dist/workflow-catalog.d.ts

@@ -7,7 +7,12 @@ export interface WorkflowRoute {
     readonly defaultEnabled: boolean;
 }
 export declare const workflowRoutes: readonly WorkflowRoute[];
-export declare const packageOwnedTargets: readonly [".github/actions", ".github/workflows/agent-*.md", ".github/workflows/shared/platform-defaults.md", ".github/workflows/shared/opencode-ci.md", ".github/workflows/work-router.yml", "scripts/compile-agent-workflows.mjs"];
+export declare const packageOwnedTargets: readonly [".github/actions", ".github/workflows/agent-*.md", ".github/workflows/shared/platform-defaults.md", ".github/workflows/shared/opencode-ci.md", ".github/workflows/work-router.yml", "scripts/compile-agent-workflows.mjs", "opencode.ci.json"];
+export interface MandatoryFile {
+    readonly source: string;
+    readonly target: string;
+}
+export declare const mandatoryFiles: readonly MandatoryFile[];
 export declare const generatedConsumerTargets: readonly [".github/workflows/agent-*.lock.yml", ".github/aw/actions-lock.json"];
 export declare const templateNames: readonly ["agentics-checks", "agentics-maintenance", "app-ci-dotnet-next", "app-ci-node-monorepo", "opencode.ci.json"];
 export type TemplateName = (typeof templateNames)[number];

package/dist/workflow-catalog.js

@@ -23,6 +23,11 @@ export const packageOwnedTargets = [
     ".github/workflows/shared/opencode-ci.md",
     ".github/workflows/work-router.yml",
     "scripts/compile-agent-workflows.mjs",
+    "opencode.ci.json",
+];
+export const mandatoryFiles = [
+    { source: "templates/opencode/opencode.ci.json", target: "opencode.ci.json" },
+    { source: "scripts/compile-agent-workflows.mjs", target: "scripts/compile-agent-workflows.mjs" },
 ];
 export const generatedConsumerTargets = [
     ".github/workflows/agent-*.lock.yml",

package/loops/scripts/compile-agent-workflows.mjs

@@ -1,29 +1,29 @@
-// Managed by @plainconceptsplatform/workflows. Source: loops/scripts/compile-agent-workflows.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
-import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
-
-const workflowDirectory = existsSync("loops/workflows") ? "loops/workflows" : ".github/workflows";
-
-// On Windows, `gh` resolves to a shim that spawnSync cannot find without a shell.
-// Resolve the full path via `where` so spawnSync works with shell: false (security-safe).
-function resolveGhPath() {
-  if (process.platform !== "win32") return "gh";
-  const result = spawnSync("where", ["gh"], { encoding: "utf8", shell: false });
-  if (result.status === 0) {
-    const first = result.stdout.split("\n").map((s) => s.trim()).find(Boolean);
-    if (first) return first;
-  }
-  return "gh";
-}
-
-const compile = spawnSync(resolveGhPath(), ["aw", "compile", "--strict", "--dir", workflowDirectory], {
-  stdio: "inherit",
-  shell: false,
-});
-
-if (compile.error?.code === "ENOENT" || compile.status === null) {
-  process.stderr.write("Could not run `gh aw compile`. Install githubnext/gh-aw first.\n");
-  process.exit(1);
-}
-
-process.exit(compile.status ?? 1);
+// Managed by @plainconceptsplatform/workflows. Source: loops/scripts/compile-agent-workflows.mjs. Update with `workflows update --force`; consumer edits may be overwritten.
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+
+const workflowDirectory = existsSync("loops/workflows") ? "loops/workflows" : ".github/workflows";
+
+// On Windows, `gh` resolves to a shim that spawnSync cannot find without a shell.
+// Resolve the full path via `where` so spawnSync works with shell: false (security-safe).
+function resolveGhPath() {
+  if (process.platform !== "win32") return "gh";
+  const result = spawnSync("where", ["gh"], { encoding: "utf8", shell: false });
+  if (result.status === 0) {
+    const first = result.stdout.split("\n").map((s) => s.trim()).find(Boolean);
+    if (first) return first;
+  }
+  return "gh";
+}
+
+const compile = spawnSync(resolveGhPath(), ["aw", "compile", "--strict", "--dir", workflowDirectory], {
+  stdio: "inherit",
+  shell: false,
+});
+
+if (compile.error?.code === "ENOENT" || compile.status === null) {
+  process.stderr.write("Could not run `gh aw compile`. Install githubnext/gh-aw first.\n");
+  process.exit(1);
+}
+
+process.exit(compile.status ?? 1);

package/loops/workflows/shared/opencode-ci.md

@@ -5,23 +5,126 @@ env:
   CODEGRAPH_VERSION: "1.5.0"
   RTK_VERSION: "0.44.1"
   RTK_SHA256: "986f29704469b3d1051e2474105c6c75ab8b73651068dcd61612c1fb3938ad95"
-description: Shared CI setup for Platform agent workflows.
+description: |
+  Shared CI setup for Platform agent workflows. Installs pinned tooling and merges
+  opencode.ci.json into opencode.jsonc so the CI agent gets its provider and model config.
+
+  Consumer-specific steps (NuGet, .NET restore, OpenSpec, etc.) should be added after the
+  shared baseline in the consumer copy. The merge step below is package-owned and required
+  for the agent to resolve the `plainconcepts` provider and its models.
 
 pre-agent-steps:
   - name: Create agent scratch directory
     run: mkdir -p .opencode/.tmp
+
+  - name: Install ripgrep
+    run: |
+      set -euo pipefail
+
+      if ! command -v rg > /dev/null; then
+        sudo apt-get update
+        sudo apt-get install --yes ripgrep
+      fi
+
+      rg --version
+
   - name: Activate the pnpm version package.json pins
     run: |
       set -euo pipefail
       corepack enable
       corepack prepare --activate
       pnpm --version
+
   - name: Cache the pnpm store
     uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
     with:
       path: ~/.local/share/pnpm/store
       key: pnpm-store-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
       restore-keys: pnpm-store-${{ runner.os }}-
+
+  - name: Install RTK
+    run: |
+      set -euo pipefail
+
+      tarball="$RUNNER_TEMP/rtk.tar.gz"
+      curl -fsSL -o "$tarball" \
+        "https://github.com/rtk-ai/rtk/releases/download/v${RTK_VERSION}/rtk-x86_64-unknown-linux-musl.tar.gz"
+      echo "${RTK_SHA256}  $tarball" | sha256sum --check --strict
+
+      tar -xzf "$tarball" -C "$RUNNER_TEMP"
+      sudo install -m 0755 "$RUNNER_TEMP/rtk" /usr/local/bin/rtk
+
+      rtk --version
+      rtk init -g --opencode --auto-patch
+
+  - name: Install agentmemory
+    run: |
+      set -euo pipefail
+      npm install -g "@agentmemory/agentmemory@${AGENTMEMORY_VERSION}"
+      agentmemory --version
+
+  - name: Install codegraph and index the repository
+    continue-on-error: true
+    run: |
+      set -euo pipefail
+      npm install -g "@colbymchenry/codegraph@${CODEGRAPH_VERSION}"
+      codegraph init
+
+  - name: Install opencode plugin dependencies
+    run: |
+      set -euo pipefail
+
+      if [ ! -f .opencode/package.json ]; then
+        echo "No .opencode/package.json, nothing to install"
+        exit 0
+      fi
+
+      # These plugins are optional tooling for the agent, not something the task
+      # depends on, so a transitive peer conflict between two of them must not
+      # take down every audit, propose and implement run. Strict first, so a real
+      # incompatibility is still visible in the log.
+      if ! npm install --prefix .opencode; then
+        echo "::warning::Strict npm install failed on a peer conflict. Retrying with --legacy-peer-deps; check .opencode/package.json."
+        npm install --prefix .opencode --legacy-peer-deps
+      fi
+
   - name: Install workspace dependencies
     run: pnpm install --frozen-lockfile
+
+  - name: Merge the CI-only OpenCode provider into opencode.jsonc
+    run: |
+      set -euo pipefail
+
+      CONFIG=opencode.jsonc
+      FRAGMENT=opencode.ci.json
+
+      [ -f "$FRAGMENT" ] || { echo "::error::$FRAGMENT is missing from the checkout"; exit 1; }
+
+      # Pure JSON on purpose, not JSONC: jq cannot parse `//` comments, and a naive
+      # comment-stripper would corrupt the `http://` inside the provider's api URL.
+      jq -e . "$FRAGMENT" > /dev/null \
+        || { echo "::error::$FRAGMENT is not valid JSON. Comments are not allowed in it."; exit 1; }
+
+      # Despite the .jsonc name, this file is committed in this repository and is read by
+      # jq below, so it must contain no comments. A single `//` line fails the merge with
+      # "Invalid numeric literal", which names neither the file nor the reason.
+      if [ -f "$CONFIG" ] && ! jq -e . "$CONFIG" > /dev/null 2>&1; then
+        echo "::error::$CONFIG is tracked and must be comment-free JSON: jq cannot parse it."
+        exit 1
+      fi
+
+      # opencode.jsonc is untracked in most repositories, so it usually does not exist here.
+      # Create it from the fragment when absent, merge when a checkout did provide one.
+      if [ -f "$CONFIG" ]; then
+        merged=$(jq -s '.[0] * .[1]' "$CONFIG" "$FRAGMENT")
+      else
+        merged=$(jq -S . "$FRAGMENT")
+      fi
+      printf '%s\n' "$merged" > "$CONFIG"
+
+      # gh-aw's own "Write OpenCode Config" step runs next and merges its base config with
+      # `$existing * $base`. Base wins on conflicting keys, but it defines neither `model`
+      # nor this provider, so both survive and `awf-proxy` is added alongside.
+      echo "Wrote $CONFIG from $FRAGMENT:"
+      jq -r '"  model: \(.model // "unset")", "  plugins: \(.plugin // [] | join(", "))", "  providers: \(.provider // {} | keys | join(", "))"' "$CONFIG"
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",