Repo settings — per-repo Claude Code configuration

Where this fits in the multi-model layout

The canonical per-repo instruction file is now AGENTS.md (read by Codex, Cursor, Copilot, and — via contextFileName — Gemini), with CLAUDE.md as a thin shim that imports it (@AGENTS.md) and adds Claude-only notes. The shared cross-tool memory lives in .ai/. This page documents the Claude-native .claude/ behaviour layer that sits alongside those files. For the full canonical repo layout and per-tool config matrix, see the agents standard and the AI workspace standard.

Every repo carries the canonical AGENTS.md + CLAUDE.md shim at the root and a .claude/ folder (the Claude Code behavior layer). All are committed. A settings.local.json in .claude/ is gitignored for machine-specific overrides.

Full repo-level structure

Standard repo (single engineer agent)

Most repos use this minimal structure:

<repo>/
├── AGENTS.md                       ← canonical cross-tool context (MCP-first + offline fallback)
├── CLAUDE.md                       ← shim: "@AGENTS.md" + Claude-only notes
├── .ai/                            ← shared state/ + memory/ + mcp/ (all tools read/update)
└── .claude/
    ├── agents/
    │   └── <repo-name>-engineer.md  ← repo-specific agent definition
    ├── hooks/
    │   ├── block-secrets.ps1        ← PreToolUse: blocks writes with secret patterns
    │   ├── validate-path.ps1        ← PreToolUse: blocks writes to protected paths
    │   ├── log-tokens.ps1           ← PostToolUse: appends to logs/tokens.jsonl
    │   ├── format-on-write.ps1      ← PostToolUse: formatter stub (disabled by default)
    │   ├── summarize-session.ps1    ← Stop: appends to logs/sessions.jsonl
    │   └── check-context.ps1        ← UserPromptSubmit: context-watch (reference copy)
    ├── logs/
    │   ├── sessions.jsonl           ← session stop log (gitignored)
    │   └── tokens.jsonl             ← token usage log (gitignored)
    ├── settings.json                ← CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, hooks, permissions
    └── settings.local.json          ← machine-specific overrides (gitignored)

Workstream pipeline repo (full set)

Repos using the workstream pipeline pattern additionally include commands, skills, and the full 9-agent set:

<repo>/
├── AGENTS.md
├── CLAUDE.md
├── .ai/
└── .claude/
    ├── agents/
    │   ├── <prefix>-planner.md
    │   ├── <prefix>-coder.md
    │   ├── <prefix>-reviewer.md
    │   ├── <prefix>-documenter.md
    │   ├── <prefix>-router.md
    │   ├── <prefix>-test-writer.md
    │   ├── <prefix>-investigator.md
    │   ├── <prefix>-operator.md
    │   └── <prefix>-security-reviewer.md
    ├── commands/
    │   ├── build.md
    │   ├── document.md
    │   ├── investigate.md
    │   ├── operate.md
    │   ├── refactor.md
    │   ├── route.md
    │   └── test.md
    ├── skills/
    │   ├── workstream-build/SKILL.md
    │   ├── workstream-document/SKILL.md
    │   ├── workstream-investigate/SKILL.md
    │   ├── workstream-operate/SKILL.md
    │   ├── workstream-refactor/SKILL.md
    │   ├── workstream-review/SKILL.md
    │   ├── workstream-test/SKILL.md
    │   ├── handoff/SKILL.md
    │   └── route-decision/SKILL.md
    ├── hooks/           ← same as standard set above
    ├── logs/            ← same as standard set above
    ├── settings.json
    └── settings.local.json

The commands/, skills/, and the multi-agent set are Claude-native (Tier A). Tier B clients run the same seven workstreams sequentially from AGENTS.md + MCP calls — they do not get emulated .claude/ equivalents. See the Tier B digest.

Templates for all agents, commands, skills, and hooks are in templates/claude/.

AGENTS.md and CLAUDE.md — mandatory content

