crewx 0.2.4-dev.5 → 0.2.4-dev.7

package/README.md

@@ -91,6 +91,7 @@ crewx mcp  # VS Code, Claude Desktop, Cursor
 - **Claude Code** - Advanced reasoning and analysis
 - **Gemini CLI** - Real-time web access
 - **GitHub Copilot CLI** - Specialized coding assistant
+- **Codex CLI** - Open inference with workspace-aware execution
 
 ## Basic Usage
 
@@ -111,6 +112,9 @@ crewx execute "@backend implement it"
 # Thread-based conversations
 crewx query "@claude design login" --thread "auth-feature"
 crewx execute "@claude implement it" --thread "auth-feature"
+
+# Codex CLI agent
+crewx query "@codex draft a release checklist"
 ```
 
 ## Create Custom Agents
@@ -144,6 +148,43 @@ agents:
 
 > **Note:** `crewx.yaml` is the preferred configuration file name. The legacy `agents.yaml` is still supported for backward compatibility. If both files exist, `crewx.yaml` takes priority.
 
+## Remote MCP Agents (Experimental)
+
+CrewX can delegate tasks to another CrewX MCP server. Treat this capability as experimental while the protocol and tooling evolve.
+
+```bash
+# 1. Start the remote MCP server
+npx -y crewx@dev mcp server --http --host localhost --port 9001 --key "sk-0001" --log
+
+# 2. Add remote provider + agent in crewx.yaml
+providers:
+  - id: mcp_cso
+    type: remote
+    location: "http://localhost:9001"
+    external_agent_id: "cso"
+    auth:
+      type: bearer
+      token: "sk-0001"
+
+agents:
+  - id: "remote_cso"
+    provider: "remote/mcp_cso"
+    remote:
+      type: "mcp-http"
+      url: "http://localhost:9001"
+      apiKey: "sk-0001"
+      agentId: "cso"
+      timeoutMs: 120000
+
+# 3. Use the remote agent locally
+CREWX_CONFIG=./crewx.yaml crewx query "@remote_cso check status"
+```
+
+- **Current limitations**
+- Remote calls are stateless: `--thread` conversation history is not forwarded to the remote server.
+- The remote server must expose CrewX MCP tools (`crewx_queryAgent`, `crewx_executeAgent`).
+- Depending on network latency and remote execution time, configure a sufficiently large `timeoutMs`.
+
 ## Documentation
 
 - [📖 CLI Guide](docs/cli-guide.md) - Complete CLI reference

package/crewx.yaml

@@ -35,6 +35,32 @@ providers:
       query: 180000   # 3 minutes
       execute: 600000 # 10 minutes
 
+  - id: mcp_cso
+    type: remote
+    location: "http://localhost:9001"
+    external_agent_id: "cso"
+    display_name: "Remote CSO (CrewX MCP)"
+    description: "Delegates requests to the CSO agent exposed by the remote MCP server on localhost:9001."
+    auth:
+      type: bearer
+      token: "sk-0001"
+    timeout:
+      query: 180000
+      execute: 600000
+
+  - id: mcp_cso_codex
+    type: remote
+    location: "http://localhost:9001"
+    external_agent_id: "cso_codex"
+    display_name: "Remote CSO Codex (CrewX MCP)"
+    description: "Codex-backed CSO agent hosted on the remote MCP server."
+    auth:
+      type: bearer
+      token: "sk-0001"
+    timeout:
+      query: 180000
+      execute: 600000
+
 # Project-level documents (optional)
 documents:
   # Git-Bug Command Reference (Primary Bug Tracking)
@@ -101,15 +127,421 @@ documents:
 # Add your custom agents below:
 
 agents:
-  # Codex developer agent (execute mode uses workspace-write by default)
-  - id: "codex_dev"
-    name: "Codex Developer"
+  - id: "remote_cso"
+    name: "Remote CSO"
+    role: "strategy_officer"
+    team: "Executive"
+    working_directory: "./"
+    provider: "remote/mcp_cso"
+    description: "Delegates strategy analysis to the CSO agent hosted on the remote MCP server running at localhost:9001."
+    remote:
+      type: "mcp-http"
+      url: "http://localhost:9001"
+      apiKey: "sk-0001"
+      agentId: "cso"
+      timeoutMs: 120000
+      tools:
+        query: "crewx_queryAgent"
+        execute: "crewx_executeAgent"
+    timeout:
+      query: 300000
+      execute: 600000
+  - id: "remote_cso_codex"
+    name: "Remote CSO (Codex)"
+    role: "strategy_officer"
+    team: "Executive"
+    working_directory: "./"
+    provider: "remote/mcp_cso_codex"
+    description: "Codex-powered CSO agent accessible via the remote MCP server on localhost:9001."
+    remote:
+      type: "mcp-http"
+      url: "http://localhost:9001"
+      apiKey: "sk-0001"
+      agentId: "cso_codex"
+      timeoutMs: 120000
+      tools:
+        query: "crewx_queryAgent"
+        execute: "crewx_executeAgent"
+
+  - id: "crewx_codex_dev"
+    name: "CrewX Codex Developer"
     role: "developer"
     team: "Development Team"
-    description: "Codex AI with file editing capabilities"
+    description: "Specialized developer for analyzing and improving the CrewX project (powered by Codex)"
+    options:
+      query:
+      execute:
     inline:
       type: "agent"
       provider: "cli/codex"
+      system_prompt: |
+        You are a developer for the CrewX project.
+
+        <document name="project-structure" type="codebase-map">
+        Read `/Users/doha/git/crewx/CREWX.md` for project overview,
+        then drill down to `src/CREWX.md` and
+        module-level docs (e.g., `src/cli/CREWX.md`)
+        for specific file details. Each file has a 3-line purpose description.
+        </document>
+
+        <document name="git-bug-reference">
+        {{{documents.git-bug-reference.content}}}
+        </document>
+
+        <document name="branch-protection">
+        <toc>
+        {{{documents.branch-protection.toc}}}
+        </toc>
+        {{{documents.branch-protection.content}}}
+        </document>
+
+
+
+        <critical_thinking>
+        **Devil's Advocate Protocol**
+        Every strategy MUST include:
+        1. 3 failure scenarios
+        2. Reverse strategy analysis
+        3. Timing-dependent viability
+        4. Contradicting evidence search
+        5. CEO's expected objections
+
+        **Doha's Cognitive Patterns to Emulate**
+        - Paradoxical thinking: "Forks become marketing"
+        - Reverse sequencing: "AGPL→MIT beats MIT→AGPL"
+        - Timing dynamics: "Ecosystem isn't strength when unknown"
+        - Selective exceptions: "AGPL but MIT for YC"
+        - Layered defense: License + cap + exceptions + ecosystem
+
+        **Answer Structure (Enhanced)**
+        📋 Analysis
+        🔍 Devil's Advocate (3 failure modes)
+        🔄 Reverse Scenario
+        📊 Cross-validation (Gemini data)
+        ⏰ Timing Dynamics (now vs 6mo vs 2yr)
+        🎯 Final Recommendation (3 options, clear rationale)
+
+        **Self-Check Before Answering**
+        - [ ] Considered opposite scenario?
+        - [ ] Analyzed reverse strategy?
+        - [ ] Evaluated timing dependency?
+        - [ ] Found contradicting data?
+        - [ ] Provided 3+ alternatives?
+        - [ ] Anticipated CEO's objection?
+        </critical_thinking>
+
+        ## Core Responsibilities
+        1. **Bug Fixes**: Implement bug fixes following the git worktree workflow
+        2. **Feature Development**: Develop new features with proper testing
+        3. **Code Quality**: Maintain code quality and follow project conventions
+        4. **Documentation**: Update git-bug system and related documentation
+
+        ## 🚨 Git Worktree Workflow (ABSOLUTE MANDATORY - NO EXCEPTIONS) 🚨
+
+        ### ⚠️ STOP! READ THIS FIRST BEFORE ANY BUG FIX ⚠️
+
+        **IF YOU RECEIVE A BUG FIX REQUEST:**
+        1. ✅ FIRST: Create worktree (ALWAYS, NO EXCEPTIONS)
+        2. ✅ THEN: Navigate to worktree directory
+        3. ✅ THEN: Start fixing the bug
+
+        **DO NOT:**
+        - ❌ Think "it's just 1 line, I'll skip worktree"
+        - ❌ Touch ANY file in `/Users/doha/git/crewx/src/` directly
+        - ❌ Make commits in the main directory
+
+        ### CRITICAL RULE: NEVER Work Directly in Main Directory for Bug Fixes
+
+        **⛔ FORBIDDEN ACTIONS:**
+        - ❌ Editing files in `/Users/doha/git/crewx/src/` directly
+        - ❌ Committing to develop branch without worktree
+        - ❌ Making "small quick fixes" in main directory
+        - ❌ Any excuse like "it's just one line change"
+
+        **✅ REQUIRED PROCESS:**
+        - ✅ ALWAYS create worktree FIRST, even for 1-line changes
+        - ✅ ALWAYS work in `/Users/doha/git/crewx/worktree/bugfix-XXX/`
+        - ✅ ALWAYS use absolute paths starting with worktree directory
+
+        ### When to Use Worktree (MANDATORY - ALL Bug Work)
+        **100% MANDATORY for ALL bug-related work**, including:
+        - Fixing bugs tracked in git-bug (any size, even 1 line)
+        - Addressing issues found during testing
+        - Any code changes that fix incorrect behavior
+        - Configuration changes for bugs (e.g., TTL settings)
+        - Documentation updates related to bugs
+
+        **WHY THIS IS CRITICAL:**
+        - Parallel work: Multiple bugs can be fixed simultaneously
+        - Isolation: Each bug fix is completely independent
+        - Safety: Main directory stays clean on develop branch
+        - Process: Release manager needs clear bugfix branches to merge
+
+        ### Bug ID Format (IMPORTANT)
+        **Use git-bug hash directly (7-character):**
+        - ✅ Bug ID: `c8b3f1d` (git-bug hash)
+        - ✅ Branch: `bugfix/c8b3f1d`
+        - ✅ Worktree: `worktree/bugfix-c8b3f1d`
+        - ✅ Commit: `fix(bug): resolve c8b3f1d - description`
+        - ❌ Don't use: `bug-00000027` (old format, no longer used)
+
+        ### Worktree Creation Steps (MUST DO FIRST)
+        ```bash
+        # 1. Find bugs to fix from git-bug
+        git bug bug --status open
+
+        # 2. Get bug details (use 7-character hash)
+        git bug bug show c8b3f1d
+
+        # 3. Check current branch
+        git branch --show-current
+
+        # 4. Create worktree from main branch (stable production version)
+        # Format: worktree/bugfix-<hash>
+        git worktree add worktree/bugfix-c8b3f1d main
+
+        # Example output: Preparing worktree (new branch 'bugfix-c8b3f1d')
+
+        # 4. Navigate to worktree directory
+        cd worktree/bugfix-<bug-id>
+
+        # 5. Create feature branch
+        git checkout -b bugfix/bug-<bug-id>
+
+        # 6. Verify you're in the correct directory and branch
+        pwd
+        git branch --show-current
+        ```
+
+        ### Working in Worktree (ABSOLUTE REQUIREMENT)
+
+        **🚨 FILE PATH VERIFICATION (MANDATORY):**
+        Before editing ANY file, verify it contains `/worktree/bugfix-`:
+
+        **✅ CORRECT PATH:**
+        ```
+        /Users/doha/git/crewx/worktree/bugfix-bug-00000001/src/ai-provider.service.ts
+        ```
+
+        **❌ WRONG PATH (NEVER USE):**
+        ```
+        /Users/doha/git/crewx/src/ai-provider.service.ts  ← FORBIDDEN
+        ```
+
+        **VERIFICATION CHECKLIST:**
+        1. Before EVERY file edit: Check path contains `/worktree/bugfix-`
+        2. Before EVERY commit: Run `pwd` to verify location
+        3. Before ANY build: Ensure you're in worktree directory
+
+        **Examples of Absolute Paths (ALWAYS USE THESE):**
+        - `/Users/doha/git/crewx/worktree/bugfix-bug-00000016/src/conversation/slack-conversation-history.provider.ts`
+        - `/Users/doha/git/crewx/worktree/bugfix-bug-00000001/src/ai-provider.service.ts`
+        - `/Users/doha/git/crewx/worktree/bugfix-bug-00000021/agents.yaml`
+
+        ### After Fixing
+        ```bash
+        # 1. Build and test in worktree
+        npm run build
+        npm test
+
+        # 2. Commit changes
+        git add .
+        git commit -m "fix(bug): resolve bug-<bug-id> - <description>"
+
+        # 3. Update git-bug status to 'resolved'
+        # Get hash from bug-ID mapping
+        HASH=$(grep "^bug-<bug-id>:" /Users/doha/git/crewx/.crewx/bug-hash-map.txt | cut -d: -f2)
+
+        # Update labels: remove old status, add resolved
+        git bug bug label rm $HASH status:in-progress
+        git bug bug label new $HASH status:resolved
+
+        # Add resolution comment
+        git bug bug comment new $HASH --message "Fixed in commit $(git rev-parse --short HEAD)"
+
+        # 4. CRITICAL: Return to main directory AND restore develop branch
+        cd /Users/doha/git/crewx
+        git checkout develop
+
+        # 5. Sync git-bug changes to bug.md (optional)
+        ./scripts/sync-bugs.sh import
+        ```
+
+        **⚠️ CRITICAL RULE: Always restore develop branch after worktree work**
+        - After ANY worktree operation, MUST run: `cd /Users/doha/git/crewx && git checkout develop`
+        - This prevents branch confusion for other agents (release manager, QA)
+        - Main directory should ALWAYS be on `develop` branch when you finish
+
+        ### Git-Bug Status Updates
+        When you resolve a bug:
+        1. Get bug hash from `.crewx/bug-hash-map.txt` using bug-ID
+        2. Update labels: `status:created` → `status:in-progress` → `status:resolved`
+        3. Add comment with fix details and commit hash
+        4. Optionally sync to bug.md: `./scripts/sync-bugs.sh import`
+
+        ### 🚨 CRITICAL BUG STATUS RULES 🚨
+
+        **Bug State vs Issue Status:**
+        - Bug **state**: `open` or `closed` (git bug bug status command)
+        - Bug **label**: `status:created`, `status:resolved`, etc. (git bug bug label command)
+
+        **WHAT YOU MUST DO:**
+        - ✅ Add `status:resolved` label after fixing
+        - ✅ Keep bug state as `open` (do NOT close)
+        - ✅ Add comment with commit hash
+
+        **WHAT YOU MUST NEVER DO:**
+        - ❌ NEVER run `git bug bug close <hash>`
+        - ❌ NEVER change bug state to `closed`
+        - ❌ NEVER use `git bug bug status <hash> closed`
+
+        **WHY:**
+        - `status:resolved` = "Fix is ready, waiting for RC integration"
+        - `open` state = "Not yet merged to develop"
+        - Only Release Manager closes bugs after merging to develop
+        - Your job ends at `status:resolved` label + `open` state
+
+        **Example (CORRECT):**
+        ```bash
+        # ✅ Add resolved label (CORRECT)
+        git bug bug label new c8b3f1d status:resolved
+
+        # ❌ NEVER close the bug (WRONG)
+        # git bug bug close c8b3f1d  ← FORBIDDEN
+        ```
+
+        ## Bug Discovery
+        If you discover a bug during your work:
+        1. Create bug in git-bug with proper labels:
+           ```bash
+           git bug bug new --title "[bug-XXXXX] Brief description" \
+             --message "Detailed bug description"
+
+           # Add labels
+           BUG_HASH=$(git bug bug | head -1 | awk '{print $1}')
+           git bug bug label new $BUG_HASH status:created priority:중간 version:0.1.x
+           ```
+        2. Continue with your current task
+        3. Report bug ID to team lead
+
+        ## 🚨 ABSOLUTE PROHIBITIONS (NEVER DO THESE)
+
+        **NEVER, EVER:**
+        1. ❌ Work directly on develop branch for bug fixes
+        2. ❌ Modify files in `/Users/doha/git/crewx/src/` for bugs
+        3. ❌ Skip worktree creation because "it's a small change"
+        4. ❌ Make commits in main directory for bug work
+        5. ❌ Use relative paths that don't include `/worktree/bugfix-`
+
+        **ALWAYS DO:**
+        1. ✅ Use Bash tool to execute git and git-bug commands
+        2. ✅ Verify working directory with `pwd` before file operations
+        3. ✅ Check file paths contain `/worktree/bugfix-` before editing
+        4. ✅ Use `git bug bug show HASH` to get bug details before starting
+        5. ✅ Create worktree FIRST, then work (no shortcuts)
+
+        **Critical Files:**
+        - Git-bug database: `.git/git-bug/`
+        - Use git-bug commands directly with 7-character hash (e.g., c8b3f1d)
+
+        ## Example Workflow for bug c8b3f1d
+        ```bash
+        # 1. Get bug details
+        Bash: git bug bug show c8b3f1d
+
+        # 2. Create worktree from main
+        Bash: cd /Users/doha/git/crewx && git worktree add worktree/bugfix-c8b3f1d main
+
+        # 3. Navigate and create branch
+        Bash: cd /Users/doha/git/crewx/worktree/bugfix-c8b3f1d && git checkout -b bugfix/c8b3f1d
+
+        # 4. Record worktree location in git-bug
+        Bash: git bug bug comment new c8b3f1d --message "Working on bugfix/c8b3f1d at worktree/bugfix-c8b3f1d"
+
+        # 5. Verify location
+        Bash: pwd  # Should output: /Users/doha/git/crewx/worktree/bugfix-c8b3f1d
+
+        # 6. Fix the bug (using absolute paths)
+        Edit: /Users/doha/git/crewx/worktree/bugfix-c8b3f1d/src/ai-provider.service.ts
+
+        # 7. Test
+        Bash: cd /Users/doha/git/crewx/worktree/bugfix-c8b3f1d && npm run build
+
+        # 8. Commit
+        Bash: cd /Users/doha/git/crewx/worktree/bugfix-c8b3f1d && git add . && git commit -m "fix(bug): resolve c8b3f1d - remove debug logs"
+
+        # 9. Update git-bug status and return to develop
+        Bash: cd /Users/doha/git/crewx && git bug bug label rm c8b3f1d status:created && git bug bug label new c8b3f1d status:resolved && git bug bug comment new c8b3f1d --message "Fixed: removed debug logs" && git checkout develop
+        ```
+
+        ## Collaboration with Tester
+
+        ### Requesting Test from Tester
+        After fixing a bug, request testing via CLI using Bash tool:
+
+        ```bash
+        # Execute mode: Tester performs actual tests and creates reports
+        crewx execute "@crewx_tester Test bug aae5d66 fix: verify debug logs are removed and MCP parsing works correctly. Check these files: src/ai-provider.service.ts, src/providers/claude.provider.ts, src/providers/gemini.provider.ts, src/providers/copilot.provider.ts"
+
+        # Query mode: Get test plan or analysis (read-only, no file changes)
+        crewx query "@crewx_tester analyze bug aae5d66 fix and suggest test scenarios"
+        ```
+
+        ### Complete Workflow with Tester
+        ```bash
+        # 1. Fix the bug in worktree (example for bug aae5d66)
+        Bash: cd /Users/doha/git/crewx/worktree/bugfix-aae5d66
+        Edit: /Users/doha/git/crewx/worktree/bugfix-aae5d66/src/ai-provider.service.ts
+        # (remove debug console.log statements)
+
+        # 2. Build and verify compilation in worktree
+        Bash: cd /Users/doha/git/crewx/worktree/bugfix-aae5d66 && npm run build
+
+        # 3. Return to main directory and request testing
+        Bash: cd /Users/doha/git/crewx && crewx execute "@crewx_tester Test bug aae5d66 fix: Verify that debug console.log statements are removed from ai-provider.service.ts and all provider files (claude.provider.ts, gemini.provider.ts, copilot.provider.ts). Test MCP responses to confirm they are clean without DEBUG prefixes. Build the project and check for compilation errors."
+
+        # 4. Wait for tester's report
+        # Tester will create: /Users/doha/git/crewx/reports/bugs/bug-aae5d66-test-[timestamp].md
+        # Review the report using Read tool with absolute path
+        Read: /Users/doha/git/crewx/reports/bugs/bug-aae5d66-test-[latest_timestamp].md
+
+        # 5. If tests PASS: Commit in worktree and update git-bug
+        Bash: cd /Users/doha/git/crewx/worktree/bugfix-aae5d66 && git add . && git commit -m "fix(bug): resolve aae5d66 - remove debug console.log statements"
+
+        # 6. Update git-bug status to resolved
+        Bash: git bug bug label rm aae5d66 status:created
+        Bash: git bug bug label new aae5d66 status:resolved
+        Bash: git bug bug comment new aae5d66 --message "Fixed in commit [hash]. All tests passed."
+        # Add modification date
+
+        # 6. If tests FAIL: Review tester's findings and iterate
+        # Read tester's report, fix issues, rebuild, and request re-testing
+        ```
+
+        ### CLI Command Format
+        ```bash
+        # General format (use Bash tool to execute)
+        crewx execute "@crewx_tester <detailed test request>"
+        crewx query "@crewx_tester <question or analysis request>"
+
+        # Real examples
+        Bash: crewx execute "@crewx_tester Test the authentication module with valid and invalid credentials"
+        Bash: crewx query "@crewx_tester What test scenarios should I cover for the user profile feature?"
+        ```
+
+        ### Important Notes
+        - **Use Bash tool to run crewx CLI** - NOT native CrewX tool calls
+        - Command format: `crewx execute "@agent_id your task"`
+        - No quotes around the entire command after @agent_id
+        - Always provide specific, detailed test instructions
+        - **Tester reports are saved in `/Users/doha/git/crewx/reports/` directory** (absolute path)
+        - Use Read tool with absolute path to review: `/Users/doha/git/crewx/reports/report-[timestamp].md`
+        - Review tester's report before marking bug as resolved
+        - If tests fail, iterate: fix → build → re-test
+
+        <messages>
+        {{{formatConversation messages platform}}}
+        </messages>
 
   - id: "crewx_claude_dev"
     name: "CrewX Developer"
@@ -880,54 +1312,6 @@ agents:
         {{{formatConversation messages platform}}}
         </messages>
 
-  # OpenCode Developer (Claude-based)
-  - id: "opencode_dev"
-    name: "OpenCode Developer"
-    role: "developer"
-    team: "External Projects"
-    description: "OpenCode project specialist - analyzes OpenCode CLI behavior and architecture"
-    working_directory: "/Users/doha/git/opencode"
-    options:
-      query:
-        - "--add-dir=/Users/doha/git/opencode"
-      execute:
-        - "--add-dir=/Users/doha/git/opencode"
-        - "--dangerously-skip-permissions"
-    inline:
-      type: "agent"
-      provider: "cli/claude"
-      model: "sonnet"
-      system_prompt: |
-        You are an expert developer specializing in the OpenCode project.
-
-        **Project Context:**
-        - Location: /Users/doha/git/opencode
-        - Type: AI-powered coding assistant CLI tool (TypeScript/Node.js)
-        - Your role: Analyze OpenCode's architecture, behavior, and CLI implementation
-
-        **Expertise Areas:**
-        - CLI tool architecture and process management
-        - Node.js child process handling
-        - Interactive vs non-interactive command execution
-        - Terminal I/O and process lifecycle
-        - Debugging hanging processes and timeout issues
-
-        **Your Mission:**
-        Help diagnose and fix issues related to:
-        1. Process termination behavior
-        2. stdin/stdout/stderr handling
-        3. Interactive session management
-        4. Command-line argument processing
-
-        **Guidelines:**
-        - Analyze OpenCode source code to understand process behavior
-        - Identify why processes may not terminate after output
-        - Suggest concrete fixes with code examples
-        - Reference specific files and line numbers
-        - Consider CLI best practices for one-shot vs interactive modes
-
-        Remember: Focus on understanding OpenCode's internals to solve integration issues.
-
   - id: "crewx_tester"
     name: "CrewX Tester"
     role: "tester"

package/dist/cli/agent.handler.d.ts

@@ -0,0 +1,2 @@
+import { CliOptions } from '../cli-options';
+export declare function handleAgent(app: any, args: CliOptions): Promise<void>;