@cubis/foundry 0.3.83 → 0.3.84

package/README.md

@@ -2,7 +2,7 @@
 
 Workflow-first installer for multi-platform AI agent environments.
 
-Last updated: 2026-03-04.
+Last updated: 2026-03-17.
 
 `cbx` installs workflows, skills, wrappers, and rule files for:
 
@@ -25,6 +25,8 @@ Skill install default is profile-based:
 - [What This CLI Manages](#what-this-cli-manages)
 - [Install](#install)
 - [Guided Init Wizard (`cbx init`)](#guided-init-wizard-cbx-init)
+- [What `cbx init` Generates](#what-cbx-init-generates)
+- [Build Flows](#build-flows)
 - [Quickstarts](#quickstarts)
 - [Scope Model (Global vs Project)](#scope-model-global-vs-project)
 - [Credential Model (Metadata + Machine Vault)](#credential-model-metadata--machine-vault)
@@ -56,6 +58,7 @@ Source of truth inside this repo:
 
 - `workflows/skills/<id>` is the canonical source for skill packages.
 - `workflows/workflows/agent-environment-setup/shared/{agents,workflows}` is the canonical source for custom agents and workflows.
+- `scripts/lib/platform-parity.mjs` is the canonical source for the cross-platform parity registry, audited upstream references, and per-platform capability contracts.
 - `workflows/workflows/agent-environment-setup/platforms/*` contains generated platform adapters and mirrors, not the authoring source.
 - Active generated skill mirrors are maintained for `codex`, `antigravity`, `copilot`, `claude`, and `gemini`.
 - Any leftover `cursor` or `windsurf` folders under `platforms/*` should be treated as legacy artifacts, not active CLI targets.
@@ -130,6 +133,164 @@ Detailed wizard behavior and platform matrix:
 
 - `docs/cli-init-wizard.md`
 
+## What `cbx init` Generates
+
+`cbx init` is a guided wrapper around `cbx workflows install`. It does not generate repo source files inside Foundry itself. It generates install artifacts in the target workspace for each selected runtime.
+
+Step by step:
+
+1. Collect selections for bundle, platforms, skill profile, MCP integrations, and MCP runtime.
+2. Map those answers into the shared install engine used by `cbx workflows install`.
+3. Apply each selected platform sequentially. If one platform fails, init stops on that failure.
+4. Write platform runtime artifacts into the workspace-oriented install targets.
+5. Persist non-secret metadata into `cbx_config.json` and machine-scoped secrets into `~/.cbx/credentials.env` when keys were supplied.
+6. Patch the selected platform MCP runtime config when `cubis-foundry`, `postman`, `stitch`, or `playwright` is enabled.
+
+What gets written per selected platform:
+
+- `codex`
+  - `<workspace>/AGENTS.md`
+  - `<workspace>/.codex/agents/*`
+  - `<workspace>/.agents/skills/*`
+  - `<workspace>/.vscode/mcp.json` when MCP is enabled
+- `antigravity`
+  - `<workspace>/.agents/rules/GEMINI.md`
+  - `<workspace>/.agents/skills/*`
+  - `<workspace>/.gemini/commands/*`
+  - `<workspace>/.gemini/settings.json` when MCP is enabled
+- `copilot`
+  - `<workspace>/AGENTS.md`
+  - `<workspace>/.github/copilot-instructions.md`
+  - `<workspace>/.github/agents/*`
+  - `<workspace>/.github/skills/*`
+  - `<workspace>/.github/prompts/*`
+  - `<workspace>/.vscode/mcp.json` when MCP is enabled
+- `claude`
+  - `<workspace>/CLAUDE.md`
+  - `<workspace>/.claude/agents/*`
+  - `<workspace>/.claude/skills/*`
+  - `<workspace>/.claude/hooks/*`
+  - `<workspace>/.mcp.json` when MCP is enabled
+- `gemini`
+  - `<workspace>/.gemini/GEMINI.md`
+  - `<workspace>/.gemini/commands/*`
+  - `<workspace>/.gemini/settings.json` when MCP is enabled
+
+Also generated during init when applicable:
+
+- `<workspace>/cbx_config.json` for non-secret Foundry metadata
+- `~/.cbx/credentials.env` for persisted machine-local secrets
+- Workspace engineering files managed by the selected bundle, if that bundle includes them
+
+Important:
+
+- `cbx init --dry-run` shows the plan and writes nothing.
+- Init uses workspace-oriented behavior even if legacy scope flags are passed for compatibility.
+- No raw API keys are written into runtime config files or generated workspace artifacts.
+
+## Build Flows
+
+There are three different “build” paths in this repo. They generate different things.
+
+### 1. `cbx build architecture`
+
+This is the end-user build helper for project foundation docs.
+
+```bash
+cbx build architecture --platform codex
+```
+
+Step by step:
+
+1. Probe the selected runtime surface (`codex`, `claude`, `gemini`, or `copilot`).
+2. Inspect the repository and current foundation docs.
+3. Generate or refresh the managed foundation document set under `docs/foundation/`.
+4. Update ADR scaffolding used by the architecture workflow.
+
+Files generated or refreshed:
+
+- `docs/foundation/MEMORY.md`
+- `docs/foundation/PRODUCT.md`
+- `docs/foundation/ARCHITECTURE.md`
+- `docs/foundation/TECH.md`
+- `docs/foundation/memory/domain.md`
+- `docs/foundation/memory/runtime.md`
+- `docs/foundation/memory/integrations.md`
+- `docs/foundation/memory/debugging.md`
+- `docs/foundation/adr/README.md`
+- `docs/foundation/adr/0000-template.md`
+
+Use `--dry-run` to preview the planned invocation and `--check` to detect drift without writing.
+
+### 2. `npm run build:cli`
+
+This is the maintainer TypeScript compile step for the CLI itself.
+
+```bash
+npm run build:cli
+```
+
+What it generates:
+
+- compiled CLI output under `dist/cli/*`
+
+What it does not generate:
+
+- no platform mirrors
+- no workflow/skill adapters
+- no parity docs
+- no MCP manifest
+
+### 3. `npm run generate:all`
+
+This is the maintainer asset-generation pipeline for the Foundry repo.
+
+```bash
+npm run generate:all
+```
+
+Step by step:
+
+1. `npm run generate:platform-assets`
+   - regenerates `workflows/workflows/agent-environment-setup/platforms/*`
+   - refreshes the bundle manifest at `workflows/workflows/agent-environment-setup/manifest.json`
+     - keeps a compact parity summary and artifact pointers instead of embedding the full registry inline
+   - refreshes parity JSON:
+     - `workflows/workflows/agent-environment-setup/generated/pattern-registry.json`
+     - `workflows/workflows/agent-environment-setup/generated/platform-capabilities.json`
+     - `workflows/workflows/agent-environment-setup/generated/upstream-capability-audit.json`
+   - refreshes parity docs:
+     - `docs/platform-support-matrix.md`
+     - `docs/cross-platform-pattern-catalog.md`
+     - `docs/platform-capability-details.md`
+2. `npm run sync:skill-mirrors`
+   - syncs generated skill mirrors into active platform adapters
+3. `npm run generate:skills-index`
+   - refreshes:
+     - `workflows/skills/skills_index.json`
+     - `workflows/workflows/agent-environment-setup/platforms/claude/skills/skills_index.json`
+     - `workflows/workflows/agent-environment-setup/platforms/copilot/skills/skills_index.json`
+4. `npm run generate:skill-catalog`
+   - refreshes:
+     - `workflows/skills/generated/skill-catalog.json`
+     - `workflows/skills/generated/skill-audit.json`
+5. `npm run generate:mcp-manifest`
+   - refreshes:
+     - `mcp/generated/mcp-manifest.json`
+6. `npm run inject:mcp-rules:all`
+   - updates the managed MCP blocks in:
+     - `workflows/workflows/agent-environment-setup/platforms/codex/rules/AGENTS.md`
+     - `workflows/workflows/agent-environment-setup/platforms/antigravity/rules/GEMINI.md`
+     - `workflows/workflows/agent-environment-setup/platforms/gemini/rules/GEMINI.md`
+     - `workflows/workflows/agent-environment-setup/platforms/copilot/rules/copilot-instructions.md`
+     - `workflows/workflows/agent-environment-setup/platforms/claude/rules/CLAUDE.md`
+
+Recommended maintainer loop:
+
+1. Edit canonical sources under `workflows/skills/*` and `workflows/workflows/agent-environment-setup/shared/*`.
+2. Run `npm run generate:all`.
+3. Run `npm run test:ci`.
+
 ## Quickstarts
 
 ### Codex (recommended baseline)
@@ -489,6 +650,8 @@ Generated MCP artifacts:
 
 - `mcp/generated/mcp-manifest.json` (catalog snapshot used by managed rule blocks)
 - `mcp/generated/README.md` (artifact notes)
+- `workflows/workflows/agent-environment-setup/generated/{pattern-registry,platform-capabilities,upstream-capability-audit}.json`
+- `docs/{platform-support-matrix,cross-platform-pattern-catalog,platform-capability-details}.md`
 
 Foundry local serve command (canonical entrypoint for MCP client registration):
 

package/dist/cli/build/commands.js

@@ -16,4 +16,3 @@ export function registerBuildCommands(program, deps) {
         buildCommand.help();
     });
 }
-//# sourceMappingURL=commands.js.map

package/dist/cli/build/foundation.js

@@ -0,0 +1,134 @@
+import path from "node:path";
+export const FOUNDATION_DOCS_DIR = path.join("docs", "foundation");
+export const FOUNDATION_ADR_DIR = path.join(FOUNDATION_DOCS_DIR, "adr");
+export const FOUNDATION_MEMORY_DIR = path.join(FOUNDATION_DOCS_DIR, "memory");
+export const FOUNDATION_DESIGN_DIR = path.join(FOUNDATION_DOCS_DIR, "design");
+export const ARCHITECTURE_BUILD_PLATFORM_CAPABILITIES = {
+    antigravity: "You are generating repo-shared foundation docs for Antigravity. Use the Gemini-family CLI surface available in this environment and optimize the docs for `.agents/rules/GEMINI.md` plus command-driven workflows.",
+    codex: "You can read, write, and execute shell commands. Use `codex exec` mode.",
+    claude: "You can read, write files, and run bash commands. Use non-interactive mode.",
+    gemini: "You can read, write files, and run commands within your sandbox. Follow Gemini CLI conventions.",
+    copilot: "You can read, write files, and use terminal commands. Follow Copilot agent conventions.",
+};
+export function buildProductBuildSkeleton() {
+    return [
+        "# Product",
+        "",
+        "This file is managed by `cbx build architecture`.",
+        "",
+        "<!-- cbx:product:foundation:start version=1 profile=uninitialized -->",
+        "Replace this managed section by running `cbx build architecture --platform <antigravity|codex|claude|gemini|copilot>`.",
+        "<!-- cbx:product:foundation:end -->",
+        "",
+    ].join("\n");
+}
+export function buildArchitectureBuildSkeleton() {
+    return [
+        "# Architecture",
+        "",
+        "This file is managed by `cbx build architecture`.",
+        "",
+        "<!-- cbx:architecture:doc:start version=1 profile=uninitialized -->",
+        "Replace this managed section by running `cbx build architecture --platform <antigravity|codex|claude|gemini|copilot>`.",
+        "<!-- cbx:architecture:doc:end -->",
+        "",
+    ].join("\n");
+}
+export function buildTechBuildSkeleton() {
+    return [
+        "# TECH.md",
+        "",
+        "This file is managed by `cbx build architecture`.",
+        "",
+        "<!-- cbx:architecture:tech:start version=1 snapshot=uninitialized -->",
+        "Replace this managed section by running `cbx build architecture --platform <antigravity|codex|claude|gemini|copilot>`.",
+        "<!-- cbx:architecture:tech:end -->",
+        "",
+    ].join("\n");
+}
+export function buildMemoryBuildSkeleton() {
+    return [
+        "# Memory",
+        "",
+        "This file is managed by `cbx build architecture` as the durable AI entrypoint for the project.",
+        "",
+        "<!-- cbx:memory:index:start version=1 profile=uninitialized -->",
+        "Replace this managed section by running `cbx build architecture --platform <antigravity|codex|claude|gemini|copilot>`.",
+        "<!-- cbx:memory:index:end -->",
+        "",
+    ].join("\n");
+}
+export function buildDesignBuildSkeleton() {
+    return [
+        "# Design",
+        "",
+        "This file is managed by `cbx build architecture` as the durable design-system backbone for UI, Stitch, and mobile work.",
+        "",
+        "<!-- cbx:design:foundation:start version=1 profile=uninitialized -->",
+        "Replace this managed section by running `cbx build architecture --platform <antigravity|codex|claude|gemini|copilot>`.",
+        "<!-- cbx:design:foundation:end -->",
+        "",
+    ].join("\n");
+}
+export function buildMemoryTopicSkeleton(title, topicId) {
+    return [
+        `# ${title}`,
+        "",
+        "This file is managed by `cbx build architecture`.",
+        "",
+        `<!-- cbx:memory:topic:start version=1 topic=${topicId} profile=uninitialized -->`,
+        "Replace this managed section by running `cbx build architecture`.",
+        "<!-- cbx:memory:topic:end -->",
+        "",
+    ].join("\n");
+}
+export function buildAdrReadme() {
+    return [
+        "# Architecture Decision Records",
+        "",
+        "Use this directory for durable decisions that future contributors and agents need to preserve.",
+        "",
+        "## When to add an ADR",
+        "",
+        "- Architecture style or boundary changes",
+        "- Data model or persistence strategy changes",
+        "- Deployment or scaling model changes",
+        "- Design-system ownership or shared UX pattern changes",
+        "",
+        "## Suggested format",
+        "",
+        "1. Context",
+        "2. Decision",
+        "3. Consequences",
+        "4. Validation",
+        "",
+        "Start with `0000-template.md` and create numbered follow-up ADRs for accepted decisions.",
+        "",
+    ].join("\n");
+}
+export function buildAdrTemplate() {
+    return [
+        "# ADR 0000: Title",
+        "",
+        "## Status",
+        "",
+        "Proposed",
+        "",
+        "## Context",
+        "",
+        "- What problem or pressure led to this decision?",
+        "",
+        "## Decision",
+        "",
+        "- What is the chosen direction?",
+        "",
+        "## Consequences",
+        "",
+        "- What tradeoffs, benefits, or costs follow from this choice?",
+        "",
+        "## Validation",
+        "",
+        "- How will the team know this decision is working?",
+        "",
+    ].join("\n");
+}

package/dist/cli/commands/register.js

@@ -3,6 +3,8 @@ import { registerWorkflowCommands } from "../workflows/commands.js";
 import { registerMcpCommands } from "../mcp/commands.js";
 import { registerRulesCommands } from "../rules/commands.js";
 import { registerBuildCommands } from "../build/commands.js";
+import { registerMobileCommands } from "../mobile/commands.js";
+import { registerWebCommands } from "../web/commands.js";
 export function registerCommands(deps) {
     const program = new Command();
     program
@@ -11,17 +13,23 @@ export function registerCommands(deps) {
         .version(deps.cliVersion);
     program
         .command("init")
-        .description("Run guided interactive install wizard")
+        .description("Bootstrap a secure AI workspace and harness in the current project")
         .option("-y, --yes", "accept defaults and apply without confirmation")
         .option("--dry-run", "preview wizard execution without writing files")
         .option("--overwrite", "overwrite existing files where supported")
         .option("--target <path>", "run against target project directory")
         .option("--bundle <bundleId>", "workflow bundle id")
+        .option("--stack <stack>", "workspace stack: web|api|cli|mobile|ml|fullstack|monorepo")
+        .option("--profile <profile>", "workspace profile: core|developer|security|research|full")
+        .option("--template <template>", "optional organization template name")
+        .option("--authoring-ai <platform>", "AI used for context docs: codex|claude|gemini|copilot")
+        .option("--skip-context", "skip automatic context generation after install")
+        .option("--capability-packs <items>", "comma-separated packs: frontend,backend,database,devops,security,playwright,research,agentic")
         .option("--platforms <items>", "comma-separated platforms: codex,antigravity,copilot,claude,gemini")
-        .option("--skill-profile <profile>", "skills profile: core|web-backend|full")
+        .option("--skill-profile <profile>", "skills profile: core|web-backend|mobile-qa|full")
         .option("--skills-scope <scope>", "deprecated for init: installs are workspace-only")
         .option("--mcp-scope <scope>", "deprecated for init: MCP config installs in workspace scope")
-        .option("--mcps <items>", "comma-separated MCP selections: cubis-foundry,postman,stitch,playwright")
+        .option("--mcps <items>", "comma-separated MCP selections: cubis-foundry,postman,stitch,playwright,android")
         .option("--postman-mode <mode>", "Postman mode: full|minimal")
         .option("--postman-workspace-id <id|null>", "optional: set default Postman workspace ID (use 'null' for no default)")
         .option("--mcp-runtime <runtime>", "MCP runtime: docker|local")
@@ -29,6 +37,130 @@ export function registerCommands(deps) {
         .option("--no-banner", "skip init welcome banner")
         .option("--json", "print machine-readable final summary")
         .action(deps.runInitWizard);
+    program
+        .command("add <platform>")
+        .description("Add one platform projection to the current workspace")
+        .option("--target <path>", "target project directory")
+        .option("--overwrite", "overwrite existing managed files where supported")
+        .option("--dry-run", "preview without writing files")
+        .option("-y, --yes", "skip confirmation")
+        .action(deps.runWorkspaceAdd);
+    program
+        .command("sync [platform]")
+        .description("Detect drift and re-apply managed workspace assets")
+        .option("--target <path>", "target project directory")
+        .option("--check", "exit 1 if drift is detected")
+        .option("--overwrite", "overwrite managed files during sync")
+        .option("--dry-run", "preview sync without writing files")
+        .action(deps.runWorkspaceSync);
+    const contextCommand = program
+        .command("context")
+        .description("Generate and validate AI-readable workspace context docs");
+    contextCommand
+        .command("generate")
+        .description("Generate or refresh foundation docs and platform rules")
+        .option("--platform <platform>", "authoring AI: codex|claude|gemini|copilot")
+        .option("--research <mode>", "research mode: auto|always|never", "auto")
+        .option("--overwrite", "overwrite managed context scaffolding")
+        .option("--watch", "reserved for future watch mode")
+        .option("--dry-run", "preview generation invocation without writing files")
+        .option("--json", "output JSON")
+        .action(deps.runContextGenerate);
+    contextCommand
+        .command("diff")
+        .description("Show context freshness and drift against current code")
+        .option("--json", "output JSON")
+        .action(deps.runContextDiff);
+    contextCommand
+        .command("validate")
+        .description("Validate context completeness and freshness")
+        .option("--json", "output JSON")
+        .action(deps.runContextValidate);
+    contextCommand.action(() => {
+        contextCommand.help();
+    });
+    const harnessCommand = program
+        .command("harness")
+        .description("Inspect and manage workspace harness runtime state");
+    harnessCommand
+        .command("audit")
+        .description("Run deterministic harness security and safety audit")
+        .option("--scope <scope>", "repo|hooks|skills|commands|agents", "repo")
+        .option("--format <format>", "text|json", "text")
+        .action(deps.runHarnessAudit);
+    harnessCommand.action(() => {
+        harnessCommand.help();
+    });
+    const loopCommand = program
+        .command("loop")
+        .description("Manage bounded autonomous loop runs");
+    loopCommand
+        .command("start")
+        .description("Create a managed loop run with explicit criteria")
+        .requiredOption("--task <task>", "task description")
+        .requiredOption("--completion-criteria <text>", "completion criteria")
+        .option("--max-iterations <count>", "maximum iterations", "20")
+        .option("--platform <platform>", "execution platform")
+        .option("--validate-command <command>", "verification command to run between iterations")
+        .option("--dry-run", "preview without writing runtime state")
+        .action(deps.runLoopStart);
+    loopCommand
+        .command("status")
+        .description("Show current or recent loop runs")
+        .option("--id <id>", "specific loop run id")
+        .option("--json", "output JSON")
+        .action(deps.runLoopStatus);
+    loopCommand
+        .command("stop")
+        .description("Stop a managed loop run")
+        .requiredOption("--id <id>", "loop run id")
+        .option("--reason <text>", "stop reason", "stopped by operator")
+        .action(deps.runLoopStop);
+    loopCommand.action(() => {
+        loopCommand.help();
+    });
+    const memoryCommand = program
+        .command("memory")
+        .description("Review and apply staged continuous-learning artifacts");
+    memoryCommand
+        .command("review")
+        .description("List staged learning candidates")
+        .option("--json", "output JSON")
+        .action(deps.runMemoryReview);
+    memoryCommand
+        .command("apply")
+        .description("Apply a staged memory candidate to managed workspace memory")
+        .requiredOption("--id <id>", "candidate file id")
+        .option("--target <target>", "memory|context-pack|skill-note", "memory")
+        .action(deps.runMemoryApply);
+    memoryCommand
+        .command("prune")
+        .description("Remove stale staged learning candidates")
+        .option("--all", "remove all staged candidates")
+        .option("--id <id>", "remove a specific candidate")
+        .action(deps.runMemoryPrune);
+    memoryCommand.action(() => {
+        memoryCommand.help();
+    });
+    const profileCommand = program
+        .command("profile")
+        .description("Manage workspace harness safety profiles");
+    profileCommand
+        .command("set <profile>")
+        .description("Set hook/autonomy profile: minimal|standard|strict|autonomous")
+        .option("--target <path>", "target project directory")
+        .action(deps.runProfileSet);
+    profileCommand.action(() => {
+        profileCommand.help();
+    });
+    program
+        .command("upgrade")
+        .description("Upgrade managed workspace assets to the latest Foundry catalog")
+        .option("--platform <platform>", "upgrade only one platform")
+        .option("--dry-run", "preview upgrade without writing files")
+        .option("--check", "report upgrade drift and exit 1 when changes are needed")
+        .option("--changelog", "print managed areas that will be refreshed")
+        .action(deps.runWorkspaceUpgrade);
     registerWorkflowCommands(program, {
         printPlatforms: deps.printPlatforms,
         withInstallOptions: deps.withInstallOptions,
@@ -51,6 +183,9 @@ export function registerCommands(deps) {
         runMcpRuntimeUp: deps.runMcpRuntimeUp,
         runMcpRuntimeDown: deps.runMcpRuntimeDown,
         defaultMcpDockerContainerName: deps.defaultMcpDockerContainerName,
+        runMcpStatus: deps.runMcpStatus,
+        runMcpTest: deps.runMcpTest,
+        runMcpProxy: deps.runMcpProxy,
     });
     registerRulesCommands(program, {
         runRulesInit: deps.runRulesInit,
@@ -59,6 +194,12 @@ export function registerCommands(deps) {
     registerBuildCommands(program, {
         runBuildArchitecture: deps.runBuildArchitecture,
     });
+    registerMobileCommands(program, {
+        runMobileQa: deps.runMobileQa,
+    });
+    registerWebCommands(program, {
+        runWebQa: deps.runWebQa,
+    });
     const agentsCommand = program
         .command("agents")
         .description("Cubis Agent Bot commands");
@@ -90,4 +231,3 @@ export function registerCommands(deps) {
     });
     return program;
 }
-//# sourceMappingURL=register.js.map

package/dist/cli/config/index.js

@@ -1,2 +1 @@
-export {};
-//# sourceMappingURL=index.js.map
+export { expandUniquePaths, PLATFORM_IDS, WORKFLOW_PROFILES, resolveArtifactProfilePaths, resolveLegacySkillDirsForCleanup, resolveProfilePathCandidates, resolveProfilePaths, } from "./workflowProfiles.js";