CLAUDE_INIT.md

Purpose: An interactive, role-aware, evidence-driven bootstrap prompt for Claude Code. Drop this file at a repo root and run it. Claude Code will interview you (role, scope, depth, posture, connectors), scan the whole project, derive the rules / agents / memory the repo actually needs, then generate a .claude/ (and/or ~/.claude/) setup tailored to your role — not generic boilerplate.
cd <your-repo>
claude
> Read CLAUDE_INIT.md and execute it.
Stack-agnostic across engineering and business roles (FE/BE, infra/IaC, FinOps/cost data, finance/ops docs, polyglot monorepos). Idempotent and non-destructive: never overwrites your files without asking, never writes secrets, never commits.

Role

You configure Claude Code for a specific person on a specific repository. Three things drive everything: who is running it (Chief, Head, EM, TL/SL/PM, DevOps/Infra/SRE, FE, BE, QA, or a business role — FinOps, Finance, Accounting, Operational), where the config lives (team-shared vs personal), and what the repo actually contains (discovered by scanning, then turned into rules/agents/memory). Bias toward a small, high-signal setup. Every artifact must earn its place against this role and concrete evidence in this codebase.

Core principles

These permanent rules are persisted, not just recited. During Phase 4 the bootstrap writes the standing runtime rules into .claude/rules/operating.md (committed, loads every session) and CLAUDE.local.md, so they keep binding after this one-time run. A rule that lives only in this prompt evaporates once the run ends (F11).

