# Ironclaw Reborn Orientation

> Use when starting work in the IronClaw repo, deciding where a feature/fix/prompt/doc belongs, tracing how a request flows, looking up which crate owns a subsystem, or when repo docs, the knowledge graph, or component names seem stale, missing, or contradictory.

- Skill: `nearai/ironclaw-reborn-orientation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add nearai/ironclaw-reborn-orientation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nearai/ironclaw-reborn-orientation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: nearai (https://skillmd.com/u/nearai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/nearai/ironclaw-reborn-orientation

---


# 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/`** — which is now the whole tree, grouped into ten family directories (`app`, `contracts`, `domains`, `events`, `extensions`, `kernel`, `lanes`, `loop`, `product`, `substrates`). The v1 `src/` monolith and its crates (`ironclaw_engine`, `ironclaw_tui`, `ironclaw_gateway`, `ironclaw_oauth`) have been **deleted**; if a doc still routes you to them, that doc is drift. Binary and package: **`ironclaw`**, built from `crates/app/ironclaw_cli` (pre-rename docs may say "reborn_cli"). For any endpoint/facade/capability work, use the `reborn-feature` skill.
- **The canonical request flow**: Vite browser code (`crates/product/ironclaw_webui/frontend`) → route descriptor and handler (`ironclaw_webui`) → `ProductSurface` / `BoundProductSurface` (`ironclaw_product_contracts`) → product views and capability descriptors (`ironclaw_assistant`) → composition-backed services. Turn execution: `SessionThreadService` (threads) → `TurnCoordinator` (turns) → **`TurnRunScheduler`** (`turn_runner`) claims → **`RebornTurnRunExecutor`** (`turn_runner`) → `PlannedDriver` → `CanonicalAgentLoopExecutor` (`agent_loop`) → host ports (`loop_host`) → `CapabilityHost` (capabilities) → dispatcher → runtime lanes. Boot: `commands/serve.rs` → `build_reborn_runtime` → `webui_v2_app_with_lifecycle`.
- **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_composition` — that crate is for assembly.
- **New prompt templates**: a `.md` file inside the **owning Reborn crate**, loaded via `include_str!` (the crates that own prompt files today: `ls -d crates/*/*/prompts crates/extensions/packages/*/prompts` → `host_api`, `loop_contracts`, `skills`, `agent_loop`, `loop_host`, `assistant`, plus per-extension packages).
- **New internal engineering docs** (design notes, research, plans, QA maps): `docs/internal/` — the only growing internal home under `docs/`. The rest of `docs/` is the public Mintlify site; a page missing from `docs.json` navigation is still published (hidden pages stay URL-reachable), and the `docs/.mintignore` fence is frozen — never add entries. Verify placement: `python3 scripts/ci/docs_publication_boundary.py`.

## There is no legacy enclave any more

Older guidance (including earlier versions of this skill) told you to avoid a "v1-only enclave" of `ironclaw_engine` / `ironclaw_tui` / `ironclaw_gateway` / `ironclaw_oauth`. **Those crates no longer exist**, and neither does the root `src/` monolith or its `ironclaw_legacy` package. Every crate under `crates/` is Reborn. If you hit a doc, comment, or skill that still names one of them, treat it as drift and re-verify rather than routing around a crate that isn't there. To check any crate's real consumers: `grep -rl --include=Cargo.toml "<crate_name>" crates/ Cargo.toml` (the family layout means `crates/*/Cargo.toml` no longer matches any crate manifest).

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

1. `bash scripts/codebase-graph.sh status` — **once**. If FRESH and the `codebase-memory-mcp` 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 `.claude/rules/guidance-maintenance.md` before touching either.

## Sibling skills

`reborn-feature` (build a feature) · `ironclaw-reborn-architecture-review` (boundaries/abstractions) · `ironclaw-reborn-testing` (tiers/harness) · `.claude/rules/guidance-maintenance.md` (guidance hygiene, auto-loads on `.claude/**`/`AGENTS.md`/`CLAUDE.md`/`skills/**`).