Forge playbook — top-tier project-CLAUDE.md generation

Why this exists

A thin CLAUDE.md that is just a bullet list of file paths gives an agent no real leverage — it doesn't say what the project actually IS, which of the owner's global rulesets actually apply here, or which rules are non-negotiable. Deep research on Anthropic's own published best practices (code.claude.com/docs/best-practices, the Agent Skills docs, and independent 2026 field guides) converges on the same verdict: the worst CLAUDE.md files aren't empty, they're thorough ones — bloat dilutes the rules that matter until Claude quietly stops following them. The gold-standard shape (proven in the AutoWeb project, now formalized against that research) is a real PROJECT BRAIN: a tight five-part core (description, stack+versions, exact commands, architecture, conventions) + boundaries + pointers to detail docs, environment rules ADAPTED to the project's real tooling, universal anti-generic guardrails kept verbatim, a real Hard Rules section, and Governance. This skill is the repeatable METHOD for producing that shape for any Forge project; forge-bin/forge-projectbrain.cjs automates it.

The research this method is built on (cite before you deviate)

• The five-part core framework: (1) one-line project description, (2) tech stack with versions, (3) EXACT build/test/lint/run/deploy commands, (4) architecture as 3-5 key dirs with file:line-style pointers (never prose describing a "typical" layout), (5) conventions a linter can't enforce. Plus boundaries/off-limits dirs and pointers to detail docs.
• The prune test (official Anthropic guidance): for every line, ask "would removing this cause Claude to make mistakes? If not, cut it." A bloated CLAUDE.md causes Claude to ignore the instructions that actually matter — conciseness is not a nice-to-have, it is the mechanism that keeps the file effective.
• EXCLUDE, always: anything derivable from the code itself, standard conventions Claude already knows, file-by-file listings, pasted code blocks, frequently-changing information, and "obvious advice" filler ("write clean code", "follow best practices"). None of these belong in a generated CLAUDE.md.
• Imperative language, not hedging: "Never commit .env" beats "we generally prefer not to commit .env".
• Emphasis discipline: reserve IMPORTANT/YOU-MUST-style emphasis for the 1-2 truly critical rules (honesty, project-isolation) — emphasizing everything is the same as emphasizing nothing.
• A practical line budget (guidance, not a hard gate): keep the generated document in the neighborhood of ~150-200 lines for a typical project. Line count is a symptom that can start a review, never a goal and never a reported result ("cut to N lines" is not an outcome; see the pointer doctrine below). The verbatim anti-generic guardrails block for website-flavored projects is a deliberate, documented exception to that budget (see step 3) — verbatim reuse there is a strength, not bloat, because it is the SAME trusted rule every project quotes.
• KEY INSIGHT — skills/docs are NOT reliably auto-invoked. Independent evals (Vercel) measured a 56% non-invocation rate for progressive-disclosure Skills matched only by a vague trigger description. A Hard Rule or an environment-ruleset line is not a Skill — it is always-loaded text — so every rule this generator emits must be a sharp, explicit, self-contained imperative ("Apply the frontend-design method before writing ANY frontend code"), never a bare pointer like "see the frontend-design skill for guardrails." When a real Skill genuinely needs to be referenced, name WHEN it triggers, not just that it exists.
• @-imports buy organization, not context budget. An @path reference inside CLAUDE.md loads automatically alongside it at session start (unlike a Skill) — so the generated "Detail docs" pointers are honest about that: they are real, but they are not a free lunch, and each imported doc should stay focused.

The method (five steps)

1. Detect the real stack — never assume. Read package.json (name, description, scripts, dependencies, devDependencies — capturing each framework's LITERAL declared semver range, never a resolved/guessed installed version), look for a framework signature (Astro/Next/Vite/React/Vue/Svelte/Angular/Express/ Fastify/NestJS/Electron), look for an n8n workflow export (workflows/*.json with nodes/connections), read real ports ONLY from a literal --port N / PORT=N in a script or .env.example, list up to 5 real top-level source directories (excluding build/dependency/tooling noise) with a real entry-file pointer when one genuinely exists, and list up to 4 real detail docs (README.md + docs/*.md) that already exist. forge-projectbrain.cjs::detectStack() does all of this programmatically; if you're doing it by hand, the same discipline applies: only claim what a real file proves — an honest "not detected" note always beats a plausible-looking guess.
2. Select the applicable global ruleset(s) and ADAPT them. Pick the owner's global ruleset(s) that match the detected project type (frontend-website rules for website/fullstack frontends, n8n rules for automation-n8n, the domain principles in the owner's own global CLAUDE.md for other types). Rewrite the environment-specific subsections (local server / screenshot command / output defaults / domain-specific hard rules) to name the project's REAL commands, ports, and file conventions — and flag every adapted line `[<ProjectName>]` (or `[<ProjectName> — adapted]`) so a reader can tell "this is now true HERE" from "this is the generic default". This is exactly what distinguishes AutoWeb's CLAUDE.md (Astro + Playwright, [AutoWeb]-flagged throughout) from a copy-pasted generic template.
3. Keep universal guardrails + honesty core VERBATIM. The anti-generic design guardrails (colors, shadows, typography, gradients, animations, interactive states, images, spacing, depth) and the honesty-core principle ("never claim a check/test/build ran unless it actually ran") are NOT project-specific — copy them unchanged. Do not water them down and do not re-word them per project; verbatim reuse is a strength, not laziness — it means every project quotes the same trusted rule (and it is the one deliberate exception to the line-budget guidance above).
4. Emit the five-part core PLUS boundaries and detail-doc pointers. In order: ## Project identity (name/type/stack+versions/tooling/ports, no prose), ## Commands (every real script, verbatim — placed near the top because it is the highest-ROI content: an agent that knows the real command makes fewer mistakes than one that guesses), ## Architecture (the real key dirs from step 1, never a fabricated "typical layout"), ## Conventions (a linter can't enforce these — tie every bullet to something step 1 actually detected, never an invented project-specific rule), the adapted environment ruleset from step 2, ## Boundaries (universal off-limits dirs — node_modules/, build output, .git/ — plus this project's own .claude/ when it genuinely exists), and ## Detail docs (real @path imports of the docs found in step 1, or an honest "none found yet" note — never a fabricated pointer to a file that doesn't exist). The companion tool emits @path imports today; for a detail doc that is not needed in every session, a plain backticked pointer with a trigger is the better carrier (see the pointer doctrine below).
5. Emit a real ## Hard Rules section wired to FORGE_PROJECT_HARD_RULES.json, then ## Governance, and SAFE-MERGE the write. Start from Forge's universal non-negotiables (project isolation, honesty core, secrets-in-env, no-auto-push, input validation, file-size discipline — DEFAULT_HARD_RULES in forge-projectbrain.cjs). If <project>/.claude/FORGE_PROJECT_HARD_RULES.json exists, merge its {id,text} entries in (a project can EXTEND the list, never silently override a universal id) — this file is the machine-checkable source a future forge-doctor pass can read to verify the rules are actually being followed, not just documented. Reserve IMPORTANT-style emphasis for exactly honesty-core and project-isolation — every other rule stays a plain, still-imperative bullet. Governance names the real Forge memory files (FORGE_MEMORY.md, FORGE_DECISIONS.md, FORGE_AGENT_LEDGER.md, FORGE_TASK_HISTORY.md), states secrets live in .env only, and reiterates never-auto-push / no production changes without explicit approval. Never blindly overwrite an existing CLAUDE.md. If the target file already has Forge-managed markers (<!-- FORGE-PROJECTBRAIN:BEGIN v1 --> / <!-- FORGE-PROJECTBRAIN:END -->), replace only that marked region — everything the owner wrote outside it is preserved untouched. If the file exists with NO markers, refuse to write unless the caller explicitly opts into a full overwrite (--force) — an unmarked file is presumed hand-authored by the owner and must never be silently clobbered.