Interactive first. Run the Phase 1 interview and wait for answers. Numbered options, defaults marked (default). Accept "use defaults".
Evidence-driven. On an existing project, scan the whole repo, then derive artifacts from what you find (Appendix C). Each generated rule/agent/memory seed must cite the evidence that justified it.
Detect, don't assume. Commands, package manager, versions come from the repo's own files. If unknown → TODO + ask.
Scope routing. Team-shared → committed .claude/. One person's role kit → personal ~/.claude/. Don't pollute the committed baseline with individual tooling unless told it's team-wide.
Confirm before writing. Finish Phases 1–3, stop for approval, show the plan.
Never clobber. Existing CLAUDE.md / settings.json / .mcp.json / .claude/* → skip or minimal-merge, say which. Preserve any existing memory.
Never write secrets. ${ENV_VAR} only. Don't echo secrets you encounter.
Skills, not commands. skills/<name>/SKILL.md, never commands/*.md.
Casing is load-bearing. CLAUDE.md uppercase; settings.json lowercase.
Hooks wired in settings.json, scripts in hooks/, chmod +x.
Guidance vs enforcement. CLAUDE.md/rules/ = read; permissions/hooks = enforced.
Safety scales with blast radius. Infra/SRE setups must deny destructive ops by default (apply/destroy/delete). Leadership setups (Chief/Head/EM) default to read-only.
No model pin, no auto-commit.
Big docs load on demand. Store API specs (gRPC .proto, OpenAPI/Swagger, GraphQL SDL) and long reference docs under .claude/docs/, wired via a path-scoped rule — never paste their contents into CLAUDE.md (that loads every session). .claude/docs/ is not auto-loaded; a rule or CLAUDE.md reference is what makes it usable.
English artifacts, Indonesian replies. Author everything you generate — file names, variable names, comments, and the body of every skill/rule/agent/CLAUDE.md — in English. The assistant's conversational replies to the user are Bahasa Indonesia with English technical terms, set via CLAUDE.local.md (Appendix F1).
Always generate local files. Beside the committed config, generate CLAUDE.local.md, .claude/settings.local.json, and local MCP (scope-based) — Appendix F2.
Plans live in .plan/. Project plans → .plan/NN_name_of_plan.md (zero-padded number + snake_case). Generate planning with the highest-capability model + extended thinking ON (F4).
All temp work in .cache/. Every temporary file, script, or scratch artifact goes only there — never anywhere else in the repo. Gitignored (F5).
Presentations = one self-contained HTML in .share/ (committed) — interactive, mobile-responsive, visually striking, with an EN/ID toggle (F5).
Parallelize above a threshold, capped to the machine. Use subagents only when there are >= 3 independent subtasks; for small/single-file work, run inline. Cap concurrency so local execution never throttles the device; surface progress via event hooks + a terminal/ntfy heartbeat (F6).
Mermaid only in docs/HTML, never in context. Right chart type, official syntax (validate via a mermaid/context7 MCP or local CLI if available), no styling, <br> for line breaks (F7).
Never expose passwords/credentials in any file, diagram, or output unless the user explicitly asks.
Never commit or push unless the user explicitly asks.
Best-practice engineering by default. Any code/config/content you generate uses the architecture and design pattern that fits the project (e.g. DDD, Hexagonal/Ports-and-Adapters, Clean, layered) — follow the repo's existing pattern, or decide and state one for greenfield. Apply current, widely-adopted conventions; pick frameworks/libraries that are actively maintained, free of known high/critical CVEs, and stable, and justify each choice (F9).
Pin static version numbers — never latest. Every dependency, base image, interpreter, and SDK is pinned to an explicit numeric version (e.g. 4.21.2, never latest or an unpinned range; container images use a pinned tag, ideally a @sha256 digest, never :latest) so the project doesn't break over time. Commit the lockfile, and pair pinning with an automated update tool (Renovate/Dependabot) so pins still receive security patches (F9).
Gotcha register. /find-gotcha-items runs a high-level audit and logs non-obvious traps to .issues/NN_gotcha_YYYYMMDD.md; /update-context keeps their statuses current (F10).
Evidence over assumption when investigating. When the user asks Claude to find out, verify, or explain why/whether something is true, ground the answer in evidence, never recall or guess: official documentation (read it; cite source + version) or a real experiment (run the command, write a minimal repro, check the installed version/lockfile/source). State confidence; label anything unverified as an assumption; if evidence is unobtainable, say so (F12).

Personas at a glance (generation targets)

Persona	Posture (default)	Focus	Lives in
FE Engineer	read-write	Components, a11y, styling, FE tests, bundle	`~/.claude/`
BE Engineer	read-write	Endpoints, DB/migrations, authz, API tests	`~/.claude/`
DevOps/Infra/SRE	read-write, destructive-deny	IaC, manifests, CI/CD, runbooks, SLO, incidents	`~/.claude/`
QA	read-write, test-scoped	Test plans, e2e, repro, coverage, flaky triage	`~/.claude/`
TL/SL/PM	read-mostly	Review, ADRs, PRDs, risk, planning	`~/.claude/`
EM	read-only	Repo health, tech-debt, security posture, RCA	`~/.claude/`
Head	read-only	Multi-team delivery, architecture coherence, standards	`~/.claude/`
Chief	read-only	Portfolio risk/cost/compliance, board narrative	`~/.claude/`
FinOps	read-only	Cloud cost drivers, COGS/allocation, optimization, tagging	`~/.claude/`
Finance	read-only	Variance, forecast, statements, spend narrative	`~/.claude/`
Accounting	read-only	Journal entries, reconciliation, close, audit support	`~/.claude/`
Operational	read-only	SOPs/runbooks, vendor review, ops reporting	`~/.claude/`
Team baseline	read-write	Shared conventions, reviewer agent, security floor	`.claude/` (committed)

Most people want both: the committed team baseline for the repo + their personal role kit. Chief/Head/EM kits are about synthesis across repos — a single-repo run is one data point; the real win is the same personal kit run over your whole portfolio plus a consistent committed baseline in every repo.

Phase 0 — Safety preconditions

git rev-parse --is-inside-work-tree 2>/dev/null && echo "git: yes" || echo "git: NO"
git status --porcelain | head -20

Not git → warn, continue (skip .gitignore). Dirty tree → list changes, ask to proceed.

Phase 1 — Interactive interview (ASK, then WAIT)

Present as a numbered list with defaults; stop for my answers. Infer sensible defaults from obvious signals (e.g. an IaC-heavy repo → suggest DevOps/Infra/SRE).

Q1 — What are you setting up?

Team baseline only → committed .claude/
My personal role kit only → ~/.claude/
Both (default)

Q2 — Your role (skip if Q1 = team baseline only)

Individual contributors: 1. FE Engineer 2. BE Engineer 3. DevOps/Infra/SRE 4. QA
Leads & leadership: 5. TL/SL/PM 6. EM 7. Head 8. Chief
Business & finance: 9. FinOps 10. Finance 11. Accounting 12. Operational

Q3 — Scaffold depth: 1. Minimal 2. Standard (default) 3. Full

Q4 — Write posture: 1. Read-only 2. Read-write (default per role — see matrix; leadership defaults read-only, infra defaults read-write-with-destructive-deny)

Q5 — MCP connectors (multi-select, pre-selected by role): none · GitHub/GitLab · Atlassian (Jira/Confluence) · Outline · Linear · Figma

Team scope → .mcp.json. Personal scope → emit claude mcp add --scope user … commands.

Restate the chosen (scope, role, depth, posture, connectors) in one line for confirmation.

Phase 2 — Scan the whole project & derive artifacts

2A — Inventory (read-only: `ls`, `cat`, `Read`, `Grep`, `Glob`)

Structure: monorepo? workspaces (pnpm-workspace.yaml, workspaces, go.work, turbo.json, nx.json, Cargo/Maven/Gradle multi-module). Significant source dirs and what each is.
Languages/runtimes: .nvmrc, .tool-versions, go.mod, pyproject.toml, pom.xml, Cargo.toml, Dockerfile.
Commands (verbatim): build / test / lint / format / typecheck / dev — from package.json, Makefile, Taskfile.yml, justfile, pyproject.toml, go.mod.
Conventions: formatter, test framework, module/export style, test-file naming, API shape, state mgmt, styling system. Read any CONTRIBUTING.md, style guide, .editorconfig, linter config, and existing ADRs.
Architecture / patterns: infer the existing design pattern from the layout (DDD bounded contexts, Hexagonal ports/adapters, Clean/layered, MVC, etc.) so generated code conforms; note it for F9.
API contracts & docs: gRPC .proto, OpenAPI/Swagger (openapi.*, swagger.*), GraphQL SDL, and long-form reference docs — note their locations. These become .claude/docs/ entries wired by a path-scoped rule (see 2B).
Infra & delivery: *.tf/*.tfvars, helm/, kustomize/, k8s/ manifests, ansible/, serverless.yml, Pulumi, Dockerfile(s), CI workflows.
Security surface: auth/crypto/secret-handling code; credential file patterns present (.env*, *.pem, *.key, *-key.json, credentials.json, kubeconfig) — list patterns, never contents.
Existing config: inventory current .claude/ and .mcp.json; treat as sources of truth.

2B — Derive (the dynamic engine)

Run the Evidence → Artifact mapping in Appendix C. For each match, decide whether it warrants a rule, an agent, and/or a memory seed, on top of the role kit. Deduplicate against the role kit and against anything already in .claude/.

Memory seeding: for any agent you generate with memory: project, prepare an initial .claude/agent-memory/<agent>/MEMORY.md capturing discovered, durable facts relevant to that agent (architecture map, custom patterns, known gotchas). Do not hand-write the main session auto memory (~/.claude/projects/…/MEMORY.md) — that's Claude-maintained; encode durable facts in CLAUDE.md + rules/ + seeded agent memory instead.

Docs handling: treat API contracts (gRPC .proto, OpenAPI/Swagger, GraphQL SDL) and long reference docs as on-demand material. Place them under .claude/docs/ — or, if a canonical copy already drives codegen elsewhere (e.g. proto/, api/openapi.yaml), reference that path instead of duplicating, to avoid drift. Then add a path-scoped rule that tells Claude to read the relevant spec before editing the matching code (e.g. paths: ["src/api/**"] → "read the matching spec in .claude/docs/ first"). Never inline a full spec into CLAUDE.md; .claude/docs/ is inert until a rule/CLAUDE.md points to it. The project summary + tech stack stay in root CLAUDE.md.

Output of Phase 2: a Project Profile block + a Derived Artifacts list where every item names its evidence, e.g. iac-safety rule + infra-reviewer agent ← found terraform/ and helm/.

Phase 3 — Propose the plan (then STOP)

Merge role kit (Appendix B) + derived artifacts (2B), deduped. Present:

Exact tree(s) — committed .claude/ and/or ~/.claude/ — each node [new]/[skip — exists]/ [merge], with a one-line justification (role and/or evidence).
Resolved commands/conventions → CLAUDE.md (verbatim).
permissions.allow / deny — deny from credential patterns (+ destructive-op denies for infra); allow from detected commands; read-only posture → no write/exec allow rules.
MCP wiring per Q5.
Memory seeds to be written and their source facts.
TODOs. Wait for approval; honor edits.

Phase 4 — Generate (after approval)

Team artifacts → .claude/…; personal → ~/.claude/….
Skills: one folder + SKILL.md; disable-model-invocation: true for user-only workflows (/deploy, /release-notes, /postmortem); precise description for auto-invoked review/analysis skills.
Agents: tools: allow-list matches posture — reviewers/auditors get read-only tools; infra agents never get apply/destroy capability.
Write seeded agent-memory/<agent>/MEMORY.md files from 2B.
Persist the standing rules: write .claude/rules/operating.md (committed) with the permanent runtime rules so they load every session — this is what makes the principles outlive this run (F11).
Generate local files (Appendix F2): CLAUDE.local.md (git name/email + Indonesian-reply directive), .claude/settings.local.json (the co-author trailer is ON by default — no key needed), and emit claude mcp add --scope local … commands for personal MCP servers.
Generate an automated dependency-update config (renovate.json or .github/dependabot.yml) so pinned versions still get security patches (F9).
Create workspace dirs on first use, not preemptively (an empty dir on a fresh repo is just clutter): .plan/, .issues/, and .share/ (all committed; .plan/.issues content in English) when the first plan/issue/presentation is written; .cache/ (scratch, gitignored) when first needed. Generate the always-on workflow skills (update-context, plan, present, find-gotcha-items) and the multi-agent heartbeat hook + script (Appendix F3–F6, F10).
chmod +x .claude/hooks/*.sh. Keep only language/infra arms the repo uses. No model pin. No empty dirs for omitted components.

Phase 5 — Verify

find .claude -type f 2>/dev/null | sort
[ -d ~/.claude ] && find ~/.claude -maxdepth 3 -type f 2>/dev/null | sort
ls -l .claude/hooks/ 2>/dev/null
[ -f .claude/settings.json ] && jq empty .claude/settings.json && echo "settings.json: valid"
git check-ignore .claude/settings.local.json 2>/dev/null && echo "local: ignored" || echo "local: check .gitignore"

Fix any failure before summarizing.

Phase 6 — Summarize

Table: each file created/skipped/merged · scope (committed/personal) · purpose · (for derived items) the evidence.
Detected commands encoded in CLAUDE.md; deny-list applied + patterns that drove it.
Memory seeds written. Any claude mcp add --scope user … commands to run.
Next steps: review CLAUDE.md; commit .claude/ (confirm settings.local.json gitignored); decide whether any personal skill should be promoted to the team baseline. Don't commit unless asked.

Appendix A — Canonical structure & scope routing

Root (committed): CLAUDE.md, .mcp.json, .worktreeinclude; CLAUDE.local.md (gitignored). .claude/ (committed baseline): settings.json, rules/, skills/, agents/, hooks/, agent-memory/ (seeded/autogen); settings.local.json (gitignored). Convention: .claude/docs/ for API specs / long reference docs — not auto-loaded; a path-scoped rule or CLAUDE.md must point to it. ~/.claude/ (personal): CLAUDE.md, settings.json, rules/, skills/, agents/, output-styles/; personal MCP via claude mcp add --scope user → ~/.claude.json. Repo workspace dirs: .plan/ (project plans NN_name.md, committed) · .issues/ (gotcha/risk findings NN_gotcha_YYYYMMDD.md, committed) · .share/ (presentation HTML, committed) · .cache/ (all temporary/scratch + scripts, gitignored). Local files: CLAUDE.local.md and .claude/settings.local.json (both gitignored) — Appendix F2.

rules/*.md without paths: load every session; with paths: load when a matching file enters context. Skill frontmatter: description drives auto-invoke; disable-model-invocation: true = user-only; user-invocable: false = hidden from /. Args $ARGUMENTS/$0/$1; !`cmd` injects shell output; ${CLAUDE_SKILL_DIR} for bundled files. Precedence (high→low): managed → CLI → some env → settings.local.json → project settings.json → global settings.json → defaults. Arrays combine; scalars take the most specific.

Appendix B — Role → Artifacts matrix

[U] = user-only (disable-model-invocation: true). Depth truncates lists (Minimal ≈ first 2–3, Standard ≈ 4–5, Full = all). Reviewer/auditor agents are read-only (tools: Read, Grep, Glob).

Team baseline (committed `.claude/`) — role-neutral

CLAUDE.md; settings.json (permissions + deny + format/block-secrets hooks); rules/ (coding conventions + path-scoped rule for the dominant source area); agent code-reviewer; .gitignore additions. Posture read-write. MCP GitHub/GitLab if a remote exists.

FE Engineer (personal) — read-write · detect: React/Vue/Svelte/Angular, Tailwind/CSS-modules, Vite/Next, Storybook, Playwright/Cypress

Skills: build-component — scaffold a component matching conventions · a11y-check — audit a component/page for accessibility · write-component-tests — RTL/Vitest tests · responsive-review — check breakpoints/layout · bundle-audit — flag bundle-size regressions.
Agents: ui-reviewer (a11y, semantics, prop hygiene) · component-test-writer.
Rules: component conventions; styling system; a11y standards; state-mgmt — path-scoped to FE dirs.
MCP: GitHub/GitLab + Figma.

BE Engineer (personal) — read-write · detect: Express/Fastify/Nest, Gin/net-http, FastAPI/Django, Spring; DB + migration tool; OIDC/JWT; REST/gRPC/GraphQL

Skills: add-endpoint — scaffold endpoint + validation + tests · db-migration — generate a migration in the detected tool (Atlas/Bytebase/Flyway/Prisma) · write-api-tests · query-review — DB query/index review · trace-flow — trace a request end-to-end · contract-check — OpenAPI/proto ↔ implementation consistency.
Agents: api-reviewer (validation, authz, error handling, injection) · query-optimizer · security-auditor.
Rules: API design (validation, response shape, rate limit); DB/migration; authz; error-handling — path-scoped to service/api dirs.
MCP: GitHub/GitLab + Atlassian.

DevOps/Infra/SRE (personal) — read-write with destructive-deny · detect: Terraform, Helm, Kustomize, k8s manifests, Ansible, CI workflows, Dockerfiles

Skills: plan-infra [U] — terraform plan / helm diff (dry-run only) · review-manifest — lint k8s/Helm + policy/security checks · runbook [U] — generate/update an operational runbook · rollback-plan [U] — produce a rollback procedure for a change · cve-scan — image/dependency CVE surface · slo-review — assess SLO/alerting config.
Agents: infra-reviewer (drift, misconfig, exposed secrets — read-only) · manifest-linter · security-hardening-auditor.
Rules: IaC conventions; manifest standards; "never apply/destroy/delete without explicit confirmation"; secret-handling — path-scoped to terraform/, helm/, k8s/, .github/workflows/.
Permissions (critical): allow plan/diff/lint/fmt/read; deny terraform apply, terraform destroy, kubectl delete, kubectl apply, helm upgrade, helm uninstall, gcloud … delete, aws … delete, rm -rf. Add the destructive-op guard hook (Appendix D).
MCP: GitHub/GitLab.

QA (personal) — read-write, test-scoped (treat `src/` as read-reference)

Skills: test-plan — derive a plan from spec/diff · write-e2e — author e2e in the detected framework · reproduce-bug [U] — !`gh issue view $ARGUMENTS` → minimal repro + failing test · regression-check — map a change to impacted areas · coverage-report · flaky-triage.
Agents: bug-reproducer (Read, Grep, Glob, Bash) · coverage-analyzer.
Rules: test conventions; test-data handling; "edit only under {{TEST_DIRS}}".
MCP: GitHub/GitLab + Atlassian.

TL/SL/PM (personal) — read-mostly (writes limited to docs/ADRs)

Skills: review-pr — !`git diff $ARGUMENTS` structured review · write-adr [U] · draft-prd [U] · release-notes [U] · risk-assessment · dependency-audit · estimate.
Agents: architecture-reviewer · security-auditor · dependency-auditor (+Bash) · doc-writer (+Write).
Rules: ADR format; PRD template; documentation standards (Diátaxis).
Output style: explanatory (built-in) or custom review-mode. MCP: Atlassian/Outline/Linear + GitHub/GitLab.

EM (personal) — read-only

Skills: repo-health · tech-debt-audit (rank by effort/impact) · security-posture · dependency-license-audit · postmortem [U] · onboarding-doc [U].
Agents: tech-debt-analyzer · security-posture-auditor · license-auditor (+Bash) · doc-writer (+Write).
Rules: reporting/doc standards. Output style: report-mode (keep-coding-instructions: false).
Permissions: read-only — no write/exec allow. MCP: Atlassian/Outline + GitHub/GitLab.

Head (personal) — read-only · department / multi-team altitude

Skills: delivery-health — summarize CI/test/release health for the repo as one portfolio input · architecture-coherence — assess fit against expected patterns · standards-adherence — does this repo follow the org baseline (compare to team .claude/)? · tech-strategy-brief [U] · onboarding-readiness.
Agents: architecture-reviewer · standards-auditor · doc-writer (+Write).
Rules: reporting standards. Output style: leadership-brief (keep-coding-instructions: false).
Permissions: read-only. MCP: Atlassian/Outline + GitHub/GitLab.
Note: designed to run across many repos; aggregate outputs externally.

Chief (personal) — read-only · org / board altitude

Skills: exec-tech-brief [U] — board-ready summary of state & risk · risk-liability-summary — surface security/compliance/architecture liabilities · security-compliance-posture · cost-exposure-narrative [U] — FinOps/scaling cost framing (infra evidence + your figures) · portfolio-rollup [U] — fold one repo into a portfolio view.
Agents: security-posture-auditor · license-auditor (+Bash) · doc-writer (+Write).
Rules: board-reporting standards. Output style: board-brief (keep-coding-instructions: false; lead with exec summary, quantify risk, no implementation detail).
Permissions: strictly read-only; full deny-list. MCP: Atlassian/Outline.
Note: value is portfolio synthesis; per-repo run is one input.

Business & finance band (personal) — read-only; reports/docs via `doc-writer`

These kits assume the working folder holds financial / cost / operational data and docs (cost exports, IaC cost drivers, financial models, ledgers, SOPs) — not application code. For pure spreadsheet-driven finance/accounting, Claude Cowork is the better home; this is for data/docs repos and wiki-export folders. All four default to read-only over data, emitting report files via a scoped doc-writer.

FinOps (personal) — read-only · detect: IaC cost drivers, cloud billing exports (CSV/JSON), cost dashboards, tagging/labeling

Skills: cost-surface-scan — find cost drivers in IaC (instance types, replicas, storage class, egress, retention) · cogs-allocation [U] — apply an allocation method (e.g. MAU-proportional) to produce a COGS breakdown by business unit · optimization-audit — rank savings (rightsizing, spot/CUD, idle, retention) · commitment-review — RI/CUD/savings-plan coverage · cost-anomaly-explain — explain a cost drift from a config diff · tag-coverage-audit — cost-allocation tag/label hygiene.
Agents: cost-driver-analyzer (Read, Grep, Glob) · optimization-auditor (Read, Grep, Glob) · doc-writer (+Write).
Rules: tagging/labeling standards; retention-policy standards; region / data-residency constraints; cost-config conventions — path-scoped to IaC dirs.
Memory seed: business-unit allocation map; region/residency constraints; instance/retention inventory.
Output style: finops-report (editorial finance aesthetic; lead with totals + deltas).
MCP: GitHub/GitLab + Outline/Atlassian.

Finance (personal) — read-only (reports via `doc-writer`) · detect: financial models, budgets/forecasts, spreadsheets, finance docs

Skills: variance-analysis — budget-vs-actual decomposition with drivers · forecast-review · financial-statement-prep [U] — P&L / balance sheet / cash flow with period-over-period comparison · budget-summary · spend-narrative [U] — leadership-ready commentary.
Agents: variance-analyzer (Read, Grep, Glob) · doc-writer (+Write).
Rules: reporting standards; figure/format conventions.
Output style: financial-report (keep-coding-instructions: false).
MCP: Outline/Atlassian.

Accounting (personal) — read-only (workpapers via `doc-writer`) · detect: ledger/GL exports, reconciliation files, transaction data, accounting docs

Skills: journal-entry [U] — prepare a JE (debits/credits) with support · reconciliation — GL vs subledger/bank, classify reconciling items · close-checklist [U] — month-end close tasks & sequencing · audit-support — control testing & sample selection.
Agents: reconciliation-analyzer (Read, Grep, Glob) · doc-writer (+Write).
Rules: chart-of-accounts conventions; workpaper standards; control/evidence handling.
Output style: workpaper (keep-coding-instructions: false).
MCP: Outline/Atlassian.

Operational (personal) — read-only (docs via `doc-writer`) · detect: SOPs/runbooks, process docs, vendor/contract docs, operational data exports

Skills: process-doc [U] — author/update an SOP or runbook · support-runbook [U] · vendor-review — review a vendor/contract doc for terms & risk · ops-report [U] — operational status summary · data-export-summary — summarize an exported dataset/report.
Agents: process-analyzer (Read, Grep, Glob) · doc-writer (+Write).
Rules: SOP/runbook format; documentation standards (Diátaxis).
Output style: ops-report.
MCP: Outline/Atlassian.

Appendix C — Evidence → Artifact derivation (existing-project engine)

Apply on top of the role kit. Generate only what fits the chosen role/posture; cite the evidence.

Scan finds…	Rule	Agent	Memory seed
OpenAPI / proto / GraphQL spec	`api-contract` (path-scoped) → reads spec in `.claude/docs/`	`api-reviewer`	endpoints + contract notes
Terraform / Helm / Kustomize / k8s	`iac-safety` + `manifest`	`infra-reviewer`	env/cluster/module map + destructive-op reminder
DB migrations / ORM	`migration` + `query`	`query-optimizer`	schema/index notes + migration tool
Auth / crypto / secret-handling code	`authz` + `secret-handling`	`security-auditor`	auth/token flow notes
`CONTRIBUTING.md` / style guide / linter config	`conventions` (encode its rules)	—	—
Existing ADRs	`adr-format`	—	decision-log pointer
Test framework + patterns	`testing` (path-scoped)	`coverage-analyzer`	flaky/known-failing notes
Monorepo workspaces	per-package `CLAUDE.md` notes	—	package/ownership map
CI workflows	CI-awareness in `CLAUDE.md`	—	required checks / pipeline notes
FE framework + design tokens	`component` + `a11y` (path-scoped)	`ui-reviewer`	component/token map
Cloud billing exports (CSV/JSON) / cost dashboards	`cost-tagging`	`cost-driver-analyzer`	BU allocation map + region/residency
IaC cost drivers (instance/replica/storage/retention)	`cost-config` (path-scoped)	`optimization-auditor`	instance/retention inventory
Financial models / budgets / spreadsheets	`finance-reporting`	`variance-analyzer`	period/account map
Ledger / GL / reconciliation exports	`accounting-controls`	`reconciliation-analyzer`	chart-of-accounts notes
SOPs / runbooks / process docs	`process-doc` standards	`process-analyzer`	process/owner map
Existing `.claude/` content	merge, don't replace	preserve	preserve existing memory

Appendix D — Templates (resolve `{{PLACEHOLDER}}`)

Generic skill — `skills/<name>/SKILL.md`

---
description: {{PRECISE_ONE_LINE — controls auto-invocation}}
{{# user-only: }}disable-model-invocation: true
{{# optional: }}argument-hint: {{ARG_HINT}}
---
{{# optional: }}!`{{COMMAND_USING_$ARGUMENTS}}`

{{STEP-BY-STEP INSTRUCTIONS — reference CLAUDE.md / .claude/rules/; ${CLAUDE_SKILL_DIR} for bundled files.}}

Generic agent — `agents/<name>.md`

---
name: {{NAME}}
description: {{WHEN_TO_DELEGATE}}
tools: {{ALLOWLIST — reviewers/auditors: Read, Grep, Glob}}
{{# to seed/keep memory: }}memory: project
---
{{SYSTEM PROMPT. End with: every finding includes a concrete fix.}}

Seeded subagent memory — `agent-memory/<agent>/MEMORY.md`

# {{AGENT}} memory (seeded from initial scan — the agent maintains this going forward)

## Architecture / patterns
- {{DISCOVERED_PATTERN_1}}
- {{DISCOVERED_PATTERN_2}}

## Known gotchas
- {{GOTCHA_1}}

Output style — `output-styles/<name>.md` (personal)

---
description: {{PURPOSE}}
keep-coding-instructions: {{true_for_IC | false_for_leadership/report_modes}}
---
{{APPENDED INSTRUCTIONS — e.g. "Lead with an executive summary; quantify risk; leave implementation to teams."}}

`CLAUDE.md`

# {{PROJECT_NAME}} — Claude Code project context

## Stack
- {{LANGUAGES_AND_RUNTIMES}} · Package manager: {{PKG_MGR}} {{MONOREPO_NOTE_OR_OMIT}}

## Commands
- Build: `{{BUILD}}` · Test: `{{TEST}}` · Lint: `{{LINT}}` · Typecheck: `{{TYPECHECK_OR_OMIT}}` · Run: `{{DEV}}`

## Conventions
- {{CONVENTION_1}} · {{CONVENTION_2}} · Tests live {{TEST_LOCATION}}

## Architecture (only what's needed every session)
- {{SHORT_NOTES}} {{# include CI required-checks + package map if monorepo}}
- {{# if API specs exist: }}API contracts: see `.claude/docs/` — read the relevant spec on demand (don't inline).

## Working agreements
- Prefer editing existing files over adding new ones unless asked.
- Run the relevant test/lint command after changes and report the result.

Existing CLAUDE.md → extend missing Commands, don't rewrite.

`.claude/settings.json` (team baseline)

{
  // Optional "$schema" for editor autocomplete if the current schemastore URL is known.
  "permissions": {
    "allow": [
      "Bash({{TEST_PREFIX}} *)", "Bash({{BUILD_PREFIX}} *)", "Bash({{LINT_PREFIX}} *)",
      "Bash(git diff *)", "Bash(git status *)", "Bash(git log *)"
    ],
    "deny": [
      "Bash(rm -rf *)", "Read(./.env)", "Read(./.env.*)", "Read(./**/*.pem)", "Read(./**/*.key)"
      // + one Read(...) deny per credential pattern found in Phase 2
    ]
  },
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-secrets.sh" }] }],
    "PostToolUse": [{ "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh" }] }]
  }
}

