Skip to content

Commit 42d1a3d

Browse files
shinezyySihaoLiu
shinezyy
and
SihaoLiu
authored
feat: skills for codex + stop-gate wrapper (#31) (v1.11.0)
* feat: skills for codex + stop-gate wrapper - Add unified skill installer and docs for Codex/Kimi - Add rlcr-stop-gate wrapper to reuse stop-hook logic in skill mode - Make RLCR default models runtime-aware (plugin: gpt-5.3-codex, skill: gpt-5.2) - Add tests for stop-gate wrapper * Simplify Codex/Kimi skill install without HUMANIZE_ROOT * bump version * Fix PR review issues and bump version to 1.11.0 - Bump version to 1.11.0 in plugin.json, marketplace.json, README.md - rlcr-stop-gate.sh: capture hook exit code explicitly to map non-zero to exit 20 instead of leaking raw hook exit codes via set -e - rlcr-stop-gate.sh: add standard Stop hook fields (hook_event_name, stop_hook_active, cwd) to constructed JSON input - install-skill.sh: use awk ENVIRON instead of -v to avoid backslash escape interpretation; clean up temp file on awk failure - Unify runtime-aware model default logic in loop-common.sh as single source of truth, removing duplicate detection from setup-rlcr-loop.sh and loop-codex-stop-hook.sh - Fix Kimi doc showing plugin-mode default model instead of skill-mode * Use pull_request_target for claude-code-review workflow Switch from pull_request to pull_request_target so fork PRs can access OIDC tokens and secrets needed by claude-code-action. Explicitly checkout the PR head SHA since pull_request_target defaults to the base branch. * Fix stop-gate dead option, test temp dir leak, and install-skill cp atomicity - Remove --tasks-base-dir from rlcr-stop-gate.sh (hook never consumed it) - Fix test-stop-gate.sh to use single setup_test_dir call with subdirs, preventing EXIT trap overwrite that leaked first temp directory - Add exit-0 (allow) test cases for stop gate with no active loop - Make install-skill.sh cp fallback atomic: copy to temp sibling first, then swap into place to avoid data loss on partial copy failure * Fix runtime model detection using script path instead of CLAUDE_PLUGIN_ROOT CLAUDE_PLUGIN_ROOT is a config-time template variable that Claude Code substitutes when loading plugin configs, not a runtime environment variable. The previous check always evaluated to false, causing gpt-5.2 to be selected even in plugin mode. Use BASH_SOURCE path to detect if the script runs from .claude/plugins/cache/ instead. * minor: remove reference to codex in state.md block modification --------- Co-authored-by: Sihao Liu <sihao@cs.ucla.edu>
1 parent d28a5be commit 42d1a3d

File tree

18 files changed

+1468
-29
lines changed

18 files changed

+1468
-29
lines changed

‎.claude-plugin/marketplace.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
"name": "humanize",
99
"source": "./",
1010
"description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
11-
"version": "1.10.7"
11+
"version": "1.11.0"
1212
}
1313
]
1414
}

‎.claude-plugin/plugin.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "humanize",
33
"description": "Humanize - An iterative development plugin that uses Codex to review Claude's work. Creates a feedback loop where Claude implements plans and Codex independently reviews progress, ensuring quality through continuous refinement.",
4-
"version": "1.10.7",
4+
"version": "1.11.0",
55
"author": {
66
"name": "humania-org"
77
},

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Humanize
22

3-
**Current Version: 1.10.7**
3+
**Current Version: 1.11.0**
44