AGENTS.md is the canonical file every tool reads. CLAUDE.md is a shim. The templates at templates/AGENTS.md.template and templates/CLAUDE.md.template carry the full structure with markers.

AGENTS.md must contain: a one-paragraph repo identity; an MCP-first block (call bootstrap(repo, client) at session start; prefer MCP answers); an offline fallback (hard-rules digest + scope name + public standards URLs on https://platform.hybridsolutions.cloud/standards/… — no auth required); the session protocol (read .ai/state/* first, update HANDOFF.md before ending); and a key-facts table (ADO project, area path, KV). CLAUDE.md imports it with @AGENTS.md and adds only Claude-specific notes.

The mandatory topic set (identity, ADO details, standards references, key facts, repo structure, actions, subagents, owner) applies to AGENTS.md:

1. What this repo is

One to three paragraphs: what it does, why it exists, what it is not. Scope boundaries matter — be explicit.

2. ADO project details

markdown

- **ADO org:** https://dev.azure.com/hybridcloudsolutions
- **ADO project:** <Project Name>
- **Area path:** <Area Path>
- **Work item format:** AB#<id> in commit messages

3. Standards references

Link to the public standards site — do not copy the standards in. This works on any machine and tool with zero auth:

markdown

## Standards

This repo follows all HCS platform standards:
- Scripting: https://platform.hybridsolutions.cloud/standards/scripting/
- Governance: https://platform.hybridsolutions.cloud/standards/governance/
- Documentation: https://platform.hybridsolutions.cloud/standards/documentation/

4. Key facts

Facts an AI client needs that are not derivable from the code:

Primary language and runtime version
Environment variables the repo expects (names only, never values)
Build, test, and serve commands
External dependencies or integration points

5. Repo structure

Top-level tree — two levels of depth is sufficient.

6. Actions (autonomous / confirm)

markdown

## Actions

**Run autonomously:**
- Read, search, grep any file in this repo
- Write and edit files in this repo
- Run scripts already committed to `scripts/`
- `git add`, `git commit`, `git push`
- <repo-specific additions>

**Always confirm before:**
- Creating or deleting Azure resources
- Any az CLI write operation
- Destructive operations
- <repo-specific additions>

7. Hooks and slash commands (if applicable)

If the repo uses the workstream pipeline pattern, add a Hooks table and Slash Commands table (Claude-native). See the turnerlegacy config for a worked example. For standard repos with the engineer agent only, these sections are optional but encouraged.

8. Subagents available in this repo

End with this stanza so a Claude Code session knows which agents are available:

markdown

## Subagents available in this repo

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

User-level agents (available in every repo): triage-lookup, markdown-prose-editor,
azurelocal-domain-expert, mkdocs-material-doctor, turner-module-scaffold-engineer,
mms-2026-demo-presenter, orchestration-pm, security-waf-caf, terraform-validator,
bicep-validator, arm-validator, ansible-linter, powershell-linter, gemini-runner,
reviewer, security-reviewer, documenter.

9. Owner

Name and email. Helps a client calibrate tone and detail level.

.claude/settings.json — minimum content

Every repo .claude/settings.json must have at minimum:

json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "allow": [
      "Bash(git add:*)",
      "Bash(git commit -m ':*)",
      "Bash(git push:*)",
      "Bash(gh issue:*)",
      "Bash(gh pr:*)",
      "Bash(pwsh -NoProfile -Command ':*)",
      "Bash(pwsh -NoProfile -File ':*)"
    ]
  }
}

Add repo-specific patterns for build commands, test runners, and any other operations that would otherwise generate permission prompts. Patterns accumulate — add new ones as sessions surface permission prompts you want to pre-approve.

See templates/claude/settings.json.template for the full starting template.

.claude/settings.local.json — machine-specific overrides

This file is gitignored. Use it for:

Paths that differ per developer machine
Patterns for commands only you run locally (not part of the shared workflow)
Overriding behaviors that the committed settings.json sets