Read-only posture: drop all write/exec allow, keep deny + hooks. Infra posture: add the destructive-op denies (above) and the guard hook (below). Strip JSON comments before writing.

`.claude/hooks/block-secrets.sh`

Hooks like this are a speed bump, not a security boundary — grep matching is bypassable (vars, base64, alt syntax). The real boundary is permissions.deny in settings.json.

#!/usr/bin/env bash
set -euo pipefail
command -v jq >/dev/null || { echo "jq required for this hook" >&2; exit 0; }
cmd="$(jq -r '.tool_input.command // empty')"
if printf '%s' "$cmd" | grep -Eiq '(\.env([^a-z]|$)|\.pem|\.key|id_rsa|credentials\.json|kubeconfig)'; then
  echo "Blocked: command appears to access a credential file." >&2; exit 2
fi
exit 0

`.claude/hooks/guard-destructive.sh` (DevOps/Infra/SRE)

Speed bump, not a boundary (see above). Pair it with permissions.deny rules for real enforcement.

#!/usr/bin/env bash
# Hard-stop infra-destructive commands. Register under PreToolUse matcher "Bash".
set -euo pipefail
command -v jq >/dev/null || { echo "jq required for this hook" >&2; exit 0; }
cmd="$(jq -r '.tool_input.command // empty')"
if printf '%s' "$cmd" | grep -Eiq '(terraform[[:space:]]+(apply|destroy)|kubectl[[:space:]]+(delete|apply)|helm[[:space:]]+(upgrade|uninstall|delete)|(gcloud|aws)[[:space:]].*(delete|destroy)|rm[[:space:]]+-rf)'; then
  echo "Blocked: destructive infra command. Run it yourself outside Claude if intended." >&2; exit 2
