Merge pull request #21 from Tshoiasc/master

Enhance codex.py to auto-detect long inputs and switch to stdin mode,…

.claude-plugin/marketplace.json

@@ -149,6 +149,32 @@
       "agents": [
         "./agents/gpt5.md"
       ]
+    },
+    {
+      "name": "requirements-clarity",
+      "source": "./requirements-clarity/",
+      "description": "Transforms vague requirements into actionable PRDs through systematic clarification with 100-point scoring system",
+      "version": "1.0.0",
+      "author": {
+        "name": "Claude Code Dev Workflows",
+        "url": "https://github.com/cexll/myclaude"
+      },
+      "homepage": "https://github.com/cexll/myclaude",
+      "repository": "https://github.com/cexll/myclaude",
+      "license": "MIT",
+      "keywords": [
+        "requirements",
+        "clarification",
+        "prd",
+        "specifications",
+        "quality-gates",
+        "requirements-engineering"
+      ],
+      "category": "essentials",
+      "strict": false,
+      "skills": [
+        "./skills/SKILL.md"
+      ]
     }
   ]
 }

.gitignore

@@ -1,3 +1,4 @@
 CLAUDE.md
-
 .claude/
+
+

README.md

@@ -46,6 +46,7 @@ make install
 | **[requirements-driven-workflow](docs/REQUIREMENTS-WORKFLOW.md)** | Streamlined requirements-to-code workflow | `/requirements-pilot` |
 | **[development-essentials](docs/DEVELOPMENT-COMMANDS.md)** | Core development slash commands | `/code` `/debug` `/test` `/optimize` |
 | **[advanced-ai-agents](docs/ADVANCED-AGENTS.md)** | GPT-5 deep reasoning integration | Agent: `gpt5` |
+| **[requirements-clarity](docs/REQUIREMENTS-CLARITY.md)** | Automated requirements clarification with 100-point scoring | Auto-activated skill |
 
 ## 💡 Use Cases
 
@@ -62,6 +63,11 @@ make install
 - Direct implementation, debugging, testing, optimization
 - No workflow overhead
 
+**Requirements Clarity** - Automated requirements engineering
+- Auto-detects vague requirements and initiates clarification
+- 100-point quality scoring system
+- Generates complete PRD documents
+
 ## 🎯 Key Features
 
 - **🤖 Role-Based Agents**: Specialized AI agents for each development phase
@@ -70,6 +76,7 @@ make install
 - **📁 Persistent Artifacts**: All specs saved to `.claude/specs/`
 - **🔌 Plugin System**: Native Claude Code plugin support
 - **🔄 Flexible Workflows**: Choose full agile or lightweight development
+- **🎯 Requirements Clarity**: Automated requirements clarification with quality scoring
 
 ## 📚 Documentation
 

README_CN.md

@@ -46,6 +46,7 @@ make install
 | **[requirements-driven-workflow](docs/REQUIREMENTS-WORKFLOW.md)** | 精简的需求到代码工作流 | `/requirements-pilot` |
 | **[development-essentials](docs/DEVELOPMENT-COMMANDS.md)** | 核心开发斜杠命令 | `/code` `/debug` `/test` `/optimize` |
 | **[advanced-ai-agents](docs/ADVANCED-AGENTS.md)** | GPT-5 深度推理集成 | 智能体: `gpt5` |
+| **[requirements-clarity](docs/REQUIREMENTS-CLARITY.md)** | 自动需求澄清，100分制质量评分 | 自动激活技能 |
 
 ## 💡 使用场景
 
@@ -62,6 +63,11 @@ make install
 - 直接实现、调试、测试、优化
 - 无工作流开销
 
+**需求澄清** - 自动化需求工程
+- 自动检测模糊需求并启动澄清流程
+- 100分制质量评分系统
+- 生成完整的产品需求文档
+
 ## 🎯 核心特性
 
 - **🤖 角色化智能体**: 每个开发阶段的专业 AI 智能体
@@ -70,6 +76,7 @@ make install
 - **📁 持久化产物**: 所有规格保存至 `.claude/specs/`
 - **🔌 插件系统**: 原生 Claude Code 插件支持
 - **🔄 灵活工作流**: 选择完整敏捷或轻量开发
+- **🎯 需求澄清**: 自动化需求澄清与质量评分
 
 ## 📚 文档
 

development-essentials/README.md

