Skip to content

CLAUDE.md

Latest commit

 

History

History
90 lines (70 loc) · 4.21 KB

CLAUDE.md

File metadata and controls

90 lines (70 loc) · 4.21 KB
Raw

Claude Code — laravel-spatie-event-sourcing

What this repo is

A Claude Code skill that generates event-sourced domain code for Laravel using spatie/laravel-event-sourcing. The repo is packaged as an installable plugin marketplace; the skill is the single source of truth and lives in plugins/laravel-spatie-event-sourcing/skills/laravel-spatie-event-sourcing/.

Repo layout

.claude-plugin/
  marketplace.json      — Marketplace catalog (marketplace name: albertoarena)
plugins/laravel-spatie-event-sourcing/
  .claude-plugin/
    plugin.json         — Plugin manifest (name, description, version, author)
  skills/laravel-spatie-event-sourcing/   — canonical skill source
    SKILL.md            — Main skill file (frontmatter + instructions)
    references/         — Design heuristics, ADR template, TDD patterns, API cheatsheet
    assets/templates/   — .stub files for code generation
    scripts/            — verify-setup.sh (project bootstrap)
examples/orders/        — Worked example (order management domain)
docs/                   — Human-readable documentation

Key conventions

  • The skill follows a two-gate workflow: Gate 1 (Design/ADR) must be approved before Gate 2 (Implementation) begins.
  • Tests are always written FIRST (TDD).
  • Generated code goes under app/Domain/<Context>/ in the target project.
  • Events use past-tense names (OrderPlaced, not OrderUpdated).
  • One reactor per side effect.
  • Projectors are sync by default.

Development

  • When editing the skill, keep SKILL.md under 500 lines.
  • Reference files provide detail that doesn't need to be in the main prompt.
  • Stub templates use {{ placeholder }} syntax.
  • Stub templates and reference file examples must stay in sync. When updating test patterns in references/tdd-patterns.md, update the corresponding .stub files in assets/templates/, and vice versa.

Releases

The plugin is distributed through the marketplace in this repo. /plugin install users only receive an update when the version in the plugin manifest changes, so every release starts by bumping that version.

How to release

  1. Bump the plugin version. Edit version in plugins/laravel-spatie-event-sourcing/.claude-plugin/plugin.json to the new X.Y.Z (semver: patch = metadata/docs, minor = new skill capability, major = breaking change). This is the field that gives /plugin install users update control — if it doesn't change, they don't see the release.
  2. Roll the changelog. Rename [Unreleased] → [X.Y.Z] - YYYY-MM-DD in CHANGELOG.md and add a fresh empty [Unreleased] above it.
  3. Rebuild the .skill artifact. Run scripts/build-skill.sh so the committed laravel-spatie-event-sourcing.skill matches the canonical skill under plugins/. (Skip re-committing it if only the manifest/docs changed — plugin.json and README are not inside the archive, so its content is unchanged.)
  4. Validate. claude plugin validate . --strict and claude plugin validate ./plugins/laravel-spatie-event-sourcing --strict must both pass.
  5. PR to main and merge. /plugin marketplace add resolves against the GitHub default branch, so users only get the change once it lands on main.
  6. Tag and push. git tag -a vX.Y.Z -m "vX.Y.Z" then git push origin vX.Y.Z. The release.yml workflow rebuilds the .skill and attaches it to the GitHub release automatically.

Keep the plugin.json version and the git tag in sync (vX.Y.Z ↔ X.Y.Z). Primary install path is the marketplace (/plugin install); the .skill archive is the manual fallback.

Changelog

  • Every major change (new features, breaking changes, significant fixes) must be tracked in CHANGELOG.md.
  • Follow the Keep a Changelog format.
  • Add entries under [Unreleased] as changes are made. Move them to a versioned section on release.

Git Commit Conventions

Format

  • type: short subject line (max 50 chars)
  • Detailed body paragraph explaining what and why (not how).

Rules

  • No Claude attribution - NEVER include "Generated with Claude Code" or "Co-Authored-By: Claude"
  • Keep first line under 50 characters
  • Use heredoc for multi-line commit messages