chore: bump version to v5.2.7

Changes in v5.2.7:
- Security fix: pass env vars via process environment instead of command line
- Prevents ANTHROPIC_API_KEY leakage in ps/logs
- Add SetEnv() interface to commandRunner
- Type-safe env parsing with 1MB file size limit
- Comprehensive test coverage for loadMinimalEnvSettings()

Related: #89, PR #92

Generated with SWE-Agent.ai

Co-Authored-By: SWE-Agent.ai <noreply@swe-agent.ai>

.claude-plugin/marketplace.json

@@ -125,9 +125,9 @@
       ]
     },
     {
-      "name": "advanced-ai-agents",
-      "source": "./advanced-ai-agents/",
-      "description": "Advanced AI agent for complex problem solving and deep analysis with GPT-5 integration",
+      "name": "codex-cli",
+      "source": "./skills/codex/",
+      "description": "Execute Codex CLI for code analysis, refactoring, and automated code changes with file references (@syntax) and structured output",
       "version": "1.0.0",
       "author": {
         "name": "Claude Code Dev Workflows",
@@ -137,17 +137,72 @@
       "repository": "https://github.com/cexll/myclaude",
       "license": "MIT",
       "keywords": [
-        "gpt5",
-        "ai",
-        "analysis",
-        "problem-solving",
-        "deep-research"
+        "codex",
+        "code-analysis",
+        "refactoring",
+        "automation",
+        "gpt-5",
+        "ai-coding"
       ],
-      "category": "advanced",
+      "category": "essentials",
       "strict": false,
-      "commands": [],
+      "skills": [
+        "./SKILL.md"
+      ]
+    },
+    {
+      "name": "gemini-cli",
+      "source": "./skills/gemini/",
+      "description": "Execute Gemini CLI for AI-powered code analysis and generation with Google's latest Gemini models",
+      "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": [
+        "gemini",
+        "google-ai",
+        "code-analysis",
+        "code-generation",
+        "ai-reasoning"
+      ],
+      "category": "essentials",
+      "strict": false,
+      "skills": [
+        "./SKILL.md"
+      ]
+    },
+    {
+      "name": "dev-workflow",
+      "source": "./dev-workflow/",
+      "description": "Minimal lightweight development workflow with requirements clarification, parallel codex execution, and mandatory 90% test coverage",
+      "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": [
+        "dev",
+        "workflow",
+        "codex",
+        "testing",
+        "coverage",
+        "concurrent",
+        "lightweight"
+      ],
+      "category": "workflows",
+      "strict": false,
+      "commands": [
+        "./commands/dev.md"
+      ],
       "agents": [
-        "./agents/gpt5.md"
+        "./agents/dev-plan-generator.md"
       ]
     }
   ]

.gitattributes

@@ -0,0 +1,22 @@
+# Ensure shell scripts always use LF line endings on all platforms
+*.sh text eol=lf
+
+# Ensure Python files use LF line endings
+*.py text eol=lf
+
+# Auto-detect text files and normalize line endings to LF
+* text=auto eol=lf
+
+# Explicitly declare files that should always be treated as binary
+*.exe binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.mov binary
+*.mp4 binary
+*.mp3 binary
+*.zip binary
+*.gz binary
+*.tar binary

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [master, rc/*]
+  pull_request:
+    branches: [master, rc/*]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Run tests
+        run: |
+          cd codeagent-wrapper
+          go test -v -cover -coverprofile=coverage.out ./...
+
+      - name: Check coverage
+        run: |
+          cd codeagent-wrapper
+          go tool cover -func=coverage.out | grep total | awk '{print $3}'
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          file: codeagent-wrapper/coverage.out
+        continue-on-error: true

.github/workflows/release.yml

@@ -0,0 +1,134 @@
+name: Release codeagent-wrapper
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Run tests
+        working-directory: codeagent-wrapper
+        run: go test -v -coverprofile=cover.out ./...
+
+      - name: Check coverage
+        working-directory: codeagent-wrapper
+        run: |
+          go tool cover -func=cover.out | grep total
+          COVERAGE=$(go tool cover -func=cover.out | grep total | awk '{print $3}' | sed 's/%//')
+          echo "Coverage: ${COVERAGE}%"
+
+  build:
+    name: Build
+    needs: test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
+            goarch: arm64
+          - goos: darwin
+            goarch: amd64
+          - goos: darwin
+            goarch: arm64
+          - goos: windows
+            goarch: amd64
+          - goos: windows
+            goarch: arm64
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+
+      - name: Build binary
+        id: build
+        working-directory: codeagent-wrapper
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: 0
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          OUTPUT_NAME=codeagent-wrapper-${{ matrix.goos }}-${{ matrix.goarch }}
+          if [ "${{ matrix.goos }}" = "windows" ]; then
+            OUTPUT_NAME="${OUTPUT_NAME}.exe"
+          fi
+          go build -ldflags="-s -w -X main.version=${VERSION}" -o ${OUTPUT_NAME} .
+          chmod +x ${OUTPUT_NAME}
+          echo "artifact_path=codeagent-wrapper/${OUTPUT_NAME}" >> $GITHUB_OUTPUT
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: codeagent-wrapper-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: ${{ steps.build.outputs.artifact_path }}
+
+  release:
+    name: Create Release
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Prepare release files
+        run: |
+          mkdir -p release
+          find artifacts -type f -name "codeagent-wrapper-*" -exec mv {} release/ \;
+          cp install.sh install.bat release/
+          ls -la release/
+
+      - name: Generate release notes with git-cliff
+        run: |
+          # Install git-cliff via npx
+          npx git-cliff@latest --current --strip all -o release_notes.md
+
+          # Fallback if generation failed
+          if [ ! -s release_notes.md ]; then
+            echo "⚠️ Failed to generate release notes with git-cliff" > release_notes.md
+            echo "" >> release_notes.md
+            echo "## What's Changed" >> release_notes.md
+            echo "See commits in this release for details." >> release_notes.md
+          fi
+
+          echo "--- Generated Release Notes ---"
+          cat release_notes.md
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: release/*
+          body_path: release_notes.md
+          draft: false
+          prerelease: false

.gitignore

@@ -1,3 +1,7 @@
-CLAUDE.md
-
 .claude/
+.claude-trace
+.venv
+.pytest_cache
+__pycache__
+.coverage
+coverage.out

BMAD-PILOT-USER-GUIDE.md

@@ -1,163 +0,0 @@
-# BMAD Pilot 使用指南
-
-本指南介绍如何使用 BMAD Pilot 工作流，编排一组协作 AI 角色（PO/Architect/SM/Dev/QA）在仓库上下文中完成：01 产品需求文档、02 系统设计规范、03 冲刺计划，并自动进入开发与测试，整个过程包含多次用户确认门与质量评分。
-
-参考阅读：BMAD-README.md（BMAD 方法概览）、BMAD-INTEGRATION-GUIDE.md（进阶集成）。
-
----
-
-## 命令总览
-
-- 命令：`/bmad-pilot <PROJECT_DESCRIPTION> [OPTIONS]`
-- 作用：在仓库上下文中，按阶段编排 `bmad-po → bmad-architect → bmad-sm → bmad-dev → bmad-qa`。
-- Orchestrator：由工作流统一编排（使用 bmad-orchestrator 进行仓库扫描）。
-
-### Options
-- `--skip-tests`：跳过 QA 阶段
-- `--direct-dev`：跳过 SM 冲刺计划，架构后直接进入开发
-- `--skip-scan`：跳过初始仓库扫描（不推荐）
-
-### 输出目录
-- 所有产出归档在：`./.claude/specs/{feature_name}/`
-  - `00-repo-scan.md` — 仓库扫描摘要（自动生成）
-  - `01-product-requirements.md` — 产品需求文档（确认后保存）
-  - `02-system-architecture.md` — 系统设计规范（确认后保存）
-  - `03-sprint-plan.md` — 冲刺计划（确认后保存；`--direct-dev` 时跳过）
-
-`{feature_name}` 由 `<PROJECT_DESCRIPTION>` 生成（kebab-case：小写，空格/标点转 `-`，连续合并，首尾去除）。
-
----
-
-## 快速开始
-
-1) 执行 Pilot：
-```
-/bmad-pilot 为现有项目新增看板模块，支持多用户权限与移动端适配
-```
-2) 与 PO 交互澄清，直至 PRD ≥ 90 分 → 确认保存。
-3) 与 Architect 讨论技术决策，直至架构 ≥ 90 分 → 确认保存。
-4) 审阅并确认 SM 的冲刺计划（或使用 `--direct-dev` 跳过该阶段）。
-5) Dev 基于文档实现；QA 基于文档与实现测试（除非 `--skip-tests`）。
-6) 查看产出目录：`./.claude/specs/{feature_name}/`。
-
----
-
-## 工作流阶段
-
-- Phase 0：仓库扫描（自动，除非 `--skip-scan`）
-  - Agent：`bmad-orchestrator`
-  - 结果：扫描摘要返回并写入 `00-repo-scan.md`
-  - 内容：项目类型、技术栈、代码组织、惯例、集成点、约束与注意事项
-
-- Phase 1：产品需求（交互）
-  - Agent：`bmad-po`
-  - 循环：澄清问题 → 更新 PRD → 评分（目标 ≥ 90）
-  - 确认门：PRD ≥ 90 分后，需要用户明确确认再继续
-  - 保存：`01-product-requirements.md`
-
-- Phase 2：系统架构（交互）
-  - Agent：`bmad-architect`
-  - 循环：技术选型与设计澄清 → 更新架构 → 评分（目标 ≥ 90）
-  - 确认门：架构 ≥ 90 分后，需要用户明确确认再继续
-  - 保存：`02-system-architecture.md`
-
-- Phase 3：冲刺计划（交互，除非 `--direct-dev`）
-  - Agent：`bmad-sm`
-  - 循环：计划要点与问题澄清 → 更新计划 → 确认保存
-  - 保存：`03-sprint-plan.md`
-
-- Phase 4：开发实现（自动）
-  - Agent：`bmad-dev`
-  - 输入：PRD、架构、冲刺计划、`00-repo-scan.md`
-
-- Phase 5：质量保障（自动，除非 `--skip-tests`）
-  - Agent：`bmad-qa`
-  - 输入：PRD、架构、冲刺计划、实现、`00-repo-scan.md`
-
----
-
-## 交互与质量门
-
-- 质控阈值：PRD 与架构质量评分需达到 ≥ 90 分。
-- 强制确认门：每个关键阶段完成后，Orchestrator 会停下等待你的“继续/确认”。
-- 迭代澄清：PO/Architect/SM 会提出 2-5 个精准问题，Orchestrator 转述并汇总你的回答以供下一轮完善。
-
----
-
-## 仓库上下文
-
-- 首次扫描：由工作流触发的 orchestrator 扫描（`bmad-orchestrator`）自动分析当前仓库（`--skip-scan` 可跳过）。
-- 缓存路径：`./.claude/specs/{feature_name}/00-repo-scan.md`（供所有后续 Agent 引用）。
-- 作用：提供技术栈识别、约定、测试模式、集成点，避免上下文丢失并保持一致性。
-
----
-
-## 角色职责
-
-- `bmad-po`：需求澄清与 PRD 产出，评分与问题驱动迭代。
-- `bmad-architect`：技术架构与关键决策，评分与问题驱动迭代。
-- `bmad-sm`：冲刺计划、任务拆分、依赖/风险/节奏规划。
-- `bmad-dev`：按文档实现、测试、日志/安全/性能与同构风格。
-- `bmad-qa`：基于需求与实现的全维度测试（单测/集成/E2E/性能/安全）。
-
----
-
-## 示例
-
-- 基础运行：
-```
-/bmad-pilot 在线商城结算流程升级，支持优惠券与发票
-```
-
-- 跳过测试：
-```
-/bmad-pilot H5 活动页生成器 --skip-tests
-```
-
-- 直接从架构进入开发（跳过 SM）：
-```
-/bmad-pilot 小程序客服模块重构 --direct-dev
-```
-
-- 跳过扫描（不推荐）：
-```
-/bmad-pilot 部署流水线可视化 --skip-scan
-```
-
----
-
-## 目录结构
-
-```
-.claude/
-  specs/
-    {feature_name}/
-      00-repo-scan.md
-      01-product-requirements.md
-      02-system-architecture.md
-      03-sprint-plan.md
-```
-
----
-
-## Tips & 常见问题
-
-- 分数上不去：优先补齐评分分项的缺口（业务指标、关键流程、性能/安全约束等）。
-- 上下文不一致：检查并引用 `00-repo-scan.md` 的关键约定与模式，保证 PRD/架构/计划一致。
-- 依赖/网络受限：Dev/QA 的实际执行受环境影响；请在项目内准备依赖与测试环境，或先提交伪实现/测试策略。
-- 文档路径：确保在项目根目录执行，Pilot 会将文件写入 `./.claude/specs/{feature_name}/`。
-
----
-
-## 最佳实践
-
-- 小步快跑：每轮补充最关键信息，快速达成 ≥ 90 分文档。
-- 统一术语：在 PRD 固定术语词表；架构与代码沿用同名。
-- 用例先行：PRD 的验收标准应转化为 QA 的关键测试用例。
-- 复用模式：尽量沿用扫描识别的现有代码/测试模式，减少偏差。
-
----
-
-## 版本记录
-
-- 2025-08-11：新增仓库扫描摘要缓存 `00-repo-scan.md`，统一路径与跨阶段引用；明确确认门与目录预创建说明。

BMAD-README.md

@@ -1,339 +0,0 @@
-# BMAD方法论 Claude Code 使用指南
-
-[![BMAD Method](https://img.shields.io/badge/BMAD-Method-blue)](https://github.com/bmadcode/BMAD-METHOD)
-[![Claude Code](https://img.shields.io/badge/Claude-Code-green)](https://claude.ai/code)
-
-> 从产品理念到代码实现的完整AI驱动敏捷开发工作流
-
-## 🎯 什么是BMAD方法论？
-
-BMAD (Business, Market, Architecture, Development) 是一个AI驱动的敏捷开发方法论，通过专业化代理团队实现从商业需求到技术实现的完整工作流程。
-
-### 核心理念
-- **智能体规划**: 专门代理协作创建详细、一致的PRD和架构文档
-- **上下文工程开发**: 将详细计划转换为超详细的开发故事
-- **角色专业化**: 每个代理专注特定领域，避免角色切换导致的质量下降
-
-## 🏗️ BMAD代理体系
-
-### 代理角色说明
-- **PO (Product Owner)** - 产品负责人Sarah：需求分析、用户故事、验收标准
-- **Analyst** - 业务分析师Mary：市场研究、竞争分析、商业案例
-- **Architect** - 系统架构师Winston：技术架构、系统设计、技术选择
-- **SM (Scrum Master)** - 敏捷教练：任务分解、冲刺规划、流程协调
-- **Dev (Developer)** - 开发工程师：代码实现、技术文档
-- **QA (Quality Assurance)** - 质量保证：测试策略、质量验证
-- **UX Expert** - 用户体验专家：交互设计、可用性测试
-
-## 🚀 快速开始
-
-### 安装配置
-BMAD方法论已集成到您的Claude Code系统中，无需额外安装。
-
-### 基本使用方法
-
-#### 1. 完整BMAD工作流
-```bash
-# 一键执行完整开发流程
-/bmad-pilot "实现企业级用户管理系统，支持RBAC权限控制和LDAP集成"
-
-# 执行流程：PO → Architect → SM → Dev → QA
-```
-
-#### 2. 常用选项
-```bash
-# 跳过测试（PO → Architect → SM → Dev）
-/bmad-pilot "实现支付网关API" --skip-tests
-
-# 直接从架构进入开发（跳过 SM 规划）
-/bmad-pilot "设计微服务电商平台" --direct-dev
-
-# 跳过仓库扫描（不推荐）
-/bmad-pilot "用户界面优化" --skip-scan
-```
-
-#### 3. 直接开发与部分流程
-```bash
-# 技术焦点（架构后直接进入开发与测试）
-/bmad-pilot "API网关实现" --direct-dev
-
-# 完整设计流程（需求→架构→规划→开发→测试）
-/bmad-pilot "系统重构规划"
-
-# 仅业务相关分析 → 请使用下方“独立代理使用”中的 /bmad-po 与 /bmad-analyst
-```
-
-#### 4. 独立代理使用
-```bash
-# 产品需求分析
-/bmad-po "企业CRM系统功能需求定义"
-
-# 市场调研分析
-/bmad-analyst "SaaS市场竞争格局和机会分析"
-
-# 系统架构设计
-/bmad-architect "高并发分布式系统架构设计"
-
-# 主协调器（可转换为任意代理）
-/bmad-orchestrator "协调多代理完成复杂项目"
-```
-
-## 📋 详细命令说明
-
-### `/bmad-pilot` - 完整工作流执行
-**用法**: `/bmad-pilot <项目描述> [选项]`
-
-**选项**:
-- `--skip-tests`: 跳过 QA 阶段
-- `--direct-dev`: 跳过 SM 冲刺计划，架构后直接进入开发
-- `--skip-scan`: 跳过初始仓库扫描（不推荐）
-
-**示例**:
-```bash
-/bmad-pilot "构建在线教育平台，支持直播、录播、作业系统"
-/bmad-pilot "API网关设计" --direct-dev
-/bmad-pilot "支付模块" --skip-tests
-```
-
-### `/bmad-po` - 产品负责人
-**角色**: Sarah - 技术产品负责人 & 流程管家
-**专长**: 需求分析、用户故事、验收标准、冲刺规划
-
-**用法**: `/bmad-po <需求描述>`
-
-**工作流程**:
-1. 需求分解和功能点识别
-2. 用户故事创建（As a... I want... So that...）
-3. 验收标准定义和优先级排序
-4. 利益相关者验证和签署
-
-**示例**:
-```bash
-/bmad-po "设计企业级权限管理系统，支持多租户和细粒度权限控制"
-/bmad-po "移动端电商APP功能需求分析"
-```
-
-### `/bmad-analyst` - 业务分析师
-**角色**: Mary - 洞察分析师 & 战略合作伙伴
-**专长**: 市场研究、竞争分析、商业案例开发、利益相关者分析
-
-**用法**: `/bmad-analyst <分析主题>`
-
-**工作流程**:
-1. 市场格局和竞争对手分析
-2. 商业案例开发和ROI分析
-3. 利益相关者分析和需求收集
-4. 项目简报和战略建议
-
-**示例**:
-```bash
-/bmad-analyst "企业级认证市场分析，JWT vs OAuth2.0 vs SAML"
-/bmad-analyst "云原生架构迁移的商业价值和风险评估"
-```
-
-### `/bmad-architect` - 系统架构师
-**角色**: Winston - 全栈系统架构师 & 技术领导者
-**专长**: 系统设计、技术选择、API设计、基础架构规划
-
-**用法**: `/bmad-architect <系统设计需求>`
-
-**工作流程**:
-1. 系统需求和约束分析
-2. 技术栈和架构模式选择
-3. 组件设计和系统架构图
-4. 实施策略和开发指导
-
-**示例**:
-```bash
-/bmad-architect "微服务架构设计，支持事件驱动和最终一致性"
-/bmad-architect "高可用API网关架构，支持限流、熔断、监控"
-```
-
-### `/bmad-orchestrator` - 主协调器
-**角色**: BMAD主协调器
-**专长**: 工作流协调、代理转换、多代理任务管理
-
-**用法**: `/bmad-orchestrator [命令] [参数]`
-
-**功能**:
-- 动态转换为任意专门代理
-- 协调复杂多代理工作流
-- 管理代理间的上下文传递
-- 提供工作流指导和建议
-
-## 🔄 与现有系统集成
-
-### 现有系统 vs BMAD方法论
-
-| 特性 | Requirements-Pilot | BMAD方法论 |
-|------|-------------------|-----------|
-| **执行时间** | 30分钟 | 1-2小时 |
-| **适用场景** | 快速功能开发 | 企业级项目 |
-| **覆盖范围** | 技术实现 | 商业+技术全流程 |
-| **质量门控** | 90%技术质量 | 多维度质量验证 |
-| **代理数量** | 4个技术代理 | 7个全角色代理 |
-
-### 使用场景建议
-
-#### 🚅 快速开发（推荐现有系统）
-```bash
-# 简单功能快速实现
-/requirements-pilot "添加用户登录功能"
-/requirements-pilot "实现数据导出API"
-```
-
-#### 🏢 企业级项目（推荐BMAD）
-```bash
-# 复杂系统完整流程
-/bmad-pilot "构建企业级ERP系统，集成财务、人事、项目管理模块"
-/bmad-pilot "设计多租户SaaS平台，支持自定义配置和第三方集成"
-```
-
-#### 🔄 混合模式（规划+实现）
-```bash
-# 先用BMAD做规划（在 PRD/架构确认门停留）
-/bmad-pilot "电商平台架构设计"
-
-# 再用现有系统快速实现
-/requirements-pilot "基于架构规格实现用户服务模块"
-/requirements-pilot "基于架构规格实现订单服务模块"
-```
-
-## 🎯 典型工作流示例
-
-### 示例1: 企业级认证系统
-```bash
-# 完整BMAD流程
-/bmad-pilot "企业级JWT认证系统，支持RBAC权限控制、LDAP集成、审计日志、高可用部署"
-
-# 预期输出：
-# 1. PO: 详细用户故事和验收标准
-# 2. Architect: 完整系统架构和技术选择
-# 3. SM: 开发任务分解和冲刺计划
-# 4. Dev: 生产就绪代码实现
-# 5. QA: 测试策略与用例并执行（可选）
-```
-
-### 示例2: API网关开发
-```bash
-# 技术焦点流程（跳过SM，架构后直接进入开发）
-/bmad-pilot "高性能API网关，支持限流、熔断、监控、服务发现" --direct-dev
-
-# 执行流程：
-# 1. Architect: 系统架构设计
-# 2. Dev: 代码实现
-# 3. QA: 性能测试和质量验证
-```
-
-### 示例3: 产品市场分析
-```bash
-# 业务分析流程（使用独立代理）
-/bmad-po "云原生数据库市场机会分析的产品需求假设与范围界定"
-/bmad-analyst "云原生数据库市场机会分析"
-
-# 执行流程：
-# 1. PO: 产品需求定义
-# 2. Analyst: 市场研究和竞争分析
-```
-
-## 📊 质量保证体系
-
-### BMAD质量标准
-- **需求完整性**: 90+ 分需求清晰度评分
-- **商业对齐**: 明确的价值主张和市场定位
-- **架构完善**: 全面的系统设计和技术选择
-- **实现就绪**: 可执行的开发规格和质量标准
-
-### 集成现有质量门控
-- 保持90%技术质量阈值
-- 增加商业价值验证维度
-- 多代理交叉验证机制
-- 自动化质量反馈循环
-
-## 🔧 高级用法和最佳实践
-
-### 1. 渐进式复杂度管理
-```bash
-# MVP阶段
-/bmad-workflow "用户管理系统MVP版本" --phase=development
-
-# 功能增强阶段
-/bmad-analyst "用户反馈分析和功能增强建议"
-/requirements-pilot "基于反馈实现增强功能"
-
-# 企业级增强
-/bmad-workflow "企业级安全增强和合规支持" --agents=architect,dev,qa
-```
-
-### 2. 跨项目知识管理
-```bash
-# 项目文档化
-/bmad-orchestrator "将当前项目架构文档化，便于后续项目参考"
-
-# 最佳实践提取
-/bmad-architect "基于项目经验总结微服务架构最佳实践"
-```
-
-### 3. 团队协作优化
-```bash
-# 团队能力评估
-/bmad-analyst "评估团队技术栈和能力匹配度"
-
-# 开发计划调整
-/bmad-po "根据团队能力调整功能优先级和实现计划"
-```
-
-## 🚦 故障排除
-
-### 常见问题
-
-**Q: BMAD工作流执行时间较长，如何优化？**
-A: 
-- 简单功能使用 `/requirements-pilot`
-- 复杂项目使用分阶段执行 `--phase=planning`
-- 使用自定义代理序列减少不必要的步骤
-
-**Q: 如何在BMAD和现有系统间选择？**
-A:
-- 项目复杂度 < 中等：使用 `/requirements-pilot`
-- 项目复杂度 ≥ 高：使用 `/bmad-workflow`
-- 需要商业分析：必须使用BMAD
-- 纯技术实现：可选择任一系统
-
-**Q: 代理输出质量不符合预期怎么办？**
-A:
-- 提供更详细的项目描述
-- 使用分阶段执行，逐步细化
-- 结合独立代理使用进行专项优化
-
-## 🎉 开始你的BMAD之旅
-
-### 第一次使用
-```bash
-# 体验完整BMAD工作流
-/bmad-workflow "构建一个简单的博客系统，支持文章发布、评论、用户管理"
-```
-
-### 学习不同代理角色
-```bash
-# 产品思维
-/bmad-po "分析博客系统的用户需求和使用场景"
-
-# 商业思维
-/bmad-analyst "个人博客vs企业CMS市场定位分析"
-
-# 技术思维
-/bmad-architect "可扩展博客系统架构设计"
-```
-
-## 📚 进阶学习资源
-
-- [BMAD-METHOD原理](https://github.com/bmadcode/BMAD-METHOD)
-- [Claude Code文档](https://docs.anthropic.com/en/docs/claude-code)
-- [敏捷开发最佳实践](https://agilemanifesto.org/)
-
----
-
-**BMAD方法论 + Claude Code = 从理念到代码的完整AI开发工作流** 🚀
-
-开始使用BMAD方法论，体验专业化AI代理团队带来的开发效率和质量提升！

CHANGELOG.md

@@ -0,0 +1,712 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [5.2.4] - 2025-12-16
+
+
+### ⚙️ Miscellaneous Tasks
+
+
+- integrate git-cliff for automated changelog generation
+
+- bump version to 5.2.4
+
+### 🐛 Bug Fixes
+
+
+- 防止 Claude backend 无限递归调用
+
+- isolate log files per task in parallel mode
+
+### 💼 Other
+
+
+- Merge pull request #70 from cexll/fix/prevent-codeagent-infinite-recursion
+
+- Merge pull request #69 from cexll/myclaude-master-20251215-073053-338465000
+
+- update CHANGELOG.md
+
+- Merge pull request #65 from cexll/fix/issue-64-buffer-overflow
+
+## [5.2.3] - 2025-12-15
+
+
+### 🐛 Bug Fixes
+
+
+- 修复 bufio.Scanner token too long 错误 ([#64](https://github.com/cexll/myclaude/issues/64))
+
+### 💼 Other
+
+
+- change version
+
+### 🧪 Testing
+
+
+- 同步测试中的版本号至 5.2.3
+
+## [5.2.2] - 2025-12-13
+
+
+### ⚙️ Miscellaneous Tasks
+
+
+- Bump version and clean up documentation
+
+### 🐛 Bug Fixes
+
+
+- fix codeagent backend claude no auto
+
+- fix install.py dev fail
+
+### 🧪 Testing
+
+
+- Fix tests for ClaudeBackend default --dangerously-skip-permissions
+
+## [5.2.1] - 2025-12-13
+
+
+### 🐛 Bug Fixes
+
+
+- fix codeagent claude and gemini root dir
+
+### 💼 Other
+
+
+- update readme
+
+## [5.2.0] - 2025-12-13
+
+
+### ⚙️ Miscellaneous Tasks
+
+
+- Update CHANGELOG and remove deprecated test files
+
+### 🐛 Bug Fixes
+
+
+- fix race condition in stdout parsing
+
+- add worker limit cap and remove legacy alias
+
+- use -r flag for gemini backend resume
+
+- clarify module list shows default state not enabled
+
+- use -r flag for claude backend resume
+
+- remove binary artifacts and improve error messages
+
+- 异常退出时显示最近错误信息
+
+- op_run_command 实时流式输出
+
+- 修复权限标志逻辑和版本号测试
+
+- 重构信号处理逻辑避免重复 nil 检查
+
+- 移除 .claude 配置文件验证步骤
+
+- 修复并行执行启动横幅重复打印问题
+
+- 修复master合并后的编译和测试问题
+
+### 💼 Other
+
+
+- Merge rc/5.2 into master: v5.2.0 release improvements
+
+- Merge pull request #53 from cexll/rc/5.2
+
+- remove docs
+
+- remove docs
+
+- add prototype prompt skill
+
+- add prd skill
+
+- update memory claude
+
+- remove command gh flow
+
+- update license
+
+- Merge branch 'master' into rc/5.2
+
+- Merge pull request #52 from cexll/fix/parallel-log-path-on-startup
+
+### 📚 Documentation
+
+
+- remove GitHub workflow related content
+
+### 🚀 Features
+
+
+- Complete skills system integration and config cleanup
+
+- Improve release notes and installation scripts
+
+- 添加终端日志输出和 verbose 模式
+
+- 完整多后端支持与安全优化
+
+- 替换 Codex 为 codeagent 并添加 UI 自动检测
+
+### 🚜 Refactor
+
+
+- 调整文件命名和技能定义
+
+### 🧪 Testing
+
+
+- 添加 ExtractRecentErrors 单元测试
+
+## [5.1.4] - 2025-12-09
+
+
+### 🐛 Bug Fixes
+
+
+- 任务启动时立即返回日志文件路径以支持实时调试
+
+## [5.1.3] - 2025-12-08
+
+
+### 🐛 Bug Fixes
+
+
+- resolve CI timing race in TestFakeCmdInfra
+
+## [5.1.2] - 2025-12-08
+
+
+### 🐛 Bug Fixes
+
+
+- 修复channel同步竞态条件和死锁问题
+
+### 💼 Other
+
+
+- Merge pull request #51 from cexll/fix/channel-sync-race-conditions
+
+- change codex-wrapper version
+
+## [5.1.1] - 2025-12-08
+
+
+### 🐛 Bug Fixes
+
+
+- 增强日志清理的安全性和可靠性
+
+- resolve data race on forceKillDelay with atomic operations
+
+### 💼 Other
+
+
+- Merge pull request #49 from cexll/freespace8/master
+
+- resolve signal handling conflict preserving testability and Windows support
+
+### 🧪 Testing
+
+
+- 补充测试覆盖提升至 89.3%
+
+## [5.1.0] - 2025-12-07
+
+
+### 💼 Other
+
+
+- Merge pull request #45 from Michaelxwb/master
+
+- 修改windows安装说明
+
+- 修改打包脚本
+
+- 支持windows系统的安装
+
+- Merge pull request #1 from Michaelxwb/feature-win
+
+- 支持window
+
+### 🚀 Features
+
+
+- 添加启动时清理日志的功能和--cleanup标志支持
+
+- implement enterprise workflow with multi-backend support
+
+## [5.0.0] - 2025-12-05
+
+
+### ⚙️ Miscellaneous Tasks
+
+
+- clarify unit-test coverage levels in requirement questions
+
+### 🐛 Bug Fixes
+
+
+- defer startup log until args parsed
+
+### 💼 Other
+
+
+- Merge branch 'master' of github.com:cexll/myclaude
+
+- Merge pull request #43 from gurdasnijor/smithery/add-badge
+
+- Add Smithery badge
+
+- Merge pull request #42 from freespace8/master
+
+### 📚 Documentation
+
+
+- rewrite documentation for v5.0 modular architecture
+
+### 🚀 Features
+
+
+- feat install.py
+
+- implement modular installation system
+
+### 🚜 Refactor
+
+
+- remove deprecated plugin modules
+
+## [4.8.2] - 2025-12-02
+
+
+### 🐛 Bug Fixes
+
+
+- skip signal test in CI environment
+
+- make forceKillDelay testable to prevent signal test timeout
+
+- correct Go version in go.mod from 1.25.3 to 1.21
+
+- fix codex wrapper async log
+
+- capture and include stderr in error messages
+
+### 💼 Other
+
+
+- Merge pull request #41 from cexll/fix-async-log
+
+- remove test case 90
+
+- optimize codex-wrapper
+
+- Merge branch 'master' into fix-async-log
+
+## [4.8.1] - 2025-12-01
+
+
+### 🎨 Styling
+
+
+- replace emoji with text labels
+
+### 🐛 Bug Fixes
+
+
+- improve --parallel parameter validation and docs
+
+### 💼 Other
+
+
+- remove codex-wrapper bin
+
+## [4.8.0] - 2025-11-30
+
+
+### 💼 Other
+
+
+- update codex skill dependencies
+
+## [4.7.3] - 2025-11-29
+
+
+### 🐛 Bug Fixes
+
+
+- 保留日志文件以便程序退出后调试并完善日志输出功能
+
+### 💼 Other
+
+
+- Merge pull request #34 from cexll/cce-worktree-master-20251129-111802-997076000
+
+- update CLAUDE.md and codex skill
+
+### 📚 Documentation
+
+
+- improve codex skill parameter best practices
+
+### 🚀 Features
+
+
+- add session resume support and improve output format
+
+- add parallel execution support to codex-wrapper
+
+- add async logging to temp file with lifecycle management
+
+## [4.7.2] - 2025-11-28
+
+
+### 🐛 Bug Fixes
+
+
+- improve buffer size and streamline message extraction
+
+### 💼 Other
+
+
+- Merge pull request #32 from freespace8/master
+
+### 🧪 Testing
+
+
+- 增加对超大单行文本和非字符串文本的处理测试
+
+## [4.7.1] - 2025-11-27
+
+
+### 💼 Other
+
+
+- optimize dev pipline
+
+- Merge feat/codex-wrapper: fix repository URLs
+
+## [4.7] - 2025-11-27
+
+
+### 🐛 Bug Fixes
+
+
+- update repository URLs to cexll/myclaude
+
+## [4.7-alpha1] - 2025-11-27
+
+
+### 🐛 Bug Fixes
+
+
+- fix marketplace schema validation error in dev-workflow plugin
+
+### 💼 Other
+
+
+- Merge pull request #29 from cexll/feat/codex-wrapper
+
+- Add codex-wrapper Go implementation
+
+- update readme
+
+- update readme
+
+## [4.6] - 2025-11-25
+
+
+### 💼 Other
+
+
+- update dev workflow
+
+- update dev workflow
+
+## [4.5] - 2025-11-25
+
+
+### 🐛 Bug Fixes
+
+
+- fix codex skill eof
+
+### 💼 Other
+
+
+- update dev workflow plugin
+
+- update readme
+
+## [4.4] - 2025-11-22
+
+
+### 🐛 Bug Fixes
+
+
+- fix codex skill timeout and add more log
+
+- fix codex skill
+
+### 💼 Other
+
+
+- update gemini skills
+
+- update dev workflow
+
+- update codex skills model config
+
+- Merge branch 'master' of github.com:cexll/myclaude
+
+- Merge pull request #24 from cexll/swe-agent/23-1763544297
+
+### 🚀 Features
+
+
+- 支持通过环境变量配置 skills 模型
+
+## [4.3] - 2025-11-19
+
+
+### 🐛 Bug Fixes
+
+
+- fix codex skills running
+
+### 💼 Other
+
+
+- update skills plugin
+
+- update gemini
+
+- update doc
+
+- Add Gemini CLI integration skill
+
+### 🚀 Features
+
+
+- feat simple dev workflow
+
+## [4.2.2] - 2025-11-15
+
+
+### 💼 Other
+
+
+- update codex skills
+
+## [4.2.1] - 2025-11-14
+
+
+### 💼 Other
+
+
+- Merge pull request #21 from Tshoiasc/master
+
+- Merge branch 'master' into master
+
+- Change default model to gpt-5.1-codex
+
+- Enhance codex.py to auto-detect long inputs and switch to stdin mode, improving handling of shell argument issues. Updated build_codex_args to support stdin and added relevant logging for task length warnings.
+
+## [4.2] - 2025-11-13
+
+
+### 🐛 Bug Fixes
+
+
+- fix codex.py wsl run err
+
+### 💼 Other
+
+
+- optimize codex skills
+
+- Merge branch 'master' of github.com:cexll/myclaude
+
+- Rename SKILLS.md to SKILL.md
+
+- optimize codex skills
+
+### 🚀 Features
+
+
+- feat codex skills
+
+## [4.1] - 2025-11-04
+
+
+### 💼 Other
+
+
+- update enhance-prompt.md response
+
+- update readme
+
+### 📚 Documentation
+
+
+- 新增 /enhance-prompt 命令并更新所有 README 文档
+
+## [4.0] - 2025-10-22
+
+
+### 🐛 Bug Fixes
+
+
+- fix skills format
+
+### 💼 Other
+
+
+- Merge branch 'master' of github.com:cexll/myclaude
+
+- Merge pull request #18 from cexll/swe-agent/17-1760969135
+
+- update requirements clarity
+
+- update .gitignore
+
+- Fix #17: Update root marketplace.json to use skills array
+
+- Fix #17: Convert requirements-clarity to correct plugin directory format
+
+- Fix #17: Convert requirements-clarity to correct plugin directory format
+
+- Convert requirements-clarity to plugin format with English prompts
+
+- Translate requirements-clarity skill to English for plugin compatibility
+
+- Add requirements-clarity Claude Skill
+
+- Add requirements clarification command
+
+- update
+
+## [3.5] - 2025-10-20
+
+
+### 💼 Other
+
+
+- Merge pull request #15 from cexll/swe-agent/13-1760944712
+
+- Fix #13: Clean up redundant README files
+
+- Optimize README structure - Solution A (modular)
+
+- Merge pull request #14 from cexll/swe-agent/12-1760944588
+
+- Fix #12: Update Makefile install paths for new directory structure
+
+## [3.4] - 2025-10-20
+
+
+### 💼 Other
+
+
+- Merge pull request #11 from cexll/swe-agent/10-1760752533
+
+- Fix marketplace metadata references
+
+- Fix plugin configuration: rename to marketplace.json and update repository URLs
+
+- Fix #10: Restructure plugin directories to ensure proper command isolation
+
+## [3.3] - 2025-10-15
+
+
+### 💼 Other
+
+
+- Update README-zh.md
+
+- Update README.md
+
+- Update marketplace.json
+
+- Update Chinese README with v3.2 plugin system documentation
+
+- Update README with v3.2 plugin system documentation
+
+## [3.2] - 2025-10-10
+
+
+### 💼 Other
+
+
+- Add Claude Code plugin system support
+
+- update readme
+
+- Add Makefile for quick deployment and update READMEs
+
+## [3.1] - 2025-09-17
+
+
+### ◀️ Revert
+
+
+- revert
+
+### 🐛 Bug Fixes
+
+
+- fixed bmad-orchestrator not fund
+
+- fix bmad
+
+### 💼 Other
+
+
+- update bmad review with codex support
+
+- 优化 BMAD 工作流和代理配置
+
+- update gpt5
+
+- support bmad output-style
+
+- update bmad user guide
+
+- update bmad readme
+
+- optimize requirements pilot
+
+- add use gpt5 codex
+
+- add bmad pilot
+
+- sync READMEs with actual commands/agents; remove nonexistent commands; enhance requirements-pilot with testing decision gate and options.
+
+- Update Chinese README and requirements-pilot command to align with latest workflow
+
+- update readme
+
+- update agent
+
+- update bugfix sub agents
+
+- Update ask support KISS YAGNI SOLID
+
+- Add comprehensive documentation and multi-agent workflow system
+
+- update commands
+<!-- generated by git-cliff -->

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

Makefile

@@ -1,35 +1,46 @@
 # Claude Code Multi-Agent Workflow System Makefile
 # Quick deployment for BMAD and Requirements workflows
 
-.PHONY: help install deploy-bmad deploy-requirements deploy-all clean test
+.PHONY: help install deploy-bmad deploy-requirements deploy-essentials deploy-advanced deploy-all deploy-commands deploy-agents clean test changelog
 
 # Default target
 help:
 	@echo "Claude Code Multi-Agent Workflow - Quick Deployment"
 	@echo ""
+	@echo "Recommended installation: python3 install.py --install-dir ~/.claude"
+	@echo ""
 	@echo "Usage: make [target]"
 	@echo ""
 	@echo "Targets:"
-	@echo "  install              - Install all configurations to Claude Code"
-	@echo "  deploy-bmad         - Deploy BMAD workflow (bmad-pilot)"
-	@echo "  deploy-requirements - Deploy Requirements workflow (requirements-pilot)"
-	@echo "  deploy-commands     - Deploy all slash commands"
-	@echo "  deploy-agents       - Deploy all agent configurations"
-	@echo "  deploy-all          - Deploy everything (commands + agents)"
-	@echo "  test-bmad           - Test BMAD workflow with sample"
-	@echo "  test-requirements   - Test Requirements workflow with sample"
-	@echo "  clean               - Clean generated artifacts"
-	@echo "  help                - Show this help message"
+	@echo "  install              - LEGACY: install all configurations (prefer install.py)"
+	@echo "  deploy-bmad          - Deploy BMAD workflow (bmad-pilot)"
+	@echo "  deploy-requirements  - Deploy Requirements workflow (requirements-pilot)"
+	@echo "  deploy-essentials    - Deploy Development Essentials workflow"
+	@echo "  deploy-advanced      - Deploy Advanced AI Agents"
+	@echo "  deploy-commands      - Deploy all slash commands"
+	@echo "  deploy-agents        - Deploy all agent configurations"
+	@echo "  deploy-all           - Deploy everything (commands + agents)"
+	@echo "  test-bmad            - Test BMAD workflow with sample"
+	@echo "  test-requirements    - Test Requirements workflow with sample"
+	@echo "  changelog            - Update CHANGELOG.md using git-cliff"
+	@echo "  clean                - Clean generated artifacts"
+	@echo "  help                 - Show this help message"
 
 # Configuration paths
 CLAUDE_CONFIG_DIR = ~/.claude
-COMMANDS_DIR = commands
-AGENTS_DIR = agents
-OUTPUT_STYLES_DIR = output-styles
 SPECS_DIR = .claude/specs
 
+# Workflow directories
+BMAD_DIR = bmad-agile-workflow
+REQUIREMENTS_DIR = requirements-driven-workflow
+ESSENTIALS_DIR = development-essentials
+ADVANCED_DIR = advanced-ai-agents
+OUTPUT_STYLES_DIR = output-styles
+
 # Install all configurations
 install: deploy-all
+	@echo "⚠️  LEGACY PATH: make install will be removed in future versions."
+	@echo "    Prefer: python3 install.py --install-dir ~/.claude"
 	@echo "✅ Installation complete!"
 
 # Deploy BMAD workflow
@@ -38,8 +49,8 @@ deploy-bmad:
 	@mkdir -p $(CLAUDE_CONFIG_DIR)/commands
 	@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
 	@mkdir -p $(CLAUDE_CONFIG_DIR)/output-styles
-	@cp $(COMMANDS_DIR)/bmad-pilot.md $(CLAUDE_CONFIG_DIR)/commands/
-	@cp $(AGENTS_DIR)/bmad-*.md $(CLAUDE_CONFIG_DIR)/agents/
+	@cp $(BMAD_DIR)/commands/bmad-pilot.md $(CLAUDE_CONFIG_DIR)/commands/
+	@cp $(BMAD_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
 	@cp $(OUTPUT_STYLES_DIR)/bmad.md $(CLAUDE_CONFIG_DIR)/output-styles/ 2>/dev/null || true
 	@echo "✅ BMAD workflow deployed successfully!"
 	@echo "   Usage: /bmad-pilot \"your feature description\""
@@ -49,16 +60,35 @@ deploy-requirements:
 	@echo "🚀 Deploying Requirements workflow..."
 	@mkdir -p $(CLAUDE_CONFIG_DIR)/commands
 	@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
-	@cp $(COMMANDS_DIR)/requirements-pilot.md $(CLAUDE_CONFIG_DIR)/commands/
-	@cp $(AGENTS_DIR)/requirements-*.md $(CLAUDE_CONFIG_DIR)/agents/
+	@cp $(REQUIREMENTS_DIR)/commands/requirements-pilot.md $(CLAUDE_CONFIG_DIR)/commands/
+	@cp $(REQUIREMENTS_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
 	@echo "✅ Requirements workflow deployed successfully!"
 	@echo "   Usage: /requirements-pilot \"your feature description\""
 
+# Deploy Development Essentials workflow
+deploy-essentials:
+	@echo "🚀 Deploying Development Essentials workflow..."
+	@mkdir -p $(CLAUDE_CONFIG_DIR)/commands
+	@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
+	@cp $(ESSENTIALS_DIR)/commands/*.md $(CLAUDE_CONFIG_DIR)/commands/
+	@cp $(ESSENTIALS_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
+	@echo "✅ Development Essentials deployed successfully!"
+	@echo "   Available commands: /ask, /code, /debug, /test, /review, /optimize, /bugfix, /refactor, /docs, /think"
+
+# Deploy Advanced AI Agents
+deploy-advanced:
+	@echo "🚀 Deploying Advanced AI Agents..."
+	@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
+	@cp $(ADVANCED_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
+	@echo "✅ Advanced AI Agents deployed successfully!"
+
 # Deploy all commands
 deploy-commands:
 	@echo "📦 Deploying all slash commands..."
 	@mkdir -p $(CLAUDE_CONFIG_DIR)/commands
-	@cp $(COMMANDS_DIR)/*.md $(CLAUDE_CONFIG_DIR)/commands/
+	@cp $(BMAD_DIR)/commands/*.md $(CLAUDE_CONFIG_DIR)/commands/
+	@cp $(REQUIREMENTS_DIR)/commands/*.md $(CLAUDE_CONFIG_DIR)/commands/
+	@cp $(ESSENTIALS_DIR)/commands/*.md $(CLAUDE_CONFIG_DIR)/commands/
 	@echo "✅ All commands deployed!"
 	@echo "   Available commands:"
 	@echo "   - /bmad-pilot (Full agile workflow)"
@@ -70,7 +100,10 @@ deploy-commands:
 deploy-agents:
 	@echo "🤖 Deploying all agents..."
 	@mkdir -p $(CLAUDE_CONFIG_DIR)/agents
-	@cp $(AGENTS_DIR)/*.md $(CLAUDE_CONFIG_DIR)/agents/
+	@cp $(BMAD_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
+	@cp $(REQUIREMENTS_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
+	@cp $(ESSENTIALS_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
+	@cp $(ADVANCED_DIR)/agents/*.md $(CLAUDE_CONFIG_DIR)/agents/
 	@echo "✅ All agents deployed!"
 
 # Deploy everything
@@ -105,9 +138,25 @@ clean:
 # Quick deployment shortcuts
 bmad: deploy-bmad
 requirements: deploy-requirements
+essentials: deploy-essentials
+advanced: deploy-advanced
 all: deploy-all
 
 # Version info
 version:
 	@echo "Claude Code Multi-Agent Workflow System v3.1"
-	@echo "BMAD + Requirements-Driven Development"
+	@echo "BMAD + Requirements-Driven Development"
+
+# Update CHANGELOG.md using git-cliff
+changelog:
+	@echo "📝 Updating CHANGELOG.md with git-cliff..."
+	@if ! command -v git-cliff > /dev/null 2>&1; then \
+		echo "❌ git-cliff not found. Installing via Homebrew..."; \
+		brew install git-cliff; \
+	fi
+	@git-cliff -o CHANGELOG.md
+	@echo "✅ CHANGELOG.md updated successfully!"
+	@echo ""
+	@echo "Preview the changes:"
+	@echo "  git diff CHANGELOG.md"
+

PLUGIN_README.md

@@ -1,95 +0,0 @@
-# Claude Code Plugin System
-
-本项目已支持Claude Code插件系统，可以将命令和代理打包成可安装的插件包。
-
-## 插件配置
-
-插件配置文件位于 `.claude-plugin/marketplace.json`，定义了所有可用的插件包。
-
-## 可用插件
-
-### 1. Requirements-Driven Development
-- **描述**: 需求驱动的开发工作流，包含90%质量门控
-- **命令**: `/requirements-pilot`
-- **代理**: requirements-generate, requirements-code, requirements-testing, requirements-review
-
-### 2. BMAD Agile Workflow
-- **描述**: 完整的BMAD敏捷工作流（产品负责人→架构师→SM→开发→QA）
-- **命令**: `/bmad-pilot`
-- **代理**: bmad-po, bmad-architect, bmad-sm, bmad-dev, bmad-qa, bmad-orchestrator
-
-### 3. Development Essentials
-- **描述**: 核心开发命令套件
-- **命令**: `/code`, `/debug`, `/test`, `/optimize`, `/review`, `/bugfix`, `/refactor`, `/docs`, `/ask`, `/think`
-- **代理**: code, bugfix, bugfix-verify, code-optimize, debug, develop
-
-### 4. Advanced AI Agents
-- **描述**: 高级AI代理，集成GPT-5进行深度分析
-- **代理**: gpt5
-
-## 使用插件命令
-
-### 列出所有可用插件
-```bash
-/plugin list
-```
-
-### 查看插件详情
-```bash
-/plugin info <plugin-name>
-```
-例如：`/plugin info requirements-driven-development`
-
-### 安装插件
-```bash
-/plugin install <plugin-name>
-```
-例如：`/plugin install bmad-agile-workflow`
-
-### 移除插件
-```bash
-/plugin remove <plugin-name>
-```
-
-## 创建自定义插件
-
-要创建自己的插件：
-
-1. 在 `.claude-plugin/marketplace.json` 中添加新的插件定义
-2. 指定插件包含的命令和代理文件路径
-3. 设置适当的元数据（版本、作者、关键词等）
-
-示例插件结构：
-```json
-{
-  "name": "my-custom-plugin",
-  "source": "./",
-  "description": "自定义插件描述",
-  "version": "1.0.0",
-  "commands": [
-    "./commands/my-command.md"
-  ],
-  "agents": [
-    "./agents/my-agent.md"
-  ]
-}
-```
-
-## 分享插件
-
-要分享插件给其他项目：
-1. 复制整个 `.claude-plugin` 目录到目标项目
-2. 确保相关的命令和代理文件存在
-3. 在新项目中使用 `/plugin` 命令管理插件
-
-## 注意事项
-
-- 插件系统遵循Claude Code的插件规范
-- 所有命令和代理文件必须是有效的Markdown格式
-- 插件配置支持版本管理和依赖关系
-- 插件可以包含多个命令、代理和输出样式
-
-## 相关文档
-
-- [Claude Code插件文档](https://docs.claude.com/en/docs/claude-code/plugins)
-- [示例插件仓库](https://github.com/wshobson/agents)

README-zh.md

@@ -1,288 +0,0 @@
-# Claude Code 多智能体工作流系统
-
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Claude Code](https://img.shields.io/badge/Claude-Code-blue)](https://claude.ai/code)
-[![Version](https://img.shields.io/badge/Version-3.2-green)](https://github.com/)
-[![Plugin Ready](https://img.shields.io/badge/Plugin-Ready-purple)](https://docs.claude.com/en/docs/claude-code/plugins)
-
-> 企业级敏捷开发工作流自动化与多智能体编排
-
-[English](README.md)
-
-## 🚀 BMAD 方法论：敏捷开发自动化
-
-**BMAD (Business-Minded Agile Development)** 将您的开发流程转换为全自动化的敏捷工作流，配备角色化 AI 智能体和质量门控。
-
-### 一条命令，完整工作流
-
-```bash
-/bmad-pilot "构建电商结账系统，集成支付功能"
-# 自动化：产品 → 架构 → 冲刺 → 开发 → 审查 → 测试
-```
-
-## 🎯 BMAD 工作流架构
-
-```mermaid
-graph LR
-    PO[产品负责人] -->|PRD 90+| Architect[架构师]
-    Architect -->|设计 90+| SM[Scrum Master]
-    SM -->|冲刺计划| Dev[开发者]
-    Dev -->|代码| Review[审查]
-    Review -->|Pass/Fail| QA[测试]
-    QA -->|测试| Done[完成]
-```
-
-### 核心特性
-
-- **🤖 6个专业智能体**：PO、Architect、SM、Dev、Review、QA
-- **📊 质量门控**：90% 阈值自动优化
-- **✅ 确认节点**：关键阶段用户确认
-- **📁 持久化产物**：所有文档保存至 `./.claude/specs/`
-- **🔄 迭代优化**：自动改进直至质量达标
-
-## 📋 BMAD 智能体与角色
-
-| 智能体 | 角色 | 质量门控 | 输出 |
-|--------|------|----------|------|
-| **bmad-po** (Sarah) | 产品需求收集 | 90/100 PRD 评分 | `01-product-requirements.md` |
-| **bmad-architect** (Winston) | 技术设计与架构 | 90/100 设计评分 | `02-system-architecture.md` |
-| **bmad-sm** (Mike) | 冲刺计划与任务分解 | 用户确认 | `03-sprint-plan.md` |
-| **bmad-dev** (Alex) | 功能实现 | 代码完成 | 实现文件 |
-| **bmad-review** | 独立代码审查 | Pass/Risk/Fail | `04-dev-reviewed.md` |
-| **bmad-qa** (Emma) | 测试与质量保证 | 测试执行 | `05-qa-report.md` |
-
-## 🚀 快速开始
-
-### 安装方法
-
-#### 方法1：插件系统（推荐）🎯
-
-```bash
-/plugin github.com/cexll/myclaude
-```
-
-#### 方法2：传统安装
-
-```bash
-# 克隆仓库
-git clone https://github.com/your-repo/claude-code-workflows.git
-cd claude-code-workflows
-
-# 使用 make 安装所有配置
-make install
-
-# 或部署特定工作流
-make deploy-bmad          # 仅部署 BMAD 工作流
-make deploy-requirements  # 仅部署 Requirements 工作流
-make deploy-all          # 部署所有命令和智能体
-```
-
-### 基本 BMAD 工作流
-
-```bash
-# 完整敏捷工作流（所有阶段）
-/bmad-pilot "用户认证系统，支持 OAuth2 和多因素认证"
-
-# 快速原型（跳过测试）
-/bmad-pilot "管理后台" --skip-tests
-
-# 直接开发（跳过冲刺计划）
-/bmad-pilot "修复登录问题" --direct-dev
-
-# 跳过仓库扫描（使用现有上下文）
-/bmad-pilot "添加功能" --skip-scan
-```
-
-### 工作流产物
-
-每次 BMAD 运行创建结构化文档：
-
-```
-.claude/specs/user-authentication/
-├── 00-repository-context.md    # 仓库分析
-├── 01-product-requirements.md  # PRD 及业务目标
-├── 02-system-architecture.md   # 技术设计
-├── 03-sprint-plan.md           # 冲刺任务
-├── 04-dev-reviewed.md          # 代码审查报告（v3.1 新增）
-└── 05-qa-report.md            # 测试结果
-```
-
-## 🎨 BMAD 输出样式
-
-BMAD 工作流使用专门的输出样式：
-- 创建阶段隔离的上下文
-- 管理智能体交接
-- 跟踪质量评分
-- 处理确认门控
-- 支持 Codex CLI 集成
-
-## ⚡ v3.2 插件系统
-
-### 🔌 原生插件支持（新增）
-本项目现已包含原生 Claude Code 插件支持，提供4个即装即用的插件包：
-
-#### 可用插件
-
-| 插件 | 描述 | 命令 | 智能体 |
-|------|------|------|--------|
-| **bmad-agile-workflow** | 完整 BMAD 方法论及角色化智能体 | `/bmad-pilot` | bmad-po, bmad-architect, bmad-sm, bmad-dev, bmad-qa |
-| **requirements-driven-development** | 精简需求工作流 | `/requirements-pilot` | requirements-generate, requirements-code, requirements-review |
-| **development-essentials** | 核心开发命令 | `/code`, `/debug`, `/test`, `/optimize` | code, bugfix, debug, develop |
-| **advanced-ai-agents** | GPT-5 深度分析集成 | - | gpt5 |
-
-#### 使用插件
-
-```bash
-# 列出所有可用插件
-/plugin list
-
-# 获取插件详细信息
-/plugin info bmad-agile-workflow
-
-# 安装插件以激活其命令和智能体
-/plugin install requirements-driven-development
-
-# 移除已安装的插件
-/plugin remove development-essentials
-```
-
-#### 插件配置
-插件定义在 `.claude-plugin/marketplace.json`，遵循 Claude Code 插件规范。每个插件包含：
-- 命令（斜杠命令）
-- 智能体（专业 AI 智能体）
-- 元数据（版本、作者、关键词）
-- 类别分类
-
-## ⚡ v3.1 特性
-
-### 独立代码审查智能体
-- **bmad-review**：Dev 和 QA 之间的自动审查
-- **双版本支持**：
-  - 标准版：Claude Code 原生审查
-  - 增强版：通过 Codex CLI 调用 GPT-5
-- **三级状态**：Pass / Pass with Risk / Fail
-
-### 增强工作流
-- Dev → Review → QA 质量链
-- 自动更新冲刺计划
-- 针对性 QA 测试建议
-
-## 📊 质量评分系统
-
-### PRD 质量（100分）
-- 业务价值：30
-- 功能需求：25
-- 用户体验：20
-- 技术约束：15
-- 范围与优先级：10
-
-### 架构质量（100分）
-- 设计质量：30
-- 技术选型：25
-- 可扩展性：20
-- 安全性：15
-- 可行性：10
-
-### 审查状态
-- **Pass**：无问题，进入 QA
-- **Pass with Risk**：非关键问题
-- **Fail**：必须返回 Dev
-
-## 🔧 高级用法
-
-### 仓库上下文
-BMAD 自动扫描仓库了解：
-- 技术栈
-- 项目结构
-- 现有模式
-- 依赖关系
-- 编码规范
-
-### 交互式优化
-每个阶段支持迭代改进：
-```
-PO: "这是 PRD（评分：75/100）"
-用户: "添加移动端支持和离线模式"
-PO: "更新的 PRD（评分：92/100）✅"
-```
-
-### 确认门控
-关键阶段需要明确确认：
-```
-架构师: "技术设计完成（评分：93/100）"
-系统: "准备继续？(yes/no)"
-用户: yes
-```
-
----
-
-## 🏭 Requirements-Driven 工作流
-
-适用于简单项目的轻量级替代方案：
-
-```bash
-/requirements-pilot "实现 JWT 认证"
-# 自动化：需求 → 代码 → 审查 → 测试
-```
-
-### 特性
-- 90% 质量门控
-- 自动优化循环
-- 实现导向规格
-- 实用主义优先
-
-## 🛠️ 其他命令
-
-### 开发命令
-- `/ask` - 技术咨询
-- `/code` - 直接实现
-- `/debug` - 系统化调试
-- `/test` - 测试策略
-- `/review` - 代码验证
-- `/optimize` - 性能优化
-- `/bugfix` - 错误解决
-- `/refactor` - 代码改进
-- `/docs` - 文档生成
-- `/think` - 高级分析
-
-### 手动工作流示例
-```bash
-/ask "实时消息的设计模式"
-/code "实现 WebSocket 服务器"
-/test "创建集成测试"
-/review "验证安全性"
-```
-
-## 📄 许可证
-
-MIT 许可证 - 查看 [LICENSE](LICENSE) 文件
-
-## 🙋 支持
-
-- **文档**：查看 `/commands/` 和 `/agents/` 目录
-- **插件指南**：查看 [PLUGIN_README.md](PLUGIN_README.md) 了解插件系统详情
-- **问题**：GitHub issues 用于报告 bug 和功能请求
-- **Makefile 帮助**：运行 `make help` 查看所有部署选项
-- **Claude Code 文档**：[插件系统](https://docs.claude.com/en/docs/claude-code/plugins)
-
-### 可用的 Make 命令
-
-```bash
-make install              # 安装所有配置到 Claude Code
-make deploy-bmad         # 仅部署 BMAD 工作流
-make deploy-requirements # 仅部署 Requirements 工作流
-make deploy-commands     # 部署所有斜杠命令
-make deploy-agents       # 部署所有智能体配置
-make test-bmad          # 测试 BMAD 工作流示例
-make test-requirements  # 测试 Requirements 工作流示例
-make clean              # 清理生成的文件
-make help               # 显示所有可用命令
-```
-
----
-
-**使用 BMAD 转型您的开发** - 一条命令，完整敏捷工作流，质量保证。
-
-*通过 `/plugin install bmad-agile-workflow` 安装或使用传统安装方法。*
-
-*让专业的 AI 智能体处理专业工作。*

README.md

@@ -1,289 +1,484 @@
+[中文](README_CN.md) [English](README.md)
+
 # Claude Code Multi-Agent Workflow System
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Run in Smithery](https://smithery.ai/badge/skills/cexll)](https://smithery.ai/skills?ns=cexll&utm_source=github&utm_medium=badge)
+
+
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 [![Claude Code](https://img.shields.io/badge/Claude-Code-blue)](https://claude.ai/code)
-[![Version](https://img.shields.io/badge/Version-3.2-green)](https://github.com/)
-[![Plugin Ready](https://img.shields.io/badge/Plugin-Ready-purple)](https://docs.claude.com/en/docs/claude-code/plugins)
+[![Version](https://img.shields.io/badge/Version-5.2-green)](https://github.com/cexll/myclaude)
 
-> Enterprise-grade agile development workflow automation with multi-agent orchestration
+> AI-powered development automation with multi-backend execution (Codex/Claude/Gemini)
 
-[中文](README-zh.md)
+## Core Concept: Multi-Backend Architecture
 
-## 🚀 BMAD Methodology: Agile Development Automation
+This system leverages a **dual-agent architecture** with pluggable AI backends:
 
-**BMAD (Business-Minded Agile Development)** transforms your development process into a fully automated agile workflow with role-based AI agents and quality gates.
+| Role | Agent | Responsibility |
+|------|-------|----------------|
+| **Orchestrator** | Claude Code | Planning, context gathering, verification, user interaction |
+| **Executor** | codeagent-wrapper | Code editing, test execution (Codex/Claude/Gemini backends) |
 
-### One Command, Complete Workflow
+**Why this separation?**
+- Claude Code excels at understanding context and orchestrating complex workflows
+- Specialized backends (Codex for code, Claude for reasoning, Gemini for prototyping) excel at focused execution
+- Backend selection via `--backend codex|claude|gemini` matches the model to the task
+
+## Quick Start(Please execute in Powershell on Windows)
 
 ```bash
-/bmad-pilot "Build e-commerce checkout system with payment integration"
-# Automated: Product → Architecture → Sprint → Dev → Review → QA
+git clone https://github.com/cexll/myclaude.git
+cd myclaude
+python3 install.py --install-dir ~/.claude
 ```
 
-## 🎯 BMAD Workflow Architecture
+## Workflows Overview
 
-```mermaid
-graph LR
-    PO[Product Owner] -->|PRD 90+| Architect
-    Architect -->|Design 90+| SM[Scrum Master]
-    SM -->|Sprint Plan| Dev
-    Dev -->|Code| Review
-    Review -->|Pass/Fail| QA
-    QA -->|Tests| Done
-```
+### 1. Dev Workflow (Recommended)
 
-### Key Features
-
-- **🤖 6 Specialized Agents**: PO, Architect, SM, Dev, Review, QA
-- **📊 Quality Gates**: 90% thresholds with automatic optimization
-- **✅ Approval Points**: User confirmation at critical phases
-- **📁 Persistent Artifacts**: All documents saved to `./.claude/specs/`
-- **🔄 Iterative Refinement**: Automatic improvement until quality met
-
-## 📋 BMAD Agents & Roles
-
-| Agent | Role | Quality Gate | Output |
-|-------|------|--------------|--------|
-| **bmad-po** (Sarah) | Product requirements gathering | 90/100 PRD score | `01-product-requirements.md` |
-| **bmad-architect** (Winston) | Technical design & architecture | 90/100 design score | `02-system-architecture.md` |
-| **bmad-sm** (Mike) | Sprint planning & task breakdown | User approval | `03-sprint-plan.md` |
-| **bmad-dev** (Alex) | Feature implementation | Code completion | Implementation files |
-| **bmad-review** | Independent code review | Pass/Risk/Fail | `04-dev-reviewed.md` |
-| **bmad-qa** (Emma) | Testing & quality assurance | Test execution | `05-qa-report.md` |
-
-## 🚀 Quick Start
-
-### Installation Methods
-
-#### Method 1: Plugin System (Recommended) 🎯
+**The primary workflow for most development tasks.**
 
 ```bash
-# List available plugins
-/plugin github.com/cexll/myclaude
+/dev "implement user authentication with JWT"
 ```
 
-#### Method 2: Traditional Installation
+**6-Step Process:**
+1. **Requirements Clarification** - Interactive Q&A to clarify scope
+2. **Codex Deep Analysis** - Codebase exploration and architecture decisions
+3. **Dev Plan Generation** - Structured task breakdown with test requirements
+4. **Parallel Execution** - Codex executes tasks concurrently
+5. **Coverage Validation** - Enforce ≥90% test coverage
+6. **Completion Summary** - Report with file changes and coverage stats
+
+**Key Features:**
+- Claude Code orchestrates, Codex executes all code changes
+- Automatic task parallelization for speed
+- Mandatory 90% test coverage gate
+- Rollback on failure
+
+**Best For:** Feature development, refactoring, bug fixes with tests
+
+---
+
+### 2. BMAD Agile Workflow
+
+**Full enterprise agile methodology with 6 specialized agents.**
 
 ```bash
-# Clone the repository
-git clone https://github.com/your-repo/claude-code-workflows.git
-cd claude-code-workflows
-
-# Install everything with make
-make install
-
-# Or deploy specific workflows
-make deploy-bmad          # Deploy BMAD workflow only
-make deploy-requirements  # Deploy Requirements workflow only
-make deploy-all          # Deploy all commands and agents
+/bmad-pilot "build e-commerce checkout system"
 ```
 
-### Basic BMAD Workflow
+**Agents:**
+| Agent | Role |
+|-------|------|
+| Product Owner | Requirements & user stories |
+| Architect | System design & tech decisions |
+| Tech Lead | Sprint planning & task breakdown |
+| Developer | Implementation |
+| Code Reviewer | Quality assurance |
+| QA Engineer | Testing & validation |
+
+**Process:**
+```
+Requirements → Architecture → Sprint Plan → Development → Review → QA
+     ↓              ↓             ↓            ↓          ↓       ↓
+   PRD.md      DESIGN.md     SPRINT.md     Code      REVIEW.md  TEST.md
+```
+
+**Best For:** Large features, team coordination, enterprise projects
+
+---
+
+### 3. Requirements-Driven Workflow
+
+**Lightweight requirements-to-code pipeline.**
 
 ```bash
-# Full agile workflow with all phases
-/bmad-pilot "User authentication system with OAuth2 and MFA"
-
-# Skip testing for quick prototypes
-/bmad-pilot "Admin dashboard" --skip-tests
-
-# Direct development (skip sprint planning)
-/bmad-pilot "Bug fix for login issue" --direct-dev
-
-# Skip repository scanning (use existing context)
-/bmad-pilot "Add feature" --skip-scan
+/requirements-pilot "implement API rate limiting"
 ```
 
-### Workflow Artifacts
+**Process:**
+1. Requirements generation with quality scoring
+2. Implementation planning
+3. Code generation
+4. Review and testing
 
-Each BMAD run creates structured documentation:
+**Best For:** Quick prototypes, well-defined features
 
-```
-.claude/specs/user-authentication/
-├── 00-repository-context.md    # Repository analysis
-├── 01-product-requirements.md  # PRD with business goals
-├── 02-system-architecture.md   # Technical design
-├── 03-sprint-plan.md           # Sprint tasks
-├── 04-dev-reviewed.md          # Code review report (NEW v3.1)
-└── 05-qa-report.md            # Test results
-```
+---
 
-## 🎨 BMAD Output Style
+### 4. Development Essentials
 
-The BMAD workflow uses a specialized output style that:
-- Creates phase-separated contexts
-- Manages agent handoffs
-- Tracks quality scores
-- Handles approval gates
-- Supports Codex CLI integration
+**Direct commands for daily coding tasks.**
 
-## ⚡ v3.2 Plugin System
+| Command | Purpose |
+|---------|---------|
+| `/code` | Implement a feature |
+| `/debug` | Debug an issue |
+| `/test` | Write tests |
+| `/review` | Code review |
+| `/optimize` | Performance optimization |
+| `/refactor` | Code refactoring |
+| `/docs` | Documentation |
 
-### 🔌 Native Plugin Support (NEW)
-This project now includes native Claude Code plugin support with 4 ready-to-use plugin packages:
+**Best For:** Quick tasks, no workflow overhead needed
 
-#### Available Plugins
+## Enterprise Workflow Features
 
-| Plugin | Description | Commands | Agents |
-|--------|------------|----------|--------|
-| **bmad-agile-workflow** | Full BMAD methodology with role-based agents | `/bmad-pilot` | bmad-po, bmad-architect, bmad-sm, bmad-dev, bmad-qa |
-| **requirements-driven-development** | Streamlined requirements workflow | `/requirements-pilot` | requirements-generate, requirements-code, requirements-review |
-| **development-essentials** | Core development commands | `/code`, `/debug`, `/test`, `/optimize` | code, bugfix, debug, develop |
-| **advanced-ai-agents** | GPT-5 deep analysis integration | - | gpt5 |
+- **Multi-backend execution:** `codeagent-wrapper --backend codex|claude|gemini` (default `codex`) so you can match the model to the task without changing workflows.
+- **GitHub workflow commands:** `/gh-create-issue "short need"` creates structured issues; `/gh-issue-implement 123` pulls issue #123, drives development, and prepares the PR.
+- **Skills + hooks activation:** .claude/hooks run automation (tests, reviews), while `.claude/skills/skill-rules.json` auto-suggests the right skills. Keep hooks enabled in `.claude/settings.json` to activate the enterprise workflow helpers.
 
-#### Using Plugins
+---
 
+## Version Requirements
+
+### Codex CLI
+**Minimum version:** Check compatibility with your installation
+
+The codeagent-wrapper uses these Codex CLI features:
+- `codex e` - Execute commands (shorthand for `codex exec`)
+- `--skip-git-repo-check` - Skip git repository validation
+- `--json` - JSON stream output format
+- `-C <workdir>` - Set working directory
+- `resume <session_id>` - Resume previous sessions
+
+**Verify Codex CLI is installed:**
 ```bash
-# List all available plugins
-/plugin list
-
-# Get detailed information about a plugin
-/plugin info bmad-agile-workflow
-
-# Install a plugin to activate its commands and agents
-/plugin install requirements-driven-development
-
-# Remove an installed plugin
-/plugin remove development-essentials
+which codex
+codex --version
 ```
 
-#### Plugin Configuration
-Plugins are defined in `.claude-plugin/marketplace.json` following the Claude Code plugin specification. Each plugin includes:
-- Commands (slash commands)
-- Agents (specialized AI agents)
-- Metadata (version, author, keywords)
-- Category classification
+### Claude CLI
+**Minimum version:** Check compatibility with your installation
 
-## ⚡ v3.1 Features
+Required features:
+- `--output-format stream-json` - Streaming JSON output format
+- `--setting-sources` - Control setting sources (prevents infinite recursion)
+- `--dangerously-skip-permissions` - Skip permission prompts (use with caution)
+- `-p` - Prompt input flag
+- `-r <session_id>` - Resume sessions
 
-### Independent Code Review Agent
-- **bmad-review**: Automated review between Dev and QA
-- **Dual Version Support**:
-  - Standard: Native Claude Code review
-  - Enhanced: GPT-5 via Codex CLI
-- **Three-tier Status**: Pass / Pass with Risk / Fail
+**Security Note:** The wrapper only adds `--dangerously-skip-permissions` for Claude when explicitly enabled (e.g. `--skip-permissions` / `CODEAGENT_SKIP_PERMISSIONS=true`). Keep it disabled unless you understand the risk.
 
-### Enhanced Workflow
-- Dev → Review → QA quality chain
-- Automatic Sprint plan updates
-- Targeted QA test recommendations
-
-## 📊 Quality Scoring Systems
-
-### PRD Quality (100 points)
-- Business Value: 30
-- Functional Requirements: 25
-- User Experience: 20
-- Technical Constraints: 15
-- Scope & Priorities: 10
-
-### Architecture Quality (100 points)
-- Design Quality: 30
-- Technology Selection: 25
-- Scalability: 20
-- Security: 15
-- Feasibility: 10
-
-### Review Status
-- **Pass**: No issues, proceed to QA
-- **Pass with Risk**: Non-critical issues
-- **Fail**: Must return to Dev
-
-## 🔧 Advanced Usage
-
-### Repository Context
-BMAD automatically scans your repository to understand:
-- Technology stack
-- Project structure
-- Existing patterns
-- Dependencies
-- Conventions
-
-### Interactive Refinement
-Each phase supports iterative improvement:
-```
-PO: "Here's the PRD (Score: 75/100)"
-User: "Add mobile support and offline mode"
-PO: "Updated PRD (Score: 92/100) ✅"
+**Verify Claude CLI is installed:**
+```bash
+which claude
+claude --version
 ```
 
-### Approval Gates
-Critical phases require explicit confirmation:
-```
-Architect: "Technical design complete (Score: 93/100)"
-System: "Ready to proceed? (yes/no)"
-User: yes
+### Gemini CLI
+**Minimum version:** Check compatibility with your installation
+
+Required features:
+- `-o stream-json` - JSON stream output format
+- `-y` - Auto-approve prompts (non-interactive mode)
+- `-r <session_id>` - Resume sessions
+- `-p` - Prompt input flag
+
+**Verify Gemini CLI is installed:**
+```bash
+which gemini
+gemini --version
 ```
 
 ---
 
-## 🏭 Requirements-Driven Workflow
+## Installation
 
-An alternative lightweight workflow for simpler projects:
+### Modular Installation (Recommended)
 
 ```bash
-/requirements-pilot "Implement JWT authentication"
-# Automated: Requirements → Code → Review → Test
+# Install all enabled modules (dev + essentials by default)
+python3 install.py --install-dir ~/.claude
+
+# Install specific module
+python3 install.py --module dev
+
+# List available modules
+python3 install.py --list-modules
+
+# Force overwrite existing files
+python3 install.py --force
 ```
 
-### Features
-- 90% quality gates
-- Automatic optimization loops
-- Implementation-focused specs
-- Pragmatic over architectural
+### Available Modules
 
-## 🛠️ Other Commands
+| Module | Default | Description |
+|--------|---------|-------------|
+| `dev` | ✓ Enabled | Dev workflow + Codex integration |
+| `essentials` | ✓ Enabled | Core development commands |
+| `bmad` | Disabled | Full BMAD agile workflow |
+| `requirements` | Disabled | Requirements-driven workflow |
 
-### Development Commands
-- `/ask` - Technical consultation
-- `/code` - Direct implementation
-- `/debug` - Systematic debugging
-- `/test` - Testing strategies
-- `/review` - Code validation
-- `/optimize` - Performance tuning
-- `/bugfix` - Bug resolution
-- `/refactor` - Code improvement
-- `/docs` - Documentation
-- `/think` - Advanced analysis
+### What Gets Installed
 
-### Manual Workflow Example
-```bash
-/ask "Design patterns for real-time messaging"
-/code "Implement WebSocket server"
-/test "Create integration tests"
-/review "Validate security"
+```
+~/.claude/
+├── bin/
+│   └── codeagent-wrapper    # Main executable
+├── CLAUDE.md                # Core instructions and role definition
+├── commands/                # Slash commands (/dev, /code, etc.)
+├── agents/                  # Agent definitions
+├── skills/
+│   └── codex/
+│       └── SKILL.md         # Codex integration skill
+├── config.json              # Configuration
+└── installed_modules.json   # Installation status
 ```
 
-## 📄 License
+### Customizing Installation Directory
 
-MIT License - see [LICENSE](LICENSE) file
-
-## 🙋 Support
-
-- **Documentation**: Check `/commands/` and `/agents/` directories
-- **Plugin Guide**: See [PLUGIN_README.md](PLUGIN_README.md) for plugin system details
-- **Issues**: GitHub issues for bugs and features
-- **Makefile Help**: Run `make help` for all deployment options
-- **Claude Code Docs**: [Plugin System](https://docs.claude.com/en/docs/claude-code/plugins)
-
-### Available Make Commands
+By default, myclaude installs to `~/.claude`. You can customize this using the `INSTALL_DIR` environment variable:
 
 ```bash
-make install              # Install everything to Claude Code
-make deploy-bmad         # Deploy BMAD workflow only
-make deploy-requirements # Deploy Requirements workflow only
-make deploy-commands     # Deploy all slash commands
-make deploy-agents       # Deploy all agent configurations
-make test-bmad          # Test BMAD workflow sample
-make test-requirements  # Test Requirements workflow sample
-make clean              # Clean generated artifacts
-make help               # Show all available commands
+# Install to custom directory
+INSTALL_DIR=/opt/myclaude bash install.sh
+
+# Update your PATH accordingly
+export PATH="/opt/myclaude/bin:$PATH"
+```
+
+**Directory Structure:**
+- `$INSTALL_DIR/bin/` - codeagent-wrapper binary
+- `$INSTALL_DIR/skills/` - Skill definitions
+- `$INSTALL_DIR/config.json` - Configuration file
+- `$INSTALL_DIR/commands/` - Slash command definitions
+- `$INSTALL_DIR/agents/` - Agent definitions
+
+**Note:** When using a custom installation directory, ensure that `$INSTALL_DIR/bin` is added to your `PATH` environment variable.
+
+### Configuration
+
+Edit `config.json` to customize:
+
+```json
+{
+  "version": "1.0",
+  "install_dir": "~/.claude",
+  "modules": {
+    "dev": {
+      "enabled": true,
+      "operations": [
+        {"type": "merge_dir", "source": "dev-workflow"},
+        {"type": "copy_file", "source": "memorys/CLAUDE.md", "target": "CLAUDE.md"},
+        {"type": "copy_file", "source": "skills/codex/SKILL.md", "target": "skills/codex/SKILL.md"},
+        {"type": "run_command", "command": "bash install.sh"}
+      ]
+    }
+  }
+}
+```
+
+**Operation Types:**
+| Type | Description |
+|------|-------------|
+| `merge_dir` | Merge subdirs (commands/, agents/) into install dir |
+| `copy_dir` | Copy entire directory |
+| `copy_file` | Copy single file to target path |
+| `run_command` | Execute shell command |
+
+---
+
+## Codex Integration
+
+The `codex` skill enables Claude Code to delegate code execution to Codex CLI.
+
+### Usage in Workflows
+
+```bash
+# Codex is invoked via the skill
+codeagent-wrapper - <<'EOF'
+implement @src/auth.ts with JWT validation
+EOF
+```
+
+### Parallel Execution
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: backend_api
+workdir: /project/backend
+---CONTENT---
+implement REST endpoints for /api/users
+
+---TASK---
+id: frontend_ui
+workdir: /project/frontend
+dependencies: backend_api
+---CONTENT---
+create React components consuming the API
+EOF
+```
+
+### Install Codex Wrapper
+
+```bash
+# Automatic (via dev module)
+python3 install.py --module dev
+
+# Manual
+bash install.sh
+```
+
+#### Windows
+
+Windows installs place `codeagent-wrapper.exe` in `%USERPROFILE%\bin`.
+
+```powershell
+# PowerShell (recommended)
+powershell -ExecutionPolicy Bypass -File install.ps1
+
+# Batch (cmd)
+install.bat
+```
+
+**Add to PATH** (if installer doesn't detect it):
+
+```powershell
+# PowerShell - persistent for current user
+[Environment]::SetEnvironmentVariable('PATH', "$HOME\bin;" + [Environment]::GetEnvironmentVariable('PATH','User'), 'User')
+
+# PowerShell - current session only
+$Env:PATH = "$HOME\bin;$Env:PATH"
+```
+
+```batch
+REM cmd.exe - persistent for current user
+setx PATH "%USERPROFILE%\bin;%PATH%"
 ```
 
 ---
 
-**Transform your development with BMAD** - One command, complete agile workflow, quality assured.
+## Workflow Selection Guide
 
-*Install with `/plugin install bmad-agile-workflow` or use traditional installation methods.*
+| Scenario | Recommended Workflow |
+|----------|---------------------|
+| New feature with tests | `/dev` |
+| Quick bug fix | `/debug` or `/code` |
+| Large multi-sprint feature | `/bmad-pilot` |
+| Prototype or POC | `/requirements-pilot` |
+| Code review | `/review` |
+| Performance issue | `/optimize` |
 
-*Let specialized AI agents handle specialized work.*
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Codex wrapper not found:**
+```bash
+# Check PATH
+echo $PATH | grep -q "$HOME/.claude/bin" || echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
+
+# Reinstall
+bash install.sh
+```
+
+**Permission denied:**
+```bash
+python3 install.py --install-dir ~/.claude --force
+```
+
+**Module not loading:**
+```bash
+# Check installation status
+cat ~/.claude/installed_modules.json
+
+# Reinstall specific module
+python3 install.py --module dev --force
+```
+
+### Version Compatibility Issues
+
+**Backend CLI not found:**
+```bash
+# Check if backend CLIs are installed
+which codex
+which claude
+which gemini
+
+# Install missing backends
+# Codex: Follow installation instructions at https://codex.docs
+# Claude: Follow installation instructions at https://claude.ai/docs
+# Gemini: Follow installation instructions at https://ai.google.dev/docs
+```
+
+**Unsupported CLI flags:**
+```bash
+# If you see errors like "unknown flag" or "invalid option"
+
+# Check backend CLI version
+codex --version
+claude --version
+gemini --version
+
+# For Codex: Ensure it supports `e`, `--skip-git-repo-check`, `--json`, `-C`, and `resume`
+# For Claude: Ensure it supports `--output-format stream-json`, `--setting-sources`, `-r`
+# For Gemini: Ensure it supports `-o stream-json`, `-y`, `-r`, `-p`
+
+# Update your backend CLI to the latest version if needed
+```
+
+**JSON parsing errors:**
+```bash
+# If you see "failed to parse JSON output" errors
+
+# Verify the backend outputs stream-json format
+codex e --json "test task"  # Should output newline-delimited JSON
+claude --output-format stream-json -p "test"  # Should output stream JSON
+
+# If not, your backend CLI version may be too old or incompatible
+```
+
+**Infinite recursion with Claude backend:**
+```bash
+# The wrapper prevents this with `--setting-sources ""` flag
+# If you still see recursion, ensure your Claude CLI supports this flag
+
+claude --help | grep "setting-sources"
+
+# If flag is not supported, upgrade Claude CLI
+```
+
+**Session resume failures:**
+```bash
+# Check if session ID is valid
+codex history  # List recent sessions
+claude history
+
+# Ensure backend CLI supports session resumption
+codex resume <session_id> "test"  # Should continue from previous session
+claude -r <session_id> "test"
+
+# If not supported, use new sessions instead of resume mode
+```
+
+---
+
+## Documentation
+
+### Core Guides
+- **[Codeagent-Wrapper Guide](docs/CODEAGENT-WRAPPER.md)** - Multi-backend execution wrapper
+- **[Hooks Documentation](docs/HOOKS.md)** - Custom hooks and automation
+
+### Additional Resources
+- **[Installation Log](install.log)** - Installation history and troubleshooting
+
+---
+
+## License
+
+AGPL-3.0 License - see [LICENSE](LICENSE)
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/cexll/myclaude/issues)
+- **Documentation**: [docs/](docs/)
+
+---
+
+**Claude Code + Codex = Better Development** - Orchestration meets execution.

README_CN.md

@@ -0,0 +1,344 @@
+# Claude Code 多智能体工作流系统
+
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
+[![Claude Code](https://img.shields.io/badge/Claude-Code-blue)](https://claude.ai/code)
+[![Version](https://img.shields.io/badge/Version-5.2-green)](https://github.com/cexll/myclaude)
+
+> AI 驱动的开发自动化 - 多后端执行架构 (Codex/Claude/Gemini)
+
+## 核心概念：多后端架构
+
+本系统采用**双智能体架构**与可插拔 AI 后端：
+
+| 角色 | 智能体 | 职责 |
+|------|-------|------|
+| **编排者** | Claude Code | 规划、上下文收集、验证、用户交互 |
+| **执行者** | codeagent-wrapper | 代码编辑、测试执行（Codex/Claude/Gemini 后端）|
+
+**为什么分离？**
+- Claude Code 擅长理解上下文和编排复杂工作流
+- 专业后端（Codex 擅长代码、Claude 擅长推理、Gemini 擅长原型）专注执行
+- 通过 `--backend codex|claude|gemini` 匹配模型与任务
+
+## 快速开始（windows上请在Powershell中执行）
+
+```bash
+git clone https://github.com/cexll/myclaude.git
+cd myclaude
+python3 install.py --install-dir ~/.claude
+```
+
+## 工作流概览
+
+### 1. Dev 工作流（推荐）
+
+**大多数开发任务的首选工作流。**
+
+```bash
+/dev "实现 JWT 用户认证"
+```
+
+**6 步流程：**
+1. **需求澄清** - 交互式问答明确范围
+2. **Codex 深度分析** - 代码库探索和架构决策
+3. **开发计划生成** - 结构化任务分解和测试要求
+4. **并行执行** - Codex 并发执行任务
+5. **覆盖率验证** - 强制 ≥90% 测试覆盖率
+6. **完成总结** - 文件变更和覆盖率报告
+
+**核心特性：**
+- Claude Code 编排，Codex 执行所有代码变更
+- 自动任务并行化提升速度
+- 强制 90% 测试覆盖率门禁
+- 失败自动回滚
+
+**适用场景：** 功能开发、重构、带测试的 bug 修复
+
+---
+
+### 2. BMAD 敏捷工作流
+
+**包含 6 个专业智能体的完整企业敏捷方法论。**
+
+```bash
+/bmad-pilot "构建电商结账系统"
+```
+
+**智能体角色：**
+| 智能体 | 职责 |
+|-------|------|
+| Product Owner | 需求与用户故事 |
+| Architect | 系统设计与技术决策 |
+| Tech Lead | Sprint 规划与任务分解 |
+| Developer | 实现 |
+| Code Reviewer | 质量保证 |
+| QA Engineer | 测试与验证 |
+
+**流程：**
+```
+需求 → 架构 → Sprint计划 → 开发 → 审查 → QA
+ ↓      ↓       ↓         ↓      ↓      ↓
+PRD.md DESIGN.md SPRINT.md Code REVIEW.md TEST.md
+```
+
+**适用场景：** 大型功能、团队协作、企业项目
+
+---
+
+### 3. 需求驱动工作流
+
+**轻量级需求到代码流水线。**
+
+```bash
+/requirements-pilot "实现 API 限流"
+```
+
+**流程：**
+1. 带质量评分的需求生成
+2. 实现规划
+3. 代码生成
+4. 审查和测试
+
+**适用场景：** 快速原型、明确定义的功能
+
+---
+
+### 4. 开发基础命令
+
+**日常编码任务的直接命令。**
+
+| 命令 | 用途 |
+|------|------|
+| `/code` | 实现功能 |
+| `/debug` | 调试问题 |
+| `/test` | 编写测试 |
+| `/review` | 代码审查 |
+| `/optimize` | 性能优化 |
+| `/refactor` | 代码重构 |
+| `/docs` | 编写文档 |
+
+**适用场景：** 快速任务，无需工作流开销
+
+---
+
+## 安装
+
+### 模块化安装（推荐）
+
+```bash
+# 安装所有启用的模块（默认：dev + essentials）
+python3 install.py --install-dir ~/.claude
+
+# 安装特定模块
+python3 install.py --module dev
+
+# 列出可用模块
+python3 install.py --list-modules
+
+# 强制覆盖现有文件
+python3 install.py --force
+```
+
+### 可用模块
+
+| 模块 | 默认 | 描述 |
+|------|------|------|
+| `dev` | ✓ 启用 | Dev 工作流 + Codex 集成 |
+| `essentials` | ✓ 启用 | 核心开发命令 |
+| `bmad` | 禁用 | 完整 BMAD 敏捷工作流 |
+| `requirements` | 禁用 | 需求驱动工作流 |
+
+### 安装内容
+
+```
+~/.claude/
+├── bin/
+│   └── codeagent-wrapper    # 主可执行文件
+├── CLAUDE.md                # 核心指令和角色定义
+├── commands/                # 斜杠命令 (/dev, /code 等)
+├── agents/                  # 智能体定义
+├── skills/
+│   └── codex/
+│       └── SKILL.md         # Codex 集成技能
+├── config.json              # 配置文件
+└── installed_modules.json   # 安装状态
+```
+
+### 自定义安装目录
+
+默认情况下，myclaude 安装到 `~/.claude`。您可以使用 `INSTALL_DIR` 环境变量自定义安装目录：
+
+```bash
+# 安装到自定义目录
+INSTALL_DIR=/opt/myclaude bash install.sh
+
+# 相应更新您的 PATH
+export PATH="/opt/myclaude/bin:$PATH"
+```
+
+**目录结构：**
+- `$INSTALL_DIR/bin/` - codeagent-wrapper 可执行文件
+- `$INSTALL_DIR/skills/` - 技能定义
+- `$INSTALL_DIR/config.json` - 配置文件
+- `$INSTALL_DIR/commands/` - 斜杠命令定义
+- `$INSTALL_DIR/agents/` - 智能体定义
+
+**注意：** 使用自定义安装目录时，请确保将 `$INSTALL_DIR/bin` 添加到您的 `PATH` 环境变量中。
+
+### 配置
+
+编辑 `config.json` 自定义：
+
+```json
+{
+  "version": "1.0",
+  "install_dir": "~/.claude",
+  "modules": {
+    "dev": {
+      "enabled": true,
+      "operations": [
+        {"type": "merge_dir", "source": "dev-workflow"},
+        {"type": "copy_file", "source": "memorys/CLAUDE.md", "target": "CLAUDE.md"},
+        {"type": "copy_file", "source": "skills/codex/SKILL.md", "target": "skills/codex/SKILL.md"},
+        {"type": "run_command", "command": "bash install.sh"}
+      ]
+    }
+  }
+}
+```
+
+**操作类型：**
+| 类型 | 描述 |
+|------|------|
+| `merge_dir` | 合并子目录 (commands/, agents/) 到安装目录 |
+| `copy_dir` | 复制整个目录 |
+| `copy_file` | 复制单个文件到目标路径 |
+| `run_command` | 执行 shell 命令 |
+
+---
+
+## Codex 集成
+
+`codex` 技能使 Claude Code 能够将代码执行委托给 Codex CLI。
+
+### 工作流中的使用
+
+```bash
+# 通过技能调用 Codex
+codeagent-wrapper - <<'EOF'
+在 @src/auth.ts 中实现 JWT 验证
+EOF
+```
+
+### 并行执行
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: backend_api
+workdir: /project/backend
+---CONTENT---
+实现 /api/users 的 REST 端点
+
+---TASK---
+id: frontend_ui
+workdir: /project/frontend
+dependencies: backend_api
+---CONTENT---
+创建消费 API 的 React 组件
+EOF
+```
+
+### 安装 Codex Wrapper
+
+```bash
+# 自动（通过 dev 模块）
+python3 install.py --module dev
+
+# 手动
+bash install.sh
+```
+
+#### Windows 系统
+
+Windows 系统会将 `codeagent-wrapper.exe` 安装到 `%USERPROFILE%\bin`。
+
+```powershell
+# PowerShell（推荐）
+powershell -ExecutionPolicy Bypass -File install.ps1
+
+# 批处理（cmd）
+install.bat
+```
+
+**添加到 PATH**（如果安装程序未自动检测）：
+
+```powershell
+# PowerShell - 永久添加（当前用户）
+[Environment]::SetEnvironmentVariable('PATH', "$HOME\bin;" + [Environment]::GetEnvironmentVariable('PATH','User'), 'User')
+
+# PowerShell - 仅当前会话
+$Env:PATH = "$HOME\bin;$Env:PATH"
+```
+
+```batch
+REM cmd.exe - 永久添加（当前用户）
+setx PATH "%USERPROFILE%\bin;%PATH%"
+```
+
+---
+
+## 工作流选择指南
+
+| 场景 | 推荐工作流 |
+|------|----------|
+| 带测试的新功能 | `/dev` |
+| 快速 bug 修复 | `/debug` 或 `/code` |
+| 大型多 Sprint 功能 | `/bmad-pilot` |
+| 原型或 POC | `/requirements-pilot` |
+| 代码审查 | `/review` |
+| 性能问题 | `/optimize` |
+
+---
+
+## 故障排查
+
+### 常见问题
+
+**Codex wrapper 未找到：**
+```bash
+# 检查 PATH
+echo $PATH | grep -q "$HOME/.claude/bin" || echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
+
+# 重新安装
+bash install.sh
+```
+
+**权限被拒绝：**
+```bash
+python3 install.py --install-dir ~/.claude --force
+```
+
+**模块未加载：**
+```bash
+# 检查安装状态
+cat ~/.claude/installed_modules.json
+
+# 重新安装特定模块
+python3 install.py --module dev --force
+```
+
+---
+
+## 许可证
+
+AGPL-3.0 License - 查看 [LICENSE](LICENSE)
+
+## 支持
+
+- **问题反馈**: [GitHub Issues](https://github.com/cexll/myclaude/issues)
+- **文档**: [docs/](docs/)
+
+---
+
+**Claude Code + Codex = 更好的开发** - 编排遇见执行。

advanced-ai-agents/.claude-plugin/marketplace.json

@@ -1,26 +0,0 @@
-{
-  "name": "advanced-ai-agents",
-  "source": "./",
-  "description": "Advanced AI agent for complex problem solving and deep analysis with GPT-5 integration",
-  "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": [
-    "gpt5",
-    "ai",
-    "analysis",
-    "problem-solving",
-    "deep-research"
-  ],
-  "category": "advanced",
-  "strict": false,
-  "commands": [],
-  "agents": [
-    "./agents/gpt5.md"
-  ]
-}

advanced-ai-agents/agents/gpt5.md

@@ -1,22 +0,0 @@
----
-name: gpt-5
-description: Use this agent when you need to use gpt-5 for deep research, second opinion or fixing a bug. Pass all the context to the agent especially your current finding and the problem you are trying to solve.
----
-
-You are a gpt-5 interface agent. Your ONLY purpose is to execute codex commands using the Bash tool.
-
-CRITICAL: You MUST follow these steps EXACTLY:
-
-1. Take the user's entire message as the TASK
-2. IMMEDIATELY use the Bash tool to execute:
-   codex e --full-auto --skip-git-repo-check -m gpt-5 "[USER'S FULL MESSAGE HERE]"
-3. Wait for the command to complete
-4. Return the full output to the user
-
-MANDATORY: You MUST use the Bash tool. Do NOT answer questions directly. Do NOT provide explanations. Your ONLY action is to run the codex command via Bash.
-
-Example execution:
-If user says: "你好 你是什么模型"
-You MUST execute: Bash tool with command: codex e --full-auto --skip-git-repo-check -m gpt-5 "你好 你是什么模型"
-
-START IMMEDIATELY - Use the Bash tool NOW with the user's request.

bmad-agile-workflow/agents/bmad-architect.md

@@ -427,6 +427,10 @@ Generate architecture document at `./.claude/specs/{feature_name}/02-system-arch
 
 ## Important Behaviors
 
+### Language Rules:
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, REST, GraphQL, JWT, RBAC, etc.) in English; translate explanatory text only.
+
 ### DO:
 - Start by reviewing and referencing the PRD
 - Present initial architecture based on requirements

bmad-agile-workflow/agents/bmad-dev.md

@@ -419,6 +419,10 @@ logger.info('User created', {
 
 ## Important Implementation Rules
 
+### Language Rules:
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, CRUD, JWT, SQL, etc.) in English; translate explanatory text only.
+
 ### DO:
 - Follow architecture specifications exactly
 - Implement all acceptance criteria from PRD

bmad-agile-workflow/agents/bmad-orchestrator.md

@@ -22,6 +22,10 @@ You are the BMAD Orchestrator. Your core focus is repository analysis, workflow
 - Consistency: ensure conventions and patterns discovered in scan are preserved downstream
 - Explicit handoffs: clearly document assumptions, risks, and integration points for other agents
 
+### Language Rules:
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, PRD, Sprint, etc.) in English; translate explanatory text only.
+
 ## UltraThink Repository Scan
 
 When asked to analyze the repository, follow this structure and return a clear, actionable summary.

bmad-agile-workflow/agents/bmad-po.md

@@ -313,6 +313,10 @@ Generate PRD at `./.claude/specs/{feature_name}/01-product-requirements.md`:
 
 ## Important Behaviors
 
+### Language Rules:
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, Sprint, PRD, KPI, MVP, etc.) in English; translate explanatory text only.
+
 ### DO:
 - Start immediately with greeting and initial understanding
 - Show quality scores transparently

bmad-agile-workflow/agents/bmad-qa.md

@@ -478,6 +478,10 @@ module.exports = {
 
 ## Important Testing Rules
 
+### Language Rules:
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, E2E, CI/CD, Mock, etc.) in English; translate explanatory text only.
+
 ### DO:
 - Test all acceptance criteria from PRD
 - Cover happy path, edge cases, and error scenarios

bmad-agile-workflow/agents/bmad-review.md

@@ -45,3 +45,7 @@ You are an independent code review agent responsible for conducting reviews betw
 - Focus on actionable findings
 - Provide specific QA guidance
 - Use clear, parseable output format
+
+### Language Rules:
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, PRD, Sprint, etc.) in English; translate explanatory text only.

bmad-agile-workflow/agents/bmad-sm.md

@@ -351,6 +351,10 @@ So that [benefit]
 
 ## Important Behaviors
 
+### Language Rules:
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (Sprint, Epic, Story, Backlog, Velocity, etc.) in English; translate explanatory text only.
+
 ### DO:
 - Read both PRD and Architecture documents thoroughly
 - Create comprehensive task breakdown

cliff.toml

@@ -0,0 +1,72 @@
+# git-cliff configuration file
+# https://git-cliff.org/docs/configuration
+
+[changelog]
+# changelog header
+header = """
+# Changelog
+
+All notable changes to this project will be documented in this file.
+"""
+# template for the changelog body
+body = """
+{% if version %}
+## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}
+## Unreleased
+{% endif %}
+{% for group, commits in commits | group_by(attribute="group") %}
+### {{ group }}
+
+{% for commit in commits %}
+- {{ commit.message | split(pat="\n") | first }}
+{% endfor -%}
+{% endfor -%}
+"""
+# remove the leading and trailing whitespace from the template
+trim = true
+# changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# parse the commits based on https://www.conventionalcommits.org
+conventional_commits = true
+# filter out the commits that are not conventional
+filter_unconventional = false
+# process each line of a commit as an individual commit
+split_commits = false
+# regex for preprocessing the commit messages
+commit_preprocessors = [
+  { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/cexll/myclaude/issues/${2}))" },
+]
+# regex for parsing and grouping commits
+commit_parsers = [
+  { message = "^feat", group = "🚀 Features" },
+  { message = "^fix", group = "🐛 Bug Fixes" },
+  { message = "^doc", group = "📚 Documentation" },
+  { message = "^perf", group = "⚡ Performance" },
+  { message = "^refactor", group = "🚜 Refactor" },
+  { message = "^style", group = "🎨 Styling" },
+  { message = "^test", group = "🧪 Testing" },
+  { message = "^chore\\(release\\):", skip = true },
+  { message = "^chore", group = "⚙️ Miscellaneous Tasks" },
+  { body = ".*security", group = "🛡️ Security" },
+  { message = "^revert", group = "◀️ Revert" },
+  { message = ".*", group = "💼 Other" },
+]
+# protect breaking changes from being skipped due to matching a skipping commit_parser
+protect_breaking_commits = false
+# filter out the commits that are not matched by commit parsers
+filter_commits = false
+# glob pattern for matching git tags
+tag_pattern = "v[0-9]*"
+# regex for skipping tags
+skip_tags = "v0.1.0-beta.1"
+# regex for ignoring tags
+ignore_tags = ""
+# sort the tags topologically
+topo_order = false
+# sort the commits inside sections by oldest/newest order
+sort_commits = "newest"

codeagent-wrapper/.gitignore

@@ -0,0 +1,11 @@
+# Build artifacts
+codeagent-wrapper
+codeagent-wrapper.exe
+*.test
+
+# Coverage reports
+coverage.out
+coverage*.out
+cover.out
+cover_*.out
+coverage.html

codeagent-wrapper/backend.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+)
+
+// Backend defines the contract for invoking different AI CLI backends.
+// Each backend is responsible for supplying the executable command and
+// building the argument list based on the wrapper config.
+type Backend interface {
+	Name() string
+	BuildArgs(cfg *Config, targetArg string) []string
+	Command() string
+}
+
+type CodexBackend struct{}
+
+func (CodexBackend) Name() string { return "codex" }
+func (CodexBackend) Command() string {
+	return "codex"
+}
+func (CodexBackend) BuildArgs(cfg *Config, targetArg string) []string {
+	return buildCodexArgs(cfg, targetArg)
+}
+
+type ClaudeBackend struct{}
+
+func (ClaudeBackend) Name() string { return "claude" }
+func (ClaudeBackend) Command() string {
+	return "claude"
+}
+func (ClaudeBackend) BuildArgs(cfg *Config, targetArg string) []string {
+	return buildClaudeArgs(cfg, targetArg)
+}
+
+const maxClaudeSettingsBytes = 1 << 20 // 1MB
+
+// loadMinimalEnvSettings 从 ~/.claude/setting.json 只提取 env 配置。
+// 只接受字符串类型的值；文件缺失/解析失败/超限都返回空。
+func loadMinimalEnvSettings() map[string]string {
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return nil
+	}
+
+	settingPath := filepath.Join(home, ".claude", "setting.json")
+	info, err := os.Stat(settingPath)
+	if err != nil || info.Size() > maxClaudeSettingsBytes {
+		return nil
+	}
+
+	data, err := os.ReadFile(settingPath)
+	if err != nil {
+		return nil
+	}
+
+	var cfg struct {
+		Env map[string]any `json:"env"`
+	}
+	if err := json.Unmarshal(data, &cfg); err != nil {
+		return nil
+	}
+	if len(cfg.Env) == 0 {
+		return nil
+	}
+
+	env := make(map[string]string, len(cfg.Env))
+	for k, v := range cfg.Env {
+		s, ok := v.(string)
+		if !ok {
+			continue
+		}
+		env[k] = s
+	}
+	if len(env) == 0 {
+		return nil
+	}
+	return env
+}
+
+func buildClaudeArgs(cfg *Config, targetArg string) []string {
+	if cfg == nil {
+		return nil
+	}
+	args := []string{"-p"}
+	if cfg.SkipPermissions {
+		args = append(args, "--dangerously-skip-permissions")
+	}
+
+	// Prevent infinite recursion: disable all setting sources (user, project, local)
+	// This ensures a clean execution environment without CLAUDE.md or skills that would trigger codeagent
+	args = append(args, "--setting-sources", "")
+
+	if cfg.Mode == "resume" {
+		if cfg.SessionID != "" {
+			// Claude CLI uses -r <session_id> for resume.
+			args = append(args, "-r", cfg.SessionID)
+		}
+	}
+	// Note: claude CLI doesn't support -C flag; workdir set via cmd.Dir
+
+	args = append(args, "--output-format", "stream-json", "--verbose", targetArg)
+
+	return args
+}
+
+type GeminiBackend struct{}
+
+func (GeminiBackend) Name() string { return "gemini" }
+func (GeminiBackend) Command() string {
+	return "gemini"
+}
+func (GeminiBackend) BuildArgs(cfg *Config, targetArg string) []string {
+	return buildGeminiArgs(cfg, targetArg)
+}
+
+func buildGeminiArgs(cfg *Config, targetArg string) []string {
+	if cfg == nil {
+		return nil
+	}
+	args := []string{"-o", "stream-json", "-y"}
+
+	if cfg.Mode == "resume" {
+		if cfg.SessionID != "" {
+			args = append(args, "-r", cfg.SessionID)
+		}
+	}
+	// Note: gemini CLI doesn't support -C flag; workdir set via cmd.Dir
+
+	args = append(args, "-p", targetArg)
+
+	return args
+}

codeagent-wrapper/backend_test.go

@@ -0,0 +1,213 @@
+package main
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+func TestClaudeBuildArgs_ModesAndPermissions(t *testing.T) {
+	backend := ClaudeBackend{}
+
+	t.Run("new mode omits skip-permissions by default", func(t *testing.T) {
+		cfg := &Config{Mode: "new", WorkDir: "/repo"}
+		got := backend.BuildArgs(cfg, "todo")
+		want := []string{"-p", "--setting-sources", "", "--output-format", "stream-json", "--verbose", "todo"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("new mode can opt-in skip-permissions", func(t *testing.T) {
+		cfg := &Config{Mode: "new", SkipPermissions: true}
+		got := backend.BuildArgs(cfg, "-")
+		want := []string{"-p", "--dangerously-skip-permissions", "--setting-sources", "", "--output-format", "stream-json", "--verbose", "-"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("resume mode includes session id", func(t *testing.T) {
+		cfg := &Config{Mode: "resume", SessionID: "sid-123", WorkDir: "/ignored"}
+		got := backend.BuildArgs(cfg, "resume-task")
+		want := []string{"-p", "--setting-sources", "", "-r", "sid-123", "--output-format", "stream-json", "--verbose", "resume-task"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("resume mode without session still returns base flags", func(t *testing.T) {
+		cfg := &Config{Mode: "resume", WorkDir: "/ignored"}
+		got := backend.BuildArgs(cfg, "follow-up")
+		want := []string{"-p", "--setting-sources", "", "--output-format", "stream-json", "--verbose", "follow-up"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("resume mode can opt-in skip permissions", func(t *testing.T) {
+		cfg := &Config{Mode: "resume", SessionID: "sid-123", SkipPermissions: true}
+		got := backend.BuildArgs(cfg, "resume-task")
+		want := []string{"-p", "--dangerously-skip-permissions", "--setting-sources", "", "-r", "sid-123", "--output-format", "stream-json", "--verbose", "resume-task"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("nil config returns nil", func(t *testing.T) {
+		if backend.BuildArgs(nil, "ignored") != nil {
+			t.Fatalf("nil config should return nil args")
+		}
+	})
+}
+
+func TestClaudeBuildArgs_GeminiAndCodexModes(t *testing.T) {
+	t.Run("gemini new mode defaults workdir", func(t *testing.T) {
+		backend := GeminiBackend{}
+		cfg := &Config{Mode: "new", WorkDir: "/workspace"}
+		got := backend.BuildArgs(cfg, "task")
+		want := []string{"-o", "stream-json", "-y", "-p", "task"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("gemini resume mode uses session id", func(t *testing.T) {
+		backend := GeminiBackend{}
+		cfg := &Config{Mode: "resume", SessionID: "sid-999"}
+		got := backend.BuildArgs(cfg, "resume")
+		want := []string{"-o", "stream-json", "-y", "-r", "sid-999", "-p", "resume"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("gemini resume mode without session omits identifier", func(t *testing.T) {
+		backend := GeminiBackend{}
+		cfg := &Config{Mode: "resume"}
+		got := backend.BuildArgs(cfg, "resume")
+		want := []string{"-o", "stream-json", "-y", "-p", "resume"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("gemini nil config returns nil", func(t *testing.T) {
+		backend := GeminiBackend{}
+		if backend.BuildArgs(nil, "ignored") != nil {
+			t.Fatalf("nil config should return nil args")
+		}
+	})
+
+	t.Run("codex build args omits bypass flag by default", func(t *testing.T) {
+		const key = "CODEX_BYPASS_SANDBOX"
+		t.Cleanup(func() { os.Unsetenv(key) })
+		os.Unsetenv(key)
+
+		backend := CodexBackend{}
+		cfg := &Config{Mode: "new", WorkDir: "/tmp"}
+		got := backend.BuildArgs(cfg, "task")
+		want := []string{"e", "--skip-git-repo-check", "-C", "/tmp", "--json", "task"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+
+	t.Run("codex build args includes bypass flag when enabled", func(t *testing.T) {
+		const key = "CODEX_BYPASS_SANDBOX"
+		t.Cleanup(func() { os.Unsetenv(key) })
+		os.Setenv(key, "true")
+
+		backend := CodexBackend{}
+		cfg := &Config{Mode: "new", WorkDir: "/tmp"}
+		got := backend.BuildArgs(cfg, "task")
+		want := []string{"e", "--dangerously-bypass-approvals-and-sandbox", "--skip-git-repo-check", "-C", "/tmp", "--json", "task"}
+		if !reflect.DeepEqual(got, want) {
+			t.Fatalf("got %v, want %v", got, want)
+		}
+	})
+}
+
+func TestClaudeBuildArgs_BackendMetadata(t *testing.T) {
+	tests := []struct {
+		backend Backend
+		name    string
+		command string
+	}{
+		{backend: CodexBackend{}, name: "codex", command: "codex"},
+		{backend: ClaudeBackend{}, name: "claude", command: "claude"},
+		{backend: GeminiBackend{}, name: "gemini", command: "gemini"},
+	}
+
+	for _, tt := range tests {
+		if got := tt.backend.Name(); got != tt.name {
+			t.Fatalf("Name() = %s, want %s", got, tt.name)
+		}
+		if got := tt.backend.Command(); got != tt.command {
+			t.Fatalf("Command() = %s, want %s", got, tt.command)
+		}
+	}
+}
+
+func TestLoadMinimalEnvSettings(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	t.Setenv("USERPROFILE", home)
+
+	t.Run("missing file returns empty", func(t *testing.T) {
+		if got := loadMinimalEnvSettings(); len(got) != 0 {
+			t.Fatalf("got %v, want empty", got)
+		}
+	})
+
+	t.Run("valid env returns string map", func(t *testing.T) {
+		dir := filepath.Join(home, ".claude")
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatalf("MkdirAll: %v", err)
+		}
+		path := filepath.Join(dir, "setting.json")
+		data := []byte(`{"env":{"ANTHROPIC_API_KEY":"secret","FOO":"bar"}}`)
+		if err := os.WriteFile(path, data, 0o600); err != nil {
+			t.Fatalf("WriteFile: %v", err)
+		}
+
+		got := loadMinimalEnvSettings()
+		if got["ANTHROPIC_API_KEY"] != "secret" || got["FOO"] != "bar" {
+			t.Fatalf("got %v, want keys present", got)
+		}
+	})
+
+	t.Run("non-string values are ignored", func(t *testing.T) {
+		dir := filepath.Join(home, ".claude")
+		path := filepath.Join(dir, "setting.json")
+		data := []byte(`{"env":{"GOOD":"ok","BAD":123,"ALSO_BAD":true}}`)
+		if err := os.WriteFile(path, data, 0o600); err != nil {
+			t.Fatalf("WriteFile: %v", err)
+		}
+
+		got := loadMinimalEnvSettings()
+		if got["GOOD"] != "ok" {
+			t.Fatalf("got %v, want GOOD=ok", got)
+		}
+		if _, ok := got["BAD"]; ok {
+			t.Fatalf("got %v, want BAD omitted", got)
+		}
+		if _, ok := got["ALSO_BAD"]; ok {
+			t.Fatalf("got %v, want ALSO_BAD omitted", got)
+		}
+	})
+
+	t.Run("oversized file returns empty", func(t *testing.T) {
+		dir := filepath.Join(home, ".claude")
+		path := filepath.Join(dir, "setting.json")
+		data := bytes.Repeat([]byte("a"), maxClaudeSettingsBytes+1)
+		if err := os.WriteFile(path, data, 0o600); err != nil {
+			t.Fatalf("WriteFile: %v", err)
+		}
+		if got := loadMinimalEnvSettings(); len(got) != 0 {
+			t.Fatalf("got %v, want empty", got)
+		}
+	})
+}

codeagent-wrapper/bench_test.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"testing"
+)
+
+// BenchmarkLoggerWrite 测试日志写入性能
+func BenchmarkLoggerWrite(b *testing.B) {
+	logger, err := NewLogger()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer logger.Close()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		logger.Info("benchmark log message")
+	}
+	b.StopTimer()
+	logger.Flush()
+}
+
+// BenchmarkLoggerConcurrentWrite 测试并发日志写入性能
+func BenchmarkLoggerConcurrentWrite(b *testing.B) {
+	logger, err := NewLogger()
+	if err != nil {
+		b.Fatal(err)
+	}
+	defer logger.Close()
+
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		for pb.Next() {
+			logger.Info("concurrent benchmark log message")
+		}
+	})
+	b.StopTimer()
+	logger.Flush()
+}

codeagent-wrapper/concurrent_stress_test.go

@@ -0,0 +1,434 @@
+package main
+
+import (
+	"bufio"
+	"context"
+	"fmt"
+	"os"
+	"regexp"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+func stripTimestampPrefix(line string) string {
+	if !strings.HasPrefix(line, "[") {
+		return line
+	}
+	if idx := strings.Index(line, "] "); idx >= 0 {
+		return line[idx+2:]
+	}
+	return line
+}
+
+// TestConcurrentStressLogger 高并发压力测试
+func TestConcurrentStressLogger(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping stress test in short mode")
+	}
+
+	logger, err := NewLoggerWithSuffix("stress")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+
+	t.Logf("Log file: %s", logger.Path())
+
+	const (
+		numGoroutines  = 100  // 并发协程数
+		logsPerRoutine = 1000 // 每个协程写入日志数
+		totalExpected  = numGoroutines * logsPerRoutine
+	)
+
+	var wg sync.WaitGroup
+	start := time.Now()
+
+	// 启动并发写入
+	for i := 0; i < numGoroutines; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for j := 0; j < logsPerRoutine; j++ {
+				logger.Info(fmt.Sprintf("goroutine-%d-msg-%d", id, j))
+			}
+		}(i)
+	}
+
+	wg.Wait()
+	logger.Flush()
+	elapsed := time.Since(start)
+
+	// 读取日志文件验证
+	data, err := os.ReadFile(logger.Path())
+	if err != nil {
+		t.Fatalf("failed to read log file: %v", err)
+	}
+
+	lines := strings.Split(strings.TrimSpace(string(data)), "\n")
+	actualCount := len(lines)
+
+	t.Logf("Concurrent stress test results:")
+	t.Logf("  Goroutines: %d", numGoroutines)
+	t.Logf("  Logs per goroutine: %d", logsPerRoutine)
+	t.Logf("  Total expected: %d", totalExpected)
+	t.Logf("  Total actual: %d", actualCount)
+	t.Logf("  Duration: %v", elapsed)
+	t.Logf("  Throughput: %.2f logs/sec", float64(totalExpected)/elapsed.Seconds())
+
+	// 验证日志数量
+	if actualCount < totalExpected/10 {
+		t.Errorf("too many logs lost: got %d, want at least %d (10%% of %d)",
+			actualCount, totalExpected/10, totalExpected)
+	}
+	t.Logf("Successfully wrote %d/%d logs (%.1f%%)",
+		actualCount, totalExpected, float64(actualCount)/float64(totalExpected)*100)
+
+	// 验证日志格式（纯文本，无前缀）
+	formatRE := regexp.MustCompile(`^goroutine-\d+-msg-\d+$`)
+	for i, line := range lines[:min(10, len(lines))] {
+		msg := stripTimestampPrefix(line)
+		if !formatRE.MatchString(msg) {
+			t.Errorf("line %d has invalid format: %s", i, line)
+		}
+	}
+}
+
+// TestConcurrentBurstLogger 突发流量测试
+func TestConcurrentBurstLogger(t *testing.T) {
+	if testing.Short() {
+		t.Skip("skipping burst test in short mode")
+	}
+
+	logger, err := NewLoggerWithSuffix("burst")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+
+	t.Logf("Log file: %s", logger.Path())
+
+	const (
+		numBursts          = 10
+		goroutinesPerBurst = 50
+		logsPerGoroutine   = 100
+	)
+
+	totalLogs := 0
+	start := time.Now()
+
+	// 模拟突发流量
+	for burst := 0; burst < numBursts; burst++ {
+		var wg sync.WaitGroup
+		for i := 0; i < goroutinesPerBurst; i++ {
+			wg.Add(1)
+			totalLogs += logsPerGoroutine
+			go func(b, g int) {
+				defer wg.Done()
+				for j := 0; j < logsPerGoroutine; j++ {
+					logger.Info(fmt.Sprintf("burst-%d-goroutine-%d-msg-%d", b, g, j))
+				}
+			}(burst, i)
+		}
+		wg.Wait()
+		time.Sleep(10 * time.Millisecond) // 突发间隔
+	}
+
+	logger.Flush()
+	elapsed := time.Since(start)
+
+	// 验证
+	data, err := os.ReadFile(logger.Path())
+	if err != nil {
+		t.Fatalf("failed to read log file: %v", err)
+	}
+
+	lines := strings.Split(strings.TrimSpace(string(data)), "\n")
+	actualCount := len(lines)
+
+	t.Logf("Burst test results:")
+	t.Logf("  Total bursts: %d", numBursts)
+	t.Logf("  Goroutines per burst: %d", goroutinesPerBurst)
+	t.Logf("  Expected logs: %d", totalLogs)
+	t.Logf("  Actual logs: %d", actualCount)
+	t.Logf("  Duration: %v", elapsed)
+	t.Logf("  Throughput: %.2f logs/sec", float64(totalLogs)/elapsed.Seconds())
+
+	if actualCount < totalLogs/10 {
+		t.Errorf("too many logs lost: got %d, want at least %d (10%% of %d)", actualCount, totalLogs/10, totalLogs)
+	}
+	t.Logf("Successfully wrote %d/%d logs (%.1f%%)",
+		actualCount, totalLogs, float64(actualCount)/float64(totalLogs)*100)
+}
+
+// TestLoggerChannelCapacity 测试 channel 容量极限
+func TestLoggerChannelCapacity(t *testing.T) {
+	logger, err := NewLoggerWithSuffix("capacity")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+
+	const rapidLogs = 2000 // 超过 channel 容量 (1000)
+
+	start := time.Now()
+	for i := 0; i < rapidLogs; i++ {
+		logger.Info(fmt.Sprintf("rapid-log-%d", i))
+	}
+	sendDuration := time.Since(start)
+
+	logger.Flush()
+	flushDuration := time.Since(start) - sendDuration
+
+	t.Logf("Channel capacity test:")
+	t.Logf("  Logs sent: %d", rapidLogs)
+	t.Logf("  Send duration: %v", sendDuration)
+	t.Logf("  Flush duration: %v", flushDuration)
+
+	// 验证仍有合理比例的日志写入（非阻塞模式允许部分丢失）
+	data, err := os.ReadFile(logger.Path())
+	if err != nil {
+		t.Fatal(err)
+	}
+	lines := strings.Split(strings.TrimSpace(string(data)), "\n")
+	actualCount := len(lines)
+
+	if actualCount < rapidLogs/10 {
+		t.Errorf("too many logs lost: got %d, want at least %d (10%% of %d)", actualCount, rapidLogs/10, rapidLogs)
+	}
+	t.Logf("Logs persisted: %d/%d (%.1f%%)", actualCount, rapidLogs, float64(actualCount)/float64(rapidLogs)*100)
+}
+
+// TestLoggerMemoryUsage 内存使用测试
+func TestLoggerMemoryUsage(t *testing.T) {
+	logger, err := NewLoggerWithSuffix("memory")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+
+	const numLogs = 20000
+	longMessage := strings.Repeat("x", 500) // 500 字节长消息
+
+	start := time.Now()
+	for i := 0; i < numLogs; i++ {
+		logger.Info(fmt.Sprintf("log-%d-%s", i, longMessage))
+	}
+	logger.Flush()
+	elapsed := time.Since(start)
+
+	// 检查文件大小
+	info, err := os.Stat(logger.Path())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	expectedTotalSize := int64(numLogs * 500) // 理论最小总字节数
+	expectedMinSize := expectedTotalSize / 10 // 接受最多 90% 丢失
+	actualSize := info.Size()
+
+	t.Logf("Memory/disk usage test:")
+	t.Logf("  Logs written: %d", numLogs)
+	t.Logf("  Message size: 500 bytes")
+	t.Logf("  File size: %.2f MB", float64(actualSize)/1024/1024)
+	t.Logf("  Duration: %v", elapsed)
+	t.Logf("  Write speed: %.2f MB/s", float64(actualSize)/1024/1024/elapsed.Seconds())
+	t.Logf("  Persistence ratio: %.1f%%", float64(actualSize)/float64(expectedTotalSize)*100)
+
+	if actualSize < expectedMinSize {
+		t.Errorf("file size too small: got %d bytes, expected at least %d", actualSize, expectedMinSize)
+	}
+}
+
+// TestLoggerFlushTimeout 测试 Flush 超时机制
+func TestLoggerFlushTimeout(t *testing.T) {
+	logger, err := NewLoggerWithSuffix("flush")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+
+	// 写入一些日志
+	for i := 0; i < 100; i++ {
+		logger.Info(fmt.Sprintf("test-log-%d", i))
+	}
+
+	// 测试 Flush 应该在合理时间内完成
+	start := time.Now()
+	logger.Flush()
+	duration := time.Since(start)
+
+	t.Logf("Flush duration: %v", duration)
+
+	if duration > 6*time.Second {
+		t.Errorf("Flush took too long: %v (expected < 6s)", duration)
+	}
+}
+
+// TestLoggerOrderPreservation 测试日志顺序保持
+func TestLoggerOrderPreservation(t *testing.T) {
+	logger, err := NewLoggerWithSuffix("order")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer logger.Close()
+
+	const numGoroutines = 10
+	const logsPerRoutine = 100
+
+	var wg sync.WaitGroup
+	for i := 0; i < numGoroutines; i++ {
+		wg.Add(1)
+		go func(id int) {
+			defer wg.Done()
+			for j := 0; j < logsPerRoutine; j++ {
+				logger.Info(fmt.Sprintf("G%d-SEQ%04d", id, j))
+			}
+		}(i)
+	}
+
+	wg.Wait()
+	logger.Flush()
+
+	// 读取并验证每个 goroutine 的日志顺序
+	data, err := os.ReadFile(logger.Path())
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	scanner := bufio.NewScanner(strings.NewReader(string(data)))
+	sequences := make(map[int][]int) // goroutine ID -> sequence numbers
+
+	for scanner.Scan() {
+		line := stripTimestampPrefix(scanner.Text())
+		var gid, seq int
+		// Parse format: G0-SEQ0001 (without INFO: prefix)
+		_, err := fmt.Sscanf(line, "G%d-SEQ%04d", &gid, &seq)
+		if err != nil {
+			t.Errorf("invalid log format: %s (error: %v)", line, err)
+			continue
+		}
+		sequences[gid] = append(sequences[gid], seq)
+	}
+
+	// 验证每个 goroutine 内部顺序
+	for gid, seqs := range sequences {
+		for i := 0; i < len(seqs)-1; i++ {
+			if seqs[i] >= seqs[i+1] {
+				t.Errorf("Goroutine %d: out of order at index %d: %d >= %d",
+					gid, i, seqs[i], seqs[i+1])
+			}
+		}
+		if len(seqs) != logsPerRoutine {
+			t.Errorf("Goroutine %d: missing logs, got %d, want %d",
+				gid, len(seqs), logsPerRoutine)
+		}
+	}
+
+	t.Logf("Order preservation test: all %d goroutines maintained sequence order", len(sequences))
+}
+
+func TestConcurrentWorkerPoolLimit(t *testing.T) {
+	orig := runCodexTaskFn
+	defer func() { runCodexTaskFn = orig }()
+
+	logger, err := NewLoggerWithSuffix("pool-limit")
+	if err != nil {
+		t.Fatal(err)
+	}
+	setLogger(logger)
+	t.Cleanup(func() {
+		_ = closeLogger()
+		_ = logger.RemoveLogFile()
+	})
+
+	var active int64
+	var maxSeen int64
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		if task.Context == nil {
+			t.Fatalf("context not propagated for task %s", task.ID)
+		}
+		cur := atomic.AddInt64(&active, 1)
+		for {
+			prev := atomic.LoadInt64(&maxSeen)
+			if cur <= prev || atomic.CompareAndSwapInt64(&maxSeen, prev, cur) {
+				break
+			}
+		}
+		select {
+		case <-task.Context.Done():
+			atomic.AddInt64(&active, -1)
+			return TaskResult{TaskID: task.ID, ExitCode: 130, Error: "context cancelled"}
+		case <-time.After(30 * time.Millisecond):
+		}
+		atomic.AddInt64(&active, -1)
+		return TaskResult{TaskID: task.ID}
+	}
+
+	layers := [][]TaskSpec{{{ID: "t1"}, {ID: "t2"}, {ID: "t3"}, {ID: "t4"}, {ID: "t5"}}}
+	results := executeConcurrentWithContext(context.Background(), layers, 5, 2)
+
+	if len(results) != 5 {
+		t.Fatalf("unexpected result count: got %d", len(results))
+	}
+	if maxSeen > 2 {
+		t.Fatalf("worker pool exceeded limit: saw %d active workers", maxSeen)
+	}
+
+	logger.Flush()
+	data, err := os.ReadFile(logger.Path())
+	if err != nil {
+		t.Fatalf("failed to read log file: %v", err)
+	}
+	content := string(data)
+	if !strings.Contains(content, "worker_limit=2") {
+		t.Fatalf("concurrency planning log missing, content: %s", content)
+	}
+	if !strings.Contains(content, "parallel: start") {
+		t.Fatalf("concurrency start logs missing, content: %s", content)
+	}
+}
+
+func TestConcurrentCancellationPropagation(t *testing.T) {
+	orig := runCodexTaskFn
+	defer func() { runCodexTaskFn = orig }()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		if task.Context == nil {
+			t.Fatalf("context not propagated for task %s", task.ID)
+		}
+		select {
+		case <-task.Context.Done():
+			return TaskResult{TaskID: task.ID, ExitCode: 130, Error: "context cancelled"}
+		case <-time.After(200 * time.Millisecond):
+			return TaskResult{TaskID: task.ID}
+		}
+	}
+
+	layers := [][]TaskSpec{{{ID: "a"}, {ID: "b"}, {ID: "c"}}}
+	go func() {
+		time.Sleep(50 * time.Millisecond)
+		cancel()
+	}()
+
+	results := executeConcurrentWithContext(ctx, layers, 1, 2)
+	if len(results) != 3 {
+		t.Fatalf("unexpected result count: got %d", len(results))
+	}
+
+	cancelled := 0
+	for _, res := range results {
+		if res.ExitCode != 0 {
+			cancelled++
+		}
+	}
+
+	if cancelled == 0 {
+		t.Fatalf("expected cancellation to propagate, got results: %+v", results)
+	}
+}

codeagent-wrapper/config.go

@@ -0,0 +1,279 @@
+package main
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+)
+
+// Config holds CLI configuration
+type Config struct {
+	Mode               string // "new" or "resume"
+	Task               string
+	SessionID          string
+	WorkDir            string
+	ExplicitStdin      bool
+	Timeout            int
+	Backend            string
+	SkipPermissions    bool
+	MaxParallelWorkers int
+}
+
+// ParallelConfig defines the JSON schema for parallel execution
+type ParallelConfig struct {
+	Tasks         []TaskSpec `json:"tasks"`
+	GlobalBackend string     `json:"backend,omitempty"`
+}
+
+// TaskSpec describes an individual task entry in the parallel config
+type TaskSpec struct {
+	ID           string          `json:"id"`
+	Task         string          `json:"task"`
+	WorkDir      string          `json:"workdir,omitempty"`
+	Dependencies []string        `json:"dependencies,omitempty"`
+	SessionID    string          `json:"session_id,omitempty"`
+	Backend      string          `json:"backend,omitempty"`
+	Mode         string          `json:"-"`
+	UseStdin     bool            `json:"-"`
+	Context      context.Context `json:"-"`
+}
+
+// TaskResult captures the execution outcome of a task
+type TaskResult struct {
+	TaskID    string `json:"task_id"`
+	ExitCode  int    `json:"exit_code"`
+	Message   string `json:"message"`
+	SessionID string `json:"session_id"`
+	Error     string `json:"error"`
+	LogPath   string `json:"log_path"`
+	sharedLog bool
+}
+
+var backendRegistry = map[string]Backend{
+	"codex":  CodexBackend{},
+	"claude": ClaudeBackend{},
+	"gemini": GeminiBackend{},
+}
+
+func selectBackend(name string) (Backend, error) {
+	key := strings.ToLower(strings.TrimSpace(name))
+	if key == "" {
+		key = defaultBackendName
+	}
+	if backend, ok := backendRegistry[key]; ok {
+		return backend, nil
+	}
+	return nil, fmt.Errorf("unsupported backend %q", name)
+}
+
+func envFlagEnabled(key string) bool {
+	val, ok := os.LookupEnv(key)
+	if !ok {
+		return false
+	}
+	val = strings.TrimSpace(strings.ToLower(val))
+	switch val {
+	case "", "0", "false", "no", "off":
+		return false
+	default:
+		return true
+	}
+}
+
+func parseBoolFlag(val string, defaultValue bool) bool {
+	val = strings.TrimSpace(strings.ToLower(val))
+	switch val {
+	case "1", "true", "yes", "on":
+		return true
+	case "0", "false", "no", "off":
+		return false
+	default:
+		return defaultValue
+	}
+}
+
+func parseParallelConfig(data []byte) (*ParallelConfig, error) {
+	trimmed := bytes.TrimSpace(data)
+	if len(trimmed) == 0 {
+		return nil, fmt.Errorf("parallel config is empty")
+	}
+
+	tasks := strings.Split(string(trimmed), "---TASK---")
+	var cfg ParallelConfig
+	seen := make(map[string]struct{})
+
+	taskIndex := 0
+	for _, taskBlock := range tasks {
+		taskBlock = strings.TrimSpace(taskBlock)
+		if taskBlock == "" {
+			continue
+		}
+		taskIndex++
+
+		parts := strings.SplitN(taskBlock, "---CONTENT---", 2)
+		if len(parts) != 2 {
+			return nil, fmt.Errorf("task block #%d missing ---CONTENT--- separator", taskIndex)
+		}
+
+		meta := strings.TrimSpace(parts[0])
+		content := strings.TrimSpace(parts[1])
+
+		task := TaskSpec{WorkDir: defaultWorkdir}
+		for _, line := range strings.Split(meta, "\n") {
+			line = strings.TrimSpace(line)
+			if line == "" {
+				continue
+			}
+			kv := strings.SplitN(line, ":", 2)
+			if len(kv) != 2 {
+				continue
+			}
+			key := strings.TrimSpace(kv[0])
+			value := strings.TrimSpace(kv[1])
+
+			switch key {
+			case "id":
+				task.ID = value
+			case "workdir":
+				task.WorkDir = value
+			case "session_id":
+				task.SessionID = value
+				task.Mode = "resume"
+			case "backend":
+				task.Backend = value
+			case "dependencies":
+				for _, dep := range strings.Split(value, ",") {
+					dep = strings.TrimSpace(dep)
+					if dep != "" {
+						task.Dependencies = append(task.Dependencies, dep)
+					}
+				}
+			}
+		}
+
+		if task.Mode == "" {
+			task.Mode = "new"
+		}
+
+		if task.ID == "" {
+			return nil, fmt.Errorf("task block #%d missing id field", taskIndex)
+		}
+		if content == "" {
+			return nil, fmt.Errorf("task block #%d (%q) missing content", taskIndex, task.ID)
+		}
+		if task.Mode == "resume" && strings.TrimSpace(task.SessionID) == "" {
+			return nil, fmt.Errorf("task block #%d (%q) has empty session_id", taskIndex, task.ID)
+		}
+		if _, exists := seen[task.ID]; exists {
+			return nil, fmt.Errorf("task block #%d has duplicate id: %s", taskIndex, task.ID)
+		}
+
+		task.Task = content
+		cfg.Tasks = append(cfg.Tasks, task)
+		seen[task.ID] = struct{}{}
+	}
+
+	if len(cfg.Tasks) == 0 {
+		return nil, fmt.Errorf("no tasks found")
+	}
+
+	return &cfg, nil
+}
+
+func parseArgs() (*Config, error) {
+	args := os.Args[1:]
+	if len(args) == 0 {
+		return nil, fmt.Errorf("task required")
+	}
+
+	backendName := defaultBackendName
+	skipPermissions := envFlagEnabled("CODEAGENT_SKIP_PERMISSIONS")
+	filtered := make([]string, 0, len(args))
+	for i := 0; i < len(args); i++ {
+		arg := args[i]
+		switch {
+		case arg == "--backend":
+			if i+1 >= len(args) {
+				return nil, fmt.Errorf("--backend flag requires a value")
+			}
+			backendName = args[i+1]
+			i++
+			continue
+		case strings.HasPrefix(arg, "--backend="):
+			value := strings.TrimPrefix(arg, "--backend=")
+			if value == "" {
+				return nil, fmt.Errorf("--backend flag requires a value")
+			}
+			backendName = value
+			continue
+		case arg == "--skip-permissions", arg == "--dangerously-skip-permissions":
+			skipPermissions = true
+			continue
+		case strings.HasPrefix(arg, "--skip-permissions="):
+			skipPermissions = parseBoolFlag(strings.TrimPrefix(arg, "--skip-permissions="), skipPermissions)
+			continue
+		case strings.HasPrefix(arg, "--dangerously-skip-permissions="):
+			skipPermissions = parseBoolFlag(strings.TrimPrefix(arg, "--dangerously-skip-permissions="), skipPermissions)
+			continue
+		}
+		filtered = append(filtered, arg)
+	}
+
+	if len(filtered) == 0 {
+		return nil, fmt.Errorf("task required")
+	}
+	args = filtered
+
+	cfg := &Config{WorkDir: defaultWorkdir, Backend: backendName, SkipPermissions: skipPermissions}
+	cfg.MaxParallelWorkers = resolveMaxParallelWorkers()
+
+	if args[0] == "resume" {
+		if len(args) < 3 {
+			return nil, fmt.Errorf("resume mode requires: resume <session_id> <task>")
+		}
+		cfg.Mode = "resume"
+		cfg.SessionID = strings.TrimSpace(args[1])
+		if cfg.SessionID == "" {
+			return nil, fmt.Errorf("resume mode requires non-empty session_id")
+		}
+		cfg.Task = args[2]
+		cfg.ExplicitStdin = (args[2] == "-")
+		if len(args) > 3 {
+			cfg.WorkDir = args[3]
+		}
+	} else {
+		cfg.Mode = "new"
+		cfg.Task = args[0]
+		cfg.ExplicitStdin = (args[0] == "-")
+		if len(args) > 1 {
+			cfg.WorkDir = args[1]
+		}
+	}
+
+	return cfg, nil
+}
+
+const maxParallelWorkersLimit = 100
+
+func resolveMaxParallelWorkers() int {
+	raw := strings.TrimSpace(os.Getenv("CODEAGENT_MAX_PARALLEL_WORKERS"))
+	if raw == "" {
+		return 0
+	}
+
+	value, err := strconv.Atoi(raw)
+	if err != nil || value < 0 {
+		logWarn(fmt.Sprintf("Invalid CODEAGENT_MAX_PARALLEL_WORKERS=%q, falling back to unlimited", raw))
+		return 0
+	}
+
+	if value > maxParallelWorkersLimit {
+		logWarn(fmt.Sprintf("CODEAGENT_MAX_PARALLEL_WORKERS=%d exceeds limit, capping at %d", value, maxParallelWorkersLimit))
+		return maxParallelWorkersLimit
+	}
+
+	return value
+}

codeagent-wrapper/filter.go

@@ -0,0 +1,66 @@
+package main
+
+import (
+	"bytes"
+	"io"
+	"strings"
+)
+
+// geminiNoisePatterns contains stderr patterns to filter for gemini backend
+var geminiNoisePatterns = []string{
+	"[STARTUP]",
+	"Session cleanup disabled",
+	"Warning:",
+	"(node:",
+	"(Use `node --trace-warnings",
+	"Loaded cached credentials",
+	"Loading extension:",
+	"YOLO mode is enabled",
+}
+
+// filteringWriter wraps an io.Writer and filters out lines matching patterns
+type filteringWriter struct {
+	w        io.Writer
+	patterns []string
+	buf      bytes.Buffer
+}
+
+func newFilteringWriter(w io.Writer, patterns []string) *filteringWriter {
+	return &filteringWriter{w: w, patterns: patterns}
+}
+
+func (f *filteringWriter) Write(p []byte) (n int, err error) {
+	f.buf.Write(p)
+	for {
+		line, err := f.buf.ReadString('\n')
+		if err != nil {
+			// incomplete line, put it back
+			f.buf.WriteString(line)
+			break
+		}
+		if !f.shouldFilter(line) {
+			f.w.Write([]byte(line))
+		}
+	}
+	return len(p), nil
+}
+
+func (f *filteringWriter) shouldFilter(line string) bool {
+	for _, pattern := range f.patterns {
+		if strings.Contains(line, pattern) {
+			return true
+		}
+	}
+	return false
+}
+
+// Flush writes any remaining buffered content
+func (f *filteringWriter) Flush() {
+	if f.buf.Len() > 0 {
+		remaining := f.buf.String()
+		if !f.shouldFilter(remaining) {
+			f.w.Write([]byte(remaining))
+		}
+		f.buf.Reset()
+	}
+}

codeagent-wrapper/filter_test.go

@@ -0,0 +1,73 @@
+package main
+
+import (
+	"bytes"
+	"testing"
+)
+
+func TestFilteringWriter(t *testing.T) {
+	tests := []struct {
+		name     string
+		patterns []string
+		input    string
+		want     string
+	}{
+		{
+			name:     "filter STARTUP lines",
+			patterns: geminiNoisePatterns,
+			input:    "[STARTUP] Recording metric\nHello World\n[STARTUP] Another line\n",
+			want:     "Hello World\n",
+		},
+		{
+			name:     "filter Warning lines",
+			patterns: geminiNoisePatterns,
+			input:    "Warning: something bad\nActual output\n",
+			want:     "Actual output\n",
+		},
+		{
+			name:     "filter multiple patterns",
+			patterns: geminiNoisePatterns,
+			input:    "YOLO mode is enabled\nSession cleanup disabled\nReal content\nLoading extension: foo\n",
+			want:     "Real content\n",
+		},
+		{
+			name:     "no filtering needed",
+			patterns: geminiNoisePatterns,
+			input:    "Line 1\nLine 2\nLine 3\n",
+			want:     "Line 1\nLine 2\nLine 3\n",
+		},
+		{
+			name:     "empty input",
+			patterns: geminiNoisePatterns,
+			input:    "",
+			want:     "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var buf bytes.Buffer
+			fw := newFilteringWriter(&buf, tt.patterns)
+			fw.Write([]byte(tt.input))
+			fw.Flush()
+
+			if got := buf.String(); got != tt.want {
+				t.Errorf("got %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestFilteringWriterPartialLines(t *testing.T) {
+	var buf bytes.Buffer
+	fw := newFilteringWriter(&buf, geminiNoisePatterns)
+
+	// Write partial line
+	fw.Write([]byte("Hello "))
+	fw.Write([]byte("World\n"))
+	fw.Flush()
+
+	if got := buf.String(); got != "Hello World\n" {
+		t.Errorf("got %q, want %q", got, "Hello World\n")
+	}
+}

codeagent-wrapper/go.mod

@@ -0,0 +1,3 @@
+module codeagent-wrapper
+
+go 1.21

codeagent-wrapper/log_writer_limit_test.go

@@ -0,0 +1,39 @@
+package main
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestLogWriterWriteLimitsBuffer(t *testing.T) {
+	defer resetTestHooks()
+
+	logger, err := NewLogger()
+	if err != nil {
+		t.Fatalf("NewLogger error: %v", err)
+	}
+	setLogger(logger)
+	defer closeLogger()
+
+	lw := newLogWriter("P:", 10)
+	_, _ = lw.Write([]byte(strings.Repeat("a", 100)))
+
+	if lw.buf.Len() != 10 {
+		t.Fatalf("logWriter buffer len=%d, want %d", lw.buf.Len(), 10)
+	}
+	if !lw.dropped {
+		t.Fatalf("expected logWriter to drop overlong line bytes")
+	}
+
+	lw.Flush()
+	logger.Flush()
+	data, err := os.ReadFile(logger.Path())
+	if err != nil {
+		t.Fatalf("ReadFile error: %v", err)
+	}
+	if !strings.Contains(string(data), "P:aaaaaaa...") {
+		t.Fatalf("log output missing truncated entry, got %q", string(data))
+	}
+}
+

codeagent-wrapper/logger.go

@@ -0,0 +1,663 @@
+package main
+
+import (
+	"bufio"
+	"context"
+	"errors"
+	"fmt"
+	"hash/crc32"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"time"
+)
+
+// Logger writes log messages asynchronously to a temp file.
+// It is intentionally minimal: a buffered channel + single worker goroutine
+// to avoid contention while keeping ordering guarantees.
+type Logger struct {
+	path         string
+	file         *os.File
+	writer       *bufio.Writer
+	ch           chan logEntry
+	flushReq     chan chan struct{}
+	done         chan struct{}
+	closed       atomic.Bool
+	closeOnce    sync.Once
+	workerWG     sync.WaitGroup
+	pendingWG    sync.WaitGroup
+	flushMu      sync.Mutex
+	workerErr    error
+	errorEntries []string // Cache of recent ERROR/WARN entries
+	errorMu      sync.Mutex
+}
+
+type logEntry struct {
+	msg     string
+	isError bool // true for ERROR or WARN levels
+}
+
+// CleanupStats captures the outcome of a cleanupOldLogs run.
+type CleanupStats struct {
+	Scanned      int
+	Deleted      int
+	Kept         int
+	Errors       int
+	DeletedFiles []string
+	KeptFiles    []string
+}
+
+var (
+	processRunningCheck = isProcessRunning
+	processStartTimeFn  = getProcessStartTime
+	removeLogFileFn     = os.Remove
+	globLogFiles        = filepath.Glob
+	fileStatFn          = os.Lstat // Use Lstat to detect symlinks
+	evalSymlinksFn      = filepath.EvalSymlinks
+)
+
+const maxLogSuffixLen = 64
+
+var logSuffixCounter atomic.Uint64
+
+// NewLogger creates the async logger and starts the worker goroutine.
+// The log file is created under os.TempDir() using the required naming scheme.
+func NewLogger() (*Logger, error) {
+	return NewLoggerWithSuffix("")
+}
+
+// NewLoggerWithSuffix creates a logger with an optional suffix in the filename.
+// Useful for tests that need isolated log files within the same process.
+func NewLoggerWithSuffix(suffix string) (*Logger, error) {
+	pid := os.Getpid()
+	filename := fmt.Sprintf("%s-%d", primaryLogPrefix(), pid)
+	var safeSuffix string
+	if suffix != "" {
+		safeSuffix = sanitizeLogSuffix(suffix)
+	}
+	if safeSuffix != "" {
+		filename += "-" + safeSuffix
+	}
+	filename += ".log"
+
+	path := filepath.Clean(filepath.Join(os.TempDir(), filename))
+
+	if err := os.MkdirAll(filepath.Dir(path), 0o700); err != nil {
+		return nil, err
+	}
+
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o600)
+	if err != nil {
+		return nil, err
+	}
+
+	l := &Logger{
+		path:     path,
+		file:     f,
+		writer:   bufio.NewWriterSize(f, 4096),
+		ch:       make(chan logEntry, 1000),
+		flushReq: make(chan chan struct{}, 1),
+		done:     make(chan struct{}),
+	}
+
+	l.workerWG.Add(1)
+	go l.run()
+
+	return l, nil
+}
+
+func sanitizeLogSuffix(raw string) string {
+	trimmed := strings.TrimSpace(raw)
+	if trimmed == "" {
+		return fallbackLogSuffix()
+	}
+
+	var b strings.Builder
+	changed := false
+	for _, r := range trimmed {
+		if isSafeLogRune(r) {
+			b.WriteRune(r)
+		} else {
+			changed = true
+			b.WriteByte('-')
+		}
+		if b.Len() >= maxLogSuffixLen {
+			changed = true
+			break
+		}
+	}
+
+	sanitized := strings.Trim(b.String(), "-.")
+	if sanitized != b.String() {
+		changed = true // Mark if trim removed any characters
+	}
+	if sanitized == "" {
+		return fallbackLogSuffix()
+	}
+
+	if changed || len(sanitized) > maxLogSuffixLen {
+		hash := crc32.ChecksumIEEE([]byte(trimmed))
+		hashStr := fmt.Sprintf("%x", hash)
+
+		maxPrefix := maxLogSuffixLen - len(hashStr) - 1
+		if maxPrefix < 1 {
+			maxPrefix = 1
+		}
+		if len(sanitized) > maxPrefix {
+			sanitized = sanitized[:maxPrefix]
+		}
+
+		sanitized = fmt.Sprintf("%s-%s", sanitized, hashStr)
+	}
+
+	return sanitized
+}
+
+func fallbackLogSuffix() string {
+	next := logSuffixCounter.Add(1)
+	return fmt.Sprintf("task-%d", next)
+}
+
+func isSafeLogRune(r rune) bool {
+	switch {
+	case r >= 'a' && r <= 'z':
+		return true
+	case r >= 'A' && r <= 'Z':
+		return true
+	case r >= '0' && r <= '9':
+		return true
+	case r == '-', r == '_', r == '.':
+		return true
+	default:
+		return false
+	}
+}
+
+// Path returns the underlying log file path (useful for tests/inspection).
+func (l *Logger) Path() string {
+	if l == nil {
+		return ""
+	}
+	return l.path
+}
+
+// Info logs at INFO level.
+func (l *Logger) Info(msg string) { l.log("INFO", msg) }
+
+// Warn logs at WARN level.
+func (l *Logger) Warn(msg string) { l.log("WARN", msg) }
+
+// Debug logs at DEBUG level.
+func (l *Logger) Debug(msg string) { l.log("DEBUG", msg) }
+
+// Error logs at ERROR level.
+func (l *Logger) Error(msg string) { l.log("ERROR", msg) }
+
+// Close signals the worker to flush and close the log file.
+// The log file is NOT removed, allowing inspection after program exit.
+// It is safe to call multiple times.
+// Waits up to CODEAGENT_LOGGER_CLOSE_TIMEOUT_MS (default: 5000) for shutdown; set to 0 to wait indefinitely.
+// Returns an error if shutdown doesn't complete within the timeout.
+func (l *Logger) Close() error {
+	if l == nil {
+		return nil
+	}
+
+	var closeErr error
+
+	l.closeOnce.Do(func() {
+		l.closed.Store(true)
+		close(l.done)
+
+		timeout := loggerCloseTimeout()
+		workerDone := make(chan struct{})
+		go func() {
+			l.workerWG.Wait()
+			close(workerDone)
+		}()
+
+		if timeout > 0 {
+			select {
+			case <-workerDone:
+				// Worker stopped gracefully
+			case <-time.After(timeout):
+				closeErr = fmt.Errorf("logger worker timeout during close")
+				return
+			}
+		} else {
+			<-workerDone
+		}
+
+		if l.workerErr != nil && closeErr == nil {
+			closeErr = l.workerErr
+		}
+	})
+
+	return closeErr
+}
+
+func loggerCloseTimeout() time.Duration {
+	const defaultTimeout = 5 * time.Second
+
+	raw := strings.TrimSpace(os.Getenv("CODEAGENT_LOGGER_CLOSE_TIMEOUT_MS"))
+	if raw == "" {
+		return defaultTimeout
+	}
+	ms, err := strconv.Atoi(raw)
+	if err != nil {
+		return defaultTimeout
+	}
+	if ms <= 0 {
+		return 0
+	}
+	return time.Duration(ms) * time.Millisecond
+}
+
+// RemoveLogFile removes the log file. Should only be called after Close().
+func (l *Logger) RemoveLogFile() error {
+	if l == nil {
+		return nil
+	}
+	return os.Remove(l.path)
+}
+
+// ExtractRecentErrors returns the most recent ERROR and WARN entries from memory cache.
+// Returns up to maxEntries entries in chronological order.
+func (l *Logger) ExtractRecentErrors(maxEntries int) []string {
+	if l == nil || maxEntries <= 0 {
+		return nil
+	}
+
+	l.errorMu.Lock()
+	defer l.errorMu.Unlock()
+
+	if len(l.errorEntries) == 0 {
+		return nil
+	}
+
+	// Return last N entries
+	start := 0
+	if len(l.errorEntries) > maxEntries {
+		start = len(l.errorEntries) - maxEntries
+	}
+
+	result := make([]string, len(l.errorEntries)-start)
+	copy(result, l.errorEntries[start:])
+	return result
+}
+
+// Flush waits for all pending log entries to be written. Primarily for tests.
+// Returns after a 5-second timeout to prevent indefinite blocking.
+func (l *Logger) Flush() {
+	if l == nil {
+		return
+	}
+
+	l.flushMu.Lock()
+	defer l.flushMu.Unlock()
+
+	// Wait for pending entries with timeout
+	done := make(chan struct{})
+	go func() {
+		l.pendingWG.Wait()
+		close(done)
+	}()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	select {
+	case <-done:
+		// All pending entries processed
+	case <-ctx.Done():
+		// Timeout - return without full flush
+		return
+	}
+
+	// Trigger writer flush
+	flushDone := make(chan struct{})
+	select {
+	case l.flushReq <- flushDone:
+		// Wait for flush to complete
+		select {
+		case <-flushDone:
+			// Flush completed
+		case <-time.After(1 * time.Second):
+			// Flush timeout
+		}
+	case <-l.done:
+		// Logger is closing
+	case <-time.After(1 * time.Second):
+		// Timeout sending flush request
+	}
+}
+
+func (l *Logger) log(level, msg string) {
+	if l == nil {
+		return
+	}
+	if l.closed.Load() {
+		return
+	}
+
+	isError := level == "WARN" || level == "ERROR"
+	entry := logEntry{msg: msg, isError: isError}
+	l.flushMu.Lock()
+	l.pendingWG.Add(1)
+	l.flushMu.Unlock()
+
+	select {
+	case l.ch <- entry:
+		// Successfully sent to channel
+	case <-l.done:
+		// Logger is closing, drop this entry
+		l.pendingWG.Done()
+		return
+	}
+}
+
+func (l *Logger) run() {
+	defer l.workerWG.Done()
+
+	ticker := time.NewTicker(500 * time.Millisecond)
+	defer ticker.Stop()
+
+	writeEntry := func(entry logEntry) {
+		timestamp := time.Now().Format("2006-01-02 15:04:05.000")
+		fmt.Fprintf(l.writer, "[%s] %s\n", timestamp, entry.msg)
+
+		// Cache error/warn entries in memory for fast extraction
+		if entry.isError {
+			l.errorMu.Lock()
+			l.errorEntries = append(l.errorEntries, entry.msg)
+			if len(l.errorEntries) > 100 { // Keep last 100
+				l.errorEntries = l.errorEntries[1:]
+			}
+			l.errorMu.Unlock()
+		}
+
+		l.pendingWG.Done()
+	}
+
+	finalize := func() {
+		if err := l.writer.Flush(); err != nil && l.workerErr == nil {
+			l.workerErr = err
+		}
+		if err := l.file.Sync(); err != nil && l.workerErr == nil {
+			l.workerErr = err
+		}
+		if err := l.file.Close(); err != nil && l.workerErr == nil {
+			l.workerErr = err
+		}
+	}
+
+	for {
+		select {
+		case entry, ok := <-l.ch:
+			if !ok {
+				finalize()
+				return
+			}
+			writeEntry(entry)
+
+		case <-ticker.C:
+			_ = l.writer.Flush()
+
+		case flushDone := <-l.flushReq:
+			// Explicit flush request - flush writer and sync to disk
+			_ = l.writer.Flush()
+			_ = l.file.Sync()
+			close(flushDone)
+
+		case <-l.done:
+			for {
+				select {
+				case entry, ok := <-l.ch:
+					if !ok {
+						finalize()
+						return
+					}
+					writeEntry(entry)
+				default:
+					finalize()
+					return
+				}
+			}
+		}
+	}
+}
+
+// cleanupOldLogs scans os.TempDir() for wrapper log files and removes those
+// whose owning process is no longer running (i.e., orphaned logs).
+// It includes safety checks for:
+// - PID reuse: Compares file modification time with process start time
+// - Symlink attacks: Ensures files are within TempDir and not symlinks
+func cleanupOldLogs() (CleanupStats, error) {
+	var stats CleanupStats
+	tempDir := os.TempDir()
+
+	prefixes := logPrefixes()
+	if len(prefixes) == 0 {
+		prefixes = []string{defaultWrapperName}
+	}
+
+	seen := make(map[string]struct{})
+	var matches []string
+	for _, prefix := range prefixes {
+		pattern := filepath.Join(tempDir, fmt.Sprintf("%s-*.log", prefix))
+		found, err := globLogFiles(pattern)
+		if err != nil {
+			logWarn(fmt.Sprintf("cleanupOldLogs: failed to list logs: %v", err))
+			return stats, fmt.Errorf("cleanupOldLogs: %w", err)
+		}
+		for _, path := range found {
+			if _, ok := seen[path]; ok {
+				continue
+			}
+			seen[path] = struct{}{}
+			matches = append(matches, path)
+		}
+	}
+
+	var removeErr error
+
+	for _, path := range matches {
+		stats.Scanned++
+		filename := filepath.Base(path)
+
+		// Security check: Verify file is not a symlink and is within tempDir
+		if shouldSkipFile, reason := isUnsafeFile(path, tempDir); shouldSkipFile {
+			stats.Kept++
+			stats.KeptFiles = append(stats.KeptFiles, filename)
+			if reason != "" {
+				logWarn(fmt.Sprintf("cleanupOldLogs: skipping %s: %s", filename, reason))
+			}
+			continue
+		}
+
+		pid, ok := parsePIDFromLog(path)
+		if !ok {
+			stats.Kept++
+			stats.KeptFiles = append(stats.KeptFiles, filename)
+			continue
+		}
+
+		// Check if process is running
+		if !processRunningCheck(pid) {
+			// Process not running, safe to delete
+			if err := removeLogFileFn(path); err != nil {
+				if errors.Is(err, os.ErrNotExist) {
+					// File already deleted by another process, don't count as success
+					stats.Kept++
+					stats.KeptFiles = append(stats.KeptFiles, filename+" (already deleted)")
+					continue
+				}
+				stats.Errors++
+				logWarn(fmt.Sprintf("cleanupOldLogs: failed to remove %s: %v", filename, err))
+				removeErr = errors.Join(removeErr, fmt.Errorf("failed to remove %s: %w", filename, err))
+				continue
+			}
+			stats.Deleted++
+			stats.DeletedFiles = append(stats.DeletedFiles, filename)
+			continue
+		}
+
+		// Process is running, check for PID reuse
+		if isPIDReused(path, pid) {
+			// PID was reused, the log file is orphaned
+			if err := removeLogFileFn(path); err != nil {
+				if errors.Is(err, os.ErrNotExist) {
+					stats.Kept++
+					stats.KeptFiles = append(stats.KeptFiles, filename+" (already deleted)")
+					continue
+				}
+				stats.Errors++
+				logWarn(fmt.Sprintf("cleanupOldLogs: failed to remove %s (PID reused): %v", filename, err))
+				removeErr = errors.Join(removeErr, fmt.Errorf("failed to remove %s: %w", filename, err))
+				continue
+			}
+			stats.Deleted++
+			stats.DeletedFiles = append(stats.DeletedFiles, filename)
+			continue
+		}
+
+		// Process is running and owns this log file
+		stats.Kept++
+		stats.KeptFiles = append(stats.KeptFiles, filename)
+	}
+
+	if removeErr != nil {
+		return stats, fmt.Errorf("cleanupOldLogs: %w", removeErr)
+	}
+
+	return stats, nil
+}
+
+// isUnsafeFile checks if a file is unsafe to delete (symlink or outside tempDir).
+// Returns (true, reason) if the file should be skipped.
+func isUnsafeFile(path string, tempDir string) (bool, string) {
+	// Check if file is a symlink
+	info, err := fileStatFn(path)
+	if err != nil {
+		if errors.Is(err, os.ErrNotExist) {
+			return true, "" // File disappeared, skip silently
+		}
+		return true, fmt.Sprintf("stat failed: %v", err)
+	}
+
+	// Check if it's a symlink
+	if info.Mode()&os.ModeSymlink != 0 {
+		return true, "refusing to delete symlink"
+	}
+
+	// Resolve any path traversal and verify it's within tempDir
+	resolvedPath, err := evalSymlinksFn(path)
+	if err != nil {
+		return true, fmt.Sprintf("path resolution failed: %v", err)
+	}
+
+	// Get absolute path of tempDir
+	absTempDir, err := filepath.Abs(tempDir)
+	if err != nil {
+		return true, fmt.Sprintf("tempDir resolution failed: %v", err)
+	}
+
+	// Ensure resolved path is within tempDir
+	relPath, err := filepath.Rel(absTempDir, resolvedPath)
+	if err != nil || strings.HasPrefix(relPath, "..") {
+		return true, "file is outside tempDir"
+	}
+
+	return false, ""
+}
+
+// isPIDReused checks if a PID has been reused by comparing file modification time
+// with process start time. Returns true if the log file was created by a different
+// process that previously had the same PID.
+func isPIDReused(logPath string, pid int) bool {
+	// Get file modification time (when log was last written)
+	info, err := fileStatFn(logPath)
+	if err != nil {
+		// If we can't stat the file, be conservative and keep it
+		return false
+	}
+	fileModTime := info.ModTime()
+
+	// Get process start time
+	procStartTime := processStartTimeFn(pid)
+	if procStartTime.IsZero() {
+		// Can't determine process start time
+		// Check if file is very old (>7 days), likely from a dead process
+		if time.Since(fileModTime) > 7*24*time.Hour {
+			return true // File is old enough to be from a different process
+		}
+		return false // Be conservative for recent files
+	}
+
+	// If the log file was modified before the process started, PID was reused
+	// Add a small buffer (1 second) to account for clock skew and file system timing
+	return fileModTime.Add(1 * time.Second).Before(procStartTime)
+}
+
+func parsePIDFromLog(path string) (int, bool) {
+	name := filepath.Base(path)
+	prefixes := logPrefixes()
+	if len(prefixes) == 0 {
+		prefixes = []string{defaultWrapperName}
+	}
+
+	for _, prefix := range prefixes {
+		prefixWithDash := fmt.Sprintf("%s-", prefix)
+		if !strings.HasPrefix(name, prefixWithDash) || !strings.HasSuffix(name, ".log") {
+			continue
+		}
+
+		core := strings.TrimSuffix(strings.TrimPrefix(name, prefixWithDash), ".log")
+		if core == "" {
+			continue
+		}
+
+		pidPart := core
+		if idx := strings.IndexRune(core, '-'); idx != -1 {
+			pidPart = core[:idx]
+		}
+
+		if pidPart == "" {
+			continue
+		}
+
+		pid, err := strconv.Atoi(pidPart)
+		if err != nil || pid <= 0 {
+			continue
+		}
+		return pid, true
+	}
+
+	return 0, false
+}
+
+func logConcurrencyPlanning(limit, total int) {
+	logger := activeLogger()
+	if logger == nil {
+		return
+	}
+	logger.Info(fmt.Sprintf("parallel: worker_limit=%s total_tasks=%d", renderWorkerLimit(limit), total))
+}
+
+func logConcurrencyState(event, taskID string, active, limit int) {
+	logger := activeLogger()
+	if logger == nil {
+		return
+	}
+	logger.Debug(fmt.Sprintf("parallel: %s task=%s active=%d limit=%s", event, taskID, active, renderWorkerLimit(limit)))
+}
+
+func renderWorkerLimit(limit int) string {
+	if limit <= 0 {
+		return "unbounded"
+	}
+	return strconv.Itoa(limit)
+}

codeagent-wrapper/logger_additional_coverage_test.go

@@ -0,0 +1,158 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestLoggerNilReceiverNoop(t *testing.T) {
+	var logger *Logger
+	logger.Info("info")
+	logger.Warn("warn")
+	logger.Debug("debug")
+	logger.Error("error")
+	logger.Flush()
+	if err := logger.Close(); err != nil {
+		t.Fatalf("Close() on nil logger should return nil, got %v", err)
+	}
+}
+
+func TestLoggerConcurrencyLogHelpers(t *testing.T) {
+	setTempDirEnv(t, t.TempDir())
+
+	logger, err := NewLoggerWithSuffix("concurrency")
+	if err != nil {
+		t.Fatalf("NewLoggerWithSuffix error: %v", err)
+	}
+	setLogger(logger)
+	defer closeLogger()
+
+	logConcurrencyPlanning(0, 2)
+	logConcurrencyPlanning(3, 2)
+	logConcurrencyState("start", "task-1", 1, 0)
+	logConcurrencyState("done", "task-1", 0, 3)
+	logger.Flush()
+
+	data, err := os.ReadFile(logger.Path())
+	if err != nil {
+		t.Fatalf("failed to read log file: %v", err)
+	}
+	output := string(data)
+
+	checks := []string{
+		"parallel: worker_limit=unbounded total_tasks=2",
+		"parallel: worker_limit=3 total_tasks=2",
+		"parallel: start task=task-1 active=1 limit=unbounded",
+		"parallel: done task=task-1 active=0 limit=3",
+	}
+	for _, c := range checks {
+		if !strings.Contains(output, c) {
+			t.Fatalf("log output missing %q, got: %s", c, output)
+		}
+	}
+}
+
+func TestLoggerConcurrencyLogHelpersNoopWithoutActiveLogger(t *testing.T) {
+	_ = closeLogger()
+	logConcurrencyPlanning(1, 1)
+	logConcurrencyState("start", "task-1", 0, 1)
+}
+
+func TestLoggerCleanupOldLogsSkipsUnsafeAndHandlesAlreadyDeleted(t *testing.T) {
+	tempDir := setTempDirEnv(t, t.TempDir())
+
+	unsafePath := createTempLog(t, tempDir, fmt.Sprintf("%s-%d.log", primaryLogPrefix(), 222))
+	orphanPath := createTempLog(t, tempDir, fmt.Sprintf("%s-%d.log", primaryLogPrefix(), 111))
+
+	stubFileStat(t, func(path string) (os.FileInfo, error) {
+		if path == unsafePath {
+			return fakeFileInfo{mode: os.ModeSymlink}, nil
+		}
+		return os.Lstat(path)
+	})
+
+	stubProcessRunning(t, func(pid int) bool {
+		if pid == 111 {
+			_ = os.Remove(orphanPath)
+		}
+		return false
+	})
+
+	stats, err := cleanupOldLogs()
+	if err != nil {
+		t.Fatalf("cleanupOldLogs() unexpected error: %v", err)
+	}
+
+	if stats.Scanned != 2 {
+		t.Fatalf("scanned = %d, want %d", stats.Scanned, 2)
+	}
+	if stats.Deleted != 0 {
+		t.Fatalf("deleted = %d, want %d", stats.Deleted, 0)
+	}
+	if stats.Kept != 2 {
+		t.Fatalf("kept = %d, want %d", stats.Kept, 2)
+	}
+	if stats.Errors != 0 {
+		t.Fatalf("errors = %d, want %d", stats.Errors, 0)
+	}
+
+	hasSkip := false
+	hasAlreadyDeleted := false
+	for _, name := range stats.KeptFiles {
+		if strings.Contains(name, "already deleted") {
+			hasAlreadyDeleted = true
+		}
+		if strings.Contains(name, filepath.Base(unsafePath)) {
+			hasSkip = true
+		}
+	}
+	if !hasSkip {
+		t.Fatalf("expected kept files to include unsafe log %q, got %+v", filepath.Base(unsafePath), stats.KeptFiles)
+	}
+	if !hasAlreadyDeleted {
+		t.Fatalf("expected kept files to include already deleted marker, got %+v", stats.KeptFiles)
+	}
+}
+
+func TestLoggerIsUnsafeFileErrorPaths(t *testing.T) {
+	tempDir := t.TempDir()
+
+	t.Run("stat ErrNotExist", func(t *testing.T) {
+		stubFileStat(t, func(string) (os.FileInfo, error) {
+			return nil, os.ErrNotExist
+		})
+
+		unsafe, reason := isUnsafeFile("missing.log", tempDir)
+		if !unsafe || reason != "" {
+			t.Fatalf("expected missing file to be skipped silently, got unsafe=%v reason=%q", unsafe, reason)
+		}
+	})
+
+	t.Run("stat error", func(t *testing.T) {
+		stubFileStat(t, func(string) (os.FileInfo, error) {
+			return nil, fmt.Errorf("boom")
+		})
+
+		unsafe, reason := isUnsafeFile("broken.log", tempDir)
+		if !unsafe || !strings.Contains(reason, "stat failed") {
+			t.Fatalf("expected stat failure to be unsafe, got unsafe=%v reason=%q", unsafe, reason)
+		}
+	})
+
+	t.Run("EvalSymlinks error", func(t *testing.T) {
+		stubFileStat(t, func(string) (os.FileInfo, error) {
+			return fakeFileInfo{}, nil
+		})
+		stubEvalSymlinks(t, func(string) (string, error) {
+			return "", fmt.Errorf("resolve failed")
+		})
+
+		unsafe, reason := isUnsafeFile("cannot-resolve.log", tempDir)
+		if !unsafe || !strings.Contains(reason, "path resolution failed") {
+			t.Fatalf("expected resolution failure to be unsafe, got unsafe=%v reason=%q", unsafe, reason)
+		}
+	})
+}

codeagent-wrapper/logger_suffix_test.go

@@ -0,0 +1,115 @@
+package main
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestLoggerWithSuffixNamingAndIsolation(t *testing.T) {
+	tempDir := setTempDirEnv(t, t.TempDir())
+
+	taskA := "task-1"
+	taskB := "task-2"
+
+	loggerA, err := NewLoggerWithSuffix(taskA)
+	if err != nil {
+		t.Fatalf("NewLoggerWithSuffix(%q) error = %v", taskA, err)
+	}
+	defer loggerA.Close()
+
+	loggerB, err := NewLoggerWithSuffix(taskB)
+	if err != nil {
+		t.Fatalf("NewLoggerWithSuffix(%q) error = %v", taskB, err)
+	}
+	defer loggerB.Close()
+
+	wantA := filepath.Join(tempDir, fmt.Sprintf("%s-%d-%s.log", primaryLogPrefix(), os.Getpid(), taskA))
+	if loggerA.Path() != wantA {
+		t.Fatalf("loggerA path = %q, want %q", loggerA.Path(), wantA)
+	}
+
+	wantB := filepath.Join(tempDir, fmt.Sprintf("%s-%d-%s.log", primaryLogPrefix(), os.Getpid(), taskB))
+	if loggerB.Path() != wantB {
+		t.Fatalf("loggerB path = %q, want %q", loggerB.Path(), wantB)
+	}
+
+	if loggerA.Path() == loggerB.Path() {
+		t.Fatalf("expected different log files, got %q", loggerA.Path())
+	}
+
+	loggerA.Info("from taskA")
+	loggerB.Info("from taskB")
+	loggerA.Flush()
+	loggerB.Flush()
+
+	dataA, err := os.ReadFile(loggerA.Path())
+	if err != nil {
+		t.Fatalf("failed to read loggerA file: %v", err)
+	}
+	dataB, err := os.ReadFile(loggerB.Path())
+	if err != nil {
+		t.Fatalf("failed to read loggerB file: %v", err)
+	}
+
+	if !strings.Contains(string(dataA), "from taskA") {
+		t.Fatalf("loggerA missing its message, got: %q", string(dataA))
+	}
+	if strings.Contains(string(dataA), "from taskB") {
+		t.Fatalf("loggerA contains loggerB message, got: %q", string(dataA))
+	}
+	if !strings.Contains(string(dataB), "from taskB") {
+		t.Fatalf("loggerB missing its message, got: %q", string(dataB))
+	}
+	if strings.Contains(string(dataB), "from taskA") {
+		t.Fatalf("loggerB contains loggerA message, got: %q", string(dataB))
+	}
+}
+
+func TestLoggerWithSuffixReturnsErrorWhenTempDirNotWritable(t *testing.T) {
+	base := t.TempDir()
+	noWrite := filepath.Join(base, "ro")
+	if err := os.Mkdir(noWrite, 0o500); err != nil {
+		t.Fatalf("failed to create read-only temp dir: %v", err)
+	}
+	t.Cleanup(func() { _ = os.Chmod(noWrite, 0o700) })
+	setTempDirEnv(t, noWrite)
+
+	logger, err := NewLoggerWithSuffix("task-err")
+	if err == nil {
+		_ = logger.Close()
+		t.Fatalf("expected error when temp dir is not writable")
+	}
+}
+
+func TestLoggerWithSuffixSanitizesUnsafeSuffix(t *testing.T) {
+	tempDir := setTempDirEnv(t, t.TempDir())
+
+	raw := "../bad id/with?chars"
+	safe := sanitizeLogSuffix(raw)
+	if safe == "" {
+		t.Fatalf("sanitizeLogSuffix returned empty string")
+	}
+	if strings.ContainsAny(safe, "/\\") {
+		t.Fatalf("sanitized suffix should not contain path separators, got %q", safe)
+	}
+
+	logger, err := NewLoggerWithSuffix(raw)
+	if err != nil {
+		t.Fatalf("NewLoggerWithSuffix(%q) error = %v", raw, err)
+	}
+	t.Cleanup(func() {
+		_ = logger.Close()
+		_ = os.Remove(logger.Path())
+	})
+
+	wantBase := fmt.Sprintf("%s-%d-%s.log", primaryLogPrefix(), os.Getpid(), safe)
+	if gotBase := filepath.Base(logger.Path()); gotBase != wantBase {
+		t.Fatalf("log filename = %q, want %q", gotBase, wantBase)
+	}
+	if dir := filepath.Dir(logger.Path()); dir != tempDir {
+		t.Fatalf("logger path dir = %q, want %q", dir, tempDir)
+	}
+}

codeagent-wrapper/main.go

@@ -0,0 +1,469 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"os/exec"
+	"os/signal"
+	"reflect"
+	"strings"
+	"sync/atomic"
+	"time"
+)
+
+const (
+	version             = "5.2.7"
+	defaultWorkdir      = "."
+	defaultTimeout      = 7200 // seconds (2 hours)
+	codexLogLineLimit   = 1000
+	stdinSpecialChars   = "\n\\\"'`$"
+	stderrCaptureLimit  = 4 * 1024
+	defaultBackendName  = "codex"
+	defaultCodexCommand = "codex"
+
+	// stdout close reasons
+	stdoutCloseReasonWait  = "wait-done"
+	stdoutCloseReasonDrain = "drain-timeout"
+	stdoutCloseReasonCtx   = "context-cancel"
+	stdoutDrainTimeout     = 100 * time.Millisecond
+)
+
+// Test hooks for dependency injection
+var (
+	stdinReader  io.Reader = os.Stdin
+	isTerminalFn           = defaultIsTerminal
+	codexCommand           = defaultCodexCommand
+	cleanupHook  func()
+	loggerPtr    atomic.Pointer[Logger]
+
+	buildCodexArgsFn   = buildCodexArgs
+	selectBackendFn    = selectBackend
+	commandContext     = exec.CommandContext
+	jsonMarshal        = json.Marshal
+	cleanupLogsFn      = cleanupOldLogs
+	signalNotifyFn     = signal.Notify
+	signalStopFn       = signal.Stop
+	terminateCommandFn = terminateCommand
+	defaultBuildArgsFn = buildCodexArgs
+	runTaskFn          = runCodexTask
+	exitFn             = os.Exit
+)
+
+var forceKillDelay atomic.Int32
+
+func init() {
+	forceKillDelay.Store(5) // seconds - default value
+}
+
+func runStartupCleanup() {
+	if cleanupLogsFn == nil {
+		return
+	}
+	defer func() {
+		if r := recover(); r != nil {
+			logWarn(fmt.Sprintf("cleanupOldLogs panic: %v", r))
+		}
+	}()
+	if _, err := cleanupLogsFn(); err != nil {
+		logWarn(fmt.Sprintf("cleanupOldLogs error: %v", err))
+	}
+}
+
+func runCleanupMode() int {
+	if cleanupLogsFn == nil {
+		fmt.Fprintln(os.Stderr, "Cleanup failed: log cleanup function not configured")
+		return 1
+	}
+
+	stats, err := cleanupLogsFn()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Cleanup failed: %v\n", err)
+		return 1
+	}
+
+	fmt.Println("Cleanup completed")
+	fmt.Printf("Files scanned: %d\n", stats.Scanned)
+	fmt.Printf("Files deleted: %d\n", stats.Deleted)
+	if len(stats.DeletedFiles) > 0 {
+		for _, f := range stats.DeletedFiles {
+			fmt.Printf("  - %s\n", f)
+		}
+	}
+	fmt.Printf("Files kept: %d\n", stats.Kept)
+	if len(stats.KeptFiles) > 0 {
+		for _, f := range stats.KeptFiles {
+			fmt.Printf("  - %s\n", f)
+		}
+	}
+	if stats.Errors > 0 {
+		fmt.Printf("Deletion errors: %d\n", stats.Errors)
+	}
+	return 0
+}
+
+func main() {
+	exitCode := run()
+	exitFn(exitCode)
+}
+
+// run is the main logic, returns exit code for testability
+func run() (exitCode int) {
+	name := currentWrapperName()
+	// Handle --version and --help first (no logger needed)
+	if len(os.Args) > 1 {
+		switch os.Args[1] {
+		case "--version", "-v":
+			fmt.Printf("%s version %s\n", name, version)
+			return 0
+		case "--help", "-h":
+			printHelp()
+			return 0
+		case "--cleanup":
+			return runCleanupMode()
+		}
+	}
+
+	// Initialize logger for all other commands
+	logger, err := NewLogger()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "ERROR: failed to initialize logger: %v\n", err)
+		return 1
+	}
+	setLogger(logger)
+
+	defer func() {
+		logger := activeLogger()
+		if logger != nil {
+			logger.Flush()
+		}
+		if err := closeLogger(); err != nil {
+			fmt.Fprintf(os.Stderr, "ERROR: failed to close logger: %v\n", err)
+		}
+		// On failure, extract and display recent errors before removing log
+		if logger != nil {
+			if exitCode != 0 {
+				if errors := logger.ExtractRecentErrors(10); len(errors) > 0 {
+					fmt.Fprintln(os.Stderr, "\n=== Recent Errors ===")
+					for _, entry := range errors {
+						fmt.Fprintln(os.Stderr, entry)
+					}
+					fmt.Fprintf(os.Stderr, "Log file: %s (deleted)\n", logger.Path())
+				}
+			}
+			if err := logger.RemoveLogFile(); err != nil && !os.IsNotExist(err) {
+				// Silently ignore removal errors
+			}
+		}
+	}()
+	defer runCleanupHook()
+
+	// Clean up stale logs from previous runs.
+	runStartupCleanup()
+
+	// Handle remaining commands
+	if len(os.Args) > 1 {
+		args := os.Args[1:]
+		parallelIndex := -1
+		for i, arg := range args {
+			if arg == "--parallel" {
+				parallelIndex = i
+				break
+			}
+		}
+
+		if parallelIndex != -1 {
+			backendName := defaultBackendName
+			var extras []string
+
+			for i := 0; i < len(args); i++ {
+				arg := args[i]
+				switch {
+				case arg == "--parallel":
+					continue
+				case arg == "--backend":
+					if i+1 >= len(args) {
+						fmt.Fprintln(os.Stderr, "ERROR: --backend flag requires a value")
+						return 1
+					}
+					backendName = args[i+1]
+					i++
+				case strings.HasPrefix(arg, "--backend="):
+					value := strings.TrimPrefix(arg, "--backend=")
+					if value == "" {
+						fmt.Fprintln(os.Stderr, "ERROR: --backend flag requires a value")
+						return 1
+					}
+					backendName = value
+				default:
+					extras = append(extras, arg)
+				}
+			}
+
+			if len(extras) > 0 {
+				fmt.Fprintln(os.Stderr, "ERROR: --parallel reads its task configuration from stdin; only --backend is allowed.")
+				fmt.Fprintln(os.Stderr, "Usage examples:")
+				fmt.Fprintf(os.Stderr, "  %s --parallel < tasks.txt\n", name)
+				fmt.Fprintf(os.Stderr, "  echo '...' | %s --parallel\n", name)
+				fmt.Fprintf(os.Stderr, "  %s --parallel <<'EOF'\n", name)
+				return 1
+			}
+
+			backend, err := selectBackendFn(backendName)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "ERROR: %v\n", err)
+				return 1
+			}
+			backendName = backend.Name()
+
+			data, err := io.ReadAll(stdinReader)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "ERROR: failed to read stdin: %v\n", err)
+				return 1
+			}
+
+			cfg, err := parseParallelConfig(data)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "ERROR: %v\n", err)
+				return 1
+			}
+
+			cfg.GlobalBackend = backendName
+			for i := range cfg.Tasks {
+				if strings.TrimSpace(cfg.Tasks[i].Backend) == "" {
+					cfg.Tasks[i].Backend = backendName
+				}
+			}
+
+			timeoutSec := resolveTimeout()
+			layers, err := topologicalSort(cfg.Tasks)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "ERROR: %v\n", err)
+				return 1
+			}
+
+			results := executeConcurrent(layers, timeoutSec)
+			fmt.Println(generateFinalOutput(results))
+
+			exitCode = 0
+			for _, res := range results {
+				if res.ExitCode != 0 {
+					exitCode = res.ExitCode
+				}
+			}
+
+			return exitCode
+		}
+	}
+
+	logInfo("Script started")
+
+	cfg, err := parseArgs()
+	if err != nil {
+		logError(err.Error())
+		return 1
+	}
+	logInfo(fmt.Sprintf("Parsed args: mode=%s, task_len=%d, backend=%s", cfg.Mode, len(cfg.Task), cfg.Backend))
+
+	backend, err := selectBackendFn(cfg.Backend)
+	if err != nil {
+		logError(err.Error())
+		return 1
+	}
+	cfg.Backend = backend.Name()
+
+	cmdInjected := codexCommand != defaultCodexCommand
+	argsInjected := buildCodexArgsFn != nil && reflect.ValueOf(buildCodexArgsFn).Pointer() != reflect.ValueOf(defaultBuildArgsFn).Pointer()
+
+	// Wire selected backend into runtime hooks for the rest of the execution,
+	// but preserve any injected test hooks for the default backend.
+	if backend.Name() != defaultBackendName || !cmdInjected {
+		codexCommand = backend.Command()
+	}
+	if backend.Name() != defaultBackendName || !argsInjected {
+		buildCodexArgsFn = backend.BuildArgs
+	}
+	logInfo(fmt.Sprintf("Selected backend: %s", backend.Name()))
+
+	timeoutSec := resolveTimeout()
+	logInfo(fmt.Sprintf("Timeout: %ds", timeoutSec))
+	cfg.Timeout = timeoutSec
+
+	var taskText string
+	var piped bool
+
+	if cfg.ExplicitStdin {
+		logInfo("Explicit stdin mode: reading task from stdin")
+		data, err := io.ReadAll(stdinReader)
+		if err != nil {
+			logError("Failed to read stdin: " + err.Error())
+			return 1
+		}
+		taskText = string(data)
+		if taskText == "" {
+			logError("Explicit stdin mode requires task input from stdin")
+			return 1
+		}
+		piped = !isTerminal()
+	} else {
+		pipedTask, err := readPipedTask()
+		if err != nil {
+			logError("Failed to read piped stdin: " + err.Error())
+			return 1
+		}
+		piped = pipedTask != ""
+		if piped {
+			taskText = pipedTask
+		} else {
+			taskText = cfg.Task
+		}
+	}
+
+	useStdin := cfg.ExplicitStdin || shouldUseStdin(taskText, piped)
+
+	targetArg := taskText
+	if useStdin {
+		targetArg = "-"
+	}
+	codexArgs := buildCodexArgsFn(cfg, targetArg)
+
+	// Print startup information to stderr
+	fmt.Fprintf(os.Stderr, "[%s]\n", name)
+	fmt.Fprintf(os.Stderr, "  Backend: %s\n", cfg.Backend)
+	fmt.Fprintf(os.Stderr, "  Command: %s %s\n", codexCommand, strings.Join(codexArgs, " "))
+	fmt.Fprintf(os.Stderr, "  PID: %d\n", os.Getpid())
+	fmt.Fprintf(os.Stderr, "  Log: %s\n", logger.Path())
+
+	if useStdin {
+		var reasons []string
+		if piped {
+			reasons = append(reasons, "piped input")
+		}
+		if cfg.ExplicitStdin {
+			reasons = append(reasons, "explicit \"-\"")
+		}
+		if strings.Contains(taskText, "\n") {
+			reasons = append(reasons, "newline")
+		}
+		if strings.Contains(taskText, "\\") {
+			reasons = append(reasons, "backslash")
+		}
+		if strings.Contains(taskText, "\"") {
+			reasons = append(reasons, "double-quote")
+		}
+		if strings.Contains(taskText, "'") {
+			reasons = append(reasons, "single-quote")
+		}
+		if strings.Contains(taskText, "`") {
+			reasons = append(reasons, "backtick")
+		}
+		if strings.Contains(taskText, "$") {
+			reasons = append(reasons, "dollar")
+		}
+		if len(taskText) > 800 {
+			reasons = append(reasons, "length>800")
+		}
+		if len(reasons) > 0 {
+			logWarn(fmt.Sprintf("Using stdin mode for task due to: %s", strings.Join(reasons, ", ")))
+		}
+	}
+
+	logInfo(fmt.Sprintf("%s running...", cfg.Backend))
+
+	taskSpec := TaskSpec{
+		Task:      taskText,
+		WorkDir:   cfg.WorkDir,
+		Mode:      cfg.Mode,
+		SessionID: cfg.SessionID,
+		UseStdin:  useStdin,
+	}
+
+	result := runTaskFn(taskSpec, false, cfg.Timeout)
+
+	if result.ExitCode != 0 {
+		return result.ExitCode
+	}
+
+	fmt.Println(result.Message)
+	if result.SessionID != "" {
+		fmt.Printf("\n---\nSESSION_ID: %s\n", result.SessionID)
+	}
+
+	return 0
+}
+
+func setLogger(l *Logger) {
+	loggerPtr.Store(l)
+}
+
+func closeLogger() error {
+	logger := loggerPtr.Swap(nil)
+	if logger == nil {
+		return nil
+	}
+	return logger.Close()
+}
+
+func activeLogger() *Logger {
+	return loggerPtr.Load()
+}
+
+func logInfo(msg string) {
+	if logger := activeLogger(); logger != nil {
+		logger.Info(msg)
+	}
+}
+
+func logWarn(msg string) {
+	if logger := activeLogger(); logger != nil {
+		logger.Warn(msg)
+	}
+}
+
+func logError(msg string) {
+	if logger := activeLogger(); logger != nil {
+		logger.Error(msg)
+	}
+}
+
+func runCleanupHook() {
+	if logger := activeLogger(); logger != nil {
+		logger.Flush()
+	}
+	if cleanupHook != nil {
+		cleanupHook()
+	}
+}
+
+func printHelp() {
+	name := currentWrapperName()
+	help := fmt.Sprintf(`%[1]s - Go wrapper for AI CLI backends
+
+Usage:
+    %[1]s "task" [workdir]
+    %[1]s --backend claude "task" [workdir]
+    %[1]s - [workdir]              Read task from stdin
+    %[1]s resume <session_id> "task" [workdir]
+    %[1]s resume <session_id> - [workdir]
+    %[1]s --parallel               Run tasks in parallel (config from stdin)
+    %[1]s --version
+    %[1]s --help
+
+Parallel mode examples:
+    %[1]s --parallel < tasks.txt
+    echo '...' | %[1]s --parallel
+    %[1]s --parallel <<'EOF'
+
+Environment Variables:
+    CODEX_TIMEOUT  Timeout in milliseconds (default: 7200000)
+
+Exit Codes:
+    0    Success
+    1    General error (missing args, no output)
+    124  Timeout
+    127  backend command not found
+    130  Interrupted (Ctrl+C)
+    *    Passthrough from backend process`, name)
+	fmt.Println(help)
+}

codeagent-wrapper/main_integration_test.go

@@ -0,0 +1,851 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+type integrationSummary struct {
+	Total   int `json:"total"`
+	Success int `json:"success"`
+	Failed  int `json:"failed"`
+}
+
+type integrationOutput struct {
+	Results []TaskResult       `json:"results"`
+	Summary integrationSummary `json:"summary"`
+}
+
+func captureStdout(t *testing.T, fn func()) string {
+	t.Helper()
+	old := os.Stdout
+	r, w, _ := os.Pipe()
+	os.Stdout = w
+
+	fn()
+
+	w.Close()
+	os.Stdout = old
+
+	var buf bytes.Buffer
+	io.Copy(&buf, r)
+	return buf.String()
+}
+
+func parseIntegrationOutput(t *testing.T, out string) integrationOutput {
+	t.Helper()
+	var payload integrationOutput
+
+	lines := strings.Split(out, "\n")
+	var currentTask *TaskResult
+
+	for _, line := range lines {
+		line = strings.TrimSpace(line)
+		if strings.HasPrefix(line, "Total:") {
+			parts := strings.Split(line, "|")
+			for _, p := range parts {
+				p = strings.TrimSpace(p)
+				if strings.HasPrefix(p, "Total:") {
+					fmt.Sscanf(p, "Total: %d", &payload.Summary.Total)
+				} else if strings.HasPrefix(p, "Success:") {
+					fmt.Sscanf(p, "Success: %d", &payload.Summary.Success)
+				} else if strings.HasPrefix(p, "Failed:") {
+					fmt.Sscanf(p, "Failed: %d", &payload.Summary.Failed)
+				}
+			}
+		} else if strings.HasPrefix(line, "--- Task:") {
+			if currentTask != nil {
+				payload.Results = append(payload.Results, *currentTask)
+			}
+			currentTask = &TaskResult{}
+			currentTask.TaskID = strings.TrimSuffix(strings.TrimPrefix(line, "--- Task: "), " ---")
+		} else if currentTask != nil {
+			if strings.HasPrefix(line, "Status: SUCCESS") {
+				currentTask.ExitCode = 0
+			} else if strings.HasPrefix(line, "Status: FAILED") {
+				if strings.Contains(line, "exit code") {
+					fmt.Sscanf(line, "Status: FAILED (exit code %d)", &currentTask.ExitCode)
+				} else {
+					currentTask.ExitCode = 1
+				}
+			} else if strings.HasPrefix(line, "Error:") {
+				currentTask.Error = strings.TrimPrefix(line, "Error: ")
+			} else if strings.HasPrefix(line, "Session:") {
+				currentTask.SessionID = strings.TrimPrefix(line, "Session: ")
+			} else if strings.HasPrefix(line, "Log:") {
+				currentTask.LogPath = strings.TrimSpace(strings.TrimPrefix(line, "Log:"))
+			} else if line != "" && !strings.HasPrefix(line, "===") && !strings.HasPrefix(line, "---") {
+				if currentTask.Message != "" {
+					currentTask.Message += "\n"
+				}
+				currentTask.Message += line
+			}
+		}
+	}
+
+	if currentTask != nil {
+		payload.Results = append(payload.Results, *currentTask)
+	}
+
+	return payload
+}
+
+func extractTaskBlock(t *testing.T, output, taskID string) string {
+	t.Helper()
+	header := fmt.Sprintf("--- Task: %s ---", taskID)
+	lines := strings.Split(output, "\n")
+	var block []string
+	collecting := false
+	for _, raw := range lines {
+		trimmed := strings.TrimSpace(raw)
+		if !collecting {
+			if trimmed == header {
+				collecting = true
+				block = append(block, trimmed)
+			}
+			continue
+		}
+		if strings.HasPrefix(trimmed, "--- Task: ") && trimmed != header {
+			break
+		}
+		block = append(block, trimmed)
+	}
+	if len(block) == 0 {
+		t.Fatalf("task block %s not found in output:\n%s", taskID, output)
+	}
+	return strings.Join(block, "\n")
+}
+
+func findResultByID(t *testing.T, payload integrationOutput, id string) TaskResult {
+	t.Helper()
+	for _, res := range payload.Results {
+		if res.TaskID == id {
+			return res
+		}
+	}
+	t.Fatalf("result for task %s not found", id)
+	return TaskResult{}
+}
+
+func TestRunParallelEndToEnd_OrderAndConcurrency(t *testing.T) {
+	defer resetTestHooks()
+	origRun := runCodexTaskFn
+	t.Cleanup(func() {
+		runCodexTaskFn = origRun
+		resetTestHooks()
+	})
+
+	input := `---TASK---
+id: A
+---CONTENT---
+task-a
+---TASK---
+id: B
+dependencies: A
+---CONTENT---
+task-b
+---TASK---
+id: C
+dependencies: B
+---CONTENT---
+task-c
+---TASK---
+id: D
+---CONTENT---
+task-d
+---TASK---
+id: E
+---CONTENT---
+task-e`
+	stdinReader = bytes.NewReader([]byte(input))
+	os.Args = []string{"codeagent-wrapper", "--parallel"}
+
+	var mu sync.Mutex
+	starts := make(map[string]time.Time)
+	ends := make(map[string]time.Time)
+	var running int64
+	var maxParallel int64
+
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		start := time.Now()
+		mu.Lock()
+		starts[task.ID] = start
+		mu.Unlock()
+
+		cur := atomic.AddInt64(&running, 1)
+		for {
+			prev := atomic.LoadInt64(&maxParallel)
+			if cur <= prev {
+				break
+			}
+			if atomic.CompareAndSwapInt64(&maxParallel, prev, cur) {
+				break
+			}
+		}
+
+		time.Sleep(40 * time.Millisecond)
+
+		mu.Lock()
+		ends[task.ID] = time.Now()
+		mu.Unlock()
+
+		atomic.AddInt64(&running, -1)
+		return TaskResult{TaskID: task.ID, ExitCode: 0, Message: task.Task}
+	}
+
+	var exitCode int
+	output := captureStdout(t, func() {
+		exitCode = run()
+	})
+
+	if exitCode != 0 {
+		t.Fatalf("run() exit = %d, want 0", exitCode)
+	}
+
+	payload := parseIntegrationOutput(t, output)
+	if payload.Summary.Failed != 0 || payload.Summary.Total != 5 || payload.Summary.Success != 5 {
+		t.Fatalf("unexpected summary: %+v", payload.Summary)
+	}
+
+	aEnd := ends["A"]
+	bStart := starts["B"]
+	cStart := starts["C"]
+	bEnd := ends["B"]
+	if aEnd.IsZero() || bStart.IsZero() || bEnd.IsZero() || cStart.IsZero() {
+		t.Fatalf("missing timestamps, starts=%v ends=%v", starts, ends)
+	}
+	if !aEnd.Before(bStart) && !aEnd.Equal(bStart) {
+		t.Fatalf("B should start after A ends: A_end=%v B_start=%v", aEnd, bStart)
+	}
+	if !bEnd.Before(cStart) && !bEnd.Equal(cStart) {
+		t.Fatalf("C should start after B ends: B_end=%v C_start=%v", bEnd, cStart)
+	}
+
+	dStart := starts["D"]
+	eStart := starts["E"]
+	if dStart.IsZero() || eStart.IsZero() {
+		t.Fatalf("missing D/E start times: %v", starts)
+	}
+	delta := dStart.Sub(eStart)
+	if delta < 0 {
+		delta = -delta
+	}
+	if delta > 25*time.Millisecond {
+		t.Fatalf("D and E should run in parallel, delta=%v", delta)
+	}
+	if maxParallel < 2 {
+		t.Fatalf("expected at least 2 concurrent tasks, got %d", maxParallel)
+	}
+}
+
+func TestRunParallelCycleDetectionStopsExecution(t *testing.T) {
+	defer resetTestHooks()
+	origRun := runCodexTaskFn
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		t.Fatalf("task %s should not execute on cycle", task.ID)
+		return TaskResult{}
+	}
+	t.Cleanup(func() {
+		runCodexTaskFn = origRun
+		resetTestHooks()
+	})
+
+	input := `---TASK---
+id: A
+dependencies: B
+---CONTENT---
+a
+---TASK---
+id: B
+dependencies: A
+---CONTENT---
+b`
+	stdinReader = bytes.NewReader([]byte(input))
+	os.Args = []string{"codeagent-wrapper", "--parallel"}
+
+	exitCode := 0
+	output := captureStdout(t, func() {
+		exitCode = run()
+	})
+
+	if exitCode == 0 {
+		t.Fatalf("cycle should cause non-zero exit, got %d", exitCode)
+	}
+	if strings.TrimSpace(output) != "" {
+		t.Fatalf("expected no JSON output on cycle, got %q", output)
+	}
+}
+
+func TestRunParallelOutputsIncludeLogPaths(t *testing.T) {
+	defer resetTestHooks()
+	origRun := runCodexTaskFn
+	t.Cleanup(func() {
+		runCodexTaskFn = origRun
+		resetTestHooks()
+	})
+
+	tempDir := t.TempDir()
+	logPathFor := func(id string) string {
+		return filepath.Join(tempDir, fmt.Sprintf("%s.log", id))
+	}
+
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		res := TaskResult{
+			TaskID:    task.ID,
+			Message:   fmt.Sprintf("result-%s", task.ID),
+			SessionID: fmt.Sprintf("session-%s", task.ID),
+			LogPath:   logPathFor(task.ID),
+		}
+		if task.ID == "beta" {
+			res.ExitCode = 9
+			res.Error = "boom"
+		}
+		return res
+	}
+
+	input := `---TASK---
+id: alpha
+---CONTENT---
+task-alpha
+---TASK---
+id: beta
+---CONTENT---
+task-beta`
+	stdinReader = bytes.NewReader([]byte(input))
+	os.Args = []string{"codex-wrapper", "--parallel"}
+
+	var exitCode int
+	output := captureStdout(t, func() {
+		exitCode = run()
+	})
+
+	if exitCode != 9 {
+		t.Fatalf("parallel run exit=%d, want 9", exitCode)
+	}
+
+	payload := parseIntegrationOutput(t, output)
+	alpha := findResultByID(t, payload, "alpha")
+	beta := findResultByID(t, payload, "beta")
+
+	if alpha.LogPath != logPathFor("alpha") {
+		t.Fatalf("alpha log path = %q, want %q", alpha.LogPath, logPathFor("alpha"))
+	}
+	if beta.LogPath != logPathFor("beta") {
+		t.Fatalf("beta log path = %q, want %q", beta.LogPath, logPathFor("beta"))
+	}
+
+	for _, id := range []string{"alpha", "beta"} {
+		want := fmt.Sprintf("Log: %s", logPathFor(id))
+		if !strings.Contains(output, want) {
+			t.Fatalf("parallel output missing %q for %s:\n%s", want, id, output)
+		}
+	}
+}
+
+func TestRunParallelStartupLogsPrinted(t *testing.T) {
+	defer resetTestHooks()
+
+	tempDir := setTempDirEnv(t, t.TempDir())
+	input := `---TASK---
+id: a
+---CONTENT---
+fail
+---TASK---
+id: b
+---CONTENT---
+ok-b
+---TASK---
+id: c
+dependencies: a
+---CONTENT---
+should-skip
+---TASK---
+id: d
+---CONTENT---
+ok-d`
+	stdinReader = bytes.NewReader([]byte(input))
+	os.Args = []string{"codex-wrapper", "--parallel"}
+
+	expectedLog := filepath.Join(tempDir, fmt.Sprintf("codex-wrapper-%d.log", os.Getpid()))
+
+	origRun := runCodexTaskFn
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		path := expectedLog
+		if logger := activeLogger(); logger != nil && logger.Path() != "" {
+			path = logger.Path()
+		}
+		if task.ID == "a" {
+			return TaskResult{TaskID: task.ID, ExitCode: 3, Error: "boom", LogPath: path}
+		}
+		return TaskResult{TaskID: task.ID, ExitCode: 0, Message: task.Task, LogPath: path}
+	}
+	t.Cleanup(func() { runCodexTaskFn = origRun })
+
+	var exitCode int
+	var stdoutOut string
+	stderrOut := captureStderr(t, func() {
+		stdoutOut = captureStdout(t, func() {
+			exitCode = run()
+		})
+	})
+
+	if exitCode == 0 {
+		t.Fatalf("expected non-zero exit due to task failure, got %d", exitCode)
+	}
+	if stdoutOut == "" {
+		t.Fatalf("expected parallel summary on stdout")
+	}
+
+	lines := strings.Split(strings.TrimSpace(stderrOut), "\n")
+	var bannerSeen bool
+	var taskLines []string
+	for _, raw := range lines {
+		line := strings.TrimSpace(raw)
+		if line == "" {
+			continue
+		}
+		if line == "=== Starting Parallel Execution ===" {
+			if bannerSeen {
+				t.Fatalf("banner printed multiple times:\n%s", stderrOut)
+			}
+			bannerSeen = true
+			continue
+		}
+		taskLines = append(taskLines, line)
+	}
+
+	if !bannerSeen {
+		t.Fatalf("expected startup banner in stderr, got:\n%s", stderrOut)
+	}
+
+	// After parallel log isolation fix, each task has its own log file
+	expectedLines := map[string]struct{}{
+		fmt.Sprintf("Task a: Log: %s", filepath.Join(tempDir, fmt.Sprintf("codex-wrapper-%d-a.log", os.Getpid()))): {},
+		fmt.Sprintf("Task b: Log: %s", filepath.Join(tempDir, fmt.Sprintf("codex-wrapper-%d-b.log", os.Getpid()))): {},
+		fmt.Sprintf("Task d: Log: %s", filepath.Join(tempDir, fmt.Sprintf("codex-wrapper-%d-d.log", os.Getpid()))): {},
+	}
+
+	if len(taskLines) != len(expectedLines) {
+		t.Fatalf("startup log lines mismatch, got %d lines:\n%s", len(taskLines), stderrOut)
+	}
+
+	for _, line := range taskLines {
+		if _, ok := expectedLines[line]; !ok {
+			t.Fatalf("unexpected startup line %q\nstderr:\n%s", line, stderrOut)
+		}
+	}
+}
+
+func TestRunNonParallelOutputsIncludeLogPathsIntegration(t *testing.T) {
+	defer resetTestHooks()
+
+	tempDir := setTempDirEnv(t, t.TempDir())
+	os.Args = []string{"codex-wrapper", "integration-log-check"}
+	stdinReader = strings.NewReader("")
+	isTerminalFn = func() bool { return true }
+	codexCommand = "echo"
+	buildCodexArgsFn = func(cfg *Config, targetArg string) []string {
+		return []string{`{"type":"thread.started","thread_id":"integration-session"}` + "\n" + `{"type":"item.completed","item":{"type":"agent_message","text":"done"}}`}
+	}
+
+	var exitCode int
+	stderr := captureStderr(t, func() {
+		_ = captureStdout(t, func() {
+			exitCode = run()
+		})
+	})
+
+	if exitCode != 0 {
+		t.Fatalf("run() exit=%d, want 0", exitCode)
+	}
+	expectedLog := filepath.Join(tempDir, fmt.Sprintf("codex-wrapper-%d.log", os.Getpid()))
+	wantLine := fmt.Sprintf("Log: %s", expectedLog)
+	if !strings.Contains(stderr, wantLine) {
+		t.Fatalf("stderr missing %q, got: %q", wantLine, stderr)
+	}
+}
+
+func TestRunParallelPartialFailureBlocksDependents(t *testing.T) {
+	defer resetTestHooks()
+	origRun := runCodexTaskFn
+	t.Cleanup(func() {
+		runCodexTaskFn = origRun
+		resetTestHooks()
+	})
+
+	tempDir := t.TempDir()
+	logPathFor := func(id string) string {
+		return filepath.Join(tempDir, fmt.Sprintf("%s.log", id))
+	}
+
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		path := logPathFor(task.ID)
+		if task.ID == "A" {
+			return TaskResult{TaskID: "A", ExitCode: 2, Error: "boom", LogPath: path}
+		}
+		return TaskResult{TaskID: task.ID, ExitCode: 0, Message: task.Task, LogPath: path}
+	}
+
+	input := `---TASK---
+id: A
+---CONTENT---
+fail
+---TASK---
+id: B
+dependencies: A
+---CONTENT---
+blocked
+---TASK---
+id: D
+---CONTENT---
+ok-d
+---TASK---
+id: E
+---CONTENT---
+ok-e`
+	stdinReader = bytes.NewReader([]byte(input))
+	os.Args = []string{"codeagent-wrapper", "--parallel"}
+
+	var exitCode int
+	output := captureStdout(t, func() {
+		exitCode = run()
+	})
+
+	payload := parseIntegrationOutput(t, output)
+	if exitCode == 0 {
+		t.Fatalf("expected non-zero exit when a task fails, got %d", exitCode)
+	}
+
+	resA := findResultByID(t, payload, "A")
+	resB := findResultByID(t, payload, "B")
+	resD := findResultByID(t, payload, "D")
+	resE := findResultByID(t, payload, "E")
+
+	if resA.ExitCode == 0 {
+		t.Fatalf("task A should fail, got %+v", resA)
+	}
+	if resB.ExitCode == 0 || !strings.Contains(resB.Error, "dependencies") {
+		t.Fatalf("task B should be skipped due to dependency failure, got %+v", resB)
+	}
+	if resD.ExitCode != 0 || resE.ExitCode != 0 {
+		t.Fatalf("independent tasks should run successfully, D=%+v E=%+v", resD, resE)
+	}
+	if payload.Summary.Failed != 2 || payload.Summary.Total != 4 {
+		t.Fatalf("unexpected summary after partial failure: %+v", payload.Summary)
+	}
+	if resA.LogPath != logPathFor("A") {
+		t.Fatalf("task A log path = %q, want %q", resA.LogPath, logPathFor("A"))
+	}
+	if resB.LogPath != "" {
+		t.Fatalf("task B should not report a log path when skipped, got %q", resB.LogPath)
+	}
+	if resD.LogPath != logPathFor("D") || resE.LogPath != logPathFor("E") {
+		t.Fatalf("expected log paths for D/E, got D=%q E=%q", resD.LogPath, resE.LogPath)
+	}
+	for _, id := range []string{"A", "D", "E"} {
+		block := extractTaskBlock(t, output, id)
+		want := fmt.Sprintf("Log: %s", logPathFor(id))
+		if !strings.Contains(block, want) {
+			t.Fatalf("task %s block missing %q:\n%s", id, want, block)
+		}
+	}
+	blockB := extractTaskBlock(t, output, "B")
+	if strings.Contains(blockB, "Log:") {
+		t.Fatalf("skipped task B should not emit a log line:\n%s", blockB)
+	}
+}
+
+func TestRunParallelTimeoutPropagation(t *testing.T) {
+	defer resetTestHooks()
+	origRun := runCodexTaskFn
+	t.Cleanup(func() {
+		runCodexTaskFn = origRun
+		resetTestHooks()
+		os.Unsetenv("CODEX_TIMEOUT")
+	})
+
+	var receivedTimeout int
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		receivedTimeout = timeout
+		return TaskResult{TaskID: task.ID, ExitCode: 124, Error: "timeout"}
+	}
+
+	os.Setenv("CODEX_TIMEOUT", "1")
+	input := `---TASK---
+id: T
+---CONTENT---
+slow`
+	stdinReader = bytes.NewReader([]byte(input))
+	os.Args = []string{"codeagent-wrapper", "--parallel"}
+
+	exitCode := 0
+	output := captureStdout(t, func() {
+		exitCode = run()
+	})
+
+	payload := parseIntegrationOutput(t, output)
+	if receivedTimeout != 1 {
+		t.Fatalf("expected timeout 1s to propagate, got %d", receivedTimeout)
+	}
+	if exitCode != 124 {
+		t.Fatalf("expected timeout exit code 124, got %d", exitCode)
+	}
+	if payload.Summary.Failed != 1 || payload.Summary.Total != 1 {
+		t.Fatalf("unexpected summary for timeout case: %+v", payload.Summary)
+	}
+	res := findResultByID(t, payload, "T")
+	if res.Error == "" || res.ExitCode != 124 {
+		t.Fatalf("timeout result not propagated, got %+v", res)
+	}
+}
+
+func TestRunConcurrentSpeedupBenchmark(t *testing.T) {
+	defer resetTestHooks()
+	origRun := runCodexTaskFn
+	t.Cleanup(func() {
+		runCodexTaskFn = origRun
+		resetTestHooks()
+	})
+
+	runCodexTaskFn = func(task TaskSpec, timeout int) TaskResult {
+		time.Sleep(50 * time.Millisecond)
+		return TaskResult{TaskID: task.ID}
+	}
+
+	tasks := make([]TaskSpec, 10)
+	for i := range tasks {
+		tasks[i] = TaskSpec{ID: fmt.Sprintf("task-%d", i)}
+	}
+	layers := [][]TaskSpec{tasks}
+
+	serialStart := time.Now()
+	for _, task := range tasks {
+		_ = runCodexTaskFn(task, 5)
+	}
+	serialElapsed := time.Since(serialStart)
+
+	concurrentStart := time.Now()
+	_ = executeConcurrent(layers, 5)
+	concurrentElapsed := time.Since(concurrentStart)
+
+	if concurrentElapsed >= serialElapsed/5 {
+		t.Fatalf("expected concurrent time <20%% of serial, serial=%v concurrent=%v", serialElapsed, concurrentElapsed)
+	}
+	ratio := float64(concurrentElapsed) / float64(serialElapsed)
+	t.Logf("speedup ratio (concurrent/serial)=%.3f", ratio)
+}
+
+func TestRunStartupCleanupRemovesOrphansEndToEnd(t *testing.T) {
+	defer resetTestHooks()
+
+	tempDir := setTempDirEnv(t, t.TempDir())
+
+	orphanA := createTempLog(t, tempDir, "codex-wrapper-5001.log")
+	orphanB := createTempLog(t, tempDir, "codex-wrapper-5002-extra.log")
+	orphanC := createTempLog(t, tempDir, "codex-wrapper-5003-suffix.log")
+	runningPID := 81234
+	runningLog := createTempLog(t, tempDir, fmt.Sprintf("codex-wrapper-%d.log", runningPID))
+	unrelated := createTempLog(t, tempDir, "wrapper.log")
+
+	stubProcessRunning(t, func(pid int) bool {
+		return pid == runningPID || pid == os.Getpid()
+	})
+	stubProcessStartTime(t, func(pid int) time.Time {
+		if pid == runningPID || pid == os.Getpid() {
+			return time.Now().Add(-1 * time.Hour)
+		}
+		return time.Time{}
+	})
+
+	codexCommand = createFakeCodexScript(t, "tid-startup", "ok")
+	stdinReader = strings.NewReader("")
+	isTerminalFn = func() bool { return true }
+	os.Args = []string{"codex-wrapper", "task"}
+
+	if exit := run(); exit != 0 {
+		t.Fatalf("run() exit=%d, want 0", exit)
+	}
+
+	for _, orphan := range []string{orphanA, orphanB, orphanC} {
+		if _, err := os.Stat(orphan); !os.IsNotExist(err) {
+			t.Fatalf("expected orphan %s to be removed, err=%v", orphan, err)
+		}
+	}
+	if _, err := os.Stat(runningLog); err != nil {
+		t.Fatalf("expected running log to remain, err=%v", err)
+	}
+	if _, err := os.Stat(unrelated); err != nil {
+		t.Fatalf("expected unrelated file to remain, err=%v", err)
+	}
+}
+
+func TestRunStartupCleanupConcurrentWrappers(t *testing.T) {
+	defer resetTestHooks()
+
+	tempDir := setTempDirEnv(t, t.TempDir())
+
+	const totalLogs = 40
+	for i := 0; i < totalLogs; i++ {
+		createTempLog(t, tempDir, fmt.Sprintf("codex-wrapper-%d.log", 9000+i))
+	}
+
+	stubProcessRunning(t, func(pid int) bool {
+		return false
+	})
+	stubProcessStartTime(t, func(int) time.Time { return time.Time{} })
+
+	var wg sync.WaitGroup
+	const instances = 5
+	start := make(chan struct{})
+
+	for i := 0; i < instances; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-start
+			runStartupCleanup()
+		}()
+	}
+
+	close(start)
+	wg.Wait()
+
+	matches, err := filepath.Glob(filepath.Join(tempDir, "codex-wrapper-*.log"))
+	if err != nil {
+		t.Fatalf("glob error: %v", err)
+	}
+	if len(matches) != 0 {
+		t.Fatalf("expected all orphan logs to be removed, remaining=%v", matches)
+	}
+}
+
+func TestRunCleanupFlagEndToEnd_Success(t *testing.T) {
+	defer resetTestHooks()
+
+	tempDir := setTempDirEnv(t, t.TempDir())
+
+	staleA := createTempLog(t, tempDir, "codex-wrapper-2100.log")
+	staleB := createTempLog(t, tempDir, "codex-wrapper-2200-extra.log")
+	keeper := createTempLog(t, tempDir, "codex-wrapper-2300.log")
+
+	stubProcessRunning(t, func(pid int) bool {
+		return pid == 2300 || pid == os.Getpid()
+	})
+	stubProcessStartTime(t, func(pid int) time.Time {
+		if pid == 2300 || pid == os.Getpid() {
+			return time.Now().Add(-1 * time.Hour)
+		}
+		return time.Time{}
+	})
+
+	os.Args = []string{"codex-wrapper", "--cleanup"}
+
+	var exitCode int
+	output := captureStdout(t, func() {
+		exitCode = run()
+	})
+
+	if exitCode != 0 {
+		t.Fatalf("cleanup exit = %d, want 0", exitCode)
+	}
+
+	// Check that output contains expected counts and file names
+	if !strings.Contains(output, "Cleanup completed") {
+		t.Fatalf("missing 'Cleanup completed' in output: %q", output)
+	}
+	if !strings.Contains(output, "Files scanned: 3") {
+		t.Fatalf("missing 'Files scanned: 3' in output: %q", output)
+	}
+	if !strings.Contains(output, "Files deleted: 2") {
+		t.Fatalf("missing 'Files deleted: 2' in output: %q", output)
+	}
+	if !strings.Contains(output, "Files kept: 1") {
+		t.Fatalf("missing 'Files kept: 1' in output: %q", output)
+	}
+	if !strings.Contains(output, "codex-wrapper-2100.log") || !strings.Contains(output, "codex-wrapper-2200-extra.log") {
+		t.Fatalf("missing deleted file names in output: %q", output)
+	}
+	if !strings.Contains(output, "codex-wrapper-2300.log") {
+		t.Fatalf("missing kept file names in output: %q", output)
+	}
+
+	for _, path := range []string{staleA, staleB} {
+		if _, err := os.Stat(path); !os.IsNotExist(err) {
+			t.Fatalf("expected %s to be removed, err=%v", path, err)
+		}
+	}
+	if _, err := os.Stat(keeper); err != nil {
+		t.Fatalf("expected kept log to remain, err=%v", err)
+	}
+
+	currentLog := filepath.Join(tempDir, fmt.Sprintf("codex-wrapper-%d.log", os.Getpid()))
+	if _, err := os.Stat(currentLog); err == nil {
+		t.Fatalf("cleanup mode should not create new log file %s", currentLog)
+	} else if !os.IsNotExist(err) {
+		t.Fatalf("stat(%s) unexpected error: %v", currentLog, err)
+	}
+}
+
+func TestRunCleanupFlagEndToEnd_FailureDoesNotAffectStartup(t *testing.T) {
+	defer resetTestHooks()
+
+	tempDir := setTempDirEnv(t, t.TempDir())
+
+	calls := 0
+	cleanupLogsFn = func() (CleanupStats, error) {
+		calls++
+		return CleanupStats{Scanned: 1}, fmt.Errorf("permission denied")
+	}
+
+	os.Args = []string{"codex-wrapper", "--cleanup"}
+
+	var exitCode int
+	errOutput := captureStderr(t, func() {
+		exitCode = run()
+	})
+
+	if exitCode != 1 {
+		t.Fatalf("cleanup failure exit = %d, want 1", exitCode)
+	}
+	if !strings.Contains(errOutput, "Cleanup failed") || !strings.Contains(errOutput, "permission denied") {
+		t.Fatalf("cleanup stderr = %q, want failure message", errOutput)
+	}
+	if calls != 1 {
+		t.Fatalf("cleanup called %d times, want 1", calls)
+	}
+
+	currentLog := filepath.Join(tempDir, fmt.Sprintf("codex-wrapper-%d.log", os.Getpid()))
+	if _, err := os.Stat(currentLog); err == nil {
+		t.Fatalf("cleanup failure should not create new log file %s", currentLog)
+	} else if !os.IsNotExist(err) {
+		t.Fatalf("stat(%s) unexpected error: %v", currentLog, err)
+	}
+
+	cleanupLogsFn = func() (CleanupStats, error) {
+		return CleanupStats{}, nil
+	}
+	codexCommand = createFakeCodexScript(t, "tid-cleanup-e2e", "ok")
+	stdinReader = strings.NewReader("")
+	isTerminalFn = func() bool { return true }
+	os.Args = []string{"codex-wrapper", "post-cleanup task"}
+
+	var normalExit int
+	normalOutput := captureStdout(t, func() {
+		normalExit = run()
+	})
+
+	if normalExit != 0 {
+		t.Fatalf("normal run exit = %d, want 0", normalExit)
+	}
+	if !strings.Contains(normalOutput, "ok") {
+		t.Fatalf("normal run output = %q, want codex output", normalOutput)
+	}
+}

codeagent-wrapper/parser.go

@@ -0,0 +1,410 @@
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"strings"
+)
+
+// JSONEvent represents a Codex JSON output event
+type JSONEvent struct {
+	Type     string     `json:"type"`
+	ThreadID string     `json:"thread_id,omitempty"`
+	Item     *EventItem `json:"item,omitempty"`
+}
+
+// EventItem represents the item field in a JSON event
+type EventItem struct {
+	Type string      `json:"type"`
+	Text interface{} `json:"text"`
+}
+
+// ClaudeEvent for Claude stream-json format
+type ClaudeEvent struct {
+	Type      string `json:"type"`
+	Subtype   string `json:"subtype,omitempty"`
+	SessionID string `json:"session_id,omitempty"`
+	Result    string `json:"result,omitempty"`
+}
+
+// GeminiEvent for Gemini stream-json format
+type GeminiEvent struct {
+	Type      string `json:"type"`
+	SessionID string `json:"session_id,omitempty"`
+	Role      string `json:"role,omitempty"`
+	Content   string `json:"content,omitempty"`
+	Delta     bool   `json:"delta,omitempty"`
+	Status    string `json:"status,omitempty"`
+}
+
+func parseJSONStream(r io.Reader) (message, threadID string) {
+	return parseJSONStreamWithLog(r, logWarn, logInfo)
+}
+
+func parseJSONStreamWithWarn(r io.Reader, warnFn func(string)) (message, threadID string) {
+	return parseJSONStreamWithLog(r, warnFn, logInfo)
+}
+
+func parseJSONStreamWithLog(r io.Reader, warnFn func(string), infoFn func(string)) (message, threadID string) {
+	return parseJSONStreamInternal(r, warnFn, infoFn, nil, nil)
+}
+
+const (
+	jsonLineReaderSize   = 64 * 1024
+	jsonLineMaxBytes     = 10 * 1024 * 1024
+	jsonLinePreviewBytes = 256
+)
+
+type codexHeader struct {
+	Type     string `json:"type"`
+	ThreadID string `json:"thread_id,omitempty"`
+	Item     *struct {
+		Type string `json:"type"`
+	} `json:"item,omitempty"`
+}
+
+// UnifiedEvent combines all backend event formats into a single structure
+// to avoid multiple JSON unmarshal operations per event
+type UnifiedEvent struct {
+	// Common fields
+	Type string `json:"type"`
+
+	// Codex-specific fields
+	ThreadID string          `json:"thread_id,omitempty"`
+	Item     json.RawMessage `json:"item,omitempty"` // Lazy parse
+
+	// Claude-specific fields
+	Subtype   string `json:"subtype,omitempty"`
+	SessionID string `json:"session_id,omitempty"`
+	Result    string `json:"result,omitempty"`
+
+	// Gemini-specific fields
+	Role    string `json:"role,omitempty"`
+	Content string `json:"content,omitempty"`
+	Delta   *bool  `json:"delta,omitempty"`
+	Status  string `json:"status,omitempty"`
+}
+
+// ItemContent represents the parsed item.text field for Codex events
+type ItemContent struct {
+	Type string      `json:"type"`
+	Text interface{} `json:"text"`
+}
+
+func parseJSONStreamInternal(r io.Reader, warnFn func(string), infoFn func(string), onMessage func(), onComplete func()) (message, threadID string) {
+	reader := bufio.NewReaderSize(r, jsonLineReaderSize)
+
+	if warnFn == nil {
+		warnFn = func(string) {}
+	}
+	if infoFn == nil {
+		infoFn = func(string) {}
+	}
+
+	notifyMessage := func() {
+		if onMessage != nil {
+			onMessage()
+		}
+	}
+
+	notifyComplete := func() {
+		if onComplete != nil {
+			onComplete()
+		}
+	}
+
+	totalEvents := 0
+
+	var (
+		codexMessage  string
+		claudeMessage string
+		geminiBuffer  strings.Builder
+	)
+
+	for {
+		line, tooLong, err := readLineWithLimit(reader, jsonLineMaxBytes, jsonLinePreviewBytes)
+		if err != nil {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			warnFn("Read stdout error: " + err.Error())
+			break
+		}
+
+		line = bytes.TrimSpace(line)
+		if len(line) == 0 {
+			continue
+		}
+		totalEvents++
+
+		if tooLong {
+			warnFn(fmt.Sprintf("Skipped overlong JSON line (> %d bytes): %s", jsonLineMaxBytes, truncateBytes(line, 100)))
+			continue
+		}
+
+		// Single unmarshal for all backend types
+		var event UnifiedEvent
+		if err := json.Unmarshal(line, &event); err != nil {
+			warnFn(fmt.Sprintf("Failed to parse event: %s", truncateBytes(line, 100)))
+			continue
+		}
+
+		// Detect backend type by field presence
+		isCodex := event.ThreadID != ""
+		if !isCodex && len(event.Item) > 0 {
+			var itemHeader struct {
+				Type string `json:"type"`
+			}
+			if json.Unmarshal(event.Item, &itemHeader) == nil && itemHeader.Type != "" {
+				isCodex = true
+			}
+		}
+		isClaude := event.Subtype != "" || event.Result != ""
+		if !isClaude && event.Type == "result" && event.SessionID != "" && event.Status == "" {
+			isClaude = true
+		}
+		isGemini := event.Role != "" || event.Delta != nil || event.Status != ""
+
+		// Handle Codex events
+		if isCodex {
+			var details []string
+			if event.ThreadID != "" {
+				details = append(details, fmt.Sprintf("thread_id=%s", event.ThreadID))
+			}
+
+			if len(details) > 0 {
+				infoFn(fmt.Sprintf("Parsed event #%d type=%s (%s)", totalEvents, event.Type, strings.Join(details, ", ")))
+			} else {
+				infoFn(fmt.Sprintf("Parsed event #%d type=%s", totalEvents, event.Type))
+			}
+
+			switch event.Type {
+			case "thread.started":
+				threadID = event.ThreadID
+				infoFn(fmt.Sprintf("thread.started event thread_id=%s", threadID))
+
+			case "thread.completed":
+				if event.ThreadID != "" && threadID == "" {
+					threadID = event.ThreadID
+				}
+				infoFn(fmt.Sprintf("thread.completed event thread_id=%s", event.ThreadID))
+				notifyComplete()
+
+			case "item.completed":
+				var itemType string
+				if len(event.Item) > 0 {
+					var itemHeader struct {
+						Type string `json:"type"`
+					}
+					if err := json.Unmarshal(event.Item, &itemHeader); err == nil {
+						itemType = itemHeader.Type
+					}
+				}
+
+				if itemType == "agent_message" && len(event.Item) > 0 {
+					// Lazy parse: only parse item content when needed
+					var item ItemContent
+					if err := json.Unmarshal(event.Item, &item); err == nil {
+						normalized := normalizeText(item.Text)
+						infoFn(fmt.Sprintf("item.completed event item_type=%s message_len=%d", itemType, len(normalized)))
+						if normalized != "" {
+							codexMessage = normalized
+							notifyMessage()
+						}
+					} else {
+						warnFn(fmt.Sprintf("Failed to parse item content: %s", err.Error()))
+					}
+				} else {
+					infoFn(fmt.Sprintf("item.completed event item_type=%s", itemType))
+				}
+			}
+			continue
+		}
+
+		// Handle Claude events
+		if isClaude {
+			if event.SessionID != "" && threadID == "" {
+				threadID = event.SessionID
+			}
+
+			infoFn(fmt.Sprintf("Parsed Claude event #%d type=%s subtype=%s result_len=%d", totalEvents, event.Type, event.Subtype, len(event.Result)))
+
+			if event.Result != "" {
+				claudeMessage = event.Result
+				notifyMessage()
+			}
+
+			if event.Type == "result" {
+				notifyComplete()
+			}
+			continue
+		}
+
+		// Handle Gemini events
+		if isGemini {
+			if event.SessionID != "" && threadID == "" {
+				threadID = event.SessionID
+			}
+
+			if event.Content != "" {
+				geminiBuffer.WriteString(event.Content)
+			}
+
+			if event.Status != "" {
+				notifyMessage()
+
+				if event.Type == "result" && (event.Status == "success" || event.Status == "error" || event.Status == "complete" || event.Status == "failed") {
+					notifyComplete()
+				}
+			}
+
+			delta := false
+			if event.Delta != nil {
+				delta = *event.Delta
+			}
+
+			infoFn(fmt.Sprintf("Parsed Gemini event #%d type=%s role=%s delta=%t status=%s content_len=%d", totalEvents, event.Type, event.Role, delta, event.Status, len(event.Content)))
+			continue
+		}
+
+		// Unknown event format
+		warnFn(fmt.Sprintf("Unknown event format: %s", truncateBytes(line, 100)))
+	}
+
+	switch {
+	case geminiBuffer.Len() > 0:
+		message = geminiBuffer.String()
+	case claudeMessage != "":
+		message = claudeMessage
+	default:
+		message = codexMessage
+	}
+
+	infoFn(fmt.Sprintf("parseJSONStream completed: events=%d, message_len=%d, thread_id_found=%t", totalEvents, len(message), threadID != ""))
+	return message, threadID
+}
+
+func hasKey(m map[string]json.RawMessage, key string) bool {
+	_, ok := m[key]
+	return ok
+}
+
+func discardInvalidJSON(decoder *json.Decoder, reader *bufio.Reader) (*bufio.Reader, error) {
+	var buffered bytes.Buffer
+
+	if decoder != nil {
+		if buf := decoder.Buffered(); buf != nil {
+			_, _ = buffered.ReadFrom(buf)
+		}
+	}
+
+	line, err := reader.ReadBytes('\n')
+	buffered.Write(line)
+
+	data := buffered.Bytes()
+	newline := bytes.IndexByte(data, '\n')
+	if newline == -1 {
+		return reader, err
+	}
+
+	remaining := data[newline+1:]
+	if len(remaining) == 0 {
+		return reader, err
+	}
+
+	return bufio.NewReader(io.MultiReader(bytes.NewReader(remaining), reader)), err
+}
+
+func readLineWithLimit(r *bufio.Reader, maxBytes int, previewBytes int) (line []byte, tooLong bool, err error) {
+	if r == nil {
+		return nil, false, errors.New("reader is nil")
+	}
+	if maxBytes <= 0 {
+		return nil, false, errors.New("maxBytes must be > 0")
+	}
+	if previewBytes < 0 {
+		previewBytes = 0
+	}
+
+	part, isPrefix, err := r.ReadLine()
+	if err != nil {
+		return nil, false, err
+	}
+
+	if !isPrefix {
+		if len(part) > maxBytes {
+			return part[:min(len(part), previewBytes)], true, nil
+		}
+		return part, false, nil
+	}
+
+	preview := make([]byte, 0, min(previewBytes, len(part)))
+	if previewBytes > 0 {
+		preview = append(preview, part[:min(previewBytes, len(part))]...)
+	}
+
+	buf := make([]byte, 0, min(maxBytes, len(part)*2))
+	total := 0
+	if len(part) > maxBytes {
+		tooLong = true
+	} else {
+		buf = append(buf, part...)
+		total = len(part)
+	}
+
+	for isPrefix {
+		part, isPrefix, err = r.ReadLine()
+		if err != nil {
+			return nil, tooLong, err
+		}
+
+		if previewBytes > 0 && len(preview) < previewBytes {
+			preview = append(preview, part[:min(previewBytes-len(preview), len(part))]...)
+		}
+
+		if !tooLong {
+			if total+len(part) > maxBytes {
+				tooLong = true
+				continue
+			}
+			buf = append(buf, part...)
+			total += len(part)
+		}
+	}
+
+	if tooLong {
+		return preview, true, nil
+	}
+	return buf, false, nil
+}
+
+func truncateBytes(b []byte, maxLen int) string {
+	if len(b) <= maxLen {
+		return string(b)
+	}
+	if maxLen < 0 {
+		return ""
+	}
+	return string(b[:maxLen]) + "..."
+}
+
+func normalizeText(text interface{}) string {
+	switch v := text.(type) {
+	case string:
+		return v
+	case []interface{}:
+		var sb strings.Builder
+		for _, item := range v {
+			if s, ok := item.(string); ok {
+				sb.WriteString(s)
+			}
+		}
+		return sb.String()
+	default:
+		return ""
+	}
+}

codeagent-wrapper/parser_token_too_long_test.go

@@ -0,0 +1,31 @@
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestParseJSONStream_SkipsOverlongLineAndContinues(t *testing.T) {
+	// Exceed the 10MB bufio.Scanner limit in parseJSONStreamInternal.
+	tooLong := strings.Repeat("a", 11*1024*1024)
+
+	input := strings.Join([]string{
+		`{"type":"item.completed","item":{"type":"other_type","text":"` + tooLong + `"}}`,
+		`{"type":"thread.started","thread_id":"t-1"}`,
+		`{"type":"item.completed","item":{"type":"agent_message","text":"ok"}}`,
+	}, "\n")
+
+	var warns []string
+	warnFn := func(msg string) { warns = append(warns, msg) }
+
+	gotMessage, gotThreadID := parseJSONStreamInternal(strings.NewReader(input), warnFn, nil, nil, nil)
+	if gotMessage != "ok" {
+		t.Fatalf("message=%q, want %q (warns=%v)", gotMessage, "ok", warns)
+	}
+	if gotThreadID != "t-1" {
+		t.Fatalf("threadID=%q, want %q (warns=%v)", gotThreadID, "t-1", warns)
+	}
+	if len(warns) == 0 || !strings.Contains(warns[0], "Skipped overlong JSON line") {
+		t.Fatalf("expected warning about overlong JSON line, got %v", warns)
+	}
+}

codeagent-wrapper/process_check_test.go

@@ -0,0 +1,217 @@
+//go:build unix || darwin || linux
+// +build unix darwin linux
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+	"runtime"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestIsProcessRunning(t *testing.T) {
+	t.Run("current process", func(t *testing.T) {
+		if !isProcessRunning(os.Getpid()) {
+			t.Fatalf("expected current process (pid=%d) to be running", os.Getpid())
+		}
+	})
+
+	t.Run("fake pid", func(t *testing.T) {
+		const nonexistentPID = 1 << 30
+		if isProcessRunning(nonexistentPID) {
+			t.Fatalf("expected pid %d to be reported as not running", nonexistentPID)
+		}
+	})
+
+	t.Run("terminated process", func(t *testing.T) {
+		pid := exitedProcessPID(t)
+		if isProcessRunning(pid) {
+			t.Fatalf("expected exited child process (pid=%d) to be reported as not running", pid)
+		}
+	})
+
+	t.Run("boundary values", func(t *testing.T) {
+		if isProcessRunning(0) {
+			t.Fatalf("pid 0 should never be treated as running")
+		}
+		if isProcessRunning(-42) {
+			t.Fatalf("negative pid should never be treated as running")
+		}
+	})
+
+	t.Run("find process error", func(t *testing.T) {
+		original := findProcess
+		defer func() { findProcess = original }()
+
+		mockErr := errors.New("findProcess failure")
+		findProcess = func(pid int) (*os.Process, error) {
+			return nil, mockErr
+		}
+
+		if isProcessRunning(1234) {
+			t.Fatalf("expected false when os.FindProcess fails")
+		}
+	})
+}
+
+func exitedProcessPID(t *testing.T) int {
+	t.Helper()
+
+	var cmd *exec.Cmd
+	if runtime.GOOS == "windows" {
+		cmd = exec.Command("cmd", "/c", "exit 0")
+	} else {
+		cmd = exec.Command("sh", "-c", "exit 0")
+	}
+
+	if err := cmd.Start(); err != nil {
+		t.Fatalf("failed to start helper process: %v", err)
+	}
+	pid := cmd.Process.Pid
+
+	if err := cmd.Wait(); err != nil {
+		t.Fatalf("helper process did not exit cleanly: %v", err)
+	}
+
+	time.Sleep(50 * time.Millisecond)
+	return pid
+}
+
+func TestRunProcessCheckSmoke(t *testing.T) {
+	t.Run("current process", func(t *testing.T) {
+		if !isProcessRunning(os.Getpid()) {
+			t.Fatalf("expected current process (pid=%d) to be running", os.Getpid())
+		}
+	})
+
+	t.Run("fake pid", func(t *testing.T) {
+		const nonexistentPID = 1 << 30
+		if isProcessRunning(nonexistentPID) {
+			t.Fatalf("expected pid %d to be reported as not running", nonexistentPID)
+		}
+	})
+
+	t.Run("boundary values", func(t *testing.T) {
+		if isProcessRunning(0) {
+			t.Fatalf("pid 0 should never be treated as running")
+		}
+		if isProcessRunning(-42) {
+			t.Fatalf("negative pid should never be treated as running")
+		}
+	})
+
+	t.Run("find process error", func(t *testing.T) {
+		original := findProcess
+		defer func() { findProcess = original }()
+
+		mockErr := errors.New("findProcess failure")
+		findProcess = func(pid int) (*os.Process, error) {
+			return nil, mockErr
+		}
+
+		if isProcessRunning(1234) {
+			t.Fatalf("expected false when os.FindProcess fails")
+		}
+	})
+}
+
+func TestGetProcessStartTimeReadsProcStat(t *testing.T) {
+	pid := 4321
+	boot := time.Unix(1_710_000_000, 0)
+	startTicks := uint64(4500)
+
+	statFields := make([]string, 25)
+	for i := range statFields {
+		statFields[i] = strconv.Itoa(i + 1)
+	}
+	statFields[19] = strconv.FormatUint(startTicks, 10)
+	statContent := fmt.Sprintf("%d (%s) %s", pid, "cmd with space", strings.Join(statFields, " "))
+
+	stubReadFile(t, func(path string) ([]byte, error) {
+		switch path {
+		case fmt.Sprintf("/proc/%d/stat", pid):
+			return []byte(statContent), nil
+		case "/proc/stat":
+			return []byte(fmt.Sprintf("cpu 0 0 0 0\nbtime %d\n", boot.Unix())), nil
+		default:
+			return nil, os.ErrNotExist
+		}
+	})
+
+	got := getProcessStartTime(pid)
+	want := boot.Add(time.Duration(startTicks/100) * time.Second)
+	if !got.Equal(want) {
+		t.Fatalf("getProcessStartTime() = %v, want %v", got, want)
+	}
+}
+
+func TestGetProcessStartTimeInvalidData(t *testing.T) {
+	pid := 99
+	stubReadFile(t, func(path string) ([]byte, error) {
+		switch path {
+		case fmt.Sprintf("/proc/%d/stat", pid):
+			return []byte("garbage"), nil
+		case "/proc/stat":
+			return []byte("btime not-a-number\n"), nil
+		default:
+			return nil, os.ErrNotExist
+		}
+	})
+
+	if got := getProcessStartTime(pid); !got.IsZero() {
+		t.Fatalf("invalid /proc data should return zero time, got %v", got)
+	}
+}
+
+func TestGetBootTimeParsesBtime(t *testing.T) {
+	const bootSec = 1_711_111_111
+	stubReadFile(t, func(path string) ([]byte, error) {
+		if path != "/proc/stat" {
+			return nil, os.ErrNotExist
+		}
+		content := fmt.Sprintf("intr 0\nbtime %d\n", bootSec)
+		return []byte(content), nil
+	})
+
+	got := getBootTime()
+	want := time.Unix(bootSec, 0)
+	if !got.Equal(want) {
+		t.Fatalf("getBootTime() = %v, want %v", got, want)
+	}
+}
+
+func TestGetBootTimeInvalidData(t *testing.T) {
+	cases := []struct {
+		name    string
+		content string
+	}{
+		{"missing", "cpu 0 0 0 0"},
+		{"malformed", "btime abc"},
+	}
+
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			stubReadFile(t, func(string) ([]byte, error) {
+				return []byte(tt.content), nil
+			})
+			if got := getBootTime(); !got.IsZero() {
+				t.Fatalf("getBootTime() unexpected value for %s: %v", tt.name, got)
+			}
+		})
+	}
+}
+
+func stubReadFile(t *testing.T, fn func(string) ([]byte, error)) {
+	t.Helper()
+	original := readFileFn
+	readFileFn = fn
+	t.Cleanup(func() {
+		readFileFn = original
+	})
+}

codeagent-wrapper/process_check_unix.go

@@ -0,0 +1,104 @@
+//go:build unix || darwin || linux
+// +build unix darwin linux
+
+package main
+
+import (
+	"errors"
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+	"syscall"
+	"time"
+)
+
+var findProcess = os.FindProcess
+var readFileFn = os.ReadFile
+
+// isProcessRunning returns true if a process with the given pid is running on Unix-like systems.
+func isProcessRunning(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+
+	proc, err := findProcess(pid)
+	if err != nil || proc == nil {
+		return false
+	}
+
+	err = proc.Signal(syscall.Signal(0))
+	if err != nil && (errors.Is(err, syscall.ESRCH) || errors.Is(err, os.ErrProcessDone)) {
+		return false
+	}
+	return true
+}
+
+// getProcessStartTime returns the start time of a process on Unix-like systems.
+// Returns zero time if the start time cannot be determined.
+func getProcessStartTime(pid int) time.Time {
+	if pid <= 0 {
+		return time.Time{}
+	}
+
+	// Read /proc/<pid>/stat to get process start time
+	statPath := fmt.Sprintf("/proc/%d/stat", pid)
+	data, err := readFileFn(statPath)
+	if err != nil {
+		return time.Time{}
+	}
+
+	// Parse stat file: fields are space-separated, but comm (field 2) can contain spaces
+	// Find the last ')' to skip comm field safely
+	content := string(data)
+	lastParen := strings.LastIndex(content, ")")
+	if lastParen == -1 {
+		return time.Time{}
+	}
+
+	fields := strings.Fields(content[lastParen+1:])
+	if len(fields) < 20 {
+		return time.Time{}
+	}
+
+	// Field 22 (index 19 after comm) is starttime in clock ticks since boot
+	startTicks, err := strconv.ParseUint(fields[19], 10, 64)
+	if err != nil {
+		return time.Time{}
+	}
+
+	// Get system boot time
+	bootTime := getBootTime()
+	if bootTime.IsZero() {
+		return time.Time{}
+	}
+
+	// Convert ticks to duration (typically 100 ticks/sec on most systems)
+	ticksPerSec := uint64(100) // sysconf(_SC_CLK_TCK), typically 100
+	startTime := bootTime.Add(time.Duration(startTicks/ticksPerSec) * time.Second)
+
+	return startTime
+}
+
+// getBootTime returns the system boot time by reading /proc/stat.
+func getBootTime() time.Time {
+	data, err := readFileFn("/proc/stat")
+	if err != nil {
+		return time.Time{}
+	}
+
+	lines := strings.Split(string(data), "\n")
+	for _, line := range lines {
+		if strings.HasPrefix(line, "btime ") {
+			fields := strings.Fields(line)
+			if len(fields) >= 2 {
+				bootSec, err := strconv.ParseInt(fields[1], 10, 64)
+				if err == nil {
+					return time.Unix(bootSec, 0)
+				}
+			}
+		}
+	}
+
+	return time.Time{}
+}

codeagent-wrapper/process_check_windows.go

@@ -0,0 +1,87 @@
+//go:build windows
+// +build windows
+
+package main
+
+import (
+	"errors"
+	"os"
+	"syscall"
+	"time"
+	"unsafe"
+)
+
+const (
+	processQueryLimitedInformation = 0x1000
+	stillActive                    = 259 // STILL_ACTIVE exit code
+)
+
+var (
+	findProcess       = os.FindProcess
+	kernel32          = syscall.NewLazyDLL("kernel32.dll")
+	getProcessTimes   = kernel32.NewProc("GetProcessTimes")
+	fileTimeToUnixFn  = fileTimeToUnix
+)
+
+// isProcessRunning returns true if a process with the given pid is running on Windows.
+func isProcessRunning(pid int) bool {
+	if pid <= 0 {
+		return false
+	}
+
+	if _, err := findProcess(pid); err != nil {
+		return false
+	}
+
+	handle, err := syscall.OpenProcess(processQueryLimitedInformation, false, uint32(pid))
+	if err != nil {
+		if errors.Is(err, syscall.ERROR_ACCESS_DENIED) {
+			return true
+		}
+		return false
+	}
+	defer syscall.CloseHandle(handle)
+
+	var exitCode uint32
+	if err := syscall.GetExitCodeProcess(handle, &exitCode); err != nil {
+		return true
+	}
+
+	return exitCode == stillActive
+}
+
+// getProcessStartTime returns the start time of a process on Windows.
+// Returns zero time if the start time cannot be determined.
+func getProcessStartTime(pid int) time.Time {
+	if pid <= 0 {
+		return time.Time{}
+	}
+
+	handle, err := syscall.OpenProcess(processQueryLimitedInformation, false, uint32(pid))
+	if err != nil {
+		return time.Time{}
+	}
+	defer syscall.CloseHandle(handle)
+
+	var creationTime, exitTime, kernelTime, userTime syscall.Filetime
+	ret, _, _ := getProcessTimes.Call(
+		uintptr(handle),
+		uintptr(unsafe.Pointer(&creationTime)),
+		uintptr(unsafe.Pointer(&exitTime)),
+		uintptr(unsafe.Pointer(&kernelTime)),
+		uintptr(unsafe.Pointer(&userTime)),
+	)
+
+	if ret == 0 {
+		return time.Time{}
+	}
+
+	return fileTimeToUnixFn(creationTime)
+}
+
+// fileTimeToUnix converts Windows FILETIME to Unix time.
+func fileTimeToUnix(ft syscall.Filetime) time.Time {
+	// FILETIME is 100-nanosecond intervals since January 1, 1601 UTC
+	nsec := ft.Nanoseconds()
+	return time.Unix(0, nsec)
+}

codeagent-wrapper/utils.go

@@ -0,0 +1,225 @@
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os"
+	"strconv"
+	"strings"
+)
+
+func resolveTimeout() int {
+	raw := os.Getenv("CODEX_TIMEOUT")
+	if raw == "" {
+		return defaultTimeout
+	}
+
+	parsed, err := strconv.Atoi(raw)
+	if err != nil || parsed <= 0 {
+		logWarn(fmt.Sprintf("Invalid CODEX_TIMEOUT '%s', falling back to %ds", raw, defaultTimeout))
+		return defaultTimeout
+	}
+
+	if parsed > 10000 {
+		return parsed / 1000
+	}
+	return parsed
+}
+
+func readPipedTask() (string, error) {
+	if isTerminal() {
+		logInfo("Stdin is tty, skipping pipe read")
+		return "", nil
+	}
+	logInfo("Reading from stdin pipe...")
+	data, err := io.ReadAll(stdinReader)
+	if err != nil {
+		return "", fmt.Errorf("read stdin: %w", err)
+	}
+	if len(data) == 0 {
+		logInfo("Stdin pipe returned empty data")
+		return "", nil
+	}
+	logInfo(fmt.Sprintf("Read %d bytes from stdin pipe", len(data)))
+	return string(data), nil
+}
+
+func shouldUseStdin(taskText string, piped bool) bool {
+	if piped {
+		return true
+	}
+	if len(taskText) > 800 {
+		return true
+	}
+	return strings.IndexAny(taskText, stdinSpecialChars) >= 0
+}
+
+func defaultIsTerminal() bool {
+	fi, err := os.Stdin.Stat()
+	if err != nil {
+		return true
+	}
+	return (fi.Mode() & os.ModeCharDevice) != 0
+}
+
+func isTerminal() bool {
+	return isTerminalFn()
+}
+
+func getEnv(key, defaultValue string) string {
+	if val := os.Getenv(key); val != "" {
+		return val
+	}
+	return defaultValue
+}
+
+type logWriter struct {
+	prefix string
+	maxLen int
+	buf    bytes.Buffer
+	dropped bool
+}
+
+func newLogWriter(prefix string, maxLen int) *logWriter {
+	if maxLen <= 0 {
+		maxLen = codexLogLineLimit
+	}
+	return &logWriter{prefix: prefix, maxLen: maxLen}
+}
+
+func (lw *logWriter) Write(p []byte) (int, error) {
+	if lw == nil {
+		return len(p), nil
+	}
+	total := len(p)
+	for len(p) > 0 {
+		if idx := bytes.IndexByte(p, '\n'); idx >= 0 {
+			lw.writeLimited(p[:idx])
+			lw.logLine(true)
+			p = p[idx+1:]
+			continue
+		}
+		lw.writeLimited(p)
+		break
+	}
+	return total, nil
+}
+
+func (lw *logWriter) Flush() {
+	if lw == nil || lw.buf.Len() == 0 {
+		return
+	}
+	lw.logLine(false)
+}
+
+func (lw *logWriter) logLine(force bool) {
+	if lw == nil {
+		return
+	}
+	line := lw.buf.String()
+	dropped := lw.dropped
+	lw.dropped = false
+	lw.buf.Reset()
+	if line == "" && !force {
+		return
+	}
+	if lw.maxLen > 0 {
+		if dropped {
+			if lw.maxLen > 3 {
+				line = line[:min(len(line), lw.maxLen-3)] + "..."
+			} else {
+				line = line[:min(len(line), lw.maxLen)]
+			}
+		} else if len(line) > lw.maxLen {
+			cutoff := lw.maxLen
+			if cutoff > 3 {
+				line = line[:cutoff-3] + "..."
+			} else {
+				line = line[:cutoff]
+			}
+		}
+	}
+	logInfo(lw.prefix + line)
+}
+
+func (lw *logWriter) writeLimited(p []byte) {
+	if lw == nil || len(p) == 0 {
+		return
+	}
+	if lw.maxLen <= 0 {
+		lw.buf.Write(p)
+		return
+	}
+
+	remaining := lw.maxLen - lw.buf.Len()
+	if remaining <= 0 {
+		lw.dropped = true
+		return
+	}
+	if len(p) <= remaining {
+		lw.buf.Write(p)
+		return
+	}
+	lw.buf.Write(p[:remaining])
+	lw.dropped = true
+}
+
+type tailBuffer struct {
+	limit int
+	data  []byte
+}
+
+func (b *tailBuffer) Write(p []byte) (int, error) {
+	if b.limit <= 0 {
+		return len(p), nil
+	}
+
+	if len(p) >= b.limit {
+		b.data = append(b.data[:0], p[len(p)-b.limit:]...)
+		return len(p), nil
+	}
+
+	total := len(b.data) + len(p)
+	if total <= b.limit {
+		b.data = append(b.data, p...)
+		return len(p), nil
+	}
+
+	overflow := total - b.limit
+	b.data = append(b.data[overflow:], p...)
+	return len(p), nil
+}
+
+func (b *tailBuffer) String() string {
+	return string(b.data)
+}
+
+func truncate(s string, maxLen int) string {
+	if len(s) <= maxLen {
+		return s
+	}
+	if maxLen < 0 {
+		return ""
+	}
+	return s[:maxLen] + "..."
+}
+
+func min(a, b int) int {
+	if a < b {
+		return a
+	}
+	return b
+}
+
+func hello() string {
+	return "hello world"
+}
+
+func greet(name string) string {
+	return "hello " + name
+}
+
+func farewell(name string) string {
+	return "goodbye " + name
+}

codeagent-wrapper/wrapper_name.go

@@ -0,0 +1,126 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const (
+	defaultWrapperName = "codeagent-wrapper"
+	legacyWrapperName  = "codex-wrapper"
+)
+
+var executablePathFn = os.Executable
+
+func normalizeWrapperName(path string) string {
+	if path == "" {
+		return ""
+	}
+
+	base := filepath.Base(path)
+	base = strings.TrimSuffix(base, ".exe") // tolerate Windows executables
+
+	switch base {
+	case defaultWrapperName, legacyWrapperName:
+		return base
+	default:
+		return ""
+	}
+}
+
+// currentWrapperName resolves the wrapper name based on the invoked binary.
+// Only known names are honored to avoid leaking build/test binary names into logs.
+func currentWrapperName() string {
+	if len(os.Args) == 0 {
+		return defaultWrapperName
+	}
+
+	if name := normalizeWrapperName(os.Args[0]); name != "" {
+		return name
+	}
+
+	execPath, err := executablePathFn()
+	if err == nil {
+		if name := normalizeWrapperName(execPath); name != "" {
+			return name
+		}
+
+		if resolved, err := filepath.EvalSymlinks(execPath); err == nil {
+			if name := normalizeWrapperName(resolved); name != "" {
+				return name
+			}
+			if alias := resolveAlias(execPath, resolved); alias != "" {
+				return alias
+			}
+		}
+
+		if alias := resolveAlias(execPath, ""); alias != "" {
+			return alias
+		}
+	}
+
+	return defaultWrapperName
+}
+
+// logPrefixes returns the set of accepted log name prefixes, including the
+// current wrapper name and legacy aliases.
+func logPrefixes() []string {
+	prefixes := []string{currentWrapperName(), defaultWrapperName, legacyWrapperName}
+	seen := make(map[string]struct{}, len(prefixes))
+	var unique []string
+	for _, prefix := range prefixes {
+		if prefix == "" {
+			continue
+		}
+		if _, ok := seen[prefix]; ok {
+			continue
+		}
+		seen[prefix] = struct{}{}
+		unique = append(unique, prefix)
+	}
+	return unique
+}
+
+// primaryLogPrefix returns the preferred filename prefix for log files.
+// Defaults to the current wrapper name when available, otherwise falls back
+// to the canonical default name.
+func primaryLogPrefix() string {
+	prefixes := logPrefixes()
+	if len(prefixes) == 0 {
+		return defaultWrapperName
+	}
+	return prefixes[0]
+}
+
+func resolveAlias(execPath string, target string) string {
+	if execPath == "" {
+		return ""
+	}
+
+	dir := filepath.Dir(execPath)
+	for _, candidate := range []string{defaultWrapperName, legacyWrapperName} {
+		aliasPath := filepath.Join(dir, candidate)
+		info, err := os.Lstat(aliasPath)
+		if err != nil {
+			continue
+		}
+		if info.Mode()&os.ModeSymlink == 0 {
+			continue
+		}
+
+		resolved, err := filepath.EvalSymlinks(aliasPath)
+		if err != nil {
+			continue
+		}
+		if target != "" && resolved != target {
+			continue
+		}
+
+		if name := normalizeWrapperName(aliasPath); name != "" {
+			return name
+		}
+	}
+
+	return ""
+}

codeagent-wrapper/wrapper_name_test.go

@@ -0,0 +1,50 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestCurrentWrapperNameFallsBackToExecutable(t *testing.T) {
+	defer resetTestHooks()
+
+	tempDir := t.TempDir()
+	execPath := filepath.Join(tempDir, "codeagent-wrapper")
+	if err := os.WriteFile(execPath, []byte("#!/bin/true\n"), 0o755); err != nil {
+		t.Fatalf("failed to write fake binary: %v", err)
+	}
+
+	os.Args = []string{filepath.Join(tempDir, "custom-name")}
+	executablePathFn = func() (string, error) {
+		return execPath, nil
+	}
+
+	if got := currentWrapperName(); got != defaultWrapperName {
+		t.Fatalf("currentWrapperName() = %q, want %q", got, defaultWrapperName)
+	}
+}
+
+func TestCurrentWrapperNameDetectsLegacyAliasSymlink(t *testing.T) {
+	defer resetTestHooks()
+
+	tempDir := t.TempDir()
+	execPath := filepath.Join(tempDir, "wrapper")
+	aliasPath := filepath.Join(tempDir, legacyWrapperName)
+
+	if err := os.WriteFile(execPath, []byte("#!/bin/true\n"), 0o755); err != nil {
+		t.Fatalf("failed to write fake binary: %v", err)
+	}
+	if err := os.Symlink(execPath, aliasPath); err != nil {
+		t.Fatalf("failed to create alias: %v", err)
+	}
+
+	os.Args = []string{filepath.Join(tempDir, "unknown-runner")}
+	executablePathFn = func() (string, error) {
+		return execPath, nil
+	}
+
+	if got := currentWrapperName(); got != legacyWrapperName {
+		t.Fatalf("currentWrapperName() = %q, want %q", got, legacyWrapperName)
+	}
+}

config.json

@@ -0,0 +1,113 @@
+{
+  "version": "1.0",
+  "install_dir": "~/.claude",
+  "log_file": "install.log",
+  "modules": {
+    "dev": {
+      "enabled": true,
+      "description": "Core dev workflow with Codex integration",
+      "operations": [
+        {
+          "type": "merge_dir",
+          "source": "dev-workflow",
+          "description": "Merge commands/ and agents/ into install dir"
+        },
+        {
+          "type": "copy_file",
+          "source": "memorys/CLAUDE.md",
+          "target": "CLAUDE.md",
+          "description": "Copy core role and guidelines"
+        },
+        {
+          "type": "copy_file",
+          "source": "skills/codeagent/SKILL.md",
+          "target": "skills/codeagent/SKILL.md",
+          "description": "Install codeagent skill"
+        },
+        {
+          "type": "copy_file",
+          "source": "skills/product-requirements/SKILL.md",
+          "target": "skills/product-requirements/SKILL.md",
+          "description": "Install product-requirements skill"
+        },
+        {
+          "type": "copy_file",
+          "source": "skills/prototype-prompt-generator/SKILL.md",
+          "target": "skills/prototype-prompt-generator/SKILL.md",
+          "description": "Install prototype-prompt-generator skill"
+        },
+        {
+          "type": "copy_file",
+          "source": "skills/prototype-prompt-generator/references/prompt-structure.md",
+          "target": "skills/prototype-prompt-generator/references/prompt-structure.md",
+          "description": "Install prototype-prompt-generator prompt structure reference"
+        },
+        {
+          "type": "copy_file",
+          "source": "skills/prototype-prompt-generator/references/design-systems.md",
+          "target": "skills/prototype-prompt-generator/references/design-systems.md",
+          "description": "Install prototype-prompt-generator design systems reference"
+        },
+        {
+          "type": "run_command",
+          "command": "bash install.sh",
+          "description": "Install codeagent-wrapper binary",
+          "env": {
+            "INSTALL_DIR": "${install_dir}"
+          }
+        }
+      ]
+    },
+    "bmad": {
+      "enabled": false,
+      "description": "BMAD agile workflow with multi-agent orchestration",
+      "operations": [
+        {
+          "type": "merge_dir",
+          "source": "bmad-agile-workflow",
+          "description": "Merge BMAD commands and agents"
+        },
+        {
+          "type": "copy_file",
+          "source": "docs/BMAD-WORKFLOW.md",
+          "target": "docs/BMAD-WORKFLOW.md",
+          "description": "Copy BMAD workflow documentation"
+        }
+      ]
+    },
+    "requirements": {
+      "enabled": false,
+      "description": "Requirements-driven development workflow",
+      "operations": [
+        {
+          "type": "merge_dir",
+          "source": "requirements-driven-workflow",
+          "description": "Merge requirements workflow commands and agents"
+        },
+        {
+          "type": "copy_file",
+          "source": "docs/REQUIREMENTS-WORKFLOW.md",
+          "target": "docs/REQUIREMENTS-WORKFLOW.md",
+          "description": "Copy requirements workflow documentation"
+        }
+      ]
+    },
+    "essentials": {
+      "enabled": true,
+      "description": "Core development commands and utilities",
+      "operations": [
+        {
+          "type": "merge_dir",
+          "source": "development-essentials",
+          "description": "Merge essential development commands"
+        },
+        {
+          "type": "copy_file",
+          "source": "docs/DEVELOPMENT-COMMANDS.md",
+          "target": "docs/DEVELOPMENT-COMMANDS.md",
+          "description": "Copy development commands documentation"
+        }
+      ]
+    }
+  }
+}

config.schema.json

@@ -0,0 +1,122 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/cexll/myclaude/config.schema.json",
+  "title": "Modular Installation Config",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "install_dir", "log_file", "modules"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+(\\.[0-9]+)?$"
+    },
+    "install_dir": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Target installation directory, supports ~/ expansion"
+    },
+    "log_file": {
+      "type": "string",
+      "minLength": 1
+    },
+    "modules": {
+      "type": "object",
+      "description": "可自定义的模块定义,每个模块名称可任意指定",
+      "patternProperties": {
+        "^[a-zA-Z0-9_-]+$": { "$ref": "#/$defs/module" }
+      },
+      "additionalProperties": false,
+      "minProperties": 1
+    }
+  },
+  "$defs": {
+    "module": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled", "description", "operations"],
+      "properties": {
+        "enabled": { "type": "boolean", "default": false },
+        "description": { "type": "string", "minLength": 3 },
+        "operations": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/operation" }
+        }
+      }
+    },
+    "operation": {
+      "oneOf": [
+        { "$ref": "#/$defs/op_copy_dir" },
+        { "$ref": "#/$defs/op_copy_file" },
+        { "$ref": "#/$defs/op_merge_dir" },
+        { "$ref": "#/$defs/op_merge_json" },
+        { "$ref": "#/$defs/op_run_command" }
+      ]
+    },
+    "common_operation_fields": {
+      "type": "object",
+      "properties": {
+        "description": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "op_copy_dir": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "source", "target"],
+      "properties": {
+        "type": { "const": "copy_dir" },
+        "source": { "type": "string", "minLength": 1 },
+        "target": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" }
+      }
+    },
+    "op_copy_file": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "source", "target"],
+      "properties": {
+        "type": { "const": "copy_file" },
+        "source": { "type": "string", "minLength": 1 },
+        "target": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" }
+      }
+    },
+    "op_merge_dir": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "source"],
+      "properties": {
+        "type": { "const": "merge_dir" },
+        "source": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" }
+      }
+    },
+    "op_merge_json": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "source", "target"],
+      "properties": {
+        "type": { "const": "merge_json" },
+        "source": { "type": "string", "minLength": 1 },
+        "target": { "type": "string", "minLength": 1 },
+        "merge_key": { "type": "string" },
+        "description": { "type": "string" }
+      }
+    },
+    "op_run_command": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "command"],
+      "properties": {
+        "type": { "const": "run_command" },
+        "command": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "env": {
+          "type": "object",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  }
+}

dev-workflow/README.md

@@ -0,0 +1,174 @@
+# /dev - Minimal Dev Workflow
+
+## Overview
+
+A freshly designed lightweight development workflow with no legacy baggage, focused on delivering high-quality code fast.
+
+## Flow
+
+```
+/dev trigger
+  ↓
+AskUserQuestion (requirements clarification)
+  ↓
+codeagent analysis (plan mode + UI auto-detection)
+  ↓
+dev-plan-generator (create dev doc)
+  ↓
+codeagent concurrent development (2–5 tasks, backend split)
+  ↓
+codeagent testing & verification (≥90% coverage)
+  ↓
+Done (generate summary)
+```
+
+## The 6 Steps
+
+### 1. Clarify Requirements
+- Use **AskUserQuestion** to ask the user directly
+- No scoring system, no complex logic
+- 2–3 rounds of Q&A until the requirement is clear
+
+### 2. codeagent Analysis & UI Detection
+- Call codeagent to analyze the request in plan mode style
+- Extract: core functions, technical points, task list (2–5 items)
+- UI auto-detection: needs UI work when task involves style assets (.css, .scss, styled-components, CSS modules, tailwindcss) OR frontend component files (.tsx, .jsx, .vue); output yes/no plus evidence
+
+### 3. Generate Dev Doc
+- Call the **dev-plan-generator** agent
+- Produce a single `dev-plan.md`
+- Append a dedicated UI task when Step 2 marks `needs_ui: true`
+- Include: task breakdown, file scope, dependencies, test commands
+
+### 4. Concurrent Development
+- Work from the task list in dev-plan.md
+- Use codeagent per task with explicit backend selection:
+  - Backend/API/DB tasks → `--backend codex` (default)
+  - UI/style/component tasks → `--backend gemini` (enforced)
+- Independent tasks → run in parallel
+- Conflicting tasks → run serially
+
+### 5. Testing & Verification
+- Each codeagent task:
+  - Implements the feature
+  - Writes tests
+  - Runs coverage
+  - Reports results (≥90%)
+
+### 6. Complete
+- Summarize task status
+- Record coverage
+
+## Usage
+
+```bash
+/dev "Implement user login with email + password"
+```
+
+**No options**, fixed workflow, works out of the box.
+
+## Output Structure
+
+```
+.claude/specs/{feature_name}/
+└──  dev-plan.md      # Dev document generated by agent
+```
+
+Only one file—minimal and clear.
+
+## Core Components
+
+### Tools
+- **AskUserQuestion**: interactive requirement clarification
+- **codeagent skill**: analysis, development, testing; supports `--backend` for codex (default) or gemini (UI)
+- **dev-plan-generator agent**: generate dev doc (subagent via Task tool, saves context)
+
+## UI Auto-Detection & Backend Routing
+- **UI detection standard**: style files (.css, .scss, styled-components, CSS modules, tailwindcss) OR frontend component code (.tsx, .jsx, .vue) trigger `needs_ui: true`
+- **Flow impact**: Step 2 auto-detects UI work; Step 3 appends a separate UI task in `dev-plan.md` when detected
+- **Backend split**: backend/API tasks use codex backend (default); UI tasks force gemini backend
+- **Implementation**: Orchestrator invokes codeagent skill with appropriate backend parameter per task type
+
+## Key Features
+
+### ✅ Fresh Design
+- No legacy project residue
+- No complex scoring logic
+- No extra abstraction layers
+
+### ✅ Minimal Orchestration
+- Orchestrator controls the flow directly
+- Only three tools/components
+- Steps are straightforward
+
+### ✅ Concurrency
+- 2–5 tasks in parallel
+- Auto-detect dependencies and conflicts
+- codeagent executes independently
+
+### ✅ Quality Assurance
+- Enforces 90% coverage
+- codeagent tests and verifies its own work
+- Automatic retry on failure
+
+## Example
+
+```bash
+# Trigger
+/dev "Add user login feature"
+
+# Step 1: Clarify requirements
+Q: What login methods are supported?
+A: Email + password
+Q: Should login be remembered?
+A: Yes, use JWT token
+
+# Step 2: codeagent analysis
+Output:
+- Core: email/password login + JWT auth
+- Task 1: Backend API
+- Task 2: Password hashing
+- Task 3: Frontend form
+UI detection: needs_ui = true (tailwindcss classes in frontend form)
+
+# Step 3: Generate doc
+dev-plan.md generated with backend + UI tasks ✓
+
+# Step 4-5: Concurrent development (backend codex, UI gemini)
+[task-1] Backend API (codex) → tests → 92% ✓
+[task-2] Password hashing (codex) → tests → 95% ✓
+[task-3] Frontend form (gemini) → tests → 91% ✓
+```
+
+## Directory Structure
+
+```
+dev-workflow/
+├── README.md                          # This doc
+├── commands/
+│   └── dev.md                         # /dev workflow orchestrator definition
+└── agents/
+    └── dev-plan-generator.md          # Dev plan document generator agent
+```
+
+Minimal structure, only three files.
+
+## When to Use
+
+✅ **Good for**:
+- Any feature size
+- Fast iterations
+- High test coverage needs
+- Wanting concurrent speed-up
+
+## Design Principles
+
+1. **KISS**: keep it simple
+2. **Disposable**: no persistent config
+3. **Quality first**: enforce 90% coverage
+4. **Concurrency first**: leverage codeagent
+5. **No legacy baggage**: clean-slate design
+
+---
+
+**Philosophy**: zero tolerance for complexity—ship the smallest usable solution, like Linus would.

dev-workflow/agents/dev-plan-generator.md

@@ -0,0 +1,114 @@
+---
+name: dev-plan-generator
+description: Use this agent when you need to generate a structured development plan document (`dev-plan.md`) that breaks down a feature into concrete implementation tasks with testing requirements and acceptance criteria. This agent should be called after requirements analysis and before actual implementation begins.\n\n<example>\nContext: User is orchestrating a feature development workflow and needs to create a development plan after codeagent analysis is complete.\nuser: "Create a development plan for the user authentication feature based on the requirements and analysis"\nassistant: "I'll use the Task tool to launch the dev-plan-generator agent to create the structured development plan document."\n<commentary>\nThe user needs a dev-plan.md document generated from requirements and analysis. Use the dev-plan-generator agent to create the structured task breakdown.\n</commentary>\n</example>\n\n<example>\nContext: Orchestrator has completed requirements gathering and codeagent analysis for a new feature and needs to generate the development plan before moving to implementation.\nuser: "We've completed the analysis for the payment integration feature. Generate the development plan."\nassistant: "I'm going to use the Task tool to launch the dev-plan-generator agent to create the dev-plan.md document with task breakdown and testing requirements."\n<commentary>\nThis is the step in the workflow where the development plan document needs to be generated. Use the dev-plan-generator agent to create the structured plan.\n</commentary>\n</example>\n\n<example>\nContext: User is working through a requirements-driven workflow and has just approved the technical specifications.\nuser: "The specs look good. Let's move forward with creating the implementation plan."\nassistant: "I'll use the Task tool to launch the dev-plan-generator agent to generate the dev-plan.md document with the task breakdown."\n<commentary>\nAfter spec approval, the next step is generating the development plan. Use the dev-plan-generator agent to create the structured document.\n</commentary>\n</example>
+tools: Glob, Grep, Read, Edit, Write, TodoWrite
+model: sonnet
+color: green
+---
+
+You are a specialized Development Plan Document Generator. Your sole responsibility is to create structured, actionable development plan documents (`dev-plan.md`) that break down features into concrete implementation tasks.
+
+## Your Role
+
+You receive context from an orchestrator including:
+- Feature requirements description
+- codeagent analysis results (feature highlights, task decomposition, UI detection flag)
+- Feature name (in kebab-case format)
+
+Your output is a single file: `./.claude/specs/{feature_name}/dev-plan.md`
+
+## Document Structure You Must Follow
+
+```markdown
+# {Feature Name} - Development Plan
+
+## Overview
+[One-sentence description of core functionality]
+
+## Task Breakdown
+
+### Task 1: [Task Name]
+- **ID**: task-1
+- **Description**: [What needs to be done]
+- **File Scope**: [Directories or files involved, e.g., src/auth/**, tests/auth/]
+- **Dependencies**: [None or depends on task-x]
+- **Test Command**: [e.g., pytest tests/auth --cov=src/auth --cov-report=term]
+- **Test Focus**: [Scenarios to cover]
+
+### Task 2: [Task Name]
+...
+
+(2-5 tasks)
+
+## Acceptance Criteria
+- [ ] Feature point 1
+- [ ] Feature point 2
+- [ ] All unit tests pass
+- [ ] Code coverage ≥90%
+
+## Technical Notes
+- [Key technical decisions]
+- [Constraints to be aware of]
+```
+
+## Generation Rules You Must Enforce
+
+1. **Task Count**: Generate 2-5 tasks (no more, no less unless the feature is extremely simple or complex)
+2. **Task Requirements**: Each task MUST include:
+   - Clear ID (task-1, task-2, etc.)
+   - Specific description of what needs to be done
+   - Explicit file scope (directories or files affected)
+   - Dependency declaration ("None" or "depends on task-x")
+   - Complete test command with coverage parameters
+   - Testing focus points (scenarios to cover)
+3. **Task Independence**: Design tasks to be as independent as possible to enable parallel execution
+4. **Test Commands**: Must include coverage parameters (e.g., `--cov=module --cov-report=term` for pytest, `--coverage` for npm)
+5. **Coverage Threshold**: Always require ≥90% code coverage in acceptance criteria
+
+## Your Workflow
+
+1. **Analyze Input**: Review the requirements description and codeagent analysis results (including `needs_ui` flag if present)
+2. **Identify Tasks**: Break down the feature into 2-5 logical, independent tasks
+3. **Determine Dependencies**: Map out which tasks depend on others (minimize dependencies)
+4. **Specify Testing**: For each task, define the exact test command and coverage requirements
+5. **Define Acceptance**: List concrete, measurable acceptance criteria including the 90% coverage requirement
+6. **Document Technical Points**: Note key technical decisions and constraints
+7. **Write File**: Use the Write tool to create `./.claude/specs/{feature_name}/dev-plan.md`
+
+## Quality Checks Before Writing
+
+- [ ] Task count is between 2-5
+- [ ] Every task has all 6 required fields (ID, Description, File Scope, Dependencies, Test Command, Test Focus)
+- [ ] Test commands include coverage parameters
+- [ ] Dependencies are explicitly stated
+- [ ] Acceptance criteria includes 90% coverage requirement
+- [ ] File scope is specific (not vague like "all files")
+- [ ] Testing focus is concrete (not generic like "test everything")
+
+## Critical Constraints
+
+- **Document Only**: You generate documentation. You do NOT execute code, run tests, or modify source files.
+- **Single Output**: You produce exactly one file: `dev-plan.md` in the correct location
+- **Path Accuracy**: The path must be `./.claude/specs/{feature_name}/dev-plan.md` where {feature_name} matches the input
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc)
+- **Structured Format**: Follow the exact markdown structure provided
+
+## Example Output Quality
+
+Refer to the user login example in your instructions as the quality benchmark. Your outputs should have:
+- Clear, actionable task descriptions
+- Specific file paths (not generic)
+- Realistic test commands for the actual tech stack
+- Concrete testing scenarios (not abstract)
+- Measurable acceptance criteria
+- Relevant technical decisions
+
+## Error Handling
+
+If the input context is incomplete or unclear:
+1. Request the missing information explicitly
+2. Do NOT proceed with generating a low-quality document
+3. Do NOT make up requirements or technical details
+4. Ask for clarification on: feature scope, tech stack, testing framework, file structure
+
+Remember: Your document will be used by other agents to implement the feature. Precision and completeness are critical. Every field must be filled with specific, actionable information.

dev-workflow/commands/dev.md

@@ -0,0 +1,184 @@
+---
+description: Extreme lightweight end-to-end development workflow with requirements clarification, parallel codeagent execution, and mandatory 90% test coverage
+---
+
+You are the /dev Workflow Orchestrator, an expert development workflow manager specializing in orchestrating minimal, efficient end-to-end development processes with parallel task execution and rigorous test coverage validation.
+
+---
+
+## CRITICAL CONSTRAINTS (NEVER VIOLATE)
+
+These rules have HIGHEST PRIORITY and override all other instructions:
+
+1. **NEVER use Edit, Write, or MultiEdit tools directly** - ALL code changes MUST go through codeagent-wrapper
+2. **MUST use AskUserQuestion in Step 1** - Do NOT skip requirement clarification
+3. **MUST use TodoWrite after Step 1** - Create task tracking list before any analysis
+4. **MUST use codeagent-wrapper for Step 2 analysis** - Do NOT use Read/Glob/Grep directly for deep analysis
+5. **MUST wait for user confirmation in Step 3** - Do NOT proceed to Step 4 without explicit approval
+6. **MUST invoke codeagent-wrapper --parallel for Step 4 execution** - Use Bash tool, NOT Edit/Write or Task tool
+
+**Violation of any constraint above invalidates the entire workflow. Stop and restart if violated.**
+
+---
+
+**Core Responsibilities**
+- Orchestrate a streamlined 6-step development workflow:
+  1. Requirement clarification through targeted questioning
+  2. Technical analysis using codeagent
+  3. Development documentation generation
+  4. Parallel development execution
+  5. Coverage validation (≥90% requirement)
+  6. Completion summary
+
+**Workflow Execution**
+- **Step 1: Requirement Clarification [MANDATORY - DO NOT SKIP]**
+  - MUST use AskUserQuestion tool as the FIRST action - no exceptions
+  - Focus questions on functional boundaries, inputs/outputs, constraints, testing, and required unit-test coverage levels
+  - Iterate 2-3 rounds until clear; rely on judgment; keep questions concise
+  - After clarification complete: MUST use TodoWrite to create task tracking list with workflow steps
+
+- **Step 2: codeagent-wrapper Deep Analysis (Plan Mode Style) [USE CODEAGENT-WRAPPER ONLY]**
+
+  MUST use Bash tool to invoke `codeagent-wrapper` for deep analysis. Do NOT use Read/Glob/Grep tools directly - delegate all exploration to codeagent-wrapper.
+
+  **How to invoke for analysis**:
+  ```bash
+  codeagent-wrapper --backend codex - <<'EOF'
+  Analyze the codebase for implementing [feature name].
+
+  Requirements:
+  - [requirement 1]
+  - [requirement 2]
+
+  Deliverables:
+  1. Explore codebase structure and existing patterns
+  2. Evaluate implementation options with trade-offs
+  3. Make architectural decisions
+  4. Break down into 2-5 parallelizable tasks with dependencies
+  5. Determine if UI work is needed (check for .css/.tsx/.vue files)
+
+  Output the analysis following the structure below.
+  EOF
+  ```
+
+  **When Deep Analysis is Needed** (any condition triggers):
+  - Multiple valid approaches exist (e.g., Redis vs in-memory vs file-based caching)
+  - Significant architectural decisions required (e.g., WebSockets vs SSE vs polling)
+  - Large-scale changes touching many files or systems
+  - Unclear scope requiring exploration first
+
+  **UI Detection Requirements**:
+  - During analysis, output whether the task needs UI work (yes/no) and the evidence
+  - UI criteria: presence of style assets (.css, .scss, styled-components, CSS modules, tailwindcss) OR frontend component files (.tsx, .jsx, .vue)
+
+  **What the AI backend does in Analysis Mode** (when invoked via codeagent-wrapper):
+  1. **Explore Codebase**: Use Glob, Grep, Read to understand structure, patterns, architecture
+  2. **Identify Existing Patterns**: Find how similar features are implemented, reuse conventions
+  3. **Evaluate Options**: When multiple approaches exist, list trade-offs (complexity, performance, security, maintainability)
+  4. **Make Architectural Decisions**: Choose patterns, APIs, data models with justification
+  5. **Design Task Breakdown**: Produce 2-5 parallelizable tasks with file scope and dependencies
+
+  **Analysis Output Structure**:
+  ```
+  ## Context & Constraints
+  [Tech stack, existing patterns, constraints discovered]
+
+  ## Codebase Exploration
+  [Key files, modules, patterns found via Glob/Grep/Read]
+
+  ## Implementation Options (if multiple approaches)
+  | Option | Pros | Cons | Recommendation |
+
+  ## Technical Decisions
+  [API design, data models, architecture choices made]
+
+  ## Task Breakdown
+  [2-5 tasks with: ID, description, file scope, dependencies, test command]
+
+  ## UI Determination
+  needs_ui: [true/false]
+  evidence: [files and reasoning tied to style + component criteria]
+  ```
+
+  **Skip Deep Analysis When**:
+  - Simple, straightforward implementation with obvious approach
+  - Small changes confined to 1-2 files
+  - Clear requirements with single implementation path
+
+- **Step 3: Generate Development Documentation**
+  - invoke agent dev-plan-generator
+  - When creating `dev-plan.md`, append a dedicated UI task if Step 2 marked `needs_ui: true`
+  - Output a brief summary of dev-plan.md:
+    - Number of tasks and their IDs
+    - File scope for each task
+    - Dependencies between tasks
+    - Test commands
+  - Use AskUserQuestion to confirm with user:
+    - Question: "Proceed with this development plan?" (if UI work is detected, state that UI tasks will use the gemini backend)
+    - Options: "Confirm and execute" / "Need adjustments"
+  - If user chooses "Need adjustments", return to Step 1 or Step 2 based on feedback
+
+- **Step 4: Parallel Development Execution [CODEAGENT-WRAPPER ONLY - NO DIRECT EDITS]**
+  - MUST use Bash tool to invoke `codeagent-wrapper --parallel` for ALL code changes
+  - NEVER use Edit, Write, MultiEdit, or Task tools to modify code directly
+  - Build ONE `--parallel` config that includes all tasks in `dev-plan.md` and submit it once via Bash tool:
+    ```bash
+    # One shot submission - wrapper handles topology + concurrency
+    codeagent-wrapper --parallel <<'EOF'
+    ---TASK---
+    id: [task-id-1]
+    backend: codex
+    workdir: .
+    dependencies: [optional, comma-separated ids]
+    ---CONTENT---
+    Task: [task-id-1]
+    Reference: @.claude/specs/{feature_name}/dev-plan.md
+    Scope: [task file scope]
+    Test: [test command]
+    Deliverables: code + unit tests + coverage ≥90% + coverage summary
+
+    ---TASK---
+    id: [task-id-2]
+    backend: gemini
+    workdir: .
+    dependencies: [optional, comma-separated ids]
+    ---CONTENT---
+    Task: [task-id-2]
+    Reference: @.claude/specs/{feature_name}/dev-plan.md
+    Scope: [task file scope]
+    Test: [test command]
+    Deliverables: code + unit tests + coverage ≥90% + coverage summary
+    EOF
+    ```
+  - **Note**: Use `workdir: .` (current directory) for all tasks unless specific subdirectory is required
+  - Execute independent tasks concurrently; serialize conflicting ones; track coverage reports
+
+- **Step 5: Coverage Validation**
+  - Validate each task’s coverage:
+    - All ≥90% → pass
+    - Any <90% → request more tests (max 2 rounds)
+
+- **Step 6: Completion Summary**
+  - Provide completed task list, coverage per task, key file changes
+
+**Error Handling**
+- **codeagent-wrapper failure**: Retry once with same input; if still fails, log error and ask user for guidance
+- **Insufficient coverage (<90%)**: Request more tests from the failed task (max 2 rounds); if still fails, report to user
+- **Dependency conflicts**:
+  - Circular dependencies: codeagent-wrapper will detect and fail with error; revise task breakdown to remove cycles
+  - Missing dependencies: Ensure all task IDs referenced in `dependencies` field exist
+- **Parallel execution timeout**: Individual tasks timeout after 2 hours (configurable via CODEX_TIMEOUT); failed tasks can be retried individually
+- **Backend unavailable**: If codex/claude/gemini CLI not found, fail immediately with clear error message
+
+**Quality Standards**
+- Code coverage ≥90%
+- 2-5 genuinely parallelizable tasks
+- Documentation must be minimal yet actionable
+- No verbose implementations; only essential code
+
+**Communication Style**
+- Be direct and concise
+- Report progress at each workflow step
+- Highlight blockers immediately
+- Provide actionable next steps when coverage fails
+- Prioritize speed via parallelization while enforcing coverage validation

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

docs/BMAD-WORKFLOW.md

@@ -0,0 +1,258 @@
+# BMAD Workflow Complete Guide
+
+> **BMAD (Business-Minded Agile Development)** - AI-driven agile development automation with role-based agents
+
+## 🎯 What is BMAD?
+
+BMAD is an enterprise-grade agile development methodology that transforms your development process into a fully automated workflow with 6 specialized AI agents and quality gates.
+
+### Core Principles
+
+- **Agent Planning**: Specialized agents collaborate to create detailed, consistent PRDs and architecture documents
+- **Context-Driven Development**: Transform detailed plans into ultra-detailed development stories
+- **Role Specialization**: Each agent focuses on specific domains, avoiding quality degradation from role switching
+
+## 🤖 BMAD Agent System
+
+### Agent Roles
+
+| Agent | Role | Quality Gate | Artifacts |
+|-------|------|--------------|-----------|
+| **bmad-po** (Sarah) | Product Owner - requirements gathering, user stories | PRD ≥ 90/100 | `01-product-requirements.md` |
+| **bmad-architect** (Winston) | System Architect - technical design, system architecture | Design ≥ 90/100 | `02-system-architecture.md` |
+| **bmad-sm** (Mike) | Scrum Master - task breakdown, sprint planning | User approval | `03-sprint-plan.md` |
+| **bmad-dev** (Alex) | Developer - code implementation, technical docs | Code completion | Implementation files |
+| **bmad-review** | Code Reviewer - independent review between Dev and QA | Pass/Risk/Fail | `04-dev-reviewed.md` |
+| **bmad-qa** (Emma) | QA Engineer - testing strategy, quality assurance | Test execution | `05-qa-report.md` |
+
+## 🚀 Quick Start
+
+### Command Overview
+
+```bash
+# Full BMAD workflow
+/bmad-pilot "Build e-commerce checkout system with payment integration"
+
+# Workflow: PO → Architect → SM → Dev → Review → QA
+```
+
+### Command Options
+
+```bash
+# Skip testing phase
+/bmad-pilot "Admin dashboard" --skip-tests
+
+# Skip sprint planning (architecture → dev directly)
+/bmad-pilot "API gateway implementation" --direct-dev
+
+# Skip repository scan (not recommended)
+/bmad-pilot "Add feature" --skip-scan
+```
+
+### Individual Agent Usage
+
+```bash
+# Product requirements analysis only
+/bmad-po "Enterprise CRM system requirements"
+
+# Technical architecture design only
+/bmad-architect "High-concurrency distributed system design"
+
+# Orchestrator (can transform into any agent)
+/bmad-orchestrator "Coordinate multi-agent complex project"
+```
+
+## 📋 Workflow Phases
+
+### Phase 0: Repository Scan (Automatic)
+- **Agent**: `bmad-orchestrator`
+- **Output**: `00-repository-context.md`
+- **Content**: Project type, tech stack, code organization, conventions, integration points
+
+### Phase 1: Product Requirements (PO)
+- **Agent**: `bmad-po` (Sarah - Product Owner)
+- **Quality Gate**: PRD score ≥ 90/100
+- **Output**: `01-product-requirements.md`
+- **Process**:
+  1. PO generates initial PRD
+  2. System calculates quality score (100-point scale)
+  3. If < 90: User provides feedback → PO revises → Recalculate
+  4. If ≥ 90: User confirms → Save artifact → Next phase
+
+### Phase 2: System Architecture (Architect)
+- **Agent**: `bmad-architect` (Winston - System Architect)
+- **Quality Gate**: Design score ≥ 90/100
+- **Output**: `02-system-architecture.md`
+- **Process**:
+  1. Architect reads PRD + repo context
+  2. Generates technical design document
+  3. System calculates design quality score
+  4. If < 90: User provides feedback → Architect revises
+  5. If ≥ 90: User confirms → Save artifact → Next phase
+
+### Phase 3: Sprint Planning (SM)
+- **Agent**: `bmad-sm` (Mike - Scrum Master)
+- **Quality Gate**: User approval
+- **Output**: `03-sprint-plan.md`
+- **Process**:
+  1. SM reads PRD + Architecture
+  2. Breaks down tasks with story points
+  3. User reviews sprint plan
+  4. User confirms → Save artifact → Next phase
+- **Skip**: Use `--direct-dev` to skip this phase
+
+### Phase 4: Development (Dev)
+- **Agent**: `bmad-dev` (Alex - Developer)
+- **Quality Gate**: Code completion
+- **Output**: Implementation files
+- **Process**:
+  1. Dev reads all previous artifacts
+  2. Implements features following sprint plan
+  3. Creates or modifies code files
+  4. Completes implementation → Next phase
+
+### Phase 5: Code Review (Review)
+- **Agent**: `bmad-review` (Independent Reviewer)
+- **Quality Gate**: Pass / Pass with Risk / Fail
+- **Output**: `04-dev-reviewed.md`
+- **Process**:
+  1. Review reads implementation + all specs
+  2. Performs comprehensive code review
+  3. Generates review report with status:
+     - **Pass**: No issues, proceed to QA
+     - **Pass with Risk**: Non-critical issues noted
+     - **Fail**: Critical issues, return to Dev
+  4. Updates sprint plan with review findings
+
+**Enhanced Review (Optional)**:
+- Use GPT-5 via Codex CLI for deeper analysis
+- Set via `BMAD_REVIEW_MODE=enhanced` environment variable
+
+### Phase 6: Quality Assurance (QA)
+- **Agent**: `bmad-qa` (Emma - QA Engineer)
+- **Quality Gate**: Test execution
+- **Output**: `05-qa-report.md`
+- **Process**:
+  1. QA reads implementation + review + all specs
+  2. Creates targeted test strategy
+  3. Executes tests
+  4. Generates QA report
+  5. Workflow complete
+- **Skip**: Use `--skip-tests` to skip this phase
+
+## 📊 Quality Scoring System
+
+### PRD Quality (100 points)
+- **Business Value** (30): Clear value proposition, user benefits
+- **Functional Requirements** (25): Complete, unambiguous requirements
+- **User Experience** (20): User flows, interaction patterns
+- **Technical Constraints** (15): Performance, security, scalability
+- **Scope & Priorities** (10): Clear boundaries, must-have vs nice-to-have
+
+### Architecture Quality (100 points)
+- **Design Quality** (30): Modularity, maintainability, clarity
+- **Technology Selection** (25): Appropriate tech stack, justification
+- **Scalability** (20): Growth handling, performance considerations
+- **Security** (15): Authentication, authorization, data protection
+- **Feasibility** (10): Realistic implementation, resource alignment
+
+### Review Status (3 levels)
+- **Pass**: No critical issues, code meets standards
+- **Pass with Risk**: Non-critical issues, recommendations included
+- **Fail**: Critical issues, requires Dev iteration
+
+## 📁 Workflow Artifacts
+
+All documents are saved to `.claude/specs/{feature-name}/`:
+
+```
+.claude/specs/e-commerce-checkout/
+├── 00-repository-context.md    # Repo analysis (auto)
+├── 01-product-requirements.md  # PRD (PO, score ≥ 90)
+├── 02-system-architecture.md   # Design (Architect, score ≥ 90)
+├── 03-sprint-plan.md           # Sprint plan (SM, user approved)
+├── 04-dev-reviewed.md          # Code review (Review, Pass/Risk/Fail)
+└── 05-qa-report.md            # Test report (QA, tests executed)
+```
+
+Feature name generated from project description (kebab-case: lowercase, spaces/punctuation → `-`).
+
+## 🔧 Advanced Usage
+
+### Approval Gates
+
+Critical phases require explicit user confirmation:
+
+```
+Architect: "Technical design complete (Score: 93/100)"
+System: "Ready to proceed to sprint planning? (yes/no)"
+User: yes
+```
+
+### Iterative Refinement
+
+Each phase supports feedback loops:
+
+```
+PO: "Here's the PRD (Score: 75/100)"
+User: "Add mobile support and offline mode"
+PO: "Updated PRD (Score: 92/100) ✅"
+```
+
+### Repository Context
+
+BMAD automatically scans your repository to understand:
+- Technology stack (languages, frameworks, libraries)
+- Project structure (directories, modules, patterns)
+- Existing conventions (naming, formatting, architecture)
+- Dependencies (package managers, external services)
+- Integration points (APIs, databases, third-party services)
+
+### Workflow Variations
+
+**Fast Prototyping** - Skip non-essential phases:
+```bash
+/bmad-pilot "Quick admin UI" --skip-tests --direct-dev
+# Workflow: PO → Architect → Dev
+```
+
+**Architecture-First** - Focus on design:
+```bash
+/bmad-architect "Microservices architecture for e-commerce"
+# Only runs Architect agent
+```
+
+**Full Rigor** - All phases with maximum quality:
+```bash
+/bmad-pilot "Enterprise payment gateway with PCI compliance"
+# Workflow: Scan → PO → Architect → SM → Dev → Review → QA
+```
+
+## 🎨 Output Style
+
+BMAD workflow uses a specialized output style that:
+- Creates phase-separated contexts
+- Manages agent handoffs with clear boundaries
+- Tracks quality scores across phases
+- Handles approval gates with user prompts
+- Supports Codex CLI integration for enhanced reviews
+
+## 📚 Related Documentation
+
+- **[Quick Start Guide](QUICK-START.md)** - Get started in 5 minutes
+- **[Plugin System](PLUGIN-SYSTEM.md)** - Installation and configuration
+- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Alternative workflows
+- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight alternative
+
+## 💡 Best Practices
+
+1. **Don't skip repository scan** - Helps agents understand your project context
+2. **Provide detailed descriptions** - Better input → better output
+3. **Engage with agents** - Provide feedback during quality gates
+4. **Review artifacts** - Check generated documents before confirming
+5. **Use appropriate workflows** - Full BMAD for complex features, lightweight for simple tasks
+6. **Keep artifacts** - They serve as project documentation and context for future work
+
+---
+
+**Transform your development with BMAD** - One command, complete agile workflow, quality assured.

docs/CODEAGENT-WRAPPER.md

@@ -0,0 +1,407 @@
+# Codeagent-Wrapper User Guide
+
+Multi-backend AI code execution wrapper supporting Codex, Claude, and Gemini.
+
+## Overview
+
+`codeagent-wrapper` is a Go-based CLI tool that provides a unified interface to multiple AI coding backends. It handles:
+- Multi-backend execution (Codex, Claude, Gemini)
+- JSON stream parsing and output formatting
+- Session management and resumption
+- Parallel task execution with dependency resolution
+- Timeout handling and signal forwarding
+
+## Installation
+
+```bash
+# Clone repository
+git clone https://github.com/cexll/myclaude.git
+cd myclaude
+
+# Install via install.py (includes binary compilation)
+python3 install.py --module dev
+
+# Or manual installation
+cd codeagent-wrapper
+go build -o ~/.claude/bin/codeagent-wrapper
+```
+
+## Quick Start
+
+### Basic Usage
+
+```bash
+# Simple task (default: codex backend)
+codeagent-wrapper "explain @src/main.go"
+
+# With backend selection
+codeagent-wrapper --backend claude "refactor @utils.ts"
+
+# With HEREDOC (recommended for complex tasks)
+codeagent-wrapper --backend gemini - <<'EOF'
+Implement user authentication:
+- JWT tokens
+- Password hashing with bcrypt
+- Session management
+EOF
+```
+
+### Backend Selection
+
+| Backend | Command | Best For |
+|---------|---------|----------|
+| **Codex** | `--backend codex` | General code tasks (default) |
+| **Claude** | `--backend claude` | Complex reasoning, architecture |
+| **Gemini** | `--backend gemini` | Fast iteration, prototyping |
+
+## Core Features
+
+### 1. Multi-Backend Support
+
+```bash
+# Codex (default)
+codeagent-wrapper "add logging to @app.js"
+
+# Claude for architecture decisions
+codeagent-wrapper --backend claude - <<'EOF'
+Design a microservices architecture for e-commerce:
+- Service boundaries
+- Communication patterns
+- Data consistency strategy
+EOF
+
+# Gemini for quick prototypes
+codeagent-wrapper --backend gemini "create React component for user profile"
+```
+
+### 2. File References with @ Syntax
+
+```bash
+# Single file
+codeagent-wrapper "optimize @src/utils.ts"
+
+# Multiple files
+codeagent-wrapper "refactor @src/auth.ts and @src/middleware.ts"
+
+# Entire directory
+codeagent-wrapper "analyze @src for security issues"
+```
+
+### 3. Session Management
+
+```bash
+# First task
+codeagent-wrapper "add validation to user form"
+# Output includes: SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
+
+# Resume session
+codeagent-wrapper resume 019a7247-ac9d-71f3-89e2-a823dbd8fd14 - <<'EOF'
+Now add error messages for each validation rule
+EOF
+```
+
+### 4. Parallel Execution
+
+Execute multiple tasks concurrently with dependency management:
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: backend_1701234567
+workdir: /project/backend
+---CONTENT---
+implement /api/users endpoints with CRUD operations
+
+---TASK---
+id: frontend_1701234568
+workdir: /project/frontend
+---CONTENT---
+build Users page consuming /api/users
+
+---TASK---
+id: tests_1701234569
+workdir: /project/tests
+dependencies: backend_1701234567, frontend_1701234568
+---CONTENT---
+add integration tests for user management flow
+EOF
+```
+
+**Parallel Task Format:**
+- `---TASK---` - Starts task block
+- `id: <unique_id>` - Required, use `<feature>_<timestamp>` format
+- `workdir: <path>` - Optional, defaults to current directory
+- `dependencies: <id1>, <id2>` - Optional, comma-separated task IDs
+- `---CONTENT---` - Separates metadata from task content
+
+**Features:**
+- Automatic topological sorting
+- Unlimited concurrency for independent tasks
+- Error isolation (failures don't stop other tasks)
+- Dependency blocking (skip if parent fails)
+
+### 5. Working Directory
+
+```bash
+# Execute in specific directory
+codeagent-wrapper "run tests" /path/to/project
+
+# With backend selection
+codeagent-wrapper --backend claude "analyze code" /project/backend
+
+# With HEREDOC
+codeagent-wrapper - /path/to/project <<'EOF'
+refactor database layer
+EOF
+```
+
+## Advanced Usage
+
+### Timeout Control
+
+```bash
+# Set custom timeout (1 hour = 3600000ms)
+CODEX_TIMEOUT=3600000 codeagent-wrapper "long running task"
+
+# Default timeout: 7200000ms (2 hours)
+```
+
+**Timeout behavior:**
+- Sends SIGTERM to backend process
+- Waits 5 seconds
+- Sends SIGKILL if process doesn't exit
+- Returns exit code 124 (consistent with GNU timeout)
+
+### Complex Multi-line Tasks
+
+Use HEREDOC to avoid shell escaping issues:
+
+```bash
+codeagent-wrapper - <<'EOF'
+Refactor authentication system:
+
+Current issues:
+- Password stored as plain text
+- No rate limiting on login
+- Sessions don't expire
+
+Requirements:
+1. Hash passwords with bcrypt
+2. Add rate limiting (5 attempts/15min)
+3. Session expiry after 24h
+4. Add refresh token mechanism
+
+Files to modify:
+- @src/auth/login.ts
+- @src/middleware/rateLimit.ts
+- @config/session.ts
+EOF
+```
+
+### Backend-Specific Features
+
+**Codex:**
+```bash
+# Best for code editing and refactoring
+codeagent-wrapper --backend codex - <<'EOF'
+extract duplicate code in @src into reusable helpers
+EOF
+```
+
+**Claude:**
+```bash
+# Best for complex reasoning
+codeagent-wrapper --backend claude - <<'EOF'
+review @src/payment/processor.ts for:
+- Race conditions
+- Edge cases
+- Security vulnerabilities
+EOF
+```
+
+**Gemini:**
+```bash
+# Best for fast iteration
+codeagent-wrapper --backend gemini "add TypeScript types to @api.js"
+```
+
+## Output Format
+
+Standard output includes parsed agent messages and session ID:
+
+```
+Agent response text here...
+Implementation details...
+
+---
+SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
+```
+
+Error output (stderr):
+```
+ERROR: Error message details
+```
+
+Parallel execution output:
+```
+=== Parallel Execution Summary ===
+Total: 3 | Success: 2 | Failed: 1
+
+--- Task: backend_1701234567 ---
+Status: SUCCESS
+Session: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
+
+Implementation complete...
+
+--- Task: frontend_1701234568 ---
+Status: SUCCESS
+Session: 019a7248-ac9d-71f3-89e2-a823dbd8fd14
+
+UI components created...
+
+--- Task: tests_1701234569 ---
+Status: FAILED (exit code 1)
+Error: dependency backend_1701234567 failed
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error (missing args, no output) |
+| 124 | Timeout |
+| 127 | Backend command not found |
+| 130 | Interrupted (Ctrl+C) |
+| * | Passthrough from backend process |
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CODEX_TIMEOUT` | 7200000 | Timeout in milliseconds |
+
+## Troubleshooting
+
+**Backend not found:**
+```bash
+# Ensure backend CLI is installed
+which codex
+which claude
+which gemini
+
+# Check PATH
+echo $PATH
+```
+
+**Timeout too short:**
+```bash
+# Increase timeout to 4 hours
+CODEX_TIMEOUT=14400000 codeagent-wrapper "complex task"
+```
+
+**Session ID not found:**
+```bash
+# List recent sessions (backend-specific)
+codex history
+
+# Ensure session ID is copied correctly
+codeagent-wrapper resume <session_id> "continue task"
+```
+
+**Parallel tasks not running:**
+```bash
+# Check task format
+# Ensure ---TASK--- and ---CONTENT--- delimiters are correct
+# Verify task IDs are unique
+# Check dependencies reference existing task IDs
+```
+
+## Integration with Claude Code
+
+Use via the `codeagent` skill:
+
+```bash
+# In Claude Code conversation
+User: Use codeagent to implement authentication
+
+# Claude will execute:
+codeagent-wrapper --backend codex - <<'EOF'
+implement JWT authentication in @src/auth
+EOF
+```
+
+## Performance Tips
+
+1. **Use parallel execution** for independent tasks
+2. **Choose the right backend** for the task type
+3. **Keep working directory specific** to reduce context
+4. **Resume sessions** for multi-step workflows
+5. **Use @ syntax** to minimize file content in prompts
+
+## Best Practices
+
+1. **HEREDOC for complex tasks** - Avoid shell escaping nightmares
+2. **Descriptive task IDs** - Use `<feature>_<timestamp>` format
+3. **Absolute paths** - Avoid relative path confusion
+4. **Session resumption** - Continue conversations with context
+5. **Timeout tuning** - Set appropriate timeouts for task complexity
+
+## Examples
+
+### Example 1: Code Review
+
+```bash
+codeagent-wrapper --backend claude - <<'EOF'
+Review @src/payment/stripe.ts for:
+1. Security issues (API key handling, input validation)
+2. Error handling (network failures, API errors)
+3. Edge cases (duplicate charges, partial refunds)
+4. Code quality (naming, structure, comments)
+EOF
+```
+
+### Example 2: Refactoring
+
+```bash
+codeagent-wrapper --backend codex - <<'EOF'
+Refactor @src/utils:
+- Extract duplicate code into helpers
+- Add TypeScript types
+- Improve function naming
+- Add JSDoc comments
+EOF
+```
+
+### Example 3: Full-Stack Feature
+
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: api_1701234567
+workdir: /project/backend
+---CONTENT---
+implement /api/notifications endpoints with WebSocket support
+
+---TASK---
+id: ui_1701234568
+workdir: /project/frontend
+dependencies: api_1701234567
+---CONTENT---
+build Notifications component with real-time updates
+
+---TASK---
+id: tests_1701234569
+workdir: /project
+dependencies: api_1701234567, ui_1701234568
+---CONTENT---
+add E2E tests for notification flow
+EOF
+```
+
+## Further Reading
+
+- [Codex CLI Documentation](https://codex.docs)
+- [Claude CLI Documentation](https://claude.ai/docs)
+- [Gemini CLI Documentation](https://ai.google.dev/docs)
+- [Architecture Overview](./architecture.md)

docs/DEVELOPMENT-COMMANDS.md

@@ -0,0 +1,321 @@
+# Development Commands Reference
+
+> Direct slash commands for daily coding tasks without workflow overhead
+
+## 🎯 Overview
+
+Development Essentials provides focused slash commands for common development tasks. Use these when you need direct implementation without the full workflow structure.
+
+## 📋 Available Commands
+
+### `/code` - Direct Implementation
+
+Implement features, add functionality, or write code directly.
+
+**Usage**:
+```bash
+/code "Add input validation for email fields"
+/code "Implement pagination for user list API"
+/code "Create database migration for orders table"
+```
+
+**Agent**: `code`
+
+**Best for**:
+- Clear, well-defined tasks
+- Quick implementations
+- Following existing patterns
+- Adding straightforward features
+
+### `/debug` - Systematic Debugging
+
+Analyze and fix bugs with structured debugging approach.
+
+**Usage**:
+```bash
+/debug "Login fails with 500 error on invalid credentials"
+/debug "Memory leak in background worker process"
+/debug "Race condition in order processing"
+```
+
+**Agent**: `debug`
+
+**Approach**:
+1. Reproduce the issue
+2. Analyze root cause
+3. Propose solution
+4. Implement fix
+5. Verify resolution
+
+### `/test` - Testing Strategy
+
+Create tests, improve test coverage, or test existing code.
+
+**Usage**:
+```bash
+/test "Add unit tests for authentication service"
+/test "Create integration tests for payment flow"
+/test "Test edge cases for date parser"
+```
+
+**Agent**: `develop` (testing mode)
+
+**Covers**:
+- Unit tests
+- Integration tests
+- Edge cases
+- Error scenarios
+- Test data setup
+
+### `/optimize` - Performance Tuning
+
+Improve performance, reduce resource usage, or optimize algorithms.
+
+**Usage**:
+```bash
+/optimize "Reduce database queries in dashboard endpoint"
+/optimize "Speed up report generation process"
+/optimize "Improve memory usage in data processing pipeline"
+```
+
+**Agent**: `develop` (optimization mode)
+
+**Focus areas**:
+- Algorithm efficiency
+- Database query optimization
+- Caching strategies
+- Resource utilization
+- Load time reduction
+
+### `/bugfix` - Bug Resolution
+
+Fix specific bugs with focused approach.
+
+**Usage**:
+```bash
+/bugfix "Users can't reset password with special characters"
+/bugfix "Session expires too quickly on mobile"
+/bugfix "File upload fails for large files"
+```
+
+**Agent**: `bugfix`
+
+**Process**:
+1. Understand the bug
+2. Locate problematic code
+3. Implement fix
+4. Add regression tests
+5. Verify fix
+
+### `/refactor` - Code Improvement
+
+Improve code structure, readability, or maintainability without changing behavior.
+
+**Usage**:
+```bash
+/refactor "Extract user validation logic into separate module"
+/refactor "Simplify nested conditionals in order processing"
+/refactor "Remove code duplication in API handlers"
+```
+
+**Agent**: `develop` (refactor mode)
+
+**Goals**:
+- Improve readability
+- Reduce complexity
+- Eliminate duplication
+- Enhance maintainability
+- Follow best practices
+
+### `/review` - Code Validation
+
+Review code for quality, security, and best practices.
+
+**Usage**:
+```bash
+/review "Check authentication implementation for security issues"
+/review "Validate API error handling patterns"
+/review "Assess database schema design"
+```
+
+**Agent**: Independent reviewer
+
+**Review criteria**:
+- Code quality
+- Security vulnerabilities
+- Performance issues
+- Best practices compliance
+- Maintainability
+
+### `/ask` - Technical Consultation
+
+Get technical advice, design patterns, or implementation guidance.
+
+**Usage**:
+```bash
+/ask "Best approach for real-time notifications in React"
+/ask "How to handle database migrations in production"
+/ask "Design pattern for plugin system"
+```
+
+**Agent**: Technical consultant
+
+**Provides**:
+- Architecture guidance
+- Technology recommendations
+- Design patterns
+- Best practices
+- Trade-off analysis
+
+### `/docs` - Documentation
+
+Generate or improve documentation.
+
+**Usage**:
+```bash
+/docs "Create API documentation for user endpoints"
+/docs "Add JSDoc comments to utility functions"
+/docs "Write README for authentication module"
+```
+
+**Agent**: Documentation writer
+
+**Creates**:
+- Code comments
+- API documentation
+- README files
+- Usage examples
+- Architecture docs
+
+### `/think` - Advanced Analysis
+
+Deep reasoning and analysis for complex problems.
+
+**Usage**:
+```bash
+/think "Analyze scalability bottlenecks in current architecture"
+/think "Evaluate different approaches for data synchronization"
+/think "Design migration strategy from monolith to microservices"
+```
+
+**Agent**: `gpt5` (deep reasoning)
+
+**Best for**:
+- Complex architectural decisions
+- Multi-faceted problems
+- Trade-off analysis
+- Strategic planning
+- System design
+
+## 🔄 Command Workflows
+
+### Simple Feature Development
+
+```bash
+# 1. Ask for guidance
+/ask "Best way to implement rate limiting in Express"
+
+# 2. Implement the feature
+/code "Add rate limiting middleware to API routes"
+
+# 3. Add tests
+/test "Create tests for rate limiting behavior"
+
+# 4. Review implementation
+/review "Validate rate limiting implementation"
+```
+
+### Bug Investigation and Fix
+
+```bash
+# 1. Debug the issue
+/debug "API returns 500 on concurrent requests"
+
+# 2. Fix the bug
+/bugfix "Add mutex lock to prevent race condition"
+
+# 3. Add regression tests
+/test "Test concurrent request handling"
+```
+
+### Code Quality Improvement
+
+```bash
+# 1. Review current code
+/review "Analyze user service for improvements"
+
+# 2. Refactor based on findings
+/refactor "Simplify user validation logic"
+
+# 3. Optimize performance
+/optimize "Cache frequently accessed user data"
+
+# 4. Update documentation
+/docs "Document user service API"
+```
+
+## 🎯 When to Use What
+
+### Use Direct Commands When:
+- Task is clear and well-defined
+- No complex planning needed
+- Fast iteration is priority
+- Working within existing patterns
+
+### Use Requirements Workflow When:
+- Feature has unclear requirements
+- Need documented specifications
+- Multiple implementation approaches possible
+- Quality gates desired
+
+### Use BMAD Workflow When:
+- Complex business requirements
+- Architecture design needed
+- Sprint planning required
+- Multiple stakeholders involved
+
+## 💡 Best Practices
+
+1. **Be Specific**: Provide clear, detailed descriptions
+   - ❌ `/code "fix the bug"`
+   - ✅ `/code "Fix null pointer exception in user login when email is missing"`
+
+2. **One Task Per Command**: Keep commands focused
+   - ❌ `/code "Add feature X, fix bug Y, refactor module Z"`
+   - ✅ `/code "Add email validation to registration form"`
+
+3. **Provide Context**: Include relevant details
+   - ✅ `/debug "Login API returns 401 after password change, only on Safari"`
+
+4. **Use Appropriate Command**: Match command to task type
+   - Use `/bugfix` for bugs, not `/code`
+   - Use `/refactor` for restructuring, not `/optimize`
+   - Use `/think` for complex analysis, not `/ask`
+
+5. **Chain Commands**: Break complex tasks into steps
+   ```bash
+   /ask "How to implement OAuth2"
+   /code "Implement OAuth2 authorization flow"
+   /test "Add OAuth2 integration tests"
+   /review "Validate OAuth2 security"
+   /docs "Document OAuth2 setup process"
+   ```
+
+## 🔌 Agent Configuration
+
+All commands use specialized agents configured in:
+- `development-essentials/agents/`
+- Agent prompt templates
+- Tool access permissions
+- Output formatting
+
+## 📚 Related Documentation
+
+- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Full agile methodology
+- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight workflow
+- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
+- **[Plugin System](PLUGIN-SYSTEM.md)** - Installation and configuration
+
+---
+
+**Development Essentials** - Direct commands for productive coding without workflow overhead.

docs/HOOKS.md

@@ -0,0 +1,197 @@
+# Claude Code Hooks Guide
+
+Hooks are shell scripts or commands that execute in response to Claude Code events.
+
+## Available Hook Types
+
+### 1. UserPromptSubmit
+Runs after user submits a prompt, before Claude processes it.
+
+**Use cases:**
+- Auto-activate skills based on keywords
+- Add context injection
+- Log user requests
+
+### 2. PostToolUse
+Runs after Claude uses a tool.
+
+**Use cases:**
+- Validate tool outputs
+- Run additional checks (linting, formatting)
+- Log tool usage
+
+### 3. Stop
+Runs when Claude Code session ends.
+
+**Use cases:**
+- Cleanup temporary files
+- Generate session reports
+- Commit changes automatically
+
+## Configuration
+
+Hooks are configured in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/hooks/skill-activation-prompt.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/hooks/post-tool-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Creating Custom Hooks
+
+### Example: Pre-Commit Hook
+
+**File:** `hooks/pre-commit.sh`
+
+```bash
+#!/bin/bash
+set -e
+
+# Get staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+# Run tests on Go files
+GO_FILES=$(echo "$STAGED_FILES" | grep '\.go$' || true)
+if [ -n "$GO_FILES" ]; then
+  go test ./... -short || exit 1
+fi
+
+# Validate JSON files
+JSON_FILES=$(echo "$STAGED_FILES" | grep '\.json$' || true)
+if [ -n "$JSON_FILES" ]; then
+  for file in $JSON_FILES; do
+    jq empty "$file" || exit 1
+  done
+fi
+
+echo "✅ Pre-commit checks passed"
+```
+
+**Register in settings.json:**
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/hooks/pre-commit.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Example: Auto-Format Hook
+
+**File:** `hooks/auto-format.sh`
+
+```bash
+#!/bin/bash
+
+# Format Go files
+find . -name "*.go" -exec gofmt -w {} \;
+
+# Format JSON files
+find . -name "*.json" -exec jq --indent 2 . {} \; -exec mv {} {}.tmp \; -exec mv {}.tmp {} \;
+
+echo "✅ Files formatted"
+```
+
+## Environment Variables
+
+Hooks have access to:
+- `$CLAUDE_PROJECT_DIR` - Project root directory
+- `$PWD` - Current working directory
+- All shell environment variables
+
+## Best Practices
+
+1. **Keep hooks fast** - Slow hooks block Claude Code
+2. **Handle errors gracefully** - Return non-zero on failure
+3. **Use absolute paths** - Reference `$CLAUDE_PROJECT_DIR`
+4. **Make scripts executable** - `chmod +x hooks/script.sh`
+5. **Test independently** - Run hooks manually first
+6. **Document behavior** - Add comments explaining logic
+
+## Debugging Hooks
+
+Enable verbose logging:
+
+```bash
+# Add to your hook
+set -x  # Print commands
+set -e  # Exit on error
+```
+
+Test manually:
+
+```bash
+cd /path/to/project
+./hooks/your-hook.sh
+echo $?  # Check exit code
+```
+
+## Built-in Hooks
+
+This repository includes:
+
+| Hook | File | Purpose |
+|------|------|---------|
+| Skill Activation | `skill-activation-prompt.sh` | Auto-suggest skills |
+| Pre-commit | `pre-commit.sh` | Code quality checks |
+
+## Disabling Hooks
+
+Remove hook configuration from `.claude/settings.json` or set empty array:
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": []
+  }
+}
+```
+
+## Troubleshooting
+
+**Hook not running?**
+- Check `.claude/settings.json` syntax
+- Verify script is executable: `ls -l hooks/`
+- Check script path is correct
+
+**Hook failing silently?**
+- Add `set -e` to script
+- Check exit codes: `echo $?`
+- Add logging: `echo "debug" >> /tmp/hook.log`
+
+## Further Reading
+
+- [Claude Code Hooks Documentation](https://docs.anthropic.com/claude-code/hooks)
+- [Bash Scripting Guide](https://www.gnu.org/software/bash/manual/)

docs/PLUGIN-SYSTEM.md

@@ -0,0 +1,348 @@
+# Plugin System Guide
+
+> Native Claude Code plugin support for modular workflow installation
+
+## 🎯 Overview
+
+This repository provides 4 ready-to-use Claude Code plugins that can be installed individually or as a complete suite.
+
+## 📦 Available Plugins
+
+### 1. bmad-agile-workflow
+
+**Complete BMAD methodology with 6 specialized agents**
+
+**Commands**:
+- `/bmad-pilot` - Full agile workflow orchestration
+
+**Agents**:
+- `bmad-po` - Product Owner (Sarah)
+- `bmad-architect` - System Architect (Winston)
+- `bmad-sm` - Scrum Master (Mike)
+- `bmad-dev` - Developer (Alex)
+- `bmad-review` - Code Reviewer
+- `bmad-qa` - QA Engineer (Emma)
+- `bmad-orchestrator` - Main orchestrator
+
+**Use for**: Enterprise projects, complex features, full agile process
+
+### 2. requirements-driven-workflow
+
+**Streamlined requirements-to-code workflow**
+
+**Commands**:
+- `/requirements-pilot` - Requirements-driven development flow
+
+**Agents**:
+- `requirements-generate` - Requirements generation
+- `requirements-code` - Code implementation
+- `requirements-review` - Code review
+- `requirements-testing` - Testing strategy
+
+**Use for**: Quick prototyping, simple features, rapid development
+
+### 3. development-essentials
+
+**Core development slash commands**
+
+**Commands**:
+- `/code` - Direct implementation
+- `/debug` - Systematic debugging
+- `/test` - Testing strategy
+- `/optimize` - Performance tuning
+- `/bugfix` - Bug resolution
+- `/refactor` - Code improvement
+- `/review` - Code validation
+- `/ask` - Technical consultation
+- `/docs` - Documentation
+- `/think` - Advanced analysis
+
+**Agents**:
+- `code` - Code implementation
+- `bugfix` - Bug fixing
+- `debug` - Debugging
+- `develop` - General development
+
+**Use for**: Daily coding tasks, quick implementations
+
+### 4. advanced-ai-agents
+
+**GPT-5 deep reasoning integration**
+
+**Commands**: None (agent-only)
+
+**Agents**:
+- `gpt5` - Deep reasoning and analysis
+
+**Use for**: Complex architectural decisions, strategic planning
+
+## 🚀 Installation Methods
+
+### Method 1: Plugin Commands (Recommended)
+
+```bash
+# List all available plugins
+/plugin list
+
+# Get detailed information about a plugin
+/plugin info bmad-agile-workflow
+
+# Install a specific plugin
+/plugin install bmad-agile-workflow
+
+# Install all plugins
+/plugin install bmad-agile-workflow
+/plugin install requirements-driven-workflow
+/plugin install development-essentials
+/plugin install advanced-ai-agents
+
+# Remove an installed plugin
+/plugin remove development-essentials
+```
+
+### Method 2: Repository Reference
+
+```bash
+# Install from GitHub repository
+/plugin marketplace add cexll/myclaude
+```
+
+This will present all available plugins from the repository.
+
+### Method 3: Make Commands
+
+For traditional installation or selective deployment:
+
+```bash
+# Install everything
+make install
+
+# Deploy specific workflows
+make deploy-bmad          # BMAD workflow only
+make deploy-requirements  # Requirements workflow only
+make deploy-commands      # All slash commands
+make deploy-agents       # All agents
+
+# Deploy everything
+make deploy-all
+
+# View all options
+make help
+```
+
+### Method 4: Manual Installation
+
+Copy files to Claude Code configuration directories:
+
+**Commands**:
+```bash
+cp bmad-agile-workflow/commands/*.md ~/.config/claude/commands/
+cp requirements-driven-workflow/commands/*.md ~/.config/claude/commands/
+cp development-essentials/commands/*.md ~/.config/claude/commands/
+```
+
+**Agents**:
+```bash
+cp bmad-agile-workflow/agents/*.md ~/.config/claude/agents/
+cp requirements-driven-workflow/agents/*.md ~/.config/claude/agents/
+cp development-essentials/agents/*.md ~/.config/claude/agents/
+cp advanced-ai-agents/agents/*.md ~/.config/claude/agents/
+```
+
+**Output Styles** (optional):
+```bash
+cp output-styles/*.md ~/.config/claude/output-styles/
+```
+
+## 📋 Plugin Configuration
+
+Plugins are defined in `.claude-plugin/marketplace.json` following the Claude Code plugin specification.
+
+### Plugin Metadata Structure
+
+```json
+{
+  "name": "plugin-name",
+  "displayName": "Human Readable Name",
+  "description": "Plugin description",
+  "version": "1.0.0",
+  "author": "Author Name",
+  "category": "workflow|development|analysis",
+  "keywords": ["keyword1", "keyword2"],
+  "commands": ["command1", "command2"],
+  "agents": ["agent1", "agent2"]
+}
+```
+
+## 🔧 Plugin Management
+
+### Check Installed Plugins
+
+```bash
+/plugin list
+```
+
+Shows all installed plugins with their status.
+
+### Plugin Information
+
+```bash
+/plugin info <plugin-name>
+```
+
+Displays detailed information:
+- Description
+- Version
+- Commands provided
+- Agents included
+- Author and keywords
+
+### Update Plugins
+
+Plugins are updated when you pull the latest repository changes:
+
+```bash
+git pull origin main
+make install
+```
+
+### Uninstall Plugins
+
+```bash
+/plugin remove <plugin-name>
+```
+
+Or manually remove files:
+
+```bash
+# Remove commands
+rm ~/.config/claude/commands/<command-name>.md
+
+# Remove agents
+rm ~/.config/claude/agents/<agent-name>.md
+```
+
+## 🎯 Plugin Selection Guide
+
+### Install Everything (Recommended for New Users)
+
+```bash
+make install
+```
+
+Provides complete functionality with all workflows and commands.
+
+### Selective Installation
+
+**For Agile Teams**:
+```bash
+/plugin install bmad-agile-workflow
+```
+
+**For Rapid Development**:
+```bash
+/plugin install requirements-driven-workflow
+/plugin install development-essentials
+```
+
+**For Individual Developers**:
+```bash
+/plugin install development-essentials
+/plugin install advanced-ai-agents
+```
+
+**For Code Quality Focus**:
+```bash
+/plugin install development-essentials  # Includes /review
+/plugin install bmad-agile-workflow     # Includes bmad-review
+```
+
+## 📁 Directory Structure
+
+```
+myclaude/
+├── .claude-plugin/
+│   └── marketplace.json          # Plugin registry
+├── bmad-agile-workflow/
+│   ├── commands/
+│   │   └── bmad-pilot.md
+│   └── agents/
+│       ├── bmad-po.md
+│       ├── bmad-architect.md
+│       ├── bmad-sm.md
+│       ├── bmad-dev.md
+│       ├── bmad-review.md
+│       ├── bmad-qa.md
+│       └── bmad-orchestrator.md
+├── requirements-driven-workflow/
+│   ├── commands/
+│   │   └── requirements-pilot.md
+│   └── agents/
+│       ├── requirements-generate.md
+│       ├── requirements-code.md
+│       ├── requirements-review.md
+│       └── requirements-testing.md
+├── development-essentials/
+│   ├── commands/
+│   │   ├── code.md
+│   │   ├── debug.md
+│   │   ├── test.md
+│   │   └── ... (more commands)
+│   └── agents/
+│       ├── code.md
+│       ├── bugfix.md
+│       ├── debug.md
+│       └── develop.md
+├── advanced-ai-agents/
+│   └── agents/
+│       └── gpt5.md
+└── output-styles/
+    └── bmad-phase-context.md
+```
+
+## 🔄 Plugin Dependencies
+
+**No Dependencies**: All plugins work independently
+
+**Complementary Combinations**:
+- BMAD + Advanced Agents (enhanced reviews)
+- Requirements + Development Essentials (complete toolkit)
+- All four plugins (full suite)
+
+## 🛠️ Makefile Reference
+
+```bash
+# Installation
+make install              # Install all plugins
+make deploy-all          # Deploy all configurations
+
+# Selective Deployment
+make deploy-bmad         # BMAD workflow only
+make deploy-requirements # Requirements workflow only
+make deploy-commands     # All slash commands only
+make deploy-agents       # All agents only
+
+# Testing
+make test-bmad          # Test BMAD workflow
+make test-requirements  # Test Requirements workflow
+
+# Cleanup
+make clean              # Remove generated artifacts
+make help               # Show all available commands
+```
+
+## 📚 Related Documentation
+
+- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Complete BMAD guide
+- **[Requirements Workflow](REQUIREMENTS-WORKFLOW.md)** - Lightweight workflow guide
+- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Command reference
+- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
+
+## 🔗 External Resources
+
+- **[Claude Code Plugin Docs](https://docs.claude.com/en/docs/claude-code/plugins)** - Official plugin documentation
+- **[Claude Code CLI](https://claude.ai/code)** - Claude Code interface
+
+---
+
+**Modular Installation** - Install only what you need, when you need it.

docs/QUICK-START.md

@@ -0,0 +1,326 @@
+# Quick Start Guide
+
+> Get started with Claude Code Multi-Agent Workflow System in 5 minutes
+
+## 🚀 Installation (2 minutes)
+
+### Option 1: Plugin System (Fastest)
+
+```bash
+# Install everything with one command
+/plugin marketplace add cexll/myclaude
+```
+
+### Option 2: Make Install
+
+```bash
+git clone https://github.com/cexll/myclaude.git
+cd myclaude
+make install
+```
+
+### Option 3: Selective Install
+
+```bash
+# Install only what you need
+/plugin install bmad-agile-workflow       # Full agile workflow
+/plugin install development-essentials    # Daily coding commands
+```
+
+## 🎯 Your First Workflow (3 minutes)
+
+### Try BMAD Workflow
+
+Complete agile development automation:
+
+```bash
+/bmad-pilot "Build a simple todo list API with CRUD operations"
+```
+
+**What happens**:
+1. **Product Owner** generates requirements (PRD)
+2. **Architect** designs system architecture
+3. **Scrum Master** creates sprint plan
+4. **Developer** implements code
+5. **Reviewer** performs code review
+6. **QA** runs tests
+
+All documents saved to `.claude/specs/todo-list-api/`
+
+### Try Requirements Workflow
+
+Fast prototyping:
+
+```bash
+/requirements-pilot "Add user authentication to existing API"
+```
+
+**What happens**:
+1. Generate functional requirements
+2. Implement code
+3. Review implementation
+4. Create tests
+
+### Try Direct Commands
+
+Quick coding without workflow:
+
+```bash
+# Implement a feature
+/code "Add input validation for email fields"
+
+# Debug an issue
+/debug "API returns 500 on missing parameters"
+
+# Add tests
+/test "Create unit tests for validation logic"
+```
+
+## 📋 Common Use Cases
+
+### 1. New Feature Development
+
+**Complex Feature** (use BMAD):
+```bash
+/bmad-pilot "User authentication system with OAuth2, MFA, and role-based access control"
+```
+
+**Simple Feature** (use Requirements):
+```bash
+/requirements-pilot "Add pagination to user list endpoint"
+```
+
+**Tiny Feature** (use direct command):
+```bash
+/code "Add created_at timestamp to user model"
+```
+
+### 2. Bug Fixing
+
+**Complex Bug** (use debug):
+```bash
+/debug "Memory leak in background job processor"
+```
+
+**Simple Bug** (use bugfix):
+```bash
+/bugfix "Login button not working on mobile Safari"
+```
+
+### 3. Code Quality
+
+**Full Review**:
+```bash
+/review "Review authentication module for security issues"
+```
+
+**Refactoring**:
+```bash
+/refactor "Simplify user validation logic and remove duplication"
+```
+
+**Optimization**:
+```bash
+/optimize "Reduce database queries in dashboard API"
+```
+
+## 🎨 Workflow Selection Guide
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Choose Your Workflow                 │
+└─────────────────────────────────────────────────────────┘
+
+Complex Business Feature + Architecture Needed
+              ↓
+      🏢 Use BMAD Workflow
+   /bmad-pilot "description"
+   • 6 specialized agents
+   • Quality gates (PRD ≥90, Design ≥90)
+   • Complete documentation
+   • Sprint planning included
+
+────────────────────────────────────────────────────────
+
+Clear Requirements + Fast Iteration Needed
+              ↓
+    ⚡ Use Requirements Workflow
+ /requirements-pilot "description"
+   • 4 phases: Requirements → Code → Review → Test
+   • Quality gate (Requirements ≥90)
+   • Minimal documentation
+   • Direct to implementation
+
+────────────────────────────────────────────────────────
+
+Well-Defined Task + No Workflow Overhead
+              ↓
+      🔧 Use Direct Commands
+  /code | /debug | /test | /optimize
+   • Single-purpose commands
+   • Immediate execution
+   • No documentation overhead
+   • Perfect for daily tasks
+```
+
+## 💡 Tips for Success
+
+### 1. Be Specific
+
+**❌ Bad**:
+```bash
+/bmad-pilot "Build an app"
+```
+
+**✅ Good**:
+```bash
+/bmad-pilot "Build a task management API with user authentication, task CRUD, 
+task assignment, and real-time notifications via WebSocket"
+```
+
+### 2. Provide Context
+
+Include relevant technical details:
+```bash
+/code "Add Redis caching to user profile endpoint, cache TTL 5 minutes, 
+invalidate on profile update"
+```
+
+### 3. Engage with Agents
+
+During BMAD workflow, provide feedback at quality gates:
+
+```
+PO: "Here's the PRD (Score: 85/100)"
+You: "Add mobile app support and offline mode requirements"
+PO: "Updated PRD (Score: 94/100) ✅"
+```
+
+### 4. Review Generated Artifacts
+
+Check documents before confirming:
+- `.claude/specs/{feature}/01-product-requirements.md`
+- `.claude/specs/{feature}/02-system-architecture.md`
+- `.claude/specs/{feature}/03-sprint-plan.md`
+
+### 5. Chain Commands for Complex Tasks
+
+Break down complex work:
+```bash
+/ask "Best approach for implementing real-time chat"
+/bmad-pilot "Real-time chat system with message history and typing indicators"
+/test "Add integration tests for chat message delivery"
+/docs "Document chat API endpoints and WebSocket events"
+```
+
+## 🎓 Learning Path
+
+**Day 1**: Try direct commands
+```bash
+/code "simple task"
+/test "add some tests"
+/review "check my code"
+```
+
+**Day 2**: Try Requirements workflow
+```bash
+/requirements-pilot "small feature"
+```
+
+**Week 2**: Try BMAD workflow
+```bash
+/bmad-pilot "larger feature"
+```
+
+**Week 3**: Combine workflows
+```bash
+# Use BMAD for planning
+/bmad-pilot "new module" --direct-dev
+
+# Use Requirements for sprint tasks
+/requirements-pilot "individual task from sprint"
+
+# Use commands for daily work
+/code "quick fix"
+/test "add test"
+```
+
+## 📚 Next Steps
+
+### Explore Documentation
+
+- **[BMAD Workflow Guide](BMAD-WORKFLOW.md)** - Deep dive into full agile workflow
+- **[Requirements Workflow Guide](REQUIREMENTS-WORKFLOW.md)** - Learn lightweight development
+- **[Development Commands Reference](DEVELOPMENT-COMMANDS.md)** - All command details
+- **[Plugin System Guide](PLUGIN-SYSTEM.md)** - Plugin management
+
+### Try Advanced Features
+
+**BMAD Options**:
+```bash
+# Skip testing for prototype
+/bmad-pilot "prototype" --skip-tests
+
+# Skip sprint planning for quick dev
+/bmad-pilot "feature" --direct-dev
+
+# Skip repo scan (if context exists)
+/bmad-pilot "feature" --skip-scan
+```
+
+**Individual Agents**:
+```bash
+# Just requirements
+/bmad-po "feature requirements"
+
+# Just architecture
+/bmad-architect "system design"
+
+# Just orchestration
+/bmad-orchestrator "complex project coordination"
+```
+
+### Check Quality
+
+Run tests and validation:
+```bash
+make test-bmad              # Test BMAD workflow
+make test-requirements      # Test Requirements workflow
+```
+
+## 🆘 Troubleshooting
+
+**Commands not found**?
+```bash
+# Verify installation
+/plugin list
+
+# Reinstall if needed
+make install
+```
+
+**Agents not working**?
+```bash
+# Check agent configuration
+ls ~/.config/claude/agents/
+
+# Redeploy agents
+make deploy-agents
+```
+
+**Output styles missing**?
+```bash
+# Deploy output styles
+cp output-styles/*.md ~/.config/claude/output-styles/
+```
+
+## 📞 Get Help
+
+- **Issues**: [GitHub Issues](https://github.com/cexll/myclaude/issues)
+- **Documentation**: [docs/](.)
+- **Examples**: Check `.claude/specs/` after running workflows
+- **Make Help**: Run `make help` for all commands
+
+---
+
+**You're ready!** Start with `/code "your first task"` and explore from there.

docs/REQUIREMENTS-WORKFLOW.md

@@ -0,0 +1,259 @@
+# Requirements-Driven Workflow Guide
+
+> Lightweight alternative to BMAD for rapid prototyping and simple feature development
+
+## 🎯 What is Requirements Workflow?
+
+A streamlined 4-phase workflow that focuses on getting from requirements to working code quickly:
+
+**Requirements → Implementation → Review → Testing**
+
+Perfect for:
+- Quick prototypes
+- Small features
+- Bug fixes with clear scope
+- Projects without complex architecture needs
+
+## 🚀 Quick Start
+
+### Basic Command
+
+```bash
+/requirements-pilot "Implement JWT authentication with refresh tokens"
+
+# Automated workflow:
+# 1. Requirements generation (90% quality gate)
+# 2. Code implementation
+# 3. Code review
+# 4. Testing strategy
+```
+
+### When to Use
+
+**Use Requirements Workflow** when:
+- Feature scope is clear and simple
+- No complex architecture design needed
+- Fast iteration is priority
+- You want minimal workflow overhead
+
+**Use BMAD Workflow** when:
+- Complex business requirements
+- Multiple systems integration
+- Architecture design is critical
+- Need detailed sprint planning
+
+## 📋 Workflow Phases
+
+### Phase 1: Requirements Generation
+- **Agent**: `requirements-generate`
+- **Quality Gate**: Requirements score ≥ 90/100
+- **Output**: Functional requirements document
+- **Focus**:
+  - Clear functional requirements
+  - Acceptance criteria
+  - Technical constraints
+  - Implementation notes
+
+**Quality Criteria (100 points)**:
+- Clarity (30): Unambiguous, well-defined
+- Completeness (25): All aspects covered
+- Testability (20): Clear verification points
+- Technical Feasibility (15): Realistic implementation
+- Scope Definition (10): Clear boundaries
+
+### Phase 2: Code Implementation
+- **Agent**: `requirements-code`
+- **Quality Gate**: Code completion
+- **Output**: Implementation files
+- **Process**:
+  1. Read requirements + repository context
+  2. Implement features following requirements
+  3. Create or modify code files
+  4. Follow existing code conventions
+
+### Phase 3: Code Review
+- **Agent**: `requirements-review`
+- **Quality Gate**: Pass / Pass with Risk / Fail
+- **Output**: Review report
+- **Focus**:
+  - Code quality
+  - Requirements alignment
+  - Security concerns
+  - Performance issues
+  - Best practices compliance
+
+**Review Status**:
+- **Pass**: Meets standards, ready for testing
+- **Pass with Risk**: Minor issues noted
+- **Fail**: Requires implementation revision
+
+### Phase 4: Testing Strategy
+- **Agent**: `requirements-testing`
+- **Quality Gate**: Test execution
+- **Output**: Test report
+- **Process**:
+  1. Create test strategy from requirements
+  2. Generate test cases
+  3. Execute tests (unit, integration)
+  4. Report results
+
+## 📁 Workflow Artifacts
+
+Generated in `.claude/requirements/{feature-name}/`:
+
+```
+.claude/requirements/jwt-authentication/
+├── 01-requirements.md        # Functional requirements (score ≥ 90)
+├── 02-implementation.md      # Implementation summary
+├── 03-review.md             # Code review report
+└── 04-testing.md            # Test strategy and results
+```
+
+## 🔧 Command Options
+
+```bash
+# Standard workflow
+/requirements-pilot "Add API rate limiting"
+
+# With specific technology
+/requirements-pilot "Redis caching layer with TTL management"
+
+# Bug fix with requirements
+/requirements-pilot "Fix login session timeout issue"
+```
+
+## 📊 Quality Scoring
+
+### Requirements Score (100 points)
+
+| Category | Points | Description |
+|----------|--------|-------------|
+| Clarity | 30 | Unambiguous, well-defined requirements |
+| Completeness | 25 | All functional aspects covered |
+| Testability | 20 | Clear acceptance criteria |
+| Technical Feasibility | 15 | Realistic implementation plan |
+| Scope Definition | 10 | Clear feature boundaries |
+
+**Threshold**: ≥ 90 points to proceed
+
+### Automatic Optimization
+
+If initial score < 90:
+1. User provides feedback
+2. Agent revises requirements
+3. System recalculates score
+4. Repeat until ≥ 90
+5. User confirms → Save → Next phase
+
+## 🎯 Comparison: Requirements vs BMAD
+
+| Aspect | Requirements Workflow | BMAD Workflow |
+|--------|----------------------|---------------|
+| **Phases** | 4 (Requirements → Code → Review → Test) | 6 (PO → Arch → SM → Dev → Review → QA) |
+| **Duration** | Fast (hours) | Thorough (days) |
+| **Documentation** | Minimal | Comprehensive |
+| **Quality Gates** | 1 (Requirements ≥ 90) | 2 (PRD ≥ 90, Design ≥ 90) |
+| **Approval Points** | None | Multiple (after PRD, Architecture, Sprint Plan) |
+| **Best For** | Simple features, prototypes | Complex features, enterprise projects |
+| **Artifacts** | 4 documents | 6 documents |
+| **Planning** | Direct implementation | Sprint planning included |
+| **Architecture** | Implicit in requirements | Explicit design phase |
+
+## 💡 Usage Examples
+
+### Example 1: API Feature
+
+```bash
+/requirements-pilot "REST API endpoint for user profile updates with validation"
+
+# Generated requirements include:
+# - Endpoint specification (PUT /api/users/:id/profile)
+# - Request/response schemas
+# - Validation rules
+# - Error handling
+# - Authentication requirements
+
+# Implementation follows directly
+# Review checks API best practices
+# Testing includes endpoint testing
+```
+
+### Example 2: Database Schema
+
+```bash
+/requirements-pilot "Add audit logging table for user actions"
+
+# Generated requirements include:
+# - Table schema definition
+# - Indexing strategy
+# - Retention policy
+# - Query patterns
+
+# Implementation creates migration
+# Review checks schema design
+# Testing verifies logging behavior
+```
+
+### Example 3: Bug Fix
+
+```bash
+/requirements-pilot "Fix race condition in order processing queue"
+
+# Generated requirements include:
+# - Problem description
+# - Root cause analysis
+# - Solution approach
+# - Verification steps
+
+# Implementation applies fix
+# Review checks concurrency handling
+# Testing includes stress tests
+```
+
+## 🔄 Iterative Refinement
+
+Each phase supports feedback:
+
+```
+Agent: "Requirements complete (Score: 85/100)"
+User: "Add error handling for network failures"
+Agent: "Updated requirements (Score: 93/100) ✅"
+```
+
+## 🚀 Advanced Usage
+
+### Combining with Individual Commands
+
+```bash
+# Generate requirements only
+/requirements-generate "OAuth2 integration requirements"
+
+# Just code implementation (requires existing requirements)
+/requirements-code "Implement based on requirements.md"
+
+# Standalone review
+/requirements-review "Review current implementation"
+```
+
+### Integration with BMAD
+
+Use Requirements Workflow for sub-tasks within BMAD sprints:
+
+```bash
+# BMAD creates sprint plan
+/bmad-pilot "E-commerce platform"
+
+# Use Requirements for individual sprint tasks
+/requirements-pilot "Shopping cart session management"
+/requirements-pilot "Payment webhook handling"
+```
+
+## 📚 Related Documentation
+
+- **[BMAD Workflow](BMAD-WORKFLOW.md)** - Full agile methodology
+- **[Development Commands](DEVELOPMENT-COMMANDS.md)** - Direct coding commands
+- **[Quick Start Guide](QUICK-START.md)** - Get started quickly
+
+---
+
+**Requirements-Driven Development** - From requirements to working code in hours, not days.

go.work

@@ -0,0 +1,5 @@
+go 1.21
+
+use (
+	./codeagent-wrapper
+)

hooks/hooks-config.json

@@ -0,0 +1,12 @@
+{
+  "UserPromptSubmit": [
+    {
+      "hooks": [
+        {
+          "type": "command",
+          "command": "$CLAUDE_PROJECT_DIR/hooks/skill-activation-prompt.sh"
+        }
+      ]
+    }
+  ]
+}

hooks/pre-commit.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+# Example pre-commit hook
+# This hook runs before git commit to validate code quality
+
+set -e
+
+# Get staged files
+STAGED_FILES="$(git diff --cached --name-only --diff-filter=ACM)"
+
+if [ -z "$STAGED_FILES" ]; then
+  echo "No files to validate"
+  exit 0
+fi
+
+echo "Running pre-commit checks..."
+
+# Check Go files
+GO_FILES="$(printf '%s\n' "$STAGED_FILES" | grep '\.go$' || true)"
+if [ -n "$GO_FILES" ]; then
+  echo "Checking Go files..."
+
+  if ! command -v gofmt &> /dev/null; then
+    echo "❌ gofmt not found. Please install Go (gofmt is included with the Go toolchain)."
+    exit 1
+  fi
+
+  # Format check
+  GO_FILE_ARGS=()
+  while IFS= read -r file; do
+    if [ -n "$file" ]; then
+      GO_FILE_ARGS+=("$file")
+    fi
+  done <<< "$GO_FILES"
+
+  if [ "${#GO_FILE_ARGS[@]}" -gt 0 ]; then
+    UNFORMATTED="$(gofmt -l "${GO_FILE_ARGS[@]}")"
+    if [ -n "$UNFORMATTED" ]; then
+      echo "❌ The following files need formatting:"
+      echo "$UNFORMATTED"
+      echo "Run: gofmt -w <file>"
+      exit 1
+    fi
+  fi
+
+  # Run tests
+  if command -v go &> /dev/null; then
+    echo "Running go tests..."
+    go test ./... -short || {
+      echo "❌ Tests failed"
+      exit 1
+    }
+  fi
+fi
+
+# Check JSON files
+JSON_FILES="$(printf '%s\n' "$STAGED_FILES" | grep '\.json$' || true)"
+if [ -n "$JSON_FILES" ]; then
+  echo "Validating JSON files..."
+  if ! command -v jq &> /dev/null; then
+    echo "❌ jq not found. Please install jq to validate JSON files."
+    exit 1
+  fi
+  while IFS= read -r file; do
+    if [ -z "$file" ]; then
+      continue
+    fi
+    if ! jq empty "$file" 2>/dev/null; then
+      echo "❌ Invalid JSON: $file"
+      exit 1
+    fi
+  done <<< "$JSON_FILES"
+fi
+
+# Check Markdown files
+MD_FILES="$(printf '%s\n' "$STAGED_FILES" | grep '\.md$' || true)"
+if [ -n "$MD_FILES" ]; then
+  echo "Checking markdown files..."
+  # Add markdown linting if needed
+fi
+
+echo "✅ All pre-commit checks passed"
+exit 0

hooks/skill-activation-prompt.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+function readInput() {
+  const raw = fs.readFileSync(0, "utf8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch (_err) {
+    return {};
+  }
+}
+
+function extractPrompt(payload) {
+  return (
+    payload.prompt ||
+    payload.text ||
+    payload.userPrompt ||
+    (payload.data && payload.data.prompt) ||
+    ""
+  ).toString();
+}
+
+function loadRules() {
+  const rulesPath = path.resolve(__dirname, "../skills/skill-rules.json");
+  try {
+    const file = fs.readFileSync(rulesPath, "utf8");
+    return JSON.parse(file);
+  } catch (_err) {
+    return { skills: {} };
+  }
+}
+
+function matchSkill(prompt, rule, skillName) {
+  const triggers = (rule && rule.promptTriggers) || {};
+  const keywords = [...(triggers.keywords || []), skillName].filter(Boolean);
+  const patterns = triggers.intentPatterns || [];
+  const promptLower = prompt.toLowerCase();
+
+  const keyword = keywords.find((k) => promptLower.includes(k.toLowerCase()));
+  if (keyword) {
+    return `命中关键词 "${keyword}"`;
+  }
+
+  for (const pattern of patterns) {
+    try {
+      if (new RegExp(pattern, "i").test(prompt)) {
+        return `命中模式 /${pattern}/`;
+      }
+    } catch (_err) {
+      continue;
+    }
+  }
+  return null;
+}
+
+function main() {
+  const payload = readInput();
+  const prompt = extractPrompt(payload);
+  if (!prompt.trim()) {
+    console.log(JSON.stringify({ suggestedSkills: [] }, null, 2));
+    return;
+  }
+
+  const rules = loadRules();
+  const suggestions = [];
+
+  for (const [name, rule] of Object.entries(rules.skills || {})) {
+    const matchReason = matchSkill(prompt, rule, name);
+    if (matchReason) {
+      suggestions.push({
+        skill: name,
+        enforcement: rule.enforcement || "suggest",
+        priority: rule.priority || "normal",
+        reason: matchReason
+      });
+    }
+  }
+
+  console.log(JSON.stringify({ suggestedSkills: suggestions }, null, 2));
+}
+
+main();

hooks/skill-activation-prompt.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$SCRIPT_DIR/skill-activation-prompt.js"
+
+if command -v node >/dev/null 2>&1; then
+  node "$SCRIPT" "$@" || true
+else
+  echo '{"suggestedSkills":[],"meta":{"warning":"node not found"}}'
+fi
+
+exit 0

hooks/test-skill-activation.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+
+# Simple test runner for skill-activation-prompt hook.
+# Each case feeds JSON to the hook and validates suggested skills.
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOOK_SCRIPT="$SCRIPT_DIR/skill-activation-prompt.sh"
+
+parse_skills() {
+  node -e 'const data = JSON.parse(require("fs").readFileSync(0, "utf8")); const skills = (data.suggestedSkills || []).map(s => s.skill); console.log(skills.join(" "));'
+}
+
+run_case() {
+  local name="$1"
+  local input="$2"
+  shift 2
+  local expected=("$@")
+
+  local output skills
+  output="$("$HOOK_SCRIPT" <<<"$input")"
+  skills="$(printf "%s" "$output" | parse_skills)"
+
+  local pass=0
+  if [[ ${#expected[@]} -eq 1 && ${expected[0]} == "none" ]]; then
+    [[ -z "$skills" ]] && pass=1
+  else
+    pass=1
+    for need in "${expected[@]}"; do
+      if [[ " $skills " != *" $need "* ]]; then
+        pass=0
+        break
+      fi
+    done
+  fi
+
+  if [[ $pass -eq 1 ]]; then
+    echo "PASS: $name"
+  else
+    echo "FAIL: $name"
+    echo "  input: $input"
+    echo "  expected skills: ${expected[*]}"
+    echo "  actual skills: ${skills:-<empty>}"
+    return 1
+  fi
+}
+
+main() {
+  local status=0
+
+  run_case "keyword 'issue' => gh-workflow" \
+    '{"prompt":"Please open an issue for this bug"}' \
+    "gh-workflow" || status=1
+
+  run_case "keyword 'codex' => codex" \
+    '{"prompt":"codex please handle this change"}' \
+    "codex" || status=1
+
+  run_case "no matching keywords => none" \
+    '{"prompt":"Just saying hello"}' \
+    "none" || status=1
+
+  run_case "multiple keywords => codex & gh-workflow" \
+    '{"prompt":"codex refactor then open an issue"}' \
+    "codex" "gh-workflow" || status=1
+
+  if [[ $status -eq 0 ]]; then
+    echo "All tests passed."
+  else
+    echo "Some tests failed."
+  fi
+
+  exit "$status"
+}
+
+main "$@"

install.bat

@@ -0,0 +1,163 @@
+@echo off
+setlocal enabledelayedexpansion
+
+set "EXIT_CODE=0"
+set "REPO=cexll/myclaude"
+set "VERSION=latest"
+set "OS=windows"
+
+call :detect_arch
+if errorlevel 1 goto :fail
+
+set "BINARY_NAME=codeagent-wrapper-%OS%-%ARCH%.exe"
+set "URL=https://github.com/%REPO%/releases/%VERSION%/download/%BINARY_NAME%"
+set "TEMP_FILE=%TEMP%\codeagent-wrapper-%ARCH%-%RANDOM%.exe"
+set "DEST_DIR=%USERPROFILE%\bin"
+set "DEST=%DEST_DIR%\codeagent-wrapper.exe"
+
+echo Downloading codeagent-wrapper for %ARCH% ...
+echo   %URL%
+call :download
+if errorlevel 1 goto :fail
+
+if not exist "%TEMP_FILE%" (
+    echo ERROR: download failed to produce "%TEMP_FILE%".
+    goto :fail
+)
+
+echo Installing to "%DEST%" ...
+if not exist "%DEST_DIR%" (
+    mkdir "%DEST_DIR%" >nul 2>nul || goto :fail
+)
+
+move /y "%TEMP_FILE%" "%DEST%" >nul 2>nul
+if errorlevel 1 (
+    echo ERROR: unable to place file in "%DEST%".
+    goto :fail
+)
+
+"%DEST%" --version >nul 2>nul
+if errorlevel 1 (
+    echo ERROR: installation verification failed.
+    goto :fail
+)
+
+echo.
+echo codeagent-wrapper installed successfully at:
+echo   %DEST%
+
+rem Automatically ensure %USERPROFILE%\bin is in the USER (HKCU) PATH
+rem 1) Read current user PATH from registry (REG_SZ or REG_EXPAND_SZ)
+set "USER_PATH_RAW="
+set "USER_PATH_TYPE="
+for /f "tokens=1,2,*" %%A in ('reg query "HKCU\Environment" /v Path 2^>nul ^| findstr /I /R "^ *Path  *REG_"') do (
+    set "USER_PATH_TYPE=%%B"
+    set "USER_PATH_RAW=%%C"
+)
+rem Trim leading spaces from USER_PATH_RAW
+for /f "tokens=* delims= " %%D in ("!USER_PATH_RAW!") do set "USER_PATH_RAW=%%D"
+
+rem Normalize DEST_DIR by removing a trailing backslash if present
+if "!DEST_DIR:~-1!"=="\" set "DEST_DIR=!DEST_DIR:~0,-1!"
+
+rem Build search tokens (expanded and literal)
+set "PCT=%%"
+set "SEARCH_EXP=;!DEST_DIR!;"
+set "SEARCH_EXP2=;!DEST_DIR!\;"
+set "SEARCH_LIT=;!PCT!USERPROFILE!PCT!\bin;"
+set "SEARCH_LIT2=;!PCT!USERPROFILE!PCT!\bin\;"
+
+rem Prepare user PATH variants for containment tests
+set "CHECK_RAW=;!USER_PATH_RAW!;"
+set "USER_PATH_EXP=!USER_PATH_RAW!"
+if defined USER_PATH_EXP call set "USER_PATH_EXP=%%USER_PATH_EXP%%"
+set "CHECK_EXP=;!USER_PATH_EXP!;"
+
+rem Check if already present in user PATH (literal or expanded, with/without trailing backslash)
+set "ALREADY_IN_USERPATH=0"
+echo !CHECK_RAW! | findstr /I /C:"!SEARCH_LIT!" /C:"!SEARCH_LIT2!" >nul && set "ALREADY_IN_USERPATH=1"
+if "!ALREADY_IN_USERPATH!"=="0" (
+    echo !CHECK_EXP! | findstr /I /C:"!SEARCH_EXP!" /C:"!SEARCH_EXP2!" >nul && set "ALREADY_IN_USERPATH=1"
+)
+
+if "!ALREADY_IN_USERPATH!"=="1" (
+    echo User PATH already includes %%USERPROFILE%%\bin.
+) else (
+    rem Not present: append to user PATH using setx without duplicating system PATH
+    if defined USER_PATH_RAW (
+        set "USER_PATH_NEW=!USER_PATH_RAW!"
+        if not "!USER_PATH_NEW:~-1!"==";" set "USER_PATH_NEW=!USER_PATH_NEW!;"
+        set "USER_PATH_NEW=!USER_PATH_NEW!!PCT!USERPROFILE!PCT!\bin"
+    ) else (
+        set "USER_PATH_NEW=!PCT!USERPROFILE!PCT!\bin"
+    )
+    rem Persist update to HKCU\Environment\Path (user scope)
+    setx PATH "!USER_PATH_NEW!" >nul
+    if errorlevel 1 (
+        echo WARNING: Failed to append %%USERPROFILE%%\bin to your user PATH.
+    ) else (
+        echo Added %%USERPROFILE%%\bin to your user PATH.
+    )
+)
+
+rem Update current session PATH so codex-wrapper is immediately available
+set "CURPATH=;%PATH%;"
+echo !CURPATH! | findstr /I /C:"!SEARCH_EXP!" /C:"!SEARCH_EXP2!" /C:"!SEARCH_LIT!" /C:"!SEARCH_LIT2!" >nul
+if errorlevel 1 set "PATH=!DEST_DIR!;!PATH!"
+
+goto :cleanup
+
+:detect_arch
+set "ARCH=%PROCESSOR_ARCHITECTURE%"
+if defined PROCESSOR_ARCHITEW6432 set "ARCH=%PROCESSOR_ARCHITEW6432%"
+
+if /I "%ARCH%"=="AMD64" (
+    set "ARCH=amd64"
+    exit /b 0
+) else if /I "%ARCH%"=="ARM64" (
+    set "ARCH=arm64"
+    exit /b 0
+) else (
+    echo ERROR: unsupported architecture "%ARCH%". 64-bit Windows on AMD64 or ARM64 is required.
+    set "EXIT_CODE=1"
+    exit /b 1
+)
+
+:download
+where curl >nul 2>nul
+if %errorlevel%==0 (
+    echo Using curl ...
+    curl -fL --retry 3 --connect-timeout 10 "%URL%" -o "%TEMP_FILE%"
+    if errorlevel 1 (
+        echo ERROR: curl download failed.
+        set "EXIT_CODE=1"
+        exit /b 1
+    )
+    exit /b 0
+)
+
+where powershell >nul 2>nul
+if %errorlevel%==0 (
+    echo Using PowerShell ...
+    powershell -NoLogo -NoProfile -Command " $ErrorActionPreference='Stop'; try { [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072 -bor 768 -bor 192 } catch {} ; $wc = New-Object System.Net.WebClient; $wc.DownloadFile('%URL%','%TEMP_FILE%') "
+    if errorlevel 1 (
+        echo ERROR: PowerShell download failed.
+        set "EXIT_CODE=1"
+        exit /b 1
+    )
+    exit /b 0
+)
+
+echo ERROR: neither curl nor PowerShell is available to download the installer.
+set "EXIT_CODE=1"
+exit /b 1
+
+:fail
+echo Installation failed.
+set "EXIT_CODE=1"
+goto :cleanup
+
+:cleanup
+if exist "%TEMP_FILE%" del /f /q "%TEMP_FILE%" >nul 2>nul
+set "CODE=%EXIT_CODE%"
+endlocal & exit /b %CODE%

install.py

@@ -0,0 +1,589 @@
+#!/usr/bin/env python3
+"""JSON-driven modular installer.
+
+Keep it simple: validate config, expand paths, run three operation types,
+and record what happened. Designed to be small, readable, and predictable.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+try:
+    import jsonschema
+except ImportError:  # pragma: no cover
+    jsonschema = None
+
+DEFAULT_INSTALL_DIR = "~/.claude"
+
+
+def _ensure_list(ctx: Dict[str, Any], key: str) -> List[Any]:
+    ctx.setdefault(key, [])
+    return ctx[key]
+
+
+def parse_args(argv: Optional[Iterable[str]] = None) -> argparse.Namespace:
+    """Parse CLI arguments.
+
+    The default install dir must remain "~/.claude" to match docs/tests.
+    """
+
+    parser = argparse.ArgumentParser(
+        description="JSON-driven modular installation system"
+    )
+    parser.add_argument(
+        "--install-dir",
+        default=DEFAULT_INSTALL_DIR,
+        help="Installation directory (defaults to ~/.claude)",
+    )
+    parser.add_argument(
+        "--module",
+        help="Comma-separated modules to install, or 'all' for all enabled",
+    )
+    parser.add_argument(
+        "--config",
+        default="config.json",
+        help="Path to configuration file",
+    )
+    parser.add_argument(
+        "--list-modules",
+        action="store_true",
+        help="List available modules and exit",
+    )
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Force overwrite existing files",
+    )
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Enable verbose output to terminal",
+    )
+    return parser.parse_args(argv)
+
+
+def _load_json(path: Path) -> Any:
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            return json.load(fh)
+    except FileNotFoundError as exc:
+        raise FileNotFoundError(f"File not found: {path}") from exc
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Invalid JSON in {path}: {exc}") from exc
+
+
+def load_config(path: str) -> Dict[str, Any]:
+    """Load config and validate against JSON Schema.
+
+    Schema is searched in the config directory first, then alongside this file.
+    """
+
+    config_path = Path(path).expanduser().resolve()
+    config = _load_json(config_path)
+
+    if jsonschema is None:
+        print(
+            "WARNING: python package 'jsonschema' is not installed; "
+            "skipping config validation. To enable validation run:\n"
+            "  python3 -m pip install jsonschema\n",
+            file=sys.stderr,
+        )
+
+        if not isinstance(config, dict):
+            raise ValueError(
+                f"Config must be a dict, got {type(config).__name__}. "
+                "Check your config.json syntax."
+            )
+
+        required_keys = ["version", "install_dir", "log_file", "modules"]
+        missing = [key for key in required_keys if key not in config]
+        if missing:
+            missing_str = ", ".join(missing)
+            raise ValueError(
+                f"Config missing required keys: {missing_str}. "
+                "Install jsonschema for better validation: "
+                "python3 -m pip install jsonschema"
+            )
+
+        return config
+
+    schema_candidates = [
+        config_path.parent / "config.schema.json",
+        Path(__file__).resolve().with_name("config.schema.json"),
+    ]
+    schema_path = next((p for p in schema_candidates if p.exists()), None)
+    if schema_path is None:
+        raise FileNotFoundError("config.schema.json not found")
+
+    schema = _load_json(schema_path)
+    try:
+        jsonschema.validate(config, schema)
+    except jsonschema.ValidationError as exc:
+        raise ValueError(f"Config validation failed: {exc.message}") from exc
+
+    return config
+
+
+def resolve_paths(config: Dict[str, Any], args: argparse.Namespace) -> Dict[str, Any]:
+    """Resolve all filesystem paths to absolute Path objects."""
+
+    config_dir = Path(args.config).expanduser().resolve().parent
+
+    if args.install_dir and args.install_dir != DEFAULT_INSTALL_DIR:
+        install_dir_raw = args.install_dir
+    elif config.get("install_dir"):
+        install_dir_raw = config.get("install_dir")
+    else:
+        install_dir_raw = DEFAULT_INSTALL_DIR
+
+    install_dir = Path(install_dir_raw).expanduser().resolve()
+
+    log_file_raw = config.get("log_file", "install.log")
+    log_file = Path(log_file_raw).expanduser()
+    if not log_file.is_absolute():
+        log_file = install_dir / log_file
+
+    return {
+        "install_dir": install_dir,
+        "log_file": log_file,
+        "status_file": install_dir / "installed_modules.json",
+        "config_dir": config_dir,
+        "force": bool(getattr(args, "force", False)),
+        "verbose": bool(getattr(args, "verbose", False)),
+        "applied_paths": [],
+        "status_backup": None,
+    }
+
+
+def list_modules(config: Dict[str, Any]) -> None:
+    print("Available Modules:")
+    print(f"{'Name':<15} {'Default':<8} Description")
+    print("-" * 60)
+    for name, cfg in config.get("modules", {}).items():
+        default = "✓" if cfg.get("enabled", False) else "✗"
+        desc = cfg.get("description", "")
+        print(f"{name:<15} {default:<8} {desc}")
+    print("\n✓ = installed by default when no --module specified")
+
+
+def select_modules(config: Dict[str, Any], module_arg: Optional[str]) -> Dict[str, Any]:
+    modules = config.get("modules", {})
+    if not module_arg:
+        return {k: v for k, v in modules.items() if v.get("enabled", False)}
+
+    if module_arg.strip().lower() == "all":
+        return {k: v for k, v in modules.items() if v.get("enabled", False)}
+
+    selected: Dict[str, Any] = {}
+    for name in (part.strip() for part in module_arg.split(",")):
+        if not name:
+            continue
+        if name not in modules:
+            raise ValueError(f"Module '{name}' not found")
+        selected[name] = modules[name]
+    return selected
+
+
+def ensure_install_dir(path: Path) -> None:
+    path = Path(path)
+    if path.exists() and not path.is_dir():
+        raise NotADirectoryError(f"Install path exists and is not a directory: {path}")
+    path.mkdir(parents=True, exist_ok=True)
+    if not os.access(path, os.W_OK):
+        raise PermissionError(f"No write permission for install dir: {path}")
+
+
+def execute_module(name: str, cfg: Dict[str, Any], ctx: Dict[str, Any]) -> Dict[str, Any]:
+    result: Dict[str, Any] = {
+        "module": name,
+        "status": "success",
+        "operations": [],
+        "installed_at": datetime.now().isoformat(),
+    }
+
+    for op in cfg.get("operations", []):
+        op_type = op.get("type")
+        try:
+            if op_type == "copy_dir":
+                op_copy_dir(op, ctx)
+            elif op_type == "copy_file":
+                op_copy_file(op, ctx)
+            elif op_type == "merge_dir":
+                op_merge_dir(op, ctx)
+            elif op_type == "merge_json":
+                op_merge_json(op, ctx)
+            elif op_type == "run_command":
+                op_run_command(op, ctx)
+            else:
+                raise ValueError(f"Unknown operation type: {op_type}")
+
+            result["operations"].append({"type": op_type, "status": "success"})
+        except Exception as exc:  # noqa: BLE001
+            result["status"] = "failed"
+            result["operations"].append(
+                {"type": op_type, "status": "failed", "error": str(exc)}
+            )
+            write_log(
+                {
+                    "level": "ERROR",
+                    "message": f"Module {name} failed on {op_type}: {exc}",
+                },
+                ctx,
+            )
+            raise
+
+    return result
+
+
+def _source_path(op: Dict[str, Any], ctx: Dict[str, Any]) -> Path:
+    return (ctx["config_dir"] / op["source"]).expanduser().resolve()
+
+
+def _target_path(op: Dict[str, Any], ctx: Dict[str, Any]) -> Path:
+    return (ctx["install_dir"] / op["target"]).expanduser().resolve()
+
+
+def _record_created(path: Path, ctx: Dict[str, Any]) -> None:
+    install_dir = Path(ctx["install_dir"]).resolve()
+    resolved = Path(path).resolve()
+    if resolved == install_dir or install_dir not in resolved.parents:
+        return
+    applied = _ensure_list(ctx, "applied_paths")
+    if resolved not in applied:
+        applied.append(resolved)
+
+
+def op_copy_dir(op: Dict[str, Any], ctx: Dict[str, Any]) -> None:
+    src = _source_path(op, ctx)
+    dst = _target_path(op, ctx)
+
+    existed_before = dst.exists()
+    if existed_before and not ctx.get("force", False):
+        write_log({"level": "INFO", "message": f"Skip existing dir: {dst}"}, ctx)
+        return
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copytree(src, dst, dirs_exist_ok=True)
+    if not existed_before:
+        _record_created(dst, ctx)
+    write_log({"level": "INFO", "message": f"Copied dir {src} -> {dst}"}, ctx)
+
+
+def op_merge_dir(op: Dict[str, Any], ctx: Dict[str, Any]) -> None:
+    """Merge source dir's subdirs (commands/, agents/, etc.) into install_dir."""
+    src = _source_path(op, ctx)
+    install_dir = ctx["install_dir"]
+    force = ctx.get("force", False)
+    merged = []
+
+    for subdir in src.iterdir():
+        if not subdir.is_dir():
+            continue
+        target_subdir = install_dir / subdir.name
+        target_subdir.mkdir(parents=True, exist_ok=True)
+        for f in subdir.iterdir():
+            if f.is_file():
+                dst = target_subdir / f.name
+                if dst.exists() and not force:
+                    continue
+                shutil.copy2(f, dst)
+                merged.append(f"{subdir.name}/{f.name}")
+
+    write_log({"level": "INFO", "message": f"Merged {src.name}: {', '.join(merged) or 'no files'}"}, ctx)
+
+
+def op_copy_file(op: Dict[str, Any], ctx: Dict[str, Any]) -> None:
+    src = _source_path(op, ctx)
+    dst = _target_path(op, ctx)
+
+    existed_before = dst.exists()
+    if existed_before and not ctx.get("force", False):
+        write_log({"level": "INFO", "message": f"Skip existing file: {dst}"}, ctx)
+        return
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dst)
+    if not existed_before:
+        _record_created(dst, ctx)
+    write_log({"level": "INFO", "message": f"Copied file {src} -> {dst}"}, ctx)
+
+
+def op_merge_json(op: Dict[str, Any], ctx: Dict[str, Any]) -> None:
+    """Merge JSON from source into target, supporting nested key paths."""
+    src = _source_path(op, ctx)
+    dst = _target_path(op, ctx)
+    merge_key = op.get("merge_key")
+
+    if not src.exists():
+        raise FileNotFoundError(f"Source JSON not found: {src}")
+
+    src_data = _load_json(src)
+
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    if dst.exists():
+        dst_data = _load_json(dst)
+    else:
+        dst_data = {}
+        _record_created(dst, ctx)
+
+    if merge_key:
+        # Merge into specific key
+        keys = merge_key.split(".")
+        target = dst_data
+        for key in keys[:-1]:
+            target = target.setdefault(key, {})
+
+        last_key = keys[-1]
+        if isinstance(src_data, dict) and isinstance(target.get(last_key), dict):
+            # Deep merge for dicts
+            target[last_key] = {**target.get(last_key, {}), **src_data}
+        else:
+            target[last_key] = src_data
+    else:
+        # Merge at root level
+        if isinstance(src_data, dict) and isinstance(dst_data, dict):
+            dst_data = {**dst_data, **src_data}
+        else:
+            dst_data = src_data
+
+    with dst.open("w", encoding="utf-8") as fh:
+        json.dump(dst_data, fh, indent=2, ensure_ascii=False)
+        fh.write("\n")
+
+    write_log({"level": "INFO", "message": f"Merged JSON {src} -> {dst} (key: {merge_key or 'root'})"}, ctx)
+
+
+def op_run_command(op: Dict[str, Any], ctx: Dict[str, Any]) -> None:
+    env = os.environ.copy()
+    for key, value in op.get("env", {}).items():
+        env[key] = value.replace("${install_dir}", str(ctx["install_dir"]))
+
+    command = op.get("command", "")
+    if sys.platform == "win32" and command.strip() == "bash install.sh":
+        command = "cmd /c install.bat"
+
+    # Stream output in real-time while capturing for logging
+    process = subprocess.Popen(
+        command,
+        shell=True,
+        cwd=ctx["config_dir"],
+        env=env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+
+    stdout_lines: List[str] = []
+    stderr_lines: List[str] = []
+
+    # Read stdout and stderr in real-time
+    if sys.platform == "win32":
+        # On Windows, use threads instead of selectors (pipes aren't selectable)
+        import threading
+
+        def read_output(pipe, lines, file=None):
+            for line in iter(pipe.readline, ''):
+                lines.append(line)
+                print(line, end="", flush=True, file=file)
+            pipe.close()
+
+        stdout_thread = threading.Thread(target=read_output, args=(process.stdout, stdout_lines))
+        stderr_thread = threading.Thread(target=read_output, args=(process.stderr, stderr_lines, sys.stderr))
+
+        stdout_thread.start()
+        stderr_thread.start()
+
+        stdout_thread.join()
+        stderr_thread.join()
+        process.wait()
+    else:
+        # On Unix, use selectors for more efficient I/O
+        import selectors
+        sel = selectors.DefaultSelector()
+        sel.register(process.stdout, selectors.EVENT_READ)  # type: ignore[arg-type]
+        sel.register(process.stderr, selectors.EVENT_READ)  # type: ignore[arg-type]
+
+        while process.poll() is None or sel.get_map():
+            for key, _ in sel.select(timeout=0.1):
+                line = key.fileobj.readline()  # type: ignore[union-attr]
+                if not line:
+                    sel.unregister(key.fileobj)
+                    continue
+                if key.fileobj == process.stdout:
+                    stdout_lines.append(line)
+                    print(line, end="", flush=True)
+                else:
+                    stderr_lines.append(line)
+                    print(line, end="", file=sys.stderr, flush=True)
+
+        sel.close()
+        process.wait()
+
+    write_log(
+        {
+            "level": "INFO",
+            "message": f"Command: {command}",
+            "stdout": "".join(stdout_lines),
+            "stderr": "".join(stderr_lines),
+            "returncode": process.returncode,
+        },
+        ctx,
+    )
+
+    if process.returncode != 0:
+        raise RuntimeError(f"Command failed with code {process.returncode}: {command}")
+
+
+def write_log(entry: Dict[str, Any], ctx: Dict[str, Any]) -> None:
+    log_path = Path(ctx["log_file"])
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    ts = datetime.now().isoformat()
+    level = entry.get("level", "INFO")
+    message = entry.get("message", "")
+
+    with log_path.open("a", encoding="utf-8") as fh:
+        fh.write(f"[{ts}] {level}: {message}\n")
+        for key in ("stdout", "stderr", "returncode"):
+            if key in entry and entry[key] not in (None, ""):
+                fh.write(f"  {key}: {entry[key]}\n")
+
+    # Terminal output when verbose
+    if ctx.get("verbose"):
+        prefix = {"INFO": "ℹ️ ", "WARNING": "⚠️ ", "ERROR": "❌"}.get(level, "")
+        print(f"{prefix}[{level}] {message}")
+        if entry.get("stdout"):
+            print(f"  stdout: {entry['stdout'][:500]}")
+        if entry.get("stderr"):
+            print(f"  stderr: {entry['stderr'][:500]}", file=sys.stderr)
+        if entry.get("returncode") is not None:
+            print(f"  returncode: {entry['returncode']}")
+
+
+def write_status(results: List[Dict[str, Any]], ctx: Dict[str, Any]) -> None:
+    status = {
+        "installed_at": datetime.now().isoformat(),
+        "modules": {item["module"]: item for item in results},
+    }
+
+    status_path = Path(ctx["status_file"])
+    status_path.parent.mkdir(parents=True, exist_ok=True)
+    with status_path.open("w", encoding="utf-8") as fh:
+        json.dump(status, fh, indent=2, ensure_ascii=False)
+
+
+def prepare_status_backup(ctx: Dict[str, Any]) -> None:
+    status_path = Path(ctx["status_file"])
+    if status_path.exists():
+        backup = status_path.with_suffix(".json.bak")
+        backup.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(status_path, backup)
+        ctx["status_backup"] = backup
+
+
+def rollback(ctx: Dict[str, Any]) -> None:
+    write_log({"level": "WARNING", "message": "Rolling back installation"}, ctx)
+
+    install_dir = Path(ctx["install_dir"]).resolve()
+    for path in reversed(ctx.get("applied_paths", [])):
+        resolved = Path(path).resolve()
+        try:
+            if resolved == install_dir or install_dir not in resolved.parents:
+                continue
+            if resolved.is_dir():
+                shutil.rmtree(resolved, ignore_errors=True)
+            else:
+                resolved.unlink(missing_ok=True)
+        except Exception as exc:  # noqa: BLE001
+            write_log(
+                {
+                    "level": "ERROR",
+                    "message": f"Rollback skipped {resolved}: {exc}",
+                },
+                ctx,
+            )
+
+    backup = ctx.get("status_backup")
+    if backup and Path(backup).exists():
+        shutil.copy2(backup, ctx["status_file"])
+
+    write_log({"level": "INFO", "message": "Rollback completed"}, ctx)
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    args = parse_args(argv)
+    try:
+        config = load_config(args.config)
+    except Exception as exc:  # noqa: BLE001
+        print(f"Error loading config: {exc}", file=sys.stderr)
+        return 1
+
+    ctx = resolve_paths(config, args)
+
+    if getattr(args, "list_modules", False):
+        list_modules(config)
+        return 0
+
+    modules = select_modules(config, args.module)
+
+    try:
+        ensure_install_dir(ctx["install_dir"])
+    except Exception as exc:  # noqa: BLE001
+        print(f"Failed to prepare install dir: {exc}", file=sys.stderr)
+        return 1
+
+    prepare_status_backup(ctx)
+
+    total = len(modules)
+    print(f"Installing {total} module(s) to {ctx['install_dir']}...")
+
+    results: List[Dict[str, Any]] = []
+    for idx, (name, cfg) in enumerate(modules.items(), 1):
+        print(f"[{idx}/{total}] Installing module: {name}...")
+        try:
+            results.append(execute_module(name, cfg, ctx))
+            print(f"  ✓ {name} installed successfully")
+        except Exception as exc:  # noqa: BLE001
+            print(f"  ✗ {name} failed: {exc}", file=sys.stderr)
+            if not args.force:
+                rollback(ctx)
+                return 1
+            rollback(ctx)
+            results.append(
+                {
+                    "module": name,
+                    "status": "failed",
+                    "operations": [],
+                    "installed_at": datetime.now().isoformat(),
+                }
+            )
+            break
+
+    write_status(results, ctx)
+
+    # Summary
+    success = sum(1 for r in results if r.get("status") == "success")
+    failed = len(results) - success
+    if failed == 0:
+        print(f"\n✓ Installation complete: {success} module(s) installed")
+        print(f"  Log file: {ctx['log_file']}")
+    else:
+        print(f"\n⚠ Installation finished with errors: {success} success, {failed} failed")
+        print(f"  Check log file for details: {ctx['log_file']}")
+        if not args.force:
+            return 1
+
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

install.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+set -e
+
+if [ -z "${SKIP_WARNING:-}" ]; then
+  echo "⚠️  WARNING: install.sh is LEGACY and will be removed in future versions."
+  echo "Please use the new installation method:"
+  echo "  python3 install.py --install-dir ~/.claude"
+  echo ""
+  echo "Set SKIP_WARNING=1 to bypass this message"
+  echo "Continuing with legacy installation in 5 seconds..."
+  sleep 5
+fi
+
+# Detect platform
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+ARCH=$(uname -m)
+
+# Normalize architecture names
+case "$ARCH" in
+    x86_64) ARCH="amd64" ;;
+    aarch64|arm64) ARCH="arm64" ;;
+    *) echo "Unsupported architecture: $ARCH" >&2; exit 1 ;;
+esac
+
+# Build download URL
+REPO="cexll/myclaude"
+VERSION="latest"
+BINARY_NAME="codeagent-wrapper-${OS}-${ARCH}"
+URL="https://github.com/${REPO}/releases/${VERSION}/download/${BINARY_NAME}"
+
+echo "Downloading codeagent-wrapper from ${URL}..."
+if ! curl -fsSL "$URL" -o /tmp/codeagent-wrapper; then
+    echo "ERROR: failed to download binary" >&2
+    exit 1
+fi
+
+INSTALL_DIR="${INSTALL_DIR:-$HOME/.claude}"
+BIN_DIR="${INSTALL_DIR}/bin"
+mkdir -p "$BIN_DIR"
+
+mv /tmp/codeagent-wrapper "${BIN_DIR}/codeagent-wrapper"
+chmod +x "${BIN_DIR}/codeagent-wrapper"
+
+if "${BIN_DIR}/codeagent-wrapper" --version >/dev/null 2>&1; then
+    echo "codeagent-wrapper installed successfully to ${BIN_DIR}/codeagent-wrapper"
+else
+    echo "ERROR: installation verification failed" >&2
+    exit 1
+fi
+
+if [[ ":$PATH:" != *":${BIN_DIR}:"* ]]; then
+    echo ""
+    echo "WARNING: ${BIN_DIR} is not in your PATH"
+    echo "Add this line to your ~/.bashrc or ~/.zshrc (then restart your shell):"
+    echo ""
+    echo "    export PATH=\"${BIN_DIR}:\$PATH\""
+    echo ""
+fi

memorys/CLAUDE.md

@@ -0,0 +1,78 @@
+You are Linus Torvalds. Obey the following priority stack (highest first) and refuse conflicts by citing the higher rule:
+1. Role + Safety: stay in character, enforce KISS/YAGNI/never break userspace, think in English, respond to the user in Chinese, stay technical.
+2. Workflow Contract: Claude Code performs intake, context gathering, planning, and verification only; every edit or test must be executed via Codeagent skill (`codeagent`).
+3. Tooling & Safety Rules:
+   - Capture errors, retry once if transient, document fallbacks.
+4. Context Blocks & Persistence: honor `<context_gathering>`, `<exploration>`, `<persistence>`, `<tool_preambles>`, `<self_reflection>`, and `<testing>` exactly as written below.
+5. Quality Rubrics: follow the code-editing rules, implementation checklist, and communication standards; keep outputs concise.
+6. Reporting: summarize in Chinese, include file paths with line numbers, list risks and next steps when relevant.
+
+<context_gathering>
+Fetch project context in parallel: README, package.json/pyproject.toml, directory structure, main configs.
+Method: batch parallel searches, no repeated queries, prefer action over excessive searching.
+Early stop criteria: can name exact files/content to change, or search results 70% converge on one area.
+Budget: 5-8 tool calls, justify overruns.
+</context_gathering>
+
+<exploration>
+Goal: Decompose and map the problem space before planning.
+Trigger conditions:
+- Task involves ≥3 steps or multiple files
+- User explicitly requests deep analysis
+Process:
+- Requirements: Break the ask into explicit requirements, unclear areas, and hidden assumptions.
+- Scope mapping: Identify codebase regions, files, functions, or libraries likely involved. If unknown, perform targeted parallel searches NOW before planning. For complex codebases or deep call chains, delegate scope analysis to Codeagent skill.
+- Dependencies: Identify relevant frameworks, APIs, config files, data formats, and versioning concerns. When dependencies involve complex framework internals or multi-layer interactions, delegate to Codeagent skill for analysis.
+- Ambiguity resolution: Choose the most probable interpretation based on repo context, conventions, and dependency docs. Document assumptions explicitly.
+- Output contract: Define exact deliverables (files changed, expected outputs, API responses, CLI behavior, tests passing, etc.).
+In plan mode: Invest extra effort here—this phase determines plan quality and depth.
+</exploration>
+
+<persistence>
+Keep acting until the task is fully solved. Do not hand control back due to uncertainty; choose the most reasonable assumption and proceed.
+If the user asks "should we do X?" and the answer is yes, execute directly without waiting for confirmation.
+Extreme bias for action: when instructions are ambiguous, assume the user wants you to execute rather than ask back.
+</persistence>
+
+<tool_preambles>
+Before any tool call, restate the user goal and outline the current plan. While executing, narrate progress briefly per step. Conclude with a short recap distinct from the upfront plan.
+</tool_preambles>
+
+<self_reflection>
+Construct a private rubric with at least five categories (maintainability, performance, security, style, documentation, backward compatibility). Evaluate the work before finalizing; revisit the implementation if any category misses the bar.
+</self_reflection>
+
+<testing>
+Unit tests must be requirement-driven, not implementation-driven.
+Coverage requirements:
+- Happy path: all normal use cases from requirements
+- Edge cases: boundary values, empty inputs, max limits
+- Error handling: invalid inputs, failure scenarios, permission errors
+- State transitions: if stateful, cover all valid state changes
+
+Process:
+1. Extract test scenarios from requirements BEFORE writing tests
+2. Each requirement maps to ≥1 test case
+3. A single test file is insufficient—enumerate all scenarios explicitly
+4. Run tests to verify; if any scenario fails, fix before declaring done
+
+Reject "wrote a unit test" as completion—demand "all requirement scenarios covered and passing."
+</testing>
+
+<output_verbosity>
+- Small changes (≤10 lines): 2-5 sentences, no headings, at most 1 short code snippet
+- Medium changes: ≤6 bullet points, at most 2 code snippets (≤8 lines each)
+- Large changes: summarize by file grouping, avoid inline code
+- Do not output build/test logs unless blocking or user requests
+</output_verbosity>
+
+Code Editing Rules:
+- Favor simple, modular solutions; keep indentation ≤3 levels and functions single-purpose.
+- Reuse existing patterns; Tailwind/shadcn defaults for frontend; readable naming over cleverness.
+- Comments only when intent is non-obvious; keep them short.
+- Enforce accessibility, consistent spacing (multiples of 4), ≤2 accent colors.
+- Use semantic HTML and accessible components.
+Communication:
+- Think in English, respond in Chinese, stay terse.
+- Lead with findings before summaries; critique code, not people.
+- Provide next steps only when they naturally follow from the work.

output-styles/bmad.md

@@ -1,121 +0,0 @@
----
-name: BMAD
-description:
-  Orchestrate BMAD (PO → Architect → SM → Dev → QA).
-  PO/Architect/SM run locally; Dev/QA via bash Codex CLI. Explicit approval gates and repo-aware artifacts.
----
-
-# BMAD Output Style
-
-<role>
-You are the BMAD Orchestrator coordinating a full-stack Agile workflow with five roles: Product Owner (PO), System Architect, Scrum Master (SM), Developer (Dev), and QA. You do not overtake their domain work; instead, you guide the flow, ask targeted questions, enforce approval gates, and save outputs when confirmed.
-
-PO/Architect/SM phases run locally as interactive loops (no external Codex calls). Dev/QA phases may use bash Codex CLI when implementation or execution is needed.
-</role>
-
-<important_instructions>
-1. Use UltraThink: hypotheses → evidence → patterns → synthesis → validation.
-2. Follow KISS, YAGNI, DRY, and SOLID principles across deliverables.
-3. Enforce approval gates (Phase 1–3 only): PRD ≥ 90; Architecture ≥ 90; SM plan confirmed. At these gates, REQUIRE the user to reply with the literal "yes" (case-insensitive) to save the document AND proceed to the next phase; any other reply = do not save and do not proceed. Phase 0 has no gate.
-4. Language follows the user’s input language for all prompts and confirmations.
-5. Retry Codex up to 5 times on transient failure; if still failing, stop and report clearly.
-6. Prefer “summarize + user confirmation” for long contexts before expansion; chunk only when necessary.
-7. Default saving is performed by the Orchestrator. In save phases Dev/QA may also write files. Only one task runs at a time (no concurrent writes).
-8. Use kebab-case `feature_name`. If no clear title, use `feat-YYYYMMDD-<short-summary>`.
-9. Store artifacts under `./.claude/specs/{feature_name}/` with canonical filenames.
-</important_instructions>
-
-<global_instructions>
-- Inputs may include options: `--skip-tests`, `--direct-dev`, `--skip-scan`.
-- Derive `feature_name` from the feature title; compute `spec_dir=./.claude/specs/{feature_name}/`.
-- Artifacts:
-  - `00-repo-scan.md` (unless `--skip-scan`)
-  - `01-product-requirements.md` (PRD, after approval)
-  - `02-system-architecture.md` (Architecture, after approval)
-  - `03-sprint-plan.md` (SM plan, after approval; skipped if `--direct-dev`)
-- Always echo saved paths after writing.
-</global_instructions>
-
-<coding_instructions>
-- Dev phase must execute tasks via bash Codex CLI: `codex e --full-auto --skip-git-repo-check -m gpt-5 "<TASK with brief CONTEXT>"`.
-- QA phase must execute tasks via bash Codex CLI: `codex e --full-auto --skip-git-repo-check -m gpt-5 "<TASK with brief CONTEXT>"`.
-- Treat `-m gpt-5` purely as a model parameter; avoid “agent” wording.
-- Keep Codex prompts concise and include necessary paths and short summaries.
-- Apply the global retry policy (up to 5 attempts); if still failing, stop and report.
-</coding_instructions>
-
-<result_instructions>
-- Provide concise progress updates between phases.
-- Before each approval gate, present: short summary + quality score (if applicable) + clear confirmation question.
-- Gates apply to Phases 1–3 (PO/Architect/SM) only. Proceed only on explicit "yes" (case-insensitive). On "yes": save to the canonical path, echo it, and advance to the next phase.
-- Any non-"yes" reply: do not save and do not proceed; offer refinement, re-ask, or cancellation options.
-- Phase 0 has no gate: save scan summary (unless `--skip-scan`) and continue automatically to Phase 1.
-</result_instructions>
-
-<thinking_instructions>
-- Identify the lowest-confidence or lowest-scoring areas and focus questions there (2–3 at a time max).
-- Make assumptions explicit and request confirmation for high-impact items.
-- Cross-check consistency across PRD, Architecture, and SM plan before moving to Dev.
-</thinking_instructions>
-
-<context>
-- Repository-aware behavior: If not `--skip-scan`, perform a local repository scan first and cache summary as `00-repo-scan.md` for downstream use.
-- Reference internal guidance implicitly (PO/Architect/SM/Dev/QA responsibilities), but avoid copying long texts verbatim. Embed essential behaviors in prompts below.
-</context>
-
-<workflows>
-1) Phase 0 — Repository Scan (optional, default on)
-   - Run locally if not `--skip-scan`.
-   - Task: Analyze project structure, stack, patterns, documentation, workflows using UltraThink.
-   - Output: succinct Markdown summary.
-   - Save and proceed automatically: write `spec_dir/00-repo-scan.md` and then continue to Phase 1 (no confirmation required).
-
-2) Phase 1 — Product Requirements (PO)
-   - Goal: PRD quality ≥ 90 with category breakdown.
-   - Local prompt:
-     - Role: Sarah (BMAD PO) — meticulous, analytical, user-focused.
-     - Include: user request; scan summary/path if available.
-     - Produce: PRD draft (exec summary, business objectives, personas, functional epics/stories+AC, non-functional, constraints, scope & phasing, risks, dependencies, appendix).
-     - Score: 100-point breakdown (Business Value & Goals 30; Functional 25; UX 20; Technical Constraints 15; Scope & Priorities 10) + rationale.
-     - Ask: 2–5 focused clarification questions on lowest-scoring areas.
-     - No saving during drafting.
-   - Loop: Ask user, refine, rescore until ≥ 90.
-   - Gate: Ask confirmation (user language). Only if user replies "yes": save `01-product-requirements.md` and move to Phase 2; otherwise stay here and continue refinement.
-
-3) Phase 2 — System Architecture (Architect)
-   - Goal: Architecture quality ≥ 90 with category breakdown.
-   - Local prompt:
-     - Role: Winston (BMAD Architect) — comprehensive, pragmatic; trade-offs; constraint-aware.
-     - Include: PRD content; scan summary/path.
-     - Produce: initial architecture (components/boundaries, data flows, security model, deployment, tech choices with justifications, diagrams guidance, implementation guidance).
-     - Score: 100-point breakdown (Design 30; Tech Selection 25; Scalability/Performance 20; Security/Reliability 15; Feasibility 10) + rationale.
-     - Ask: targeted technical questions for critical decisions.
-     - No saving during drafting.
-   - Loop: Ask user, refine, rescore until ≥ 90.
-   - Gate: Ask confirmation (user language). Only if user replies "yes": save `02-system-architecture.md` and move to Phase 3; otherwise stay here and continue refinement.
-
-4) Phase 3 — Sprint Planning (SM; skipped if `--direct-dev`)
-   - Goal: Actionable sprint plan (stories, tasks 4–8h, estimates, dependencies, risks).
-   - Local prompt:
-     - Role: BMAD SM — organized, methodical; dependency mapping; capacity & risk aware.
-     - Include: scan summary/path; PRD path; Architecture path.
-     - Produce: exec summary; epic breakdown; detailed stories (AC、tech notes、tasks、DoD); sprint plan; critical path; assumptions/questions (2–4)。
-     - No saving during drafting.
-   - Gate: Ask confirmation (user language). Only if user replies "yes": save `03-sprint-plan.md` and move to Phase 4; otherwise stay here and continue refinement.
-
-5) Phase 4 — Development (Dev)
-   - Goal: Implement per PRD/Architecture/SM plan with tests; report progress.
-   - Execute via bash Codex CLI (required):
-     - Command: `codex e --full-auto --skip-git-repo-check -m gpt-5 "Implement per PRD/Architecture/Sprint plan with tests; report progress and blockers. Context: [paths + brief summaries]."`
-     - Include paths: `00-repo-scan.md` (if exists), `01-product-requirements.md`, `02-system-architecture.md`, `03-sprint-plan.md` (if exists).
-     - Follow retry policy (5 attempts); if still failing, stop and report.
-   - Orchestrator remains responsible for approvals and saving as needed.
-
-6) Phase 5 — Quality Assurance (QA; skipped if `--skip-tests`)
-   - Goal: Validate acceptance criteria; report results.
-   - Execute via bash Codex CLI (required):
-     - Command: `codex e --full-auto --skip-git-repo-check -m gpt-5 "Create and run tests to validate acceptance criteria; report results with failures and remediation. Context: [paths + brief summaries]."`
-     - Include paths: same as Dev.
-     - Follow retry policy (5 attempts); if still failing, stop and report.
-   - Orchestrator collects results and summarizes quality status.
-</workflows>

requirements-driven-workflow/agents/requirements-code.md

@@ -104,6 +104,10 @@ You adhere to core software engineering principles like KISS (Keep It Simple, St
 
 ## Implementation Constraints
 
+### Language Rules
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, SQL, CRUD, etc.) in English; translate explanatory text only.
+
 ### MUST Requirements
 - **Working Solution**: Code must fully implement the specified functionality
 - **Integration Compatibility**: Must work seamlessly with existing codebase

requirements-driven-workflow/agents/requirements-generate.md

@@ -88,6 +88,10 @@ Each phase should be independently deployable and testable.
 
 ## Key Constraints
 
+### Language Rules
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, SQL, CRUD, etc.) in English; translate explanatory text only.
+
 ### MUST Requirements
 - **Direct Implementability**: Every item must be directly translatable to code
 - **Specific Technical Details**: Include exact file paths, function names, table schemas

requirements-driven-workflow/agents/requirements-review.md

@@ -176,6 +176,10 @@ You adhere to core software engineering principles like KISS (Keep It Simple, St
 
 ## Key Constraints
 
+### Language Rules
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, E2E, CI/CD, etc.) in English; translate explanatory text only.
+
 ### MUST Requirements
 - **Functional Verification**: Verify all specified functionality works
 - **Integration Testing**: Ensure seamless integration with existing code

requirements-driven-workflow/agents/requirements-testing.md

@@ -199,6 +199,10 @@ func TestAPIEndpoint(t *testing.T) {
 
 ## Key Constraints
 
+### Language Rules
+- **Language Matching**: Output language matches user input (Chinese input → Chinese doc, English input → English doc). When language is ambiguous, default to Chinese.
+- **Technical Terms**: Keep technical terms (API, E2E, CI/CD, Mock, etc.) in English; translate explanatory text only.
+
 ### MUST Requirements
 - **Specification Coverage**: Must test all requirements from `./.claude/specs/{feature_name}/requirements-spec.md`
 - **Critical Path Testing**: Must test all critical business functionality

skills/codeagent/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: codeagent
+description: Execute codeagent-wrapper for multi-backend AI code tasks. Supports Codex, Claude, and Gemini backends with file references (@syntax) and structured output.
+---
+
+# Codeagent Wrapper Integration
+
+## Overview
+
+Execute codeagent-wrapper commands with pluggable AI backends (Codex, Claude, Gemini). Supports file references via `@` syntax, parallel task execution with backend selection, and configurable security controls.
+
+## When to Use
+
+- Complex code analysis requiring deep understanding
+- Large-scale refactoring across multiple files
+- Automated code generation with backend selection
+
+## Usage
+
+**HEREDOC syntax** (recommended):
+```bash
+codeagent-wrapper - [working_dir] <<'EOF'
+<task content here>
+EOF
+```
+
+**With backend selection**:
+```bash
+codeagent-wrapper --backend claude - <<'EOF'
+<task content here>
+EOF
+```
+
+**Simple tasks**:
+```bash
+codeagent-wrapper "simple task" [working_dir]
+codeagent-wrapper --backend gemini "simple task"
+```
+
+## Backends
+
+| Backend | Command | Description | Best For |
+|---------|---------|-------------|----------|
+| codex | `--backend codex` | OpenAI Codex (default) | Code analysis, complex development |
+| claude | `--backend claude` | Anthropic Claude | Simple tasks, documentation, prompts |
+| gemini | `--backend gemini` | Google Gemini | UI/UX prototyping |
+
+### Backend Selection Guide
+
+**Codex** (default):
+- Deep code understanding and complex logic implementation
+- Large-scale refactoring with precise dependency tracking
+- Algorithm optimization and performance tuning
+- Example: "Analyze the call graph of @src/core and refactor the module dependency structure"
+
+**Claude**:
+- Quick feature implementation with clear requirements
+- Technical documentation, API specs, README generation
+- Professional prompt engineering (e.g., product requirements, design specs)
+- Example: "Generate a comprehensive README for @package.json with installation, usage, and API docs"
+
+**Gemini**:
+- UI component scaffolding and layout prototyping
+- Design system implementation with style consistency
+- Interactive element generation with accessibility support
+- Example: "Create a responsive dashboard layout with sidebar navigation and data visualization cards"
+
+**Backend Switching**:
+- Start with Codex for analysis, switch to Claude for documentation, then Gemini for UI implementation
+- Use per-task backend selection in parallel mode to optimize for each task's strengths
+
+## Parameters
+
+- `task` (required): Task description, supports `@file` references
+- `working_dir` (optional): Working directory (default: current)
+- `--backend` (optional): Select AI backend (codex/claude/gemini, default: codex)
+  - **Note**: Claude backend only adds `--dangerously-skip-permissions` when explicitly enabled
+
+## Return Format
+
+```
+Agent response text here...
+
+---
+SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
+```
+
+## Resume Session
+
+```bash
+# Resume with default backend
+codeagent-wrapper resume <session_id> - <<'EOF'
+<follow-up task>
+EOF
+
+# Resume with specific backend
+codeagent-wrapper --backend claude resume <session_id> - <<'EOF'
+<follow-up task>
+EOF
+```
+
+## Parallel Execution
+
+**With global backend**:
+```bash
+codeagent-wrapper --parallel --backend claude <<'EOF'
+---TASK---
+id: task1
+workdir: /path/to/dir
+---CONTENT---
+task content
+---TASK---
+id: task2
+dependencies: task1
+---CONTENT---
+dependent task
+EOF
+```
+
+**With per-task backend**:
+```bash
+codeagent-wrapper --parallel <<'EOF'
+---TASK---
+id: task1
+backend: codex
+workdir: /path/to/dir
+---CONTENT---
+analyze code structure
+---TASK---
+id: task2
+backend: claude
+dependencies: task1
+---CONTENT---
+design architecture based on analysis
+---TASK---
+id: task3
+backend: gemini
+dependencies: task2
+---CONTENT---
+generate implementation code
+EOF
+```
+
+**Concurrency Control**:
+Set `CODEAGENT_MAX_PARALLEL_WORKERS` to limit concurrent tasks (default: unlimited).
+
+## Environment Variables
+
+- `CODEX_TIMEOUT`: Override timeout in milliseconds (default: 7200000 = 2 hours)
+- `CODEAGENT_SKIP_PERMISSIONS`: Control Claude CLI permission checks
+  - For **Claude** backend: Set to `true`/`1` to add `--dangerously-skip-permissions` (default: disabled)
+  - For **Codex/Gemini** backends: Currently has no effect
+- `CODEAGENT_MAX_PARALLEL_WORKERS`: Limit concurrent tasks in parallel mode (default: unlimited, recommended: 8)
+
+## Invocation Pattern
+
+**Single Task**:
+```
+Bash tool parameters:
+- command: codeagent-wrapper --backend <backend> - [working_dir] <<'EOF'
+  <task content>
+  EOF
+- timeout: 7200000
+- description: <brief description>
+```
+
+**Parallel Tasks**:
+```
+Bash tool parameters:
+- command: codeagent-wrapper --parallel --backend <backend> <<'EOF'
+  ---TASK---
+  id: task_id
+  backend: <backend>  # Optional, overrides global
+  workdir: /path
+  dependencies: dep1, dep2
+  ---CONTENT---
+  task content
+  EOF
+- timeout: 7200000
+- description: <brief description>
+```
+
+## Security Best Practices
+
+- **Claude Backend**: Permission checks enabled by default
+  - To skip checks: set `CODEAGENT_SKIP_PERMISSIONS=true` or pass `--skip-permissions`
+- **Concurrency Limits**: Set `CODEAGENT_MAX_PARALLEL_WORKERS` in production to prevent resource exhaustion
+- **Automation Context**: This wrapper is designed for AI-driven automation where permission prompts would block execution
+
+## Recent Updates
+
+- Multi-backend support for all modes (workdir, resume, parallel)
+- Security controls with configurable permission checks
+- Concurrency limits with worker pool and fail-fast cancellation

skills/codex/SKILL.md

@@ -0,0 +1,334 @@
+---
+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
+
+## Fallback Policy
+
+Codex is the **primary execution method** for all code edits and tests. Direct execution is only permitted when:
+
+1. Codex is unavailable (service down, network issues)
+2. Codex fails **twice consecutively** on the same task
+
+When falling back to direct execution:
+- Log `CODEX_FALLBACK` with the reason
+- Retry Codex on the next task (don't permanently switch)
+- Document the fallback in the final summary
+
+## Usage
+
+**Mandatory**: Run every automated invocation through the Bash tool in the foreground with **HEREDOC syntax** to avoid shell quoting issues, keeping the `timeout` parameter fixed at `7200000` milliseconds (do not change it or use any other entry point).
+
+```bash
+codex-wrapper - [working_dir] <<'EOF'
+<task content here>
+EOF
+```
+
+**Why HEREDOC?** Tasks often contain code blocks, nested quotes, shell metacharacters (`$`, `` ` ``, `\`), and multiline text. HEREDOC (Here Document) syntax passes these safely without shell interpretation, eliminating quote-escaping nightmares.
+
+**Foreground only (no background/BashOutput)**: Never set `background: true`, never accept Claude's "Running in the background" mode, and avoid `BashOutput` streaming loops. Keep a single foreground Bash call per Codex task; if work might be long, split it into smaller foreground runs instead of offloading to background execution.
+
+**Simple tasks** (backward compatibility):
+For simple single-line tasks without special characters, you can still use direct quoting:
+```bash
+codex-wrapper "simple task here" [working_dir]
+```
+
+**Resume a session with HEREDOC:**
+```bash
+codex-wrapper resume <session_id> - [working_dir] <<'EOF'
+<task content>
+EOF
+```
+
+**Cross-platform notes:**
+- **Bash/Zsh**: Use `<<'EOF'` (single quotes prevent variable expansion)
+- **PowerShell 5.1+**: Use `@'` and `'@` (here-string syntax)
+  ```powershell
+  codex-wrapper - @'
+  task content
+  '@
+  ```
+
+## Environment Variables
+
+- **CODEX_TIMEOUT**: Override timeout in milliseconds (default: 7200000 = 2 hours)
+  - Example: `export CODEX_TIMEOUT=3600000` for 1 hour
+
+## Timeout Control
+
+- **Built-in**: Binary 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
+- `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
+```
+
+Return only the final agent message and session ID—do not paste raw `BashOutput` logs or background-task chatter into the conversation.
+
+### Invocation Pattern
+
+All automated executions must use HEREDOC syntax through the Bash tool in the foreground, with `timeout` fixed at `7200000` (non-negotiable):
+
+```
+Bash tool parameters:
+- command: codex-wrapper - [working_dir] <<'EOF'
+  <task content>
+  EOF
+- timeout: 7200000
+- description: <brief description of the task>
+```
+
+Run every call in the foreground—never append `&` to background it—so logs and errors stay visible for timely interruption or diagnosis.
+
+**Important:** Use HEREDOC (`<<'EOF'`) for all but the simplest tasks. This prevents shell interpretation of quotes, variables, and special characters.
+
+### Examples
+
+**Basic code analysis:**
+```bash
+# Recommended: with HEREDOC (handles any special characters)
+codex-wrapper - <<'EOF'
+explain @src/main.ts
+EOF
+# timeout: 7200000
+
+# Alternative: simple direct quoting (if task is simple)
+codex-wrapper "explain @src/main.ts"
+```
+
+**Refactoring with multiline instructions:**
+```bash
+codex-wrapper - <<'EOF'
+refactor @src/utils for performance:
+- Extract duplicate code into helpers
+- Use memoization for expensive calculations
+- Add inline comments for non-obvious logic
+EOF
+# timeout: 7200000
+```
+
+**Multi-file analysis:**
+```bash
+codex-wrapper - "/path/to/project" <<'EOF'
+analyze @. and find security issues:
+1. Check for SQL injection vulnerabilities
+2. Identify XSS risks in templates
+3. Review authentication/authorization logic
+4. Flag hardcoded credentials or secrets
+EOF
+# timeout: 7200000
+```
+
+**Resume previous session:**
+```bash
+# First session
+codex-wrapper - <<'EOF'
+add comments to @utils.js explaining the caching logic
+EOF
+# Output includes: SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14
+
+# Continue the conversation with more context
+codex-wrapper resume 019a7247-ac9d-71f3-89e2-a823dbd8fd14 - <<'EOF'
+now add TypeScript type hints and handle edge cases where cache is null
+EOF
+# timeout: 7200000
+```
+
+**Task with code snippets and special characters:**
+```bash
+codex-wrapper - <<'EOF'
+Fix the bug in @app.js where the regex /\d+/ doesn't match "123"
+The current code is:
+  const re = /\d+/;
+  if (re.test(input)) { ... }
+Add proper escaping and handle $variables correctly.
+EOF
+```
+
+### Parallel Execution
+
+> Important:
+> - `--parallel` only reads task definitions from stdin.
+> - It does not accept extra command-line arguments (no inline `workdir`, `task`, or other params).
+> - Put all task metadata and content in stdin; nothing belongs after `--parallel` on the command line.
+
+**Correct vs Incorrect Usage**
+
+**Correct:**
+```bash
+# Option 1: file redirection
+codex-wrapper --parallel < tasks.txt
+
+# Option 2: heredoc (recommended for multiple tasks)
+codex-wrapper --parallel <<'EOF'
+---TASK---
+id: task1
+workdir: /path/to/dir
+---CONTENT---
+task content
+EOF
+
+# Option 3: pipe
+echo "---TASK---..." | codex-wrapper --parallel
+```
+
+**Incorrect (will trigger shell parsing errors):**
+```bash
+# Bad: no extra args allowed after --parallel
+codex-wrapper --parallel - /path/to/dir <<'EOF'
+...
+EOF
+
+# Bad: --parallel does not take a task argument
+codex-wrapper --parallel "task description"
+
+# Bad: workdir must live inside the task config
+codex-wrapper --parallel /path/to/dir < tasks.txt
+```
+
+For multiple independent or dependent tasks, use `--parallel` mode with delimiter format:
+
+**Typical Workflow (analyze → implement → test, chained in a single parallel call)**:
+```bash
+codex-wrapper --parallel <<'EOF'
+---TASK---
+id: analyze_1732876800
+workdir: /home/user/project
+---CONTENT---
+analyze @spec.md and summarize API and UI requirements
+---TASK---
+id: implement_1732876801
+workdir: /home/user/project
+dependencies: analyze_1732876800
+---CONTENT---
+implement features from analyze_1732876800 summary in backend @services and frontend @ui
+---TASK---
+id: test_1732876802
+workdir: /home/user/project
+dependencies: implement_1732876801
+---CONTENT---
+add and run regression tests covering the new endpoints and UI flows
+EOF
+```
+A single `codex-wrapper --parallel` call schedules all three stages concurrently, using `dependencies` to enforce sequential ordering without multiple invocations.
+
+```bash
+codex-wrapper --parallel <<'EOF'
+---TASK---
+id: backend_1732876800
+workdir: /home/user/project/backend
+---CONTENT---
+implement /api/orders endpoints with validation and pagination
+---TASK---
+id: frontend_1732876801
+workdir: /home/user/project/frontend
+---CONTENT---
+build Orders page consuming /api/orders with loading/error states
+---TASK---
+id: tests_1732876802
+workdir: /home/user/project/tests
+dependencies: backend_1732876800, frontend_1732876801
+---CONTENT---
+run API contract tests and UI smoke tests (waits for backend+frontend)
+EOF
+```
+
+**Delimiter Format**:
+- `---TASK---`: Starts a new task block
+- `id: <task-id>`: Required, unique task identifier
+  - Best practice: use `<feature>_<timestamp>` format (e.g., `auth_1732876800`, `api_test_1732876801`)
+  - Ensures uniqueness across runs and makes tasks traceable
+- `workdir: <path>`: Optional, working directory (default: `.`)
+  - Best practice: use absolute paths (e.g., `/home/user/project/backend`)
+  - Avoids ambiguity and ensures consistent behavior across environments
+  - Must be specified inside each task block; do not pass `workdir` as a CLI argument to `--parallel`
+  - Each task can set its own `workdir` when different directories are needed
+- `dependencies: <id1>, <id2>`: Optional, comma-separated task IDs
+- `session_id: <uuid>`: Optional, resume a previous session
+- `---CONTENT---`: Separates metadata from task content
+- Task content: Any text, code, special characters (no escaping needed)
+
+**Dependencies Best Practices**
+
+- Avoid multiple invocations: Place "analyze then implement" in a single `codex-wrapper --parallel` call, chaining them via `dependencies`, rather than running analysis first and then launching implementation separately.
+- Naming convention: Use `<action>_<timestamp>` format (e.g., `analyze_1732876800`, `implement_1732876801`), where action names map to features/stages and timestamps ensure uniqueness and sortability.
+- Dependency chain design: Keep chains short; only add dependencies for tasks that truly require ordering, let others run in parallel, avoiding over-serialization that reduces throughput.
+
+**Resume Failed Tasks**:
+```bash
+# Use session_id from previous output to resume
+codex-wrapper --parallel <<'EOF'
+---TASK---
+id: T2
+session_id: 019xxx-previous-session-id
+---CONTENT---
+fix the previous error and retry
+EOF
+```
+
+**Output**: Human-readable text format
+```
+=== Parallel Execution Summary ===
+Total: 3 | Success: 2 | Failed: 1
+
+--- Task: T1 ---
+Status: SUCCESS
+Session: 019xxx
+
+Task output message...
+
+--- Task: T2 ---
+Status: FAILED (exit code 1)
+Error: some error message
+```
+
+**Features**:
+- Automatic topological sorting based on dependencies
+- Unlimited concurrency for independent tasks
+- Error isolation (failed tasks don't stop others)
+- Dependency blocking (dependent tasks skip if parent fails)
+
+## Notes
+
+- **Binary distribution**: Single Go binary, zero dependencies
+- **Installation**: Download from GitHub Releases or use install.sh
+- **Cross-platform compatible**: Linux (amd64/arm64), macOS (amd64/arm64)
+- All automated runs must use the Bash tool with the fixed timeout to provide dual timeout protection and unified logging/exit semantics
+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/gemini/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: gemini
+description: Execute Gemini CLI for AI-powered code analysis and generation. Use when you need to leverage Google's Gemini models for complex reasoning tasks.
+---
+
+# Gemini CLI Integration
+
+## Overview
+
+Execute Gemini CLI commands with support for multiple models and flexible prompt input. Integrates Google's Gemini AI models into Claude Code workflows.
+
+## When to Use
+
+- Complex reasoning tasks requiring advanced AI capabilities
+- Code generation and analysis with Gemini models
+- Tasks requiring Google's latest AI technology
+- Alternative perspective on code problems
+
+## Usage
+**Mandatory**: Run via uv with fixed timeout 7200000ms (foreground):
+```bash
+uv run ~/.claude/skills/gemini/scripts/gemini.py "<prompt>" [working_dir]
+```
+
+**Optional** (direct execution or using Python):
+```bash
+~/.claude/skills/gemini/scripts/gemini.py "<prompt>" [working_dir]
+# or
+python3 ~/.claude/skills/gemini/scripts/gemini.py "<prompt>" [working_dir]
+```
+
+## Environment Variables
+
+- **GEMINI_MODEL**: Configure model (default: `gemini-3-pro-preview`)
+  - Example: `export GEMINI_MODEL=gemini-3`
+
+## Timeout Control
+
+- **Fixed**: 7200000 milliseconds (2 hours), immutable
+- **Bash tool**: Always set `timeout: 7200000` for double protection
+
+### Parameters
+
+- `prompt` (required): Task prompt or question
+- `working_dir` (optional): Working directory (default: current directory)
+
+### Return Format
+
+Plain text output from Gemini:
+
+```text
+Model response text here...
+```
+
+Error format (stderr):
+
+```text
+ERROR: Error message
+```
+
+### Invocation Pattern
+
+When calling via Bash tool, always include the timeout parameter:
+
+```yaml
+Bash tool parameters:
+- command: uv run ~/.claude/skills/gemini/scripts/gemini.py "<prompt>"
+- timeout: 7200000
+- description: <brief description of the task>
+```
+
+Alternatives:
+
+```yaml
+# Direct execution (simplest)
+- command: ~/.claude/skills/gemini/scripts/gemini.py "<prompt>"
+
+# Using python3
+- command: python3 ~/.claude/skills/gemini/scripts/gemini.py "<prompt>"
+```
+
+### Examples
+
+**Basic query:**
+
+```bash
+uv run ~/.claude/skills/gemini/scripts/gemini.py "explain quantum computing"
+# timeout: 7200000
+```
+
+**Code analysis:**
+
+```bash
+uv run ~/.claude/skills/gemini/scripts/gemini.py "review this code for security issues: $(cat app.py)"
+# timeout: 7200000
+```
+
+**With specific working directory:**
+
+```bash
+uv run ~/.claude/skills/gemini/scripts/gemini.py "analyze project structure" "/path/to/project"
+# timeout: 7200000
+```
+
+**Using python3 directly (alternative):**
+
+```bash
+python3 ~/.claude/skills/gemini/scripts/gemini.py "your prompt here"
+```
+
+## Notes
+
+- **Recommended**: Use `uv run` for automatic Python environment management (requires uv installed)
+- **Alternative**: Direct execution `./gemini.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)
+- Requires Gemini CLI installed and authenticated
+- Supports all Gemini model variants (configure via `GEMINI_MODEL` environment variable)
+- Output is streamed directly from Gemini CLI

skills/gemini/scripts/gemini.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.8"
+# dependencies = []
+# ///
+"""
+Gemini CLI wrapper with cross-platform support.
+
+Usage:
+    uv run gemini.py "<prompt>" [workdir]
+    python3 gemini.py "<prompt>"
+    ./gemini.py "your prompt"
+"""
+import subprocess
+import sys
+import os
+
+DEFAULT_MODEL = os.environ.get('GEMINI_MODEL', 'gemini-3-pro-preview')
+DEFAULT_WORKDIR = '.'
+TIMEOUT_MS = 7_200_000  # 固定 2 小时，毫秒
+DEFAULT_TIMEOUT = TIMEOUT_MS // 1000
+FORCE_KILL_DELAY = 5
+
+
+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 log_info(message: str):
+    """输出信息到 stderr"""
+    sys.stderr.write(f"INFO: {message}\n")
+
+
+def parse_args():
+    """解析位置参数"""
+    if len(sys.argv) < 2:
+        log_error('Prompt required')
+        sys.exit(1)
+
+    return {
+        'prompt': sys.argv[1],
+        'workdir': sys.argv[2] if len(sys.argv) > 2 else DEFAULT_WORKDIR
+    }
+
+
+def build_gemini_args(args) -> list:
+    """构建 gemini CLI 参数"""
+    return [
+        'gemini',
+        '-m', DEFAULT_MODEL,
+        '-p', args['prompt']
+    ]
+
+
+def main():
+    log_info('Script started')
+    args = parse_args()
+    log_info(f"Prompt length: {len(args['prompt'])}")
+    log_info(f"Working dir: {args['workdir']}")
+    gemini_args = build_gemini_args(args)
+    timeout_sec = DEFAULT_TIMEOUT
+    log_info(f"Timeout: {timeout_sec}s")
+
+    # 如果指定了工作目录，切换到该目录
+    if args['workdir'] != DEFAULT_WORKDIR:
+        try:
+            os.chdir(args['workdir'])
+        except FileNotFoundError:
+            log_error(f"Working directory not found: {args['workdir']}")
+            sys.exit(1)
+        except PermissionError:
+            log_error(f"Permission denied: {args['workdir']}")
+            sys.exit(1)
+        log_info('Changed working directory')
+
+    try:
+        log_info(f"Starting gemini with model {DEFAULT_MODEL}")
+        process = None
+        # 启动 gemini 子进程，直接透传 stdout 和 stderr
+        process = subprocess.Popen(
+            gemini_args,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1  # 行缓冲
+        )
+
+        # 实时输出 stdout
+        for line in process.stdout:
+            sys.stdout.write(line)
+            sys.stdout.flush()
+
+        # 等待进程结束
+        returncode = process.wait(timeout=timeout_sec)
+
+        # 读取 stderr
+        stderr_output = process.stderr.read()
+        if stderr_output:
+            sys.stderr.write(stderr_output)
+
+        # 检查退出码
+        if returncode != 0:
+            log_error(f'Gemini exited with status {returncode}')
+            sys.exit(returncode)
+
+        sys.exit(0)
+
+    except subprocess.TimeoutExpired:
+        log_error(f'Gemini execution timeout ({timeout_sec}s)')
+        if process is not None:
+            process.kill()
+            try:
+                process.wait(timeout=FORCE_KILL_DELAY)
+            except subprocess.TimeoutExpired:
+                pass
+        sys.exit(124)
+
+    except FileNotFoundError:
+        log_error("gemini command not found in PATH")
+        log_error("Please install Gemini CLI: https://github.com/google/generative-ai-python")
+        sys.exit(127)
+
+    except KeyboardInterrupt:
+        if process is not None:
+            process.terminate()
+            try:
+                process.wait(timeout=FORCE_KILL_DELAY)
+            except subprocess.TimeoutExpired:
+                process.kill()
+        sys.exit(130)
+
+
+if __name__ == '__main__':
+    main()

skills/product-requirements/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: product-requirements
+description: Interactive Product Owner skill for requirements gathering, analysis, and PRD generation. Triggers when users request product requirements, feature specification, PRD creation, or need help understanding and documenting project requirements. Uses quality scoring and iterative dialogue to ensure comprehensive requirements before generating professional PRD documents.
+---
+
+# Product Requirements Skill
+
+## Overview
+
+Transform user requirements into professional Product Requirements Documents (PRDs) through interactive dialogue, quality scoring, and iterative refinement. Act as Sarah, a meticulous Product Owner who ensures requirements are clear, testable, and actionable before documentation.
+
+## Core Identity
+
+- **Role**: Technical Product Owner & Requirements Specialist
+- **Approach**: Systematic, quality-driven, user-focused
+- **Method**: Quality scoring (100-point scale) with 90+ threshold for PRD generation
+- **Output**: Professional yet concise PRDs saved to `docs/{feature-name}-prd.md`
+
+## Interactive Process
+
+### Step 1: Initial Understanding & Context Gathering
+
+Greet as Sarah and immediately gather project context:
+
+```
+"Hi! I'm Sarah, your Product Owner. I'll help define clear requirements for your feature.
+
+Let me first understand your project context..."
+```
+
+**Context gathering actions:**
+1. Read project README, package.json/pyproject.toml in parallel
+2. Understand tech stack, existing architecture, and conventions
+3. Present initial interpretation of the user's request within project context
+4. Ask: "Is this understanding correct? What would you like to add?"
+
+**Early stop**: Once you can articulate the feature request clearly within the project's context, proceed to quality assessment.
+
+### Step 2: Quality Assessment (100-Point System)
+
+Evaluate requirements across five dimensions:
+
+#### Scoring Breakdown:
+
+**Business Value & Goals (30 points)**
+- 10 pts: Clear problem statement and business need
+- 10 pts: Measurable success metrics and KPIs
+- 10 pts: Expected outcomes and ROI justification
+
+**Functional Requirements (25 points)**
+- 10 pts: Complete user stories with acceptance criteria
+- 10 pts: Clear feature descriptions and workflows
+- 5 pts: Edge cases and error handling defined
+
+**User Experience (20 points)**
+- 8 pts: Well-defined user personas
+- 7 pts: User journey and interaction flows
+- 5 pts: UI/UX preferences and constraints
+
+**Technical Constraints (15 points)**
+- 5 pts: Performance requirements
+- 5 pts: Security and compliance needs
+- 5 pts: Integration requirements
+
+**Scope & Priorities (10 points)**
+- 5 pts: Clear MVP definition
+- 3 pts: Phased delivery plan
+- 2 pts: Priority rankings
+
+**Display format:**
+```
+📊 Requirements Quality Score: [TOTAL]/100
+
+Breakdown:
+- Business Value & Goals: [X]/30
+- Functional Requirements: [X]/25
+- User Experience: [X]/20
+- Technical Constraints: [X]/15
+- Scope & Priorities: [X]/10
+
+[If < 90]: Let me ask targeted questions to improve clarity...
+[If ≥ 90]: Excellent! Ready to generate PRD.
+```
+
+### Step 3: Targeted Clarification
+
+**If score < 90**, use `AskUserQuestion` tool to clarify gaps. Focus on the lowest-scoring area first.
+
+**Question categories by dimension:**
+
+**Business Value (if <24/30):**
+- "What specific business problem are we solving?"
+- "How will we measure success?"
+- "What happens if we don't build this?"
+
+**Functional Requirements (if <20/25):**
+- "Can you walk me through the main user workflows?"
+- "What should happen when [specific edge case]?"
+- "What are the must-have vs. nice-to-have features?"
+
+**User Experience (if <16/20):**
+- "Who are the primary users?"
+- "What are their goals and pain points?"
+- "Can you describe the ideal user experience?"
+
+**Technical Constraints (if <12/15):**
+- "What performance expectations do you have?"
+- "Are there security or compliance requirements?"
+- "What systems need to integrate with this?"
+
+**Scope & Priorities (if <8/10):**
+- "What's the minimum viable product (MVP)?"
+- "How should we phase the delivery?"
+- "What are the top 3 priorities?"
+
+**Ask 2-3 questions at a time** using `AskUserQuestion` tool. Don't overwhelm.
+
+### Step 4: Iterative Refinement
+
+After each user response:
+1. Update understanding
+2. Recalculate quality score
+3. Show progress: "Great! That improved [area] from X to Y."
+4. Continue until 90+ threshold met
+
+### Step 5: Final Confirmation & PRD Generation
+
+When score ≥ 90:
+
+```
+"Excellent! Here's the final PRD summary:
+
+[2-3 sentence executive summary]
+
+📊 Final Quality Score: [SCORE]/100
+
+Generating professional PRD at docs/{feature-name}-prd.md..."
+```
+
+Generate PRD using template below, then confirm:
+```
+"✅ PRD saved to docs/{feature-name}-prd.md
+
+Review the document and let me know if any adjustments are needed."
+```
+
+## PRD Template (Streamlined Professional Version)
+
+Save to: `docs/{feature-name}-prd.md`
+
+```markdown
+# Product Requirements Document: [Feature Name]
+
+**Version**: 1.0
+**Date**: [YYYY-MM-DD]
+**Author**: Sarah (Product Owner)
+**Quality Score**: [SCORE]/100
+
+---
+
+## Executive Summary
+
+[2-3 paragraphs covering: what problem this solves, who it helps, and expected impact. Include business context and why this feature matters now.]
+
+---
+
+## Problem Statement
+
+**Current Situation**: [Describe current pain points or limitations]
+
+**Proposed Solution**: [High-level description of the feature]
+
+**Business Impact**: [Quantifiable or qualitative expected outcomes]
+
+---
+
+## Success Metrics
+
+**Primary KPIs:**
+- [Metric 1]: [Target value and measurement method]
+- [Metric 2]: [Target value and measurement method]
+- [Metric 3]: [Target value and measurement method]
+
+**Validation**: [How and when we'll measure these metrics]
+
+---
+
+## User Personas
+
+### Primary: [Persona Name]
+- **Role**: [User type]
+- **Goals**: [What they want to achieve]
+- **Pain Points**: [Current frustrations]
+- **Technical Level**: [Novice/Intermediate/Advanced]
+
+[Add secondary persona if relevant]
+
+---
+
+## User Stories & Acceptance Criteria
+
+### Story 1: [Story Title]
+
+**As a** [persona]
+**I want to** [action]
+**So that** [benefit]
+
+**Acceptance Criteria:**
+- [ ] [Specific, testable criterion]
+- [ ] [Another criterion covering happy path]
+- [ ] [Edge case or error handling criterion]
+
+### Story 2: [Story Title]
+
+[Repeat structure]
+
+[Continue for all core user stories - typically 3-5 for MVP]
+
+---
+
+## Functional Requirements
+
+### Core Features
+
+**Feature 1: [Name]**
+- Description: [Clear explanation of functionality]
+- User flow: [Step-by-step interaction]
+- Edge cases: [What happens when...]
+- Error handling: [How system responds to failures]
+
+**Feature 2: [Name]**
+[Repeat structure]
+
+### Out of Scope
+- [Explicitly list what's NOT included in this release]
+- [Helps prevent scope creep]
+
+---
+
+## Technical Constraints
+
+### Performance
+- [Response time requirements: e.g., "API calls < 200ms"]
+- [Scalability: e.g., "Support 10k concurrent users"]
+
+### Security
+- [Authentication/authorization requirements]
+- [Data protection and privacy considerations]
+- [Compliance requirements: GDPR, SOC2, etc.]
+
+### Integration
+- **[System 1]**: [Integration details and dependencies]
+- **[System 2]**: [Integration details]
+
+### Technology Stack
+- [Required frameworks, libraries, or platforms]
+- [Compatibility requirements: browsers, devices, OS]
+- [Infrastructure constraints: cloud provider, database, etc.]
+
+---
+
+## MVP Scope & Phasing
+
+### Phase 1: MVP (Required for Initial Launch)
+- [Core feature 1]
+- [Core feature 2]
+- [Core feature 3]
+
+**MVP Definition**: [What's the minimum that delivers value?]
+
+### Phase 2: Enhancements (Post-Launch)
+- [Enhancement 1]
+- [Enhancement 2]
+
+### Future Considerations
+- [Potential future feature 1]
+- [Potential future feature 2]
+
+---
+
+## Risk Assessment
+
+| Risk | Probability | Impact | Mitigation Strategy |
+|------|------------|--------|---------------------|
+| [Risk 1: e.g., API rate limits] | High/Med/Low | High/Med/Low | [Specific mitigation plan] |
+| [Risk 2: e.g., User adoption] | High/Med/Low | High/Med/Low | [Mitigation plan] |
+| [Risk 3: e.g., Technical debt] | High/Med/Low | High/Med/Low | [Mitigation plan] |
+
+---
+
+## Dependencies & Blockers
+
+**Dependencies:**
+- [Dependency 1]: [Description and owner]
+- [Dependency 2]: [Description]
+
+**Known Blockers:**
+- [Blocker 1]: [Description and resolution plan]
+
+---
+
+## Appendix
+
+### Glossary
+- **[Term]**: [Definition]
+- **[Term]**: [Definition]
+
+### References
+- [Link to design mockups]
+- [Related documentation]
+- [Technical specs or API docs]
+
+---
+
+*This PRD was created through interactive requirements gathering with quality scoring to ensure comprehensive coverage of business, functional, UX, and technical dimensions.*
+```
+
+## Communication Guidelines
+
+### Tone
+- Professional yet approachable
+- Clear, jargon-free language
+- Collaborative and respectful
+
+### Show Progress
+- Celebrate improvements: "Great! That really clarifies things."
+- Acknowledge complexity: "This is a complex requirement, let's break it down."
+- Be transparent: "I need more information about X to ensure quality."
+
+### Handle Uncertainty
+- If user is unsure: "That's okay, let's explore some options..."
+- For assumptions: "I'll assume X based on typical patterns, but we can adjust."
+
+## Important Behaviors
+
+### DO:
+- Start with greeting and context gathering
+- Show quality scores transparently after assessment
+- Use `AskUserQuestion` tool for clarification (2-3 questions max per round)
+- Iterate until 90+ quality threshold
+- Generate PRD with proper feature name in filename
+- Maintain focus on actionable, testable requirements
+
+### DON'T:
+- Skip context gathering phase
+- Accept vague requirements (iterate to 90+)
+- Overwhelm with too many questions at once
+- Proceed without quality threshold
+- Make assumptions without validation
+- Use overly technical jargon
+
+## Success Criteria
+
+- ✅ Achieve 90+ quality score through systematic dialogue
+- ✅ Create concise, actionable PRD (not bloated documentation)
+- ✅ Save to `docs/{feature-name}-prd.md` with proper naming
+- ✅ Enable smooth handoff to development phase
+- ✅ Maintain positive, collaborative user engagement
+
+---
+
+**Remember**: Think in English, respond to user in Chinese. Quality over speed—iterate until requirements are truly clear.

skills/prototype-prompt-generator/SKILL.md

@@ -0,0 +1,497 @@
+---
+name: prototype-prompt-generator
+description: This skill should be used when users need to generate detailed, structured prompts for creating UI/UX prototypes. Trigger when users request help with "create a prototype prompt", "design a mobile app", "generate UI specifications", or need comprehensive design documentation for web/mobile applications. Works with multiple design systems including WeChat Work, iOS Native, Material Design, and Ant Design Mobile.
+---
+
+# Prototype Prompt Generator
+
+## Overview
+
+Generate comprehensive, production-ready prompts for UI/UX prototype creation. Transform user requirements into detailed technical specifications that include design systems, color palettes, component specifications, layout structures, and implementation guidelines. Output prompts are structured for optimal consumption by AI tools or human developers building HTML/CSS/React prototypes.
+
+## Workflow
+
+### Step 1: Gather Requirements
+
+Begin by collecting essential information from the user. Ask targeted questions to understand:
+
+**Application Type & Purpose:**
+- What kind of application? (e.g., enterprise tool, e-commerce, social media, dashboard)
+- Who are the target users?
+- What are the primary use cases and workflows?
+
+**Platform & Context:**
+- Target platform: iOS, Android, Web, WeChat Mini Program, or cross-platform?
+- Device: Mobile phone, tablet, desktop, or responsive?
+- Viewport dimensions if known (e.g., 375px for iPhone, 1200px for desktop)
+
+**Design Preferences:**
+- Design style: WeChat Work, iOS Native, Material Design, Ant Design Mobile, or custom?
+- Brand colors or visual preferences?
+- Any design references or inspiration?
+
+**Feature Requirements:**
+- Key pages and features needed
+- Navigation structure (tabs, drawer, stack navigation)
+- Data to display (metrics, lists, forms, media)
+- User interactions (tap, swipe, long-press, etc.)
+
+**Content & Data:**
+- Actual content to display (realistic text, numbers, names)
+- Empty states, error states, loading states
+- Any specific business logic or rules
+
+**Technical Constraints:**
+- Framework preference: Plain HTML, React, Vue, or framework-agnostic?
+- CSS approach: Tailwind CSS, CSS Modules, styled-components?
+- Image assets: Real images, placeholders, or specific sources?
+- CDN dependencies or version requirements?
+
+**Ask questions incrementally** (2-3 at a time) to avoid overwhelming the user. Many details can be inferred from context or filled with sensible defaults.
+
+### Step 2: Select Design System
+
+Based on the gathered requirements, choose the appropriate design system from `references/design-systems.md`:
+
+**WeChat Work Style:**
+- **When to use**: Chinese enterprise applications, work management tools, B2B platforms, internal business systems
+- **Characteristics**: Simple and professional, tech blue primary color, clear information hierarchy
+- **Key audience**: Chinese business users, corporate environments
+
+**iOS Native Style:**
+- **When to use**: iOS-specific apps, Apple ecosystem integration, apps targeting iPhone/iPad users
+- **Characteristics**: Minimalist, spacious layouts, San Francisco font, system colors
+- **Key audience**: Apple users, consumer apps, content-focused applications
+
+**Material Design Style:**
+- **When to use**: Android-first apps, Google ecosystem integration, cross-platform with Material UI
+- **Characteristics**: Bold graphics, elevation system, ripple effects, Roboto font
+- **Key audience**: Android users, Google services, developer tools
+
+**Ant Design Mobile Style:**
+- **When to use**: Enterprise mobile applications with complex data entry and forms
+- **Characteristics**: Efficiency-oriented, consistent components, suitable for business applications
+- **Key audience**: Business users, enterprise mobile apps, data-heavy interfaces
+
+**If the user hasn't specified a design system**, recommend one based on:
+- Geographic location: Chinese users → WeChat Work, Western users → iOS/Material
+- Platform: iOS → iOS Native, Android → Material Design
+- Application type: Enterprise B2B → WeChat Work or Ant Design, Consumer app → iOS or Material
+
+Load the complete design system specifications from `references/design-systems.md` to ensure accurate color codes, component dimensions, and interaction patterns.
+
+### Step 3: Structure the Prompt
+
+Using the template from `references/prompt-structure.md`, construct a comprehensive prompt with these sections:
+
+**1. Role Definition**
+Define expertise relevant to the prototype:
+```
+# Role
+You are a world-class UI/UX engineer and frontend developer, specializing in [specific domain] using [technologies].
+```
+
+**2. Task Description**
+State clearly what to build and the design style:
+```
+# Task
+Create a [type] prototype for [application description].
+Design style must strictly follow [design system], with core keywords: [3-5 key attributes].
+```
+
+**3. Tech Stack Specifications**
+List all technologies, frameworks, and resources:
+- File structure (single HTML, multi-page, component-based)
+- Framework and version (e.g., Tailwind CSS CDN)
+- Device simulation (viewport size, device chrome)
+- Asset sources (Unsplash, Pexels, real images)
+- Icon libraries (FontAwesome, Material Icons)
+- Custom configuration (Tailwind config, theme variables)
+
+**4. Visual Design Requirements**
+Provide detailed specifications:
+
+**(a) Color Palette:**
+Include all colors with hex codes:
+- Background colors (main, section, card)
+- Primary and accent colors with usage
+- Status colors (success, warning, error)
+- Text colors (title, body, secondary, disabled)
+- UI element colors (borders, dividers)
+
+**(b) UI Style Characteristics:**
+Specify for each component type:
+- Cards: background, radius, shadow, border, padding
+- Buttons: variants (primary, secondary, ghost), dimensions, states
+- Icons: style, sizes, colors, containers
+- List items: layout, height, divider style, active state
+- Shadows: type and usage
+
+**(c) Layout Structure:**
+Describe each major section:
+- Top navigation bar: height, title style, icons, background
+- Content areas: grids, cards, lists, spacing
+- Quick access areas: icon grids, layouts
+- Data display cards: metrics, layout, styling
+- Feature lists: structure, icons, interactions
+- Bottom tab bar: height, tabs, active/inactive states, badges
+
+**(d) Specific Page Content:**
+Provide actual content, not placeholders:
+- Real page titles and section headings
+- Actual data points (numbers, names, dates)
+- Feature names and descriptions
+- Button labels and link text
+- Sample list items with realistic content
+
+**5. Implementation Details**
+Cover technical specifics:
+- Page width and centering approach
+- Layout systems (Flexbox, Grid, or both)
+- Fixed/sticky positioning for navigation
+- Spacing scale (margins, padding, gaps)
+- Typography (font family, sizes, weights)
+- Interactive states (hover, active, focus, disabled)
+- Icon sources and usage
+- Border and divider styling
+
+**6. Tailwind Configuration**
+If using Tailwind CSS, provide custom config:
+```javascript
+tailwind.config = {
+  theme: {
+    extend: {
+      colors: {
+        'brand-primary': '#3478F6',
+        // ... all custom colors
+      }
+    }
+  }
+}
+```
+
+**7. Content Structure & Hierarchy**
+Visualize the page structure as a tree:
+```
+Page Name
+├─ Section 1
+│  ├─ Element 1
+│  └─ Element 2
+├─ Section 2
+│  ├─ Subsection A
+│  │  ├─ Item 1
+│  │  └─ Item 2
+│  └─ Subsection B
+└─ Section 3
+```
+
+**8. Special Requirements**
+Highlight unique considerations:
+- Design system-specific guidelines
+- Primary color application scenarios
+- Interaction details (tap feedback, animations, gestures)
+- Accessibility requirements (contrast, touch targets, ARIA)
+- Performance considerations (image optimization, lazy loading)
+
+**9. Output Format**
+Specify the exact deliverable:
+```
+# Output Format
+
+Please output complete [file type] code, ensuring:
+1. [Requirement 1]
+2. [Requirement 2]
+...
+
+The output should be production-ready and viewable at [viewport] on [device].
+```
+
+### Step 4: Populate with Specifics
+
+Replace all template placeholders with concrete values:
+
+**Replace vague terms with precise specifications:**
+- ❌ "Use blue colors" → ✅ "Primary: #3478F6 (tech blue), Link: #576B95 (link blue)"
+- ❌ "Make buttons rounded" → ✅ "Border radius: 4px (Tailwind: rounded)"
+- ❌ "Add some spacing" → ✅ "Card spacing: 12px, page margins: 16px"
+- ❌ "Display user info" → ✅ "Show username (15px bold), email (13px gray), avatar (48px circle)"
+
+**Use real content, not placeholders:**
+- ❌ "Lorem ipsum dolor sit amet" → ✅ "Customer Total: 14, Today's New Customers: 1, Today's Revenue: ¥0.00"
+- ❌ "[Company Name]" → ✅ "Acme Insurance Co."
+- ❌ "Feature 1, Feature 2, Feature 3" → ✅ "Customer Contact, Customer Moments, Customer Groups"
+
+**Specify all measurements:**
+- Component heights (44px, 50px, 64px)
+- Font sizes (13px, 15px, 16px, 18px)
+- Spacing values (8px, 12px, 16px, 24px)
+- Icon sizes (24px, 32px, 48px)
+- Border radius (4px, 8px, 10px)
+
+**Define all states:**
+- Normal: base colors and styles
+- Hover: if applicable (desktop)
+- Active/Pressed: opacity or background changes
+- Disabled: grayed out with reduced opacity
+- Selected: highlight color (often primary brand color)
+
+**Include all colors:**
+Every color mentioned must have a hex code. Reference the chosen design system from `references/design-systems.md` for accurate values.
+
+### Step 5: Quality Assurance
+
+Before presenting the final prompt, verify against the checklist in `references/prompt-structure.md`:
+
+**Completeness Check:**
+- [ ] Role clearly defined with relevant expertise
+- [ ] Task explicitly states what to build and design style
+- [ ] All tech stack components listed with versions/CDNs
+- [ ] Complete color palette with hex codes for all colors
+- [ ] All UI components specified with exact dimensions and styles
+- [ ] Page layout fully described with precise measurements
+- [ ] Actual, realistic content provided (no placeholders like "Lorem Ipsum" or "[Name]")
+- [ ] Implementation details cover all technical requirements
+- [ ] Tailwind config included if using Tailwind CSS
+- [ ] Content hierarchy visualized as a tree structure
+- [ ] Special requirements and interactions documented
+- [ ] Output format clearly defined with all deliverables
+
+**Clarity Check:**
+- [ ] No ambiguous terms or vague descriptions (e.g., "some padding", "nice colors")
+- [ ] All measurements specified with units (px, rem, %, vh, etc.)
+- [ ] All colors defined with hex codes (e.g., #3478F6, not just "blue")
+- [ ] Component states described (normal, hover, active, disabled, selected)
+- [ ] Layout relationships clear (parent-child, spacing, alignment, z-index)
+
+**Specificity Check:**
+- [ ] Design system explicitly named (WeChat Work, iOS Native, Material Design, etc.)
+- [ ] Viewport dimensions provided (e.g., 375px × 812px for iPhone)
+- [ ] Typography scale defined (sizes, weights, line heights)
+- [ ] Interactive behaviors documented with timing if animated
+- [ ] Edge cases considered (long text overflow, empty states, loading, errors)
+
+**Realism Check:**
+- [ ] Real content examples, not Latin placeholder text
+- [ ] Authentic data points (realistic numbers, names, dates, amounts)
+- [ ] Practical feature set (not overengineered or underspecified)
+- [ ] Appropriate complexity for the stated use case
+
+**Technical Accuracy Check:**
+- [ ] Valid Tailwind class names (if using Tailwind)
+- [ ] Correct CDN links with versions (e.g., https://cdn.tailwindcss.com)
+- [ ] Proper HTML structure implied (semantic elements, hierarchy)
+- [ ] Feasible layout techniques (Flexbox/Grid patterns that work)
+- [ ] Accessible markup considerations (touch targets ≥44px, color contrast)
+
+If any checks fail, refine the prompt before proceeding.
+
+### Step 6: Present and Iterate
+
+**Present the generated prompt to the user** with a brief explanation:
+- What design system was selected and why
+- Key design decisions made
+- Any assumptions or defaults applied
+- How to use the prompt (copy and provide to another AI tool or developer)
+
+**Offer refinement options:**
+- "Would you like to adjust any colors or spacing?"
+- "Should we add more pages or features?"
+- "Do you want to change the design system?"
+- "Any specific interactions or animations to emphasize?"
+
+**Iterate based on feedback:**
+If the user requests changes:
+1. Update the relevant sections of the prompt
+2. Maintain consistency across all sections
+3. Re-verify against the quality checklist
+4. Present the updated prompt
+
+**Save or Export:**
+Offer to save the prompt to a file:
+- Markdown file for documentation
+- Text file for easy copying
+- Include as a code block for immediate use
+
+## Best Practices
+
+**1. Default to High Quality:**
+Even if the user provides minimal requirements, generate a comprehensive prompt. It's easier to remove details than to add them later. Include:
+- Complete color palettes (8-12 colors minimum)
+- All common UI components (buttons, cards, lists, inputs)
+- Multiple component states (normal, active, disabled)
+- Responsive considerations
+- Accessibility basics (contrast, touch targets)
+
+**2. Use Design System Defaults Intelligently:**
+When user requirements are vague:
+- Apply the full design system consistently
+- Use standard component dimensions from the design system
+- Follow established patterns (e.g., WeChat Work's 64px list items)
+- Include typical interaction patterns for the platform
+
+**3. Prioritize Clarity Over Brevity:**
+Longer, detailed prompts produce better prototypes than short, vague ones. Include:
+- Exact hex codes instead of color names
+- Precise measurements instead of relative terms
+- Specific component layouts instead of general descriptions
+- Actual content instead of placeholder text
+
+**4. Think Mobile-First:**
+For mobile applications, always consider:
+- Safe areas (iOS notch, Android gesture bar)
+- Touch target sizes (minimum 44px × 44px)
+- Thumb-reachable zones (bottom navigation over top)
+- Portrait orientation primarily (landscape as secondary)
+- One-handed operation where possible
+
+**5. Balance Flexibility and Specificity:**
+- Be specific about core design elements (colors, typography, key components)
+- Allow flexibility in implementation details (exact animation timing, minor spacing adjustments)
+- Specify "must-haves" clearly, mark "nice-to-haves" as optional
+
+**6. Consider the Full User Journey:**
+Include specifications for:
+- Entry points (splash screen, onboarding if applicable)
+- Primary workflows (happy path through key features)
+- Edge cases (empty states, error states, loading states)
+- Exit points (logout, back navigation, completion states)
+
+**7. Provide Context, Not Just Specs:**
+Explain the "why" behind design decisions:
+- "Tech blue (#3478F6) for trust and professionalism in enterprise context"
+- "64px list item height for comfortable thumb tapping on mobile"
+- "Fixed bottom tab bar for quick access to primary features"
+
+**8. Validate Technical Feasibility:**
+Before finalizing the prompt:
+- Ensure CSS/Tailwind classes can achieve the described design
+- Verify that layout patterns work with the stated grid/flexbox approach
+- Confirm that the specified viewport can accommodate all content
+- Check that CDN links and versions are correct and available
+
+**9. Make It Actionable:**
+The prompt should enable immediate implementation:
+- Include all necessary CDN links and imports
+- Provide complete Tailwind config (no "...add more as needed")
+- Specify file structure and organization
+- Define clear deliverables (HTML file, React components, etc.)
+
+**10. Anticipate Questions:**
+Address common uncertainties in the prompt:
+- Font fallbacks (e.g., "sans-serif" system font stack)
+- Image dimensions and aspect ratios
+- Icon usage (when to use FontAwesome vs SVG vs emoji)
+- Z-index layering (what's on top)
+- Overflow behavior (scroll, truncate, wrap)
+
+## Common Patterns
+
+### Pattern 1: Enterprise Work Dashboard (WeChat Work Style)
+**Typical Structure:**
+- Top navigation bar (44px, title + search/menu icons)
+- Quick access grid (4-column icon grid)
+- Data summary cards (key metrics in horizontal layout)
+- Feature list (icon + text rows, 64px height each)
+- Bottom tab bar (5 tabs, 50px height)
+
+**Key Elements:**
+- Tech blue (#3478F6) for primary actions and active states
+- White cards with subtle shadows on light gray background
+- 48px icons with rounded-lg containers
+- Right arrow indicators for navigation
+
+### Pattern 2: iOS Consumer App (iOS Native Style)
+**Typical Structure:**
+- Large title navigation bar (96px when expanded)
+- Card-based content sections
+- System standard lists (44px minimum row height)
+- Tab bar with SF Symbols icons
+
+**Key Elements:**
+- System blue (#007AFF) for interactive elements
+- Generous whitespace (20px margins, 16px padding)
+- Subtle dividers with left inset
+- Translucent blur effects on navigation
+
+### Pattern 3: Android App (Material Design Style)
+**Typical Structure:**
+- Top app bar (56px on mobile, 64px on tablet)
+- FAB (Floating Action Button) for primary action
+- Card-based content with elevation
+- Bottom navigation or navigation drawer
+
+**Key Elements:**
+- Bold primary color (#6200EE) with elevation shadows
+- Ripple effects on tap
+- 16dp grid system
+- Material icons (24px)
+
+### Pattern 4: Enterprise Form App (Ant Design Mobile)
+**Typical Structure:**
+- Simple navigation bar (45px)
+- Form sections with grouped inputs
+- List views with detailed information
+- Fixed bottom action bar with primary button
+
+**Key Elements:**
+- Professional blue (#108EE9) for actions
+- Dense information layout
+- Clear form field labels and validation
+- Breadcrumb or step indicators for multi-step flows
+
+## Troubleshooting
+
+**Issue: User requirements are too vague**
+**Solution:** Ask focused questions, provide examples of similar apps, suggest design systems to choose from, or create a default prompt and offer iteration.
+
+**Issue: User wants multiple design styles mixed**
+**Solution:** Pick a primary design system for overall structure and consistency, then incorporate specific elements from other systems as accent features. Explain trade-offs.
+
+**Issue: User specifies impossible or conflicting requirements**
+**Solution:** Identify the conflict, explain why it's problematic (e.g., "64px icons won't fit in a 44px navigation bar"), suggest alternatives, and seek clarification.
+
+**Issue: Too many features for one prompt**
+**Solution:** Focus on the primary page/workflow first, generate that prompt, then create separate prompts for additional features. Maintain consistency across prompts.
+
+**Issue: User lacks technical knowledge**
+**Solution:** Avoid jargon, explain design decisions in plain language, provide visual descriptions instead of technical terms, and include helpful comments in the prompt.
+
+**Issue: Prototype prompt doesn't produce good results**
+**Solution:** Review against the quality checklist, ensure all colors have hex codes, verify all measurements are specified, add more specific content examples, check for ambiguous language.
+
+## Resources
+
+This skill includes reference documentation to support prompt generation:
+
+### references/design-systems.md
+Comprehensive specifications for major design systems:
+- **WeChat Work Style**: Chinese enterprise applications
+- **iOS Native Style**: Apple ecosystem apps
+- **Material Design**: Google/Android apps
+- **Ant Design Mobile**: Enterprise mobile apps
+
+Each design system includes:
+- Complete color palettes with hex codes
+- Component specifications (dimensions, spacing, states)
+- Typography scales (sizes, weights, line heights)
+- Interaction patterns (animations, gestures, feedback)
+- Layout guidelines (grids, spacing, safe areas)
+- Code examples (Tailwind classes, CSS snippets)
+
+**When to reference:** Always load this file when generating a prompt to ensure accurate design system specifications. Use it to populate color values, component dimensions, and interaction patterns.
+
+### references/prompt-structure.md
+Detailed template and guidelines for prompt construction:
+- Standard prompt structure (9 sections)
+- Template syntax with placeholders
+- Examples for each section
+- Quality checklist (completeness, clarity, specificity)
+- Workflow guidance (requirements → prompt → iteration)
+- Tips for effective prompts
+- Common pitfalls to avoid
+
+**When to reference:** Use this as the skeleton for every generated prompt. It ensures consistency and completeness across all prompts you create.
+
+---
+
+**Note:** This skill generates prompts for prototype creation—it does not create the prototypes themselves. The output is a comprehensive text prompt that can be provided to another AI tool, developer, or design tool to generate the actual HTML/CSS/React code.

skills/prototype-prompt-generator/references/design-systems.md

@@ -0,0 +1,388 @@
+# Design Systems Reference
+
+This document provides detailed specifications for common design systems used in mobile and web applications.
+
+## 企业微信 (WeChat Work) Style
+
+### Core Characteristics
+- **Simplicity & Professionalism**: Clean interface with clear information hierarchy
+- **Operational Clarity**: Clear action paths with explicit next steps
+- **Tech Blue**: Primary color scheme emphasizing efficiency and trust
+
+### Color Palette
+```
+Primary Colors:
+- Tech Blue: #3478F6 (buttons, icons, emphasis)
+- Link Blue: #576B95 (hyperlinks)
+- Alert Red: #FA5151 (warnings, errors)
+- Warning Orange: #FF976A (cautions)
+
+Neutral Colors:
+- Title Black: #191919 (headings)
+- Text Gray: #333333 (body text)
+- Light Text: #999999 (secondary text)
+- Divider: #E5E5E5 (borders, separators)
+- Background Area: #F7F8FA (section backgrounds)
+- White: #FFFFFF (card backgrounds)
+```
+
+### Component Specifications
+
+#### Cards
+- Background: White (#FFFFFF)
+- Border Radius: 8px (rounded-lg)
+- Shadow: Subtle (shadow-sm)
+- No thick borders
+- Spacing: 12px between cards
+
+#### Buttons
+- Primary: Blue background (#3478F6), white text
+- Height: 44px
+- Border Radius: 4px (rounded)
+- Active State: 90% opacity (active:opacity-90)
+
+#### Icons
+- Style: Rounded square background (rounded-lg) or pure icon
+- Primary Icons: Tech Blue (#3478F6)
+- Sizes: 24px / 32px / 48px
+
+#### List Items
+- Layout: Left icon/avatar (48px) + Title (15px bold) + Subtitle (13px gray) + Right arrow
+- Height: 64px
+- Divider: Left indent 64px (aligned with content)
+- Active State: Gray background (active:bg-gray-50)
+
+#### Navigation Bar (Top)
+- Height: 44px
+- Title: Centered, 16px bold, deep black
+- Background: White with 1px bottom border (border-gray-200)
+- Icons: Search and menu icons on right
+
+#### Tab Bar (Bottom)
+- Height: 50px
+- Layout: Icon + Text (vertical)
+- Selected: Tech Blue (#3478F6)
+- Unselected: Gray
+- Position: Fixed bottom (fixed bottom-0)
+- Badge Support: Red circular badge with white text
+
+### Typography
+- System Default: Sans-serif
+- Headings: font-semibold or font-bold
+- Title: 16px bold
+- Body: 15px
+- Caption: 13px
+- Helper Text: 13px gray
+
+### Spacing & Layout
+- Page Margins: 16px (left/right)
+- Card Spacing: 12px
+- Content Padding: 16px
+- Mobile Width: 375px (max-w-[375px])
+
+### Interaction Patterns
+- Tap Feedback: Background changes to light gray (bg-gray-50)
+- Button Press: Opacity reduces to 90%
+- Card Elevation: Subtle shadow (shadow-sm)
+- List Navigation: Right arrow indicator
+
+---
+
+## iOS Native Style
+
+### Core Characteristics
+- **Minimalism**: Clean, spacious layouts with generous whitespace
+- **Clarity**: Clear visual hierarchy and focus on content
+- **Depth**: Subtle shadows and layering to create depth
+
+### Color Palette
+```
+System Colors:
+- Blue: #007AFF (primary actions, links)
+- Green: #34C759 (success, positive actions)
+- Red: #FF3B30 (destructive actions, errors)
+- Orange: #FF9500 (warnings)
+- Yellow: #FFCC00 (cautions)
+- Gray: #8E8E93 (secondary text)
+
+Background Colors:
+- System Background: #FFFFFF (light mode), #000000 (dark mode)
+- Secondary Background: #F2F2F7 (light mode), #1C1C1E (dark mode)
+- Tertiary Background: #FFFFFF (light mode), #2C2C2E (dark mode)
+
+Text Colors:
+- Primary: #000000 (light mode), #FFFFFF (dark mode)
+- Secondary: #3C3C43 (60% opacity)
+- Tertiary: #3C3C43 (30% opacity)
+```
+
+### Component Specifications
+
+#### Navigation Bar
+- Height: 44px (compact), 96px (large title)
+- Title: 34px bold (large), 17px semibold (inline)
+- Background: Translucent blur effect
+- Buttons: Text or icon, 17px regular
+
+#### Tab Bar
+- Height: 49px
+- Layout: Icon + Text (vertical, 10pt text)
+- Selected: Blue (#007AFF)
+- Unselected: Gray (#8E8E93)
+- Position: Fixed bottom
+- Blur Effect: Translucent background
+
+#### List/Table View
+- Cell Height: 44px minimum
+- Layout: Left accessory + Title + Detail + Right accessory/chevron
+- Separator: 0.5px hairline, inset from left
+- Active State: Gray highlight (bg-gray-100)
+
+#### Buttons
+- Primary: Blue background (#007AFF), white text, 50px height, rounded corners (10px)
+- Secondary: No background, blue text
+- Destructive: Red text
+- Corner Radius: 10px (rounded-lg)
+
+#### Cards
+- Border Radius: 10px (rounded-lg)
+- Background: White (light mode), #1C1C1E (dark mode)
+- Shadow: Subtle (0 1px 3px rgba(0,0,0,0.1))
+- Padding: 16px
+
+### Typography (San Francisco Font)
+- Large Title: 34px bold
+- Title 1: 28px regular
+- Title 2: 22px regular
+- Title 3: 20px regular
+- Headline: 17px semibold
+- Body: 17px regular
+- Callout: 16px regular
+- Subheadline: 15px regular
+- Footnote: 13px regular
+- Caption 1: 12px regular
+- Caption 2: 11px regular
+
+### Spacing
+- Edge Margins: 16px (standard), 20px (large screens)
+- Inter-Element Spacing: 8px / 16px / 24px
+- Section Spacing: 32px
+
+### Interaction Patterns
+- Tap Feedback: Subtle highlight (no ripple effect)
+- Swipe Gestures: Swipe to delete, swipe back navigation
+- Pull to Refresh: System spinner at top
+- Haptic Feedback: Light impact on selection
+
+---
+
+## Material Design (Google) Style
+
+### Core Characteristics
+- **Material Metaphor**: Physical surfaces and realistic motion
+- **Bold Graphics**: Intentional use of color, imagery, typography
+- **Motion**: Meaningful animations that provide feedback
+
+### Color Palette
+```
+Primary Colors:
+- Primary: #6200EE (brand color, main actions)
+- Primary Variant: #3700B3 (darker shade)
+- Secondary: #03DAC6 (accent color, floating actions)
+- Secondary Variant: #018786 (darker accent)
+
+Status Colors:
+- Error: #B00020 (errors, alerts)
+- Success: #4CAF50 (success states)
+- Warning: #FF9800 (warnings)
+- Info: #2196F3 (informational)
+
+Background/Surface:
+- Background: #FFFFFF (light), #121212 (dark)
+- Surface: #FFFFFF (light), #121212 (dark)
+- Surface Variant: #F5F5F5 (light), #1E1E1E (dark)
+
+Text Colors:
+- High Emphasis: #000000 (87% opacity)
+- Medium Emphasis: #000000 (60% opacity)
+- Disabled: #000000 (38% opacity)
+```
+
+### Component Specifications
+
+#### App Bar (Top)
+- Height: 56px (mobile), 64px (desktop)
+- Title: 20px medium weight
+- Background: Primary color or white
+- Icons: 24px, white or primary color
+- Elevation: 4dp
+
+#### Bottom Navigation
+- Height: 56px
+- Layout: Icon (24px) + Label (12px)
+- Active: Primary color with ripple effect
+- Inactive: 60% opacity
+- Elevation: 8dp
+
+#### Cards
+- Border Radius: 4px (rounded)
+- Background: White (light), #1E1E1E (dark)
+- Elevation: 1dp (resting), 8dp (raised)
+- Padding: 16px
+
+#### Buttons
+- Contained: Primary color background, white text, 36px height, 4px radius
+- Outlined: 1px border, primary color text, transparent background
+- Text: No border/background, primary color text
+- Corner Radius: 4px (rounded)
+- Ripple Effect: Material ripple on tap
+
+#### Lists
+- Item Height: 48px (single-line), 64px (two-line), 88px (three-line)
+- Left Icon: 24px (40px container)
+- Right Icon: 24px
+- Divider: 1px, 87% opacity
+- Ripple Effect: On tap
+
+#### Floating Action Button (FAB)
+- Size: 56px (standard), 40px (mini)
+- Shape: Circular
+- Color: Secondary color
+- Elevation: 6dp (resting), 12dp (pressed)
+- Icon: 24px white
+
+### Typography (Roboto Font)
+- H1: 96px light
+- H2: 60px light
+- H3: 48px regular
+- H4: 34px regular
+- H5: 24px regular
+- H6: 20px medium
+- Subtitle 1: 16px regular
+- Subtitle 2: 14px medium
+- Body 1: 16px regular
+- Body 2: 14px regular
+- Button: 14px medium, uppercase
+- Caption: 12px regular
+- Overline: 10px regular, uppercase
+
+### Spacing & Grid
+- Base Unit: 8dp
+- Layout Grid: 8dp increments
+- Margins: 16dp (mobile), 24dp (tablet)
+- Gutters: 16dp (mobile), 24dp (tablet)
+- Touch Target: 48dp minimum
+
+### Elevation System
+- Level 0: 0dp (background)
+- Level 1: 1dp (cards at rest)
+- Level 2: 2dp (buttons at rest)
+- Level 3: 3dp (refresh indicator)
+- Level 4: 4dp (app bar)
+- Level 6: 6dp (FAB at rest)
+- Level 8: 8dp (bottom nav, menus)
+- Level 12: 12dp (FAB pressed)
+- Level 16: 16dp (nav drawer)
+- Level 24: 24dp (dialog, picker)
+
+### Interaction Patterns
+- Ripple Effect: Circular expanding animation from tap point
+- State Changes: Smooth color transitions (300ms)
+- Entry/Exit Animations: Fade + scale/slide
+- Touch Feedback: Immediate visual response
+
+---
+
+## Ant Design Mobile Style
+
+### Core Characteristics
+- **Enterprise-Grade**: Professional UI for business applications
+- **Efficiency-Oriented**: Optimized for quick task completion
+- **Consistent**: Unified design language across platforms
+
+### Color Palette
+```
+Primary Colors:
+- Brand Blue: #108EE9 (primary actions)
+- Link Blue: #108EE9 (links, emphasis)
+- Success: #00A854 (success states)
+- Warning: #FFBF00 (warnings)
+- Error: #F04134 (errors, destructive actions)
+
+Neutral Colors:
+- Heading: #000000 (85% opacity)
+- Body Text: #000000 (65% opacity)
+- Secondary Text: #000000 (45% opacity)
+- Disabled: #000000 (25% opacity)
+- Border: #E9E9E9 (borders, dividers)
+- Background: #F5F5F5 (page background)
+- White: #FFFFFF (component background)
+```
+
+### Component Specifications
+
+#### Navigation Bar
+- Height: 45px
+- Title: 18px bold, centered
+- Background: #108EE9 or white
+- Icons: 22px
+- Border Bottom: 1px (#E9E9E9)
+
+#### Tab Bar
+- Height: 50px
+- Layout: Icon (22px) + Text (10px)
+- Active: Brand blue (#108EE9)
+- Inactive: #888888
+- Badge: Red dot or number
+
+#### List
+- Item Height: 44px minimum
+- Left Icon: 22px (44px container)
+- Right Arrow: 16px
+- Divider: 1px, inset 15px from left
+- Active State: #DDDDDD background
+
+#### Buttons
+- Default: 47px height, 5px radius
+- Primary: Blue background (#108EE9), white text
+- Ghost: Transparent background, blue border and text
+- Disabled: Gray with 60% opacity
+
+#### Cards
+- Border Radius: 2px (rounded-sm)
+- Background: White
+- Border: 1px (#E9E9E9) or none
+- Shadow: Optional subtle shadow
+- Padding: 15px
+
+### Typography (System Default)
+- Heading: 18px bold
+- Subheading: 15px bold
+- Body: 14px regular
+- Caption: 12px regular
+- Button: 16px medium
+
+### Spacing
+- Base Unit: 5px
+- Standard Spacing: 15px
+- Edge Margins: 15px
+- Component Padding: 15px
+
+---
+
+## Usage Guidelines
+
+When generating a prototype prompt, reference the appropriate design system based on user requirements:
+
+1. **WeChat Work Style**: Use for Chinese enterprise applications, work management tools, B2B platforms
+2. **iOS Native Style**: Use when user requests iOS-specific design or mentions Apple guidelines
+3. **Material Design**: Use for Android-first apps, Google ecosystem apps, or when cross-platform Material UI is requested
+4. **Ant Design Mobile**: Use for enterprise mobile applications with complex data and forms
+
+For each design system, include:
+- Complete color palette with hex codes
+- Component specifications (dimensions, spacing, states)
+- Typography scale (sizes, weights, line heights)
+- Interaction patterns (tap feedback, animations)
+- Accessibility considerations
+- Code examples (Tailwind classes or CSS)

skills/prototype-prompt-generator/references/prompt-structure.md

@@ -0,0 +1,530 @@
+# Prototype Prompt Structure Template
+
+This document provides a comprehensive template for generating high-quality prototype prompts. Each section includes guidelines and examples.
+
+---
+
+## Standard Prompt Structure
+
+A well-structured prototype prompt should contain the following sections in order:
+
+### 1. Role Definition
+Define the expertise and perspective Claude should adopt.
+
+**Template:**
+```
+# Role
+You are a world-class [domain] engineer specializing in [specific skills]. You excel at [key capabilities].
+```
+
+**Example:**
+```
+# Role
+You are a world-class UI/UX engineer and frontend developer, specializing in creating professional, efficient enterprise-grade mobile application interfaces using Tailwind CSS.
+```
+
+---
+
+### 2. Task Description
+Clearly state what needs to be created, with emphasis on key quality attributes.
+
+**Template:**
+```
+# Task
+Create a [type of prototype] for [application description].
+Design style must strictly follow [design system/style guide], with core keywords: [3-5 key attributes].
+```
+
+**Example:**
+```
+# Task
+Create a high-fidelity prototype (HTML + Tailwind CSS) for an insurance agent work application.
+Design style must strictly follow WeChat Work style, with core keywords: simple and professional, clear information hierarchy, explicit action paths, tech blue primary color.
+```
+
+---
+
+### 3. Tech Stack Specifications
+List all technologies, frameworks, and resources required.
+
+**Template:**
+```
+# Tech Stack
+- File Structure: [describe output file organization]
+- Frameworks: [CSS frameworks, JS libraries, etc.]
+- Device Simulation: [viewport size, device features]
+- Asset Sources: [image sources, icon libraries]
+- CDN Resources: [external dependencies]
+- Custom Configuration: [theme extensions, variables]
+```
+
+**Example:**
+```
+# Tech Stack
+- Each page outputs as an independent HTML file (e.g., home.html, discover.html)
+- index.html is the entry point, using iframe to display all pages
+- Simulate iPhone 16 Pro dimensions with rounded corners, including iOS status bar and bottom navigation
+- Use real UI image assets (from Unsplash, Pexels, Apple UI resources), no placeholders
+- Include Tailwind CSS (CDN: <script src="https://cdn.tailwindcss.com"></script>)
+- Use FontAwesome (CDN) for icons
+- Custom Tailwind config with brand colors: Tech Blue #3478F6, Link Blue #576B95, Alert Red #FA5151
+```
+
+---
+
+### 4. Visual Design Requirements
+Provide detailed specifications for visual design elements.
+
+**Sections to include:**
+1. **Color Palette**: Primary, secondary, neutral, and status colors with hex codes
+2. **UI Style Characteristics**: Card design, buttons, icons, list items, shadows
+3. **Layout Structure**: Viewport dimensions, navigation bars, content areas, tab bars
+4. **Specific Page Content**: Actual text, data, and functional elements
+
+**Template:**
+
+```
+# Visual Design Requirements
+
+## 1. Color Palette
+**Background Colors:**
+- Main Background: [color name] [hex code]
+- Section Background: [color name] [hex code]
+
+**Primary Colors:**
+- Main Color: [color name] [hex code] (usage: [buttons, icons, emphasis])
+- Accent Color: [color name] [hex code] (usage: [links, secondary actions])
+
+**Status Colors:**
+- Success: [hex code]
+- Warning: [hex code]
+- Error: [hex code]
+
+**Text Colors:**
+- Title: [hex code]
+- Body: [hex code]
+- Secondary: [hex code]
+
+**UI Elements:**
+- Divider: [hex code]
+- Border: [hex code]
+
+## 2. UI Style Characteristics
+
+**Card Design:**
+- Background: [color]
+- Border Radius: [size] ([Tailwind class])
+- Shadow: [type] ([Tailwind class])
+- Border: [style]
+- Spacing: [measurements]
+
+**Buttons:**
+- Primary Button: [background] + [text color], height [px], radius [size] ([Tailwind class])
+- Active State: [opacity/color] ([Tailwind class])
+- Additional variants: [outline, ghost, text, etc.]
+
+**Icons:**
+- Style: [rounded/square/circular] ([Tailwind class])
+- Primary Icon Color: [color]
+- Sizes: [24px / 32px / 48px]
+- Container: [if applicable]
+
+**List Items:**
+- Layout: [Left element] + [Title size/weight] + [Subtitle size/color] + [Right element]
+- Height: [px]
+- Divider: [position, style]
+- Active State: [interaction feedback]
+
+**Shadows:**
+- Style: [subtle/prominent] ([Tailwind classes])
+- Usage: [where shadows apply]
+
+## 3. Layout Structure (Mobile View - [width]px)
+
+**Top Navigation Bar ([height]px):**
+- Title: [position, size, weight, color]
+- Left/Right Icons: [elements]
+- Background: [color]
+- Border: [style and position]
+
+**Content Sections:**
+[Describe each major section with:]
+- Section Name
+- Layout Pattern: [grid/flex/list]
+- Elements: [what it contains]
+- Styling: [colors, spacing, borders]
+
+**Quick Access Area:**
+[If applicable]
+- Grid: [columns x rows]
+- Icon Style: [shape, size]
+- Text: [size, position]
+
+**Data Display Cards:**
+[If applicable]
+- Metrics: [list key data points]
+- Number Display: [size, weight]
+- Label Style: [size, color]
+- Layout: [horizontal/vertical/grid]
+
+**Feature List:**
+[If applicable]
+- Section Title: [size, color, alignment]
+- List Items: [icon + text layout]
+- Item Height: [px]
+- Interaction: [tap feedback]
+
+**Bottom TabBar ([height]px, Sticky):**
+- Tab Count: [number]
+- Tabs: [list tab names]
+- Active State: [color, style]
+- Inactive State: [color, style]
+- Badges: [if applicable]
+- Position: [fixed/sticky]
+
+## 4. Specific Page Content
+[Include actual content for the prototype:]
+
+**Page Title:** [name]
+
+**Section 1: [Name]**
+- Element 1: [description]
+- Element 2: [description]
+...
+
+**Section 2: [Name]**
+- [Actual text and data to display]
+
+**Bottom Navigation:**
+- [List all tabs with states]
+```
+
+---
+
+### 5. Implementation Details
+Provide technical implementation guidelines.
+
+**Template:**
+```
+# Implementation Details
+- Page Width: [max-width] and [alignment]
+- Layout System: [Flexbox/Grid/both]
+- Navigation: [fixed/sticky positions]
+- Spacing: [margins, padding, gaps]
+- Typography: [font family, weights, sizes]
+- Interactive States: [hover, active, focus effects]
+- Icons: [source and usage]
+- Borders: [colors and positions]
+```
+
+**Example:**
+```
+# Implementation Details
+- Page width set to max-w-[375px] and centered to simulate phone screen
+- Use Flexbox and Grid layout systems
+- Top navigation bar: sticky top-0 z-10
+- Bottom TabBar: fixed bottom-0 w-full
+- Card spacing: 12px, page left/right margins: 16px
+- Typography: System default sans-serif, titles use font-semibold or font-bold
+- All clickable elements have tap feedback: active:opacity-90 or active:bg-gray-50
+- Icons: FontAwesome or placeholder div + background color
+- Dividers: border-gray-200 or border-gray-100
+```
+
+---
+
+### 6. Tailwind Configuration
+If using Tailwind CSS, provide custom configuration.
+
+**Template:**
+```
+# Tailwind Config (in <script> tag)
+
+```javascript
+tailwind.config = {
+  theme: {
+    extend: {
+      colors: {
+        'brand-primary': '[hex]',
+        'brand-secondary': '[hex]',
+        // ... more colors
+      },
+      spacing: {
+        // custom spacing if needed
+      },
+      fontSize: {
+        // custom font sizes if needed
+      }
+    }
+  }
+}
+```
+```
+
+---
+
+### 7. Content Structure & Hierarchy
+Visualize the page structure and content hierarchy.
+
+**Template:**
+```
+# Example Content & Structure
+
+[Page Name]
+├─ [Section 1 Name]
+│  ├─ [Element 1]
+│  ├─ [Element 2]
+│  └─ [Element 3]
+├─ [Section 2 Name]
+│  ├─ [Subsection A]
+│  │  ├─ [Item 1]
+│  │  └─ [Item 2]
+│  └─ [Subsection B]
+└─ [Section 3 Name]
+    └─ [Elements]
+```
+
+**Example:**
+```
+# Example Content & Structure
+
+Work Dashboard
+├─ Quick Access (4-grid)
+│  ├─ Manage Enterprise
+│  ├─ Select Apps
+│  ├─ Find Services
+│  └─ Submit Requests
+├─ Feature Card
+│  └─ Customer Data Stats (14 customers, 1 new, ¥0.00)
+├─ Common Features List
+│  ├─ Customer Contact
+│  ├─ Customer Moments
+│  ├─ Customer Groups
+│  ├─ WeChat Service
+│  └─ Broadcast Assistant
+└─ Bottom TabBar
+    ├─ Messages
+    ├─ Email
+    ├─ Documents
+    ├─ Workspace (current)
+    └─ Contacts (16)
+```
+
+---
+
+### 8. Special Requirements
+Highlight unique considerations or constraints.
+
+**Template:**
+```
+# Special Requirements
+
+- [Design System] Key Points:
+  - [Characteristic 1]
+  - [Characteristic 2]
+  - [Characteristic 3]
+
+- [Primary Color] Application Scenarios:
+  - [Usage 1]
+  - [Usage 2]
+  - [Usage 3]
+
+- Interaction Details:
+  - [Interaction 1]: [behavior]
+  - [Interaction 2]: [behavior]
+  - [Interaction 3]: [behavior]
+
+- Accessibility:
+  - [Requirement 1]
+  - [Requirement 2]
+
+- Performance:
+  - [Consideration 1]
+  - [Consideration 2]
+```
+
+---
+
+### 9. Output Format
+Specify the exact deliverable format.
+
+**Template:**
+```
+# Output Format
+
+Please output complete [file type] code, ensuring:
+1. [Requirement 1]
+2. [Requirement 2]
+3. [Requirement 3]
+...
+
+The output should be production-ready and viewable at [viewport size] on [device type].
+```
+
+**Example:**
+```
+# Output Format
+
+Please output complete index.html code, ensuring:
+1. Perfect display on 375px width mobile screen
+2. All interactive elements have proper feedback
+3. Real image assets (no placeholders)
+4. Proper iOS status bar and safe area simulation
+5. Smooth scrolling and fixed navigation elements
+
+The output should be immediately viewable in a browser and represent a pixel-perfect work dashboard homepage.
+```
+
+---
+
+## Prompt Generation Workflow
+
+When generating a prototype prompt, follow this workflow:
+
+### Step 1: Gather Requirements
+Ask the user:
+- What type of application? (e.g., enterprise tool, e-commerce, social media)
+- Target platform? (iOS, Android, Web, WeChat Mini Program)
+- Design style preference? (WeChat Work, iOS Native, Material Design, custom)
+- Key features and pages needed?
+- Target users and use cases?
+- Any specific content or data to display?
+- Brand colors or visual preferences?
+
+### Step 2: Select Design System
+Based on requirements, choose the appropriate design system from references/design-systems.md:
+- **WeChat Work**: Chinese enterprise apps, B2B tools
+- **iOS Native**: iOS apps, Apple ecosystem
+- **Material Design**: Android apps, Google ecosystem
+- **Ant Design Mobile**: Enterprise mobile apps with complex forms
+
+### Step 3: Structure the Prompt
+Using the sections above:
+1. Define the role (UI/UX engineer with specific expertise)
+2. Describe the task (what to build, design style, key attributes)
+3. Specify tech stack (frameworks, device, assets, CDNs)
+4. Detail visual design (colors, components, layout, content)
+5. Provide implementation guidelines (technical details)
+6. Include Tailwind config (if using Tailwind)
+7. Show content hierarchy (visual tree structure)
+8. Add special requirements (design system specifics, interactions)
+9. Specify output format (deliverable expectations)
+
+### Step 4: Populate with Specifics
+- Replace all template placeholders with actual values
+- Include real content (text, numbers, labels)
+- Specify exact colors (hex codes)
+- Define precise measurements (px, rem, etc.)
+- List all page elements and features
+- Add interaction states and behaviors
+
+### Step 5: Review and Refine
+Ensure the prompt:
+- Is complete and self-contained
+- Has no ambiguous placeholders
+- Includes all necessary technical details
+- Specifies exact design requirements
+- Provides realistic content examples
+- Defines clear deliverables
+
+---
+
+## Quality Checklist
+
+Before finalizing a prototype prompt, verify:
+
+**Completeness:**
+- [ ] Role clearly defined with relevant expertise
+- [ ] Task explicitly states what to build and design style
+- [ ] All tech stack components listed with versions/CDNs
+- [ ] Complete color palette with hex codes
+- [ ] All UI components specified with dimensions and styles
+- [ ] Page layout fully described with measurements
+- [ ] Actual content provided (not placeholders)
+- [ ] Implementation details cover technical requirements
+- [ ] Tailwind config included (if applicable)
+- [ ] Content hierarchy visualized
+- [ ] Special requirements and interactions documented
+- [ ] Output format clearly defined
+
+**Clarity:**
+- [ ] No ambiguous terms or vague descriptions
+- [ ] Measurements specified (px, rem, %, etc.)
+- [ ] Colors defined with hex codes
+- [ ] Component states described (normal, hover, active, disabled)
+- [ ] Layout relationships clear (parent-child, spacing, alignment)
+
+**Specificity:**
+- [ ] Design system explicitly named
+- [ ] Viewport dimensions provided
+- [ ] Typography scale defined (sizes, weights, line heights)
+- [ ] Interactive behaviors documented
+- [ ] Edge cases considered (long text, empty states, etc.)
+
+**Realism:**
+- [ ] Real content examples (not Lorem Ipsum)
+- [ ] Authentic data points (numbers, names, dates)
+- [ ] Practical feature set (not overengineered)
+- [ ] Appropriate complexity for use case
+
+**Technical Accuracy:**
+- [ ] Valid Tailwind class names
+- [ ] Correct CDN links
+- [ ] Proper HTML structure implied
+- [ ] Feasible layout techniques (Flexbox/Grid)
+- [ ] Accessible markup considerations
+
+---
+
+## Example Variations
+
+### Minimal Prompt (for simple landing page)
+```
+# Role
+You are a frontend developer specializing in clean, modern web design.
+
+# Task
+Create a single-page landing page (HTML + Tailwind CSS) for a SaaS product.
+Style: Modern, minimal, professional with soft colors.
+
+# Tech Stack
+- Single index.html file
+- Tailwind CSS (CDN)
+- Desktop-first responsive (max 1200px)
+- Use Unsplash for hero image
+
+# Visual Design
+- Colors: Primary #6366F1 (indigo), Background #F9FAFB (gray-50), Text #111827 (gray-900)
+- Sections: Hero (full viewport height) + Features (3 columns) + CTA
+- Typography: System sans-serif, Hero 48px bold, Body 18px regular
+
+# Output Format
+Single HTML file, production-ready, mobile-responsive.
+```
+
+### Complex Prompt (for multi-page app)
+[Follow full template structure with all sections, detailed component specs, multiple pages, complex interactions]
+
+---
+
+## Tips for Effective Prompts
+
+1. **Be Specific**: "Blue button" → "Primary button: #3478F6 background, white text, 44px height, 4px rounded corners"
+
+2. **Provide Context**: Don't just list features, explain their purpose and how they relate to user workflows
+
+3. **Use Real Content**: "Insurance agent dashboard" with "14 customers, ¥1,234.56 revenue" is better than "Dashboard with metrics"
+
+4. **Reference Standards**: "Follow WeChat Work design guidelines" gives Claude a comprehensive style framework
+
+5. **Include Edge Cases**: Mention empty states, loading states, error states, long text handling
+
+6. **Specify Interactions**: Don't assume—explicitly state tap feedback, hover effects, animation timing
+
+7. **Think Mobile-First**: For mobile apps, always specify touch target sizes (minimum 44px), safe areas, gesture support
+
+8. **Consider Accessibility**: Mention color contrast, touch target sizes, semantic HTML, ARIA labels
+
+9. **Balance Detail and Brevity**: Be thorough but organized—use sections and hierarchy to keep prompts scannable
+
+10. **Test Your Mental Model**: Can someone else understand exactly what to build from this prompt? If not, add clarity.

skills/skill-rules.json

@@ -0,0 +1,116 @@
+{
+  "skills": {
+    "codex": {
+      "type": "execution",
+      "enforcement": "suggest",
+      "priority": "high",
+      "promptTriggers": {
+        "keywords": [
+          "refactor",
+          "implement",
+          "code change",
+          "bug fix",
+          "生成代码",
+          "重构",
+          "修复"
+        ],
+        "intentPatterns": [
+          "(refactor|rewrite|optimi[sz]e)\\b",
+          "(implement|build|write).*(feature|function|module|code)",
+          "(fix|debug).*(bug|error|issue)"
+        ]
+      }
+    },
+    "codeagent": {
+      "type": "execution",
+      "enforcement": "suggest",
+      "priority": "high",
+      "promptTriggers": {
+        "keywords": [
+          "codeagent",
+          "multi-backend",
+          "backend selection",
+          "parallel task",
+          "多后端",
+          "并行任务",
+          "gemini",
+          "claude backend"
+        ],
+        "intentPatterns": [
+          "\\bcodeagent\\b",
+          "backend\\s+(codex|claude|gemini)",
+          "parallel.*task",
+          "multi.*backend"
+        ]
+      }
+    },
+    "gh-workflow": {
+      "type": "domain",
+      "enforcement": "suggest",
+      "priority": "high",
+      "promptTriggers": {
+        "keywords": [
+          "issue",
+          "pr",
+          "pull request",
+          "github",
+          "gh workflow",
+          "merge"
+        ],
+        "intentPatterns": [
+          "(create|open|update|close|review).*(pr|pull request|issue)",
+          "\\bgithub\\b|\\bgh\\b"
+        ]
+      }
+    },
+    "product-requirements": {
+      "type": "domain",
+      "enforcement": "suggest",
+      "priority": "high",
+      "promptTriggers": {
+        "keywords": [
+          "requirements",
+          "prd",
+          "product requirements",
+          "feature specification",
+          "product owner",
+          "需求",
+          "产品需求",
+          "需求文档",
+          "功能规格"
+        ],
+        "intentPatterns": [
+          "(product|feature).*requirement",
+          "\\bPRD\\b",
+          "requirements?.*document",
+          "(gather|collect|define|write).*requirement"
+        ]
+      }
+    },
+    "prototype-prompt-generator": {
+      "type": "domain",
+      "enforcement": "suggest",
+      "priority": "medium",
+      "promptTriggers": {
+        "keywords": [
+          "prototype",
+          "ui design",
+          "ux design",
+          "mobile app design",
+          "web app design",
+          "原型",
+          "界面设计",
+          "UI设计",
+          "UX设计",
+          "移动应用设计"
+        ],
+        "intentPatterns": [
+          "(create|generate|design).*(prototype|UI|UX|interface)",
+          "(mobile|web).*app.*(design|prototype)",
+          "prototype.*prompt",
+          "design.*system"
+        ]
+      }
+    }
+  }
+}