msd-core/get-shit-done/templates/claude-md.md

CLAUDE.md Template

Template for project-root CLAUDE.md — auto-generated by gsd-tools generate-claude-md.

Contains 7 marker-bounded sections. Each section is independently updatable. The generate-claude-md subcommand manages 6 sections (project, stack, conventions, architecture, skills, workflow enforcement). The profile section is managed exclusively by generate-claude-profile.

---

Section Templates

Project Section

<!-- GSD:project-start source:PROJECT.md -->
## Project

{{project_content}}
<!-- GSD:project-end -->

Fallback text:

Project not yet initialized. Run /gsd-new-project to set up.

Stack Section

<!-- GSD:stack-start source:STACK.md -->
## Technology Stack

{{stack_content}}
<!-- GSD:stack-end -->

Fallback text:

Technology stack not yet documented. Will populate after codebase mapping or first phase.

Conventions Section

<!-- GSD:conventions-start source:CONVENTIONS.md -->
## Conventions

{{conventions_content}}
<!-- GSD:conventions-end -->

Fallback text:

Conventions not yet established. Will populate as patterns emerge during development.

Architecture Section

<!-- GSD:architecture-start source:ARCHITECTURE.md -->
## Architecture

{{architecture_content}}
<!-- GSD:architecture-end -->

Fallback text:

Architecture not yet mapped. Follow existing patterns found in the codebase.

Skills Section

<!-- GSD:skills-start source:skills/ -->
## Project Skills

| Skill          | Description           | Path                      |
| -------------- | --------------------- | ------------------------- |
| {{skill_name}} | {{skill_description}} | `{{skill_path}}/SKILL.md` |
<!-- GSD:skills-end -->

Fallback text:

No project skills found. Add skills to any of: `.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, or `.github/skills/` with a `SKILL.md` index file.

Discovery behavior:

• Scans .claude/skills/, .agents/skills/, .cursor/skills/, .github/skills/ for subdirectories containing SKILL.md
• Extracts name and description from YAML frontmatter (supports multi-line descriptions)
• Skips GSD's own installed skills (directories starting with gsd-)
• Deduplicates by skill name across directories

Workflow Enforcement Section

<!-- GSD:workflow-start source:GSD defaults -->
## GSD Workflow Enforcement

Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.

Use these entry points:
- `/gsd-quick` for small fixes, doc updates, and ad-hoc tasks
- `/gsd-debug` for investigation and bug fixing
- `/gsd-execute-phase` for planned phase work

Do not make direct repo edits outside a GSD workflow unless the user explicitly asks to bypass it.
<!-- GSD:workflow-end -->

Profile Section (Placeholder Only)

<!-- GSD:profile-start -->
## Developer Profile

> Profile not yet configured. Run `/gsd-profile-user` to generate your developer profile.
> This section is managed by `generate-claude-profile` — do not edit manually.
<!-- GSD:profile-end -->

Note: This section is NOT managed by generate-claude-md. It is managed exclusively by generate-claude-profile. The placeholder above is only used when creating a new CLAUDE.md file and no profile section exists yet.

---

Section Ordering

1. Project — Identity and purpose (what this project is)
2. Stack — Technology choices (what tools are used)
3. Conventions — Code patterns and rules (how code is written)
4. Architecture — System structure (how components fit together)
5. Skills — Discovered project skills with name and description (what domain knowledge is available)
6. Workflow Enforcement — Default GSD entry points for file-changing work
7. Profile — Developer behavioral preferences (how to interact)

Marker Format

• Start: <!-- GSD:{name}-start source:{file} -->
• End: <!-- GSD:{name}-end -->
• Source attribute enables targeted updates when source files change
• Partial match on start marker (without closing -->) for detection

Fallback Behavior

When a source file is missing, fallback text provides Claude-actionable guidance:

• Guides Claude's behavior in the absence of data
• Not placeholder ads or "missing" notices
• Each fallback tells Claude what to do, not just what's absent