Apply Humanize2 platform onto h2-dev alongside dev features

Bring the entire Humanize 2.0 codebase (MCP server hub, HTML workflow
runtime, agent backends, dashboard, and first-party flow cartridges)
into h2-dev so this branch carries both the Humanize 1.0 RLCR plugin
surface from dev and the Humanize 2.0 platform surface.

- Register a humanize2 MCP server at the plugin root via .mcp.json,
  pointing at the built dist/index.js, following the Claude Code
  plugin MCP server convention (location at plugin root, command
  invoked under CLAUDE_PLUGIN_ROOT).
- Add the TypeScript MCP server sources under src/, hub HTTP server,
  agent backends, workflow coordinator, schema registry, storage,
  recovery, and projection.
- Add manual smoke scripts under scripts/ and the vitest suite under
  tests/, including workflow grammar, RPC, storage, and recovery
  coverage.
- Add the workflow cartridges under flow/ (rlcr, gen-idea, gen-plan,
  refine-plan, experimental/team-intervention-smoke).
- Extend .gitignore for the Humanize2 build artifacts (node_modules,
  dist, coverage, logs, local .h2 state).
- Update README to document the Humanize 2.0 platform side of this
  transitional branch.

Author: SihaoLiu

.gitignore

@@ -16,3 +16,15 @@ temp
 # Python cache
 __pycache__/
 *.pyc
+
+# Humanize2 build artifacts and dependencies
+node_modules/
+dist/
+coverage/
+*.log
+
+# Local superpowers cache
+.superpowers/
+
+# Humanize2 runtime state (per-user, written under ~/.h2 by default)
+.h2/

.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "humanize2": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"],
+      "cwd": "${CLAUDE_PLUGIN_ROOT}"
+    }
+  }
+}

README.md

@@ -6,6 +6,8 @@
 
 A Claude Code plugin that provides iterative development with independent AI review. Build with confidence through continuous feedback loops.
 
