Ult Onboarding Index

---
name: onboarding-index
description: Discover CEP-managed content already present in a target repo (What/How layer docs, compiled guidelines, context packages, decision ledger) via existence checks against layout-slots-registry.yaml-resolved paths, then write one canonical root AGENTS.md onboarding index plus thin per-tool pointer stubs (.github/copilot-instructions.md, CLAUDE.md, .cursor/rules/onboarding.mdc) that link into it. All writes are marked-block or existence-gated and non-destructive, including install.sh's own AGENTS.md skill-catalog block. Codex needs no separate stub -- root AGENTS.md is already its native onboarding format. Do NOT use it to generate the CEP content itself (ult-autoscaffold-content/compiling-project-guidelines do that) or to resolve layer paths (ult-repo-layout does that). Do NOT confuse it with this OSS repo's own AGENTS.md (generated by catalog/export_adapters.py) -- this skill only ever writes into a separate target repo being onboarded with CEP.
namespace: ult
version: 0.6.0
origin: ground-up
author: Pranay Mishra
maintainer: Pranay Mishra
adapted_from: ~
upstream_version: ~
released: 2026-08-21
tags: [developer, onboarding, documentation, multi-tool, index]
bundle: utilities
tier: draft
---

# ult-onboarding-index

## Overview

`ult-repo-layout` resolves *where* CEP content lives. `ult-autoscaffold-content`
and `compiling-project-guidelines` make sure real content exists at those
resolved paths. Neither of them assembles a single entry point into all of
it, and neither speaks the native onboarding dialect of each coding tool
(Copilot, Claude Code, Cursor, Codex). `ult-autoscaffold-content/SKILL.md`
names this gap explicitly, in its "What this skill deliberately does not do"
section:

> Does not author Copilot/Claude/Cursor/Codex-specific instruction files or
> a root multi-tool onboarding index. That's a distinct, deferred concern —
> this skill's own output is tool-agnostic CEP content, consumed the same
> way regardless of which agent reads it.

This skill is that concern. It discovers what CEP-managed content already
exists in the target repo, then writes one canonical root `AGENTS.md`
plus thin per-tool pointer stubs that link into it — so a first-time user
of any of the four tools finds the same onboarding trail regardless of
which one they open first.

**This is not this OSS repo's own root `AGENTS.md`.** This repo's
`AGENTS.md` is generated by `catalog/export_adapters.py`'s
`render_agents_md()` — a table of *this library's own skill catalog*. This
skill never touches that file. It runs *inside a separate target repo*
that has installed and is using CEP, and writes an `AGENTS.md` there
describing *that repo's* CEP content — a different document, in a
different repo, produced by a different mechanism. If you are looking at
this skill from inside `context-engineering-protocol` itself, it does
nothing here; it only acts on the repo it's invoked against.

**Codex gets no separate pointer file.** Root `AGENTS.md` is already
Codex's native onboarding format (this repo's own `README.md` documents
Codex Desktop reading it unprompted). Writing a Codex-specific stub file
would be redundant machinery with no consumer, so the per-tool pointer set
below covers three tools, not four.

## Step 1 — Confirm CEP is present

This skill only makes sense against a repo that has already run
`ult-repo-layout` and has a `context-config.yaml`. If `context-config.yaml`
is absent, stop and say so — do not guess a layout. This mirrors
`ult-autoscaffold-content`'s own Step 2 posture toward `ult-repo-layout`: a
one-way dependency, never worked around.

## Step 2 — Discover

Read `references/slot-discovery.md` for the full list of what to
existence-check and how each path resolves. In short: resolve each
registered slot's path from `context-config.yaml` (falling back to its
`workspace_root_leaf` default per `layout-slots-registry.yaml` when the
project hasn't overridden it — the same resolution `ult-repo-layout`
performs), then check whether something real is actually there. Also
resolve and glob `how_dimension.how_l2.path` directly — it's a config key,
not a registered slot, resolved the exact same way
`compiling-project-guidelines` Step 1 already does it.

Build a slot → resolved path → present/absent table before moving on. Check
the `outputs`-bucket slots (`plans_output`, `brainstorm_output`,
`user_stories_output`, `security_docs`, `security_report`,
`project_plan_docs`) too, even though they'll typically resolve "absent"
today — see `references/slot-discovery.md` for why.

