orchestration-onboard

name	orchestration-onboard
description	Set up the current repository for the orchestrator-worker workflow - project CLAUDE.md, path-scoped rules, continuity directories, and permission settings - by reading the codebase first and proposing a plan before writing anything.
disable-model-invocation	true
argument-hint	[path to the standing-orders repo, if not ~/dev/claude-standing-orders]

Onboard this repository

Set up the repository in the current working directory for the orchestrator–worker workflow. Template files live in the standing-orders repo — use $ARGUMENTS as its path if given, otherwise try ~/dev/claude-standing-orders, and ask if neither exists.

Write nothing until step 4 is approved. This skill produces a plan first.

1. Read the repository

Use the Explore subagent so this does not fill the main context. Establish:

• language, framework, and how the source tree is laid out
• the real build, test, lint, and format commands — from the Makefile, package.json scripts, pyproject.toml, justfile, or CI config, not from convention
• where migrations, models or schemas, background jobs, and request handlers live
• whether a CLAUDE.md, AGENTS.md, .cursorrules, or .github/copilot-instructions.md already exists, and what it says
• whether docs/changelogs/, docs/decisions/, docs/adr/, or an equivalent exists
• what this system does and what breaks if it is wrong — the risk profile

2. Interview me for what the code cannot tell you

The operating-constraints section is the highest-value part of the file and the one you cannot infer. Ask me — in one batch, not one at a time — only about what you could not determine from the code:

• traffic shape: peak versus average, what spikes and when
• which paths have a user actively waiting, and which do not
• hard external limits: rate limits, quotas, third-party throttling
• which tables or collections grow without bound
• compliance or audit obligations, if any
• what a new engineer gets wrong in their first week

If I answer "not applicable" to something, drop that item rather than writing a hedge.

3. Map the templates onto this repository

From <orchestrator>/project-template/:

• CLAUDE.md — fill every FILL marker from steps 1 and 2. Delete the guidance comments. Delete any non-negotiable that is not true here; a rule that is present but untrue teaches me to ignore the file. Keep it under ~150 lines.
• rules/*.md — rewrite each paths: list to match this repository's actual layout, verifying each glob matches real files. Delete rules that do not apply. Add a rule only if this project has a standard the templates do not cover.
• settings.json — merge into any existing .claude/settings.json rather than replacing it. Add ask entries for the destructive commands specific to this project: migrations, deploys, data backfills, anything that touches production.

If a rule file would end up with fewer than three applicable rules, fold it into CLAUDE.md instead. Do not ship near-empty files.

4. Show me the plan

Present, before writing anything:

• the CLAUDE.md you propose, in full
• for each rule file: its paths globs, a count of files each glob matches, and which rules you kept, changed, or dropped
• a diff against any existing CLAUDE.md, and what would be lost
• the directories and files you would create
• anything from step 2 you are still unsure about

Then stop and wait for my approval.

5. Apply

On approval:

1. Write CLAUDE.md and .claude/rules/*.md. If the repository already has an AGENTS.md, do not duplicate it: Claude Code reads CLAUDE.md and not AGENTS.md, so write a CLAUDE.md whose first line is @AGENTS.md and put only the Claude-specific additions below that import. One file stays authoritative and both tools read the same instructions. Never maintain the same content in both.
2. Merge .claude/settings.json.
3. Create the continuity directories if missing: a changelog directory and a decision log. If this repository already uses a non-default convention — docs/adr/, a root DECISIONS.md, a changelogs/ directory — keep it and write .claude/continuity.json pointing at it rather than creating a second convention:

   { "changelogDir": "docs/changelogs", "decisionFile": "docs/decisions/DECISIONS.md" }
   

   Add this project's test and lint commands to the same file as "verifyCommands": ["make test", "make lint"], using the real commands from step 1. This is what activates the verification reminder; without the key that hook stays silent, so a project that skips this simply keeps today's behavior.
4. Seed the decision log with the standing decisions you found in step 1 that already constrain future work — the choices that are load-bearing but written down nowhere. Three or four lines each: decision, why, what it rules out.
5. Add .claude/settings.local.json and .claude/worker-ledger.jsonl to .gitignore. Leave .claude/agent-memory/ tracked.
6. Write a changelog entry for the onboarding itself.

6. Verify and report

Confirm with /context that the project CLAUDE.md loaded. Path-scoped rules will not appear until a matching file is read — read one file per rule to prove each glob fires, and report any that did not.

Report as a table: files created, files modified, rules dropped and why, and anything I still need to fill in myself.