+> **Note**: The `h2-dev` branch is a transitional branch that ships Humanize 1.0 features (RLCR loop, Codex review, planning commands) **and** the Humanize 2.0 platform (MCP server hub with HTML workflow cartridges) side by side. See the [Humanize 2.0 Platform](#humanize-20-platform-mcp-server-hub) section below for the new generic workflow runtime.
+
 ## 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.
@@ -98,6 +100,66 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [
 - [Configuration](docs/usage.md#configuration) -- Shared config hierarchy and override rules
 - [Bitter Lesson Workflow](docs/bitlesson.md) -- Project memory, selector routing, and delta validation
 
+## Humanize 2.0 Platform (MCP Server Hub)
+
+Humanize 2.0 ships alongside the 1.0 plugin on this branch. It is a local MCP server hub and HTML workflow runtime that turns Humanize from a fixed RLCR plugin into a general-purpose flow execution platform. The same human programmer keeps using familiar agent CLIs (Codex, Claude Code, Gemini CLI, Zed, etc.); the hub provides the shared workflow layer underneath.
+
+### Build
+
+The MCP server is shipped as TypeScript source and must be built once before use:
+
+```bash
+cd <plugin-root>
+npm install
+npm run build
+```
+
+### Plugin MCP Registration
+
+The plugin auto-registers a `humanize2` MCP server via `.mcp.json` at the plugin root. After building, the server starts automatically with the plugin under any MCP-capable Claude Code client.
+
+### Start the Local Hub
+
+```bash
+HUMANIZE2_PORT=4772 npm run hub
+# Open the dashboard
+xdg-open http://127.0.0.1:4772
+```
+
+The dashboard lists Agent Sessions, shows the logical session graph and Gantt timeline, and lets you select a session to inspect input history, log, and output. The hub uses `~/.h2/config.yaml` and stores run history under `~/.h2/cache` by default. Set `HUMANIZE2_CACHE_DIR` or `HUMANIZE2_DEFAULT_TIMEOUT_MS` to override those values.
+
+### MCP Tools
+
+The `humanize2` server exposes these MCP tools:
+
+- `agent_status` reports availability for configured agent backends.
+- `agent_run` accepts an explicit `agent` field and dispatches to that backend.
+- `agent_spawn_child` starts a hub-managed child run; the current run is used as the parent automatically when called from a Humanize2-managed agent.
+- `codex_run` dispatches directly to Codex CLI.
+- `claude_run` dispatches directly to Claude Code CLI.
+- `agent_send_message` sends a message to a hub-managed run. If the run is still active, the hub interrupts it and starts a linked continuation run.
+- `agent_wait` waits for a hub-managed run to finish.
+
+The hub also exposes a workflow surface (`workflow_*`, `view_*`, `board_*`, `artifact_*`, `event_*`, `human_*`) for HTML workflow cartridges under `flow/`.
+
+### Workflow Cartridges
+
+First-party flow cartridges ship under `flow/`:
+
+- `flow/rlcr` -- the legacy RLCR loop expressed as a workflow cartridge
+- `flow/gen-idea`, `flow/gen-plan`, `flow/refine-plan` -- planning workflows
+- `flow/experimental/team-intervention-smoke` -- intervention smoke test
+
+See the source under `src/` and tests under `tests/` for the full workflow grammar, MCP/RPC surface, and runtime behavior.
+
+### Development Checks
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```
+
 ## License
 
 MIT

flow/experimental/team-intervention-smoke/workflow.html

@@ -0,0 +1,53 @@
+<h2-workflow id="team-intervention-smoke" name="Team Intervention Smoke" version="0.1.0" schema="humanize2.workflow.html.v1">
+  <h2-manifest>
+    <h2-capability name="agent" tools="codex,claude"></h2-capability>
+    <h2-capability name="artifact" schemas="team.workerResult.v1,team.captainResult.v1"></h2-capability>
+    <h2-capability name="script" allow="test.pass"></h2-capability>
+    <h2-capability name="view"></h2-capability>
+  </h2-manifest>
+
+  <h2-state>
+    <h2-board id="team-board" schema="team.board.v1"></h2-board>
+    <h2-artifact name="worker-1-final" schema="team.workerResult.v1"></h2-artifact>
+    <h2-artifact name="worker-2-final" schema="team.workerResult.v1"></h2-artifact>
+    <h2-artifact name="worker-3-final" schema="team.workerResult.v1"></h2-artifact>
+    <h2-artifact name="team-summary" schema="team.captainResult.v1"></h2-artifact>
+  </h2-state>
+
+  <h2-template id="captain-prompt" type="prompt">
+    You are the captain for a Humanize2 team-intervention smoke run. This workflow expects you, the captain, to coordinate the whole team through Humanize2 and then deliver the final artifact named team-summary.
+
+    Use Humanize2 MCP tools directly when available. The workflow context also includes a JSON-RPC URL as a fallback for the same operations. Do not create workers by writing handoff files.
+
+    Do this exact workflow:
+    1. Create three managed worker agent sessions for yourself with agent_spawn_child. Omit parentRunId so Humanize2 uses your current run as the logical parent.
+       Worker 1: agent codex, shortName team-worker-1, cwd inherited from this run, timeoutMs 900000.
+       Worker 2: agent claude, shortName team-worker-2, cwd inherited from this run, timeoutMs 900000.
+       Worker 3: agent codex, shortName team-worker-3, cwd inherited from this run, timeoutMs 900000.
+    2. Give each worker an initial prompt that tells it to write a local note under temp/team-worker-N.md, record initial task A/B/C with local timestamp and cwd, wait 90 seconds before finalizing unless a Humanize2 message changes the task, then deliver worker-N-final through Humanize2 with schema team.workerResult.v1 and producer worker-N.
+    3. Wait 25 seconds after all three workers are created.
+    4. Use agent_send_message to change worker 1 from task A to final task D, worker 2 from task B to final task E, and worker 3 from task C to final task F. Keep the same output files.
+    5. Wait for the worker runs or their continuation runs to stop with agent_wait.
+    6. Patch board team-board with status ok and a short summary of worker final tasks.
+    7. Deliver artifact team-summary through Humanize2 with schema team.captainResult.v1, producer captain, and content containing status ok plus the worker run ids, worker artifact names, and final tasks D/E/F.
+
+    Do not finish until team-summary has been delivered.
+  </h2-template>
+
+  <h2-flow>
+    <h2-script id="preflight" uses="test.pass"></h2-script>
+    <h2-agent id="captain" role="captain" tool="codex" prompt="#captain-prompt" short-name="team-captain" timeout="20m">
+      <h2-expect artifact="team-summary" schema="team.captainResult.v1"></h2-expect>
+    </h2-agent>
+    <h2-transform id="team-board-result" from="artifact.team-summary" to="board.team-board"></h2-transform>
+    <h2-script id="complete" uses="test.pass"></h2-script>
+  </h2-flow>
+
+  <h2-view slot="properties">
+    <section data-h2-view="team-board">
+      <h3>Team Intervention Smoke</h3>
+      <p>Status: <span data-h2-bind="board.team-board.status">Waiting for captain summary.</span></p>
+      <p>Primary final tasks: <span data-h2-bind="board.team-board.finalTasks">-</span></p>
+    </section>
+  </h2-view>
+</h2-workflow>

flow/gen-idea/workflow.html

@@ -0,0 +1,80 @@
+<h2-workflow id="gen-idea" name="Generate Idea Draft" version="0.1.0" schema="humanize2.workflow.html.v1">
+  <h2-manifest>
+    <h2-capability name="agent" tools="claude,codex"></h2-capability>
+    <h2-capability name="artifact" schemas="idea.input.v1,idea.directions.v1,idea.proposal.v1,idea.draft.v1"></h2-capability>
+    <h2-capability name="script" allow="humanize.validateIdeaInput,idea.collectProposalStatus"></h2-capability>
+    <h2-capability name="view"></h2-capability>
+  </h2-manifest>
+
+  <h2-state>
+    <h2-board id="idea-scoreboard" schema="idea.scoreboard.v1"></h2-board>
+  </h2-state>
+
+  <h2-template id="direction-prompt" type="prompt">
+    Read the delivered idea-input artifact and repository context. Do not modify project files.
+    Gather repo context from README.md, local instruction files when present, and the top-level directory listing.
+    Produce exactly 6 orthogonal directions. Each direction must include a 2-5 word name and a single-sentence rationale explaining why it is distinct.
+    If fewer than 6 directions are possible after one retry, deliver at least 2 directions and include a warning field. Deliver idea-directions through Humanize2.
+  </h2-template>
+  <h2-template id="exploration-prompt" type="prompt">
+    Explore the direction assigned by your vertex id and expected artifact. Read idea-directions and select the matching ordered direction.
+    Include a verbatim copy of the original idea from idea-input in your reasoning context.
+    Explore this direction within the current repo. Gather OBJECTIVE_EVIDENCE:
+    - Specific repo paths with existing patterns worth extending.
+    - Prior art or precedent in the codebase or adjacent tooling.
+    - Measurable considerations where discoverable from reading the code.
+
+    Read-only. Do not write any files.
+
+    If no concrete evidence exists for this direction, report the literal string "exploratory, no concrete precedent" once in OBJECTIVE_EVIDENCE and stop exploring further. Fabrication of references is forbidden.
+
+    Deliver your expected idea-proposal-* artifact through Humanize2 with APPROACH_SUMMARY, OBJECTIVE_EVIDENCE, KNOWN_RISKS, and CONFIDENCE.
+  </h2-template>
+  <h2-template id="synthesis-prompt" type="prompt">
+    Synthesize the delivered exploration proposals into one Primary direction and alternatives.
+    Choose the Primary direction by evidence density, fit with existing repo patterns, implementation surface area, and confidence.
+    Preserve the original idea content from idea-input byte-for-byte in the draft content.
+    Deliver idea-draft through Humanize2 with title, original idea, primary direction, objective evidence, known risks, alternatives, synthesis notes, requested direction count, and actual proposal count.
+  </h2-template>
+
+  <h2-flow>
+    <h2-check id="validate-input" uses="humanize.validateIdeaInput"></h2-check>
+    <h2-await id="idea-input-await" on="exists(artifact.idea-input)"></h2-await>
+    <h2-agent id="direction-lead" role="lead" tool="claude" prompt="#direction-prompt" short-name="gen-idea-directions" timeout="30m">
+      <h2-expect artifact="idea-directions" schema="idea.directions.v1"></h2-expect>
+    </h2-agent>
+    <h2-parallel id="exploration-swarm">
+      <h2-agent id="explore-direction-1" role="explorer" parent="direction-lead" tool="claude" prompt="#exploration-prompt" short-name="idea-direction-1" timeout="30m">
+        <h2-expect artifact="idea-proposal-1" schema="idea.proposal.v1"></h2-expect>
+      </h2-agent>
+      <h2-agent id="explore-direction-2" role="explorer" parent="direction-lead" tool="codex" prompt="#exploration-prompt" short-name="idea-direction-2" timeout="30m">
+        <h2-expect artifact="idea-proposal-2" schema="idea.proposal.v1"></h2-expect>
+      </h2-agent>
+      <h2-agent id="explore-direction-3" role="explorer" parent="direction-lead" tool="claude" prompt="#exploration-prompt" short-name="idea-direction-3" timeout="30m">
+        <h2-expect artifact="idea-proposal-3" schema="idea.proposal.v1"></h2-expect>
+      </h2-agent>
+      <h2-agent id="explore-direction-4" role="explorer" parent="direction-lead" tool="codex" prompt="#exploration-prompt" short-name="idea-direction-4" timeout="30m">
+        <h2-expect artifact="idea-proposal-4" schema="idea.proposal.v1"></h2-expect>
+      </h2-agent>
+      <h2-agent id="explore-direction-5" role="explorer" parent="direction-lead" tool="claude" prompt="#exploration-prompt" short-name="idea-direction-5" timeout="30m">
+        <h2-expect artifact="idea-proposal-5" schema="idea.proposal.v1"></h2-expect>
+      </h2-agent>
+      <h2-agent id="explore-direction-6" role="explorer" parent="direction-lead" tool="codex" prompt="#exploration-prompt" short-name="idea-direction-6" timeout="30m">
+        <h2-expect artifact="idea-proposal-6" schema="idea.proposal.v1"></h2-expect>
+      </h2-agent>
+    </h2-parallel>
+    <h2-transform id="proposal-summary" from="artifact.idea-proposal-1" to="board.idea-scoreboard" uses="idea.collectProposalStatus"></h2-transform>
+    <h2-agent id="synthesis-lead" role="synthesizer" tool="claude" prompt="#synthesis-prompt" short-name="idea-synthesis" timeout="30m">
+      <h2-expect artifact="idea-draft" schema="idea.draft.v1"></h2-expect>
+    </h2-agent>
+  </h2-flow>
+
+  <h2-view slot="properties">
+    <section data-h2-view="idea-scoreboard">
+      <h3>Idea Exploration Scoreboard</h3>
+      <p>Architecture proposal: <span data-h2-bind="board.idea-scoreboard.architecture">-</span></p>
+      <p>Product proposal: <span data-h2-bind="board.idea-scoreboard.product">-</span></p>
+      <p>Risk proposal: <span data-h2-bind="board.idea-scoreboard.risk">-</span></p>
+    </section>
+  </h2-view>
+</h2-workflow>

flow/gen-plan/workflow.html

@@ -0,0 +1,72 @@
+<h2-workflow id="gen-plan" name="Generate Plan" version="0.1.0" schema="humanize2.workflow.html.v1">
+  <h2-manifest>
+    <h2-capability name="agent" tools="claude,codex"></h2-capability>
+    <h2-capability name="artifact" schemas="plan.draft.v1,plan.relevance.v1,plan.analysis.v1,plan.candidate.v1,plan.verdict.v1,plan.final.v1,plan.humanDecision.v1"></h2-capability>
+    <h2-capability name="script" allow="humanize.validatePlanInput,humanize.resolveProjectConfig"></h2-capability>
+    <h2-capability name="human-input"></h2-capability>
+    <h2-capability name="view"></h2-capability>
+  </h2-manifest>
+
+  <h2-state>
+    <h2-board id="plan-convergence" schema="plan.convergence.v1"></h2-board>
+  </h2-state>
+
+  <h2-template id="relevance-prompt" type="prompt">
+    Inspect the delivered idea draft and repository context. Deliver plan-relevance with relevant or not-relevant status and a concise reason.
+  </h2-template>
+  <h2-template id="analysis-prompt" type="prompt">
+    Review the delivered draft before planning. Deliver plan-first-pass-analysis with risks, missing requirements, technical gaps, alternatives, questions, and candidate criteria.
+  </h2-template>
+  <h2-template id="candidate-prompt" type="prompt">
+    Use the draft, relevance result, first-pass analysis, and any prior convergence verdict to produce a candidate implementation plan.
+    The plan must preserve all original draft content, identify risks, and include task routing tags. Deliver plan-candidate through Humanize2.
+  </h2-template>
+  <h2-template id="review-prompt" type="prompt">
+    Challenge the candidate plan for feasibility and unresolved decisions. Deliver plan-convergence-verdict through Humanize2.
+    Use status converged when no required changes remain, revise when another candidate pass is needed, or needs-human-decision when an explicit user decision is required.
+    Include agreements, disagreements, required changes, optional improvements, unresolved decisions, and convergence notes.
+  </h2-template>
+  <h2-template id="final-plan-prompt" type="prompt">
+    Generate the final plan artifact using the agreed schema. Do not implement project code.
+    The final plan must include Goal Description, Acceptance Criteria, Path Boundaries, Feasibility Hints and Suggestions, Dependencies and Sequence, Task Breakdown, Claude-Codex Deliberation, Pending User Decisions, and Implementation Notes.
+    Every Task Breakdown row must use a tag of coding or analyze.
+    Preserve the draft appendix and summarize resolved disagreements. Deliver plan-final through Humanize2.
+  </h2-template>
+
+  <h2-flow>
+    <h2-check id="validate-io" uses="humanize.validatePlanInput"></h2-check>
+    <h2-check id="load-config" uses="humanize.resolveProjectConfig"></h2-check>
+    <h2-await id="plan-draft-await" on="exists(artifact.plan-draft)"></h2-await>
+    <h2-agent id="relevance-checker" role="checker" tool="claude" prompt="#relevance-prompt" short-name="plan-relevance" timeout="20m">
+      <h2-expect artifact="plan-relevance" schema="plan.relevance.v1"></h2-expect>
+    </h2-agent>
+    <h2-agent id="first-pass-reviewer" role="reviewer" tool="codex" prompt="#analysis-prompt" short-name="plan-first-pass" timeout="30m">
+      <h2-expect artifact="plan-first-pass-analysis" schema="plan.analysis.v1"></h2-expect>
+    </h2-agent>
+    <h2-loop id="plan-convergence-loop" max="3">
+      <h2-agent id="candidate-writer" role="planner" tool="claude" prompt="#candidate-prompt" short-name="plan-candidate" timeout="45m">
+        <h2-expect artifact="plan-candidate" schema="plan.candidate.v1"></h2-expect>
+      </h2-agent>
+      <h2-agent id="convergence-reviewer" role="reviewer" tool="codex" prompt="#review-prompt" short-name="plan-convergence" timeout="30m">
+        <h2-expect artifact="plan-convergence-verdict" schema="plan.verdict.v1"></h2-expect>
+      </h2-agent>
+      <h2-branch id="convergence-route" on="artifact.plan-convergence-verdict.status">
+        <h2-case value="revise" continue="plan-convergence-loop"></h2-case>
+        <h2-case value="converged" goto="final-plan-writer"></h2-case>
+        <h2-case value="needs-human-decision" goto="decision-request"></h2-case>
+        <h2-default goto="decision-request"></h2-default>
+      </h2-branch>
+    </h2-loop>
+    <h2-human id="decision-request" prompt="Resolve pending planning decisions" artifact="plan-human-decision" schema="plan.humanDecision.v1"></h2-human>
+    <h2-agent id="final-plan-writer" role="planner" tool="claude" prompt="#final-plan-prompt" short-name="plan-final" timeout="45m">
+      <h2-expect artifact="plan-final" schema="plan.final.v1"></h2-expect>
+    </h2-agent>
+  </h2-flow>
+
+  <h2-view slot="properties">
+    <section data-h2-view="plan-convergence">
+      <h3>Plan Convergence</h3>
+      <p>Status: <span data-h2-bind="board.plan-convergence.status">-</span></p>
+    </section>
+  </h2-view>
+</h2-workflow>