fi
exit 0

`.claude/hooks/format.sh`

#!/usr/bin/env bash
set -euo pipefail
command -v jq >/dev/null || exit 0
file="$(jq -r '.tool_input.file_path // empty')"; [ -z "$file" ] && exit 0
case "$file" in
  *.ts|*.tsx|*.js|*.jsx|*.json|*.md) command -v {{JS_FORMATTER}} >/dev/null && {{JS_FORMAT_INVOCATION}} "$file" || true ;;
  *.go) command -v gofmt >/dev/null && gofmt -w "$file" || true ;;
  *.py) command -v ruff >/dev/null && ruff format "$file" || true ;;
  *.tf|*.tfvars) command -v terraform >/dev/null && terraform fmt "$file" || true ;;
  *.rs) command -v rustfmt >/dev/null && rustfmt "$file" || true ;;
esac

`.claude/rules/<topic>.md`

---
paths:
  - "{{GLOB}}"   # omit to load every session
---
# {{TOPIC}} rules
- {{RULE_1}}
- {{RULE_2}}

MCP — team scope (`.mcp.json`) vs personal

{ "mcpServers": { "{{NAME}}": { "command": "{{CMD}}", "args": ["{{ARGS}}"],
  "env": { "{{TOKEN}}": "${{{TOKEN}}}" } } } }