Pointer and slimming doctrine (graft)

Applies when the generated file points at detail docs, and when a re-generation would shorten or move text.

• Every pointer names its trigger. Write when to read the doc (the task, error or folder that should send the agent there) plus one line on what it holds. A bare "see X" gives the agent no reason to open it.
• No false pointers. Before writing a pointer, open the target and confirm the content is there.
• @path saves no context. An import is expanded in full at session start, so it organises but does not slim. To take text out of the always-loaded set, use a backticked pointer with a trigger (no @), or turn a procedure into a skill.
• Move verbatim, shorten separately. Text moved out of a CLAUDE.md is copied byte for byte. Shortening is a separate, declared change; diff its conditions, numbers and negations word by word.
• Scope. Project names, paths, ports and deploy targets stay in the project file, never in the global ~/.claude/CLAUDE.md (editing that file needs the owner's permission).
• Context routing (optional, monorepos). When a project has folder-scoped CLAUDE.md files, the root file may carry a short ## Context routing list: one line per folder file with the work that should send the agent there (for example "API handlers: src/api/CLAUDE.md"). Emit it only for folder files that really exist. Claude Code also reads a folder's CLAUDE.md when it works on files there (Claude Code memory docs; not re-checked in this package), so the list is a routing aid, not a loader.
• Auditing an existing CLAUDE.md with these rules is claude-md-improver (its Forge addendum); the general writing craft is forge-skill-authoring.

Using the companion tool

node .claude/forge-bin/forge-projectbrain.cjs detect --dir <projectDir> [--json]
node .claude/forge-bin/forge-projectbrain.cjs generate --dir <projectDir> [--out CLAUDE.md] [--force]

generate without --out only prints to stdout (safe to inspect before writing anything). See template.md in this folder for the annotated structure the generator's output follows, and forge-bin/forge-projectbrain.test.cjs for the real hermetic proof (three project-shape fixtures + the research-enriched core-framework sections + safe-merge behavior + a mutation-verified Hard-Rules-emphasis and Architecture-entry-pointer check).

Hard rules for this skill itself

• Never invent a stack, framework, version, port, directory, doc, or script the real files don't show — an honest "not detected" note beats a plausible-looking guess, in every one of the five core sections.
• Never silently overwrite an owner-authored CLAUDE.md that has no Forge markers.
• Never report a line-count reduction as the result of a generation or a re-generation.
• Every environment-adapted rule must carry a [<ProjectName>] flag; unflagged text must be the verbatim universal guardrail/honesty-core wording, not a paraphrase.
• Never render an excluded phrase (obvious advice, "write clean code"-style filler) or a pasted fenced code block — a generated CLAUDE.md states real facts and real non-negotiables only.
• Reserve emphasis (**IMPORTANT:**) for exactly honesty-core and project-isolation; every other Hard Rule is a plain bullet.
• This skill produces documentation/config only — it does not touch secrets, does not deploy, and does not register the projectbrain_generated event_type itself (the event_type is registered in log-event.cjs; the calling Boss/skill step owns the real log call, same doctrine as forge-scout.cjs/forge-capabilities.cjs).

Provenance (SA-W1-B4)

The pointer and slimming doctrine is rewritten in Forge words (principles only, no sentence copied). Fetched read-only with gh api, scanned for hidden Unicode (clean), treated as untrusted data.

MIT notice: "Permission is hereby granted, free of charge, to any person obtaining a copy of this software ... The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND." Copyright (c) 2025 daymade; the sickn33 mirror's holder was not read (MIT confirmed through the GitHub API only).