fix installer offline fallback and remove codex/gemini skills

fix(executor): filter codex_core stderr noise
Merge pull request #147 from AsakiEmura/fix/unset-claudecode-env
2026-02-28 09:23:05 +08:00 · 2026-02-22 16:45:26 +08:00 · 2026-02-18 16:32:59 +08:00 · 2026-02-18 16:32:18 +08:00 · 2026-02-18 07:56:25 +08:00 · 2026-02-14 23:58:38 +08:00
14 changed files with 950 additions and 707 deletions
--- a/bin/cli.js
+++ b/bin/cli.js
@@ -1006,17 +1006,20 @@ async function installSelected(picks, tag, config, installDir, force, dryRun) {
  try {
    let repoRoot = repoRootFromHere();
    if (needRepo || needWrapper) {
-      if (!tag) throw new Error("No tag available to download");
+      if (tag) {
-      const archive = path.join(tmp, "src.tgz");
+        const archive = path.join(tmp, "src.tgz");
-      const url = `https://codeload.github.com/${REPO.owner}/${REPO.name}/tar.gz/refs/tags/${encodeURIComponent(
+        const url = `https://codeload.github.com/${REPO.owner}/${REPO.name}/tar.gz/refs/tags/${encodeURIComponent(
-        tag
+          tag
-      )}`;
+        )}`;
-      process.stdout.write(`Downloading ${REPO.owner}/${REPO.name}@${tag}...\n`);
+        process.stdout.write(`Downloading ${REPO.owner}/${REPO.name}@${tag}...\n`);
-      await downloadToFile(url, archive);
+        await downloadToFile(url, archive);
-      process.stdout.write("Extracting...\n");
+        process.stdout.write("Extracting...\n");
-      const extracted = path.join(tmp, "src");
+        const extracted = path.join(tmp, "src");
-      await extractTarGz(archive, extracted);
+        await extractTarGz(archive, extracted);
-      repoRoot = extracted;
+        repoRoot = extracted;
      } else {
        process.stdout.write("Offline mode: installing from local package contents.\n");
      }
    }
    await fs.promises.mkdir(installDir, { recursive: true });
--- a/codeagent-wrapper/README.md
+++ b/codeagent-wrapper/README.md
@@ -1,97 +1,158 @@
 # codeagent-wrapper
-`codeagent-wrapper` 是一个用 Go 编写的“多后端 AI 代码代理”命令行包装器：用统一的 CLI 入口封装不同的 AI 工具后端（Codex / Claude / Gemini / Opencode），并提供一致的参数、配置与会话恢复体验。
+[English](README.md) | [中文](README_CN.md)
-入口：`cmd/codeagent/main.go`（生成二进制名：`codeagent`）和 `cmd/codeagent-wrapper/main.go`（生成二进制名：`codeagent-wrapper`）。两者行为一致。
+A multi-backend AI code agent CLI wrapper written in Go. Provides a unified CLI entry point wrapping different AI tool backends (Codex / Claude / Gemini / OpenCode) with consistent flags, configuration, skill injection, and session resumption.
-## 功能特性
+Entry point: `cmd/codeagent-wrapper/main.go` (binary: `codeagent-wrapper`).
- 多后端支持：`codex` / `claude` / `gemini` / `opencode`
+## Features
 - 统一命令行：`codeagent [flags] <task>` / `codeagent resume <session_id> <task> [workdir]`
 - 自动 stdin：遇到换行/特殊字符/超长任务自动走 stdin，避免 shell quoting 地狱；也可显式使用 `-`
 - 配置合并：支持配置文件与 `CODEAGENT_*` 环境变量（viper）
 - Agent 预设：从 `~/.codeagent/models.json` 读取 backend/model/prompt 等预设
 - 并行执行：`--parallel` 从 stdin 读取多任务配置，支持依赖拓扑并发执行
 - 日志清理：`codeagent cleanup` 清理旧日志（日志写入系统临时目录）
-## 安装
+- **Multi-backend support**: `codex` / `claude` / `gemini` / `opencode`
 - **Unified CLI**: `codeagent-wrapper [flags] <task>` / `codeagent-wrapper resume <session_id> <task> [workdir]`
 - **Auto stdin**: Automatically pipes via stdin when task contains newlines, special characters, or exceeds length; also supports explicit `-`
 - **Config merging**: Config files + `CODEAGENT_*` environment variables (viper)
 - **Agent presets**: Read backend/model/prompt/reasoning/yolo/allowed_tools from `~/.codeagent/models.json`
 - **Dynamic agents**: Place a `{name}.md` prompt file in `~/.codeagent/agents/` to use as an agent
 - **Skill auto-injection**: `--skills` for manual specification, or auto-detect from project tech stack (Go/Rust/Python/Node.js/Vue)
 - **Git worktree isolation**: `--worktree` executes tasks in an isolated git worktree with auto-generated task_id and branch
 - **Parallel execution**: `--parallel` reads multi-task config from stdin with dependency-aware topological concurrent execution and structured summary reports
 - **Backend config**: `backends` section in `models.json` supports per-backend `base_url` / `api_key` injection
 - **Claude tool control**: `allowed_tools` / `disallowed_tools` to restrict available tools for Claude backend
 - **Stderr noise filtering**: Automatically filters noisy stderr output from Gemini and Codex backends
 - **Log cleanup**: `codeagent-wrapper cleanup` cleans old logs (logs written to system temp directory)
 - **Cross-platform**: macOS / Linux / Windows
-要求：Go 1.21+。
+## Installation
-在仓库根目录执行：
+### Recommended (interactive installer)
 ```bash
-go install ./cmd/codeagent
+npx github:cexll/myclaude
 go install ./cmd/codeagent-wrapper
 ```
-安装后确认：
+Select the `codeagent-wrapper` module to install.
 ### Manual build
 Requires: Go 1.21+.
 ```bash
-codeagent version
+# Build from source
-codeagent-wrapper version
+make build
 # Or install to $GOPATH/bin
 make install
 ```
-## 使用示例
+Verify installation:
 最简单用法（默认后端：`codex`）：
 ```bash
-codeagent "分析 internal/app/cli.go 的入口逻辑，给出改进建议"
+codeagent-wrapper --version
 ```
-指定后端：
+## Usage
 Basic usage (default backend: `codex`):
 ```bash
-codeagent --backend claude "解释 internal/executor/parallel_config.go 的并行配置格式"
+codeagent-wrapper "analyze the entry logic of internal/app/cli.go"
 ```
-指定工作目录（第 2 个位置参数）：
+Specify backend:
 ```bash
-codeagent "在当前 repo 下搜索潜在数据竞争" .
+codeagent-wrapper --backend claude "explain the parallel config format in internal/executor/parallel_config.go"
 ```
-显式从 stdin 读取 task（使用 `-`）：
+Specify working directory (2nd positional argument):
 ```bash
-cat task.txt | codeagent -
+codeagent-wrapper "search for potential data races in this repo" .
 ```
-恢复会话：
+Explicit stdin (using `-`):
 ```bash
-codeagent resume <session_id> "继续上次任务"
+cat task.txt | codeagent-wrapper -
 ```
-并行模式（从 stdin 读取任务配置；禁止位置参数）：
+HEREDOC (recommended for multi-line tasks):
 ```bash
-codeagent --parallel <<'EOF'
+codeagent-wrapper --backend claude - <<'EOF'
 Implement user authentication:
 - JWT tokens
 - bcrypt password hashing
 - Session management
 EOF
 ```
 Resume session:
 ```bash
 codeagent-wrapper resume <session_id> "continue the previous task"
 ```
 Execute in isolated git worktree:
 ```bash
 codeagent-wrapper --worktree "refactor the auth module"
 ```
 Manual skill injection:
 ```bash
 codeagent-wrapper --skills golang-base-practices "optimize database queries"
 ```
 Parallel mode (task config from stdin):
 ```bash
 codeagent-wrapper --parallel <<'EOF'
 ---TASK---
 id: t1
 workdir: .
 backend: codex
 ---CONTENT---
-列出本项目的主要模块以及它们的职责。
+List the main modules and their responsibilities.
 ---TASK---
 id: t2
 dependencies: t1
 backend: claude
 ---CONTENT---
-基于 t1 的结论，提出重构风险点与建议。
+Based on t1's findings, identify refactoring risks and suggestions.
 EOF
 ```