55
> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.
66
@@ -49,6 +49,8 @@ If you have the plugin cloned locally:
4949
claude --plugin-dir /path/to/humanize
5050
```
5151

52+
For Codex skill runtime installation, see [Install Humanize Skills for Codex](docs/install-for-codex.md).
53+
5254
### Prerequisites
5355

5456
- `codex` - OpenAI Codex CLI (for review). Check with `codex --version`.

‎docs/install-for-codex.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Install Humanize Skills for Codex
2+
3+
This guide explains how to install the Humanize skills for Codex skill runtime (`$CODEX_HOME/skills`).
4+
5+
## Quick Install (Recommended)
6+
7+
One-line install from anywhere:
8+
9+
```bash
10+
tmp_dir="$(mktemp -d)" && git clone --depth 1 https://github.com/humania-org/humanize.git "$tmp_dir/humanize" && "$tmp_dir/humanize/scripts/install-skills-codex.sh"
11+
```
12+
13+
From the Humanize repo root:
14+
15+
```bash
16+
./scripts/install-skills-codex.sh
17+
```
18+
19+
Or use the unified installer directly:
20+
21+
```bash
22+
./scripts/install-skill.sh --target codex
23+
```
24+
25+
This will:
26+
- Sync `humanize`, `humanize-gen-plan`, and `humanize-rlcr` into `${CODEX_HOME:-~/.codex}/skills`
27+
- Copy runtime dependencies into `${CODEX_HOME:-~/.codex}/skills/humanize`
28+
- Use RLCR defaults: `codex exec` with `gpt-5.2:xhigh`, `codex review` with `gpt-5.2:high`
29+
30+
## Verify
31+
32+
```bash
33+
ls -la "${CODEX_HOME:-$HOME/.codex}/skills"
34+
```
35+
36+
Expected directories:
37+
- `humanize`
38+
- `humanize-gen-plan`
39+
- `humanize-rlcr`
40+
41+
Runtime dependencies in `humanize/`:
42+
- `scripts/`
43+
- `hooks/`
44+
- `prompt-template/`
45+
46+
Installed files/directories:
47+
- `${CODEX_HOME:-~/.codex}/skills/humanize/SKILL.md`
48+
- `${CODEX_HOME:-~/.codex}/skills/humanize-gen-plan/SKILL.md`
49+
- `${CODEX_HOME:-~/.codex}/skills/humanize-rlcr/SKILL.md`
50+
- `${CODEX_HOME:-~/.codex}/skills/humanize/scripts/`
51+
- `${CODEX_HOME:-~/.codex}/skills/humanize/hooks/`
52+
- `${CODEX_HOME:-~/.codex}/skills/humanize/prompt-template/`
53+
54+
## Optional: Install for Both Codex and Kimi
55+
56+
```bash
57+
./scripts/install-skill.sh --target both
58+
```
59+
60+
## Useful Options
61+
62+
```bash
63+
# Preview without writing
64+
./scripts/install-skills-codex.sh --dry-run
65+
66+
# Custom Codex skills dir
67+
./scripts/install-skills-codex.sh --codex-skills-dir /custom/codex/skills
68+
```
69+
70+
## Troubleshooting
71+
72+
If scripts are not found from installed skills:
73+
74+
```bash
75+
ls -la "${CODEX_HOME:-$HOME/.codex}/skills/humanize/scripts"
76+
```

‎docs/install-for-kimi.md‎

Lines changed: 243 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,243 @@
1+
# Install Humanize for Kimi CLI
2+
3+
This guide explains how to install the Humanize skills for [Kimi Code CLI](https://github.com/MoonshotAI/kimi-cli).
4+
5+
## Overview
6+
7+
Humanize provides three Agent Skills for kimi:
8+
9+
| Skill | Type | Purpose |
10+
|-------|------|---------|
11+
| `humanize` | Standard | General guidance for all workflows |
12+
| `humanize-gen-plan` | Flow | Generate structured plan from draft |
13+
| `humanize-rlcr` | Flow | Iterative development with Codex review |
14+
15+
## Installation
16+
17+
### Quick Install (Recommended)
18+
19+
From the Humanize repo root, run:
20+
21+
```bash
22+
./scripts/install-skills-kimi.sh
23+
```
24+
25+
This command will:
26+
- Sync `humanize`, `humanize-gen-plan`, and `humanize-rlcr` into `~/.config/agents/skills`
27+
- Copy runtime dependencies into `~/.config/agents/skills/humanize`
28+
29+
Common installer script (all targets):
30+
31+
```bash
32+
./scripts/install-skill.sh --target kimi
33+
```
34+
35+
### Manual Install
36+
37+
### 1. Clone or navigate to the humanize repository
38+
39+
```bash
40+
cd /path/to/humanize
41+
```
42+
43+
### 2. Copy skills and runtime bundle to kimi's skills directory
44+
45+
```bash
46+
# Create the skills directory if it doesn't exist
47+
mkdir -p ~/.config/agents/skills
48+
49+
# Copy all three skills
50+
cp -r skills/humanize ~/.config/agents/skills/
51+
cp -r skills/humanize-gen-plan ~/.config/agents/skills/
52+
cp -r skills/humanize-rlcr ~/.config/agents/skills/
53+
54+
# Copy runtime dependencies used by the skills
55+
cp -r scripts ~/.config/agents/skills/humanize/
56+
cp -r hooks ~/.config/agents/skills/humanize/
57+
cp -r prompt-template ~/.config/agents/skills/humanize/
58+
59+
# Hydrate runtime root placeholders inside SKILL.md files
60+
for skill in humanize humanize-gen-plan humanize-rlcr; do
61+
sed -i.bak "s|{{HUMANIZE_RUNTIME_ROOT}}|$HOME/.config/agents/skills/humanize|g" \
62+
"$HOME/.config/agents/skills/$skill/SKILL.md"
63+
done
64+
```
65+
66+
### 3. Verify installation
67+
68+
```bash
69+
# List installed skills
70+
ls -la ~/.config/agents/skills/
71+
72+
# Should show:
73+
# humanize/
74+
# humanize-gen-plan/
75+
# humanize-rlcr/
76+
```
77+
78+
### 4. Restart kimi (if already running)
79+
80+
Skills are loaded at startup. Restart kimi to pick up the new skills:
81+
82+
```bash
83+
# Exit current kimi session
84+
/exit
85+
86+
# Or press Ctrl-D
87+
88+
# Start kimi again
89+
kimi
90+
```
91+
92+
## Usage
93+
94+
### List available skills
95+
96+
```bash
97+
/help
98+
```
99+
100+
Look for the "Skills" section in the help output.
101+
102+
### Use the skills
103+
104+
#### 1. Generate plan from draft
105+
106+
```bash
107+
# Start the flow (will ask for input/output paths)
108+
/flow:humanize-gen-plan
109+
110+
# Or load as standard skill
111+
/skill:humanize-gen-plan
112+
```
113+
114+
#### 2. Start RLCR development loop
115+
116+
```bash
117+
# Start with plan file
118+
/flow:humanize-rlcr path/to/plan.md
119+
120+
# With options
121+
/flow:humanize-rlcr path/to/plan.md --max 20 --push-every-round
122+
123+
# Skip implementation, go directly to code review
124+
/flow:humanize-rlcr --skip-impl
125+
126+
# Load as standard skill (no auto-execution)
127+
/skill:humanize-rlcr
128+
```
129+
130+
#### 3. Get general guidance
131+
132+
```bash
133+
/skill:humanize
134+
```
135+
136+
## Command Options
137+
138+
### RLCR Loop Options
139+
140+
| Option | Description | Default |
141+
|--------|-------------|---------|
142+
| `path/to/plan.md` | Plan file path | Required (unless --skip-impl) |
143+
| `--max N` | Maximum iterations | 42 |
144+
| `--codex-model MODEL:EFFORT` | Codex model | gpt-5.2:xhigh |
145+
| `--codex-timeout SECONDS` | Review timeout | 5400 |
146+
| `--base-branch BRANCH` | Base for code review | auto-detect |
147+
| `--full-review-round N` | Full alignment check interval | 5 |
148+
| `--skip-impl` | Skip to code review | false |
149+
| `--push-every-round` | Push after each round | false |
150+
151+
### Generate Plan Options
152+
153+
| Option | Description | Required |
154+
|--------|-------------|----------|
155+
| `--input <path>` | Draft file path | Yes |
156+
| `--output <path>` | Plan output path | Yes |
157+
158+
## Prerequisites
159+
160+
Ensure you have `codex` CLI installed:
161+
162+
```bash
163+
codex --version
164+
```
165+
166+
The skills will use `gpt-5.2` with `xhigh` effort level by default.
167+
168+
## Uninstall
169+
170+
To remove the skills:
171+
172+
```bash
173+
rm -rf ~/.config/agents/skills/humanize
174+
rm -rf ~/.config/agents/skills/humanize-gen-plan
175+
rm -rf ~/.config/agents/skills/humanize-rlcr
176+
```
177+
178+
## Troubleshooting
179+
180+
### Skills not showing up
181+
182+
1. Check the skills directory exists:
183+
```bash
184+
ls ~/.config/agents/skills/
185+
```
186+
187+
2. Ensure SKILL.md files are present:
188+
```bash
189+
cat ~/.config/agents/skills/humanize/SKILL.md | head -5
190+
```
191+
192+
3. Restart kimi completely
193+
194+
### Codex not found
195+
196+
The skills expect `codex` to be in your PATH. If using a proxy, ensure `~/.zprofile` is configured:
197+
198+
```bash
199+
# Add to ~/.zprofile if needed
200+
export OPENAI_API_KEY="your-api-key"
201+
# or other proxy settings
202+
```
203+
204+
### Scripts not found
205+
206+
If skills report missing scripts like `setup-rlcr-loop.sh`, verify:
207+
208+
```bash
209+
ls -la ~/.config/agents/skills/humanize/scripts
210+
```
211+
212+
### Installer options
213+
214+
The installer supports:
215+
216+
```bash
217+
./scripts/install-skill.sh --help
218+
```
219+
220+
Common examples:
221+
222+
```bash
223+
# Preview only
224+
./scripts/install-skills-kimi.sh --dry-run
225+
226+
# Custom skills directory
227+
./scripts/install-skills-kimi.sh --skills-dir /custom/skills/dir
228+
```
229+
230+
### Output files not found
231+
232+
The skills save output to:
233+
- Cache: `~/.cache/humanize/<project>/<timestamp>/`
234+
- Loop data: `.humanize/rlcr/<timestamp>/`
235+
236+
Ensure these directories are writable.
237+
238+
## See Also
239+
240+
- [Kimi CLI Documentation](https://moonshotai.github.io/kimi-cli/)
241+
- [Agent Skills Format](https://agentskills.io/)
242+
- [Install for Codex](./install-for-codex.md)
243+
- [Humanize README](../README.md)

‎hooks/lib/loop-common.sh‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,23 @@ readonly FIELD_SESSION_ID="session_id"
4040
readonly FIELD_AGENT_TEAMS="agent_teams"
4141

4242
# Default Codex configuration (single source of truth - all scripts reference this)
43-
# Both use :- so scripts can override before sourcing (e.g. PR loop sets different model/effort)
44-
DEFAULT_CODEX_MODEL="${DEFAULT_CODEX_MODEL:-gpt-5.3-codex}"
43+
# Both use :- so scripts can override before sourcing (e.g. PR loop sets different model/effort).
44+
#
45+
# Runtime-aware model selection:
46+
# Detect Claude Code plugin mode by checking if this script lives under
47+
# .claude/plugins/cache/ (CLAUDE_PLUGIN_ROOT is a config-time template
48+
# variable, not a runtime env var, so we cannot check it directly).
49+
# - Claude Code plugin mode -> gpt-5.3-codex
50+
# - Skill mode (Codex/Kimi) -> gpt-5.2
51+
if [[ -z "${DEFAULT_CODEX_MODEL:-}" ]]; then
52+
_LOOP_COMMON_SELF="${BASH_SOURCE[0]:-$0}"
53+
if [[ "$_LOOP_COMMON_SELF" == */.claude/plugins/cache/* ]]; then
54+
DEFAULT_CODEX_MODEL="gpt-5.3-codex"
55+
else
56+
DEFAULT_CODEX_MODEL="gpt-5.2"
57+
fi
58+
unset _LOOP_COMMON_SELF
59+
fi
4560
DEFAULT_CODEX_EFFORT="${DEFAULT_CODEX_EFFORT:-xhigh}"
4661

4762
# Codex review markers

0 commit comments

Comments
 (0)