@@ -0,0 +1,253 @@
+# Development Essentials - Core Development Commands
+
+核心开发命令套件，提供日常开发所需的所有基础命令。无需工作流开销，直接执行开发任务。
+
+## 📋 命令列表
+
+### 1. `/ask` - 技术咨询
+**用途**: 架构问题咨询和技术决策指导
+**适用场景**: 需要架构建议、技术选型、系统设计方案时
+
+**特点**:
+- 四位架构顾问协同：系统设计师、技术策略师、可扩展性顾问、风险分析师
+- 遵循 KISS、YAGNI、SOLID 原则
+- 提供架构分析、设计建议、技术指导和实施策略
+- **不生成代码**，专注于架构咨询
+
+**使用示例**:
+```bash
+/ask "如何设计一个支持百万并发的消息队列系统？"
+/ask "微服务架构中应该如何处理分布式事务？"
+```
+
+---
+
+### 2. `/code` - 功能实现
+**用途**: 直接实现新功能或特性
+**适用场景**: 需要快速开发新功能时
+
+**特点**:
+- 四位开发专家协同：架构师、实现工程师、集成专家、代码审查员
+- 渐进式开发，每步验证
+- 包含完整的实现计划、代码实现、集成指南和测试策略
+- 生成可运行的高质量代码
+
+**使用示例**:
+```bash
+/code "实现JWT认证中间件"
+/code "添加用户头像上传功能"
+```
+
+---
+
+### 3. `/debug` - 系统调试
+**用途**: 使用 UltraThink 方法系统性调试问题
+**适用场景**: 遇到复杂bug或系统性问题时
+
+**特点**:
+- 四位专家协同：架构师、研究员、编码员、测试员
+- UltraThink 反思阶段：综合所有洞察形成解决方案
+- 生成5-7个假设，逐步缩减到1-2个最可能的原因
+- 在实施修复前要求用户确认诊断结果
+- 证据驱动的系统性问题分析
+
+**使用示例**:
+```bash
+/debug "API响应时间突然增加10倍"
+/debug "生产环境内存泄漏问题"
+```
+
+---
+
+### 4. `/test` - 测试策略
+**用途**: 设计和实现全面的测试策略
+**适用场景**: 需要为组件或功能编写测试时
+
+**特点**:
+- 四位测试专家：测试架构师、单元测试专家、集成测试工程师、质量验证员
+- 测试金字塔策略（单元/集成/端到端比例）
+- 提供测试覆盖率分析和优先级建议
+- 包含 CI/CD 集成计划
+
+**使用示例**:
+```bash
+/test "用户认证模块"
+/test "支付处理流程"
+```
+
+---
+
+### 5. `/optimize` - 性能优化
+**用途**: 识别和优化性能瓶颈
+**适用场景**: 系统存在性能问题或需要提升性能时
+
+**特点**:
+- 四位优化专家：性能分析师、算法工程师、资源管理员、可扩展性架构师
+- 建立性能基线和量化指标
+- 优化算法复杂度、内存使用、I/O操作
+- 设计水平扩展和并发处理方案
+
+**使用示例**:
+```bash
+/optimize "数据库查询性能"
+/optimize "API响应时间优化到200ms以内"
+```
+
+---
+
+### 6. `/review` - 代码审查
+**用途**: 全方位代码质量审查
+**适用场景**: 需要审查代码质量、安全性和架构设计时
+
+**特点**:
+- 四位审查专家：质量审计员、安全分析师、性能审查员、架构评估员
+- 多维度审查：可读性、安全性、性能、架构设计
+- 提供优先级分类的改进建议
+- 包含具体代码示例和重构建议
+
+**使用示例**:
+```bash
+/review "src/auth/middleware.ts"
+/review "支付模块代码"
+```
+
+---
+
+### 7. `/bugfix` - Bug修复
+**用途**: 快速定位和修复Bug
+**适用场景**: 需要修复已知Bug时
+
+**特点**:
+- 专注于快速修复
+- 包含验证流程
+- 确保修复不引入新问题
+
+**使用示例**:
+```bash
+/bugfix "登录失败后session未清理"
+/bugfix "订单状态更新不及时"
+```
+
+---
+
+### 8. `/refactor` - 代码重构
+**用途**: 改进代码结构和可维护性
+**适用场景**: 代码质量下降或需要优化代码结构时
+
+**特点**:
+- 保持功能不变
+- 提升代码质量和可维护性
+- 遵循设计模式和最佳实践
+
+**使用示例**:
+```bash
+/refactor "将用户管理模块拆分为独立服务"
+/refactor "优化支付流程代码结构"
+```
+
+---
+
+### 9. `/docs` - 文档生成
+**用途**: 生成项目文档和API文档
+**适用场景**: 需要为代码或API生成文档时
+
+**特点**:
+- 自动分析代码结构
+- 生成清晰的文档
+- 包含使用示例
+
+**使用示例**:
+```bash
+/docs "API接口文档"
+/docs "为认证模块生成开发者文档"
+```
+
+---
+
+### 10. `/think` - 深度分析
+**用途**: 对复杂问题进行深度思考和分析
+**适用场景**: 需要全面分析复杂技术问题时
+
+**特点**:
+- 系统性思考框架
+- 多角度问题分析
+- 提供深入见解
+
+**使用示例**:
+```bash
+/think "如何设计一个高可用的分布式系统？"
+/think "微服务拆分的最佳实践是什么？"
+```
+
+---
+
+### 11. `/enhance-prompt` - 提示词增强 🆕
+**用途**: 优化和增强用户提供的指令
+**适用场景**: 需要改进模糊或不清晰的指令时
+
+**特点**:
+- 自动分析指令上下文
+- 消除歧义，提高清晰度
+- 修正错误并提高具体性
+- 立即返回增强后的提示词
+- 保留代码块等特殊格式
+
+**输出格式**:
+```
+### Here is an enhanced version of the original instruction that is more specific and clear:
+<enhanced-prompt>增强后的提示词</enhanced-prompt>
+```
+
+**使用示例**:
+```bash
+/enhance-prompt "帮我做一个登录功能"
+/enhance-prompt "优化一下这个API"
+```
+
+---
+
+## 🎯 命令选择指南
+
+| 需求场景 | 推荐命令 | 说明 |
+|---------|---------|------|
+| 需要架构建议 | `/ask` | 不生成代码，专注咨询 |
+| 实现新功能 | `/code` | 完整的功能实现流程 |
+| 调试复杂问题 | `/debug` | UltraThink系统性调试 |
+| 编写测试 | `/test` | 全面的测试策略 |
+| 性能优化 | `/optimize` | 性能瓶颈分析和优化 |
+| 代码审查 | `/review` | 多维度质量审查 |
+| 修复Bug | `/bugfix` | 快速定位和修复 |
+| 重构代码 | `/refactor` | 提升代码质量 |
+| 生成文档 | `/docs` | API和开发者文档 |
+| 深度思考 | `/think` | 复杂问题分析 |
+| 优化指令 | `/enhance-prompt` | 提示词增强 |
+
+## 🔧 代理列表
+
+Development Essentials 模块包含以下专用代理：
+
+- `code` - 代码实现代理
+- `bugfix` - Bug修复代理
+- `bugfix-verify` - Bug验证代理
+- `code-optimize` - 代码优化代理
+- `debug` - 调试分析代理
+- `develop` - 通用开发代理
+
+## 📖 使用原则
+
+1. **直接执行**: 无需工作流开销，直接运行命令
+2. **专注单一任务**: 每个命令聚焦特定开发任务
+3. **质量优先**: 所有命令都包含质量验证环节
+4. **实用主义**: KISS/YAGNI/DRY 原则贯穿始终
+5. **上下文感知**: 自动理解项目结构和编码规范
+
+## 🔗 相关文档
+
+- [主文档](../README.md) - 项目总览
+- [BMAD工作流](../docs/BMAD-WORKFLOW.md) - 完整敏捷流程
+- [Requirements工作流](../docs/REQUIREMENTS-WORKFLOW.md) - 轻量级开发流程
+- [插件系统](../PLUGIN_README.md) - 插件安装和管理
+
+---
+
+**提示**: 这些命令可以单独使用，也可以组合使用。例如：`/code` → `/test` → `/review` → `/optimize` 构成一个完整的开发周期。