Once you have the table, run:

```
python .github/skills/ult-onboarding-index/scripts/onboarding_index.py \
  discover --repo-root <target-repo-root> --slots-json <path-to-your-table.json>
```

`<path-to-your-table.json>` is a JSON object you write yourself, mapping
each slot id to the path you resolved it to (see
`references/slot-discovery.md` for the exact id list). The script does not
resolve `context-config.yaml` itself — that resolution is judgment-free
enough that duplicating it in Python would only be a second place for the
logic to drift from `ult-repo-layout`'s own. It does the mechanical part:
confirms each given path's existence, and globs the How-L2 directory's
known filenames (`CODING-STANDARDS.md`, `TESTING-GUIDELINES.md`,
`interfaces/*.md`, per-module `CONTEXT.md`) if you pass `--how-l2-path`.

## Step 3 — Render the AGENTS.md block

Fill `templates/agents-md-block-template.md` using only the slots that
existence-checked `true`. Never list an artifact whose resolved path
doesn't actually exist — a link to nothing is worse than a shorter but
honest index. For `autoscaffold_content_index` (`CEP-INDEX.md`) and
`decision_ledger`, link to the file rather than re-stating or parsing its
contents — both are already routers/logs in their own right.

## Step 4 — Render per-tool pointer stubs

For each of Copilot, Claude, and Cursor, fill the matching template
(`templates/copilot-instructions-block-template.md`,
`templates/claude-md-block-template.md`,
`templates/cursor-onboarding-mdc-template.md`). Each one is a short pointer
only — "this repo uses CEP; the canonical onboarding index is at
`AGENTS.md`" — never a duplicate of AGENTS.md's own content.

## Step 5 — Write

Follow `references/marked-block-write-protocol.md` exactly. In short:

- `AGENTS.md`, `.github/copilot-instructions.md`, `CLAUDE.md` — each gets
  its own `<!-- BEGIN cep-onboarding-index ... -->` marked block, merged via:

  ```
  python .../scripts/onboarding_index.py merge-block <target-file> <block-content-file> \
    --begin-marker "<!-- BEGIN cep-onboarding-index (auto-generated by ult-onboarding-index, do not edit) -->" \
    --end-marker "<!-- END cep-onboarding-index -->"
  ```

  This never touches content outside its own marker pair — in particular,
  it never touches `install.sh`'s own skill-catalog block in `AGENTS.md`.
  See `references/marked-block-write-protocol.md` for why.

- `.cursor/rules/onboarding.mdc` — a whole new file, existence-gated:

  ```
  python .../scripts/onboarding_index.py write-stub <target-file> --content-file <rendered-file>
  ```

  If it already exists, this is a no-op — report that it was left alone,
  same as any other place this skill declines to overwrite real content.

## Step 6 — Report back

State, per target file: created / block updated / block appended to an
existing unmarked file / skipped (already existed). Then show the full
discovery table from Step 2 — slot, resolved path, present/absent — so the
user sees exactly what got linked and what didn't, and can tell at a glance
what to run next (`ult-autoscaffold-content`, `compiling-project-guidelines`,
etc.) to fill in what's still missing.

## What this skill deliberately does not do

- **Does not generate CEP content.** It only links to content that already
  exists. `ult-autoscaffold-content` writes starter What-L2/How-L2 docs;
  `compiling-project-guidelines` reconciles scattered guideline sources.
  Neither is this skill's job.
- **Does not resolve or discover layer paths.** That's `ult-repo-layout`.
  This skill reads `context-config.yaml` as already-resolved input, never
  as something to figure out on its own.
- **Does not touch this OSS repo's own `AGENTS.md`** (the skill-catalog
  table `catalog/export_adapters.py` generates). It only ever writes into
  a separate target repo being onboarded with CEP.
- **Does not add a wizard stub card.** `ult-cep-wizard`'s four boxes each
  correspond to an independently-resolvable `project_layout.slots`/layer
  entry; this skill's output is a downstream, cross-cutting artifact with
  no such entry of its own, so it doesn't fit that model. Noted for the
  wizard's own cleanup pass, not built here.