Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/install-for-claude.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,7 @@ After installing, you should see Humanize commands available:

```
/humanize:start-rlcr-loop
/humanize:gen-idea
/humanize:gen-plan
/humanize:refine-plan
/humanize:ask-codex
Expand Down
4 changes: 3 additions & 1 deletion docs/install-for-codex.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ Or use the unified installer directly:
```

This will:
- Sync `humanize`, `humanize-gen-plan`, `humanize-refine-plan`, and `humanize-rlcr` into `${CODEX_HOME:-~/.codex}/skills`
- Sync `humanize`, `humanize-gen-idea`, `humanize-gen-plan`, `humanize-refine-plan`, and `humanize-rlcr` into `${CODEX_HOME:-~/.codex}/skills`
- Copy runtime dependencies into `${CODEX_HOME:-~/.codex}/skills/humanize`
- Install/update native Humanize Stop hooks in `${CODEX_HOME:-~/.codex}/hooks.json`
- Enable the native `hooks` feature in `${CODEX_HOME:-~/.codex}/config.toml` when `codex` is available
Expand All @@ -41,6 +41,7 @@ ls -la "${CODEX_HOME:-$HOME/.codex}/skills"

Expected directories:
- `humanize`
- `humanize-gen-idea`
- `humanize-gen-plan`
- `humanize-refine-plan`
- `humanize-rlcr`
Expand All @@ -55,6 +56,7 @@ Runtime dependencies in `humanize/`:

