@cubis/foundry 0.3.64 → 0.3.66

package/src/cli/init/prompts.ts

@@ -34,7 +34,11 @@ export async function promptInitPlatforms({
     message: "Select target platform(s):",
     required: true,
     choices: [
-      { name: "Codex", value: "codex", checked: defaultPlatforms.includes("codex") },
+      {
+        name: "Codex",
+        value: "codex",
+        checked: defaultPlatforms.includes("codex"),
+      },
       {
         name: "Antigravity",
         value: "antigravity",
@@ -45,11 +49,18 @@ export async function promptInitPlatforms({
         value: "copilot",
         checked: defaultPlatforms.includes("copilot"),
       },
+      {
+        name: "Claude Code",
+        value: "claude",
+        checked: defaultPlatforms.includes("claude"),
+      },
     ],
   });
 }
 
-export async function promptInitSkillProfile(defaultSkillProfile: InitSkillProfile) {
+export async function promptInitSkillProfile(
+  defaultSkillProfile: InitSkillProfile,
+) {
   return select<InitSkillProfile>({
     message: "Select skills install profile:",
     default: defaultSkillProfile,
@@ -70,8 +81,16 @@ export async function promptInitMcpSelection(defaultMcps: InitMcpId[]) {
         value: "cubis-foundry",
         checked: defaultMcps.includes("cubis-foundry"),
       },
-      { name: "Postman", value: "postman", checked: defaultMcps.includes("postman") },
-      { name: "Stitch", value: "stitch", checked: defaultMcps.includes("stitch") },
+      {
+        name: "Postman",
+        value: "postman",
+        checked: defaultMcps.includes("postman"),
+      },
+      {
+        name: "Stitch",
+        value: "stitch",
+        checked: defaultMcps.includes("stitch"),
+      },
     ],
   });
 }
@@ -87,7 +106,10 @@ export async function promptInitScope({
     message,
     default: defaultScope,
     choices: [
-      { name: defaultScope === "global" ? "Global (recommended)" : "Global", value: "global" },
+      {
+        name: defaultScope === "global" ? "Global (recommended)" : "Global",
+        value: "global",
+      },
       {
         name: defaultScope === "project" ? "Project (recommended)" : "Project",
         value: "project",

package/src/cli/init/types.ts

@@ -2,7 +2,7 @@ export type InitScope = "project" | "global";
 export type InitSkillProfile = "core" | "web-backend" | "full";
 export type InitMcpId = "cubis-foundry" | "postman" | "stitch";
 export type InitPostmanMode = "full" | "minimal";
-export type InitPlatformId = "codex" | "antigravity" | "copilot";
+export type InitPlatformId = "codex" | "antigravity" | "copilot" | "claude";
 export type InitMcpRuntime = "local" | "docker";
 
 export interface InitWizardSelections {

package/src/cli/platforms.ts

@@ -1 +1 @@
-export type PlatformId = "codex" | "antigravity" | "copilot";
+export type PlatformId = "codex" | "antigravity" | "copilot" | "claude";

package/workflows/skills/agent-handoff/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: "agent-handoff"
+displayName: "Agent Handoff"
+description: >
+  Load this skill when you are a CUSTOM AGENT spawned by a workflow and have received a task envelope.
+  Covers: reading the envelope, cold-start protocol, skill_get without skill_search, writing deliverables,
+  returning the result envelope, and what NOT to load into context.
+  DO NOT trigger for orchestrator/workflow-level planning — that is the workflow's job.
+  ALWAYS trigger when: "task envelope received", "spawned from workflow", "agent executing milestone",
+  "result envelope", "handoff".
+keywords:
+  [
+    "agent-handoff",
+    "handoff",
+    "task envelope",
+    "result envelope",
+    "cold-start",
+    "agent spawn",
+    "milestone agent",
+    "zero-bloat",
+    "workflow agent",
+  ]
+---
+
+# Agent Handoff Skill
+# Zero-bloat protocol for agents spawned from Foundry workflows
+
+## What This Skill Does
+
+You are a custom agent. You were spawned from a workflow with a task envelope.
+This skill tells you exactly how to execute without loading unnecessary context.
+
+---
+
+## Step 1 — Read Your Task Envelope
+
+You received a task envelope. It looks like this:
+```json
+{
+  "milestone_id": "M2",
+  "milestone_name": "Build API layer",
+  "deliverable_path": "src/api/routes.ts",
+  "acceptance_criteria": "File exists, tests pass",
+  "skill_name": "web-backend",
+  "status_file": "TASK_STATUS.md",
+  "env_context": ["NODE_ENV", "API_BASE_URL"]
+}
+```
+
+Fields you MUST use:
+- `milestone_id` — your scope identifier
+- `deliverable_path` — where to write your output
+- `acceptance_criteria` — how to verify completion
+- `skill_name` — the skill to load (pre-resolved by orchestrator)
+- `status_file` — the task status file to read and update
+
+---
+
+## Step 2 — Orient (Cold-Start, Minimal Read)
+
+Read ONLY the project status file named in `status_file` (usually TASK_STATUS.md).
+Use the [TASK_STATUS template](references/TASK_STATUS.md) only to confirm the expected shape.
+
+```
+If your milestone shows "complete" → return result envelope immediately, skip execution.
+If your milestone shows "blocked" → surface the block, do not attempt execution.
+If your milestone shows "pending" or is absent → proceed to Step 3.
+```
+
+**DO NOT read:**
+- TASK_SPEC.md (not needed unless acceptance criteria are ambiguous — read only then)
+- TASK_PLAN.md (your envelope already has your acceptance criteria)
+- Other milestones' files or outputs
+
+---
+
+## Step 3 — Load Skill (No skill_search)
+
+The orchestrator already resolved your skill. Load it directly:
+
+```
+skill_get "<skill_name from envelope>"
+```
+
+Follow the skill's instructions for executing the work.
+
+If `skill_name` is `"none"` or empty: use direct tool execution — no skill needed.
+
+**Never call `skill_search`** — that's the orchestrator's job. Calling it here wastes tokens.
+
+---
+
+## Step 4 — Execute (Code-Execution Pattern)
+
+Use the code-execution pattern for all data-heavy work:
+
+```
+# BAD — each result enters context
+call tool → result enters context
+call tool → result enters context
+
+# GOOD — process outside context
+write code that:
+  1. calls tools → stores results in variables
+  2. processes data in execution environment
+  3. writes output to deliverable_path
+  4. returns only pass/fail + summary to context
+```
+
+Load only env vars listed in `env_context` — do not scan for or load others.
+
+---
+
+## Step 5 — Verify & Update Status
+
+After execution:
+1. Confirm `deliverable_path` exists
+2. Run acceptance check (as defined in `acceptance_criteria`)
+3. Update the project status file from `status_file` using the [TASK_STATUS template](references/TASK_STATUS.md):
+
+```markdown
+## M2 — Build API layer
+- Status: complete
+- Deliverable: src/api/routes.ts ✓
+- Completed: [timestamp]
+```
+
+---
+
+## Step 6 — Return Result Envelope
+
+Return EXACTLY this structure to the calling workflow — nothing more:
+
+```json
+{
+  "milestone_id": "M2",
+  "status": "complete",
+  "deliverable": "src/api/routes.ts",
+  "verified": true,
+  "summary": "Created 4 REST endpoints. All tests pass.",
+  "errors": []
+}
+```
+
+| Field | Rule |
+|---|---|
+| `status` | One of: `complete`, `failed`, `blocked` |
+| `summary` | 1–3 sentences max — what was done, what was produced |
+| `errors` | Empty array on success; structured error objects on failure |
+| `verified` | Only `true` if acceptance criteria was explicitly checked |
+
+**Never return:** raw stdout, full file contents, intermediate reasoning, test output logs.
+If the workflow needs more detail, it will read `deliverable_path` directly.
+
+---
+
+## What You Must Never Do
+
+| Never | Why |
+|---|---|
+| Call `skill_search` | Wastes tokens — orchestrator already resolved skill |
+| Read TASK_SPEC.md / TASK_PLAN.md upfront | Your envelope has what you need |
+| Return raw tool output to workflow | Multiplies context cost |
+| Write to paths outside your `deliverable_path` | Parallel agent collision risk |
+| Load env vars not in your `env_context` | Credential scope leak |
+| Pass your context to sub-agents without filtering | Cascading bloat |
+
+---
+
+## If You Need to Spawn a Sub-Agent
+
+If your milestone requires spawning another agent:
+1. Build a NEW minimal envelope — do NOT forward your own envelope
+2. Include ONLY what the sub-agent needs for its specific task
+3. Receive sub-agent result envelope only — do not receive its full context
+4. Continue with your milestone after verifying sub-agent result
+
+---
+
+## On Failure
+
+If execution fails:
+1. Update the project status file from `status_file` with failure details
+2. Return result envelope with `"status": "failed"` and structured `errors[]`
+3. Do NOT attempt to recover beyond one retry — surface to orchestrator
+4. Do NOT continue to the next milestone
+
+---
+
+## Platform-Specific Adaptation
+
+This skill works across all Foundry platforms, but agent spawning differs:
+
+| Platform | How You Were Spawned | Return Method |
+|---|---|---|
+| **Claude Code** | Via subagent (Agent tool) or `context: fork` | Return result text — orchestrator reads it |
+| **Antigravity** | Via Agent Manager | Write to `deliverable_path`, Agent Manager collects |
+| **Copilot** | Via custom agent (`.github/agents/`) | Return structured result envelope |
+| **Codex** | Via wrapper workflow (`agent-<name>`) | Return structured result envelope |
+
+On **Claude Code**: You may have restricted tool access if spawned with `allowed-tools`.
+Only use the tools available to you. If you need a tool not in your allowlist, surface
+the need in your result envelope — do not attempt workarounds.
+
+On **Antigravity**: You may be running in parallel with other agents. Strictly respect
+your `deliverable_path` — never write outside it.

package/workflows/skills/agent-handoff/references/TASK_STATUS.md

@@ -0,0 +1,24 @@
+# TASK_STATUS.md Template
+
+Use this as a shape reference for the project-level status file mentioned in the task envelope.
+Do not copy it blindly if the active project already has a status file format.
+
+```markdown
+# Task Status
+
+## M1 — Example milestone
+- Status: pending
+- Deliverable: src/example.ts
+- Notes: Waiting on implementation
+
+## M2 — Example milestone
+- Status: complete
+- Deliverable: src/api/routes.ts
+- Completed: 2026-03-07T10:00:00Z
+- Notes: Acceptance checks passed
+
+## M3 — Example milestone
+- Status: blocked
+- Deliverable: src/db/schema.sql
+- Blocker: Migration contract not finalized
+```

package/workflows/skills/postman/SKILL.md

@@ -15,11 +15,17 @@ References:
 ## MCP-First Rule
 
 - Prefer Postman MCP tools for all Postman operations.
-- Accept both dynamic naming styles from clients:
-  - dotted: `postman.<tool>`
-  - alias: `postman_<tool>`
+- Use direct Postman server tools for actual Postman cloud work:
+  - direct server: `postman.<tool>`
+  - client-wrapped direct server: `mcp__postman__<tool>`
+- Treat Foundry `postman_*` tools as config helpers only:
+  - `postman_get_status`
+  - `postman_get_mode`
+  - `postman_set_mode`
 - Never default to raw Postman REST JSON payloads, Newman, or Postman CLI when MCP tools are available.
-- Do not use Newman/Postman CLI fallback unless the user explicitly asks for fallback.
+- Do not use `postman.runMonitor` as an automatic fallback after `postman.runCollection` timeout or failure.
+- Only use monitor execution when the user explicitly asks for monitor-based cloud execution, scheduled monitoring, or monitor validation.
+- Recommend Postman CLI as the default secondary path when direct MCP execution fails.
 - If required Postman MCP tools are unavailable, report discovery/remediation steps first.
 
 ## Setup Baseline
@@ -36,16 +42,21 @@ References:
 ## Preflight
 
 1. Read Postman status first:
-   - Call `postman_get_status`.
+   - Call `postman_get_status` for mode/default-workspace/config state.
 2. Ensure mode is `full`:
    - If not, call `postman_set_mode` with `mode: full`.
 3. Discover upstream tools:
-   - Confirm required tools exist before execution (for example workspaces/collections/runs).
+   - Confirm required direct Postman server tools exist before execution (for example workspaces/collections/runs).
 
 Execution rule:
-- For Postman requests, call MCP tools directly (`postman.*` or `postman_*`) instead of drafting manual JSON or curl payloads.
+- For Postman requests, call the direct Postman server (`postman.<tool>` or `mcp__postman__<tool>`) instead of Foundry `postman_*` config tools.
 - If the user asks for API payload examples, provide them only as supplemental documentation after MCP execution guidance.
 
+Quota-safe rule:
+- If `postman.runCollection` times out or fails, stop and classify the error before choosing any fallback.
+- Never auto-convert a collection run failure into `postman.runMonitor`.
+- Recommend Postman CLI first for repeatable local reruns.
+
 ## Default Workspace Policy
 
 Resolve workspace in this order:
@@ -76,6 +87,30 @@ When a Postman tool requires a workspace argument, always pass the resolved work
 
 ## Failure Handling
 
+### Error Classification
+
+Classify failures before suggesting any fallback:
+
+- `limitBreachedError` or "breached monitoring usage limit":
+  - monitor quota exhaustion
+  - do not retry monitor runs
+  - recommend local Postman CLI execution
+  - tell the user to check the Postman monitoring usage dashboard
+- `429` or rate-limit response:
+  - Postman API rate limiting
+  - recommend backoff and a lower request burst
+  - do not reinterpret it as monitor quota
+- collection run timeout without quota/rate-limit signal:
+  - direct MCP runtime or tool timeout
+  - do not auto-convert to a monitor run
+  - recommend Postman CLI or a smaller-scope rerun
+
+### Quota Notes
+
+- Monitor usage is separate from Postman API rate limits.
+- Monitor usage is plan/billing usage and is consumed by request count, region count, and auth requests.
+- Monitor runtime caps are separate from monitor quota and do not imply quota remains available.
+
 If dynamic Postman tools are missing:
 
 1. Verify env alias expected by config is set.

package/workflows/skills/postman/references/troubleshooting.md

@@ -28,3 +28,42 @@ Use alias tools (`postman_<tool>`) when dotted names are filtered by client UI.
 ## Missing API key at startup
 
 Expected behavior: tool names can still come from cached catalog; tool calls fail with explicit auth error until env alias is set.
+
+## Quota-safe execution
+
+Preferred path:
+
+1. Use direct Postman MCP collection execution first (`postman.runCollection` or equivalent).
+2. If that fails, stop and classify the error.
+3. Recommend Postman CLI as the safe default secondary path.
+4. Use monitor execution only when the user explicitly asks for monitor-based cloud execution.
+
+Do not auto-fallback from `runCollection` to `runMonitor`.
+
+## Error classification
+
+### `limitBreachedError` or "breached monitoring usage limit"
+
+- This is monitor quota exhaustion, not generic API failure.
+- Do not retry monitor runs.
+- Do not reinterpret it as an MCP auth issue.
+- Tell the user to check Postman monitoring usage and billing-period reset in the Postman dashboard.
+- Recommend Postman CLI as the next execution path.
+
+### `429` or rate-limited API response
+
+- This is Postman API rate limiting.
+- Reduce request burst, add backoff, and retry later.
+- Do not treat it as monitor quota exhaustion.
+
+### `runCollection` timeout without quota/rate-limit signal
+
+- Treat this as direct MCP/runtime timeout.
+- Do not auto-convert to monitor execution.
+- Recommend Postman CLI or a smaller-scope rerun.
+
+## Monitor usage facts
+
+- Monitor usage is separate from Postman API RPM limits.
+- Monitor usage is consumed by request count, region count, and auth requests.
+- Monitor runtime caps are separate from monitor quota and do not imply usage remains available.

package/workflows/workflows/agent-environment-setup/manifest.json

@@ -1,7 +1,7 @@
 {
   "id": "agent-environment-setup",
   "version": "1.0.0",
-  "description": "Workflow-first AI agent environment setup for Antigravity, Codex, and Copilot.",
+  "description": "Workflow-first AI agent environment setup for Antigravity, Codex, Copilot, and Claude Code.",
   "platforms": {
     "antigravity": {
       "workflows": [
@@ -50,6 +50,7 @@
       ],
       "skills": [
         "accessibility",
+        "agent-handoff",
         "api-designer",
         "api-patterns",
         "app-builder",
@@ -245,6 +246,7 @@
       ],
       "skills": [
         "accessibility",
+        "agent-handoff",
         "api-designer",
         "api-patterns",
         "app-builder",
@@ -419,6 +421,7 @@
       ],
       "skills": [
         "accessibility",
+        "agent-handoff",
         "api-designer",
         "api-patterns",
         "app-builder",
@@ -566,6 +569,181 @@
         "workflow-vercel.prompt.md",
         "workflow-postman.prompt.md"
       ]
+    },
+    "claude": {
+      "workflows": [
+        "orchestrate.md",
+        "brainstorm.md",
+        "plan.md",
+        "create.md",
+        "test.md",
+        "debug.md",
+        "implement-track.md",
+        "backend.md",
+        "review.md",
+        "refactor.md",
+        "incident.md",
+        "release.md",
+        "security.md",
+        "database.md",
+        "mobile.md",
+        "devops.md",
+        "qa.md",
+        "vercel.md",
+        "postman.md"
+      ],
+      "agents": [
+        "backend-specialist.md",
+        "code-archaeologist.md",
+        "database-architect.md",
+        "debugger.md",
+        "devops-engineer.md",
+        "documentation-writer.md",
+        "explorer-agent.md",
+        "frontend-specialist.md",
+        "game-developer.md",
+        "mobile-developer.md",
+        "orchestrator.md",
+        "penetration-tester.md",
+        "performance-optimizer.md",
+        "product-manager.md",
+        "product-owner.md",
+        "project-planner.md",
+        "qa-automation-engineer.md",
+        "security-auditor.md",
+        "seo-specialist.md",
+        "test-engineer.md",
+        "vercel-expert.md"
+      ],
+      "skills": [
+        "accessibility",
+        "agent-handoff",
+        "api-designer",
+        "api-patterns",
+        "app-builder",
+        "architecture",
+        "architecture-designer",
+        "ask-questions-if-underspecified",
+        "bash-linux",
+        "behavioral-modes",
+        "brainstorming",
+        "changelog-generator",
+        "clean-code",
+        "cli-developer",
+        "code-documenter",
+        "code-review-checklist",
+        "code-reviewer",
+        "database-design",
+        "database-optimizer",
+        "database-skills",
+        "debugging-wizard",
+        "deployment-procedures",
+        "design-system-builder",
+        "devops-engineer",
+        "documentation-templates",
+        "drift-flutter",
+        "error-ux-observability",
+        "fastapi-expert",
+        "fastify-patterns",
+        "feature-forge",
+        "find-bugs",
+        "fix-review",
+        "flutter-code-reviewer",
+        "flutter-expert",
+        "flutter-security-reviewer",
+        "flutter-test-master",
+        "frontend-design",
+        "game-development",
+        "geo-fundamentals",
+        "git-commit",
+        "golang-pro",
+        "gorouter-restoration",
+        "graphql-architect",
+        "i18n-localization",
+        "intelligent-routing",
+        "javascript-pro",
+        "legacy-modernizer",
+        "lint-and-validate",
+        "microservices-architect",
+        "mobile-design",
+        "monitoring-expert",
+        "nestjs-expert",
+        "next-best-practices",
+        "next-cache-components",
+        "next-upgrade",
+        "nextjs-developer",
+        "nextjs-react-expert",
+        "nodejs-best-practices",
+        "oneup-design",
+        "openapi-docs",
+        "parallel-agents",
+        "performance-profiling",
+        "plan-writing",
+        "playwright-expert",
+        "powershell-windows",
+        "prompt-engineer",
+        "python-patterns",
+        "python-pro",
+        "react-best-practices",
+        "react-expert",
+        "red-team-tactics",
+        "refactor",
+        "riverpod-3",
+        "rust-engineer",
+        "rust-pro",
+        "saas-builder",
+        "sarif-parsing",
+        "secure-code-guardian",
+        "security-reviewer",
+        "semgrep",
+        "seo-fundamentals",
+        "server-management",
+        "spec-miner",
+        "sre-engineer",
+        "static-analysis",
+        "stripe-best-practices",
+        "sub-agents",
+        "systematic-debugging",
+        "tailwind-patterns",
+        "tdd-workflow",
+        "terraform-engineer",
+        "test-master",
+        "testing-patterns",
+        "typescript-pro",
+        "ui-ux-pro-max",
+        "ux-ui-consistency",
+        "variant-analysis",
+        "vercel-ai",
+        "vercel-ai-gateway",
+        "vercel-ai-sdk",
+        "vercel-caching",
+        "vercel-cli",
+        "vercel-delivery",
+        "vercel-deployments",
+        "vercel-domains",
+        "vercel-firewall",
+        "vercel-flags",
+        "vercel-functions",
+        "vercel-observability",
+        "vercel-platform",
+        "vercel-routing",
+        "vercel-runtime",
+        "vercel-security",
+        "vercel-storage",
+        "vulnerability-scanner",
+        "web-design-guidelines",
+        "web-perf",
+        "webapp-testing",
+        "wrangler"
+      ],
+      "rulesTemplate": "platforms/claude/rules/CLAUDE.md",
+      "hooks": [
+        {
+          "type": "conductor-reference",
+          "optional": true,
+          "description": "If Conductor artifacts exist, workflows can reference them as supporting context."
+        }
+      ]
     }
   }
 }