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.
Install with the open skills CLI (global, non-interactive — available in every Claude Code session):
npx skills add nearai/ironclaw --skill "ironclaw-reborn-orientation" -g -a claude-code -yOr manually — copy the SKILL.md below into:
~/.claude/skills/ironclaw-reborn-orientation/SKILL.md---
name: ironclaw-reborn-orientation
description: 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.
---
# 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: **`ironclaw-reborn`**, 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** (memorize; saves ~25 tool calls of rediscovery): browser JS (`webui_v2_static`) → route+handler (`webui_v2`) → `RebornServicesApi` facade (`product_workflow`) → port impl (`reborn_composition`) → substrates. 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` → `build_webui_services`.
- **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_reborn_webui_ingress` (WebChat's host side). Do **not** default it into `ironclaw_reborn_composition` — that crate is for assembly, and existing Slack/auth host code there is debt, not precedent.
- **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).
You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.
Use when you have a written implementation plan to execute in a separate session with review checkpoints
Use when executing implementation plans with independent tasks in the current session