onboard

name	onboard
description	Use when starting fresh in an unfamiliar codebase and need rapid orientation. Scans structure and conventions; produces _CODEBASE_MAP.md with architecture, module graph, critical paths, entry points. Skip for specific Q&A (/geniro:investigate) or bug investigation (/geniro:debug).
context	main
model	inherit
allowed-tools	["Read","Write","Bash","Glob","Grep","Agent","AskUserQuestion"]
argument-hint	[optional: --focus area1,area2 --depth N]

Onboard: rapid codebase orientation

2-phase loop (Discover → Map). Generates a structured map that serves as a reference for the session.

Runtime portability. ${CLAUDE_PLUGIN_ROOT} is set by Claude Code. When it is unset (another Agent-Skills runtime, e.g. Cursor), resolve it before following any reference: the plugin root is the ancestor directory of this file containing .claude-plugin/plugin.json — substitute it for every ${CLAUDE_PLUGIN_ROOT} occurrence and export it as CLAUDE_PLUGIN_ROOT in every Bash call. Tool and hook substitutions for non-Claude-Code runtimes: ${CLAUDE_PLUGIN_ROOT}/skills/_shared/runtime-portability.md.

Arguments

• No arguments — full codebase scan; produces the 8-section _CODEBASE_MAP.md (default mode).
• --focus area1,area2,... — scope-limiter. Scans all, but concentrates the map output on focus areas; non-focus areas get summary-level coverage.
• --depth N — limit directory scanning to N levels deep. Useful for large monorepos where full traversal is too slow. Orthogonal to --focus (combine as needed).

Combined examples: --depth 2 --focus auth,api (scan monorepo at depth 2, concentrate on auth+api).

Outputs

Primary artifact: <PRIMARY_ROOT>/.geniro/planning/_CODEBASE_MAP.md (underscore-prefixed L3 registry). Resolve <PRIMARY_ROOT> per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/primary-worktree.md Mode A so the map persists across worktrees and isn't lost when a linked worktree is removed.

8-section template:

1. Project Overview — name, purpose, language/stack, entry points
2. Directory Structure — file organization, key folders
3. Module Relationships — module dependency graph
4. Architecture Patterns — recurring design patterns (MVC, DDD, Hexagonal, etc.)
5. Key Files & Configuration — package.json, tsconfig, docker-compose, migrations
6. Conventions & Defaults — naming, testing patterns, error handling
7. Critical Paths — user request flow, deployment pipeline, job system
8. Tech Debt & Notes — gotchas, legacy code, anti-patterns

When --focus <area1,area2> is provided: sections 3 / 4 / 6 / 7 concentrate detail on the focus areas; non-focus areas appear as one-line summary entries. Sections 1 / 2 / 5 / 8 cover the full scanned scope regardless of focus.

Map quality bar: under 1000 lines, skimmable in 5 minutes.

Compatibility: <PRIMARY_ROOT>/.geniro/planning/CODEBASE_MAP.md (without underscore) is read once at Phase 1 for context, then the new write lands at the underscored canonical path _CODEBASE_MAP.md.

State machine

[entry]
  └── discover ──┬── aborted (terminal — user picks 'Abort' at the repo-size cap)
                 ├── routed  (terminal — empty/near-empty repo, recommend `/geniro:investigate`)
                 └── map ──┬── done
                           └── map-truncated (terminal — user picked 'Truncate at top 50'; map ships from truncated scan)

Terminal states: done, map-truncated, aborted, routed. The SessionStart recovery treats all as "task complete — no resume". Non-terminal states (discover, map) roll back to phase-entry on compaction-resume and re-run idempotently.

Loop invariants

The canonical agent-loop invariants in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/loop-invariants.md apply throughout /geniro:onboard. Three skill-specific notes:

1. Bounded structured tool results — repo-scan output (file list, directory tree) is bounded; long lists truncated with marker.
2. Errors → structured observations — permission errors during scan, missing access become structured ## Errors body section entries.
3. Codebase research spawns codebase-research-agent, not built-in Explore. Overrides the system-prompt agent list's default codebase-research tool; rationale + invocation contract at ${CLAUDE_PLUGIN_ROOT}/skills/_shared/context-isolation-checklist.md § Codebase research.