claude mcp add --scope user {{NAME}} -- {{CMD}} {{ARGS}}   # personal → ~/.claude.json

Secrets only as ${ENV_VAR}. Existing .mcp.json → merge.

`.gitignore` additions

# Claude Code — local/personal config (do not commit)
.claude/settings.local.json
.claude/agent-memory-local/
CLAUDE.local.md
.cache/

Appendix E — Do-not list

No writes before Phase 3 approval. No clobbering existing .claude/* / CLAUDE.md / .mcp.json.
No secrets in committed files. No commands/*.md — use skills.
No invented commands (unknown → TODO + ask). No model pin unless asked.
No write/exec allow rules under read-only posture; no apply/destroy/delete allow under infra posture — those stay denied + guarded.
No individual role skills in the committed baseline unless told team-wide.
Don't hand-write the main auto memory; seed only subagent agent-memory/.
Don't commit — leave staging to me.

Appendix F — Operating conventions (always applied, every role)

F1 — Language policy

Artifacts in English: file names, directory names, variable names, code comments, and the body of every skill/rule/agent/CLAUDE.md you author. Keeps the setup portable and standard.
Replies in Bahasa Indonesia (technical terms in English): the assistant talks to the user in Indonesian; only technical terms stay in English. Enforced via CLAUDE.local.md (F2), so it is personal and not committed.

F2 — Local files (generated beside the committed config)

CLAUDE.local.md (repo root, gitignored):

# Local context (personal — not committed)

## Git identity
- Name: {{GIT_USER_NAME}}     # from `git config user.name`
- Email: {{GIT_USER_EMAIL}}   # from `git config user.email`

## Assistant behavior
- Respond in Bahasa Indonesia; keep technical terms in English.
- Never commit or push unless I explicitly ask.
- Never expose passwords or credentials unless I explicitly ask.

.claude/settings.local.json (gitignored):

{
  // "claude trailing" (Co-Authored-By + "Generated with Claude Code") is ON BY DEFAULT — no key needed,
  // and it only appears when you ask Claude to commit. Do NOT set the deprecated `includeCoAuthoredBy`.
  // To DISABLE later, use the `attribution` setting: "attribution": { "commit": "", "pr": "" }
  // Put any other personal overrides for this project here.
}

Local MCP (no file exists — scope-based; emit commands for the user to run):

claude mcp add --scope local {{NAME}} -- {{CMD}} {{ARGS}}   # stored in ~/.claude.json, not committed

Fetch identity with git config user.name / git config user.email; if unset, leave a TODO.

F3 — `update-context` skill — `skills/update-context/SKILL.md`

---
description: Update project context (CLAUDE.md and .claude/) from the current session and repo state
disable-model-invocation: true
argument-hint: [optional focus area]
---
Refresh the project's Claude context **recursively** from what changed this session and the current
repo. Walk the full tree — never touch only the root.

1. Re-scan for drift: new/changed commands, conventions, dependencies, architecture, API specs,
   directory structure.
2. **CLAUDE.md (recursive):** update the root `CLAUDE.md` (summary, tech stack, commands) **and** every
   nested per-package/subdir `CLAUDE.md` (e.g. `apps/*/CLAUDE.md`), each scoped to its own subtree.
   Extend, don't rewrite; keep each <= 200 lines.
3. **rules/ (recursive):** traverse `.claude/rules/` **including subdirectories** (e.g.
   `.claude/rules/frontend/react.md`); update/add rules and their `paths:` scoping. Refresh
   `.claude/docs/` and the rules that point to it if specs changed.
4. **agents + memory (every one):** for each `.claude/agents/*.md`, confirm it still fits the repo;
   for each `.claude/agent-memory/<agent>/MEMORY.md` (and `agent-memory-local/`), update durable facts
   learned this session.
5. **skills/ (every one):** scan each `.claude/skills/*/SKILL.md` for stale references (changed
   commands, paths, tools) and correct them.
6. **Reconcile gotcha findings:** revisit `.issues/NN_gotcha_*.md` and update the **status** of each
   related finding (`open` -> `mitigated`/`resolved` if fixed this session; keep `open` if still
   present; append a dated note). Never delete findings — record the change instead.
7. **settings.json:** flag permission/command drift as a *proposal* — never silently change enforcement.
8. Show a diff summary of every change and **wait for approval** before writing. Never commit.

Scope: recurse within the single project `.claude/` and across nested `CLAUDE.md` files only. Claude
Code reads just the root project `.claude/` and `~/.claude/`, so do NOT create per-package `.claude/`
folders. Personal `~/.claude/` is out of scope unless I ask.

F4 — Planning -> `.plan/NN_name_of_plan.md`

Plans capture the user's intent for the whole project, written in English. Filename: zero-padded sequence + snake_case, e.g. 01_auth_migration.md, 02_cost_optimization.md.
A skill cannot switch model or toggle thinking (those are session-level), so the skill asks the user to enable the most capable model (Opus) + extended thinking first, then plans (/model -> Opus; enable thinking, or use Plan Mode).
plan skill — skills/plan/SKILL.md:

---
description: Produce or update a project plan in .plan/ using maximum reasoning
disable-model-invocation: true
argument-hint: <plan-name>
---
First, if the session is not already on the most capable model with extended thinking enabled, ask the
user to switch (`/model` -> Opus; enable thinking / Plan Mode) and wait. Then think step by step and
write a plan (in English) at `.plan/NN_$ARGUMENTS.md` (next sequence number, snake_case) covering:
goal, scope / non-goals, phased steps with owners and impact, risks, and acceptance criteria. Planning
only — do not implement.

F5 — `.cache/` scratch (gitignored) + `.share/` presentation HTML (committed)

All temporary files, scripts, intermediate output, and scratch artifacts go only in .cache/ (gitignored). Never write temporary content anywhere else in the repo.
Presentations: always a single self-contained HTML file in .share/ (committed; CSS/JS inline, no external build), interactive, mobile-responsive, and visually striking, with an EN / ID toggle. The ID view is Bahasa Indonesia with technical terms kept in English.
present skill — skills/present/SKILL.md:

---
description: Build a single interactive, mobile-responsive, bilingual (EN/ID) HTML presentation in .share/
disable-model-invocation: true
argument-hint: <topic>
---
Create ONE self-contained `.html` file in `.share/` (all CSS/JS inline). Requirements:
- Mobile-first responsive, interactive, visually polished.
- Language toggle EN <-> ID. ID = Bahasa Indonesia; keep technical terms in English.
- If diagrams are needed, use Mermaid per Appendix F7 (right chart, official syntax, no styling, <br> newlines).
Open nothing automatically; report the file path.

F6 — Multi-agent orchestration

Parallelize only above a threshold: use subagents when there are >= 3 independent subtasks (e.g. recursive per-package CLAUDE.md updates, multi-area audits). For small or single-file work, run inline — no subagents (spawning them is pure overhead).

Concurrency cap (don't throttle the device): subagents are API-side and light on local resources, but the local commands they trigger (builds, tests, containers) are not. Cap how many agents run local work at once:

CORES=$(nproc 2>/dev/null || sysctl -n hw.ncpu)
FREE_GB=$(free -g 2>/dev/null | awk '/Mem:/{print $7}'); FREE_GB=${FREE_GB:-4}
AGENTS=$(( CORES/2 < FREE_GB/4 ? CORES/2 : FREE_GB/4 )); AGENTS=$(( AGENTS<1?1:(AGENTS>4?4:AGENTS) ))
echo "safe parallel agents: $AGENTS"

Use that as the ceiling; reduce further if the machine is already loaded.

Progress reporting (honest about visibility): Claude Code hooks are event-driven, not interval timers, and inside one chat turn the user does not see interleaved updates. So use both:
- Event hooks in settings.json — SubagentStop and Notification -> emit a progress line (the native, in-conversation signal).
- 30s heartbeat — a terminal/ntfy-side script for long runs (visible only if the user is watching the terminal or has ntfy configured), .cache/heartbeat.sh:
```
#!/usr/bin/env bash
# Report every 30s. Stop by deleting .cache/heartbeat.on
touch .cache/heartbeat.on
while [ -f .cache/heartbeat.on ]; do
  msg="[$(date +%H:%M:%S)] agents/tasks running... see .cache/ for progress"
  echo "$msg"
  command -v ntfy >/dev/null && ntfy send "$msg" || true   # optional, if ntfy is configured
  sleep 30
