Repo Claude Code onboarding

How to bring a repo onto Claude Code and the HCS orchestration system. This is the per-repo setup guide — the identity and secrets phases (AB#21–23) are covered separately in onboarding/index.md.

---

Choose your setup tier

Tier	When to use	What you deploy
Standard	Most repos — single engineer, ad-hoc work	CLAUDE.md + one engineer agent + hooks
Workstream pipeline	Complex repos — debugging, infra ops, multi-step feature work	Standard + 9 agents + 8 commands + 9 skills

If you are unsure, start with Standard. The pipeline can be added later without touching the Standard files.

---

Standard setup

1. Copy and fill CLAUDE.md

Copy-Item D:\git\platform\templates\CLAUDE.md.template <repo-root>\CLAUDE.md

Open the file and replace every :

Placeholder	Value
	Repo name as it appears in the GitHub/ADO URL
	1–3 sentences: what it does, why it exists, what it is not
	ADO project name (e.g. Platform Engineering)
	Area path (e.g. Platform Engineering\Tooling)
	PowerShell 7, TypeScript, Bicep, etc.
	How to build/serve/test this repo
	<repo-short-name>-engineer
	Your name
	Your email

Do not leave any in the committed file — that is a defect.

2. Create the .claude/ folder structure

$repo = "<repo-root>"
New-Item -ItemType Directory -Force "$repo\.claude\agents"
New-Item -ItemType Directory -Force "$repo\.claude\hooks"
New-Item -ItemType Directory -Force "$repo\.claude\logs"

3. Deploy settings.json

Copy-Item D:\git\platform\templates\claude\settings.json.template "$repo\.claude\settings.json"

Open it and replace <REPO_NAME> with the repo's short name in all hook paths.

4. Deploy hooks

Copy-Item D:\git\platform\templates\claude\hooks\* "$repo\.claude\hooks\"

5. Create log stubs

New-Item -ItemType File "$repo\.claude\logs\sessions.jsonl" -Force
New-Item -ItemType File "$repo\.claude\logs\tokens.jsonl" -Force

Both files are gitignored by the template .gitignore.

6. Create the engineer agent

Copy-Item D:\git\platform\templates\claude\agent.md.template "$repo\.claude\agents\<repo-short-name>-engineer.md"

Edit the file:

• Set name: to <repo-short-name>-engineer
• Write a specific description: — this is what Claude Code shows when spawning the agent
• Set model: sonnet (use haiku only for read-only lookup agents)
• List only the tools the agent actually needs
• Write the system prompt: what the repo is, what the agent knows, hard constraints

7. Add to .gitignore

Ensure these are in the repo's .gitignore:

.claude/logs/
.claude/settings.local.json

8. Register in master-registry.db

Add a row to D:\git\platform\master-registry.db:

- name: <repo-name>
  platform: github          # github | gitlab | ado
  local_path: D:\git\<path>
  type: <type>              # iac-terraform | iac-bicep | iac-arm | iac-ansible | iac-powershell | docs | web | app
  validation_profile: <type>
  default_branch: main
  pilot: false

If you are not sure of the type, set type: ? — the orchestration-pm will skip it until classified.

9. Commit

git add CLAUDE.md .claude/
git commit -m "feat(claude): add Claude Code scaffold"

---

Workstream pipeline setup

Do this after the Standard setup is complete.

1. Deploy the 9 pipeline agents

$prefix = "<repo-short-name>"
$src    = "D:\git\platform\templates\claude\agents"
$dst    = "<repo-root>\.claude\agents"

foreach ($f in Get-ChildItem "$src\*.md") {
    Copy-Item $f.FullName "$dst\$prefix-$($f.Name)"
}

Open each agent file. Normalize any claude-opus-4-* or claude-sonnet-4-* pinned model IDs to opus or sonnet.

2. Deploy the 8 commands

Copy-Item D:\git\platform\templates\claude\commands\* "<repo-root>\.claude\commands\"

3. Deploy the 9 skills

Copy-Item -Recurse D:\git\platform\templates\claude\skills\* "<repo-root>\.claude\skills\"

4. Add the operate log stub

New-Item -ItemType File "<repo-root>\.claude\logs\operate.jsonl" -Force

5. Update CLAUDE.md

Add these sections to the repo CLAUDE.md (see templates/CLAUDE.md.template for the full example):

Slash Commands — table of /build, /refactor, /test, /document, /investigate, /operate, /route, /review

Agents in this repo — table of all 9 agents with their model and role

Hooks — table of all 6 hooks with their event and action

6. Commit

git add .claude/ CLAUDE.md
git commit -m "feat(claude): add workstream pipeline"

---

Verify with a dry-run

From the platform repo, confirm the orchestration system can see the new repo:

/dispatch --dry-run <repo-name>

This resolves the repo from master-registry.db, loads its validation profile, and constructs a wave plan — without running any validators.

---

Subagents stanza for CLAUDE.md

Add this at the end of the repo's CLAUDE.md so Claude Code knows what agents are available:

## Subagents available in this repo

- `<repo-name>-engineer` (model: sonnet) — <one-line purpose>

User-level agents (every repo): triage-lookup, markdown-prose-editor, azurelocal-domain-expert,
mkdocs-material-doctor, turner-module-scaffold-engineer, mms-2026-demo-presenter.

Platform repo agents (when working in D:\git\platform): orchestration-pm, security-waf-caf,
terraform-validator, bicep-validator, arm-validator, ansible-linter, powershell-linter,
reviewer, security-reviewer, documenter, coder, planner, operator, investigator,
test-writer, router.

---

Quick reference

File	Template source
CLAUDE.md	templates/CLAUDE.md.template
.claude/settings.json	templates/claude/settings.json.template
.claude/agents/<name>-engineer.md	templates/claude/agent.md.template
.claude/agents/<name>-*.md (pipeline)	templates/claude/agents/
.claude/commands/*.md	templates/claude/commands/
.claude/skills/*/SKILL.md	templates/claude/skills/
.claude/hooks/*.ps1	templates/claude/hooks/