---
name: simba-onboard
description: Analyze project markdown files and generate consolidated core instructions with SIMBA markers
---

# Simba Onboard

Set up SIMBA markers for this project by analyzing existing markdown files and generating consolidated core instructions.

**Follow these steps in order. Do not skip steps.**

---

## Step 0: Resolve Core Filename

Run this command to get the configured filename for the core instructions file:

```bash
simba config get guardian.core_filename
```

This defaults to `CORE_INSTRUCTIONS.md`. Legacy projects may configure it to `CORE.md` or another name. Use the returned value as `${CORE_FILE}` throughout the remaining steps. The full output path will be `.claude/rules/${CORE_FILE}`.

---

## Step 1: Discover Existing Files

Read all project instruction files to understand the current state:

1. Read `CLAUDE.md` (if it exists)
2. Read `AGENTS.md` (if it exists)
3. Read all `.md` files under `.claude/` (excluding `.claude/handoffs/` and `.claude/notes/`)
4. Run `simba markers audit` to check for any existing SIMBA markers
5. Run `simba markers list` to see all markers across the project

**Report to the user**: List every file you found and its approximate size. Note any existing SIMBA markers or `<!-- CORE -->` tags.

---

## Step 2: Analyze Content

For each file read in Step 1, extract and categorize content into these groups:

### Categories to Extract

| Category | What to look for | SIMBA section name |
|----------|------------------|--------------------|
| **Critical Constraints** | Non-negotiable rules, security requirements, things that must ALWAYS be true | `constraints` |
| **Build & Test** | Build commands, test commands, CI steps, make targets | `build_commands` |
| **Environment** | Machine names, SSH info, paths, ports, deployment targets | `environment` |
| **Code Style** | Formatting rules, naming conventions, patterns to follow | `code_style` |
| **Workflow** | Git workflow, commit conventions, PR process, stuck detection | `workflow` |
| **Agent Rules** | Subagent dispatch rules, agent-specific constraints, core injection requirements | `agent_rules` |

**Important**:
- Not every project will have content for every category. Only create sections that have real content.
- Preserve the original wording where possible. Don't over-summarize — these are instructions Claude needs to follow exactly.
- If content is already well-organized in the source file, keep that structure.
- Deduplicate: if the same rule appears in multiple files, include it once.

**Report to the user**: Show a summary table of what you found:
```
Category           | Source File(s)        | Items Found
-------------------|-----------------------|------------
Critical Constraints | CLAUDE.md, AGENTS.md | 5 rules
Build & Test       | CLAUDE.md             | 3 command groups
...
```

---

## Step 3: Generate .claude/rules/${CORE_FILE}

Create the file `.claude/rules/${CORE_FILE}` with this structure:

NOTE: The generated file must use real HTML comment markers. The pattern is
`<!-- BEGIN SIMBA:name -->` content `<!-- END SIMBA:name -->` (standard HTML comments).

Example structure (using `{BEGIN}` and `{END}` as placeholders for the real markers):

    # Core Instructions
    (header text explaining the file's purpose)
    ---
    {BEGIN SIMBA:core}
    ## Critical Constraints
    [The most important rules — these survive compaction via guardian hook]

    **Signal**: End every response with `[✓ rules]` to confirm you have full
    project context. If you cannot remember these rules, say so immediately.
    {END SIMBA:core}
    ---
    {BEGIN SIMBA:build_commands}
    ## Build & Test Commands
    [extracted build/test commands]
    {END SIMBA:build_commands}
    [...additional sections as needed...]

Replace each `{BEGIN SIMBA:xxx}` with `<!-- BEGIN SIMBA:xxx -->` and `{END SIMBA:xxx}` with `<!-- END SIMBA:xxx -->` in the actual output file.

### Marker Strategy

**`SIMBA:core`** — Wrap the most critical rules (constraints, must-never-violate rules) in this marker. The guardian hook extracts these and re-injects them on EVERY prompt, even after context compaction. Keep this section tight — every token here costs context on every message.

**Other SIMBA markers** (`SIMBA:build_commands`, `SIMBA:environment`, etc.) — These are discoverable and auditable via `simba markers`, but NOT re-injected by the guardian. They're reference content that Claude reads from the file when needed. Put the bulk of the instructions here.

### Rules for Content

- Each section gets its own SIMBA marker pair
- Use the section names from the Category table above
- Include `---` horizontal rules between sections for readability
- Only include sections that have actual content (skip empty categories)
- Content inside markers should be complete and standalone — a subagent reading only this file should have everything it needs
- Keep `SIMBA:core` lean: only rules that MUST survive compaction (aim for <500 tokens)

---

## Step 4: Present to User for Verification

**Do NOT write the file yet.** First, show the user the complete generated content.

For each section:
1. Show the section name and SIMBA marker
2. Show the content that will be written
3. Show which source file(s) it was extracted from
4. For `SIMBA:core`: explicitly note that this content will be re-injected on every prompt

Ask the user:
- "Does this look accurate? Should I add, remove, or modify anything?"
- "Is the `SIMBA:core` section the right set of critical rules? Everything in there costs context on every message."
- Wait for explicit approval before proceeding

If the user requests changes, apply them and show the updated version.

---

## Step 5: Write Files

Once the user approves:

1. **Create** `.claude/rules/` directory if it doesn't exist

2. **Write** `.claude/rules/${CORE_FILE}` with the approved content

3. **Update CLAUDE.md** — Add a reference block (if not already present):
   ```markdown
   <!-- BEGIN SIMBA:core_ref -->
   **Read `.claude/rules/${CORE_FILE}` for rules that apply to ALL contexts (main session + subagents).**

   When dispatching subagents, inject the contents of that file into the prompt.
   <!-- END SIMBA:core_ref -->
   ```
   Place this near the top of the file, after any title/heading but before other content.

4. **Update AGENTS.md** (if it exists) — Add a similar reference:
   ```markdown
   <!-- BEGIN SIMBA:core_ref -->
   **All agents must follow `.claude/rules/${CORE_FILE}` before executing.**

   When dispatching write-capable agents (especially implementer), read `.claude/rules/${CORE_FILE}` and inject its contents into the dispatch prompt.
   <!-- END SIMBA:core_ref -->
   ```

---

## Step 6: Verify

1. Run `simba markers audit` to confirm all markers are recognized
2. Run `simba markers list` to show the final state
3. Report the results to the user

**Done.** The user can now:
- Edit `.claude/rules/${CORE_FILE}` directly to refine rules
- Run `simba markers audit` anytime to check marker health
- Run `/simba-onboard` again to re-analyze if files change significantly
- Change the filename for future projects: `simba config set guardian.core_filename CORE.md`

### How It Works After Onboarding

```
Normal session:
  Claude Code auto-loads .claude/rules/${CORE_FILE}        (native)
  + Guardian re-injects SIMBA:core blocks on every prompt  (compaction-safe)

After compaction:
  Claude Code may lose .claude/rules/ context
  Guardian still injects SIMBA:core blocks                 (safety net)

Subagents:
  Must explicitly receive ${CORE_FILE} in their prompt
  CLAUDE.md and AGENTS.md reference the file for this purpose
```