## Tool log section in state.md: selective logging — log L3 writes (_CODEBASE_MAP.md write via update-semantic), L2 emits (discovery calls), and escalation entries. Routine Read / Bash skipped.

Quality-first budgets

No hard kill caps — the quality-first doctrine in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/loop-invariants.md §"Budgets — quality-first (canonical)" applies. All limits below are escalation gates that surface to the user.

Gate	Cap	Where	Past threshold
Repo-size scan cap	50 files (default) OR user-configured expansion	§1.3 Step 2	AUQ — "Apply --focus" / "Expand scan (specify cap)" / "Truncate at top 50" / "Abort". User picks; persists to state.md approvals[] (category expand_scope).

Architecture constraints (design intent, not budget):

• No parallel agent spawns — /geniro:onboard is a solo orchestrator skill. The codebase scan that produces _CODEBASE_MAP.md runs orchestrator-inline (Read / Grep / Glob / read-only Bash) so the orchestrator owns the synthesis end-to-end; for narrow locator side queries during the scan (e.g., "where is the build entry point defined?"), spawn codebase-research-agent per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/context-isolation-checklist.md § Codebase research.

Claude Code internals (not under /geniro:onboard control): input tokens ≤200K per turn → compaction; output tokens ≤8K per turn → soft truncation.

---

Phase 1 — Discover

State.md phase: discover. Low cost — a repo-size scan + Glob + initial Read of project entry files. Exits to Phase 2 only when scan is bounded and repo-size cap is respected.

1.1 Step 0 — Mode detect

Transient detect on entry — does not persist a state.md row:

$ARGUMENTS shape	Behavior
empty	Full codebase scan (default mode).
--focus <area>	Scope-limiter on the full 8-section template.
--depth N	Limit scanning to N levels.
Combined	Both flags supported.

1.2 Step 1 — Load custom instructions + past learnings

On Phase 1 entry:

1. Refresh custom instructions — load-custom-instructions(SKILL_SLUG: onboard, LOAD_TIER: pipeline, MODE: initial-load) per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-instructions.md § Echo contract. Loads global.md + onboard.md + code-style.md.
2. Refresh project snapshot — load-semantic per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-semantic.md default top-2 (_project.md + _CODEBASE_MAP.md). If _CODEBASE_MAP.md already exists, the previous map is loaded as context (informs incremental update strategy). CODEBASE_MAP.md (without underscore) is also read once for compatibility.
3. Query past learnings — query-learnings --tag onboard --scope global --limit 5 — route per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/query-learnings.md §"Memory backend override" (a declared ## Memory Backend block redirects this to its read tool; under mode: replace the local file is empty, so only the backend read recalls anything). Surfaces prior architectural decisions and gotchas relevant to the scan (matches the scope: global discovery entries this skill emits in §2.3).
4. Cross-layer conflict resolution — resolve-conflicts per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/resolve-conflicts.md (precedence: custom instructions > project snapshot > past learnings when layers disagree; halt with AUQ on hard conflict).

Echo lines are mandatory per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/load-custom-instructions.md § Echo contract.

1.3 Step 2 — Repo-size scan + ≤50-file cap

Avoid loading entire repositories — bounded scan ≤50 files default.

Procedure:

1. Top-level discovery — Glob("*") at repo root (pwd resolved via git rev-parse --show-toplevel). Read top-level structure markers: README.md, package.json / pyproject.toml / Cargo.toml / go.mod, .github/, src/.
2. Estimate scan size — find . -type f | wc -l (or platform equivalent) to count total files. When --depth N is set, bound traversal with find . -maxdepth N -type f and record scan_depth: N in state.md frontmatter so Phase 2 mapping honors the same bound. Skip standard ignores: node_modules, .git, dist/, build/, target/, .venv, vendor/, __pycache__.
3. Apply ≤50-file default cap:

• If total file count ≤50 OR --focus provided AND focus-glob hits ≤50: proceed unblocked.
• If total >50 AND no --focus: fire the repo-size scan cap AUQ — header "Repo-size cap":
• "Apply --focus " — user supplies focus areas; re-run scan with filter.
• "Expand scan (specify cap)" — user provides explicit cap (e.g. 200, 500). Persists to state.md approvals[] with category expand_scope.
• "Truncate at top 50" — proceeds with top 50 most-likely-relevant files. Terminal state on completion: map-truncated.
• "Abort" — terminal aborted.

Approvals-persistence: before firing the expand-scope AUQ, check state.md frontmatter approvals[] for a prior entry with category: expand_scope. If found, use prior picked (typical compaction-resume scenario). The state.md ## Persisted approvals section renders this.

Edge cases:

• Empty or near-empty repo (no source files found): terminal routed with suggestion "Repo appears empty. Use /geniro:investigate to clarify project state." Run the §2.5 cleanup before writing this terminal phase, as with every other terminal exit.
• Permission errors on key directories — log to ## Errors body section; note gaps in final map's ## Tech Debt & Notes.
• Very large repos (50,000+ files) — auto-applies --depth 2 AND fires the AUQ above; user picks; default to truncate.

1.4 Step 3 — Scan structure

After caps respected:

1. List directories and file counts within scope.
2. Identify language / framework / tools (from package.json / pyproject.toml / Cargo.toml / etc.).
3. Find package managers, config files, CI/CD definitions (.github/workflows/, .gitlab-ci.yml).
4. Spot large monorepos, multi-language projects.
5. Check for documentation (README, ADRs, wiki references).

State.md update: phase: discover → phase: map. ## Scope body section captures the scanned-file list + applied cap.

---

Phase 2 — Map

State.md phase: map. Builds _CODEBASE_MAP.md (underscore-prefixed) with the 8-section template + optional --focus concentration.

2.1 Compose the codebase map content

Canonical path: <PRIMARY_ROOT>/.geniro/planning/_CODEBASE_MAP.md. Resolve <PRIMARY_ROOT> per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/primary-worktree.md Mode A so the map persists across worktrees.

Compose the map content in-context using the 8-section template from §Outputs above — do not write it to disk yet. Apply --focus concentration per the rule in §Outputs (sections 3 / 4 / 6 / 7 concentrate on focus areas; 1 / 2 / 5 / 8 stay full-scope). §2.2 persists the composed content through the update-semantic helper.

2.2 Persist the codebase map via update-semantic

Persist the composed map through update-semantic per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/update-semantic.md — that helper IS the write mechanism, holding the .codebase-map.lock for an atomic lock-guarded write. Do NOT write _CODEBASE_MAP.md with the Write tool directly: .geniro/planning/_*.md is a guarded persistent path and a direct write trips the state-helper enforcement hook and double-writes the file.

The helper writes one line per call (append-only or single-line prefix replacement — never whole-file):

• First onboard (no prior map) — emit each composed map line with update-semantic --file codebase-map --append "<line>". Append creates the file if it is missing.
• Incremental re-run (prior map exists) — for a changed entry use update-semantic --file codebase-map --replace "<line-prefix>" "<new-line>" (matches the first line starting with <line-prefix>); for a new entry use --append "<line>".

On rc=11 (lock held by another writer) defer and retry at phase end per the helper's defer-and-retry pattern.

2.3 Emit discovery learning

After _CODEBASE_MAP.md write:

• emit-learning per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/emit-learning.md — emit a discovery type entry. Required ext.{area, insight}. Default trust verified (code-grounded). After a successful emit, echo Recorded learning: <summary> to the user, per that file's §"Caller contract".

source "${CLAUDE_PLUGIN_ROOT}/lib/emit-learning.sh"
emit_learning <<'EOF'
{
"producer": "/geniro:onboard",
"type": "discovery",
"tags": ["onboard", "architecture", "<language>"],
"scope": "global",
"trust": "verified",
"summary": "<one-line architectural pattern>",
"ext": {
"area": "<top-level area, e.g. 'services', 'hexagonal-ports'>",
"insight": "<2-3 sentence non-obvious finding from the scan>"
}
}
EOF

Trigger: emit on first successful onboarding of a new codebase OR major architectural shift detected (existing _CODEBASE_MAP.md content significantly diverges from previous version — heuristic: compare section counts / module-count delta / new top-level entries). Skip when re-running onboard against a stable codebase (no architectural change).

2.3.5 Suggest improvements (inline)

After the discovery emit, before the printed next-steps block. Source candidates inline — no agent, since you just authored the map and there is no fresh diff to read — per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/improvement-routing.md §"Reflection-agent feed" (inline path) + §Routing table. Onboarding most often surfaces build/test/lint commands or tech-stack facts that belong in CLAUDE.md, occasionally a directory-scoped convention for .claude/rules/. Apply the §Candidate bar in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/improvement-routing.md (four gates + significance floor + cap) to every draft — on a fresh onboard most candidates are build/test commands and stack facts: discovery-derived per the bar's Evidence gate (the just-authored map section plus the dedup grep is their evidence), passing the bar as general; a re-run against an already-documented codebase typically yields none. Present surviving candidates via §Presentation, hand instruction-scoped rules to /geniro:instructions create, and echo Reviewed for improvements: <N> candidate(s) even at zero — only the prompt is skipped when none. Declines log via emit_rejection_if_signal (scope onboard/<area>, category improvement_candidate).

2.4 Print next steps

After the map ships, end the onboarding report with a printed "Next steps" block — suggestions only, no question:

### Next steps
- Run `/geniro:plan <idea>` to draft an approved spec for a feature against the new map.
- Run `/geniro:investigate <question>` to dig deeper into a subsystem.
- Run `/geniro:implement <task>` to design and build a change directly.
- Review `_FEATURES.md` (the manual feature backlog), or run `/geniro:plan` to author one.

2.5 Cleanup

Run this before EVERY terminal phase: write — done, map-truncated, routed, and aborted alike, not only the happy path. The migration walk scans .geniro/planning, never .geniro/state, so a slug directory left behind by an early exit has no later sweep and persists indefinitely.

State.md phase: map → done on the happy path. Per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/within-skill-state-handoff.md § Cleanup contract:

rm -rf .geniro/state/onboard/<slug>/ 2>/dev/null || true

Persistent artifacts STAY: _CODEBASE_MAP.md is T3 — never auto-deleted.

---

State file schema

Path: .geniro/state/onboard/<slug>/state.md (cwd-relative — within-skill resume-from-compaction state per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/primary-worktree.md § "Artifacts NOT in scope"; compute <slug> per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/within-skill-state-handoff.md § Slug rules).

Write via atomic_state_write per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/atomic-state-write.md:

source "${CLAUDE_PLUGIN_ROOT}/lib/atomic-state-write.sh"
atomic_state_write ".geniro/state/onboard/<slug>/state.md" <<EOF
---
tier: T1.5
producer: onboard
schema-version: 1
branch: <git-branch>
timestamp: <ISO-8601 UTC>
phase: <discover|map|done|map-truncated|aborted|routed>
status: <in-progress|done|failed>
non-resumable-actions: []
approvals: []
geniro_kind: onboard-state
geniro_schema_version: m9-v1
task_slug: <slug>
worktree: <abs-path>
focus_areas: []
scan_cap: 50
scan_depth: <N|null>
---

## Scope
<files / symbols / top-level dirs scanned; applied cap; --focus areas if any>

## Codebase Map Draft
<incremental scan results before final _CODEBASE_MAP.md write>

## Tool log
<selective logging — L3 writes, L2 emits, escalation entries>

## Errors
<permission errors, tool failures>

## Open Questions
<missing access AUQs>

## Termination reason
<— only on terminal aborted/routed states; >

## Persisted approvals
<render of frontmatter approvals[] (category: expand_scope)>
EOF

approvals[] populated when the expand-scope AUQ fires at §1.3 Step 2 (category expand_scope).

Validate before resume via validate_state_file per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/validate-state-file.md.

---

ACI per-phase tool surface

Mirrors the /geniro:implement ACI surface — read-only Phase 1, helper-mediated writes Phase 2.

Phase 1 (Discover):

• Allowed: Read / Grep / Glob / Bash (read-only commands: git status, find . -type f, wc -l) / AskUserQuestion (the §1.3 repo-size-cap expansion gate).
• Explicitly blocked: production-source Edit/Write, git add / git commit / git push. Agent spawns limited to codebase-research-agent for narrow locator side queries during the scan (no parallel agent spawns — /geniro:onboard is a solo orchestrator skill).

Phase 2 (Map):

• Allowed: Read / update-semantic (the lock-guarded write mechanism for _CODEBASE_MAP.md) / emit-learning helper invocations / AskUserQuestion (the §2.3.5 improvement-candidate presentation) / Bash (atomic_state_write for state transitions; the §2.5 cleanup of the run's scratch state).
• Explicitly blocked: direct Write/Edit to _CODEBASE_MAP.md (route through update-semantic — .geniro/planning/_*.md is a guarded persistent path), production-source Edit/Write, git add / git commit / git push.

Existing safety hooks apply across all phases (file-protection / git-guardrail / .geniro/ deletion guard).

---

_CODEBASE_MAP.md format example

Full 8-section worked example (sample TypeScript/Express project) in ${CLAUDE_PLUGIN_ROOT}/skills/onboard/onboard-reference.md §1. The 8-section template in §Outputs is the operative spec; the example illustrates the rendering.

---

Definition of done

These are the load-bearing exit gates — the invariants that, if skipped, make the onboarding incomplete or unsafe. The 8-section map content is enforced by the §2 template, not re-listed here.

• _CODEBASE_MAP.md created at <PRIMARY_ROOT>/.geniro/planning/_CODEBASE_MAP.md per ${CLAUDE_PLUGIN_ROOT}/skills/_shared/primary-worktree.md
• At least 3 critical paths traced and documented
• Map is <1000 lines and skimmable in 5 minutes (use --focus for large repos)
• L3 _CODEBASE_MAP.md updated via update-semantic
• L2 discovery emit fired per trigger conditions
• Next-steps suggestions printed at the end of the report (per §2.4)
• State.md cleaned up per §2.5

---

Examples

Three worked invocation examples (monorepo focus scan / returning-after-months refresh / feature-planning focus) in ${CLAUDE_PLUGIN_ROOT}/skills/onboard/onboard-reference.md §2.

---

Anti-rationalization

Your reasoning	Why it's wrong
"Let me document every file"	Exhaustive maps are unreadable. Sample key files, focus on structure and relationships.
"I need more detail on this module"	The codebase map captures architecture, not implementation. Keep it under 1000 lines.
"The code is self-documenting"	Code shows what, not why. Note the critical paths (user flow, deploy flow) and what's unclear.
"I'll create the map and move on"	A map nobody references is waste. Update it as you learn more, reference it when planning.
"The repo has 5000 files but I'll just scan everything — better safe than sorry."	Mass-scan violates the bounded-scan contract. The ≤50-file default cap exists for tokens + speed. Fire the AUQ — user picks --focus, expansion, or truncation. Don't silently broad-scan.
"Quick mode would be nice here — I'll informally produce a focus-only output."	There is no quick mode. The single-mode flow + --focus scope-limiter covers all legitimate needs. Inventing a quick-mode bypass mid-run breaks the single-mode contract.
"Add a wall-time kill cap so long-running discovery aborts cleanly."	Hard caps abort legitimate complex discovery mid-stride. Quality-first — no hard caps. The ≤50-file gate escalates to the user via AUQ. User has agency.
"/geniro:onboard scan should bypass the 50-file cap silently if the codebase is monorepo-scale."	The cap is explicit — ≤50 default; user-confirmable expansion. Silent bypass defeats the cost-control intent.
"Defer compaction-survival to downstream skills — /geniro:onboard is mostly scan."	The contract IS /geniro:onboard's contract — state.md frontmatter, approvals[], ## Tool log, ## Errors, ## Open Questions. Without them, compaction mid-scan loses scan progress; user re-runs from scratch.
"Audit trail isn't needed for local /geniro:onboard runs — the map IS the record."	The map captures architecture; the state.md ## Tool log captures the scan process (which directories scanned, permissions errors, time taken). Without the log, debugging a failed onboard is impossible. The SessionStart hook re-injects on compaction; without the log, post-mortem requires re-running the scan from scratch.