-## 配置说明
+## CLI Flags
-### 配置文件
+| Flag | Description |
 |------|-------------|
 | `--backend <name>` | Backend selection (codex/claude/gemini/opencode) |
 | `--model <name>` | Model override |
 | `--agent <name>` | Agent preset name (from models.json or ~/.codeagent/agents/) |
 | `--prompt-file <path>` | Read prompt from file |
 | `--skills <names>` | Comma-separated skill names for spec injection |
 | `--reasoning-effort <level>` | Reasoning effort (backend-specific) |
 | `--skip-permissions` | Skip permission prompts |
 | `--dangerously-skip-permissions` | Alias for `--skip-permissions` |
 | `--worktree` | Execute in a new git worktree (auto-generates task_id) |
 | `--parallel` | Parallel task mode (config from stdin) |
 | `--full-output` | Full output in parallel mode (default: summary only) |
 | `--config <path>` | Config file path (default: `$HOME/.codeagent/config.*`) |
 | `--version`, `-v` | Print version |
 | `--cleanup` | Clean up old logs |
-默认查找路径（当 `--config` 为空时）：
+## Configuration
 ### Config File
 Default search path (when `--config` is empty):
 - `$HOME/.codeagent/config.(yaml|yml|json|toml|...)`
-示例（YAML）：
+Example (YAML):
 ```yaml
 backend: codex
@@ -99,59 +160,113 @@ model: gpt-4.1
 skip-permissions: false
 ```
-也可以通过 `--config /path/to/config.yaml` 显式指定。
+Can also be specified explicitly via `--config /path/to/config.yaml`.
-### 环境变量（`CODEAGENT_*`）
+### Environment Variables (`CODEAGENT_*`)
-通过 viper 读取并自动映射 `-` 为 `_`，常用项：
+Read via viper with automatic `-` to `_` mapping:
- `CODEAGENT_BACKEND`（`codex|claude|gemini|opencode`）
+| Variable | Description |
- `CODEAGENT_MODEL`
+|----------|-------------|
- `CODEAGENT_AGENT`
+| `CODEAGENT_BACKEND` | Backend name (codex/claude/gemini/opencode) |
- `CODEAGENT_PROMPT_FILE`
+| `CODEAGENT_MODEL` | Model name |
- `CODEAGENT_REASONING_EFFORT`
+| `CODEAGENT_AGENT` | Agent preset name |
- `CODEAGENT_SKIP_PERMISSIONS`
+| `CODEAGENT_PROMPT_FILE` | Prompt file path |
- `CODEAGENT_FULL_OUTPUT`（并行模式 legacy 输出）
+| `CODEAGENT_REASONING_EFFORT` | Reasoning effort |
- `CODEAGENT_MAX_PARALLEL_WORKERS`（0 表示不限制，上限 100）
+| `CODEAGENT_SKIP_PERMISSIONS` | Skip permission prompts (default true; set `false` to disable) |
 | `CODEAGENT_FULL_OUTPUT` | Full output in parallel mode |
 | `CODEAGENT_MAX_PARALLEL_WORKERS` | Parallel worker count (0=unlimited, max 100) |
 | `CODEAGENT_TMPDIR` | Custom temp directory (for macOS permission issues) |
 | `CODEX_TIMEOUT` | Timeout in ms (default 7200000 = 2 hours) |
 | `CODEX_BYPASS_SANDBOX` | Codex sandbox bypass (default true; set `false` to disable) |
 | `DO_WORKTREE_DIR` | Reuse existing worktree directory (set by /do workflow) |
-### Agent 预设（`~/.codeagent/models.json`）
+### Agent Presets (`~/.codeagent/models.json`)
 可在 `~/.codeagent/models.json` 定义 agent → backend/model/prompt 等映射，用 `--agent <name>` 选择：
 ```json
 {
-  "default_backend": "opencode",
+  "default_backend": "codex",
-  "default_model": "opencode/grok-code",
+  "default_model": "gpt-4.1",
  "backends": {
    "codex": { "api_key": "..." },
    "claude": { "base_url": "http://localhost:23001", "api_key": "..." }
  },
  "agents": {
    "develop": {
      "backend": "codex",
      "model": "gpt-4.1",
      "prompt_file": "~/.codeagent/prompts/develop.md",
-      "description": "Code development"
+      "reasoning": "high",
      "yolo": true,
      "allowed_tools": ["Read", "Write", "Bash"],
      "disallowed_tools": ["WebFetch"]
    }
  }
 }
 ```
-## 支持的后端
+Use `--agent <name>` to select a preset. Agents inherit `base_url` / `api_key` from the corresponding `backends` entry.
-该项目本身不内置模型能力，依赖你本机安装并可在 `PATH` 中找到对应 CLI：
+### Dynamic Agents
- `codex`：执行 `codex e ...`（默认会添加 `--dangerously-bypass-approvals-and-sandbox`；如需关闭请设置 `CODEX_BYPASS_SANDBOX=false`）
+Place a `{name}.md` file in `~/.codeagent/agents/` to use it via `--agent {name}`. The Markdown file is read as the prompt, using `default_backend` and `default_model`.
 - `claude`：执行 `claude -p ... --output-format stream-json`（默认会跳过权限提示；如需开启请设置 `CODEAGENT_SKIP_PERMISSIONS=false`）
 - `gemini`：执行 `gemini ... -o stream-json`（可从 `~/.gemini/.env` 加载环境变量）
 - `opencode`：执行 `opencode run --format json`
