@cubis/foundry 0.3.63 → 0.3.65

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

@@ -0,0 +1,49 @@
+# Codex-Specific Notes
+
+Read this reference when executing sub-agents from Codex CLI.
+
+## Where to Set Parameters
+
+Codex CLI uses **Bash tool call parameters** for permissions and timeout. These are NOT command-line arguments—they are tool invocation settings.
+
+```json
+{
+  "tool": "Bash",
+  "parameters": {
+    "command": "/path/to/scripts/run_subagent.py --agent <name> --prompt \"<task>\" --cwd /absolute/path --timeout 600000",
+    "timeout_ms": 600000,
+    "sandbox_permissions": "require_escalated"
+  }
+}
+```
+
+## Permission: Request Escalated BEFORE First Execution
+
+Sub-agent CLIs require access to session files outside the sandbox.
+
+**Setting:** `"sandbox_permissions": "require_escalated"` in Bash tool parameters.
+
+Always request escalated permissions on the first run. Sandboxed runs fail with:
+```
+Error: Fatal error: Codex cannot access session files at ~/.codex/sessions (permission denied)
+```
+
+## Timeout: Match timeout_ms with --timeout
+
+Codex's Bash tool has its own timeout (`timeout_ms`), separate from the script's `--timeout` argument.
+
+**Setting:** `"timeout_ms": 600000` in Bash tool parameters (must match `--timeout` value).
+
+| --timeout | timeout_ms | Result |
+|-----------|------------|--------|
+| Not set | Not set | Script: 600000ms, Tool: ~10000ms → Tool kills script early |
+| 600000 | Not set | Same problem |
+| 600000 | 600000 | Correct: both aligned |
+
+## Common Errors
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `Operation not permitted (os error 1)` | Sandbox restriction | Use `sandbox_permissions:"require_escalated"` |
+| `(no output)` after few seconds | Tool timeout too short | Set `timeout_ms` to match `--timeout` |
+| `permission denied` on session files | Need elevated permissions | Request escalated permissions first |

package/workflows/workflows/agent-environment-setup/platforms/claude/skills/sub-agents/scripts/run_subagent.py

