skills-win/langgraph-plan-review/SKILL.md

name, description

name

description

langgraph-plan-review

Use the LangGraph plan-review workflow from the current Claude Code session. Trigger when the user asks to create Taskxx plans, run the Claude/Codex review loop, generate or revise Notes/Taskxx.md, or use the LangGraph workflow described by Task00.md. This skill uses the current Claude Code environment for Claude steps and only invokes the Python LangGraph app for Codex review and discuss file numbering.

LangGraph Plan Review Workflow

Use this skill to run the LangGraph plan-review workflow. All scripts are bundled under the skill's own scripts\ directory (C:\Users\bowei\.claude\skills\langgraph-plan-review\scripts\) — no dependency on E:\LangGraph_Design\lab00.

⚠️ 强制执行规则（MANDATORY — read first）

plan-review 工作流必须、且只能通过 langgraph dev 服务器来驱动。

• ✅ 唯一允许的入口：run_langgraph.ps1 → run_workflow.py。后者是一个纯 REST/SDK 客户端 （langgraph_sdk.get_sync_client(url=http://127.0.0.1:2024)），每次 start/resume 都把 run 投递到 langgraph dev 服务器执行。先用 manage_dev_server.ps1 start 把服务器拉起。 这样 LangGraph Studio 才能实时追踪线程、节点、中断与状态。

• 🚫 绝对禁止：直接 import / 在进程内运行本 skill 的图定义模块 （scripts\graph.py、scripts\workflow.py、scripts\agents.py）来跑工作流。包括但不限于：

  • python -c "from graph import ...; graph.invoke(...)" 或 .stream(...)
  • 写临时脚本 build 编译图后在进程内调用
  • 任何绕过 http://127.0.0.1:2024 的「就地执行」方式

  这类调用在 dev server 进程之外运行，Studio 追踪不到状态，一律不允许—— 即使只是想「快速验证一个节点」也不行。

• ℹ️ 例外说明：review_task.py（Codex 评审 shim）会直接调 codex，这是合规的—— 它是由运行在 dev server 内的图通过 codex_review_command 调起的评审步骤，不是绕过 dev server 去驱动工作流本身。区别在于：驱动图 = 必须走 dev server；图内部调用的工具 = 正常。

• 🛠 改了 graph.py/workflow.py/agents.py 后：dev server 内存里仍是旧代码。先 manage_dev_server.ps1 stop 再 start（或让 --reload 生效），再经 run_langgraph.ps1 重跑，使改动在被追踪的运行中生效。

Pre-flight: Environment Setup

Before running the workflow for the first time (or when unsure the environment is ready), verify that the required packages are installed in the langgraph conda env:

# Install langgraph dev server, SDK, and HTTP client
conda run -n langgraph pip install "langgraph-cli[inmem]" langgraph-sdk httpx

# Verify the SDK is importable
conda run -n langgraph python -c "from langgraph_sdk import get_sync_client; print('SDK OK')"

# Verify the langgraph dev command is available
conda run -n langgraph langgraph --version

Package	Purpose
langgraph-cli[inmem]	Provides the langgraph dev server command
langgraph-sdk	Python client used by run_workflow.py to submit runs
httpx	HTTP health-check in run_workflow.py

Codex auth (if not already set up): C:\Users\bowei\.codex\auth.json must contain a valid ChatGPT OAuth token. Run codex auth login if the file is missing.

Invariants

• Drive the graph only through the dev server (see the mandatory rule above): run_langgraph.ps1 → run_workflow.py → http://127.0.0.1:2024. Never import or run graph.py/workflow.py/agents.py in-process to execute the workflow — that bypasses the dev server and LangGraph Studio cannot track it.
• Use the current Claude Code session for all Claude Code work. Do not launch another claude process.
• Assume the current Claude Code session already has --dangerously-skip-permissions.
• Run Python through the recorded conda environment. run_langgraph.ps1 resolves conda from -CondaExe, CONDA_EXE, conda on PATH, or the user-profile miniconda fallback:

  <resolved conda.exe> run -n langgraph python
  

• Codex CLI is installed in the langgraph conda env as codex.cmd at C:\Users\bowei\.conda\envs\langgraph\codex.cmd. It must be invoked via cmd /c because .cmd files are not directly executable by Python subprocess on Windows.
• Codex auth uses ChatGPT OAuth tokens stored in C:\Users\bowei\.codex\auth.json. No API key is needed.
• run_langgraph.ps1 sets CODEX_HOME from -CodexHome, existing CODEX_HOME, or <UserProfile>\.codex.
• Always use review_task.py as the Codex review shim. Pass it via --codex-review-command as a JSON array with no spaces. This shim handles all Windows-specific codex invocation requirements: cmd /c, stdin prompt passing, --skip-git-repo-check, session resume, and explicit cwd.
• Keep all workflow files under <Claude launch work_dir>\Notes unless the user explicitly overrides -NotesDir.
• TaskId is the numeric suffix, such as 01; write the plan to Notes\Task01.md.
• discussxx-yy.md numbering is managed by the LangGraph app for Codex review files. If Claude rejects a review comment, create the next numbered discuss file manually before rerunning review.
• The workflow uses LangGraph interrupt() and persists state via the langgraph dev server.
• Each run_langgraph.ps1 invocation advances the graph to the next interrupt or completion. Use -Resume to continue the same thread after completing the requested Claude Code action.

Dev Server Lifecycle

The langgraph dev server must be running for the entire duration of a workflow session. Use manage_dev_server.ps1 to start it before the first run_langgraph.ps1 call and stop it after the workflow completes.

# Start (idempotent — safe to call even if already running)
C:\Users\bowei\.claude\skills\langgraph-plan-review\scripts\manage_dev_server.ps1 start

# Stop (call once when workflow returns {"status":"done"})
C:\Users\bowei\.claude\skills\langgraph-plan-review\scripts\manage_dev_server.ps1 stop

# Status check
C:\Users\bowei\.claude\skills\langgraph-plan-review\scripts\manage_dev_server.ps1 status

• start waits up to 45 s for http://127.0.0.1:2024/ok to respond, then prints the Studio URL.
• stop kills the process by PID file and removes it; falls back to killing by port 2024 if the PID is stale.
• If the server is already running, start is a no-op.
• Server stdout/stderr logs are written to %TEMP%\langgraph_dev_server.stdout.log and %TEMP%\langgraph_dev_server.stderr.log for debugging.
• Studio URL: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 — open in browser to track workflow execution in real time.

Workflow

1. Determine TaskId from the user. If missing, ask for it.

2. Start the dev server (idempotent):

   C:\Users\bowei\.claude\skills\langgraph-plan-review\scripts\manage_dev_server.ps1 start
   

   Wait for the "Ready" confirmation before proceeding. Open the Studio URL in a browser for real-time tracking.

3. Start or resume the LangGraph app:

   # Use double backslashes (\\) in the JSON string so Windows paths are valid JSON.
   # $task_path / $latest_discuss_path / etc. are Python Template placeholders — keep them literal.
   $codexCmd = '["C:\\Users\\bowei\\.conda\\envs\\langgraph\\python.exe","C:\\Users\\bowei\\.claude\\skills\\langgraph-plan-review\\scripts\\review_task.py","$task_path","$latest_discuss_path","$codex_session_id","$work_dir"]'
   C:\Users\bowei\.claude\skills\langgraph-plan-review\scripts\run_langgraph.ps1 `
     -TaskId <TaskId> `
     -Prompt "<original user request>" `
     -CodexReviewCommand $codexCmd `
     -Timeout 300
   

4. Inspect the returned JSON. If status is waiting, perform action_required in the current Claude Code session:

   • write_plan: write Task<TaskId>.md with project background, task objective, and concrete implementation plan, then resume with -Resume 'true'.
   • decide: read the discuss file and resume with -Resume '{"accepts":true}' or -Resume '{"accepts":false,"reason":"..."}'.
   • revise: revise Task<TaskId>.md, then resume with -Resume 'true'.
   • write_rejection: write the specified output_path, then resume with -Resume 'true'.

   Why review_task.py: Using the shim keeps all codex-specific logic in Python, and the JSON array stays simple.

   run_langgraph.ps1 base64-encodes the JSON command and resume payload before passing them through conda run, so normal PowerShell single-quoted JSON can be used. Windows paths inside the JSON string must use \\ (double backslash) to produce valid JSON, e.g. C:\\Users\\bowei\\.... run_langgraph.ps1 automatically sets PYTHONIOENCODING=utf-8 so prompts containing Unicode (Chinese, etc.) pass through correctly.

5. Inspect the command output after each resume.

   • Check "status" to determine next action: "waiting" means perform the next action_required; "done" means the workflow is complete.
   • If a new latest_discuss_path is present in the output, read that discuss file for context.

6. Stop when the workflow returns {"status":"done", ...}:

   C:\Users\bowei\.claude\skills\langgraph-plan-review\scripts\manage_dev_server.ps1 stop
   

Rejection File Rule

When the action_required is write_rejection, the interrupt payload already contains the exact file path:

{"action": "write_rejection", "output_path": "Notes/discuss04-01.md", "reason_hint": "..."}

Write the rejection content directly to action_required.output_path:

# discuss<TaskId>-<yy>

## Claude Code Rejection

<reason>

Notes

• The LangGraph app automatically scans existing discuss files and writes the next Codex review file without overwriting old discussions.
• The app no longer accepts Claude command arguments; Claude actions happen in this current session.
• If codex is unavailable, report that the review step cannot run rather than simulating it.
• review_task.py passes the review prompt through stdin with - to avoid Windows command-line quoting issues with multiline prompts.
• review_task.py passes --skip-git-repo-check so the workflow can run from Claude launch directories that are not git repositories.
• review_task.py reads Codex final output via --output-last-message so intermediate JSONL progress messages are not treated as review findings.
• review_task.py persists the Codex session id through LangGraph state and uses codex exec resume on later review passes.
• review_task.py runs Codex with the original Claude Code launch working directory as cwd.
• Codex review output is normalized to JSON for agents.py: {"has_serious_issue":true/false,"comment":"...","codex_session_id":"..."}.
• If the dev server restarts, run_workflow.py detects that the stored thread no longer exists and creates a new thread automatically.
• run_workflow.py passes the codex command and timeout as config["configurable"] per run — no server restart needed when switching projects.