generate-claude-md

Generate CLAUDE.md

Generate or update a project's CLAUDE.md by rendering the Digital Service Orchestra template with project-specific command values from workflow-config.yaml.

Usage

/dso:generate-claude-md              # Generate CLAUDE.md for current directory
/dso:generate-claude-md [project-dir] # Generate for a specific project directory

---

Steps

Step 1: Read Config

Load the project's command values via read-config.sh (located at .claude/scripts/dso read-config.sh):

PLUGIN_SCRIPTS="${CLAUDE_PLUGIN_ROOT}/scripts"

VALIDATE_CMD=$(bash "$PLUGIN_SCRIPTS/read-config.sh" commands.validate)  # shim-exempt: internal orchestration script
FORMAT_CMD=$(bash "$PLUGIN_SCRIPTS/read-config.sh" commands.format)  # shim-exempt: internal orchestration script
TEST_CMD=$(bash "$PLUGIN_SCRIPTS/read-config.sh" commands.test)  # shim-exempt: internal orchestration script
LINT_CMD=$(bash "$PLUGIN_SCRIPTS/read-config.sh" commands.lint)  # shim-exempt: internal orchestration script

Resolution order used by read-config.sh:

1. workflow-config.yaml at $(pwd)/workflow-config.yaml (project root — most common)
2. Make target fallback: if config is absent or key is empty, fall back to make <target> convention
3. Skip with warning if neither config nor make target found

Step 2: Load Template

Read the CLAUDE.md template from the plugin:

TEMPLATE_FILE="${CLAUDE_PLUGIN_ROOT}/templates/CLAUDE.md.template"
TEMPLATE_CONTENT=$(cat "$TEMPLATE_FILE")

Step 3: Substitute Placeholders

Replace {{key}} placeholders with resolved config values using sed or bash parameter expansion:

GENERATED=$(echo "$TEMPLATE_CONTENT" \
  | sed "s|{{commands.validate}}|${VALIDATE_CMD}|g" \
  | sed "s|{{commands.format}}|${FORMAT_CMD}|g" \
  | sed "s|{{commands.test}}|${TEST_CMD}|g" \
  | sed "s|{{commands.lint}}|${LINT_CMD}|g")

All placeholder tokens use the {{commands.validate}}, {{commands.format}}, {{commands.test}}, and {{commands.lint}} format (mustache-style double braces).

Step 4: Generate Quick Reference Table

The Quick Reference table in the rendered output maps each workflow action to the project-specific command resolved from config. Example output for a python-poetry project:

Action	Command	When Run
Validate all	.claude/scripts/dso validate.sh --ci	Runs automatically at start of /dso:sprint
Format code	make format	Only if auto-format hook reports failure
Run tests	make test	Before pushing, CI
Lint	make lint	After creating classes

Step 5: Merge Strategy

To merge the generated output with an existing CLAUDE.md, preserve the following project-specific sections from the existing file:

• ## Architecture — stack, pipeline, patterns, env vars
• ## Critical Rules > Architectural Invariants — project-specific structural boundaries
• ## Task Start Workflow — project-specific start flow
• ## Multi-Agent Orchestration — project-specific sub-agent rules
• ## Common Fixes — project-specific troubleshooting table
• Any other sections not present in the template

Replace or update the following generated sections:

• ## Quick Reference — command table (always replace from generated output)
• ## Working Directory & Paths — standard guidance (replace from generated output)
• ## Critical Rules > Never Do These — workflow safety rules (replace from generated output)
• ## Critical Rules > Always Do These — workflow rules (replace from generated output)

The generated sections are delimited by:

<!-- === GENERATED BY /dso:generate-claude-md — DO NOT EDIT MANUALLY ===
...
=== END GENERATED HEADER === -->

Do not overwrite content outside these delimiters without user confirmation.

Step 6: Write Output

Write the generated sections to stdout with clear section markers, then offer to write to CLAUDE.md:

=== GENERATED BY /dso:generate-claude-md ===
[rendered content]
=== END GENERATED CONTENT ===

Ask: "Write this to CLAUDE.md in [project-dir]? (yes/no/preview-diff)"

If the user confirms, write the file. If CLAUDE.md already exists, show a diff of what will change before writing.

---

Escalation Triggers

Escalate to the user (do not proceed autonomously) when:

1. Missing 'Never Do These' rules — if the template does not contain all required safety rules, report which rules are absent and ask the user to update the template before generating.
2. Wrong Quick Reference commands — if a resolved command is empty or falls back to a bare make placeholder that does not match the project's actual toolchain, ask the user to update workflow-config.yaml first.
3. Merge strategy would overwrite project-specific sections — if CLAUDE.md contains custom content in Quick Reference or Never Do These sections that would be lost, show a diff and require explicit user confirmation before proceeding.
4. Template file missing — if ${CLAUDE_PLUGIN_ROOT}/templates/CLAUDE.md.template does not exist, report the missing path and abort.

---

Error Handling

Situation	Response
workflow-config.yaml not found	Use make-convention fallbacks; warn user that no config was found
Template file missing	Report missing path, abort
Commands resolve to empty string	Report which commands are empty, escalate to user
CLAUDE.md already exists	Show diff, require confirmation before overwrite
Merge would lose project-specific sections	Escalate, do not proceed without user confirmation