-## 开发
+### Skill Auto-Detection
-```bash
+When no skills are specified via `--skills`, codeagent-wrapper auto-detects the tech stack from files in the working directory:
-make build
+
-make test
+| Detected Files | Injected Skills |
-make lint
+|----------------|-----------------|
-make clean
+| `go.mod` / `go.sum` | `golang-base-practices` |
 | `Cargo.toml` | `rust-best-practices` |
 | `pyproject.toml` / `setup.py` / `requirements.txt` | `python-best-practices` |
 | `package.json` | `vercel-react-best-practices`, `frontend-design` |
 | `vue.config.js` / `vite.config.ts` / `nuxt.config.ts` | `vue-web-app` |
 Skill specs are read from `~/.claude/skills/{name}/SKILL.md`, subject to a 16000-character budget.
 ## Supported Backends
 This project does not embed model capabilities. It requires the corresponding CLI tools installed and available in `PATH`:
 | Backend | Command | Notes |
 |---------|---------|-------|
 | `codex` | `codex e ...` | Adds `--dangerously-bypass-approvals-and-sandbox` by default; set `CODEX_BYPASS_SANDBOX=false` to disable |
 | `claude` | `claude -p ... --output-format stream-json` | Skips permissions and disables setting-sources to prevent recursion; set `CODEAGENT_SKIP_PERMISSIONS=false` to enable prompts; auto-reads env and model from `~/.claude/settings.json` |
 | `gemini` | `gemini -o stream-json -y ...` | Auto-loads env vars from `~/.gemini/.env` (GEMINI_API_KEY, GEMINI_MODEL, etc.) |
 | `opencode` | `opencode run --format json` | — |
 ## Project Structure
 ```
 cmd/codeagent-wrapper/main.go   # CLI entry point
 internal/
  app/          # CLI command definitions, argument parsing, main orchestration
  backend/      # Backend abstraction and implementations (codex/claude/gemini/opencode)
  config/       # Config loading, agent resolution, viper bindings
  executor/     # Task execution engine: single/parallel/worktree/skill injection
  logger/       # Structured logging system
  parser/       # JSON stream parser
  utils/        # Common utility functions
  worktree/     # Git worktree management
 ```
-## 故障排查
+## Development
- macOS 下如果看到临时目录相关的 `permission denied`（例如临时可执行文件无法在 `/var/folders/.../T` 执行），可设置一个可执行的临时目录：`CODEAGENT_TMPDIR=$HOME/.codeagent/tmp`。
+```bash
- `claude` 后端的 `base_url/api_key`（来自 `~/.codeagent/models.json`）会注入到子进程环境变量：`ANTHROPIC_BASE_URL` / `ANTHROPIC_API_KEY`。若 `base_url` 指向本地代理（如 `localhost:23001`），请确认代理进程在运行。
+make build    # Build binary
 make test     # Run tests
 make lint     # golangci-lint + staticcheck
 make clean    # Clean build artifacts
 make install  # Install to $GOPATH/bin
 ```
 CI uses GitHub Actions with Go 1.21 / 1.22 matrix testing.
 ## Troubleshooting
 - On macOS, if you see `permission denied` related to temp directories, set: `CODEAGENT_TMPDIR=$HOME/.codeagent/tmp`
 - `claude` backend's `base_url` / `api_key` (from `~/.codeagent/models.json` `backends.claude`) are injected as `ANTHROPIC_BASE_URL` / `ANTHROPIC_API_KEY` env vars
 - `gemini` backend's API key is loaded from `~/.gemini/.env`, injected as `GEMINI_API_KEY` with `GEMINI_API_KEY_AUTH_MECHANISM=bearer` auto-set
 - Exit codes: 127 = backend not found, 124 = timeout, 130 = interrupted
 - Parallel mode outputs structured summary by default; use `--full-output` for complete output when debugging
--- a/codeagent-wrapper/README_CN.md
+++ b/codeagent-wrapper/README_CN.md
@@ -0,0 +1,272 @@
 # codeagent-wrapper
 [English](README.md) | [中文](README_CN.md)
 `codeagent-wrapper` 是一个用 Go 编写的多后端 AI 代码代理命令行包装器：用统一的 CLI 入口封装不同的 AI 工具后端（Codex / Claude / Gemini / OpenCode），并提供一致的参数、配置、技能注入与会话恢复体验。
 入口：`cmd/codeagent-wrapper/main.go`（生成二进制名：`codeagent-wrapper`）。
 ## 功能特性
 - **多后端支持**：`codex` / `claude` / `gemini` / `opencode`
 - **统一命令行**：`codeagent-wrapper [flags] <task>` / `codeagent-wrapper resume <session_id> <task> [workdir]`
 - **自动 stdin**：遇到换行/特殊字符/超长任务自动走 stdin，避免 shell quoting 问题；也可显式使用 `-`
 - **配置合并**：支持配置文件与 `CODEAGENT_*` 环境变量（viper）
 - **Agent 预设**：从 `~/.codeagent/models.json` 读取 backend/model/prompt/reasoning/yolo/allowed_tools 等预设
 - **动态 Agent**：在 `~/.codeagent/agents/{name}.md` 放置 prompt 文件即可作为 agent 使用
 - **技能自动注入**：`--skills` 手动指定，或根据项目技术栈自动检测（Go/Rust/Python/Node.js/Vue）并注入对应技能规范
 - **Git Worktree 隔离**：`--worktree` 在独立 git worktree 中执行任务，自动生成 task_id 和分支
 - **并行执行**：`--parallel` 从 stdin 读取多任务配置，支持依赖拓扑并发执行，带结构化摘要报告
 - **后端配置**：`models.json` 的 `backends` 节支持 per-backend 的 `base_url` / `api_key` 注入
 - **Claude 工具控制**：`allowed_tools` / `disallowed_tools` 限制 Claude 后端可用工具
 - **Stderr 降噪**：自动过滤 Gemini 和 Codex 后端的噪声 stderr 输出
 - **日志清理**：`codeagent-wrapper cleanup` 清理旧日志（日志写入系统临时目录）
 - **跨平台**：支持 macOS / Linux / Windows
 ## 安装
 ### 推荐方式（交互式安装器）
 ```bash
 npx github:cexll/myclaude
 ```
 选择 `codeagent-wrapper` 模块进行安装。
 ### 手动构建
 要求：Go 1.21+。
 ```bash
 # 从源码构建
 make build
 # 或直接安装到 $GOPATH/bin
 make install
 ```
 安装后确认：
 ```bash
 codeagent-wrapper --version
 ```
 ## 使用示例
 最简单用法（默认后端：`codex`）：
 ```bash
 codeagent-wrapper "分析 internal/app/cli.go 的入口逻辑，给出改进建议"
 ```
 指定后端：
 ```bash
 codeagent-wrapper --backend claude "解释 internal/executor/parallel_config.go 的并行配置格式"
 ```
 指定工作目录（第 2 个位置参数）：
 ```bash
 codeagent-wrapper "在当前 repo 下搜索潜在数据竞争" .
 ```
 显式从 stdin 读取 task（使用 `-`）：
 ```bash
 cat task.txt | codeagent-wrapper -
 ```
 使用 HEREDOC（推荐用于多行任务）：
 ```bash
 codeagent-wrapper --backend claude - <<'EOF'
 实现用户认证系统：
 - JWT 令牌
 - bcrypt 密码哈希
 - 会话管理
 EOF
 ```
 恢复会话：
 ```bash
 codeagent-wrapper resume <session_id> "继续上次任务"
 ```
 在 git worktree 中隔离执行：
 ```bash
 codeagent-wrapper --worktree "重构认证模块"
 ```
 手动指定技能注入：
 ```bash
 codeagent-wrapper --skills golang-base-practices "优化数据库查询"
 ```
 并行模式（从 stdin 读取任务配置）：
 ```bash
 codeagent-wrapper --parallel <<'EOF'
 ---TASK---
 id: t1
 workdir: .
 backend: codex
 ---CONTENT---
 列出本项目的主要模块以及它们的职责。
 ---TASK---
 id: t2
 dependencies: t1
 backend: claude
 ---CONTENT---
 基于 t1 的结论，提出重构风险点与建议。
 EOF
 ```
 ## CLI 参数
 | 参数 | 说明 |
 |------|------|
 | `--backend <name>` | 后端选择（codex/claude/gemini/opencode） |
 | `--model <name>` | 覆盖模型 |
 | `--agent <name>` | Agent 预设名（来自 models.json 或 ~/.codeagent/agents/） |
 | `--prompt-file <path>` | 从文件读取 prompt |
 | `--skills <names>` | 逗号分隔的技能名，注入对应规范 |
 | `--reasoning-effort <level>` | 推理力度（后端相关） |
 | `--skip-permissions` | 跳过权限提示 |
 | `--dangerously-skip-permissions` | `--skip-permissions` 的别名 |
 | `--worktree` | 在新 git worktree 中执行（自动生成 task_id） |
 | `--parallel` | 并行任务模式（从 stdin 读取配置） |
 | `--full-output` | 并行模式下输出完整消息（默认仅输出摘要） |
 | `--config <path>` | 配置文件路径（默认：`$HOME/.codeagent/config.*`） |
 | `--version`, `-v` | 打印版本号 |
 | `--cleanup` | 清理旧日志 |
 ## 配置说明
 ### 配置文件
 默认查找路径（当 `--config` 为空时）：
 - `$HOME/.codeagent/config.(yaml|yml|json|toml|...)`
 示例（YAML）：
 ```yaml
 backend: codex
 model: gpt-4.1
 skip-permissions: false
 ```
 也可以通过 `--config /path/to/config.yaml` 显式指定。
 ### 环境变量（`CODEAGENT_*`）
 通过 viper 读取并自动映射 `-` 为 `_`，常用项：
 | 变量 | 说明 |
 |------|------|
 | `CODEAGENT_BACKEND` | 后端名（codex/claude/gemini/opencode） |
 | `CODEAGENT_MODEL` | 模型名 |
 | `CODEAGENT_AGENT` | Agent 预设名 |
 | `CODEAGENT_PROMPT_FILE` | Prompt 文件路径 |
 | `CODEAGENT_REASONING_EFFORT` | 推理力度 |
 | `CODEAGENT_SKIP_PERMISSIONS` | 跳过权限提示（默认 true；设 `false` 关闭） |
 | `CODEAGENT_FULL_OUTPUT` | 并行模式完整输出 |
 | `CODEAGENT_MAX_PARALLEL_WORKERS` | 并行 worker 数（0=不限制，上限 100） |
 | `CODEAGENT_TMPDIR` | 自定义临时目录（macOS 权限问题时使用） |
 | `CODEX_TIMEOUT` | 超时（毫秒，默认 7200000 即 2 小时） |
 | `CODEX_BYPASS_SANDBOX` | Codex sandbox bypass（默认 true；设 `false` 关闭） |
 | `DO_WORKTREE_DIR` | 复用已有 worktree 目录（由 /do 工作流设置） |
 ### Agent 预设（`~/.codeagent/models.json`）
 ```json
 {
  "default_backend": "codex",
  "default_model": "gpt-4.1",
  "backends": {
    "codex": { "api_key": "..." },
    "claude": { "base_url": "http://localhost:23001", "api_key": "..." }
  },
  "agents": {
    "develop": {
      "backend": "codex",
      "model": "gpt-4.1",
      "prompt_file": "~/.codeagent/prompts/develop.md",
      "reasoning": "high",
      "yolo": true,
      "allowed_tools": ["Read", "Write", "Bash"],
      "disallowed_tools": ["WebFetch"]
    }
  }
 }
 ```
 用 `--agent <name>` 选择预设，agent 会继承 `backends` 下对应后端的 `base_url` / `api_key`。
 ### 动态 Agent
 在 `~/.codeagent/agents/` 目录放置 `{name}.md` 文件，即可通过 `--agent {name}` 使用，自动读取该 Markdown 作为 prompt，使用 `default_backend` 和 `default_model`。
 ### 技能自动检测
 当未通过 `--skills` 显式指定技能时，codeagent-wrapper 会根据工作目录中的文件自动检测技术栈：
 | 检测文件 | 注入技能 |
 |----------|----------|
 | `go.mod` / `go.sum` | `golang-base-practices` |
 | `Cargo.toml` | `rust-best-practices` |
 | `pyproject.toml` / `setup.py` / `requirements.txt` | `python-best-practices` |
 | `package.json` | `vercel-react-best-practices`, `frontend-design` |
 | `vue.config.js` / `vite.config.ts` / `nuxt.config.ts` | `vue-web-app` |
 技能规范从 `~/.claude/skills/{name}/SKILL.md` 读取，受 16000 字符预算限制。
 ## 支持的后端
 该项目本身不内置模型能力，依赖本机安装并可在 `PATH` 中找到对应 CLI：
 | 后端 | 执行命令 | 说明 |
 |------|----------|------|
 | `codex` | `codex e ...` | 默认添加 `--dangerously-bypass-approvals-and-sandbox`；设 `CODEX_BYPASS_SANDBOX=false` 关闭 |
 | `claude` | `claude -p ... --output-format stream-json` | 默认跳过权限并禁用 setting-sources 防止递归；设 `CODEAGENT_SKIP_PERMISSIONS=false` 开启权限；自动读取 `~/.claude/settings.json` 中的 env 和 model |
 | `gemini` | `gemini -o stream-json -y ...` | 自动从 `~/.gemini/.env` 加载环境变量（GEMINI_API_KEY, GEMINI_MODEL 等） |
 | `opencode` | `opencode run --format json` | — |
 ## 项目结构
 ```
 cmd/codeagent-wrapper/main.go   # CLI 入口
 internal/
  app/          # CLI 命令定义、参数解析、主逻辑编排
  backend/      # 后端抽象与实现（codex/claude/gemini/opencode）
  config/       # 配置加载、agent 解析、viper 绑定
  executor/     # 任务执行引擎：单任务/并行/worktree/技能注入
  logger/       # 结构化日志系统
  parser/       # JSON stream 解析器
  utils/        # 通用工具函数
  worktree/     # Git worktree 管理
 ```
 ## 开发
 ```bash
 make build    # 构建
 make test     # 运行测试
 make lint     # golangci-lint + staticcheck
 make clean    # 清理构建产物
 make install  # 安装到 $GOPATH/bin
 ```
 CI 使用 GitHub Actions，Go 1.21 / 1.22 矩阵测试。
 ## 故障排查
 - macOS 下如果看到临时目录相关的 `permission denied`，可设置：`CODEAGENT_TMPDIR=$HOME/.codeagent/tmp`
 - `claude` 后端的 `base_url` / `api_key`（来自 `~/.codeagent/models.json` 的 `backends.claude`）会注入到子进程环境变量 `ANTHROPIC_BASE_URL` / `ANTHROPIC_API_KEY`
 - `gemini` 后端的 API key 从 `~/.gemini/.env` 加载，注入 `GEMINI_API_KEY` 并自动设置 `GEMINI_API_KEY_AUTH_MECHANISM=bearer`
 - 后端命令未找到时返回退出码 127，超时返回 124，中断返回 130
 - 并行模式默认输出结构化摘要，使用 `--full-output` 查看完整输出以便调试
--- a/codeagent-wrapper/internal/app/executor_concurrent_test.go
+++ b/codeagent-wrapper/internal/app/executor_concurrent_test.go
@@ -169,6 +169,12 @@ func (f *execFakeRunner) Process() executor.ProcessHandle {
 	return &execFakeProcess{pid: 1}
 }
 func (f *execFakeRunner) UnsetEnv(keys ...string) {
 	for _, k := range keys {
 		delete(f.env, k)
 	}
 }
 func TestExecutorRunCodexTaskWithContext(t *testing.T) {
 	defer resetTestHooks()
--- a/codeagent-wrapper/internal/app/main_test.go
+++ b/codeagent-wrapper/internal/app/main_test.go
@@ -274,6 +274,10 @@ func (d *drainBlockingCmd) Process() executor.ProcessHandle {
 	return d.inner.Process()
 }
 func (d *drainBlockingCmd) UnsetEnv(keys ...string) {
 	d.inner.UnsetEnv(keys...)
 }
 type bufferWriteCloser struct {
 	buf    bytes.Buffer
 	mu     sync.Mutex
@@ -568,6 +572,14 @@ func (f *fakeCmd) Process() executor.ProcessHandle {
 	return f.process
 }
 func (f *fakeCmd) UnsetEnv(keys ...string) {
 	f.mu.Lock()
 	defer f.mu.Unlock()
 	for _, k := range keys {
 		delete(f.env, k)
 	}
 }
 func (f *fakeCmd) runStdoutScript() {
 	if len(f.stdoutPlan) == 0 {
 		if !f.keepStdoutOpen {
--- a/codeagent-wrapper/internal/executor/env_stderr_test.go
+++ b/codeagent-wrapper/internal/executor/env_stderr_test.go
@@ -41,6 +41,11 @@ func (f *fakeCmd) SetEnv(env map[string]string) {
 	}
 }
 func (f *fakeCmd) Process() processHandle { return nil }
 func (f *fakeCmd) UnsetEnv(keys ...string) {
 	for _, k := range keys {
 		delete(f.env, k)
 	}
 }
 func TestEnvInjection_LogsToStderrAndMasksKey(t *testing.T) {
 	// Arrange ~/.codeagent/models.json via HOME override.
--- a/codeagent-wrapper/internal/executor/executor.go
+++ b/codeagent-wrapper/internal/executor/executor.go
@@ -113,6 +113,7 @@ type commandRunner interface {
 	SetStderr(io.Writer)
 	SetDir(string)
 	SetEnv(env map[string]string)
 	UnsetEnv(keys ...string)
 	Process() processHandle
 }
@@ -221,6 +222,33 @@ func (r *realCmd) SetEnv(env map[string]string) {
 	r.cmd.Env = out
 }
 func (r *realCmd) UnsetEnv(keys ...string) {
 	if r == nil || r.cmd == nil || len(keys) == 0 {
 		return
 	}
 	// If cmd.Env is nil, Go inherits all parent env vars.
 	// Populate explicitly so we can selectively remove keys.
 	if r.cmd.Env == nil {
 		r.cmd.Env = os.Environ()
 	}
 	drop := make(map[string]struct{}, len(keys))
 	for _, k := range keys {
 		drop[k] = struct{}{}
 	}
 	filtered := make([]string, 0, len(r.cmd.Env))
 	for _, kv := range r.cmd.Env {
 		idx := strings.IndexByte(kv, '=')
 		name := kv
 		if idx >= 0 {
 			name = kv[:idx]
 		}
 		if _, ok := drop[name]; !ok {
 			filtered = append(filtered, kv)
 		}
 	}
 	r.cmd.Env = filtered
 }
 func (r *realCmd) Process() processHandle {
 	if r == nil || r.cmd == nil || r.cmd.Process == nil {
 		return nil
@@ -1126,6 +1154,13 @@ func RunCodexTaskWithContext(parentCtx context.Context, taskSpec TaskSpec, backe
 	injectTempEnv(cmd)
 	// Claude Code sets CLAUDECODE=1 in its child processes. If we don't
 	// remove it, the spawned `claude -p` detects the variable and refuses
 	// to start ("cannot be launched inside another Claude Code session").
 	if commandName == "claude" {
 		cmd.UnsetEnv("CLAUDECODE")
 	}
 	// For backends that don't support -C flag (claude, gemini), set working directory via cmd.Dir
 	// Codex passes workdir via -C flag, so we skip setting Dir for it to avoid conflicts
 	if cfg.Mode != "resume" && commandName != "codex" && cfg.WorkDir != "" {
--- a/codeagent-wrapper/internal/executor/filter.go
+++ b/codeagent-wrapper/internal/executor/filter.go
@@ -20,8 +20,7 @@ var geminiNoisePatterns = []string{
 // codexNoisePatterns contains stderr patterns to filter for codex backend
 var codexNoisePatterns = []string{
-	"ERROR codex_core::codex: needs_follow_up:",
+	"ERROR codex_core::",
 	"ERROR codex_core::skills::loader:",
 }
 // filteringWriter wraps an io.Writer and filters out lines matching patterns
--- a/codeagent-wrapper/internal/executor/filter_test.go
+++ b/codeagent-wrapper/internal/executor/filter_test.go
@@ -71,3 +71,35 @@ func TestFilteringWriterPartialLines(t *testing.T) {
 		t.Errorf("got %q, want %q", got, "Hello World\n")
 	}
 }
 func TestFilteringWriterCodexNoise(t *testing.T) {
 	tests := []struct {
 		name  string
 		input string
 		want  string
 	}{
 		{
 			name:  "filter all codex_core errors",
 			input: "ERROR codex_core::rollout::list: state db missing rollout path for thread 123\nERROR codex_core::skills::loader: missing skill\nVisible output\n",
 			want:  "Visible output\n",
 		},
 		{
 			name:  "keep non codex_core errors",
 			input: "ERROR another_module::state: real failure\nERROR codex_core::codex: needs_follow_up: true\nDone\n",
 			want:  "ERROR another_module::state: real failure\nDone\n",
 		},
 	}
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
 			var buf bytes.Buffer
 			fw := newFilteringWriter(&buf, codexNoisePatterns)
 			_, _ = fw.Write([]byte(tt.input))
 			fw.Flush()
 			if got := buf.String(); got != tt.want {
 				t.Errorf("got %q, want %q", got, tt.want)
 			}
 		})
 	}
 }
--- a/skills/codex/SKILL.md
+++ b/skills/codex/SKILL.md
@@ -1,334 +0,0 @@
 ---
 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
--- a/skills/do/SKILL.md
+++ b/skills/do/SKILL.md
@@ -10,31 +10,17 @@ An orchestrator for systematic feature development. Invoke agents via `codeagent
 ## Loop Initialization (REQUIRED)