Installed files/directories:
- `${CODEX_HOME:-~/.codex}/skills/humanize/SKILL.md`
- `${CODEX_HOME:-~/.codex}/skills/humanize-gen-idea/SKILL.md`
- `${CODEX_HOME:-~/.codex}/skills/humanize-gen-plan/SKILL.md`
- `${CODEX_HOME:-~/.codex}/skills/humanize-refine-plan/SKILL.md`
- `${CODEX_HOME:-~/.codex}/skills/humanize-rlcr/SKILL.md`
Expand Down
30 changes: 22 additions & 8 deletions docs/install-for-kimi.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@ This guide explains how to install the Humanize skills for [Kimi Code CLI](https

## Overview

Humanize provides four Agent Skills for kimi:
Humanize provides five Agent Skills for kimi:

| Skill | Type | Purpose |
|-------|------|---------|
| `humanize` | Standard | General guidance for all workflows |
| `humanize-gen-idea` | Flow | Generate a repo-grounded idea draft from loose input |
| `humanize-gen-plan` | Flow | Generate structured plan from draft |
| `humanize-refine-plan` | Flow | Refine annotated plan with CMT blocks |
| `humanize-rlcr` | Flow | Iterative development with Codex review |
Expand All @@ -24,7 +25,7 @@ From the Humanize repo root, run:
```

This command will:
- Sync `humanize`, `humanize-gen-plan`, `humanize-refine-plan`, and `humanize-rlcr` into `~/.config/agents/skills`
- Sync `humanize`, `humanize-gen-idea`, `humanize-gen-plan`, `humanize-refine-plan`, and `humanize-rlcr` into `~/.config/agents/skills`
- Copy runtime dependencies into `~/.config/agents/skills/humanize`

Common installer script (all targets):
Expand All @@ -47,8 +48,9 @@ cd /path/to/humanize
# Create the skills directory if it doesn't exist
mkdir -p ~/.config/agents/skills

# Copy all four skills
# Copy all five skills
cp -r skills/humanize ~/.config/agents/skills/
cp -r skills/humanize-gen-idea ~/.config/agents/skills/
cp -r skills/humanize-gen-plan ~/.config/agents/skills/
cp -r skills/humanize-refine-plan ~/.config/agents/skills/
cp -r skills/humanize-rlcr ~/.config/agents/skills/
Expand All @@ -63,14 +65,14 @@ cp -r config ~/.config/agents/skills/humanize/
cp -r agents ~/.config/agents/skills/humanize/

# Hydrate runtime root placeholders inside SKILL.md files
for skill in humanize humanize-gen-plan humanize-refine-plan humanize-rlcr; do
for skill in humanize humanize-gen-idea humanize-gen-plan humanize-refine-plan humanize-rlcr; do
sed -i.bak "s|{{HUMANIZE_RUNTIME_ROOT}}|$HOME/.config/agents/skills/humanize|g" \
"$HOME/.config/agents/skills/$skill/SKILL.md"
done

# Strip user-invocable flag from SKILL.md files for runtime visibility
# (This matches the behavior of scripts/install-skill.sh)
for skill in humanize humanize-gen-plan humanize-refine-plan humanize-rlcr; do
for skill in humanize humanize-gen-idea humanize-gen-plan humanize-refine-plan humanize-rlcr; do
awk '
Comment thread
zevorn marked this conversation as resolved.
BEGIN { in_fm = 0; fm_done = 0 }
/^---[[:space:]]*$/ {
Expand Down Expand Up @@ -98,6 +100,7 @@ ls -la ~/.config/agents/skills/

# Should show:
# humanize/
# humanize-gen-idea/
# humanize-gen-plan/
# humanize-refine-plan/
# humanize-rlcr/
Expand Down Expand Up @@ -129,7 +132,17 @@ Look for the "Skills" section in the help output.

### Use the skills

#### 1. Generate plan from draft
#### 1. Generate an idea draft

```bash
# Start the flow with inline text
/flow:humanize-gen-idea "add undo/redo to the editor"

# Or load as standard skill
/skill:humanize-gen-idea
```

#### 2. Generate plan from draft

```bash
# Start the flow (will ask for input/output paths)
Expand All @@ -139,7 +152,7 @@ Look for the "Skills" section in the help output.
/skill:humanize-gen-plan
```

#### 2. Start RLCR development loop
#### 3. Start RLCR development loop

```bash
# Start with plan file
Expand All @@ -155,7 +168,7 @@ Look for the "Skills" section in the help output.
/skill:humanize-rlcr
```

#### 3. Get general guidance
#### 4. Get general guidance

```bash
/skill:humanize
Expand Down Expand Up @@ -199,6 +212,7 @@ To remove the skills:

```bash
rm -rf ~/.config/agents/skills/humanize
rm -rf ~/.config/agents/skills/humanize-gen-idea
rm -rf ~/.config/agents/skills/humanize-gen-plan
rm -rf ~/.config/agents/skills/humanize-refine-plan
rm -rf ~/.config/agents/skills/humanize-rlcr
Expand Down
4 changes: 3 additions & 1 deletion hooks/lib/loop-common.sh
Original file line number Diff line number Diff line change
Expand Up @@ -233,7 +233,9 @@ DEFAULT_CODEX_EFFORT="${DEFAULT_CODEX_EFFORT:-${_cfg_codex_effort:-high}}"
# Precedence: pre-set by caller (e.g. --agent-teams flag) > config value > hardcoded fallback (false)
_cfg_agent_teams="$(get_config_value "$_LOOP_COMMON_CONFIG" "agent_teams" 2>/dev/null || true)"
DEFAULT_AGENT_TEAMS="${DEFAULT_AGENT_TEAMS:-${_cfg_agent_teams:-false}}"
unset _cfg_codex_model _cfg_codex_effort _cfg_agent_teams
_cfg_provider_mode="$(get_config_value "$_LOOP_COMMON_CONFIG" "provider_mode" 2>/dev/null || true)"
DEFAULT_PROVIDER_MODE="${DEFAULT_PROVIDER_MODE:-$_cfg_provider_mode}"
unset _cfg_codex_model _cfg_codex_effort _cfg_agent_teams _cfg_provider_mode

unset _LOOP_COMMON_PROJECT_ROOT _LOOP_COMMON_CONFIG

Expand Down
14 changes: 12 additions & 2 deletions hooks/lib/methodology-analysis.sh
Original file line number Diff line number Diff line change
Expand Up @@ -78,8 +78,13 @@ Please analyze the development records in $LOOP_DIR and provide methodology impr
Write your analysis to $LOOP_DIR/methodology-analysis-report.md.
When done, write a completion note to $LOOP_DIR/methodology-analysis-done.md."

local methodology_template="claude/methodology-analysis-prompt.md"
if [[ "${PROVIDER_MODE:-}" == "codex-only" ]]; then
methodology_template="codex/methodology-analysis-prompt.md"
fi

local analysis_prompt
analysis_prompt=$(load_and_render_safe "$TEMPLATE_DIR" "claude/methodology-analysis-prompt.md" "$fallback" \
analysis_prompt=$(load_and_render_safe "$TEMPLATE_DIR" "$methodology_template" "$fallback" \
"LOOP_DIR=$LOOP_DIR" \
"EXIT_REASON=$exit_reason" \
"EXIT_REASON_DESCRIPTION=$exit_reason_description" \
Expand Down Expand Up @@ -183,12 +188,17 @@ complete_methodology_analysis() {
block_methodology_analysis_incomplete() {
local done_file="$LOOP_DIR/methodology-analysis-done.md"

local action_item="Spawn an Opus agent to analyze the development records"
if [[ "${PROVIDER_MODE:-}" == "codex-only" ]]; then
action_item="Run a Codex 5.5 methodology analysis, using a sub-agent if the current runtime supports it"
fi

local reason="# Methodology Analysis Incomplete

Please complete the methodology analysis before exiting.

You need to:
1. Spawn an Opus agent to analyze the development records
1. $action_item
2. Review the analysis report
3. Optionally help the user file a GitHub issue
4. Write a completion note to: $done_file
Expand Down
9 changes: 5 additions & 4 deletions hooks/loop-codex-stop-hook.sh
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ CODEX_TIMEOUT="${STATE_CODEX_TIMEOUT:-${CODEX_TIMEOUT:-$DEFAULT_CODEX_TIMEOUT}}"
ASK_CODEX_QUESTION="${STATE_ASK_CODEX_QUESTION:-false}"
AGENT_TEAMS="${STATE_AGENT_TEAMS:-false}"
PRIVACY_MODE="${STATE_PRIVACY_MODE:-true}"
PROVIDER_MODE="${DEFAULT_PROVIDER_MODE:-}"
BITLESSON_REQUIRED="false"
if [[ -n "$RAW_BITLESSON_REQUIRED" ]]; then
BITLESSON_REQUIRED=$(echo "$RAW_BITLESSON_REQUIRED" | sed 's/^bitlesson_required:[[:space:]]*//' | tr -d ' "')
Expand Down Expand Up @@ -1342,7 +1343,7 @@ Since the code review was skipped, please manually verify your changes before fi
3. Check for common code quality issues

## Simplification (Optional)
If time permits, use the \`code-simplifier:code-simplifier\` agent via the Task tool to simplify and refactor your code. Focus more on changes between branch from {{BASE_BRANCH}} to {{START_BRANCH}}.
If time permits, use the Codex \`code-simplifier:code-simplifier\` agent if it is available in the current runtime. If that agent is not available, perform the same simplification pass directly. Focus more on changes between branch from {{BASE_BRANCH}} to {{START_BRANCH}}.

## Constraints
- Must NOT change existing functionality
Expand All @@ -1355,7 +1356,7 @@ If time permits, use the \`code-simplifier:code-simplifier\` agent via the Task
2. Commit your changes
3. Write your finalize summary to: {{FINALIZE_SUMMARY_FILE}}"

finalize_prompt=$(load_and_render_safe "$TEMPLATE_DIR" "claude/finalize-phase-skipped-prompt.md" "$fallback" \
finalize_prompt=$(load_and_render_safe "$TEMPLATE_DIR" "codex/finalize-phase-skipped-prompt.md" "$fallback" \
"FINALIZE_SUMMARY_FILE=$finalize_summary_file" \
"PLAN_FILE=$PLAN_FILE" \
"GOAL_TRACKER_FILE=$GOAL_TRACKER_FILE" \
Expand All @@ -1367,7 +1368,7 @@ If time permits, use the \`code-simplifier:code-simplifier\` agent via the Task

Codex review has passed. The implementation is complete.

You are now in the **Finalize Phase**. Use the \`code-simplifier:code-simplifier\` agent via the Task tool to simplify and refactor your code.
You are now in the **Finalize Phase**. Use the Codex \`code-simplifier:code-simplifier\` agent if it is available in the current runtime. If that agent is not available, perform the same simplification pass directly.

## Constraints
- Must NOT change existing functionality
Expand All @@ -1383,7 +1384,7 @@ Focus on the code changes made during this RLCR session. Focus more on changes b
2. Commit your changes
3. Write your finalize summary to: {{FINALIZE_SUMMARY_FILE}}"

finalize_prompt=$(load_and_render_safe "$TEMPLATE_DIR" "claude/finalize-phase-prompt.md" "$fallback" \
finalize_prompt=$(load_and_render_safe "$TEMPLATE_DIR" "codex/finalize-phase-prompt.md" "$fallback" \
"FINALIZE_SUMMARY_FILE=$finalize_summary_file" \
"PLAN_FILE=$PLAN_FILE" \
"GOAL_TRACKER_FILE=$GOAL_TRACKER_FILE" \
Expand Down
47 changes: 47 additions & 0 deletions prompt-template/codex/finalize-phase-prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
# Finalize Phase

Codex review has passed. The implementation is complete and all acceptance criteria have been met.

You are now in the **Finalize Phase**. This is the opportunity to simplify and refactor the code before final completion.

## Your Task

Use the Codex `code-simplifier:code-simplifier` agent if it is available in the current runtime. If that agent is not available, perform the same simplification pass directly in this session.

## Constraints

These constraints are **non-negotiable**:

1. **Must NOT change existing functionality** - All features must work exactly as before
2. **Must NOT fail existing tests** - Run tests to verify nothing is broken
3. **Must NOT introduce new bugs** - Be careful with refactoring
4. **Only perform functionality-equivalent changes** - Simplification and cleanup only

## Focus Areas

Focus on:
- Code that was recently added or modified
- Changes between branch from `{{BASE_BRANCH}}` to `{{START_BRANCH}}`
- Removing unnecessary complexity
- Improving readability and maintainability
- Consolidating duplicate code
- Simplifying control flow where possible
- Removing dead code or unused variables

## Reference Files

- Original plan: @{{PLAN_FILE}}
- Goal tracker: @{{GOAL_TRACKER_FILE}}

## Before Exiting

1. Complete all `[mainline]` and `[blocking]` tasks
2. `[queued]` tasks may remain only if they are documented as non-blocking follow-up work
3. Commit your changes with a descriptive message
4. Write your finalize summary to: **{{FINALIZE_SUMMARY_FILE}}**

Your summary should include:
- What simplifications were made
- Files modified during the Finalize Phase
- Confirmation that tests still pass
- Any notes about the refactoring decisions
46 changes: 46 additions & 0 deletions prompt-template/codex/finalize-phase-skipped-prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Finalize Phase (Review Skipped)

**Warning**: Code review was skipped due to: {{REVIEW_SKIP_REASON}}

The implementation could not be fully validated. You are now in the **Finalize Phase**.

## Important Notice

Since the code review was skipped, manually verify your changes before finalizing:

1. Review your code changes for any obvious issues
2. Run any available tests to verify correctness
3. Check for common code quality issues

## Simplification (Optional)

If time permits, use the Codex `code-simplifier:code-simplifier` agent if it is available in the current runtime. If that agent is not available, perform the same simplification pass directly in this session.

Focus on changes between branch from `{{BASE_BRANCH}}` to `{{START_BRANCH}}`.

## Constraints

These constraints are **non-negotiable**:

1. **Must NOT change existing functionality** - All features must work exactly as before
2. **Must NOT fail existing tests** - Run tests to verify nothing is broken
3. **Must NOT introduce new bugs** - Be careful with refactoring
4. **Only perform functionality-equivalent changes** - Simplification and cleanup only

## Reference Files

- Original plan: @{{PLAN_FILE}}
- Goal tracker: @{{GOAL_TRACKER_FILE}}

## Before Exiting

1. Complete all `[mainline]` and `[blocking]` tasks
2. `[queued]` tasks may remain only if they are documented as non-blocking follow-up work
3. Commit your changes with a descriptive message
4. Write your finalize summary to: **{{FINALIZE_SUMMARY_FILE}}**

Your summary should include:
- What work was done
- Files modified
- Confirmation that tests still pass, if possible
- Any notes about manual verification performed
73 changes: 73 additions & 0 deletions prompt-template/codex/methodology-analysis-prompt.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Methodology Analysis Phase

The RLCR loop has reached its exit point.

**Exit reason**: {{EXIT_REASON}} - {{EXIT_REASON_DESCRIPTION}}
**Rounds completed**: {{CURRENT_ROUND}} of {{MAX_ITERATIONS}}

Before the loop fully exits, perform a methodology improvement analysis. This analysis helps improve the Humanize development methodology itself -- it is NOT about the project you just worked on.

## Instructions

### 1. Run a Sanitized Codex 5.5 Analysis

Use a Codex analysis sub-agent running `gpt-5.5` when the current runtime supports explicit model selection. If explicit model selection or sub-agent execution is unavailable, perform the analysis directly in this Codex session and note that fallback in the report.

Analysis task: Read the development records in `{{LOOP_DIR}}`:
- All files matching `round-*-summary.md`
- All files matching `round-*-review-result.md`

Analyze these records from a **pure methodology perspective** and write your findings to `{{LOOP_DIR}}/methodology-analysis-report.md`.

**CRITICAL SANITIZATION RULES** - The report MUST NOT contain:
- File paths, directory paths, or module paths
- Function names, variable names, class names, or method names
- Branch names, commit hashes, or git identifiers
- Business domain terms, product names, or feature names
- Code snippets or code fragments of any kind
- Raw error messages or stack traces
- Project-specific URLs or endpoints
- Any information that could identify the specific project

**Focus areas for analysis**:
- Iteration efficiency: Were rounds productive or did they repeat similar work?
- Feedback loop quality: Did reviewer feedback lead to meaningful improvements?
- Stagnation patterns: Were there signs of going in circles?
- Review effectiveness: Did reviews catch real issues or create false positives?
- Plan-to-execution alignment: Did execution follow the plan or drift?
- Round count vs. progress ratio: Was the number of rounds proportional to progress?
- Communication clarity: Were summaries and reviews clear and actionable?

**Output format**: Write a structured report with methodology improvement suggestions. Each suggestion should describe a general pattern observed and a concrete improvement to the RLCR methodology. If no improvements are found, write a brief note saying the methodology worked well for this session.

### 2. Read the Analysis Report

After the analysis completes, read `{{LOOP_DIR}}/methodology-analysis-report.md`. ALL subsequent user-facing content MUST be derived solely from this report -- do NOT reference raw development records directly.

### 3. Handle Results

**If no improvements found**: Briefly inform the user that the methodology analysis found no significant improvement suggestions. Then write a completion note to `{{LOOP_DIR}}/methodology-analysis-done.md` and exit.

**If improvements found**:

a) Report to the user:
- Brief summary of the exit reason ({{EXIT_REASON}}: {{EXIT_REASON_DESCRIPTION}})
- Methodology improvement suggestions from the report

b) Ask the user directly whether they would like to help improve Humanize by opening a GitHub issue with these suggestions. Emphasize:
- This is completely voluntary
- The content is fully sanitized with no project-specific information
- It helps improve the methodology for everyone

c) **If user declines**: Write a completion marker to `{{LOOP_DIR}}/methodology-analysis-done.md` and exit.

d) **If user agrees**:
- Draft a GitHub issue title and body from the analysis report
- Show the draft to the user for review and confirmation
- If confirmed: run `gh issue create --repo PolyArch/humanize --title "..." --body "..."`
- If `gh` is not available, provide the title and body so the user can create the issue manually
- Write a completion marker to `{{LOOP_DIR}}/methodology-analysis-done.md` and exit

### 4. Completion Marker

You MUST write meaningful content to `{{LOOP_DIR}}/methodology-analysis-done.md` before exiting. This file signals that the analysis phase is complete. A brief summary of what was done, such as "Analysis complete, no suggestions" or "Analysis complete, issue filed", is sufficient.
Loading
Loading