| name | engrave |
| description | Use when the user asks to generate, update, or refresh project documentation, CLAUDE.md, context files, or scoped rules. Creates Claude-optimized documentation with a short CLAUDE.md (<200 lines), detailed docs/CONTEXT.md, and path-scoped rules. |
/engrave — Documentation Generator
You are PolyForge's documentation generator. Create documentation optimized for Claude Code.
Usage
/engrave Generate all documentation
/engrave --claude-md Only update CLAUDE.md
/engrave --context Only update docs/CONTEXT.md
/engrave --rules Only update .claude/rules/
What Gets Generated
CLAUDE.md — under 200 lines strict. Every line must pass: "Would removing this cause Claude to make mistakes?" If no, cut it.docs/CONTEXT.md — detailed architecture, dependencies, data flow, key patterns, quirks. No size limit..claude/rules/ — scoped rule files with paths: frontmatter.
Process
Step 1: Analyze Project
Spawn [model: sonnet] subagent to scan and return structured JSON only:
{ "stack": {}, "entryPoints": [], "architecture": "", "patterns": [], "conventions": [], "envVars": [], "knownQuirks": [], "keyFiles": [], "testFrameworks": [] }
Subagent reads: entry points, config files, main modules, existing docs. Discard raw scan data — use only the JSON.
Step 2: Handle Existing Files
- Doesn't exist → create
- Exists with PolyForge marker → update in-place
- Exists without marker → call
AskUserQuestion with options: "Merge" / "Keep + create separate" / "Replace (backup to tmp/)" / "Other"
Step 3: Generate
Show preview with file names and line counts. Then call AskUserQuestion — "Generate these files?" with options: "Generate all" / "Preview one file" / "Cancel" / "Other". See @skills/shared/common-patterns.md § "User Questions — AskUserQuestion ONLY".
Generate each file from structured summary. Compact between files.
CLAUDE.md — only: build/test/lint commands, architecture, non-obvious conventions, @ refs to detailed docs. Include PolyForge commands list.
.claude/rules/ — scope with paths: frontmatter. Positive assertions, one per line.
Update lastUpdatedAt in .claude/polyforge.json. Compact after final file.
