Improve gen-plan convergence and task-tag routing

.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
       "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.14.0"
+      "version": "1.15.0"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "humanize",
   "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.14.0",
+  "version": "1.15.0",
   "author": {
     "name": "humania-org"
   },

README.md

@@ -1,6 +1,6 @@
 # Humanize
 
-**Current Version: 1.14.0**
+**Current Version: 1.15.0**
 
 > Derived from the [GAAC (GitHub-as-a-Context)](https://github.com/SihaoLiu/gaac) project.
 

commands/start-rlcr-loop.md

@@ -67,7 +67,9 @@ If the pre-check passed (or was skipped), execute the setup script to initialize
 
 This command starts an iterative development loop where:
 
-1. You work on the implementation plan provided
+1. You execute the implementation plan with task-tag routing
+   - `coding` tasks: Claude executes directly
+   - `analyze` tasks: execute via `/humanize:ask-codex`
 2. Write a summary of your work to the specified summary file
 3. When you try to exit, Codex reviews your summary
 4. If Codex finds issues, you receive feedback and continue
@@ -86,9 +88,11 @@ This loop uses a **Goal Tracker** to prevent goal drift across iterations:
 
 ### Key Features
 1. **Acceptance Criteria**: Each task maps to a specific AC - nothing can be "forgotten"
-2. **Plan Evolution Log**: If you discover the plan needs changes, document the change with justification
-3. **Explicit Deferrals**: Deferred tasks require strong justification and impact analysis
-4. **Full Alignment Checks**: At configurable intervals (default every 5 rounds: rounds 4, 9, 14, etc.), Codex conducts a comprehensive goal alignment audit. Use `--full-review-round N` to customize (min: 2)
+2. **Task Tag Routing**: Every task should carry `coding` or `analyze` tag from plan generation
+   - `coding -> Claude`, `analyze -> Codex`
+3. **Plan Evolution Log**: If you discover the plan needs changes, document the change with justification
+4. **Explicit Deferrals**: Deferred tasks require strong justification and impact analysis
+5. **Full Alignment Checks**: At configurable intervals (default every 5 rounds: rounds 4, 9, 14, etc.), Codex conducts a comprehensive goal alignment audit. Use `--full-review-round N` to customize (min: 2)
 
 ### How to Use
 1. **Round 0**: Initialize the Goal Tracker with Ultimate Goal and Acceptance Criteria
@@ -113,7 +117,7 @@ This loop uses a **Goal Tracker** to prevent goal drift across iterations:
 
 The RLCR loop has two phases within the active loop:
 
-1. **Implementation Phase**: Work on the plan, Codex reviews your summary
+1. **Implementation Phase**: Work by task tags (`coding -> Claude`, `analyze -> /humanize:ask-codex`), then Codex reviews your summary
 2. **Review Phase**: After COMPLETE, `codex review` checks code quality with `[P0-9]` severity markers
 
 The `--base-branch` option specifies the base branch for code review comparison. If not provided, it auto-detects from: remote default > local main > local master.

docs/usage.md

@@ -56,11 +56,16 @@ OPTIONS:
 ### gen-plan
 
 ```
-/humanize:gen-plan --input <path/to/draft.md> --output <path/to/plan.md>
+/humanize:gen-plan --input <path/to/draft.md> --output <path/to/plan.md> [OPTIONS]
 
 OPTIONS:
   --input   Path to the input draft file (required)
   --output  Path to the output plan file (required)
+  --auto-start-rlcr-if-converged
+             Start the RLCR loop automatically when the plan is converged
+             (discussion mode only; ignored in --direct)
+  --discussion  Use discussion mode (iterative Claude/Codex convergence rounds)
+  --direct      Use direct mode (skip convergence rounds, proceed immediately to plan)
   -h, --help             Show help message
 
 The gen-plan command transforms rough draft documents into structured implementation plans.
@@ -71,6 +76,7 @@ Workflow:
 3. Analyzes draft for clarity, consistency, completeness, and functionality
 4. Engages user to resolve any issues found
 5. Generates a structured plan.md with acceptance criteria
+6. Optionally starts `/humanize:start-rlcr-loop` if `--auto-start-rlcr-if-converged` conditions are met
 ```
 
 ### start-pr-loop

hooks/loop-codex-stop-hook.sh

@@ -1163,6 +1163,22 @@ Focus on the code changes made during this RLCR session. Focus more on changes b
     exit 0
 }
 
