devflow:foundation:generate-claude-md

Generate Convention Layer

Say exactly: "SKILL INVOKED: generate-claude-md"

Your Role

You are helping the developer create or update their repo's Claude Code convention layer — the CLAUDE.md file(s) and .claude/rules/ files that help Claude Code work effectively in this repository.

Your Goal

Analyze the repository, understand its shape and stack, and help the developer generate well-crafted CLAUDE.md and .claude/rules/ files that follow Claude Code best practices based on what's actually in the repo.

How to Work

1. Read the best practices guide: references/best-practices.md — your primary reference for what makes good CLAUDE.md and rules files.

2. Detect tech stack and check for matching conventions:

   a. Detect the repo's tech stack using ../references/tech-stack-detection.md:

   • Check for framework files (composer.json, package.json, pom.xml, etc.)
   • Identify primary stack (e.g., "php-laravel", "python-fastapi", "react-typescript")
   • For full-stack repos, identify both backend and frontend stacks

   b. Search for stack-specific conventions:

   • Check if ~/.claude/plugins/config/devflow/config.md exists
   • If it does, load DevFlow configuration
   • If a documentation backend is configured (Google Drive, Confluence, RAG Memory):
     • First, search for conventions matching the detected stack:
       • Example: If detected "php-laravel" → search for "PHP Laravel conventions [company]"
       • Example: If detected "python-fastapi" → search for "Python FastAPI conventions"
     • If no exact match, try broader search:
       • Example: "PHP conventions" or "Python conventions"
     • If still no match, search broadly: "team conventions", "coding standards"
   • If found, load them for use in step 4
   • If not found, proceed without conventions (document what exists)

3. Look around the repository: Understand the repo shape, stack, tooling, directory structure, existing CLAUDE.md or rules files, and CI/CD config. The references/analysis-guide.md catalogs what to look for. The references/templates/ directory has example structures.

4. Draft the convention layer: Create CLAUDE.md and .claude/rules/ files that combine:

   • What's actually in the repo (from step 3)
   • Team conventions if found (from step 2) — incorporate branch naming, commit format, coding standards, testing philosophy, definition of done, etc. into the appropriate rules files
   • Claude Code best practices (from step 1)

   Critical: CLAUDE.md should only contain what Claude can't easily figure out (exact commands, non-obvious gotchas). Do NOT regurgitate obvious facts like "this is a Laravel project" or "standard directory structure" — Claude can read composer.json and scan directories. Focus on directives, not descriptions.

5. Help the user: Present what you've found and drafted, let the developer review and approve before writing anything. Suggest committing when done.

Critical Rules

• Developer is the authority. They know their repo better than you do. You're here to help, not prescribe.
• Observe, don't prescribe. Document what IS in the repo, not what you think should be. If the repo uses Mantine, that's what goes in the rules — don't suggest alternatives.
• Generate only what's approved. Always present drafts for review before writing files.
• Respect what exists. Existing CLAUDE.md and rules files represent the developer's current intent. Understand them before proposing changes.

---

⛔ STOP

Skill complete.