# CLAUDE.md Template

Template for project-root `CLAUDE.md` — auto-generated by `ferrox-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
```
<!-- Ferrox:project-start source:PROJECT.md -->
## Project

{{project_content}}
<!-- Ferrox:project-end -->
```

**Fallback text:**
```
Project not yet initialized. Run /ferrox:new-project to set up.
```

### Stack Section
```
<!-- Ferrox:stack-start source:STACK.md -->
## Technology Stack

{{stack_content}}
<!-- Ferrox:stack-end -->
```

**Fallback text:**
```
Technology stack not yet documented. Will populate after codebase mapping or first phase.
```

### Conventions Section
```
<!-- Ferrox:conventions-start source:CONVENTIONS.md -->
## Conventions

{{conventions_content}}
<!-- Ferrox:conventions-end -->
```

**Fallback text:**
```
Conventions not yet established. Will populate as patterns emerge during development.
```

### Architecture Section
```
<!-- Ferrox:architecture-start source:ARCHITECTURE.md -->
## Architecture

{{architecture_content}}
<!-- Ferrox:architecture-end -->
```

**Fallback text:**
```
Architecture not yet mapped. Follow existing patterns found in the codebase.
```

### Skills Section
```
<!-- Ferrox:skills-start source:skills/ -->
## Project Skills

| Skill          | Description           | Path                      |
| -------------- | --------------------- | ------------------------- |
| {{skill_name}} | {{skill_description}} | `{{skill_path}}/SKILL.md` |
<!-- Ferrox: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 Ferrox's own installed skills (directories starting with `ferrox-`)
- Deduplicates by skill name across directories

### Workflow Enforcement Section
```
<!-- Ferrox:workflow-start source:Ferrox defaults -->
## Ferrox Workflow Enforcement

Start work through a Ferrox command rather than editing directly, so planning artifacts and execution context stay in sync.

Match the user's situation to the entry point:

| When the user... | Route to |
|---|---|
| describes something new to build, or has an idea and no plan yet | `/ferrox:new-project` |
| says build it, build it all, or asks what is next | `/ferrox:progress` `--next` (add `--auto` to keep going) |
| states an intent in plain words and you are unsure where it goes | `/ferrox:next` `"<their words>"` |
| wants the next step planned in detail | `/ferrox:plan-phase` |
| wants the current step built | `/ferrox:execute-phase` |
| asks whether it works, or wants to try it | `/ferrox:verify-work` |
| reports something broken, failing or wrong | `/ferrox:debug` |
| wants the work sent, released or PR'd | `/ferrox:ship` |
| wants the last step reversed | `/ferrox:undo` |
| asks for a small self contained change | `/ferrox:quick` |

There are 74 commands; `/ferrox:help` lists them. The 10 above cover almost everything.

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

### Profile Section (Placeholder Only)
```
<!-- Ferrox:profile-start -->
## Developer Profile

> Profile not yet configured. Run `/ferrox:profile-user` to generate your developer profile.
> This section is managed by `generate-claude-profile` — do not edit manually.
<!-- Ferrox: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 Ferrox entry points for file-changing work
7. **Profile** — Developer behavioral preferences (how to interact)

## Marker Format

- Start: `<!-- Ferrox:{name}-start source:{file} -->`
- End: `<!-- Ferrox:{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