+# Append task tag routing reminder to follow-up prompts.
+# Arguments: $1=prompt_file_path
+append_task_tag_routing_note() {
+    local prompt_file="$1"
+
+    cat >> "$prompt_file" << 'ROUTING_EOF'
+
+## Task Tag Routing Reminder
+
+Follow the plan's per-task routing tags strictly:
+- `coding` task -> Claude executes directly
+- `analyze` task -> execute via `/humanize:ask-codex`, then integrate the result
+- Keep Goal Tracker Active Tasks columns `Tag` and `Owner` aligned with execution
+ROUTING_EOF
+}
+
 # Continue review loop when issues are found
 # Arguments: $1=round_number, $2=review_content
 continue_review_loop_with_issues() {
@@ -1198,6 +1214,7 @@ You are in the **Review Phase** of the RLCR loop. Codex has performed a code rev
     load_and_render_safe "$TEMPLATE_DIR" "claude/review-phase-prompt.md" "$fallback" \
         "REVIEW_CONTENT=$review_content" \
         "SUMMARY_FILE=$next_summary_file" > "$next_prompt_file"
+    append_task_tag_routing_note "$next_prompt_file"
 
     jq -n \
         --arg reason "$(cat "$next_prompt_file")" \
@@ -1625,6 +1642,7 @@ FOOTER_FALLBACK="## Before Exiting
 Commit your changes and write summary to {{NEXT_SUMMARY_FILE}}"
 load_and_render_safe "$TEMPLATE_DIR" "claude/next-round-footer.md" "$FOOTER_FALLBACK" \
     "NEXT_SUMMARY_FILE=$NEXT_SUMMARY_FILE" >> "$NEXT_PROMPT_FILE"
+append_task_tag_routing_note "$NEXT_PROMPT_FILE"
 
 # Add push instruction only if push_every_round is true
 if [[ "$PUSH_EVERY_ROUND" == "true" ]]; then

prompt-template/plan/gen-plan-template.md

@@ -66,9 +66,55 @@ Example: "The implementation includes core feature X with basic validation"
 
 <Describe relative dependencies between components, not time estimates>
 
+## Task Breakdown
+
+Each task must include exactly one routing tag:
+- `coding`: implemented by Claude
+- `analyze`: executed via Codex (`/humanize:ask-codex`)
+
+| Task ID | Description | Target AC | Tag (`coding`/`analyze`) | Depends On |
+|---------|-------------|-----------|----------------------------|------------|
+| task1 | <...> | AC-1 | coding | - |
+| task2 | <...> | AC-2 | analyze | task1 |
+
+## Claude-Codex Deliberation
+
+### Agreements
+- <Point both sides agree on>
+
+### Resolved Disagreements
+- <Topic>: Claude vs Codex summary, chosen resolution, and rationale
+
+### Convergence Status
+- Final Status: `converged` or `partially_converged`
+
+## Pending User Decisions
+
+- DEC-1: <Decision topic>
+  - Claude Position: <...>
+  - Codex Position: <...>
+  - Tradeoff Summary: <...>
+  - Decision Status: `PENDING` or `<User's final decision>`
+
 ## Implementation Notes
 
 ### Code Style Requirements
 - Implementation code and comments must NOT contain plan-specific terminology such as "AC-", "Milestone", "Step", "Phase", or similar workflow markers
 - These terms are for plan documentation only, not for the resulting codebase
 - Use descriptive, domain-appropriate naming in code instead
+
+## Output File Convention
+
+This template is used to produce the main output file (e.g., `plan.md`).
+
+### Chinese Variant (`_zh` file)
+
+When `chinese_plan=true` is set in `.humanize/config.json`, a `_zh` variant of the output file is also written after the main file. The `_zh` filename is constructed by inserting `_zh` immediately before the file extension:
+
+- `plan.md` becomes `plan_zh.md`
+- `docs/my-plan.md` becomes `docs/my-plan_zh.md`
+- `output` (no extension) becomes `output_zh`
+
+The `_zh` file contains a full Chinese translation of the English plan. All identifiers (`AC-*`, task IDs, file paths, API names, command flags) remain unchanged, as they are language-neutral.
+
+When `chinese_plan=false` (the default), or when `.humanize/config.json` does not exist, or when the `chinese_plan` field is absent, the `_zh` file is NOT written. A missing config file is not an error.

scripts/setup-rlcr-loop.sh

@@ -99,7 +99,9 @@ DESCRIPTION:
   3. Has two phases: Implementation Phase and Review Phase
 
   The flow:
-  1. Claude works on the plan (Implementation Phase)
+  1. Claude executes plan tasks with tag-based routing (Implementation Phase)
+     - `coding` tasks: Claude implements directly
+     - `analyze` tasks: Claude delegates execution via `/humanize:ask-codex`
   2. Claude writes a summary to round-N-summary.md
   3. On exit attempt, Codex reviews the summary
   4. If Codex finds issues, it blocks exit and sends feedback
@@ -929,10 +931,10 @@ cat >> "$GOAL_TRACKER_FILE" << 'GOAL_TRACKER_EOF'
 | 0 | Initial plan | - | - |
 
 #### Active Tasks
-<!-- Map each task to its target Acceptance Criterion -->
-| Task | Target AC | Status | Notes |
-|------|-----------|--------|-------|
-| [To be populated by Claude based on plan] | - | pending | - |
+<!-- Map each task to its target Acceptance Criterion and routing tag -->
+| Task | Target AC | Status | Tag | Owner | Notes |
+|------|-----------|--------|-----|-------|-------|
+| [To be populated by Claude based on plan] | - | pending | coding or analyze | claude or codex | - |
 
 ### Completed and Verified
 <!-- Only move tasks here after Codex verification -->
@@ -1007,7 +1009,7 @@ Before starting implementation, you MUST initialize the Goal Tracker:
 1. Read @$GOAL_TRACKER_FILE
 2. If the "Ultimate Goal" section says "[To be extracted...]", extract a clear goal statement from the plan
 3. If the "Acceptance Criteria" section says "[To be defined...]", define 3-7 specific, testable criteria
-4. Populate the "Active Tasks" table with tasks from the plan, mapping each to an AC
+4. Populate the "Active Tasks" table with tasks from the plan, mapping each to an AC and filling Tag/Owner
 5. Write the updated goal-tracker.md
 
 **IMPORTANT**: The IMMUTABLE SECTION can only be modified in Round 0. After this round, it becomes read-only.
@@ -1019,6 +1021,15 @@ Before starting implementation, you MUST initialize the Goal Tracker:
 For all tasks that need to be completed, please use the Task system (TaskCreate, TaskUpdate, TaskList) to track each item in order of importance.
 You are strictly prohibited from only addressing the most important issues - you MUST create Tasks for ALL discovered issues and attempt to resolve each one.
 
+## Task Tag Routing (MUST FOLLOW)
+
+Each task must have one routing tag from the plan: \`coding\` or \`analyze\`.
+
+- Tag \`coding\`: Claude executes the task directly.
+- Tag \`analyze\`: Claude must execute via \`/humanize:ask-codex\`, then integrate Codex output.
+- Keep Goal Tracker "Active Tasks" columns **Tag** and **Owner** aligned with execution (\`coding -> claude\`, \`analyze -> codex\`).
+- If a task is missing a valid tag, do not guess silently; document it in Plan Evolution Log and block completion until clarified.
+
 EOF
 
 # Append plan content directly (avoids command substitution size limits for large files)
@@ -1057,6 +1068,7 @@ cat >> "$LOOP_DIR/round-0-prompt.md" << EOF
 Throughout your work, you MUST maintain the Goal Tracker:
 
 1. **Before starting a task**: Mark it as "in_progress" in Active Tasks
+   - Confirm Tag/Owner routing is correct before execution
 2. **After completing a task**: Move it to "Completed and Verified" with evidence (but mark as "pending verification")
 3. **If you discover the plan has errors**:
    - Do NOT silently change direction

scripts/validate-gen-plan-io.sh

@@ -14,17 +14,23 @@
 set -e
 
 usage() {
-    echo "Usage: $0 --input <path/to/draft.md> --output <path/to/plan.md>"
+    echo "Usage: $0 --input <path/to/draft.md> --output <path/to/plan.md> [--auto-start-rlcr-if-converged] [--discussion|--direct]"
     echo ""
     echo "Options:"
     echo "  --input   Path to the input draft file (required)"
     echo "  --output  Path to the output plan file (required)"
+    echo "  --auto-start-rlcr-if-converged  Enable direct RLCR start after converged planning (discussion mode only)"
+    echo "  --discussion  Use discussion mode (iterative Claude/Codex convergence rounds)"
+    echo "  --direct      Use direct mode (skip convergence rounds, proceed immediately to plan)"
     echo "  -h, --help  Show this help message"
     exit 6
 }
 
 INPUT_FILE=""
 OUTPUT_FILE=""
+AUTO_START_RLCR_IF_CONVERGED="false"
+GEN_PLAN_MODE_DISCUSSION="false"
+GEN_PLAN_MODE_DIRECT="false"
 
 # Parse arguments
 while [[ $# -gt 0 ]]; do
@@ -45,6 +51,18 @@ while [[ $# -gt 0 ]]; do
             OUTPUT_FILE="$2"
             shift 2
             ;;
+        --auto-start-rlcr-if-converged)
+            AUTO_START_RLCR_IF_CONVERGED="true"
+            shift
+            ;;
+        --discussion)
+            GEN_PLAN_MODE_DISCUSSION="true"
+            shift
+            ;;
+        --direct)
+            GEN_PLAN_MODE_DIRECT="true"
+            shift
+            ;;
         -h|--help)
             usage
             ;;
@@ -55,6 +73,12 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+# Validate mutually exclusive flags
+if [[ "$GEN_PLAN_MODE_DISCUSSION" == "true" && "$GEN_PLAN_MODE_DIRECT" == "true" ]]; then
+    echo "Error: --discussion and --direct are mutually exclusive"
+    exit 6
+fi
+
 # Validate required arguments
 if [[ -z "$INPUT_FILE" ]]; then
     echo "ERROR: --input is required"
@@ -66,6 +90,11 @@ if [[ -z "$OUTPUT_FILE" ]]; then
     usage
 fi
 
+# Note on auto-start behavior in direct mode
+if [[ "$GEN_PLAN_MODE_DIRECT" == "true" && "$AUTO_START_RLCR_IF_CONVERGED" == "true" ]]; then
+    echo "NOTE: --auto-start-rlcr-if-converged only triggers in --discussion mode; in --direct mode the plan is not considered converged and auto-start will be skipped."
+fi
+
 # Get absolute paths
 INPUT_FILE=$(realpath -m "$INPUT_FILE" 2>/dev/null || echo "$INPUT_FILE")
 OUTPUT_FILE=$(realpath -m "$OUTPUT_FILE" 2>/dev/null || echo "$OUTPUT_FILE")

tests/run-all-tests.sh

@@ -51,6 +51,7 @@ TEST_SUITES=(
     "test-monitor-e2e-deletion.sh"
     "test-monitor-e2e-sigint.sh"
     "test-gen-plan.sh"
+    "test-task-tag-routing.sh"
     "test-pr-loop-1-scripts.sh"
     "test-pr-loop-2-hooks.sh"
     "test-pr-loop-3-stophook.sh"