-When triggered via `/do <task>`, follow these steps:
+When triggered via `/do <task>`, initialize the task directory immediately without asking about worktree:
 ### Step 1: Ask about worktree mode
 Use AskUserQuestion to ask:
 ```
 Develop in a separate worktree? (Isolates changes from main branch)
 - Yes (Recommended for larger changes)
 - No (Work directly in current directory)
 ```
 ### Step 2: Initialize task directory
 ```bash
 # If worktree mode selected:
 python3 ".claude/skills/do/scripts/setup-do.py" --worktree "<task description>"
 # If no worktree:
 python3 ".claude/skills/do/scripts/setup-do.py" "<task description>"
 ```
 This creates a task directory under `.claude/do-tasks/` with:
 - `task.md`: Single file containing YAML frontmatter (metadata) + Markdown body (requirements/context)
 **Worktree decision is deferred until Phase 4 (Implement).** Phases 1-3 are read-only and do not require worktree isolation.
 ## Task Directory Management
 Use `task.py` to manage task state:
@@ -52,15 +38,23 @@ python3 ".claude/skills/do/scripts/task.py" list
 ## Worktree Mode
-When worktree mode is enabled in task.json, ALL `codeagent-wrapper` calls that modify code MUST include `--worktree`:
+The worktree is created **only when needed** (right before Phase 4: Implement). If the user chooses worktree mode:
 1. Run setup with `--worktree` flag to create the worktree:
   ```bash
   python3 ".claude/skills/do/scripts/setup-do.py" --worktree "<task description>"
   ```
 2. Use the `DO_WORKTREE_DIR` environment variable to direct `codeagent-wrapper` develop agent into the worktree. **Do NOT pass `--worktree` to subsequent calls** — that creates a new worktree each time.
 ```bash
-codeagent-wrapper --worktree --agent develop - . <<'EOF'
+# Save the worktree path from setup output, then prefix all develop calls:
 DO_WORKTREE_DIR=<worktree_dir> codeagent-wrapper --agent develop - . <<'EOF'
 ...
 EOF
 ```
