humanize

Humanize - Iterative Development with AI Review

Humanize creates a feedback loop where AI implements your plan while another AI independently reviews the work, ensuring quality through continuous refinement.

Runtime Root

The installer hydrates this skill with an absolute runtime root path:

{{HUMANIZE_RUNTIME_ROOT}}

All command examples below use {{HUMANIZE_RUNTIME_ROOT}}.

Core Philosophy

Iteration over Perfection: Instead of expecting perfect output in one shot, Humanize leverages an iterative feedback loop where:

• AI implements your plan
• Another AI independently reviews progress
• Issues are caught and addressed early
• Work continues until all acceptance criteria are met

Available Workflows

1. RLCR Loop - Iterative Development with Review

The RLCR (Ralph-Loop with Codex Review) loop has two phases:

Phase 1: Implementation

• AI works on the implementation plan
• AI writes a summary of work completed
• Codex reviews the summary for completeness and correctness
• If issues found → feedback loop continues
• If Codex outputs "COMPLETE" → enters Review Phase

Phase 2: Code Review

• codex review --base <branch> checks code quality
• Issues marked with [P0-9] severity markers
• If issues found → AI fixes them and continues
• If no issues → loop completes with Finalize Phase
• On Codex CLI 0.114.0+ with codex_hooks enabled, Humanize installs a native Stop hook so exit gating runs automatically

2. Generate Plan - Structured Plan from Draft

Transforms a rough draft document into a structured implementation plan with:

• Clear goal description
• Acceptance criteria in AC-X format with TDD-style positive/negative tests
• Path boundaries (upper/lower bounds, allowed choices)
• Feasibility hints and conceptual approach
• Dependencies and milestone sequencing

Commands Reference

Start RLCR Loop

# With a plan file
"{{HUMANIZE_RUNTIME_ROOT}}/scripts/setup-rlcr-loop.sh" path/to/plan.md

# Or without plan (review-only mode)
"{{HUMANIZE_RUNTIME_ROOT}}/scripts/setup-rlcr-loop.sh" --skip-impl

After each round, write the required summary and stop/exit normally. Humanize's native Codex Stop hook handles review gating automatically.

Common Options:

• --max N - Maximum iterations before auto-stop (default: 84)
• --codex-model MODEL:EFFORT - Codex model and reasoning effort for codex exec (default: gpt-5.5:high)
• Review phase codex review uses gpt-5.5:high
• --codex-timeout SECONDS - Timeout for each Codex review (default: 5400)
• --base-branch BRANCH - Base branch for code review (auto-detects if not specified)
• --full-review-round N - Interval for full alignment checks (default: 5)
• --skip-impl - Skip implementation phase, go directly to code review
• --track-plan-file - Enforce plan-file immutability when tracked in git
• --push-every-round - Require git push after each round
• --claude-answer-codex - Let Claude answer Codex Open Questions directly (default is AskUserQuestion)
• --agent-teams - Enable Agent Teams mode
• --yolo - Skip Plan Understanding Quiz and enable --claude-answer-codex
• --skip-quiz - Skip the Plan Understanding Quiz only
• --privacy - Disable methodology analysis at loop exit (default: analysis enabled)

Cancel RLCR Loop

"{{HUMANIZE_RUNTIME_ROOT}}/scripts/cancel-rlcr-loop.sh"
# or force cancel during finalize phase
"{{HUMANIZE_RUNTIME_ROOT}}/scripts/cancel-rlcr-loop.sh" --force

Generate Plan from Draft

"{{HUMANIZE_RUNTIME_ROOT}}/scripts/validate-gen-plan-io.sh" --input path/to/draft.md --output path/to/plan.md

Then follow the workflow in this skill to generate the structured plan content.

Ask Codex (One-shot Consultation)

"{{HUMANIZE_RUNTIME_ROOT}}/scripts/ask-codex.sh" [--codex-model MODEL:EFFORT] [--codex-timeout SECONDS] "your question"

Plan File Structure

A good plan file should include:

# Plan Title

## Goal Description
Clear description of what needs to be accomplished

## Acceptance Criteria

- AC-1: First criterion
  - Positive Tests (expected to PASS):
    - Test case that should succeed
  - Negative Tests (expected to FAIL):
    - Test case that should fail

## Path Boundaries

### Upper Bound (Maximum Scope)
Most comprehensive acceptable implementation

### Lower Bound (Minimum Scope)
Minimum viable implementation

### Allowed Choices
- Can use: technologies, approaches allowed
- Cannot use: prohibited technologies

## Dependencies and Sequence

### Milestones
1. Milestone 1: Description
   - Phase A: ...
   - Phase B: ...

## Implementation Notes
- Code should NOT contain plan terminology like "AC-", "Milestone", "Step"

Goal Tracker System

The RLCR loop uses a Goal Tracker to prevent goal drift:

• IMMUTABLE SECTION: Ultimate Goal and Acceptance Criteria (set in Round 0, never changed)
• MUTABLE SECTION: Active Tasks, Completed Items, Deferred Items, Plan Evolution Log

Key Principles

1. Acceptance Criteria: Each task maps to a specific AC
2. Plan Evolution Log: Document any plan changes with justification
3. Explicit Deferrals: Deferred tasks require strong justification
4. Full Alignment Checks: Every N rounds (default: 5), comprehensive goal alignment audit

Important Rules

1. Write summaries: Always write work summary to the specified file before exiting
2. Maintain Goal Tracker: Keep goal-tracker.md up-to-date with progress
3. Be thorough: Include details about implementation, files changed, tests added
4. No cheating: Don't try to exit by editing state files or running cancel commands
5. Use the native Stop hook on Codex: After writing the required summary, stop/exit normally so Codex runs the Humanize Stop hook
6. Trust the process: External review helps improve implementation quality

Prerequisites

• codex - OpenAI Codex CLI (for review)

Directory Structure

Humanize stores all data in .humanize/:

.humanize/
├── rlcr/           # RLCR loop data
│   └── <timestamp>/
│       ├── state.md
│       ├── goal-tracker.md
│       ├── round-N-summary.md
│       ├── round-N-review-result.md
│       ├── finalize-state.md
│       ├── finalize-summary.md
│       ├── methodology-analysis-state.md
│       ├── methodology-analysis-report.md
│       ├── methodology-analysis-done.md
│       └── complete-state.md
└── skill/          # One-shot skill results
    └── <timestamp>/
        ├── input.md
        ├── output.md
        └── metadata.md

Monitoring

Use the monitor script to track loop progress:

source "{{HUMANIZE_RUNTIME_ROOT}}/scripts/humanize.sh"
humanize monitor rlcr   # Monitor RLCR loop

Exit Codes

ask-codex.sh

• 0 - Success
• 1 - Validation error
• 124 - Timeout

validate-gen-plan-io.sh

• 0 - Success
• 1 - Input file not found
• 2 - Input file is empty
• 3 - Output directory does not exist
• 4 - Output file already exists
• 5 - No write permission
• 6 - Invalid arguments
• 7 - Plan template file not found