craft-project-setup

# Craft CMS Project Setup

Scaffold Claude Code configuration for Craft CMS projects. Generates a `CLAUDE.md` and `.claude/rules/` directory tailored to the project type.

## Companion Skills — Used During Scaffolding

This skill generates configuration that references other skills. It does not load them at activation, but the generated CLAUDE.md and rules will guide users toward:

- **`craftcms`** + **`craft-php-guidelines`** + **`craft-garnish`** — for plugin and module projects (craft-garnish when plugin has CP JavaScript/asset bundles)
- **`craft-site`** + **`craft-twig-guidelines`** + **`craft-content-modeling`** — for site projects
- **`ddev`** — for all project types (DDEV commands in generated config)

## Workflow

### Step 1: Detect the project

Read the project root to determine what exists. **Detect, don't assume.** Every piece of information below should be resolved by reading actual project files — never flag something as "unknown" when the answer is in `composer.json`, `package.json`, `.ddev/config.yaml`, or `git` state.

#### Project structure signals

- `.ddev/config.yaml` — DDEV project name, PHP version, database type, Node version
- `composer.json` — package type (`craft-plugin`, `craft-module`, or `project`), dependencies, scripts (check-cs, phpstan, pest)
- `src/` or `src/Plugin.php` — plugin source directory
- `templates/` — site templates
- `config/project/` — Craft project config (indicates a site)
- `config/general.php` — Craft general config
- `modules/` — custom modules
- `craft-cloud.yaml` at the repo root — **Craft Cloud project.** When present, include the `craft-cloud` skill in the generated CLAUDE.md companion-skill list and add a "Hosted on Craft Cloud" note in the generated project context. See the `craft-cloud` skill's `config-file.md` for the file's role.
- `servd.yaml` at the repo root, or `servd/craft-asset-storage` in `composer.json`, or `SERVD_PROJECT_SLUG`/`SERVD_SECURITY_KEY` env vars — **Servd project.** When present, include the `servd` skill in the generated CLAUDE.md companion-skill list and add a "Hosted on Servd" note in the generated project context. See the `servd` skill for the platform's constraints.

#### Dependency detection (from composer.json `require` and `require-dev`)

Scan `composer.json` dependencies to auto-detect capabilities. Never ask the user about things you can read:

| Package | What it tells you |
|---------|------------------|
| `nystudio107/craft-seomatic` | SEOmatic installed — `???` operator is available, meta tags handled |
| `nystudio107/craft-empty-coalesce` | `???` operator available (standalone) |
| `nystudio107/craft-vite` | Vite buildchain with nystudio107 bridge |
| `putyourlightson/craft-blitz` | Static caching — affects CSRF, template caching strategy |
| `putyourlightson/craft-sprig` | Sprig/htmx available for reactive components |
| `verbb/formie` | Formie form builder installed |
| `craftcms/ckeditor` | CKEditor for rich text |
| `ether/seo` | Alternative SEO plugin (not SEOmatic) |
| `craftcms/phpstan-package` or `phpstan/phpstan` | PHPStan available |
| `symplify/easy-coding-standard` | ECS available |
| `pestphp/pest` | Pest testing framework |
| `craftcms/cloud` | **Project hosted on Craft Cloud.** Load the `craft-cloud` companion skill; document Cloud-specific build, deploy, and runtime constraints in the generated CLAUDE.md. |
| `servd/craft-asset-storage` | **Project hosted on Servd.** Load the `servd` companion skill; document Servd's deploy workflow, ephemeral filesystem, static caching, and asset storage in the generated CLAUDE.md. |

Also check `composer.json` `scripts` section for `check-cs`, `phpstan`, `test`, `pest` commands.

#### Front-end detection (from package.json, config files)

- `package.json` — Tailwind version (v3 vs v4), Alpine.js, Vue, build tool (Vite vs Webpack)
- `tailwind.config.*` or `@tailwind` in CSS files — Tailwind v3
- `@theme` in CSS files — Tailwind v4
- `vite.config.*` — Vite configuration
- `templates/_atoms/`, `_molecules/`, `_organisms/` — atomic design patterns

#### Git detection

- `git branch --show-current` — current branch name
- `git remote -v` — remote URL
- `git log --oneline -10` — recent commit style (conventional commits? prefixed?)
- Default branch: check `git symbolic-ref refs/remotes/origin/HEAD` or look at branch names. Common patterns: `main`, `master`, `develop`

#### Chrome DevTools MCP detection

- Check `.claude.json` for existing MCP configuration
- If not present, ask: "Would you like to install Chrome DevTools MCP for browser debugging? Enables inspecting CP templates, front-end pages, console errors, and visual testing."
- If yes: run `claude mcp add chrome-devtools -- npx chrome-devtools-mcp@latest` and note session restart is needed

From these signals, determine the project type:

| Signal | Type |
|--------|------|
| `composer.json` type is `craft-plugin` | **Plugin** |
| `composer.json` type is `craft-module` | **Module** |
| `config/project/` exists, `templates/` exists | **Site** |
| Site signals + `modules/` directory | **Hybrid** (site + custom module) |
| Multiple Craft packages/projects in subdirectories | **Monorepo** (see below) |

#### Monorepo detection

A monorepo holds **more than one independently-typed Craft package** under one repository. Confirm at least one of these signals before classifying as monorepo — a single project with a `modules/` folder is a **Hybrid**, not a monorepo:

- **Multiple `composer.json` in subtrees with Craft types.** Run `find . -name composer.json -not -path '*/vendor/*' -not -path '*/node_modules/*'` and check the `type` of each. Two or more with `craft-plugin`, `craft-module`, or `project` (in distinct directories, not the repo root alone) means monorepo.
- **Root `composer.json` with path repositories.** A root `composer.json` whose `repositories` array contains `{ "type": "path", "url": "packages/*" }` (or similar) wiring local packages together.
- **Workspace layout.** A `packages/`,