-Read-only agents (code-explorer, code-architect, code-reviewer) do NOT need `--worktree`.
+Read-only agents (code-explorer, code-architect, code-reviewer) do NOT need `DO_WORKTREE_DIR`.
 ## Hard Constraints
@@ -69,7 +63,7 @@ Read-only agents (code-explorer, code-architect, code-reviewer) do NOT need `--w
 3. **Update phase after each phase.** Use `task.py update-phase <N>`.
 4. **Expect long-running `codeagent-wrapper` calls.** High-reasoning modes can take a long time.
 5. **Timeouts are not an escape hatch.** If a call times out, retry with narrower scope.
-6. **Respect worktree setting.** If enabled, always pass `--worktree` to develop agent calls.
+6. **Defer worktree decision until Phase 4.** Only ask about worktree mode right before implementation. If enabled, prefix develop agent calls with `DO_WORKTREE_DIR=<path>`. Never pass `--worktree` after initialization.
 ## Agents
@@ -78,7 +72,7 @@ Read-only agents (code-explorer, code-architect, code-reviewer) do NOT need `--w
 | `code-explorer` | Trace code, map architecture, find patterns | No (read-only) |
 | `code-architect` | Design approaches, file plans, build sequences | No (read-only) |
 | `code-reviewer` | Review for bugs, simplicity, conventions | No (read-only) |