Do not put credentials or secrets here. Gitignored ≠ safe to commit sensitive values — gitignore can be overridden or misconfigured.

json

{
  "permissions": {
    "allow": [
      "Bash(pwsh -NonInteractive -File 'D:\\tmp\\my-local-script.ps1')"
    ]
  }
}

See templates/claude/settings.local.json.template for the structure.

.claude/agents/ — repo-specific agent

Most repos have one agent definition in .claude/agents/. The agent has deep knowledge of the repo's specific structure, conventions, and constraints that would be out of place in a user-level agent.

Agent files follow the format documented in the agent roster. See templates/claude/agent.md.template for the generic scaffold, or any file in templates/claude/agents/ for a specific workstream role.

The agent name should follow the pattern <repo-name>-engineer for product repos or <repo-name>-curator for lightweight content/scratchpad repos. Use haiku for lightweight read-only agents; sonnet for everything else.

Repos using the full workstream pipeline deploy all 9 agents from templates/claude/agents/, prefixed with the repo's short name (e.g. turner-coder, turner-planner). See the agent roster for the full pipeline agent set.

What must never appear in any AGENTS.md or CLAUDE.md

Secret values, tokens, passwords, connection strings
Subscription IDs (the platform repo CLAUDE.md is the only exception)
Tenant IDs, client IDs, client secrets
API keys
Any value that would cause harm if the repo became public

settings.local.json is gitignored but still must not contain credentials.

Using the templates

Standard repo setup

Copy templates/AGENTS.md.template to the repo root as AGENTS.md and templates/CLAUDE.md.template as CLAUDE.md (the shim)
Replace every with the correct value
Copy templates/ai-workspace/ into .ai/ and fill in the starter files
Copy templates/claude/settings.json.template to .claude/settings.json
Copy all scripts from templates/claude/hooks/ to .claude/hooks/
Create .claude/logs/sessions.jsonl and .claude/logs/tokens.jsonl (empty files)
Copy templates/claude/agent.md.template to .claude/agents/<repo-name>-engineer.md and fill in its system prompt
Commit all files before the first session

Workstream pipeline setup

Same as above, plus:

Copy all files from templates/claude/agents/ to .claude/agents/; rename each file replacing the generic prefix with your repo's prefix
Copy templates/claude/commands/*.md to .claude/commands/
Copy templates/claude/skills/ tree to .claude/skills/
Add the Slash Commands and Hooks tables to AGENTS.md
Add the operate log stub: .claude/logs/operate.jsonl

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

Repo settings — per-repo Claude Code configuration ​

Full repo-level structure ​

Standard repo (single engineer agent) ​

Workstream pipeline repo (full set) ​

AGENTS.md and CLAUDE.md — mandatory content ​

1. What this repo is ​

2. ADO project details ​

3. Standards references ​

4. Key facts ​

5. Repo structure ​

6. Actions (autonomous / confirm) ​

7. Hooks and slash commands (if applicable) ​

8. Subagents available in this repo ​

9. Owner ​

.claude/settings.json — minimum content ​

.claude/settings.local.json — machine-specific overrides ​

.claude/agents/ — repo-specific agent ​

What must never appear in any AGENTS.md or CLAUDE.md ​

Using the templates ​

Standard repo setup ​

Workstream pipeline setup ​

Repo settings — per-repo Claude Code configuration

Full repo-level structure

Standard repo (single engineer agent)

Workstream pipeline repo (full set)

AGENTS.md and CLAUDE.md — mandatory content

1. What this repo is

2. ADO project details

3. Standards references

4. Key facts

5. Repo structure

6. Actions (autonomous / confirm)

7. Hooks and slash commands (if applicable)

8. Subagents available in this repo

9. Owner

.claude/settings.json — minimum content

.claude/settings.local.json — machine-specific overrides

.claude/agents/ — repo-specific agent

What must never appear in any AGENTS.md or CLAUDE.md

Using the templates

Standard repo setup

Workstream pipeline setup