القائمة
Cross-plugin naming and layout conventions for diagrams and spec artifacts. Defines the canonical aggregate stem, diagram filenames, and per-plugin sibling folder layout.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Umbrella catalog of the project's Mermaid class-diagram conventions (domain, commands, queries, ops kinds), organized by theme. Each theme lives in a sibling folder's index.md. Load when AUTHORING, editing, or REVIEWING a diagram in this project — the docs give the canonical authoring rule and the matching review lens (what is canonical and must not be flagged).
Umbrella catalog of all rest-api-spec pattern references. Each pattern lives in a sibling folder of this file — `<pattern-name>/` containing `index.md` (the pattern doc) plus an optional `examples.md` companion. Load to resolve pattern names to their reference docs by path instead of per-pattern skill invocations.
Initializes the project-wide application-layer scaffolding (project package discovery, src/<pkg>/application/, src/<pkg>/infrastructure/, src/<pkg>/infrastructure/services/, src/tests/fakes/, and a minimal src/tests/conftest.py). Invoke with: /application-spec:init-application
Initializes the project-wide domain scaffolding (project package discovery, src/<pkg>/domain/ with shared/, src/tests/ with conftest and unit/). Aggregate-agnostic — run once per project before any @domain-spec:code-generator invocation. Invoke with: /init-domain
Initializes the project-wide messaging scaffolding (project package discovery, src/<pkg>/messaging/ as an empty aggregator package, and a canonical Click __main__.py skeleton). Invoke with: /messaging-spec:init-messaging
Initializes the project-wide persistence scaffolding. Invoke with: /init-persistence
| name | naming-conventions |
| description | Cross-plugin naming and layout conventions for diagrams and spec artifacts. Defines the canonical aggregate stem, diagram filenames, and per-plugin sibling folder layout. |
| when_to_use | Use when scaffolding, reading, or writing any sibling spec file produced by domain-spec, application-spec, persistence-spec, rest-api-spec, or messaging-spec. |
| user-invocable | false |
Load this skill before deriving any sibling-artifact path or creating any diagram filename. Every cross-plugin agent reads from / writes to the layout defined here; reconstructing paths by ad-hoc string substitution will diverge from the contract.
This skill is the single source of truth for those rules. Agents and skills across domain-spec, application-spec, persistence-spec, rest-api-spec, and messaging-spec derive every input/output path from this convention.
The aggregate stem is a kebab-case identifier matching the domain aggregate root (e.g. order, purchase-order, product-catalog). It must satisfy ^[a-z][a-z0-9-]*$.
<stem> is kebab-case for spec paths and filenames only. The Python package name that appears on disk inside src/<pkg>/domain/ is the same value in snake_case — obtained by replacing every - with _. Every agent that materializes a Python directory (notably spec-core:target-locations-finder, package-preparer, scaffold-builder, code-implementer) must perform this conversion before touching the filesystem.
| Diagram stem | Spec folder | Python package directory |
|---|---|---|
order | <dir>/order.domain/ | src/<pkg>/domain/order/ |
cache-type | <dir>/cache-type.domain/ | src/<pkg>/domain/cache_type/ |
purchase-order | <dir>/purchase-order.domain/ | src/<pkg>/domain/purchase_order/ |
Validate the derived Python package name against ^[a-z][a-z0-9_]*$. Agents must abort if validation fails; they must never emit a path segment containing - under src/.
Given a domain diagram path <dir>/<stem>.md:
<dir> is the specs directory — the directory holding every diagram and sibling folder for the aggregate.<stem> is the aggregate stem — the canonical identifier that every other artifact derives from.Every plugin agent derives <dir> and <stem> by inspecting the domain-diagram path it receives. There is no second stem and no per-plugin alias.
For an aggregate stem <stem>, the Mermaid class diagrams have fixed names:
| Diagram | Path | Owner |
|---|---|---|
| Domain | <dir>/<stem>.md | hand-authored input |
| Commands application service | <dir>/<stem>.commands.md | hand-authored input |
| Queries application service | <dir>/<stem>.queries.md | hand-authored input |
| Ops application service | <dir>/<stem>.ops.<op-name>.md | hand-authored input |
<op-name> is a kebab-case discriminator matching ^[a-z][a-z0-9-]*$ and equals the kebab-case of the ops service class name (the unique braced class in the diagram), so <dir>/order.ops.subject-tagging.md declares class SubjectTagging. An aggregate may have any number of ops diagrams (zero, one, or many), each becoming one free-form orchestration application service. Both <stem> and <op-name> are dot-free, so the literal .ops. separator is unambiguous.
Beyond application-spec (which generates the ops application service), the ops diagram is a read-only input to two downstream plugins: messaging-spec reads each <stem>.ops.<op-name>.md for %% Messaging - <consumer> handler-binding blocks (an ops method may handle an event), and rest-api-spec reads it for the ops service's public methods (each becomes a REST action endpoint). Both discover ops diagrams by globbing <dir>/<stem>.ops.*.md; an aggregate with zero ops diagrams leaves their behavior unchanged. Ops-diagram deltas reach those plugins' update flows through the shared <dir>/<stem>.application/ops-updates.md report (see Cross-plugin reads below).
Examples for <stem> = order:
specs/
order.md
order.commands.md
order.queries.md
order.ops.subject-tagging.md
A plugin that needs a non-domain diagram (e.g. application-spec, messaging-spec) receives that path as an argument; it must not infer it by appending suffixes to the domain path.
Each plugin owns one folder per aggregate, named <stem>.<plugin-shortname>/, sitting next to the diagrams:
| Plugin | Folder |
|---|---|
| domain-spec | <dir>/<stem>.domain/ |
| application-spec | <dir>/<stem>.application/ |
| persistence-spec | <dir>/<stem>.persistence/ |
| rest-api-spec | <dir>/<stem>.rest-api/ |
| messaging-spec | <dir>/<stem>.messaging/ |
The folder name is the plugin short name without the -spec suffix. The folder must be created on first write by the plugin's scaffolder/initializer; subsequent agents in the same plugin assume it exists.
A plugin must never write outside its own folder. The only exceptions are:
## Artifacts index (which is the diagram itself, not another plugin's folder).Several consumer orchestrators read the commands/queries delta reports owned by the application-spec plugin even though they never write inside <dir>/<stem>.application/:
| Path | Owner | Consumed by |
|---|---|---|
<dir>/<stem>.application/commands-updates.md | application-spec:commands-updates-detector | /application-spec:update-specs, /messaging-spec:update-specs, and /rest-api-spec:update-specs — dispatching regen on commands-diagram deltas |
<dir>/<stem>.application/queries-updates.md | application-spec:queries-updates-detector | /application-spec:update-specs and /rest-api-spec:update-specs — dispatching regen on queries-diagram deltas (messaging-spec is command-side only) |
<dir>/<stem>.application/ops-updates.md | application-spec:ops-updates-detector | /messaging-spec:update-specs and /rest-api-spec:update-specs — dispatching regen on ops-diagram deltas (one aggregate-wide report covering every <stem>.ops.<op-name>.md) |
The detectors are write-once-read-many producers; each consumer orchestrator re-invokes them at its own Step 0 to ensure freshness, then the producer overwrites the prior report. The cross-plugin dependency is deliberate, read-only, and unidirectional — the reports describe the application-service diagrams (<stem>.commands.md, <stem>.queries.md, and every <stem>.ops.<op-name>.md), and application-spec is the plugin that anchors those diagrams; application-spec never reads back. The consumer orchestrators (three for commands, two for queries, two for ops) share one report per axis rather than maintaining plugin-local detectors against the same diagram. See notes/commands-queries-integration-approach.md for the full rationale.
<stem>.domain/ (domain-spec)| File | Producer | Purpose |
|---|---|---|
specs.md | class-specifier → pattern-assigner → specs-merger | Merged class specification (final) |
exceptions.md | specs-merger (stub) → exceptions-specifier (enriched) | Domain exceptions |
test-plan.md | aggregate-tests-planner | Aggregate unit-test plan |
updates.md | updates-detector | Structured diff report (input to update-specs) |
.specs-tmp/<category>.md | class-specifier, pattern-assigner | Transient per-category temp file (deleted by specs-merger / spec-splicer) |
<stem>.application/ (application-spec)| File | Producer | Purpose |
|---|---|---|
commands.specs.md | specs-merger (commands side) | Merged commands spec (final) |
commands.exceptions.md | commands-methods-writer (stub) → application-exceptions-specifier | Application exceptions raised by commands |
queries.specs.md | specs-merger (queries side) | Merged queries spec (final) |
queries.exceptions.md | queries-methods-writer (stub) → application-exceptions-specifier | Application exceptions raised by queries |
services.md | services-finder | Reconciled list of services the application layer must implement |
updates.md | application-updates-writer | Structured diff report (input to /update-code) |
commands-updates.md | application-spec:commands-updates-detector | Structured diff report of <stem>.commands.md — input to application-spec:update-specs, messaging-spec:update-specs, and rest-api-spec:update-specs (read cross-plugin; see Cross-plugin reads above) |
queries-updates.md | application-spec:queries-updates-detector | Structured diff report of <stem>.queries.md — input to application-spec:update-specs and rest-api-spec:update-specs (read cross-plugin; see Cross-plugin reads above) |
ops-updates.md | application-spec:ops-updates-detector | Structured diff report of every <stem>.ops.<op-name>.md (one aggregate-wide report) — input to messaging-spec:update-specs and rest-api-spec:update-specs (read cross-plugin; see Cross-plugin reads above) |
commands.deps.md | deps-writer commands | Transient — deleted by specs-merger |
commands.methods.md | commands-methods-writer | Transient — deleted by specs-merger |
queries.deps.md | deps-writer queries | Transient — deleted by specs-merger |
queries.methods.md | queries-methods-writer | Transient — deleted by specs-merger |
ops.<op-name>.specs.md | specs-merger (ops side) | Merged ops spec (final) — one per ops diagram |
ops.<op-name>.exceptions.md | ops-methods-writer (stub) → application-exceptions-specifier | Application exceptions raised by this ops service's methods |
ops.<op-name>.deps.md | deps-writer ops <op-name> | Transient — deleted by specs-merger |
ops.<op-name>.methods.md | ops-methods-writer | Transient — deleted by specs-merger |
The per-side fragments (commands.deps.md, commands.methods.md, queries.deps.md, queries.methods.md, and each ops.<op-name>.{deps,methods}.md) exist only between writer and merger. After a successful pipeline run, only commands.specs.md, commands.exceptions.md, queries.specs.md, queries.exceptions.md, services.md, and each ops service's ops.<op-name>.specs.md / ops.<op-name>.exceptions.md remain. The updates.md, commands-updates.md, and queries-updates.md reports are transient producer outputs (of application-updates-writer and the two application-spec detectors respectively); each is regenerated wholesale on its producer's run and overwrites the prior report.
<op-name> matches ^[a-z][a-z0-9-]*$ and equals the kebab-case of the ops service class. One pair of ops.<op-name>.specs.md / ops.<op-name>.exceptions.md per ops diagram; multiple ops services share the one flat <stem>.application/ folder (no sub-folder), exactly as commands/queries artifacts do.
<stem>.persistence/ (persistence-spec)| File | Producer | Purpose |
|---|---|---|
command-repo-spec.md | command-repo-spec-scaffolder → command-repo-spec-pattern-selector → command-repo-spec-schema-writer | Command repository spec (Sections 1–3) |
<stem>.rest-api/ (rest-api-spec)| File | Producer | Purpose |
|---|---|---|
spec.md | resource-spec-initializer → endpoint-tables-writer → response-fields-writer → request-fields-writer → parameter-mapping-writer | REST API resource spec (Tables 1–6) |
<stem>.messaging/ (messaging-spec)| File | Producer | Purpose |
|---|---|---|
<consumer-name>.md | consumer-spec-initializer → event-tables-writer → event-fields-writer | Per-consumer messaging spec |
updates.md | messaging-updates-writer | Structured per-consumer diff report (input to update-code) — one per aggregate, covers all consumers |
<consumer-name> is a kebab-case identifier matching ^[a-z][a-z0-9-]*$, supplied by the user (e.g. inventory-sync, shipping-events). One file per consumer; multiple consumers may share <stem>.messaging/. updates.md is the only non-per-consumer file in the folder.
For aggregate stem order with two messaging consumers inventory-sync and shipping-events, plus one ops service subject-tagging (declaring class SubjectTagging), after running every pipeline:
specs/
order.md
order.commands.md
order.queries.md
order.ops.subject-tagging.md
order.domain/
specs.md
exceptions.md
test-plan.md
updates.md
order.application/
commands.specs.md
commands.exceptions.md
queries.specs.md
queries.exceptions.md
ops.subject-tagging.specs.md
ops.subject-tagging.exceptions.md
services.md
updates.md
order.persistence/
command-repo-spec.md
order.rest-api/
spec.md
order.messaging/
inventory-sync.md
shipping-events.md
updates.md
Every agent and orchestrator receives a path argument and must derive sibling paths from the naming convention rather than asking the caller to pre-resolve them. This section is the single source of truth for that derivation.
<dir> and <stem> from inputs<stem> and <dir> are recovered from whichever path the caller supplied:
| Input | Recovery |
|---|---|
<domain_diagram> = <dir>/<stem>.md | <dir> = directory of input; <stem> = basename with .md stripped |
<commands_diagram> = <dir>/<stem>.commands.md | <dir> = directory of input; <stem> = basename with .commands.md stripped |
<queries_diagram> = <dir>/<stem>.queries.md | <dir> = directory of input; <stem> = basename with .queries.md stripped |
<ops_diagram> = <dir>/<stem>.ops.<op-name>.md | <dir> = directory of input; split the basename (with .md stripped) on the literal .ops. — both <stem> and <op-name> are dot-free kebab, so the split is unambiguous: the left part is <stem>, the right part is <op-name> |
<spec_file> inside <dir>/<stem>.<plugin>/... | walk up two segments: the parent's parent is <dir>; the parent's basename minus .<plugin> is <stem> |
<stem> must satisfy ^[a-z][a-z0-9-]*$. If the recovered stem fails this regex, abort with a one-sentence error rather than silently producing nonsense paths.
The supplied path is authoritative. <dir> and <stem> come only from the path the caller handed you — never from the aggregate-root class name, the bounded-context title:, or a search of the tree. Every artifact for one aggregate therefore shares a single <dir> and a single <stem>. If the aggregate root is MappingRule but the diagram you were given is …/ruleset/ruleset.md, the stem is ruleset and every sibling is …/ruleset/ruleset.<suffix>; resolving instead to …/mapping-rule/mapping-rule.commands.md (a like-named file in another folder) is a bug, not a fallback. See Path-hygiene rule 6.
<stem>Once <dir> and <stem> are recovered, every other artifact path is built from this table:
| Artifact | Path |
|---|---|
| Domain diagram | <dir>/<stem>.md |
| Commands diagram | <dir>/<stem>.commands.md |
| Queries diagram | <dir>/<stem>.queries.md |
| Ops diagram | <dir>/<stem>.ops.<op-name>.md |
| Domain merged spec | <dir>/<stem>.domain/specs.md |
| Domain exceptions | <dir>/<stem>.domain/exceptions.md |
| Domain test plan | <dir>/<stem>.domain/test-plan.md |
| Domain updates report | <dir>/<stem>.domain/updates.md |
| Application commands spec | <dir>/<stem>.application/commands.specs.md |
| Application commands exceptions | <dir>/<stem>.application/commands.exceptions.md |
| Application queries spec | <dir>/<stem>.application/queries.specs.md |
| Application queries exceptions | <dir>/<stem>.application/queries.exceptions.md |
| Application ops spec | <dir>/<stem>.application/ops.<op-name>.specs.md |
| Application ops exceptions | <dir>/<stem>.application/ops.<op-name>.exceptions.md |
| Application services report | <dir>/<stem>.application/services.md |
| Application updates report | <dir>/<stem>.application/updates.md |
| Application commands updates report | <dir>/<stem>.application/commands-updates.md |
| Application queries updates report | <dir>/<stem>.application/queries-updates.md |
| Application ops updates report | <dir>/<stem>.application/ops-updates.md |
| Persistence command-repo spec | <dir>/<stem>.persistence/command-repo-spec.md |
| REST API resource spec | <dir>/<stem>.rest-api/spec.md |
| Messaging consumer spec | <dir>/<stem>.messaging/<consumer_name>.md |
| Messaging updates report | <dir>/<stem>.messaging/updates.md |
The messaging consumer spec (<consumer_name>) and the ops artifacts (ops diagram, ops spec, ops exceptions — all keyed on <op-name>) are the only paths that require an additional discriminator; every other artifact is fully determined by <stem> plus the plugin's identity.
<domain_diagram> plus non-derivable extras (<consumer_name>, <op-name>, <service_identifier>, <tests_dir>, free-text notes). They never require the caller to pre-resolve commands/queries/ops diagrams or sibling spec files — derivation happens inside the orchestrator using the tables above.<domain_diagram> for domain-spec, application-spec, persistence-spec, and rest-api-spec; <commands_diagram> for messaging-spec — plus non-derivable extras. Sibling spec files inside the agent's own plugin folder are derived internally.path.replace('.md', '.specs.md')). Always recover <stem> and <dir> per the recovery table first, then build new paths from the artifact table.These rules apply to every agent that materializes files or directories under the project tree. They are the contract that prevents stray paths, shadow directories, and kebab-case Python imports.
<path> argument an agent writes to must be absolute. Abort with an explicit error rather than resolving against the current working directory.src/ or used as <package_path>, <output_dir>, <aggregate_pkg_dir>, <module_path> — must satisfy ^[a-z][a-z0-9_]*(/[a-z][a-z0-9_]*)*$ for its leaf segments. Treat a hyphen in any of those segments as a caller bug.spec-core:target-locations-finder), it must pass each chained agent the exact path from the report rather than passing an ancestor and letting the agent re-derive. The report is the single source of truth for where things go.<module_path> must begin with <aggregate_pkg_dir>).<stem>.commands.md, <stem>.queries.md, <stem>.ops.<op-name>.md) as a literal path under the input's own <dir> with the input's own <stem> — <dir>/<stem>.<suffix>. Do not glob the wider tree for a better-named candidate, do not re-derive the stem from the aggregate-root class name, and do not fall back to a like-named file in a different aggregate's folder. The only sanctioned glob — ops discovery — is anchored to the input's own dir and stem (<dir>/<stem>.ops.*.md) and never reaches outside <dir>. Read exactly the derived path; if it is missing, abort with an error quoting that exact absolute path (never substitute another file), and word the error so the operator can tell file missing (a path / scaffolding problem) from file present but empty / no classDiagram block (a content problem). A diagram sibling at a different <dir> or under a different <stem> than the input is never the right file, no matter how closely its name matches the aggregate.Agents that need to apply these rules cite this section by name (e.g. "Per spec-core:naming-conventions, Path hygiene rule 3, abort if the file does not exist") instead of restating them.
<stem>.specs.md, <stem>.exceptions.md flat layout is replaced by per-plugin folders).order-commands.md — the canonical separator between the aggregate stem and the role suffix is a dot (order.commands.md).order.persistence/persistence.command-repo-spec.md is wrong; use order.persistence/command-repo-spec.md).