-| `develop` | Implement code, run tests | **Yes** (if worktree enabled) |
+| `develop` | Implement code, run tests | **Yes** — use `DO_WORKTREE_DIR` env prefix |
 ## Issue Severity Definitions
@@ -175,12 +169,39 @@ EOF
 **Goal:** Build feature and review in one phase.
-1. Invoke `develop` to implement. For full-stack projects, split into backend/frontend tasks with per-task `skills:` injection. Use `--parallel` when tasks can be split; use single agent when the change is small or single-domain.
+**Step 1: Decide on worktree mode (ONLY NOW)**
-**Single-domain example** (add `--worktree` if enabled):
+Use AskUserQuestion to ask:
 ```
 Develop in a separate worktree? (Isolates changes from main branch)
 - Yes (Recommended for larger changes)
 - No (Work directly in current directory)
 ```
 If user chooses worktree:
 ```bash
 python3 ".claude/skills/do/scripts/setup-do.py" --worktree "<task description>"
 # Save the worktree path from output for DO_WORKTREE_DIR
 ```
 **Step 2: Invoke develop agent**
 For full-stack projects, split into backend/frontend tasks with per-task `skills:` injection. Use `--parallel` when tasks can be split; use single agent when the change is small or single-domain.
 **Single-domain example** (prefix with `DO_WORKTREE_DIR` if worktree enabled):
 ```bash
-codeagent-wrapper --worktree --agent develop --skills golang-base-practices - . <<'EOF'
+# With worktree:
 DO_WORKTREE_DIR=<worktree_dir> codeagent-wrapper --agent develop --skills golang-base-practices - . <<'EOF'
 Implement with minimal change set following the Phase 3 blueprint.
 - Follow Phase 1 patterns
 - Add/adjust tests per Phase 3 plan
 - Run narrowest relevant tests
 EOF
 # Without worktree:
 codeagent-wrapper --agent develop --skills golang-base-practices - . <<'EOF'
 Implement with minimal change set following the Phase 3 blueprint.
 - Follow Phase 1 patterns
 - Add/adjust tests per Phase 3 plan
@@ -191,7 +212,8 @@ EOF
 **Full-stack parallel example** (adapt task IDs, skills, and content based on Phase 3 design):
 ```bash
-codeagent-wrapper --worktree --parallel <<'EOF'
+# With worktree:
 DO_WORKTREE_DIR=<worktree_dir> codeagent-wrapper --parallel <<'EOF'
 ---TASK---
 id: p4_backend
 agent: develop
@@ -213,11 +235,17 @@ Implement frontend changes following Phase 3 blueprint.
 - Follow Phase 1 patterns
 - Add/adjust tests per Phase 3 plan
 EOF
 # Without worktree: remove DO_WORKTREE_DIR prefix
 ```
 Note: Choose which skills to inject based on Phase 3 design output. Only inject skills relevant to each task's domain.
-2. Run parallel reviews:
+**Step 3: Review**
 **Step 3: Review**
 Run parallel reviews:
 ```bash
 codeagent-wrapper --parallel <<'EOF'
