IronClaw Reborn Orientation

The corrected map, verified against HEAD on 2026-07-02 by a full architecture audit. The repo's own docs drift; when this skill and a doc disagree, re-verify with the greps given here.

Where things go

• All new features: Reborn, in crates/ — never src/ (v1 monolith, being strangled; nothing depends on it). Binary and package: ironclaw, built from crates/ironclaw_reborn_cli (root docs sometimes say "reborn_cli"). For any endpoint/facade/capability work, use the reborn-feature skill.
• The canonical request flow: Vite browser code (crates/ironclaw_webui/frontend) → route descriptor and handler (ironclaw_webui) → ProductSurface / BoundProductSurface (ironclaw_host_api) → product views and capability descriptors (ironclaw_product) → composition-backed services. Turn execution: SessionThreadService (threads) → TurnCoordinator (turns) → TurnRunScheduler (runner) claims → RebornTurnRunExecutor (runner) → PlannedDriver → CanonicalAgentLoopExecutor (agent_loop) → host ports (loop_host) → CapabilityHost (capabilities) → dispatcher → runtime lanes. Boot: commands/serve.rs → build_reborn_runtime → webui_v2_app.
• Current runner/lease names: turn claims and execution use TurnRunScheduler + RebornTurnRunExecutor; expired lease is terminal Failed{lease_expired} (RecoveryRequired is a legacy status).
• Host-side product code (serve/delivery/setup for a channel): the model is ironclaw_webui for WebChat. Do not default it into ironclaw_reborn_composition — that crate is for assembly.
• New prompt templates: a .md file inside the owning Reborn crate, loaded via include_str! (pattern: crates/ironclaw_loop_host, crates/ironclaw_turns, crates/ironclaw_skill_learning prompt files). crates/ironclaw_engine/prompts/ is the v1 engine's directory — root CLAUDE.md still points there; don't follow it for new Reborn work.

The legacy enclave (easy to mistake for current architecture)

Five crates in crates/ serve only the v1 monolith: ironclaw_engine (a complete second agent loop — boundary tests forbid Reborn crates from using it), ironclaw_tui, ironclaw_gateway, ironclaw_oauth, ironclaw_embeddings. Verify any crate's status before building on it: python3 -c ... is overkill — just check who depends on it: grep -rl "<crate_name>" crates/*/Cargo.toml Cargo.toml. If the only consumer is the root package, it's v1-only.

Discovery procedure (graph may be absent — don't stall)

1. bash scripts/codebase-graph.sh status — once. If FRESH and the codebase-memory MCP tools are available, use graph recipes (CLAUDE.md).
2. If MISSING/stale or the MCP isn't connected (common): fall back immediately — the flow map above + crates/AGENTS.md routing table + targeted grep. Note the fallback in your report; do not retry the graph.
3. Per-crate guidance: read the crate's AGENTS.md/CLAUDE.md first; when absent, fall back to CONTRACT.md/README.md, Cargo.toml, and the primary src/ entrypoint. Treat the crates/AGENTS.md map as a routing aid, not proof that an omitted crate is irrelevant.
4. openwiki/ is generated narrative — read for what/why, never edit (regenerated by CI).

Two skill systems (do not conflate)

.claude/skills/ = developer workflow (this skill). Top-level skills/ = product runtime skills compiled into the shipping binaries. Editing skills/ changes the product. See ironclaw-reborn-skill-maintainer before touching either.

Sibling skills

reborn-feature (build a feature) · ironclaw-reborn-architecture-review (boundaries/abstractions) · ironclaw-reborn-testing (tiers/harness) · ironclaw-reborn-skill-maintainer (guidance hygiene).