@@ -0,0 +1,513 @@
+#!/usr/bin/env python3
+"""
+run_subagent.py - Execute external CLI AIs as sub-agents
+
+Usage:
+    scripts/run_subagent.py --agent <name> --prompt "<task>" --cwd <path>
+    scripts/run_subagent.py --list
+
+Supported CLIs: claude, cursor-agent, codex, gemini
+
+Environment:
+    SUB_AGENTS_DIR: Override default agents directory ({cwd}/.agents/)
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from typing import Optional, Tuple
+# =============================================================================
+# Agent Loader - frontmatter parsing and system context extraction
+# =============================================================================
+
+
+def parse_frontmatter(content: str) -> tuple[dict, str]:
+    """
+    Parse YAML frontmatter from markdown content.
+    Returns (frontmatter_dict, body_without_frontmatter)
+    """
+    pattern = r"^---\s*\n(.*?)\n---\s*\n(.*)$"
+    match = re.match(pattern, content, re.DOTALL)
+
+    if not match:
+        return {}, content
+
+    frontmatter_raw = match.group(1)
+    body = match.group(2)
+
+    # Simple YAML parsing (key: value only, no nested structures)
+    frontmatter = {}
+    for line in frontmatter_raw.split("\n"):
+        line = line.strip()
+        if ":" in line and not line.startswith("#"):
+            key, value = line.split(":", 1)
+            frontmatter[key.strip()] = value.strip().strip("\"'")
+
+    return frontmatter, body
+
+
+def extract_description(body: str) -> str:
+    """Extract description from first non-heading line of body."""
+    for line in body.strip().split("\n"):
+        line = line.strip()
+        if line and not line.startswith("#"):
+            return line[:100]
+    return ""
+
+
+def load_agent(agents_dir: str, agent_name: str) -> Tuple[Optional[str], str, str]:
+    """
+    Load agent definition file and extract run-agent setting.
+    Returns (run_agent_cli, system_context, description)
+    """
+    agents_path = Path(agents_dir)
+
+    # Try .md first, then .txt
+    for ext in [".md", ".txt"]:
+        agent_file = agents_path / f"{agent_name}{ext}"
+        if agent_file.exists():
+            content = agent_file.read_text(encoding="utf-8")
+            frontmatter, body = parse_frontmatter(content)
+
+            run_agent = frontmatter.get("run-agent")
+            description = extract_description(body)
+
+            return run_agent, body.strip(), description
+
+    raise FileNotFoundError(f"Agent definition not found: {agent_name}")
+
+
+def list_agents(agents_dir: str) -> list[dict]:
+    """
+    List all available agents in the directory.
+    Returns list of {"name": str, "description": str}
+    """
+    agents_path = Path(agents_dir)
+    agents = []
+    seen_names: set[str] = set()
+
+    if not agents_path.exists():
+        return agents
+
+    for ext in [".md", ".txt"]:
+        for agent_file in agents_path.glob(f"*{ext}"):
+            name = agent_file.stem
+            # Skip if already added (prefer .md over .txt)
+            if name in seen_names:
+                continue
+            seen_names.add(name)
+
+            try:
+                content = agent_file.read_text(encoding="utf-8")
+                _, body = parse_frontmatter(content)
+                description = extract_description(body)
+                agents.append({"name": name, "description": description})
+            except Exception:
+                agents.append({"name": name, "description": ""})
+
+    return sorted(agents, key=lambda a: a["name"])
+
+
+def get_agents_dir(args_agents_dir: Optional[str], args_cwd: Optional[str]) -> str:
+    """
+    Determine agents directory.
+    Priority: --agents-dir > SUB_AGENTS_DIR > {cwd}/.agents/
+    """
+    if args_agents_dir:
+        return args_agents_dir
+
+    env_dir = os.environ.get("SUB_AGENTS_DIR")
+    if env_dir:
+        return env_dir
+
+    if args_cwd:
+        return str(Path(args_cwd) / ".agents")
+
+    # Fallback for --list without --cwd
+    return str(Path.cwd() / ".agents")
+
+
+# =============================================================================
+# CLI Resolver - determine which CLI to use
+# =============================================================================
+
+
+def detect_caller_cli() -> Optional[str]:
+    """
+    Detect which CLI is calling this script based on environment.
+    Returns: 'claude', 'cursor-agent', 'codex', 'gemini', or None
+    """
+    # Check common environment indicators
+    if os.environ.get("CLAUDE_CODE"):
+        return "claude"
+    if os.environ.get("CURSOR_AGENT"):
+        return "cursor-agent"
+    if os.environ.get("CODEX_CLI"):
+        return "codex"
+    if os.environ.get("GEMINI_CLI"):
+        return "gemini"
+
+    # Check parent process name (best effort)
+    try:
+        ppid = os.getppid()
+        cmdline_path = f"/proc/{ppid}/cmdline"
+        if os.path.exists(cmdline_path):
+            with open(cmdline_path) as f:
+                cmdline = f.read().lower()
+                if "claude" in cmdline:
+                    return "claude"
+                if "cursor" in cmdline:
+                    return "cursor-agent"
+                if "codex" in cmdline:
+                    return "codex"
+                if "gemini" in cmdline:
+                    return "gemini"
+    except Exception:
+        pass
+
+    return None
+
+
+def resolve_cli(frontmatter_cli: Optional[str], default: str = "codex") -> str:
+    """
+    Resolve which CLI to use.
+    Priority: frontmatter > caller detection > default
+    """
+    if frontmatter_cli:
+        valid_clis = {"claude", "cursor-agent", "codex", "gemini"}
+        if frontmatter_cli in valid_clis:
+            return frontmatter_cli
+
+    detected = detect_caller_cli()
+    if detected:
+        return detected
+
+    return default
+
+
+# =============================================================================
+# Stream Processor - parse CLI output
+# =============================================================================
+
+
+class StreamProcessor:
+    """Process streaming JSON output from various CLIs."""
+
+    def __init__(self):
+        self.result_json = None
+        self.gemini_parts = []
+        self.codex_messages = []
+        self.is_gemini = False
+        self.is_codex = False
+
+    def process_line(self, line: str) -> bool:
+        """
+        Process a line from CLI output.
+        Returns True when result is ready, False to continue.
+        """
+        line = line.strip()
+        if not line or self.result_json is not None:
+            return False
+
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            return False
+
+        # Detect Gemini format
+        if data.get("type") == "init":
+            self.is_gemini = True
+            return False
+
+        # Detect Codex format
+        if data.get("type") == "thread.started":
+            self.is_codex = True
+            return False
+
+        # Gemini: accumulate assistant messages
+        if self.is_gemini and data.get("type") == "message" and data.get("role") == "assistant":
+            content = data.get("content", "")
+            if isinstance(content, str):
+                self.gemini_parts.append(content)
+            return False
+
+        # Codex: accumulate agent_message items
+        if self.is_codex and data.get("type") == "item.completed":
+            item = data.get("item", {})
+            if item.get("type") == "agent_message" and isinstance(item.get("text"), str):
+                self.codex_messages.append(item["text"])
+            return False
+
+        # Codex: turn.completed signals end
+        if self.is_codex and data.get("type") == "turn.completed":
+            self.result_json = {
+                "type": "result",
+                "result": "\n".join(self.codex_messages),
+                "status": "success",
+            }
+            return True
+
+        # Result type signals completion
+        if data.get("type") == "result":
+            if self.is_gemini:
+                self.result_json = {
+                    "type": "result",
+                    "result": "".join(self.gemini_parts),
+                    "status": data.get("status", "success"),
+                }
+            else:
+                self.result_json = data
+            return True
+
+        # Fallback: first valid JSON without type field
+        if "type" not in data:
+            self.result_json = data
+            return True
+
+        return False
+
+    def get_result(self):
+        return self.result_json
+
+
+# =============================================================================
+# Agent Executor - run CLI and capture output
+# =============================================================================
+
+
+def build_command(cli: str, prompt: str) -> tuple[str, list]:
+    """Build command and arguments for the specified CLI."""
+
+    if cli == "codex":
+        return "codex", ["exec", "--json", prompt]
+
+    if cli == "claude":
+        return "claude", ["--output-format", "stream-json", "--verbose", "-p", prompt]
+
+    if cli == "gemini":
+        return "gemini", ["--output-format", "stream-json", "-p", prompt]
+
+    if cli == "cursor-agent":
+        args = ["--output-format", "json", "-p", prompt]
+        api_key = os.environ.get("CLI_API_KEY")
+        if api_key:
+            args.extend(["-a", api_key])
+        return "cursor-agent", args
+
+    raise ValueError(f"Unknown CLI: {cli}")
+
+
+def execute_agent(
+    cli: str, system_context: str, prompt: str, cwd: str, timeout: int = 600000
+) -> dict:
+    """
+    Execute agent CLI and return result.
+
+    Returns: {
+        "result": str,
+        "exit_code": int,
+        "status": "success" | "partial" | "error",
+        "cli": str
+    }
+    """
+    # Format prompt with system context
+    formatted_prompt = f"[System Context]\n{system_context}\n\n[User Prompt]\n{prompt}"
+
+    command, args = build_command(cli, formatted_prompt)
+    timeout_sec = timeout / 1000
+
+    try:
+        process = subprocess.Popen(
+            [command] + args,
+            cwd=cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+
+        processor = StreamProcessor()
+        stdout_lines = []
+
+        try:
+            # Read stdout line by line
+            for line in iter(process.stdout.readline, ""):
+                stdout_lines.append(line)
+                if processor.process_line(line):
+                    process.terminate()
+                    break
+
+            # Wait for process to finish
+            try:
+                _, stderr = process.communicate(timeout=timeout_sec)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                _, stderr = process.communicate()
+
+                result = processor.get_result()
+                return {
+                    "result": result.get("result", "") if result else "",
+                    "exit_code": 124,
+                    "status": "partial" if result else "error",
+                    "cli": cli,
+                    "error": f"Timeout after {timeout}ms",
+                }
+
+            result = processor.get_result()
+            exit_code = process.returncode or 0
+
+            # Determine status
+            if exit_code == 0 or exit_code in (143, -15) and result:
+                status = "success"
+            elif result:
+                status = "partial"
+            else:
+                status = "error"
+
+            response = {
+                "result": result.get("result", "") if result else "".join(stdout_lines),
+                "exit_code": exit_code,
+                "status": status,
+                "cli": cli,
+            }
+            if status == "error":
+                error_msg = f"CLI exited with code {exit_code}"
+                if stderr and stderr.strip():
+                    error_msg += f": {stderr.strip()}"
+                response["error"] = error_msg
+            return response
+
+        except Exception as e:
+            process.kill()
+            result = processor.get_result()
+            return {
+                "result": result.get("result", "") if result else "",
+                "exit_code": 1,
+                "status": "error",
+                "cli": cli,
+                "error": str(e),
+            }
+
+    except FileNotFoundError:
+        return {
+            "result": "",
+            "exit_code": 127,
+            "status": "error",
+            "cli": cli,
+            "error": f"CLI not found: {command}",
+        }
+    except Exception as e:
+        return {"result": "", "exit_code": 1, "status": "error", "cli": cli, "error": str(e)}
+
+
+# =============================================================================
+# Main
+# =============================================================================
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Execute external CLI AIs as sub-agents")
+    parser.add_argument("--list", action="store_true", help="List available agents")
+    parser.add_argument("--agent", help="Agent definition name")
+    parser.add_argument("--prompt", help="Task prompt")
+    parser.add_argument("--cwd", help="Working directory (absolute path)")
+    parser.add_argument("--agents-dir", help="Directory containing agent definitions")
+    parser.add_argument(
+        "--timeout", type=int, default=600000, help="Timeout in ms (default: 600000)"
+    )
+    parser.add_argument("--cli", help="Force specific CLI (claude, cursor-agent, codex, gemini)")
+
+    args = parser.parse_args()
+
+    # Handle --list
+    if args.list:
+        agents_dir = get_agents_dir(args.agents_dir, args.cwd)
+        agents = list_agents(agents_dir)
+        print(json.dumps({"agents": agents, "agents_dir": agents_dir}, ensure_ascii=False))
+        sys.exit(0)
+
+    # Validate required args for execution
+    if not args.agent:
+        print(
+            json.dumps(
+                {"result": "", "exit_code": 1, "status": "error", "error": "--agent is required"}
+            )
+        )
+        sys.exit(1)
+
+    if not args.prompt:
+        print(
+            json.dumps(
+                {"result": "", "exit_code": 1, "status": "error", "error": "--prompt is required"}
+            )
+        )
+        sys.exit(1)
+
+    if not args.cwd:
+        print(
+            json.dumps(
+                {"result": "", "exit_code": 1, "status": "error", "error": "--cwd is required"}
+            )
+        )
+        sys.exit(1)
+
+    # Validate cwd
+    if not os.path.isabs(args.cwd):
+        print(
+            json.dumps(
+                {
+                    "result": "",
+                    "exit_code": 1,
+                    "status": "error",
+                    "error": "cwd must be an absolute path",
+                }
+            )
+        )
+        sys.exit(1)
+
+    if not os.path.isdir(args.cwd):
+        print(
+            json.dumps(
+                {
+                    "result": "",
+                    "exit_code": 1,
+                    "status": "error",
+                    "error": f"cwd does not exist: {args.cwd}",
+                }
+            )
+        )
+        sys.exit(1)
+
+    # Determine agents directory
+    agents_dir = get_agents_dir(args.agents_dir, args.cwd)
+
+    # Load agent definition
+    try:
+        run_agent_cli, system_context, _ = load_agent(agents_dir, args.agent)
+    except FileNotFoundError as e:
+        print(json.dumps({"result": "", "exit_code": 1, "status": "error", "error": str(e)}))
+        sys.exit(1)
+
+    # Resolve CLI
+    cli = args.cli or resolve_cli(run_agent_cli)
+
+    # Execute
+    result = execute_agent(
+        cli=cli,
+        system_context=system_context,
+        prompt=args.prompt,
+        cwd=args.cwd,
+        timeout=args.timeout,
+    )
+
+    print(json.dumps(result, ensure_ascii=False))
+    sys.exit(0 if result["status"] == "success" else 1)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,109 @@
+---
+name: systematic-debugging
+description: 4-phase systematic debugging methodology with root cause analysis and evidence-based verification. Use when debugging complex issues.
+allowed-tools: Read, Glob, Grep
+---
+
+# Systematic Debugging
+
+> Source: obra/superpowers
+
+## Overview
+This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
+
+## 4-Phase Debugging Process
+
+### Phase 1: Reproduce
+Before fixing, reliably reproduce the issue.
+
+```markdown
+## Reproduction Steps
+1. [Exact step to reproduce]
+2. [Next step]
+3. [Expected vs actual result]
+
+## Reproduction Rate
+- [ ] Always (100%)
+- [ ] Often (50-90%)
+- [ ] Sometimes (10-50%)
+- [ ] Rare (<10%)
+```
+
+### Phase 2: Isolate
+Narrow down the source.
+
+```markdown
+## Isolation Questions
+- When did this start happening?
+- What changed recently?
+- Does it happen in all environments?
+- Can we reproduce with minimal code?
+- What's the smallest change that triggers it?
+```
+
+### Phase 3: Understand
+Find the root cause, not just symptoms.
+
+```markdown
+## Root Cause Analysis
+### The 5 Whys
+1. Why: [First observation]
+2. Why: [Deeper reason]
+3. Why: [Still deeper]
+4. Why: [Getting closer]
+5. Why: [Root cause]
+```
+
+### Phase 4: Fix & Verify
+Fix and verify it's truly fixed.
+
+```markdown
+## Fix Verification
+- [ ] Bug no longer reproduces
+- [ ] Related functionality still works
+- [ ] No new issues introduced
+- [ ] Test added to prevent regression
+```
+
+## Debugging Checklist
+
+```markdown
+## Before Starting
+- [ ] Can reproduce consistently
+- [ ] Have minimal reproduction case
+- [ ] Understand expected behavior
+
+## During Investigation
+- [ ] Check recent changes (git log)
+- [ ] Check logs for errors
+- [ ] Add logging if needed
+- [ ] Use debugger/breakpoints
+
+## After Fix
+- [ ] Root cause documented
+- [ ] Fix verified
+- [ ] Regression test added
+- [ ] Similar code checked
+```
+
+## Common Debugging Commands
+
+```bash
+# Recent changes
+git log --oneline -20
+git diff HEAD~5
+
+# Search for pattern
+grep -r "errorPattern" --include="*.ts"
+
+# Check logs
+pm2 logs app-name --err --lines 100
+```
+
+## Anti-Patterns
+
+❌ **Random changes** - "Maybe if I change this..."
+❌ **Ignoring evidence** - "That can't be the cause"
+❌ **Assuming** - "It must be X" without proof
+❌ **Not reproducing first** - Fixing blindly
+❌ **Stopping at symptoms** - Not finding root cause