@@ -239,9 +267,10 @@ Classify each issue as BLOCKING or MINOR.
 EOF
 ```
-3. Handle review results:
+**Step 4: Handle review results**
-   - **MINOR issues only** → Auto-fix via `develop`, no user interaction
+
-   - **BLOCKING issues** → Use AskUserQuestion: "Fix now / Proceed as-is"
+- **MINOR issues only** → Auto-fix via `develop`, no user interaction
 - **BLOCKING issues** → Use AskUserQuestion: "Fix now / Proceed as-is"
 ### Phase 5: Complete (No Interaction)
--- a/skills/gemini/SKILL.md
+++ b/skills/gemini/SKILL.md
@@ -1,120 +0,0 @@
 ---
 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
--- a/skills/gemini/scripts/gemini.py
+++ b/skills/gemini/scripts/gemini.py
@@ -1,140 +0,0 @@
 #!/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()
--- a/skills/harness/SKILL.md
+++ b/skills/harness/SKILL.md
@@ -0,0 +1,329 @@
 ---
 name: harness
 description: "This skill should be used for multi-session autonomous agent work requiring progress checkpointing, failure recovery, and task dependency management. Triggers on '/harness' command, or when a task involves many subtasks needing progress persistence, sleep/resume cycles across context windows, recovery from mid-task failures with partial state, or distributed work across multiple agent sessions. Synthesized from Anthropic and OpenAI engineering practices for long-running agents."
 ---
 # Harness — Long-Running Agent Framework
 Executable protocol enabling any agent task to run continuously across multiple sessions with automatic progress recovery, task dependency resolution, failure rollback, and standardized error handling.
 ## Design Principles
 1. **Design for the agent, not the human** — Test output, docs, and task structure are the agent's primary interface
 2. **Progress files ARE the context** — When context window resets, progress files + git history = full recovery
 3. **Premature completion is the #1 failure mode** — Structured task lists with explicit completion criteria prevent declaring victory early
 4. **Standardize everything grep-able** — ERROR on same line, structured timestamps, consistent prefixes
 5. **Fast feedback loops** — Pre-compute stats, run smoke tests before full validation
 6. **Idempotent everything** — Init scripts, task execution, environment setup must all be safe to re-run
 7. **Fail safe, not fail silent** — Every failure must have an explicit recovery strategy
 ## Commands
 ```
 /harness init <project-path>     # Initialize harness files in project
 /harness run                     # Start/resume the infinite loop
 /harness status                  # Show current progress and stats
 /harness add "task description"  # Add a task to the list
 ```
 ## Progress Persistence (Dual-File System)
 Maintain two files in the project working directory:
 ### harness-progress.txt (Append-Only Log)
 Free-text log of all agent actions across sessions. Never truncate.
 ```
 [2025-07-01T10:00:00Z] [SESSION-1] INIT Harness initialized for project /path/to/project
 [2025-07-01T10:00:05Z] [SESSION-1] INIT Environment health check: PASS
 [2025-07-01T10:00:10Z] [SESSION-1] LOCK acquired (pid=12345)
 [2025-07-01T10:00:11Z] [SESSION-1] Starting [task-001] Implement user authentication (base=def5678)
 [2025-07-01T10:05:00Z] [SESSION-1] CHECKPOINT [task-001] step=2/4 "auth routes created, tests pending"
 [2025-07-01T10:15:30Z] [SESSION-1] Completed [task-001] (commit abc1234)
 [2025-07-01T10:15:31Z] [SESSION-1] Starting [task-002] Add rate limiting (base=abc1234)
 [2025-07-01T10:20:00Z] [SESSION-1] ERROR [task-002] [TASK_EXEC] Redis connection refused
 [2025-07-01T10:20:01Z] [SESSION-1] ROLLBACK [task-002] git reset --hard abc1234
 [2025-07-01T10:20:02Z] [SESSION-1] STATS tasks_total=5 completed=1 failed=1 pending=3 blocked=0 attempts_total=2 checkpoints=1
 ```
 ### harness-tasks.json (Structured State)
 ```json
 {
  "version": 2,
  "created": "2025-07-01T10:00:00Z",
  "session_config": {
    "max_tasks_per_session": 20,
    "max_sessions": 50
  },
  "tasks": [
    {
      "id": "task-001",
      "title": "Implement user authentication",
      "status": "completed",
      "priority": "P0",
      "depends_on": [],
      "attempts": 1,
      "max_attempts": 3,
      "started_at_commit": "def5678",
      "validation": {
        "command": "npm test -- --testPathPattern=auth",
        "timeout_seconds": 300
      },
      "on_failure": {
        "cleanup": null
      },
      "error_log": [],
      "checkpoints": [],
      "completed_at": "2025-07-01T10:15:30Z"
    },
    {
      "id": "task-002",
      "title": "Add rate limiting",
      "status": "failed",
      "priority": "P1",
      "depends_on": [],
      "attempts": 1,
      "max_attempts": 3,
      "started_at_commit": "abc1234",
      "validation": {
        "command": "npm test -- --testPathPattern=rate-limit",
        "timeout_seconds": 120
      },
      "on_failure": {
        "cleanup": "docker compose down redis"
      },
      "error_log": ["[TASK_EXEC] Redis connection refused"],
      "checkpoints": [],
      "completed_at": null
    },
    {
      "id": "task-003",
      "title": "Add OAuth providers",
      "status": "pending",
      "priority": "P1",
      "depends_on": ["task-001"],
      "attempts": 0,
      "max_attempts": 3,
      "started_at_commit": null,
      "validation": {
        "command": "npm test -- --testPathPattern=oauth",
        "timeout_seconds": 180
      },
      "on_failure": {
        "cleanup": null
      },
      "error_log": [],
      "checkpoints": [],
      "completed_at": null
    }
  ],
  "session_count": 1,
  "last_session": "2025-07-01T10:20:02Z"
 }
 ```
 Task statuses: `pending` → `in_progress` (transient, set only during active execution) → `completed` or `failed`. A task found as `in_progress` at session start means the previous session was interrupted — handle via Context Window Recovery Protocol.
 **Session boundary**: A session starts when the agent begins executing the Session Start protocol and ends when a Stopping Condition is met or the context window resets. Each session gets a unique `SESSION-N` identifier (N = `session_count` after increment).
 ## Concurrency Control
 Before modifying `harness-tasks.json`, acquire an exclusive lock using portable `mkdir` (atomic on all POSIX systems, works on both macOS and Linux):
 ```bash
 # Acquire lock (fail fast if another agent is running)
 LOCKDIR="/tmp/harness-$(printf '%s' "$(pwd)" | shasum -a 256 2>/dev/null || sha256sum | cut -c1-8).lock"
 if ! mkdir "$LOCKDIR" 2>/dev/null; then
  # Check if lock holder is still alive
  LOCK_PID=$(cat "$LOCKDIR/pid" 2>/dev/null)
  if [ -n "$LOCK_PID" ] && kill -0 "$LOCK_PID" 2>/dev/null; then
    echo "ERROR: Another harness session is active (pid=$LOCK_PID)"; exit 1
  fi
  # Stale lock — atomically reclaim via mv to avoid TOCTOU race
  STALE="$LOCKDIR.stale.$$"
  if mv "$LOCKDIR" "$STALE" 2>/dev/null; then
    rm -rf "$STALE"
    mkdir "$LOCKDIR" || { echo "ERROR: Lock contention"; exit 1; }
    echo "WARN: Removed stale lock${LOCK_PID:+ from pid=$LOCK_PID}"
  else
    echo "ERROR: Another agent reclaimed the lock"; exit 1
  fi
 fi
 echo "$$" > "$LOCKDIR/pid"
 trap 'rm -rf "$LOCKDIR"' EXIT
 ```
 Log lock acquisition: `[timestamp] [SESSION-N] LOCK acquired (pid=<PID>)`
 Log lock release: `[timestamp] [SESSION-N] LOCK released`
 The lock is held for the entire session. The `trap EXIT` handler releases it automatically on normal exit, errors, or signals. Never release the lock between tasks within a session.
 ## Infinite Loop Protocol
 ### Session Start (Execute Every Time)
 1. **Read state**: Read last 200 lines of `harness-progress.txt` + full `harness-tasks.json`. If JSON is unparseable, see JSON corruption recovery in Error Handling.
 2. **Read git**: Run `git log --oneline -20` and `git diff --stat` to detect uncommitted work
 3. **Acquire lock**: Fail if another session is active
 4. **Recover interrupted tasks** (see Context Window Recovery below)
 5. **Health check**: Run `harness-init.sh` if it exists
 6. **Track session**: Increment `session_count` in JSON. Check `session_count` against `max_sessions` — if reached, log STATS and STOP. Initialize per-session task counter to 0.
 7. **Pick next task** using Task Selection Algorithm below
 ### Task Selection Algorithm
 Before selecting, run dependency validation:
 1. **Cycle detection**: For each non-completed task, walk `depends_on` transitively. If any task appears in its own chain, mark it `failed` with `[DEPENDENCY] Circular dependency detected: task-A -> task-B -> task-A`. Self-references (`depends_on` includes own id) are also cycles.
 2. **Blocked propagation**: If a task's `depends_on` includes a task that is `failed` and will never be retried (either `attempts >= max_attempts` OR its `error_log` contains a `[DEPENDENCY]` entry), mark the blocked task as `failed` with `[DEPENDENCY] Blocked by failed task-XXX`. Repeat until no more tasks can be propagated.
 Then pick the next task in this priority order:
 1. Tasks with `status: "pending"` where ALL `depends_on` tasks are `completed` — sorted by `priority` (P0 > P1 > P2), then by `id` (lowest first)
 2. Tasks with `status: "failed"` where `attempts < max_attempts` and ALL `depends_on` are `completed` — sorted by priority, then oldest failure first
 3. If no eligible tasks remain → log final STATS → STOP
 ### Task Execution Cycle
 For each task, execute this exact sequence:
 1. **Claim**: Record `started_at_commit` = current HEAD hash. Set status to `in_progress`, log `Starting [<task-id>] <title> (base=<hash>)`
 2. **Execute with checkpoints**: Perform the work. After each significant step, log:
   ```
   [timestamp] [SESSION-N] CHECKPOINT [task-id] step=M/N "description of what was done"
   ```
   Also append to the task's `checkpoints` array: `{ "step": M, "total": N, "description": "...", "timestamp": "ISO" }`
 3. **Validate**: Run the task's `validation.command` wrapped with `timeout`: `timeout <timeout_seconds> <command>`. If no validation command, skip. Before running, verify the command exists (e.g., `command -v <binary>`) — if missing, treat as `ENV_SETUP` error.
   - Command exits 0 → PASS
   - Command exits non-zero → FAIL
   - Command exceeds timeout → TIMEOUT
 4. **Record outcome**:
   - **Success**: status=`completed`, set `completed_at`, log `Completed [<task-id>] (commit <hash>)`, git commit
   - **Failure**: increment `attempts`, append error to `error_log`. Verify `started_at_commit` exists via `git cat-file -t <hash>` — if missing, mark failed at max_attempts. Otherwise execute `git reset --hard <started_at_commit>` and `git clean -fd` to rollback ALL commits and remove untracked files. Execute `on_failure.cleanup` if defined. Log `ERROR [<task-id>] [<category>] <message>`. Set status=`failed` (Task Selection Algorithm pass 2 handles retries when attempts < max_attempts)
 5. **Track**: Increment per-session task counter. If `max_tasks_per_session` reached, log STATS and STOP.
 6. **Continue**: Immediately pick next task (zero idle time)
 ### Stopping Conditions
 - All tasks `completed`
 - All remaining tasks `failed` at max_attempts or blocked by failed dependencies
 - `session_config.max_tasks_per_session` reached for this session
 - `session_config.max_sessions` reached across all sessions
 - User interrupts
 ## Context Window Recovery Protocol
 When a new session starts and finds a task with `status: "in_progress"`:
 1. **Check git state**:
   ```bash
   git diff --stat          # Uncommitted changes?
   git log --oneline -5     # Recent commits since task started?
   git stash list           # Any stashed work?
   ```
 2. **Check checkpoints**: Read the task's `checkpoints` array to determine last completed step
 3. **Decision matrix** (verify recent commits belong to this task by checking commit messages for the task-id):
 | Uncommitted? | Recent task commits? | Checkpoints? | Action |
 |---|---|---|---|
 | No | No | None | Mark `failed` with `[SESSION_TIMEOUT] No progress detected`, increment attempts |
 | No | No | Some | Verify file state matches checkpoint claims. If files reflect checkpoint progress, resume from last step. If not, mark `failed` — work was lost |
 | No | Yes | Any | Run `validation.command`. If passes → mark `completed`. If fails → `git reset --hard <started_at_commit>`, mark `failed` |
 | Yes | No | Any | Run validation WITH uncommitted changes present. If passes → commit, mark `completed`. If fails → `git reset --hard <started_at_commit>` + `git clean -fd`, mark `failed` |
 | Yes | Yes | Any | Commit uncommitted changes, run `validation.command`. If passes → mark `completed`. If fails → `git reset --hard <started_at_commit>` + `git clean -fd`, mark `failed` |
 4. **Log recovery**: `[timestamp] [SESSION-N] RECOVERY [task-id] action="<action taken>" reason="<reason>"`
 ## Error Handling & Recovery Strategies
 Each error category has a default recovery strategy:
 | Category | Default Recovery | Agent Action |
 |----------|-----------------|--------------|
 | `ENV_SETUP` | Re-run init, then STOP if still failing | Run `harness-init.sh` again immediately. If fails twice, log and stop — environment is broken |
 | `TASK_EXEC` | Rollback via `git reset --hard <started_at_commit>`, retry | Verify `started_at_commit` exists (`git cat-file -t <hash>`). If missing, mark failed at max_attempts. Otherwise reset, run `on_failure.cleanup` if defined, retry if attempts < max_attempts |
 | `TEST_FAIL` | Rollback via `git reset --hard <started_at_commit>`, retry | Reset to `started_at_commit`, analyze test output to identify fix, retry with targeted changes |
 | `TIMEOUT` | Kill process, execute cleanup, retry | Wrap validation with `timeout <seconds> <command>`. On timeout, run `on_failure.cleanup`, retry (consider splitting task if repeated) |
 | `DEPENDENCY` | Skip task, mark blocked | Log which dependency failed, mark task as `failed` with dependency reason |
 | `SESSION_TIMEOUT` | Use Context Window Recovery Protocol | New session assesses partial progress via Recovery Protocol — may result in completion or failure depending on validation |
 **JSON corruption**: If `harness-tasks.json` cannot be parsed, check for `harness-tasks.json.bak` (written before each modification). If backup exists and is valid, restore from it. If no valid backup, log `ERROR [ENV_SETUP] harness-tasks.json corrupted and unrecoverable` and STOP — task metadata (validation commands, dependencies, cleanup) cannot be reconstructed from logs alone.
 **Backup protocol**: Before every write to `harness-tasks.json`, copy the current file to `harness-tasks.json.bak`.
 ## Environment Initialization
 If `harness-init.sh` exists in the project root, run it at every session start. The script must be idempotent.
 Example `harness-init.sh`:
 ```bash
 #!/bin/bash
 set -e
 npm install 2>/dev/null || pip install -r requirements.txt 2>/dev/null || true
 curl -sf http://localhost:5432 >/dev/null 2>&1 || echo "WARN: DB not reachable"
 npm test -- --bail --silent 2>/dev/null || echo "WARN: Smoke test failed"
 echo "Environment health check complete"
 ```
 ## Standardized Log Format
 All log entries use grep-friendly format on a single line:
 ```
 [ISO-timestamp] [SESSION-N] <TYPE> [task-id]? [category]? message
 ```
 `[task-id]` and `[category]` are included when applicable (task-scoped entries). Session-level entries (`INIT`, `LOCK`, `STATS`) omit them.
 Types: `INIT`, `Starting`, `Completed`, `ERROR`, `CHECKPOINT`, `ROLLBACK`, `RECOVERY`, `STATS`, `LOCK`, `WARN`
 Error categories: `ENV_SETUP`, `TASK_EXEC`, `TEST_FAIL`, `TIMEOUT`, `DEPENDENCY`, `SESSION_TIMEOUT`
 Filtering:
 ```bash
 grep "ERROR" harness-progress.txt                    # All errors
 grep "ERROR" harness-progress.txt | grep "TASK_EXEC" # Execution errors only
 grep "SESSION-3" harness-progress.txt                # All session 3 activity
 grep "STATS" harness-progress.txt                    # All session summaries
 grep "CHECKPOINT" harness-progress.txt               # All checkpoints
 grep "RECOVERY" harness-progress.txt                 # All recovery actions
 ```
 ## Session Statistics
 At session end, update `harness-tasks.json`: increment `session_count`, set `last_session` to current timestamp. Then append:
 ```
 [timestamp] [SESSION-N] STATS tasks_total=10 completed=7 failed=1 pending=2 blocked=0 attempts_total=12 checkpoints=23
 ```
 `blocked` is computed at stats time: count of pending tasks whose `depends_on` includes a permanently failed task. It is not a stored status value.
 ## Init Command (`/harness init`)
 1. Create `harness-progress.txt` with initialization entry
 2. Create `harness-tasks.json` with empty task list and default `session_config`
 3. Optionally create `harness-init.sh` template (chmod +x)
 4. Ask user: add harness files to `.gitignore`?
 ## Status Command (`/harness status`)
 Read `harness-tasks.json` and `harness-progress.txt`, then display:
 1. Task summary: count by status (completed, failed, pending, blocked). `blocked` = pending tasks whose `depends_on` includes a permanently failed task (computed, not a stored status).
 2. Per-task one-liner: `[status] task-id: title (attempts/max_attempts)`
 3. Last 5 lines from `harness-progress.txt`
 4. Session count and last session timestamp
 Does NOT acquire the lock (read-only operation).
 ## Add Command (`/harness add`)
 Append a new task to `harness-tasks.json` with auto-incremented id (`task-NNN`), status `pending`, default `max_attempts: 3`, empty `depends_on`, and no validation command. Prompt user for optional fields: `priority`, `depends_on`, `validation.command`, `timeout_seconds`. Requires lock acquisition (modifies JSON).
 ## Tool Dependencies
 Requires: Bash, file read/write, git. All harness operations must be executed from the project root directory.
 Does NOT require: specific MCP servers, programming languages, or test frameworks.
Author	SHA1	Message	Date
cexll	791bd03724	fix installer offline fallback and remove codex/gemini skills	2026-02-22 16:45:26 +08:00
cexll	8252b67567	fix(executor): filter codex_core stderr noise	2026-02-18 16:32:59 +08:00
ben	207d3c5436	Merge pull request #147 from AsakiEmura/fix/unset-claudecode-env fix(executor): unset CLAUDECODE env to prevent nested session rejection	2026-02-18 16:32:18 +08:00
lza	5fe8c24f55	fix(executor): unset CLAUDECODE env to prevent nested session rejection Claude Code v2.1.41+ sets CLAUDECODE=1 in all child Bash processes and rejects startup when the variable is present. When codeagent-wrapper spawns `claude -p` as a subprocess, it inherits this variable and gets blocked with "cannot be launched inside another Claude Code session". Add UnsetEnv method to commandRunner interface and strip CLAUDECODE before spawning the claude backend. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-18 07:56:25 +08:00
cexll	1dd7b23942	feat harness skill	2026-02-14 23:58:38 +08:00
cexll	664d82795a	fixed do worktree use error	2026-02-14 23:58:20 +08:00
cexll	7cc7f50f46	docs: add bilingual README (EN + CN) reflecting current codebase Rewrite README.md in English and add README_CN.md in Chinese with language switcher links. Updated to cover all recent features: worktree isolation, skill auto-detection, dynamic agents, per-backend config, allowed/disallowed tools, stderr noise filtering, cross-platform support, and modular internal/ project structure. Generated with SWE-Agent.ai Co-Authored-By: SWE-Agent.ai <noreply@swe-agent.ai>	2026-02-10 23:13:06 +08:00