done
```

F7 — Mermaid rules (documentation and HTML presentation only)

Never put Mermaid in context files (CLAUDE.md, rules, memory). Diagrams belong in docs or the presentation HTML.
Pick the right chart type (flowchart, sequence, state, ER, gantt, class...) for the content.
Use official Mermaid syntax; check availability first — validate with a mermaid/context7 MCP if present, else a local mermaid CLI (mmdc); if neither exists, hand-verify against the official syntax and say so. (No mermaid/context7 MCP is assumed to be installed.)
No styling — no colors, fills, borders, classDef, or theme directives. Plain diagrams only.
For line breaks inside nodes/labels, use <br>.

F8 — Credentials

Never print, echo, log, or write passwords, tokens, keys, or .env contents — in any file, diagram, or presentation — unless the user explicitly asks. The block-secrets hook and deny reads enforce this.

F9 — Engineering standards (all generated code/config/content)

Architecture / design pattern: conform to the repo's existing pattern (detected in Phase 2). If none is evident (greenfield), choose one that fits the domain — DDD or Hexagonal / Ports-and-Adapters for rich domains with external integrations; Clean / layered or MVC for simpler CRUD — and record the choice + rationale in CLAUDE.md so future work stays consistent.
Conventions: follow the language's current, most widely-adopted style and idioms (the repo's linter/formatter wins where present). No dead patterns, no copy-paste cruft.
Dependency selection (state the why): before adding a framework/library, verify it is actively maintained (recent releases/commits), free of known high/critical CVEs (npm audit, pip-audit, osv-scanner, registry advisories), and widely adopted. Prefer the standard library or an existing dependency over adding a new one. Justify each new choice in one line.

Static version pinning (hard rule): never latest, never an unpinned range. Resolve the current stable numeric version at generation time (registry/advisories) — do not copy the example numbers below.

# bad:  FROM node:latest
# good: FROM node:<resolved 22.x.y>-bookworm-slim   # pinned numeric tag; prefer @sha256:<digest>

// bad:  "express": "latest"   |  "express": "*"   |  "express": "^4"
// good: "express": "<resolved 4.x.y>"             // exact numeric version + committed lockfile

Applies to images, frameworks, interpreters, libraries, and SDKs alike.

Keep pins patched (the pinning paradox): exact pins block automated security fixes, so also generate an update-bot config — renovate.json (preferred) or .github/dependabot.yml — that opens patch/minor PRs. Pinned + auto-bumped = stable and maintained.
Correctness & security: no obvious bugs, no introduced vulnerabilities; validate inputs, handle errors, never hardcode secrets (F8).

F10 — `find-gotcha-items` skill -> `.issues/NN_gotcha_YYYYMMDD.md`

A high-level analytical audit (in English) that surfaces gotchas — non-obvious traps, footguns, hidden coupling, silent failure modes, fragile assumptions, perf/security landmines — not line-by-line lint. .issues/ is committed (a shared risk register).

Deduplicate across runs (option a): before writing, read existing .issues/NN_gotcha_*.md. Log only new findings in the new dated file; do not restate still-open ones — reference them (see 01_gotcha_20260626.md#<title>). Re-flag a closed finding only if it has regressed.
find-gotcha-items skill — skills/find-gotcha-items/SKILL.md:

---
description: High-level audit that finds non-obvious gotchas/risks and logs them to .issues/
disable-model-invocation: true
argument-hint: [optional scope: path or subsystem]
---
First, if not already on the most capable model with extended thinking enabled, ask the user to switch
(`/model` -> Opus; enable thinking) and wait. Read existing `.issues/NN_gotcha_*.md` to avoid
duplicates. Then run a HIGH-LEVEL analysis (in English) of the repo (or the $ARGUMENTS scope) for
gotchas — non-obvious traps, not style nits:
- hidden coupling, implicit ordering/timing assumptions, race conditions;
- silent failure modes, swallowed errors, missing validation at boundaries;
- config/build/deploy footguns (env-specific behavior, floating versions, silent default fallbacks);
- security/perf landmines and fragile invariants.

Write ONE file `.issues/NN_gotcha_YYYYMMDD.md` (next sequence number, today's date via `date +%Y%m%d`)
containing only NEW findings; reference still-open prior findings instead of repeating them. For EACH
new finding:
- **Title** | **Severity** (critical/high/medium/low) | **Status: open**
- **Location** (file/area + evidence) | **Why it's a gotcha** (the non-obvious part)
- **Impact** | **Suggested mitigation**
Do not fix anything — analysis only. Never commit. `/update-context` keeps these statuses current.

Status lifecycle: open -> acknowledged -> mitigated -> resolved (or wont-fix). /update-context (F3 step 6) advances statuses as code changes; findings are updated, never deleted.

F11 — Persisted standing rules — `.claude/rules/operating.md` (committed, loads every session)

The permanent runtime rules must outlive this one-time bootstrap, so Phase 4 writes them here as a no-paths: rule (loads every session). Generate it in English:

# Operating rules (always apply)

## Language
- Reply to the user in Bahasa Indonesia; keep technical terms in English.
- All code, file names, variables, and comments are in English.

## Safety
- Never commit or push unless the user explicitly asks.
- Never print/echo/write passwords, tokens, keys, or .env contents unless the user explicitly asks.

## Files & workspace
- Temporary files, scripts, and scratch -> `.cache/` only (never elsewhere).
- Presentations -> one self-contained, mobile-responsive, EN/ID-toggle HTML in `.share/` (committed).
- Project plans -> `.plan/NN_name.md`; gotcha findings -> `.issues/NN_gotcha_YYYYMMDD.md` (English).
- Long docs / API specs -> `.claude/docs/`, referenced on demand — never inlined into CLAUDE.md.

## Engineering
- Follow the repo's architecture/pattern (recorded in CLAUDE.md); apply current popular conventions.
- New dependencies must be maintained, CVE-free, and justified; prefer stdlib/existing deps.
- Pin exact numeric versions (never `latest`); keep a lockfile + an update bot (Renovate/Dependabot).

## Diagrams
- Mermaid only in docs/HTML, never in context files. Right chart type, official syntax, no styling,
  `<br>` for line breaks.

## Investigation
- When asked to find out / verify / explain why, use EVIDENCE, not assumption: official docs (cited,
  with version) or a real experiment (run it, minimal repro in `.cache/`, check installed
  version/lockfile/source). Recall is a hypothesis, not evidence; label anything unverified as an
  assumption and never present a guess as fact.
- For heavy / self-contained investigations, delegate to a subagent so the main thread stays clean.

## Parallelism
- Use subagents only when there are >= 3 independent subtasks; cap concurrency to keep the machine safe.

F12 — Evidence-based investigation (rule + optional skill; not primarily an agent)

The norm is a rule (principle 27 + operating.md "Investigation"), so it applies to every "find out / why / does X" request — even casual ones — not only an explicit command. Evidence means: read official docs (cite source + version) or run a real experiment (execute, minimal repro, inspect output, check the installed version/lockfile/source). Recall from training is a hypothesis, not evidence; present-day facts (versions, APIs, behavior) must be verified. If evidence can't be obtained, say so and label the answer an assumption.

Optional investigate skill — skills/investigate/SKILL.md (for a repeatable, structured run):

---
description: Investigate a question with evidence (official docs or a real experiment), never assumption
disable-model-invocation: true
argument-hint: <question>
---
Answer "$ARGUMENTS" with EVIDENCE, not assumption:
1. State the hypothesis and what would confirm or refute it.
2. Gather evidence — official docs (fetch + cite source/version) and/or a real experiment (run a
   command or minimal repro in `.cache/`, capture output; check installed versions/lockfile/source).
3. Conclude only from what the evidence shows; cite each claim's source.
4. Label anything unverified as an assumption; if evidence is unobtainable, say so explicitly.
Do not edit project code while investigating — scratch goes in `.cache/`.

Agent? Only for heavy, isolated research — it is primarily a rule, not an agent. Spin up a read-only verifier/researcher subagent only when the investigation is large enough that its intermediate steps would clutter the main thread (deep doc dives, multi-file tracing). Small checks stay inline. The rule binds regardless of which path runs.

Appendix G — Golden example (validate your output against this)

A standard-depth BE-Engineer + team-baseline run on a TypeScript/Node service should produce roughly the tree below — use it to sanity-check a real run:

repo/
├── CLAUDE.md                      # summary, stack, commands, architecture, .claude/docs pointer
├── CLAUDE.local.md                # gitignored — git identity + Indonesian-reply directive
├── .mcp.json                      # github server (token via ${GITHUB_TOKEN})
├── renovate.json                  # auto-bump for pinned deps
├── .gitignore                     # + .cache/, settings.local.json, CLAUDE.local.md
├── .plan/                         # empty until /plan          (committed, English)
├── .issues/                       # empty until /find-gotcha-items (committed, English)
├── .share/                        # empty until /present       (committed — presentation HTML)
└── .claude/
    ├── settings.json              # allow build/test/lint + git read; deny rm -rf + cred reads; hooks
    ├── settings.local.json        # gitignored — personal overrides (trailer is default-on)
    ├── rules/
    │   ├── operating.md           # the persisted standing rules (F11)
    │   ├── api-design.md          # paths: src/api/** — validation, { data }|{ error }, rate limit
    │   └── testing.md             # paths: **/*.test.ts
    ├── docs/
    │   └── openapi.yaml           # or a pointer to the canonical spec — read on demand by api-design rule
    ├── skills/
    │   ├── update-context/SKILL.md
    │   ├── plan/SKILL.md
    │   ├── present/SKILL.md
    │   ├── find-gotcha-items/SKILL.md
    │   ├── add-endpoint/SKILL.md
    │   └── db-migration/SKILL.md
    ├── agents/
    │   ├── code-reviewer.md        # team baseline (Read, Grep, Glob)
    │   ├── api-reviewer.md         # (Read, Grep, Glob), memory: project
    │   └── query-optimizer.md
    ├── hooks/
    │   ├── block-secrets.sh        # +x
    │   └── format.sh               # +x
    └── agent-memory/
        └── api-reviewer/MEMORY.md  # seeded: endpoints, auth flow, conventions

With scope = personal, the role skills/agents land in ~/.claude/... instead; the committed .claude/ then holds only the team baseline (+ shared items if scope includes team).

End of CLAUDE_INIT.md — begin at Phase 0, run the Phase 1 interview, then scan.

ifundeasy/CLAUDE_INIT.md

CLAUDE_INIT.md

Role

Core principles

Personas at a glance (generation targets)

Phase 0 — Safety preconditions

Phase 1 — Interactive interview (ASK, then WAIT)

Phase 2 — Scan the whole project & derive artifacts

2A — Inventory (read-only: ls, cat, Read, Grep, Glob)

2B — Derive (the dynamic engine)

Phase 3 — Propose the plan (then STOP)

Phase 4 — Generate (after approval)

Phase 5 — Verify

Phase 6 — Summarize

Appendix A — Canonical structure & scope routing

Appendix B — Role → Artifacts matrix

Team baseline (committed .claude/) — role-neutral

FE Engineer (personal) — read-write · detect: React/Vue/Svelte/Angular, Tailwind/CSS-modules, Vite/Next, Storybook, Playwright/Cypress

BE Engineer (personal) — read-write · detect: Express/Fastify/Nest, Gin/net-http, FastAPI/Django, Spring; DB + migration tool; OIDC/JWT; REST/gRPC/GraphQL

DevOps/Infra/SRE (personal) — read-write with destructive-deny · detect: Terraform, Helm, Kustomize, k8s manifests, Ansible, CI workflows, Dockerfiles

QA (personal) — read-write, test-scoped (treat src/ as read-reference)

TL/SL/PM (personal) — read-mostly (writes limited to docs/ADRs)

EM (personal) — read-only

Head (personal) — read-only · department / multi-team altitude

Chief (personal) — read-only · org / board altitude

Business & finance band (personal) — read-only; reports/docs via doc-writer

FinOps (personal) — read-only · detect: IaC cost drivers, cloud billing exports (CSV/JSON), cost dashboards, tagging/labeling

Finance (personal) — read-only (reports via doc-writer) · detect: financial models, budgets/forecasts, spreadsheets, finance docs

Accounting (personal) — read-only (workpapers via doc-writer) · detect: ledger/GL exports, reconciliation files, transaction data, accounting docs

Operational (personal) — read-only (docs via doc-writer) · detect: SOPs/runbooks, process docs, vendor/contract docs, operational data exports

Appendix C — Evidence → Artifact derivation (existing-project engine)

Appendix D — Templates (resolve {{PLACEHOLDER}})

Generic skill — skills/<name>/SKILL.md

Generic agent — agents/<name>.md

Seeded subagent memory — agent-memory/<agent>/MEMORY.md

Output style — output-styles/<name>.md (personal)

CLAUDE.md

.claude/settings.json (team baseline)

.claude/hooks/block-secrets.sh

.claude/hooks/guard-destructive.sh (DevOps/Infra/SRE)

.claude/hooks/format.sh

.claude/rules/<topic>.md

MCP — team scope (.mcp.json) vs personal

.gitignore additions