new-module — scaffold from the canonical example, then reconcile
Do not re-derive a module's layout by reading a sibling wholesale. Start from the
project's designated canonical example and copy its shape.
Procedure
- Find the canonical example: read the project's patterns pointer (e.g.
plans/PATTERNS.md) which names the canonical module for this kind. If none
exists, ask the user which existing module to mirror.
- Copy the layout: replicate the directory structure, build file, and
required boilerplate from the canonical example. Substitute the new name
everywhere (package, artifact id, resource paths, ports).
- Reuse shared code — don't clone a sibling's: copying a sibling module is for
layout, not for its outbound clients / helpers. Before writing a client to a
shared capability or platform service, check the project's shared library layer
for an existing one and bind that. If none exists yet and a second module now
needs it, lift it into the shared layer rather than pasting a second copy —
the second consumer is what promotes shared code (the "second-consumer rule").
A capability client duplicated across modules is drift a copy-friendly scaffold
invites; catch it here.
- Register it: add the module wherever the project expects it (root build
file / module list / compose file / plan index).
- Reconcile: run the
check-drift skill immediately. A new module fires
several couplings (compose, root README layout, module README, architecture,
index, env vars) — let check-drift enumerate them rather than trusting memory.
- Contract stubs: create the module's README with its purpose, port, env,
endpoints/tools, and a one-line index of key classes — the README is read
before the source, so it must exist from birth.
- Test surface: if the module has an LLM surface, add a golden test; if it
introduces a cross-service wire contract, add an end-to-end test. State which
applies.
Output
The created paths, the couplings check-drift flagged, and a checklist of what the
user must still fill in (real logic, real env values). Never claim the module is
"done" — it is scaffolded.
1---2name: new-module3description: Use when creating a new module from the project's canonical layout — a new service, MCP module, agent, or migration. Fires on: "add a new module", "scaffold a service", "new MCP module", "new agent", "new migration". Copies the canonical layout, wires it in, and runs check-drift so no coupled artifact is forgotten.4---56# new-module — scaffold from the canonical example, then reconcile78Do not re-derive a module's layout by reading a sibling wholesale. Start from the9project's designated canonical example and copy its shape.1011## Procedure12131. **Find the canonical example**: read the project's patterns pointer (e.g.14 `plans/PATTERNS.md`) which names the canonical module for this kind. If none15 exists, ask the user which existing module to mirror.162. **Copy the layout**: replicate the directory structure, build file, and17 required boilerplate from the canonical example. Substitute the new name18 everywhere (package, artifact id, resource paths, ports).193. **Reuse shared code — don't clone a sibling's**: copying a sibling module is for20 *layout*, not for its outbound clients / helpers. Before writing a client to a21 shared capability or platform service, check the project's shared library layer22 for an existing one and bind that. If none exists yet and a second module now23 needs it, **lift** it into the shared layer rather than pasting a second copy —24 the second consumer is what promotes shared code (the "second-consumer rule").25 A capability client duplicated across modules is drift a copy-friendly scaffold26 invites; catch it here.274. **Register it**: add the module wherever the project expects it (root build28 file / module list / compose file / plan index).295. **Reconcile**: run the `check-drift` skill immediately. A new module fires30 several couplings (compose, root README layout, module README, architecture,31 index, env vars) — let check-drift enumerate them rather than trusting memory.326. **Contract stubs**: create the module's README with its purpose, port, env,33 endpoints/tools, and a one-line index of key classes — the README is read34 before the source, so it must exist from birth.357. **Test surface**: if the module has an LLM surface, add a golden test; if it36 introduces a cross-service wire contract, add an end-to-end test. State which37 applies.3839## Output4041The created paths, the couplings check-drift flagged, and a checklist of what the42user must still fill in (real logic, real env values). Never claim the module is43"done" — it is scaffolded.
fedoroff-vlad