spec-driven-development CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository purpose

This is a Claude Code plugin marketplace (.claude-plugin/marketplace.json) for spec-driven development plugins, e.g.:

• plugins/domain-spec — generates DDD class specs from a Mermaid class diagram, then implements the domain package and its unit tests

There is no application code, no build step, and no test suite. Artifacts are Markdown — skills, agent definitions, and plugin manifests — that are loaded by Claude Code at runtime.

Plugin layout

Each plugin under plugins/<name>/ has:

• .claude-plugin/plugin.json — plugin manifest with version (bump on user-visible changes)
• agents/*.md — single-purpose subagents with frontmatter (name, description, tools, optional model)
• skills/<skill>/SKILL.md — reusable skills; umbrella orchestrator skills (e.g. generate-domain) chain agent orchestrators (specs-generator, code-generator), which in turn coordinate the worker agents

plugins/spec-core/skills/modules/ contains Python reference modules (Entity, ValueObject, guards, the persistence context packages, the REST serializers, etc.) that the generated code imports — not source for this repo to test, but the runtime contract that the implementers/scaffolders target and copy verbatim into the target repo. They are homed under the spec-core:modules umbrella skill; see the spec-core section below for the resolution mechanism.

Shared conventions (spec-core)

plugins/spec-core is a base plugin that owns conventions and agents shared across every spec plugin. It ships:

• One skill, spec-core:naming-conventions — the single source of truth for the aggregate stem, diagram filenames, per-plugin sibling-folder layout, path-resolution tables, and the numbered Path-hygiene rules. The five spec plugins (domain-spec, application-spec, persistence-spec, rest-api-spec, messaging-spec) and model-diagrams all reference it as spec-core:naming-conventions — in agent frontmatter skills: lists and in prose — rather than each carrying their own copy.
• One agent, spec-core:target-locations-finder — the single shared resolver of where each layer's code lives in the target repo. It takes <layer> [<domain_diagram>] (layer ∈ domain/application/persistence/rest-api/messaging; the domain layer also takes the diagram, to derive the aggregate sub-package) and emits the layer's category→path→status table. It replaced five near-identical per-plugin target-locations-finder agents (the skeleton — repo/package resolution, existence check, report shape — was byte-identical; only the per-layer path set and the domain diagram-derivation branch differed). Every orchestrator (each plugin's code-generator agent, the init-* skills, and each plugin's update-code skill — which resolves its own layer) invokes it with the layer token; downstream worker agents still receive the report verbatim as <locations_report_text> and must not re-run it. When consolidating another per-plugin agent clone, home it here the same way.
• One agent, spec-core:project-package-finder — the single shared resolver of the repo's src/ root and its single project package, emitting a Repo/Src/Package/Package Dir/Tests Dir table. It is the shared Step 1 every layer initializer delegates to: /init-domain, /init-persistence, /application-spec:init-application, /rest-api-spec:init-rest-api, and /messaging-spec:init-messaging each invoke @spec-core:project-package-finder (passing their own command label, used only in its failure messages), parse the report for <repo>/<src>/<pkg>, then bind their own layer-specific derived paths from those. This replaced ~five byte-identical copies of the package-discovery preamble (the exact code CLAUDE.md flags as historically bug-prone — "past bugs came from misderiving the project root"). @spec-core:target-locations-finder performs the same resolution as its own Step 1 but keeps an inline copy rather than delegating — it cannot invoke another agent (no Agent tool) and must stay self-contained for its many orchestrator callers; the two carry a sync note and must be changed together if the resolution rule ever changes.
• The cross-layer update orchestrator, spec-core:update-specs — the single home of the cross-plugin spec-update cascade. /spec-core:update-specs <domain_diagram> runs each layer's own /…-spec:update-specs skill in dependency order — domain → {persistence ∥ application} → {rest-api ∥ messaging} — probing each layer's spec artifact on disk and skipping any layer that was never generated (graceful degradation, no hard crash). Each per-layer update-specs is now a pure single-plugin updater: it detects its own deltas, regenerates its own specs, emits its own updates.md, and invokes no other plugin. This replaced the old in-skill chaining where domain-spec:update-specs fanned out to persistence/application from its own tail (Step 10) and application-spec:update-specs re-cascaded to rest-api/messaging from its own tail (Step 9) — a control coupling that made the innermost layer (domain-spec) hard-depend on the four outer layers (dependency pointing up the stack; the Skill call failed hard on a missing leaf plugin). Homing the fan-out in spec-core inverts that the right way. The data coupling is unchanged: rest-api/messaging still read the <stem>.application/{commands,queries,ops}-updates.md detector reports application produces, and the orchestrator passes --detectors-fresh to the rest-api/messaging wave (decided by disk-presence of those reports, not by application's outcome). domain-spec and application-spec update-specs consequently dropped Skill from allowed-tools; the leaves never had it.
• The cross-layer code-update orchestrator, spec-core:update-code — the execution analog of spec-core:update-specs and the single home of the cross-plugin code-update cascade. /spec-core:update-code <domain_diagram> [--review] runs each layer's own /…-spec:update-code skill in dependency order — domain → {persistence ∥ application} → {rest-api ∥ messaging} — probing each layer's spec presence marker (the same markers update-specs uses) and skipping any layer never generated. Each per-layer update-code is a pure single-plugin updater: it resolves its own target locations, runs its own gather → (per-layer risk gate) → implement → review flow over its own code-brief-writer / code-change-writer / code-review-writer agents (persistence also runs query-code-change-writer), applies its own edits, prints its own one-line outcome, and invokes no other plugin. This replaced the old monolithic domain-spec:update-code, which hard-coded all five layers, every per-plugin agent name, and the dependency waves in a single skill rooted in the innermost layer. One deliberate divergence from the spec cascade: code layers couple on on-disk source (a downstream change-writer reads settled upstream source), so an upstream layer that does not settle — an agent hard-fail or a declined per-layer risk gate — skips its dependent downstream waves (domain ⇒ all; application ⇒ rest-api/messaging; persistence ⇒ none). The two cross-cutting features of the old monolith degrade by design (Fork 1, chosen 2026-06-14): the risk checkpoint is now per-layer (there is no global pre-edit veto once edits land wave-by-wave), and there is no consolidated summary table — only the one-line topology summary, exactly like spec-core:update-specs. Per-layer skills carry allowed-tools: Read, Bash, Agent, AskUserQuestion; the orchestrator carries Read, Bash, Skill. Single-layer code updates are now possible standalone (/persistence-spec:update-code <diagram>), which the monolith could not do.
• The cross-layer update-report schemas, spec-core:update-reports — the umbrella home of the three detector report schemas the spec-update cascade produces and consumes across plugin boundaries: the domain-diagram diff (domain/index.md, produced by domain-spec:updates-detector), the application-service-axis diff (application/index.md, produced by commands-/queries-updates-detector), and the ops-service diff (ops/index.md, produced by ops-updates-detector). Each schema is a supporting file Read by path; only the umbrella SKILL.md index auto-loads. Producers frontmatter-load spec-core:update-reports and Read <update_reports_dir>/<layer>/index.md; cross-layer consumers resolve the same umbrella — persistence-spec's command-repo-spec-migrations-appender + query-code-change-writer frontmatter-load it and Read domain/index.md (the load-bearing edge that pre-2026-06-14 forced a dual-homed domain-spec:updates-report-template), while the application/rest-api/messaging update writers cite it as provenance. This homes the schemas next to the update-specs orchestrator that drives them and retired the last dual-homed twin. Scope is deliberate: only the cross-consumed detector schemas moved. Each layer's own code-update report (<stem>.{persistence,application,rest-api,messaging}/updates.md — the ## Affected Artifacts dispatch schema its update-code flow consumes) stays a plugin-private supporting file under that plugin's own patterns umbrella; those are the candidates to follow if the cross-layer code-update workflow is later consolidated the same way.