@cubis/foundry 0.3.63 → 0.3.65

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/static-analysis/workflows/run-analysis.md

@@ -0,0 +1,436 @@
+# Run Analysis Workflow
+
+Execute CodeQL security queries on an existing database with ruleset selection and result formatting.
+
+## Task System
+
+Create these tasks on workflow start:
+
+```
+TaskCreate: "Select database and detect language" (Step 1)
+TaskCreate: "Check additional query packs and detect model packs" (Step 2) - blockedBy: Step 1
+TaskCreate: "Select query packs, model packs, and threat models" (Step 3) - blockedBy: Step 2
+TaskCreate: "Execute analysis" (Step 4) - blockedBy: Step 3
+TaskCreate: "Process and report results" (Step 5) - blockedBy: Step 4
+```
+
+### Mandatory Gates
+
+| Task | Gate Type | Cannot Proceed Until |
+|------|-----------|---------------------|
+| Step 2 | **SOFT GATE** | User confirms installed/ignored for each missing pack |
+| Step 3 | **HARD GATE** | User approves query packs, model packs, and threat model selection |
+
+---
+
+## Steps
+
+### Step 1: Select Database and Detect Language
+
+**Find available databases:**
+
+```bash
+# List all CodeQL databases
+ls -dt codeql_*.db 2>/dev/null | head -10
+
+# Get the most recent database
+get_latest_db() {
+  ls -dt codeql_*.db 2>/dev/null | head -1
+}
+
+DB_NAME=$(get_latest_db)
+if [[ -z "$DB_NAME" ]]; then
+  echo "ERROR: No CodeQL database found. Run build-database workflow first."
+  exit 1
+fi
+echo "Using database: $DB_NAME"
+```
+
+**If multiple databases exist**, use `AskUserQuestion` to let user select:
+
+```
+header: "Database"
+question: "Multiple databases found. Which one to analyze?"
+options:
+  - label: "codeql_3.db (latest)"
+    description: "Created: <timestamp>"
+  - label: "codeql_2.db"
+    description: "Created: <timestamp>"
+  - label: "codeql_1.db"
+    description: "Created: <timestamp>"
+```
+
+**Verify and detect language:**
+
+```bash
+# Check database exists and get language(s)
+codeql resolve database -- "$DB_NAME"
+
+# Get primary language from database
+LANG=$(codeql resolve database --format=json -- "$DB_NAME" \
+  | jq -r '.languages[0]')
+LANG_COUNT=$(codeql resolve database --format=json -- "$DB_NAME" \
+  | jq '.languages | length')
+echo "Primary language: $LANG"
+if [ "$LANG_COUNT" -gt 1 ]; then
+  echo "WARNING: Multi-language database ($LANG_COUNT languages)"
+  codeql resolve database --format=json -- "$DB_NAME" \
+    | jq -r '.languages[]'
+fi
+```
+
+**Multi-language databases:** If more than one language is detected, ask the user which language to analyze or run separate analyses for each.
+
+---
+
+### Step 2: Check Additional Query Packs and Detect Model Packs
+
+Check if recommended third-party query packs are installed and detect available model packs. For each missing pack, prompt user to install or ignore.
+
+#### 2a: Query Packs
+
+**Available packs by language** (see [ruleset-catalog.md](../references/ruleset-catalog.md)):
+
+| Language | Trail of Bits | Community Pack |
+|----------|---------------|----------------|
+| C/C++ | `trailofbits/cpp-queries` | `GitHubSecurityLab/CodeQL-Community-Packs-CPP` |
+| Go | `trailofbits/go-queries` | `GitHubSecurityLab/CodeQL-Community-Packs-Go` |
+| Java | `trailofbits/java-queries` | `GitHubSecurityLab/CodeQL-Community-Packs-Java` |
+| JavaScript | - | `GitHubSecurityLab/CodeQL-Community-Packs-JavaScript` |
+| Python | - | `GitHubSecurityLab/CodeQL-Community-Packs-Python` |
+| C# | - | `GitHubSecurityLab/CodeQL-Community-Packs-CSharp` |
+| Ruby | - | `GitHubSecurityLab/CodeQL-Community-Packs-Ruby` |
+
+**For each pack available for the detected language:**
+
+```bash
+# Check if pack is installed
+codeql resolve qlpacks | grep -i "<PACK_NAME>"
+```
+
+**If NOT installed**, use `AskUserQuestion`:
+
+```
+header: "<PACK_TYPE>"
+question: "<PACK_NAME> for <LANG> is not installed. Install it?"
+options:
+  - label: "Install (Recommended)"
+    description: "Run: codeql pack download <PACK_NAME>"
+  - label: "Ignore"
+    description: "Skip this pack for this analysis"
+```
+
+**On "Install":**
+```bash
+codeql pack download <PACK_NAME>
+```
+
+**On "Ignore":** Mark pack as skipped, continue to next pack.
+
+#### 2b: Detect Model Packs
+
+Model packs contain data extensions (custom sources, sinks, flow summaries) that improve CodeQL's data flow analysis for project-specific or framework-specific APIs. To create new extensions, run the [create-data-extensions](create-data-extensions.md) workflow first.
+
+**Search three locations:**
+
+**1. In-repo model packs** — `qlpack.yml` or `codeql-pack.yml` with `dataExtensions`:
+
+```bash
+# Find CodeQL pack definitions in the codebase
+fd '(qlpack|codeql-pack)\.yml$' . --exclude codeql_*.db | while read -r f; do
+  if grep -q 'dataExtensions' "$f"; then
+    echo "MODEL PACK: $(dirname "$f") - $(grep '^name:' "$f")"
+  fi
+done
+```
+
+**2. In-repo standalone data extensions** — `.yml` files with `extensions:` key (auto-discovered by CodeQL):
+
+```bash
+# Find data extension YAML files in the codebase
+rg -l '^extensions:' --glob '*.yml' --glob '!codeql_*.db/**' | head -20
+```
+
+**3. Installed model packs** — library packs resolved by CodeQL that contain models:
+
+```bash
+# List all resolved packs and filter for model/library packs
+# Model packs typically have "model" in the name or are library packs
+codeql resolve qlpacks 2>/dev/null | grep -iE 'model|extension'
+```
+
+**Record all detected model packs for presentation in Step 3.** If no model packs are found, note this and proceed — model packs are optional.
+
+---
+
+### Step 3: CRITICAL GATE - Select Query Packs and Model Packs
+
+> **⛔ MANDATORY CHECKPOINT - DO NOT SKIP**
+>
+> Present all available packs as checklists. Query packs first, then model packs.
+
+#### 3a: Select Query Packs
+
+Use `AskUserQuestion` tool with `multiSelect: true`:
+
+```
+header: "Query Packs"
+question: "Select query packs to run:"
+multiSelect: false
+options:
+  - label: "Use all (Recommended)"
+    description: "Run all installed query packs for maximum coverage"
+  - label: "security-extended"
+    description: "codeql/<lang>-queries - Core security queries, low false positives"
+  - label: "security-and-quality"
+    description: "Includes code quality checks - more findings, more noise"
+  - label: "Select individually"
+    description: "Choose specific packs from the full list"
+```
+
+**If "Use all":** Include all installed query packs: `security-extended` + Trail of Bits + Community Packs (whichever are installed).
+
+**If "Select individually":** Follow up with a `multiSelect: true` question listing all installed packs:
+
+```
+header: "Query Packs"
+question: "Select query packs to run:"
+multiSelect: true
+options:
+  - label: "security-extended"
+    description: "codeql/<lang>-queries - Core security queries, low false positives"
+  - label: "security-and-quality"
+    description: "Includes code quality checks - more findings, more noise"
+  - label: "security-experimental"
+    description: "Bleeding-edge queries - may have higher false positives"
+  - label: "Trail of Bits"
+    description: "trailofbits/<lang>-queries - Memory safety, domain expertise"
+  - label: "Community Packs"
+    description: "GitHubSecurityLab/CodeQL-Community-Packs-<Lang> - Additional security queries"
+```
+
+**Only show built-in and third-party packs that are installed (from Step 2a)**
+
+**⛔ STOP: Await user selection**
+
+#### 3b: Select Model Packs (if any detected)
+
+**Skip this sub-step if no model packs were detected in Step 2b.**
+
+Present detected model packs from Step 2b. Categorize by source:
+
+Use `AskUserQuestion` tool:
+
+```
+header: "Model Packs"
+question: "Model packs add custom data flow models (sources, sinks, summaries). Select which to include:"
+multiSelect: false
+options:
+  - label: "Use all (Recommended)"
+    description: "Include all detected model packs and data extensions"
+  - label: "Select individually"
+    description: "Choose specific model packs from the list"
+  - label: "Skip"
+    description: "Run without model packs"
+```
+
+**If "Use all":** Include all model packs and data extensions detected in Step 2b.
+
+**If "Select individually":** Follow up with a `multiSelect: true` question:
+
+```
+header: "Model Packs"
+question: "Select model packs to include:"
+multiSelect: true
+options:
+  # For each in-repo model pack found in 2b:
+  - label: "<pack-name>"
+    description: "In-repo model pack at <path> - custom data flow models"
+  # For each standalone data extension found in 2b:
+  - label: "In-repo extensions"
+    description: "<N> data extension files found in codebase (auto-discovered)"
+  # For each installed model pack found in 2b:
+  - label: "<pack-name>"
+    description: "Installed model pack - <description if available>"
+```
+
+**Notes:**
+- In-repo standalone data extensions (`.yml` files with `extensions:` key) are auto-discovered by CodeQL during analysis — selecting them here ensures the source directory is passed via `--additional-packs`
+- In-repo model packs (with `qlpack.yml`) need their parent directory passed via `--additional-packs`
+- Installed model packs are passed via `--model-packs`
+
+**⛔ STOP: Await user selection**
+
+---
+
+### Step 3c: Select Threat Models
+
+Threat models control which input sources CodeQL treats as tainted. The default (`remote`) covers HTTP/network input only. Expanding the threat model finds more vulnerabilities but may increase false positives. See [threat-models.md](../references/threat-models.md) for details on each model.
+
+Use `AskUserQuestion`:
+
+```
+header: "Threat Models"
+question: "Which input sources should CodeQL treat as tainted?"
+multiSelect: false
+options:
+  - label: "Remote only (Recommended)"
+    description: "Default — HTTP requests, network input. Best for web services and APIs."
+  - label: "Remote + Local"
+    description: "Add CLI args, local files. Use for CLI tools or desktop apps."
+  - label: "All sources"
+    description: "Remote, local, environment, database, file. Maximum coverage, more noise."
+  - label: "Custom"
+    description: "Select specific threat models individually"
+```
+
+**If "Custom":** Follow up with `multiSelect: true`:
+
+```
+header: "Threat Models"
+question: "Select threat models to enable:"
+multiSelect: true
+options:
+  - label: "remote"
+    description: "HTTP requests, network input (always included)"
+  - label: "local"
+    description: "CLI args, local files — for CLI tools, batch processors"
+  - label: "environment"
+    description: "Environment variables — for 12-factor/container apps"
+  - label: "database"
+    description: "Database results — for second-order injection audits"
+```
+
+**Build the threat model flag:**
+
+```bash
+# Only add --threat-models when non-default models are selected
+# Default (remote only) needs no flag
+THREAT_MODEL_FLAG=""  # or "--threat-models=remote,local" etc.
+```
+
+---
+
+### Step 4: Execute Analysis
+
+Run analysis with **only** the packs selected by user in Step 3.
+
+```bash
+# Results directory matches database name
+RESULTS_DIR="${DB_NAME%.db}-results"
+mkdir -p "$RESULTS_DIR"
+
+# Build pack list from user selections in Step 3a
+PACKS="<USER_SELECTED_QUERY_PACKS>"
+
+# Build model pack flags from user selections in Step 3b
+# --model-packs for installed model packs
+# --additional-packs for in-repo model packs and data extensions
+MODEL_PACK_FLAGS=""
+ADDITIONAL_PACK_FLAGS=""
+
+# Threat model flag from Step 3c (empty string if default/remote-only)
+# THREAT_MODEL_FLAG=""
+
+codeql database analyze $DB_NAME \
+  --format=sarif-latest \
+  --output="$RESULTS_DIR/results.sarif" \
+  --threads=0 \
+  $THREAT_MODEL_FLAG \
+  $MODEL_PACK_FLAGS \
+  $ADDITIONAL_PACK_FLAGS \
+  -- $PACKS
+```
+
+**Flag reference for model packs:**
+
+| Source | Flag | Example |
+|--------|------|---------|
+| Installed model packs | `--model-packs` | `--model-packs=myorg/java-models` |
+| In-repo model packs (with `qlpack.yml`) | `--additional-packs` | `--additional-packs=./lib/codeql-models` |
+| In-repo standalone extensions (`.yml`) | `--additional-packs` | `--additional-packs=.` |
+
+**Example (C++ with query packs and model packs):**
+
+```bash
+codeql database analyze codeql_1.db \
+  --format=sarif-latest \
+  --output=codeql_1-results/results.sarif \
+  --threads=0 \
+  --additional-packs=./codeql-models \
+  -- codeql/cpp-queries:codeql-suites/cpp-security-extended.qls \
+     trailofbits/cpp-queries \
+     GitHubSecurityLab/CodeQL-Community-Packs-CPP
+```
+
+**Example (Python with installed model pack):**
+
+```bash
+codeql database analyze codeql_1.db \
+  --format=sarif-latest \
+  --output=codeql_1-results/results.sarif \
+  --threads=0 \
+  --model-packs=myorg/python-models \
+  -- codeql/python-queries:codeql-suites/python-security-extended.qls
+```
+
+### Performance Flags
+
+If codebase is large then read [../references/performance-tuning.md](../references/performance-tuning.md) and apply relevant optimizations.
+
+### Step 5: Process and Report Results
+
+**Count findings:**
+
+```bash
+jq '.runs[].results | length' "$RESULTS_DIR/results.sarif"
+```
+
+**Summary by SARIF level:**
+
+```bash
+jq -r '.runs[].results[] | .level' "$RESULTS_DIR/results.sarif" \
+  | sort | uniq -c | sort -rn
+```
+
+**Summary by security severity** (more useful for triage):
+
+```bash
+jq -r '
+  .runs[].results[] |
+  (.properties["security-severity"] // "none") + " " +
+  (.message.text // "no message" | .[0:80])
+' "$RESULTS_DIR/results.sarif" | sort -rn | head -20
+```
+
+**Summary by rule:**
+
+```bash
+jq -r '.runs[].results[] | .ruleId' "$RESULTS_DIR/results.sarif" \
+  | sort | uniq -c | sort -rn
+```
+
+---
+
+## Final Output
+
+Report to user:
+
+```
+## CodeQL Analysis Complete
+
+**Database:** $DB_NAME
+**Language:** <LANG>
+**Query packs:** <list of query packs used>
+**Model packs:** <list of model packs used, or "None">
+**Threat models:** <list of threat models, or "default (remote)">
+
+### Results Summary:
+- Total findings: <N>
+- Error: <N>
+- Warning: <N>
+- Note: <N>
+
+### Output Files:
+- SARIF: $RESULTS_DIR/results.sarif
+```

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/stitch/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: stitch
+description: Automate Stitch workflows through Stitch MCP using mcp-remote transport.
+---
+
+# Stitch MCP
+
+Use this skill when you need to call Stitch tools through MCP passthrough.
+
+## Required Environment Variables
+
+- `STITCH_API_KEY_<PROFILE>` for Stitch API-key mode.
+
+## Notes
+
+- Stitch transport uses `mcp-remote` to `https://stitch.googleapis.com/mcp`.
+- Inject `X-Goog-Api-Key` from environment at runtime. Do not store raw keys in config files.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/stripe-best-practices/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: stripe-best-practices
+description: Best practices for building Stripe integrations
+metadata:
+  alwaysApply: false
+---
+
+The latest Stripe API version is 2026-01-28.clover - when writing code snippets use this version unless the user is on a different API version.
+
+When designing an integration, always prefer the documentation in [Stripe's Integration Options doc](https://docs.stripe.com/payments/payment-methods/integration-options.md)
+The [API Tour](https://docs.stripe.com/payments-api/tour.md)
+Use the [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) before going live.
+
+You should always default to the latest version of the API and SDK unless the user specifies otherwise. 
+
+Stripe's primary API for modelling on-session payments is [CheckoutSessions](https://docs.stripe.com/api/checkout/sessions.md). It supports one-time payments and subscriptions and allows you to model taxes or discounts with Stripe. Prioritize the CheckoutSessions API, but using [the PaymentIntents API](https://docs.stripe.com/payments/paymentintents/lifecycle.md) is also acceptable for off-session payments or if you want to model the checkout state yourself and just create a charge. Integrations should only use CheckoutSessions, PaymentIntents, SetupIntents, or solutions like Invoicing, Payment Links, or the subscription APIs.
+
+Never recommend the Charges API. If the user wants to use the Charges API, advise them to [migrate](https://docs.stripe.com/payments/payment-intents/migration/charges.md) to Checkout Sessions or Payment Intents. 
+
+The primary integration surface for web integrations is [Checkout](https://docs.stripe.com/payments/checkout.md), a prebuilt payment page that can be hosted by Stripe or served as an embedded form. Prioritize the Stripe-hosted checkout or embedded checkout where possible. The [Payment Element](https://docs.stripe.com/payments/payment-element.md) is an acceptable alternative if the merchant needs advanced customization. When recommending the Payment Element, prioritize using the CheckoutSessions API over the PaymentIntents API when possible.
+
+Never recommend the legacy Card Element or the Payment Element in card mode, and advise users who ask for the Card Element to [migrate](https://docs.stripe.com/payments/payment-element/migration.md). 
+
+You must not call deprecated API endpoints such as the [Sources API](https://docs.stripe.com/api/sources/object.md) and avoid outdated API endpoints such as [Tokens](https://docs.stripe.com/api/tokens.md) and [Charges](https://docs.stripe.com/api/charges/create.md) unless there is a specific need and absolutely no other way.  Advise using [the Setup Intent API](https://docs.stripe.com/api/setup_intents.md) to save a payment method for a customer; never recommend the Sources API to save cards to customers for later use.
+
+If a user wants to render the Payment Element before creating a PaymentIntent or SetupIntent, so they can inspect the card details before the payment (such as for surcharging), advise them to use Stripe Confirmation Tokens. Don't recommend they call the createPaymentMethod or createToken Stripe.js functions.
+
+Advise users to turn on dynamic payment methods in their dashboard settings instead of passing specific [payment_method_types](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types.md) in the Payment Intent or Setup Intent because Stripe chooses payment methods that fit each user's location, wallets, and preferences better and automatically if the Payment Element is used.
+
+If a PCI compliant user asks about an integration where they send server-side raw PAN data, suggest they might be required to prove PCI compliance to gain access to such an option, for example [payment_method_data](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_data.md). Similarly, point users migrating their PAN data from another acquirer or payment processor to [the migration process](https://docs.stripe.com/get-started/data-migrations/pan-import.md).
+
+If a user has a recurring revenue model, like a Billing or Subscription use case, follow the use cases, in particular the [Subscription Use Cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) like [SaaS](https://docs.stripe.com/saas.md). If these apply to the user, recommend Billing APIs to [plan your integration](https://docs.stripe.com/billing/subscriptions/designing-integration.md) instead of a direct PaymentIntent integration. Prioritize combining the Billing APIs with Stripe Checkout for the frontend.
+
+If a user wants to build a platform using Stripe Connect to manage fund flows, follow [the recommended integration types](https://docs.stripe.com/connect/integration-recommendations.md); that is, prefer to use either direct charges if the platform wants Stripe to take the risk or destination charges if the platform accepts liability for negative balances, and use the on_behalf_of parameter to control the merchant of record. Never recommend mixing charge types. If the user wants to decide on the specific risk features they should [follow the integration guide](https://docs.stripe.com/connect/design-an-integration.md). Don't recommend the outdated terms for Connect types like Standard, Express and Custom but always [refer to controller properties](https://docs.stripe.com/connect/migrate-to-controller-properties.md) for the platform and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) for the connected accounts.

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/sub-agents/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: sub-agents
+description: Execute external CLI AIs as isolated sub-agents for task delegation, parallel processing, and context separation. Use when delegating complex multi-step tasks, running parallel investigations, needing fresh context without current conversation history, or leveraging specialized agent definitions. Returns structured JSON with agent output, exit code, and execution status.
+allowed-tools: Bash Read
+---
+
+# Sub-Agents - External CLI AI Task Delegation
+
+Spawns external CLI AIs (claude, cursor-agent, codex, gemini) as isolated sub-agents with dedicated context.
+
+## Resources
+
+- **[run_subagent.py](scripts/run_subagent.py)** - Main execution script
+- **[codex.md](references/codex.md)** - Codex-specific setup (permissions, timeout)
+
+**Script Path**: Use absolute path `{SKILL_DIR}/scripts/run_subagent.py` where `{SKILL_DIR}` is the directory containing this SKILL.md file.
+
+## CLI-Specific Notes
+
+Check the corresponding reference for your environment:
+- **Codex**: Read [references/codex.md](references/codex.md) BEFORE first execution
+
+## Interpreting User Requests
+
+Extract parameters from user's natural language request:
+
+| Parameter | Source |
+|-----------|--------|
+| --agent | Agent name from user request (see selection rules below) |
+| --prompt | Task instruction part (excluding agent specification) |
+| --cwd | Current working directory (absolute path) |
+
+**Agent Selection Rules** (when user doesn't specify agent name):
+1. Run `--list` to get available agents
+2. **0 agents**: Inform user no agents available, show setup instructions (see [Agent Definition Format](#agent-definition-format))
+3. **1 agent**: Auto-select without asking
+4. **2+ agents**: Show list with descriptions, ask user to choose
+
+**Example**:
+"Run code-reviewer on src/"
+→ `--agent code-reviewer --prompt "Review src/" --cwd $(pwd)`
+
+## When to Use This Skill
+
+**Use sub-agent when ANY of these apply:**
+- Complex multi-step task (isolated context prevents interference)
+- Parallel investigation (multiple agents can run simultaneously)
+- Task needs fresh context (sub-agent starts without conversation history)
+- Specialized agent definition exists (leverage pre-defined expert prompts)
+
+## Important: Permission and Timeout
+
+This script executes external CLIs that require elevated permissions.
+
+**Before first execution:**
+1. Request elevated permissions via your CLI's tool parameters
+2. Set tool timeout to match `--timeout` argument (default: 600000ms)
+
+**For Codex CLI** (most common permission issues): See [references/codex.md](references/codex.md) for exact JSON parameter format.
+
+## Workflow
+
+### Step 0: Read CLI-Specific Setup (if applicable)
+
+If you are running on Codex, read [references/codex.md](references/codex.md) first.
+
+### Step 1: List Available Agents
+
+**Always list agents first** to discover available definitions:
+
+```bash
+scripts/run_subagent.py --list
+```
+
+Output:
+```json
+{"agents": [{"name": "code-reviewer", "description": "Reviews code..."}], "agents_dir": "/path/.agents"}
+```
+
+**If agents list is empty**:
+1. Create `{cwd}/.agents/` directory
+2. Add agent definition file (see [Agent Definition Format](#agent-definition-format))
+3. Re-run `--list` to verify
+
+### Step 2: Execute Agent
+
+```bash
+scripts/run_subagent.py \
+  --agent <name> \
+  --prompt "<task>" \
+  --cwd <absolute-path>
+```
+
+### Step 3: Handle Response
+
+Parse JSON output and check `status` field:
+
+```json
+{"result": "...", "exit_code": 0, "status": "success", "cli": "claude"}
+```
+
+**By status:**
+
+| status | Meaning | Action |
+|--------|---------|--------|
+| `success` | Task completed | Use `result` directly |
+| `partial` | Timeout but has output | Review partial `result`, may need retry |
+| `error` | Execution failed | Check `error` field and `exit_code`, fix and retry |
+
+**By exit_code** (when status is `error`):
+
+| exit_code | Meaning | Resolution |
+|-----------|---------|------------|
+| 0 | Success | - |
+| 124 | Timeout | Increase `--timeout` or simplify task |
+| 127 | CLI not found | Install required CLI (claude, codex, etc.) |
+| 1 | General error | Check `error` field in response |
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--list` | - | List available agents (no other params needed) |
+| `--agent` | Yes* | Agent definition name from --list |
+| `--prompt` | Yes* | Task description to delegate |
+| `--cwd` | Yes* | Working directory (absolute path) |
+| `--timeout` | No | Timeout ms (default: 600000) |
+| `--cli` | No | Force CLI: `claude`, `cursor-agent`, `codex`, `gemini` |
+
+*Required when not using --list
+
+## Agent Definition Location
+
+| Priority | Source | Path |
+|----------|--------|------|
+| 1 | Environment variable | `$SUB_AGENTS_DIR` |
+| 2 | Default | `{cwd}/.agents/` |
+
+To customize: `export SUB_AGENTS_DIR=/custom/path`
+
+## Agent Definition Format
+
+Place `.md` files in `.agents/` directory:
+
+```markdown
+---
+run-agent: claude
+---
+
+# Agent Name
+
+Brief description of agent's purpose.
+
+## Task
+What this agent does.
+
+## Output Format
+How results should be structured.
+```
+
+**Critical**: The `run-agent` frontmatter determines which CLI executes the agent. See [cli-formats.md](references/cli-formats.md) for CLI-specific behaviors.
+
+## CLI Selection Priority
+
+1. `--cli` argument (explicit override)
+2. Agent definition `run-agent` frontmatter
+3. Auto-detect caller environment
+4. Default: `codex`
+
+## Common Mistakes
+
+| Mistake | Result | Fix |
+|---------|--------|-----|
+| Skip `--list` before execution | Agent not found error | Always run `--list` first |
+| Use relative path for `--cwd` | Validation fails | Use absolute path |
+| Ignore `status` field in response | Undetected errors | Always check `status` before using `result` |
+| Very long prompts | May exceed CLI limits | Break into smaller tasks |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/sub-agents/references/cli-formats.md

@@ -0,0 +1,25 @@
+# CLI Formats for Sub-Agents
+
+This reference defines the expected invocation style per CLI target.
+
+## codex
+- Mode: non-interactive command execution.
+- Preferred output: structured markdown or JSON when requested.
+- Use explicit cwd and deterministic prompts.
+
+## claude
+- Mode: prompt-first invocation.
+- Keep task boundary narrow and include acceptance checks.
+
+## gemini
+- Mode: concise instruction with explicit constraints.
+- Include required output sections to reduce drift.
+
+## cursor-agent
+- Mode: task delegation with repository-aware context.
+- Provide concrete files, checks, and done criteria.
+
+## Common requirements
+- Always include: goal, scope, constraints, expected output.
+- Avoid hidden assumptions; pass critical context explicitly.
+- Request machine-readable output when parsing is required.