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.