Skip to content

GitLab

Commit afe46a42 authored by whlwhlwhl's avatar whlwhlwhl
Browse files

Slim LightOp skills package

parents
Pipeline #3632 failed with stages
in 0 seconds
Show whitespace changes
Inline Side-by-side
Showing with 1006 additions and 0 deletions
.claude-plugin/marketplace.json 0 → 100644
View file @ afe46a42
{
"name": "KernelPilot",
"owner": {
"name": "BBuf"
},
"description": "Claude Code marketplace for the Humanize LightOp/DCU operator development and optimization loop.",
"plugins": [
{
"name": "humanize",
"source": "./humanize",
"description": "Humanize plus LightOp/DCU operator workflows, dcu-profiler-report profiling, and review-gated iteration.",
"version": "1.17.0"
}
]
}
.gitignore 0 → 100644
View file @ afe46a42
__pycache__/
.pytest_cache/
.kernel-knowledge/
knowledge/external-repos/
knowledge/evidence/pull-bundles/
.humanize/
.humanize-*/
*.py[cod]
*.egg-info/
README.md 0 → 100644
View file @ afe46a42
<div align="center">
# LightOp KernelPilot
**基于 Humanize 的 LightOp/DCU 算子开发与优化 skill 包。**
</div>
LightOp KernelPilot 是面向 LightOp DCU 算子库的 KernelPilot 工作流改造版。
它保留了自主算子开发循环里真正有用的部分：明确算子语义、正确性参考、
workload 分布、benchmark 证据、profile digest、尝试记录、优化记录，以及
带 review gate 的迭代。
它移除了 NVIDIA 优先的假设，例如 Nsight Compute、CUTLASS/CuTe、PTX/SASS、
Blackwell/Hopper、TMA、WGMMA、tcgen05 等。默认面向 DCU/ROCm/HIP/DTK 环境。
## Skills
| Skill | 作用 |
| --- | --- |
| [`lightop-kernel-agent-loop`](humanize/skills/humanize-kernel-agent-loop/) | 主循环。用于新增或优化 LightOp 算子：恢复 `K/R/W/E`，检查 wrapper/binding/kernel/test/config/benchmark，实现 HIP/ROCm 改动，build、test、benchmark、profile、tune，并启动 Humanize RLCR。 |
| [`lightop-kernel-knowledge`](knowledge/SKILL.md) | 证据检索。优先查本地 LightOp 源码，其次查 ROCm/DCU 上游和官方文档，最后才把 bundled CUDA PR corpus 当作跨平台灵感。 |
| [`dcu-profiler-report`](humanize/skills/ncu-report/) | 性能剖析。把 `hipprof`、ROCm/DTK profiler、benchmark log 和可选 AMDGPU ISA 证据整理成可复现 digest，并给出一个明确的下一步 LightOp 修改。 |
磁盘上的目录名 `humanize-kernel-agent-loop` 和 `ncu-report` 是为了兼容上游
Humanize installer；真正暴露给 agent 的 skill 名称以上表 frontmatter 为准。
## 手动安装
如果没有 Claude 或 Codex CLI installer，可以直接安装这三个 LightOp/DCU
skills：
```bash
./install-lightop-skills-manual.sh --target both
```
只安装 Claude：
```bash
./install-lightop-skills-manual.sh --target claude
```
只安装 Codex：
```bash
./install-lightop-skills-manual.sh --target codex
```
默认路径：
```text
Claude: ~/.claude/skills
Codex: ${CODEX_HOME:-~/.codex}/skills
```
脚本会：
- symlink `lightop-kernel-knowledge`
- symlink `dcu-profiler-report`
- hydrate `lightop-kernel-agent-loop` 中的 `{{HUMANIZE_RUNTIME_ROOT}}` 和
`{{KERNELPILOT_ROOT}}`
- 可选安装 `knowledge/requirements.txt`
## 请求格式
一个清晰的请求最好包含：算子名、正确性参考、workload、执行环境、目标
DCU/gfx arch、baseline、benchmark 方法、成功阈值。
示例：
```text
[$lightop-kernel-agent-loop] 给 LightOp 添加 fused rmsnorm + rope + fp8
kv-cache store 算子，目标 gfx936。正确性参考使用 PyTorch/native LightOp
组合路径，覆盖 Qwen decode 的 batch/token/head_dim shape。验证环境使用
Docker 容器 lightop-dtk，容器内 repo 路径是 /workspace/lightop。
性能要求：p50 latency 比现有 unfused 路径快 15%。
```
优化已有算子的示例：
```text
[$lightop-kernel-agent-loop] 优化 gfx938 上的 lightop.moe_gemm_w8a8，
目标 workload 是 DeepSeek EP8 decode。保持现有 Python API 不变，
和当前 LightOp baseline 对比；benchmark plateau 时使用 hipprof 证据继续分析。
```
如果宿主机路径和容器路径不同，建议直接写清楚：
```text
宿主机 LightOp 路径：/public/wanghl6/lightop
验证容器：wanghl_lightop209
容器内 LightOp 路径：/home/lightop
所有 build、correctness test、benchmark、profiling 都必须在容器内执行：
docker exec wanghl_lightop209 bash -lc 'cd /home/lightop && <command>'
```
## LightOp 接入位置
主循环会在一个 LightOp checkout 中工作。该目录通常包含：
```text
setup.py
setup_torch29.py
lightop/__init__.py
lightop/csrc/export.cpp
lightop/csrc/<family>/
lightop/config*.py
test/
```
新增算子时，agent 通常会检查或修改：
- `lightop/csrc/<family>/`：HIP/C++ kernel 和 launcher
- `lightop/csrc/export.cpp`：`m.def(...)` binding
- `lightop/<op>.py`：Python wrapper
- `lightop/__init__.py`：公开 API export
- `setup.py`：只有新增 `csrc` family 需要 glob 覆盖时才改
- `test/test_<op>.py`：正确性测试
- benchmark 脚本：性能测试
- `lightop/config*.py`：需要 shape/gfx-aware dispatch 时才改
LightOp KernelPilot 的 build 规则固定为：
```bash
python setup.py install
```
无论 PyTorch 版本是什么，都不切到 `setup_torch29.py`。正常调优循环中也不删除
`build/`，以便复用增量编译结果；只有用户明确要求 clean build，或证明 cache
损坏时才清理。
## DCU Profiling
`dcu-profiler-report` 使用 SourceFind DCU 性能分析工具指南作为一阶段官方参考：
```text
https://developer.sourcefind.cn/gitbook//dcu_developer/DeveloperGuide/dcu_programming/DCU_programming_chapter3_7.html
```
默认一阶段 profiling：
```bash
cd /path/to/lightop
mkdir -p .humanize/lightop-agent/profile-artifacts/v000_baseline
python test/test_<op>.py 2>&1 \
| tee .humanize/lightop-agent/profile-artifacts/v000_baseline/benchmark.log
hipprof python test/test_<op>.py 2>&1 \
| tee .humanize/lightop-agent/profile-artifacts/v000_baseline/hipprof.txt
```
当 `hipprof` 和 benchmark log 不够解释问题时，可以进一步使用：
```text
rocprof
rocprofv3
rocprof-compute
AMDGPU ISA / code-object inspection
```
profile digest 不是只写一句 “memory-bound”。它必须给出：
```text
测到什么信号 -> 可能机制是什么 -> 为什么其他假设较弱 -> 下一步具体改哪里
```
## Build And Test 默认规则
build、install、test、benchmark、profiling 必须在同一个环境里完成。如果目标环境是
Docker，优先使用可重复的非交互命令：
```bash
docker exec <container> bash -lc 'cd /workspace/lightop && <command>'
```
在该环境的 LightOp root 下先探测版本和设备：
```bash
python - <<'PY'
import torch
print("torch:", torch.__version__)
print("hip:", torch.version.hip)
print("device:", torch.cuda.get_device_name(0))
print("gcn:", torch.cuda.get_device_properties(0).gcnArchName)
PY
hipcc --version
```
然后 build：
```bash
PYTORCH_ROCM_ARCH='gfx928;gfx936;gfx938' python setup.py install
```
再做 import smoke test：
```bash
python - <<'PY'
import torch, lightop
print("lightop:", getattr(lightop, "__file__", "unknown"))
print("gcn:", torch.cuda.get_device_properties(0).gcnArchName)
PY
```
优先跑最窄的目标测试：
```bash
cd test
python test_<op>.py
```
benchmark 必须包含 warmup，并且在计时区间前后显式使用
`torch.cuda.synchronize()` 或 HIP 同步。不能只凭 Python wall-clock 异步计时宣布
加速。
一个 LightOp 算子改动不能只靠 build 通过就算完成。完成条件至少包括：
- install 成功
- import smoke test 成功
- targeted correctness test 成功
- benchmark 和 baseline 对比完成
- 当结果接近阈值或异常时，有 profiler 证据
## 常规安装
从当前 checkout 安装 Humanize skill pack：
```bash
cd /path/to/kernel-pilot
./humanize/scripts/install-skill.sh --target codex --kernelpilot-root "$PWD"
```
Claude Code 用户可以使用：
```bash
./humanize/scripts/install-skills-claude.sh --kernelpilot-root "$PWD"
```
安装后相关 skill 名称是：
```text
lightop-kernel-agent-loop
lightop-kernel-knowledge
dcu-profiler-report
```
## 证据规则
- 本地 LightOp 源码、测试、配置和 benchmark 是第一优先级证据。
- ROCm/DCU 官方文档和上游源码是第二优先级证据。
- bundled CUDA PR corpus 只能作为跨平台灵感，除非已经明确翻译并在 DCU 上验证。
- 复制或改写外部源码时，必须记录来源路径/URL、commit 或 version、
license/notice，以及优化收益。
- profile digest 最后必须给出一个具体的下一步修改；如果 profiling 不可执行，
要说明原因。
humanize/.claude-plugin/marketplace.json 0 → 100644
View file @ afe46a42
{
"name": "PolyArch",
"owner": {
"name": "PolyArch"
},
"description": "Humanize RLCR plugin packaged with LightOp/DCU operator-loop skills.",
"plugins": [
{
"name": "humanize",
"source": "./",
"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.",
"version": "1.17.0"
}
]
}
humanize/.claude-plugin/plugin.json 0 → 100644
View file @ afe46a42
{
"name": "humanize",
"description": "Humanize packaged with LightOp/DCU operator-loop skills for adding, optimizing, benchmarking, and profiling fused ROCm operators with review-gated iteration.",
"version": "1.17.0",
"author": {
"name": "PolyArch"
},
"repository": "https://github.com/PolyArch/humanize",
"homepage": "https://github.com/PolyArch/humanize#readme",
"license": "MIT",
"keywords": [
"iterative-development",
"codex-review",
"ai-native",
"feedback-loop",
"goal-tracking",
"quality-assurance",
"lightop",
"dcu",
"rocm",
"hip"
]
}
humanize/.claude/CLAUDE.md 0 → 100644
View file @ afe46a42
# Humanize Introduction
This is a Claude Code plugin that provides iterative development with Codex review. Use `/start-rlcr-loop` to start an RLCR loop, and `/cancel-rlcr-loop` to cancel an active loop.
# Humanize Project Rules
- Everything about this project, including but not limited to implementations, comments, tests and documentations should be in English. No Emoji or CJK char is allowed.
- If version bump is required, please bump them in three files: `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` and `README.md` (the "Current Version" line).
- Version number must be in format of `X.Y.Z` where X/Y/Z is numeric number. Version MUST NOT include anything other than `X.Y.Z`. For example, a good version is `9.732.42`; Bad version examples (MUST NOT USE): `3.22.7-alpha` (extra "-alpha" string), `9.77.2 (2026-01-07)` (useless date/timestamp).
- The plan template in `commands/gen-plan.md` (Phase 5 Plan Structure section) and `prompt-template/plan/gen-plan-template.md` are intentionally kept in sync. When modifying either file, ensure both are updated to maintain consistency.
- Conversely, changes to `prompt-template/plan/gen-plan-template.md` must also be reflected in the Plan Structure section of `commands/gen-plan.md`.
humanize/.github/workflows/plan-file-test.yml 0 → 100644
View file @ afe46a42
name: Plan File Validation Tests
on:
push:
paths:
- 'scripts/setup-rlcr-loop.sh'
- 'hooks/loop-plan-file-validator.sh'
- 'hooks/loop-codex-stop-hook.sh'
- 'hooks/loop-write-validator.sh'
- 'hooks/loop-edit-validator.sh'
- 'hooks/loop-bash-validator.sh'
- 'hooks/lib/loop-common.sh'
- 'tests/test-plan-file-*.sh'
- 'tests/test-state-exit-naming.sh'
- 'tests/test-cancel-signal-file.sh'
- 'commands/cancel-rlcr-loop.md'
pull_request:
paths:
- 'scripts/setup-rlcr-loop.sh'
- 'hooks/loop-plan-file-validator.sh'
- 'hooks/loop-codex-stop-hook.sh'
- 'hooks/loop-write-validator.sh'
- 'hooks/loop-edit-validator.sh'
- 'hooks/loop-bash-validator.sh'
- 'hooks/lib/loop-common.sh'
- 'tests/test-plan-file-*.sh'
- 'tests/test-state-exit-naming.sh'
- 'tests/test-cancel-signal-file.sh'
- 'commands/cancel-rlcr-loop.md'
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
sudo apt-get update
sudo apt-get install -y jq
- name: Run plan file validation tests
run: |
chmod +x tests/test-plan-file-validation.sh
./tests/test-plan-file-validation.sh
- name: Run plan file hook tests
run: |
chmod +x tests/test-plan-file-hooks.sh
./tests/test-plan-file-hooks.sh
- name: Run state exit naming tests
run: |
chmod +x tests/test-state-exit-naming.sh
./tests/test-state-exit-naming.sh
- name: Run cancel signal file tests
run: |
chmod +x tests/test-cancel-signal-file.sh
./tests/test-cancel-signal-file.sh
humanize/.github/workflows/pr-target-check.yml 0 → 100644
View file @ afe46a42
name: PR Target Branch Check
on:
pull_request:
branches: [main, dev]
jobs:
check-target-branch:
runs-on: ubuntu-latest
steps:
- name: Enforce branch targeting rules
run: |
SOURCE="${{ github.head_ref }}"
TARGET="${{ github.base_ref }}"
echo "Source branch: $SOURCE"
echo "Target branch: $TARGET"
if [ "$TARGET" = "main" ] && [ "$SOURCE" != "dev" ]; then
echo ""
echo "========================================"
echo "FAILED: Only 'dev' branch can target 'main'."
echo ""
echo "Your branch '$SOURCE' must target 'dev' instead."
echo "Please change the base branch of this PR to 'dev'."
echo "========================================"
exit 1
fi
echo ""
echo "========================================"
echo "PASSED: Branch targeting rule satisfied."
echo "========================================"
humanize/.github/workflows/run-all-tests.yml 0 → 100644
View file @ afe46a42
name: Run All Tests
on:
push:
branches: ['**']
pull_request:
branches: ['**']
jobs:
run-all-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install dependencies
run: sudo apt-get update && sudo apt-get install -y zsh jq
- name: Run all tests
run: |
chmod +x tests/run-all-tests.sh
./tests/run-all-tests.sh
humanize/.github/workflows/shell-syntax-check.yml 0 → 100644
View file @ afe46a42
name: Shell Syntax Check
on:
push:
branches: ['**']
pull_request:
branches: ['**']
jobs:
shell-syntax-check:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install zsh
run: sudo apt-get update && sudo apt-get install -y zsh
- name: Find all shell scripts
id: find-scripts
run: |
scripts=$(find . -name "*.sh" -type f | sort)
echo "Found shell scripts:"
echo "$scripts"
echo "scripts<<EOF" >> $GITHUB_OUTPUT
echo "$scripts" >> $GITHUB_OUTPUT
echo "EOF" >> $GITHUB_OUTPUT
- name: Check bash syntax
run: |
echo "Checking bash syntax for all .sh files..."
exit_code=0
while IFS= read -r script; do
if [ -n "$script" ]; then
echo "Checking: $script"
if bash -n "$script"; then
echo " bash: OK"
else
echo " bash: FAILED"
exit_code=1
fi
fi
done <<< "${{ steps.find-scripts.outputs.scripts }}"
exit $exit_code
- name: Check zsh syntax
run: |
echo "Checking zsh syntax for all .sh files..."
exit_code=0
while IFS= read -r script; do
if [ -n "$script" ]; then
echo "Checking: $script"
if zsh -n "$script"; then
echo " zsh: OK"
else
echo " zsh: FAILED"
exit_code=1
fi
fi
done <<< "${{ steps.find-scripts.outputs.scripts }}"
exit $exit_code
humanize/.github/workflows/template-test.yml 0 → 100644
View file @ afe46a42
name: Template Loader Tests
on:
push:
branches: ['**']
paths:
- 'prompt-template/**'
- 'hooks/**'
- 'tests/**'
- '.github/workflows/template-test.yml'
pull_request:
branches: ['**']
paths:
- 'prompt-template/**'
- 'hooks/**'
- 'tests/**'
- '.github/workflows/template-test.yml'
jobs:
template-tests:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Run template loader unit tests
run: |
echo "========================================"
echo "Running template loader unit tests"
echo "========================================"
chmod +x tests/test-template-loader.sh
./tests/test-template-loader.sh
- name: Run comprehensive template validation
run: |
echo "========================================"
echo "Running comprehensive template validation"
echo "========================================"
chmod +x tests/test-templates-comprehensive.sh
./tests/test-templates-comprehensive.sh
- name: Verify template references exist
run: |
echo "========================================"
echo "Verifying all template references exist"
echo "========================================"
chmod +x tests/test-template-references.sh
./tests/test-template-references.sh
- name: Verify all hook scripts still work
run: |
echo "========================================"
echo "Verifying hook scripts can source templates"
echo "========================================"
# Test that all hook scripts can source the template loader
for script in hooks/loop-*.sh; do
echo "Testing: $script"
# Just source the script in a subshell to verify no errors
# We can't actually run them without the proper environment
bash -n "$script" && echo " Syntax: OK"
done
echo ""
echo "All hook scripts are valid"
humanize/.github/workflows/version-bump-check.yml 0 → 100644
View file @ afe46a42
name: Version Bump Check
on:
pull_request:
branches: [main]
jobs:
version-bump-check:
runs-on: ubuntu-latest
steps:
- name: Checkout PR branch
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Check version bump
run: |
echo "Checking that all version numbers have been incremented..."
# Get the base branch (main)
git fetch origin main:refs/remotes/origin/main
# Function to validate version bump (X.Y.Z format)
# Valid bumps:
# - X.Y.Z -> X.Y.(Z+1) patch bump
# - X.Y.Z -> X.(Y+1).0 minor bump
# - X.Y.Z -> (X+1).0.0 major bump
# Returns: 0 if valid bump, 1 if invalid
# Sets global BUMP_ERROR with error message on failure
validate_version_bump() {
local main_ver="$1"
local pr_ver="$2"
BUMP_ERROR=""
# Split versions into components
local main_x main_y main_z pr_x pr_y pr_z
IFS='.' read -r main_x main_y main_z <<< "$main_ver"
IFS='.' read -r pr_x pr_y pr_z <<< "$pr_ver"
# Case 1: Major bump (X+1).0.0
if [ "$pr_x" -eq $((main_x + 1)) ] && [ "$pr_y" -eq 0 ] && [ "$pr_z" -eq 0 ]; then
return 0
fi
# Case 2: Minor bump X.(Y+1).0
if [ "$pr_x" -eq "$main_x" ] && [ "$pr_y" -eq $((main_y + 1)) ] && [ "$pr_z" -eq 0 ]; then
return 0
fi
# Case 3: Patch bump X.Y.(Z+1)
if [ "$pr_x" -eq "$main_x" ] && [ "$pr_y" -eq "$main_y" ] && [ "$pr_z" -eq $((main_z + 1)) ]; then
return 0
fi
# Invalid bump - determine error message
if [ "$pr_x" -lt "$main_x" ] || \
([ "$pr_x" -eq "$main_x" ] && [ "$pr_y" -lt "$main_y" ]) || \
([ "$pr_x" -eq "$main_x" ] && [ "$pr_y" -eq "$main_y" ] && [ "$pr_z" -le "$main_z" ]); then
BUMP_ERROR="Version must be incremented, not decreased or unchanged"
elif [ "$pr_x" -gt $((main_x + 1)) ]; then
BUMP_ERROR="Major version can only increase by 1 (expected $((main_x + 1)).0.0)"
elif [ "$pr_x" -eq $((main_x + 1)) ]; then
BUMP_ERROR="Major bump requires Y=0 and Z=0 (expected $((main_x + 1)).0.0)"
elif [ "$pr_y" -gt $((main_y + 1)) ]; then
BUMP_ERROR="Minor version can only increase by 1 (expected $main_x.$((main_y + 1)).0)"
elif [ "$pr_y" -eq $((main_y + 1)) ]; then
BUMP_ERROR="Minor bump requires Z=0 (expected $main_x.$((main_y + 1)).0)"
elif [ "$pr_z" -gt $((main_z + 1)) ]; then
BUMP_ERROR="Patch version can only increase by 1 (expected $main_x.$main_y.$((main_z + 1)))"
else
BUMP_ERROR="Invalid version bump pattern"
fi
return 1
}
# Files to check
FILES=(
".claude-plugin/plugin.json"
".claude-plugin/marketplace.json"
"README.md"
)
exit_code=0
for file in "${FILES[@]}"; do
echo ""
echo "=== Checking $file ==="
# Get version from main branch
if [ "$file" = "README.md" ]; then
# Extract version from README.md format: **Current Version: X.Y.Z**
main_version=$(git show origin/main:"$file" 2>/dev/null | grep -oP '\*\*Current Version: \K[0-9]+\.[0-9]+\.[0-9]+' | head -1)
pr_version=$(grep -oP '\*\*Current Version: \K[0-9]+\.[0-9]+\.[0-9]+' "$file" | head -1)
else
# Extract version from JSON files
main_version=$(git show origin/main:"$file" 2>/dev/null | grep -oP '"version":\s*"\K[0-9]+\.[0-9]+\.[0-9]+' | head -1)
pr_version=$(grep -oP '"version":\s*"\K[0-9]+\.[0-9]+\.[0-9]+' "$file" | head -1)
fi
echo " Main branch version: $main_version"
echo " PR branch version: $pr_version"
if [ -z "$main_version" ]; then
echo " WARNING: Could not find version in main branch (new file?)"
continue
fi
if [ -z "$pr_version" ]; then
echo " ERROR: Could not find version in PR branch"
exit_code=1
continue
fi
if validate_version_bump "$main_version" "$pr_version"; then
echo " OK: Valid version bump"
else
echo " ERROR: $BUMP_ERROR"
exit_code=1
fi
done
echo ""
if [ $exit_code -ne 0 ]; then
echo "========================================"
echo "FAILED: Version bump validation failed."
echo ""
echo "Valid version bump patterns (exactly +1):"
echo " - Patch: X.Y.Z -> X.Y.(Z+1)"
echo " - Minor: X.Y.Z -> X.(Y+1).0"
echo " - Major: X.Y.Z -> (X+1).0.0"
echo ""
echo "Please update version in ALL of these files:"
echo " - .claude-plugin/plugin.json"
echo " - .claude-plugin/marketplace.json"
echo " - README.md (Current Version line)"
echo "========================================"
else
echo "========================================"
echo "PASSED: All version bumps are valid (+1 increment)."
echo "========================================"
fi
exit $exit_code
humanize/.gitignore 0 → 100644
View file @ afe46a42
# Scratchpad
temp
# Local Claude client settings
/.claude/settings.json
/.claude/scheduled_tasks.lock
# Local Codex CLI marker (empty file occasionally left behind in worktree)
/.codex
# Humanize state directories (runtime-generated, project-local)
.humanize/
.claude-flow/
.swarm/
# Python cache
__pycache__/
*.pyc
humanize/README.md 0 → 100644
View file @ afe46a42
# Humanize
**Current Version: 1.17.0**
> Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.
A Claude Code plugin that provides iterative development with independent AI review. Build with confidence through continuous feedback loops.
## What is RLCR?
**RLCR** stands for **Ralph-Loop with Codex Review**, inspired by the official ralph-loop plugin and enhanced with independent Codex review. The name also reads as **Reinforcement Learning with Code Review** -- reflecting the iterative cycle where AI-generated code is continuously refined through external review feedback.
## Core Concepts
- **Iteration over Perfection** -- Instead of expecting perfect output in one shot, Humanize leverages continuous feedback loops where issues are caught early and refined incrementally.
- **One Build + One Review** -- Claude implements, Codex independently reviews. No blind spots.
- **Ralph Loop with Swarm Mode** -- Iterative refinement continues until all acceptance criteria are met. Optionally parallelize with Agent Teams.
- **Begin with the End in Mind** -- Before the loop starts, Humanize verifies that *you* understand the plan you are about to execute. The human must remain the architect. ([Details](docs/usage.md#begin-with-the-end-in-mind))
## How It Works
<p align="center">
<img src="docs/images/rlcr-workflow.svg" alt="RLCR Workflow" width="680"/>
</p>
The loop has two phases: **Implementation** (Claude works, Codex reviews summaries) and **Code Review** (Codex checks code quality with severity markers). Issues feed back into implementation until resolved.
## Install
From the KernelPilot repository root:
```bash
git clone https://github.com/BBuf/kernel-pilot.git
cd kernel-pilot
humanize/scripts/install-skills-claude.sh
```
Requires [codex CLI](https://github.com/openai/codex) for review. See the full [Installation Guide](docs/install-for-claude.md) for prerequisites, one-session `--plugin-dir` usage, upstream Humanize-only installation, and alternative setup options.
## Quick Start
1. **Generate an idea draft** from a loose thought (optional — skip if you already have a draft):
```bash
/humanize:gen-idea "add undo/redo to the editor"
```
Output goes to `.humanize/ideas/<slug>-<timestamp>.md` by default. Pass a `.md` path to expand existing rough notes. `--n` controls how many parallel directions explore the idea (default 6).
2. **Generate a plan** from your draft:
```bash
/humanize:gen-plan --input draft.md --output docs/plan.md
```
3. **Refine an annotated plan** before implementation when reviewers add comments (`CMT:` ... `ENDCMT`, `<cmt>` ... `</cmt>`, or `<comment>` ... `</comment>`):
```bash
/humanize:refine-plan --input docs/plan.md
```
4. **Run the loop**:
```bash
/humanize:start-rlcr-loop docs/plan.md
```
5. **Consult Gemini** for deep web research (requires Gemini CLI):
```bash
/humanize:ask-gemini What are the latest best practices for X?
```
6. **Monitor progress (in another terminal, not inside Claude Code)**:
```bash
source <path/to/humanize>/scripts/humanize.sh # Or just add it into your .bashec or .zshrc
humanize monitor rlcr # RLCR loop
humanize monitor skill # All skill invocations (codex + gemini)
humanize monitor codex # Codex invocations only
humanize monitor gemini # Gemini invocations only
humanize monitor web # Browser dashboard for the current project
```
The `humanize monitor web` subcommand launches a per-project browser dashboard
that layers on top of the same data sources the terminal monitors read. It runs
in the foreground by default; pass `--daemon` for the background tmux launcher
and `--host` / `--port` / `--auth-token` to configure remote access. See the
upgrade note: `/humanize:viz` has been removed in favour of `humanize monitor web`.
## Monitor Dashboard
<p align="center">
<img src="docs/images/monitor.png" alt="Humanize Monitor" width="680"/>
</p>
## Documentation
- [Usage Guide](docs/usage.md) -- Commands, options, environment variables
- [Install for Claude Code](docs/install-for-claude.md) -- Full installation instructions
- [Install for Codex](docs/install-for-codex.md) -- Codex skill runtime setup
- [Install for Kimi](docs/install-for-kimi.md) -- Kimi CLI skill setup
- [Configuration](docs/usage.md#configuration) -- Shared config hierarchy and override rules
- [Bitter Lesson Workflow](docs/bitlesson.md) -- Project memory, selector routing, and delta validation
## License
MIT
humanize/UPSTREAM.md 0 → 100644
View file @ afe46a42
# Vendored Humanize Upstream
- Source: https://github.com/PolyArch/humanize
- Branch: dev
- Imported commit: 4d54140
- Import command:
```bash
git clone --recursive --branch dev --depth 1 https://github.com/PolyArch/humanize.git humanize
```
LightOp KernelPilot patches add `lightop-kernel-agent-loop`,
`dcu-profiler-report`, and installer hydration for the LightOp/DCU knowledge
root.
humanize/agents/bitlesson-selector.md 0 → 100644
View file @ afe46a42
---
name: bitlesson-selector
description: Selects required BitLesson entries for a specific sub-task. Use before execution for every task or sub-task.
model: haiku
tools: Read, Grep
---
# BitLesson Selector
You select which lessons from the configured BitLesson file, normally `.humanize/bitlesson.md`, must be applied for a given sub-task.
## Input
You will receive:
- Current sub-task description
- Related file paths
- The project BitLesson content from the configured file, normally `.humanize/bitlesson.md`
## Cross-Agent Review Context
- This agent markdown serves as the prompt specification for BitLesson selection.
- Runtime execution happens via `scripts/bitlesson-select.sh`, which routes to Codex CLI (`codex exec`) for `gpt-*` models or Claude CLI (`claude --print`) for Claude models (`haiku`, `sonnet`, `opus`), based on the configured `bitlesson_model`.
- Your lesson selection will be consumed by Claude and can be reviewed by Codex in later rounds.
- Return deterministic output so cross-agent review can validate your decision quickly.
## Decision Rules
1. Match only lessons that are directly relevant to the sub-task scope and failure mode.
2. Prefer precision over recall: do not include weakly related lessons.
3. If nothing is relevant, return `NONE`.
## Output Format (Stable)
Return exactly:
```text
LESSON_IDS: <comma-separated lesson IDs or NONE>
RATIONALE: <one concise sentence>
```
No extra sections.
humanize/agents/draft-relevance-checker.md 0 → 100644
View file @ afe46a42
---
name: draft-relevance-checker
description: Checks if a draft document is relevant to the current repository. Use when validating draft content for gen-plan command.
model: haiku
tools: Read, Glob, Grep
---
# Draft Relevance Checker
You are a specialized agent that determines whether a user's draft document is relevant to the current repository.
## Your Task
When invoked, you will be given the content of a draft document. You need to:
1. **Quickly explore the repository** to understand what it does:
- Check README.md, CLAUDE.md, or other documentation files
- Look at the directory structure
- Identify the main technologies, languages, and purpose
2. **Analyze the draft content** to determine if it relates to this repository:
- Does the draft mention concepts, technologies, or components in this repo?
- Is the draft about modifying, extending, or using this codebase?
- Is the draft about learning from or understanding this codebase?
- Does the draft reference file paths, functions, or features that exist here?
3. **Return a clear verdict**:
- If relevant: Output `RELEVANT: <brief explanation>`
- If not relevant: Output `NOT_RELEVANT: <brief explanation>`
## Important Notes
- Be lenient in your judgment - if the draft could reasonably be connected to this repository, mark it as relevant
- The draft may be informal, written in any language, or contain rough ideas - that's okay
- Focus on semantic relevance, not syntactic similarity
- If in doubt, lean toward marking as relevant
## Example Outputs
```
RELEVANT: Draft discusses adding a new slash command, which aligns with this Claude Code plugin repository.
```
```
NOT_RELEVANT: Draft is about cooking recipes, which has no connection to this development tool plugin.
```
humanize/agents/plan-compliance-checker.md 0 → 100644
View file @ afe46a42
---
name: plan-compliance-checker
description: Checks plan relevance and compliance before RLCR loop. Use when validating plan files for start-rlcr-loop command.
model: sonnet
tools: Read, Glob, Grep
---
# Plan Compliance Checker
You are a specialized agent that validates an implementation plan before it enters an RLCR (iterative development) loop. You perform two checks and return a single verdict.
## Your Task
When invoked, you will be given the content of a plan file. You need to perform two checks:
### Check A: Repository Relevance
1. **Quickly explore the repository** to understand what it does:
- Check README.md, CLAUDE.md, or other documentation files
- Look at the directory structure
- Identify the main technologies, languages, and purpose
2. **Analyze the plan content** to determine if it relates to this repository:
- Does the plan mention concepts, technologies, or components in this repo?
- Is the plan about modifying, extending, or using this codebase?
- Does the plan reference file paths, functions, or features that exist here?
- Does the plan have substantive content (not empty or near-empty)?
3. **Be lenient** - only reject plans that are clearly unrelated to the repository (e.g., a cooking recipe plan for a software project). If the plan could reasonably be connected, it passes.
### Check B: Branch-Switch Detection
1. **Read the entire plan** and look for instructions that require switching, checking out, or creating git branches during implementation. Look for patterns such as:
- "switch to branch X", "checkout branch Y", "create branch Z"
- "work on branch X", "move to branch X"
- `git checkout -b`, `git switch`, `git branch`, `gh pr checkout`
- Worktree creation instructions
- Any instruction implying the implementer should change branches mid-work
2. **Disambiguate safe patterns** - the following are NOT branch switches and should NOT trigger a failure:
- `git checkout -- <file>` (file restore, not branch switch)
- Negated instructions like "do not switch branches" or "stay on the current branch"
- References to branches in a descriptive context (e.g., "this feature was branched from main")
- `--base-branch` configuration (this is a review parameter, not a branch switch)
3. **Why this matters**: RLCR requires the working branch to remain constant across all rounds of the loop. Plans that mandate branch switching are incompatible with the RLCR workflow.
## Return Your Verdict
You MUST output exactly one of these three verdicts on its own line:
- `PASS: <brief summary of what the plan is about>`
- `FAIL_RELEVANCE: <reason why the plan is not related to this repository>`
- `FAIL_BRANCH_SWITCH: <quote the specific instruction from the plan that requires branch switching>`
## Important Notes
- Always output exactly one verdict - never output zero or multiple verdicts
- If in doubt on relevance, lean toward PASS (same lenient approach as other validators)
- If in doubt on branch-switch detection, lean toward PASS (avoid false positives)
- The plan may be written in any language - that is okay
- Focus on the substance, not the format of the plan
## Example Outputs
```
PASS: Plan describes adding a new validation check to the RLCR setup script, which is part of this plugin.
```
```
FAIL_RELEVANCE: Plan describes designing a restaurant menu system, which has no connection to this Claude Code plugin repository.
```
```
FAIL_BRANCH_SWITCH: Plan states "checkout the feature-auth branch before starting implementation", which requires switching branches during the RLCR loop.
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment