Skip to content

GitLab

Commit f6fe8355 authored by whlwhlwhl's avatar whlwhlwhl
Browse files

Initial LightOp KernelPilot skill pack

parents
Pipeline #3628 canceled with stages
Hide whitespace changes
Inline Side-by-side
Showing with 927 additions and 0 deletions
.claude-plugin/marketplace.json 0 → 100644
View file @ f6fe8355
{
"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 @ f6fe8355
__pycache__/
.pytest_cache/
.kernel-knowledge/
knowledge/external-repos/
.humanize/
.humanize-*/
*.py[cod]
*.egg-info/
README.md 0 → 100644
View file @ f6fe8355
<div align="center">
# LightOp KernelPilot
**A Humanize-powered skill pack for adding and optimizing LightOp fused
operators on DCU/ROCm.**
</div>
LightOp KernelPilot adapts the original KernelPilot idea to the LightOp DCU
operator library. It keeps the useful parts of the autonomous loop: explicit
operator semantics, correctness references, workload distributions, benchmark
evidence, profiling digests, ledgers, and review-gated iteration. It removes
the NVIDIA-first assumptions around Nsight Compute, CUTLASS/CuTe, PTX/SASS,
Blackwell/Hopper, TMA, WGMMA, and tcgen05.
## Skills
| Skill | Role |
| --- | --- |
| [`lightop-kernel-agent-loop`](humanize/skills/humanize-kernel-agent-loop/) | Adds or optimizes LightOp operators by recovering `K/R/W`, inspecting LightOp wrappers/bindings/kernels/tests/configs, implementing HIP/ROCm changes, building, testing, benchmarking, profiling, tuning, and starting Humanize RLCR. |
| [`lightop-kernel-knowledge`](knowledge/SKILL.md) | Gathers evidence from local LightOp source first, then ROCm/DCU upstream and official docs, then the bundled CUDA PR corpus only as cross-platform inspiration. |
| [`dcu-profiler-report`](humanize/skills/ncu-report/) | Turns `hipprof`, ROCm/DTK profiler output, benchmark logs, and optional AMDGPU ISA evidence into a reproducible digest with exactly one next LightOp edit. |
The on-disk folder names `humanize-kernel-agent-loop` and `ncu-report` are
kept for compatibility with the upstream Humanize installer, but the skill
frontmatter exposes the LightOp/DCU names above.
## Request Shape
A useful request names the operator, correctness reference, workload
distribution, execution environment, target DCU/gfx arch, baseline, benchmark
method, and success threshold:
```text
[$lightop-kernel-agent-loop] Add a LightOp fused rmsnorm + rope + fp8 kv-cache
store operator for gfx936. Use PyTorch/native LightOp composition as the
correctness reference, cover batch/token/head_dim shapes from Qwen decode, and
run in Docker container lightop-dtk with /workspace/lightop as the repo path.
Beat the existing unfused path by 15% p50 latency.
```
For optimization:
```text
[$lightop-kernel-agent-loop] Optimize lightop.moe_gemm_w8a8 on gfx938 for the
DeepSeek EP8 decode workload. Keep the public Python API unchanged, compare
against the current LightOp baseline, and use hipprof evidence when benchmark
results plateau.
```
## LightOp Integration
The loop operates on a LightOp checkout containing:
```text
setup.py
setup_torch29.py
lightop/__init__.py
lightop/csrc/export.cpp
lightop/csrc/<family>/
lightop/config*.py
test/
```
When adding an operator, the agent normally touches:
- `lightop/csrc/<family>/` for HIP/C++ implementation.
- `lightop/csrc/export.cpp` for `m.def(...)` binding.
- `lightop/<op>.py` for the Python wrapper.
- `lightop/__init__.py` for public API exports.
- `setup.py` and `setup_torch29.py` only when a new `csrc` family needs glob
coverage.
- `test/test_<op>.py` and benchmark scripts for correctness/performance.
- `lightop/config*.py` when shape/gfx-aware dispatch is needed.
## DCU Profiling
`dcu-profiler-report` uses the SourceFind DCU performance analysis guide as
the official first-pass reference:
```text
https://developer.sourcefind.cn/gitbook//dcu_developer/DeveloperGuide/dcu_programming/DCU_programming_chapter3_7.html
```
Default first-pass profile:
```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
```
Deeper profiling can use `rocprof`, `rocprofv3`, `rocprof-compute`, or
AMDGPU ISA/code-object inspection when `hipprof` and benchmark logs are not
enough.
## Build And Test Defaults
Run build, install, tests, benchmark, and profiling in one consistent
environment. If Docker is the target environment, prefer repeatable
non-interactive commands:
```bash
docker exec <container> bash -lc 'cd /workspace/lightop && <command>'
```
From the LightOp root inside that environment:
```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
PYTORCH_ROCM_ARCH='gfx928;gfx936;gfx938' python setup.py install
python - <<'PY'
import torch, lightop
print("lightop:", getattr(lightop, "__file__", "unknown"))
print("gcn:", torch.cuda.get_device_properties(0).gcnArchName)
PY
```
Run the narrowest targeted test first:
```bash
cd test
python test_<op>.py
```
Benchmark scripts must use warmup and explicit `torch.cuda.synchronize()` or
HIP synchronization around timed regions before claiming speedups. A change is
not done at build success: it needs install, import smoke, correctness,
benchmark comparison against the baseline, and profiler evidence when the
result is close to the threshold or surprising.
## Install
Install the Humanize skill pack from this checkout:
```bash
cd /path/to/kernel-pilot
./humanize/scripts/install-skill.sh --target codex --kernelpilot-root "$PWD"
```
Claude Code users can use:
```bash
./humanize/scripts/install-skills-claude.sh --kernelpilot-root "$PWD"
```
After installation, the relevant skills are:
```text
lightop-kernel-agent-loop
lightop-kernel-knowledge
dcu-profiler-report
```
## Evidence Rules
- Local LightOp source, tests, configs, and benchmarks are the primary
evidence.
- ROCm/DCU official docs and upstream source are the next evidence tier.
- The bundled CUDA PR corpus is allowed only as cross-platform inspiration
unless the idea is translated and validated on DCU.
- Any copied or adapted external source must record source path/URL, commit or
version, license/notice, and the optimization delta.
- A profile digest must end with exactly one next edit or explain why profiling
is not actionable.
humanize/.claude-plugin/marketplace.json 0 → 100644
View file @ f6fe8355
{
"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 @ f6fe8355
{
"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 @ f6fe8355
# 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 @ f6fe8355
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 @ f6fe8355
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 @ f6fe8355
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 @ f6fe8355
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 @ f6fe8355
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 @ f6fe8355
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 @ f6fe8355
# 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 @ f6fe8355
# 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 @ f6fe8355
# 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 @ f6fe8355
---
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 @ f6fe8355
---
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 @ f6fe8355
---
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