development-essentials/commands/enhance-prompt.md

@@ -0,0 +1,9 @@
+`/enhance-prompt <task info>`
+
+Here is an instruction that I'd like to give you, but it needs to be improved. Rewrite and enhance this instruction to make it clearer, more specific, less ambiguous, and correct any mistakes. Do not use any tools: reply immediately with your answer, even if you're not sure. Consider the context of our conversation history when enhancing the prompt. If there is code in triple backticks (```) consider whether it is a code sample and should remain unchanged.Reply with the following format:
+
+### BEGIN RESPONSE
+
+<enhanced-prompt>enhanced prompt goes here</enhanced-prompt>
+
+### END RESPONSE

requirements-clarity/.claude-plugin/marketplace.json

@@ -0,0 +1,26 @@
+{
+  "name": "requirements-clarity",
+  "source": "./",
+  "description": "Transforms vague requirements into actionable PRDs through systematic clarification with 100-point scoring system",
+  "version": "1.0.0",
+  "author": {
+    "name": "Claude Code Dev Workflows",
+    "url": "https://github.com/cexll/myclaude"
+  },
+  "homepage": "https://github.com/cexll/myclaude",
+  "repository": "https://github.com/cexll/myclaude",
+  "license": "MIT",
+  "keywords": [
+    "requirements",
+    "clarification",
+    "prd",
+    "specifications",
+    "quality-gates",
+    "requirements-engineering"
+  ],
+  "category": "essentials",
+  "strict": false,
+  "skills": [
+    "./skills/SKILL.md"
+  ]
+}

requirements-clarity/skills/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: Requirements Clarity
+description: Clarify ambiguous requirements through focused dialogue before implementation. Use when requirements are unclear, features are complex (>2 days), or involve cross-team coordination. Ask two core questions - Why? (YAGNI check) and Simpler? (KISS check) - to ensure clarity before coding.
+---
+
+# Requirements Clarity Skill
+
+## Description
+
+Automatically transforms vague requirements into actionable PRDs through systematic clarification with a 100-point scoring system.
+
+## Activation
+
+Auto-activate when detecting vague requirements:
+
+1. **Vague Feature Requests**
+   - User says: "add login feature", "implement payment", "create dashboard"
+   - Missing: How, with what technology, what constraints?
+
+2. **Missing Technical Context**
+   - No technology stack mentioned
+   - No integration points identified
+   - No performance/security constraints
+
+3. **Incomplete Specifications**
+   - No acceptance criteria
+   - No success metrics
+   - No edge cases considered
+   - No error handling mentioned
+
+4. **Ambiguous Scope**
+   - Unclear boundaries ("user management" - what exactly?)
+   - No distinction between MVP and future enhancements
+   - Missing "what's NOT included"
+
+**Do NOT activate when**:
+- Specific file paths mentioned (e.g., "auth.go:45")
+- Code snippets included
+- Existing functions/classes referenced
+- Bug fixes with clear reproduction steps
+
+## Core Principles
+
+1. **Systematic Questioning**
+   - Ask focused, specific questions
+   - One category at a time (2-3 questions per round)
+   - Build on previous answers
+   - Avoid overwhelming users
+
+2. **Quality-Driven Iteration**
+   - Continuously assess clarity score (0-100)
+   - Identify gaps systematically
+   - Iterate until ≥ 90 points
+   - Document all clarification rounds
+
+3. **Actionable Output**
+   - Generate concrete specifications
+   - Include measurable acceptance criteria
+   - Provide executable phases
+   - Enable direct implementation
+
+## Clarification Process
+
+### Step 1: Initial Requirement Analysis
+
+**Input**: User's requirement description
+
+**Tasks**:
+1. Parse and understand core requirement
+2. Generate feature name (kebab-case format)
+3. Determine document version (default `1.0` unless user specifies otherwise)
+4. Ensure `./docs/prds/` exists for PRD output
+5. Perform initial clarity assessment (0-100)
+
+**Assessment Rubric**:
+```
+Functional Clarity: /30 points
+- Clear inputs/outputs: 10 pts
+- User interaction defined: 10 pts
+- Success criteria stated: 10 pts
+
+Technical Specificity: /25 points
+- Technology stack mentioned: 8 pts
+- Integration points identified: 8 pts
+- Constraints specified: 9 pts
+
+Implementation Completeness: /25 points
+- Edge cases considered: 8 pts
+- Error handling mentioned: 9 pts
+- Data validation specified: 8 pts
+
+Business Context: /20 points
+- Problem statement clear: 7 pts
+- Target users identified: 7 pts
+- Success metrics defined: 6 pts
+```
+
+**Initial Response Format**:
+```markdown
+I understand your requirement. Let me help you refine this specification.
+
+**Current Clarity Score**: X/100
+
+**Clear Aspects**:
+- [List what's clear]
+
+**Needs Clarification**:
+- [List gaps]
+
+Let me systematically clarify these points...
+```
+
+### Step 2: Gap Analysis
+
+Identify missing information across four dimensions:
+
+**1. Functional Scope**
+- What is the core functionality?
+- What are the boundaries?
+- What is out of scope?
+- What are edge cases?
+
+**2. User Interaction**
+- How do users interact?
+- What are the inputs?
+- What are the outputs?
+- What are success/failure scenarios?
+
+**3. Technical Constraints**
+- Performance requirements?
+- Compatibility requirements?
+- Security considerations?
+- Scalability needs?
+
+**4. Business Value**
+- What problem does this solve?
+- Who are the target users?
+- What are success metrics?
+- What is the priority?
+
+### Step 3: Interactive Clarification
+
+**Question Strategy**:
+1. Start with highest-impact gaps
+2. Ask 2-3 questions per round
+3. Build context progressively
+4. Use user's language
+5. Provide examples when helpful
+
+**Question Format**:
+```markdown
+I need to clarify the following points to complete the requirements document:
+
+1. **[Category]**: [Specific question]?
+   - For example: [Example if helpful]
+
+2. **[Category]**: [Specific question]?
+
+3. **[Category]**: [Specific question]?
+
+Please provide your answers, and I'll continue refining the PRD.
+```
+
+**After Each User Response**:
+1. Update clarity score
+2. Capture new information in the working PRD outline
+3. Identify remaining gaps
+4. If score < 90: Continue with next round of questions
+5. If score ≥ 90: Proceed to PRD generation
+
+**Score Update Format**:
+```markdown
+Thank you for the additional information!
+
+**Clarity Score Update**: X/100 → Y/100
+
+**New Clarified Content**:
+- [Summarize new information]
+
+**Remaining Points to Clarify**:
+- [List remaining gaps if score < 90]
+
+[If score < 90: Continue with next round of questions]
+[If score ≥ 90: "Perfect! I will now generate the complete PRD document..."]
+```
+
+### Step 4: PRD Generation
+
+Once clarity score ≥ 90, generate comprehensive PRD.
+
+**Output File**:
+
+1. **Final PRD**: `./docs/prds/{feature_name}-v{version}-prd.md`
+
+Use the `Write` tool to create or update this file. Derive `{version}` from the document version recorded in the PRD (default `1.0`).
+
+## PRD Document Structure
+
+```markdown
+# {Feature Name} - Product Requirements Document (PRD)
+
+## Requirements Description
+
+### Background
+- **Business Problem**: [Describe the business problem to solve]
+- **Target Users**: [Target user groups]
+- **Value Proposition**: [Value this feature brings]
+
+### Feature Overview
+- **Core Features**: [List of main features]
+- **Feature Boundaries**: [What is and isn't included]
+- **User Scenarios**: [Typical usage scenarios]
+
+### Detailed Requirements
+- **Input/Output**: [Specific input/output specifications]
+- **User Interaction**: [User operation flow]
+- **Data Requirements**: [Data structures and validation rules]
+- **Edge Cases**: [Edge case handling]
+
+## Design Decisions
+
+### Technical Approach
+- **Architecture Choice**: [Technical architecture decisions and rationale]
+- **Key Components**: [List of main technical components]
+- **Data Storage**: [Data models and storage solutions]
+- **Interface Design**: [API/interface specifications]
+
+### Constraints
+- **Performance Requirements**: [Response time, throughput, etc.]
+- **Compatibility**: [System compatibility requirements]
+- **Security**: [Security considerations]
+- **Scalability**: [Future expansion considerations]
+
+### Risk Assessment
+- **Technical Risks**: [Potential technical risks and mitigation plans]
+- **Dependency Risks**: [External dependencies and alternatives]
+- **Schedule Risks**: [Timeline risks and response strategies]
+
+## Acceptance Criteria
+
+### Functional Acceptance
+- [ ] Feature 1: [Specific acceptance conditions]
+- [ ] Feature 2: [Specific acceptance conditions]
+- [ ] Feature 3: [Specific acceptance conditions]
+
+### Quality Standards
+- [ ] Code Quality: [Code standards and review requirements]
+- [ ] Test Coverage: [Testing requirements and coverage]
+- [ ] Performance Metrics: [Performance test pass criteria]
+- [ ] Security Review: [Security review requirements]
+
+### User Acceptance
+- [ ] User Experience: [UX acceptance criteria]
+- [ ] Documentation: [Documentation delivery requirements]
+- [ ] Training Materials: [If needed, training material requirements]
+
+## Execution Phases
+
+### Phase 1: Preparation
+**Goal**: Environment preparation and technical validation
+- [ ] Task 1: [Specific task description]
+- [ ] Task 2: [Specific task description]
+- **Deliverables**: [Phase deliverables]
+- **Time**: [Estimated time]
+
+### Phase 2: Core Development
+**Goal**: Implement core functionality
+- [ ] Task 1: [Specific task description]
+- [ ] Task 2: [Specific task description]
+- **Deliverables**: [Phase deliverables]
+- **Time**: [Estimated time]
+
+### Phase 3: Integration & Testing
+**Goal**: Integration and quality assurance
+- [ ] Task 1: [Specific task description]
+- [ ] Task 2: [Specific task description]
+- **Deliverables**: [Phase deliverables]
+- **Time**: [Estimated time]
+
+### Phase 4: Deployment
+**Goal**: Release and monitoring
+- [ ] Task 1: [Specific task description]
+- [ ] Task 2: [Specific task description]
+- **Deliverables**: [Phase deliverables]
+- **Time**: [Estimated time]
+
+---
+
+**Document Version**: 1.0  
+**Created**: {timestamp}  
+**Clarification Rounds**: {clarification_rounds}  
+**Quality Score**: {quality_score}/100
+```
+
+## Behavioral Guidelines
+
+### DO
+- Ask specific, targeted questions
+- Build on previous answers
+- Provide examples to guide users
+- Maintain conversational tone
+- Summarize clarification rounds within the PRD
+- Use clear, professional English
+- Generate concrete specifications
+- Stay in clarification mode until score ≥ 90
+
+### DON'T
+- Ask all questions at once
+- Make assumptions without confirmation
+- Generate PRD before 90+ score
+- Skip any required sections
+- Use vague or abstract language
+- Proceed without user responses
+- Exit skill mode prematurely
+
+## Success Criteria
+
+- Clarity score ≥ 90/100
+- All PRD sections complete with substance
+- Acceptance criteria checklistable (using `- [ ]` format)
+- Execution phases actionable with concrete tasks
+- User approves final PRD
+- Ready for development handoff

skills/codex/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: codex
+description: Execute Codex CLI for code analysis, refactoring, and automated code changes. Use when you need to delegate complex code tasks to Codex AI with file references (@syntax) and structured output.
+---
+
+# Codex CLI Integration
+
+## Overview
+
+Execute Codex CLI commands and parse structured JSON responses. Supports file references via `@` syntax, multiple models, and sandbox controls.
+
+## When to Use
+
+- Complex code analysis requiring deep understanding
+- Large-scale refactoring across multiple files
+- Automated code generation with safety controls
+- Tasks requiring specialized reasoning models (o3, gpt-5)
+
+## Usage
+
+**推荐方式**（使用 uv run，自动管理 Python 环境）：
+```bash
+uv run ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
+```
+
+**备选方式**（直接执行或使用 Python）：
+```bash
+~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
+# 或
+python3 ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
+```
+
+恢复会话:
+```bash
+uv run ~/.claude/skills/codex/scripts/codex.py resume <session_id> "<task>" [model] [working_dir]
+```
+
+## Timeout Control
+
+- **Built-in**: Script enforces 2-hour timeout by default
+- **Override**: Set `CODEX_TIMEOUT` environment variable (in milliseconds, e.g., `CODEX_TIMEOUT=3600000` for 1 hour)
+- **Behavior**: On timeout, sends SIGTERM, then SIGKILL after 5s if process doesn't exit
+- **Exit code**: Returns 124 on timeout (consistent with GNU timeout)
+- **Bash tool**: Always set `timeout: 7200000` parameter for double protection
+
+### Parameters
+
+- `task` (required): Task description, supports `@file` references
+- `model` (optional): Model to use (default: gpt-5.1-codex)
+  - `gpt-5.1-codex`: Default, optimized for code
+  - `gpt-5`: Fast general purpose
+- `working_dir` (optional): Working directory (default: current)
+
+### Return Format
+
+Extracts `agent_message` from Codex JSON stream and appends session ID:
+```
+Agent response text here...
+
+---
+SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
+```
+
+Error format (stderr):
+```
+ERROR: Error message
+```
+
+### Invocation Pattern
+
+When calling via Bash tool, always include the timeout parameter:
+```
+Bash tool parameters:
+- command: uv run ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
+- timeout: 7200000
+- description: <brief description of the task>
+```
+
+Alternatives:
+```
+# Direct execution (simplest)
+- command: ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
+
+# Using python3
+- command: python3 ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
+```
+
+### Examples
+
+**Basic code analysis:**
+```bash
+# Recommended: via uv run (auto-manages Python environment)
+uv run ~/.claude/skills/codex/scripts/codex.py "explain @src/main.ts"
+# timeout: 7200000
+
+# Alternative: direct execution
+~/.claude/skills/codex/scripts/codex.py "explain @src/main.ts"
+```
+
+**Refactoring with specific model:**
+```bash
+uv run ~/.claude/skills/codex/scripts/codex.py "refactor @src/utils for performance" "gpt-5"
+# timeout: 7200000
+```
+
+**Multi-file analysis:**
+```bash
+uv run ~/.claude/skills/codex/scripts/codex.py "analyze @. and find security issues" "gpt-5-codex" "/path/to/project"
+# timeout: 7200000
+```
+
+**Resume previous session:**
+```bash
+# First session
+uv run ~/.claude/skills/codex/scripts/codex.py "add comments to @utils.js" "gpt-5-codex"
+# Output includes: SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
+
+# Continue the conversation
+uv run ~/.claude/skills/codex/scripts/codex.py resume 019a7247-ac9d-71f3-89e2-a823dbd8fd14 "now add type hints"
+# timeout: 7200000
+```
+
+**Using python3 directly (alternative):**
+```bash
+python3 ~/.claude/skills/codex/scripts/codex.py "your task here"
+```
+
+## Notes
+
+- **Recommended**: Use `uv run` for automatic Python environment management (requires uv installed)
+- **Alternative**: Direct execution `./codex.py` (uses system Python via shebang)
+- Python implementation using standard library (zero dependencies)
+- Cross-platform compatible (Windows/macOS/Linux)
+- PEP 723 compliant (inline script metadata)
+- Runs with `--dangerously-bypass-approvals-and-sandbox` for automation (new sessions only)
+- Uses `--skip-git-repo-check` to work in any directory
+- Streams progress, returns only final agent message
+- Every execution returns a session ID for resuming conversations
+- Requires Codex CLI installed and authenticated

skills/codex/scripts/codex.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.8"
+# dependencies = []
+# ///
+"""
+Codex CLI wrapper with cross-platform support and session management.
+**FIXED**: Auto-detect long inputs and use stdin mode to avoid shell argument issues.
+
+Usage:
+    New session:  uv run codex.py "task" [model] [workdir]
+    Resume:       uv run codex.py resume <session_id> "task" [model] [workdir]
+    Alternative:  python3 codex.py "task"
+    Direct exec:  ./codex.py "task"
+"""
+import subprocess
+import json
+import sys
+import os
+from typing import Optional
+
+DEFAULT_MODEL = 'gpt-5.1-codex'
+DEFAULT_WORKDIR = '.'
+DEFAULT_TIMEOUT = 7200  # 2 hours in seconds
+FORCE_KILL_DELAY = 5
+STDIN_THRESHOLD = 800  # Auto-switch to stdin for prompts longer than 800 chars
+
+
+def log_error(message: str):
+    """输出错误信息到 stderr"""
+    sys.stderr.write(f"ERROR: {message}\n")
+
+
+def log_warn(message: str):
+    """输出警告信息到 stderr"""
+    sys.stderr.write(f"WARN: {message}\n")
+
+
+def resolve_timeout() -> int:
+    """解析超时配置（秒）"""
+    raw = os.environ.get('CODEX_TIMEOUT', '')
+    if not raw:
+        return DEFAULT_TIMEOUT
+
+    try:
+        parsed = int(raw)
+        if parsed <= 0:
+            log_warn(f"Invalid CODEX_TIMEOUT '{raw}', falling back to {DEFAULT_TIMEOUT}s")
+            return DEFAULT_TIMEOUT
+        # 环境变量是毫秒，转换为秒
+        return parsed // 1000 if parsed > 10000 else parsed
+    except ValueError:
+        log_warn(f"Invalid CODEX_TIMEOUT '{raw}', falling back to {DEFAULT_TIMEOUT}s")
+        return DEFAULT_TIMEOUT
+
+
+def normalize_text(text) -> Optional[str]:
+    """规范化文本：字符串或字符串数组"""
+    if isinstance(text, str):
+        return text
+    if isinstance(text, list):
+        return ''.join(text)
+    return None
+
+
+def parse_args():
+    """解析命令行参数"""
+    if len(sys.argv) < 2:
+        log_error('Task required')
+        sys.exit(1)
+
+    # 检测是否为 resume 模式
+    if sys.argv[1] == 'resume':
+        if len(sys.argv) < 4:
+            log_error('Resume mode requires: resume <session_id> <task>')
+            sys.exit(1)
+        return {
+            'mode': 'resume',
+            'session_id': sys.argv[2],
+            'task': sys.argv[3],
+            'model': sys.argv[4] if len(sys.argv) > 4 else DEFAULT_MODEL,
+            'workdir': sys.argv[5] if len(sys.argv) > 5 else DEFAULT_WORKDIR
+        }
+    else:
+        return {
+            'mode': 'new',
+            'task': sys.argv[1],
+            'model': sys.argv[2] if len(sys.argv) > 2 else DEFAULT_MODEL,
+            'workdir': sys.argv[3] if len(sys.argv) > 3 else DEFAULT_WORKDIR
+        }
+
+
+def build_codex_args(params: dict, use_stdin: bool) -> list:
+    """
+    构建 codex CLI 参数
+
+    Args:
+        params: 参数字典
+        use_stdin: 是否使用 stdin 模式（不在命令行参数中传递 task）
+    """
+    if params['mode'] == 'resume':
+        if use_stdin:
+            return [
+                'codex', 'e',
+                '--skip-git-repo-check',
+                '--json',
+                'resume',
+                params['session_id'],
+                '-'  # 从 stdin 读取
+            ]
+        else:
+            return [
+                'codex', 'e',
+                '--skip-git-repo-check',
+                '--json',
+                'resume',
+                params['session_id'],
+                params['task']
+            ]
+    else:
+        base_args = [
+            'codex', 'e',
+            '-m', params['model'],
+            '--dangerously-bypass-approvals-and-sandbox',
+            '--skip-git-repo-check',
+            '-C', params['workdir'],
+            '--json'
+        ]
+
+        if use_stdin:
+            base_args.append('-')  # 从 stdin 读取
+        else:
+            base_args.append(params['task'])
+
+        return base_args
+
+
+def main():
+    params = parse_args()
+    timeout_sec = resolve_timeout()
+
+    # **FIX: Auto-detect long inputs and enable stdin mode**
+    task_length = len(params['task'])
+    use_stdin = task_length > STDIN_THRESHOLD
+
+    if use_stdin:
+        log_warn(f"Task length ({task_length} chars) exceeds threshold, using stdin mode to avoid shell escaping issues")
+
+    codex_args = build_codex_args(params, use_stdin)
+
+    thread_id: Optional[str] = None
+    last_agent_message: Optional[str] = None
+
+    try:
+        # 启动 codex 子进程
+        process = subprocess.Popen(
+            codex_args,
+            stdin=subprocess.PIPE if use_stdin else None,  # **FIX: Enable stdin**
+            stdout=subprocess.PIPE,
+            stderr=sys.stderr,  # 错误直接透传到 stderr
+            text=True,
+            bufsize=1  # 行缓冲
+        )
+
+        # **FIX: 如果使用 stdin 模式，写入任务到 stdin**
+        if use_stdin:
+            process.stdin.write(params['task'])
+            process.stdin.close()
+
+        # 逐行解析 JSON 输出
+        for line in process.stdout:
+            line = line.strip()
+            if not line:
+                continue
+
+            try:
+                event = json.loads(line)
+
+                # 捕获 thread_id
+                if event.get('type') == 'thread.started':
+                    thread_id = event.get('thread_id')
+
+                # 捕获 agent_message
+                if (event.get('type') == 'item.completed' and
+                    event.get('item', {}).get('type') == 'agent_message'):
+                    text = normalize_text(event['item'].get('text'))
+                    if text:
+                        last_agent_message = text
+
+            except json.JSONDecodeError:
+                log_warn(f"Failed to parse line: {line}")
+
+        # 等待进程结束
+        returncode = process.wait(timeout=timeout_sec)
+
+        if returncode == 0:
+            if last_agent_message:
+                # 输出 agent_message
+                sys.stdout.write(f"{last_agent_message}\n")
+
+                # 输出 session_id（如果存在）
+                if thread_id:
+                    sys.stdout.write(f"\n---\nSESSION_ID: {thread_id}\n")
+
+                sys.exit(0)
+            else:
+                log_error('Codex completed without agent_message output')
+                sys.exit(1)
+        else:
+            log_error(f'Codex exited with status {returncode}')
+            sys.exit(returncode)
+
+    except subprocess.TimeoutExpired:
+        log_error('Codex execution timeout')
+        process.kill()
+        try:
+            process.wait(timeout=FORCE_KILL_DELAY)
+        except subprocess.TimeoutExpired:
+            pass
+        sys.exit(124)
+
+    except FileNotFoundError:
+        log_error("codex command not found in PATH")
+        sys.exit(127)
+
+    except KeyboardInterrupt:
+        process.terminate()
+        try:
+            process.wait(timeout=FORCE_KILL_DELAY)
+        except subprocess.TimeoutExpired:
+            process.kill()
+        sys.exit(130)
+
+
+if __name__ == '__main__':
+    main()