@solaqua/ghosts 0.2.2 → 0.3.0

package/engineering/skills/write-adr/README.md

@@ -0,0 +1,17 @@
+# Write ADR
+
+Write a compact decision record about architecture, technology, infrastructure,
+security, engineering practices, or domain design. Starts with a title and a
+short paragraph; adds status, alternatives, or consequences when useful.
+Works independently of a glossary.
+
+New records default to `/tmp/write-adr-<safe-decision-slug>.md`. A supplied
+destination takes precedence, and requests to revise a specific record edit
+that file.
+
+## Credits
+
+Shout-out to [Matt Pocock](https://github.com/mattpocock) for the ADR format in
+[domain-modeling](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/ADR-FORMAT.md).
+This skill adapts that format for standalone ADR writing across engineering
+decisions.

package/engineering/skills/write-adr/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: write-adr
+description: Create or revise Architecture Decision Records (ADRs) that explain a decision, its context, and its rationale. Use when the user asks to document a decision about architecture, technology, infrastructure, security, engineering practices, or domain design.
+disable-model-invocation: true
+---
+
+# Write ADR
+
+Record a decision so a future reader can understand what was chosen and why.
+ADRs can cover system structure, technology, deployment, security, engineering
+practices, or domain boundaries. A glossary or domain-modeling session is not
+a prerequisite.
+
+## Gather context
+
+Read the relevant discussion, existing ADRs, and supporting documentation or
+code. Identify the decision, the constraints that shaped it, the reason for
+the choice, and any material trade-off.
+
+Separate a proposal from an agreed decision, and an agreed decision from its
+implementation. Code can show what exists; it does not establish the original
+rationale. Do not invent alternatives, evidence, or agreement. Ask only when
+a missing choice or reason prevents an accurate record; otherwise state
+material uncertainty explicitly.
+
+## Write
+
+Save a new record to the path the user supplies; otherwise use
+`/tmp/write-adr-<safe-decision-slug>.md`, appending a timestamp when needed to
+avoid a collision. This default applies even when the repository already has
+an ADR directory. Create a repository directory only when the user specifies
+it as the destination.
+
+When the user asks to revise a specific record, edit that file. When saving a
+new record to a user-specified ADR directory, follow its filename conventions;
+if it uses sequential numbers, take the highest existing number plus one.
+Do not renumber records or overwrite an unrelated file.
+
+Follow an established document format when one exists. Otherwise use
+[templates/adr.md](templates/adr.md). Write in the user's language. A title
+and one short paragraph are sufficient when they explain:
+
+- the situation or constraint that required a choice;
+- the chosen approach and its scope;
+- the reason for choosing it, including the key accepted trade-off.
+
+Add only what helps a future reader assess the decision:
+
+- **Status:** distinguish a proposal, an accepted decision, or a retired or
+  replaced record when that distinction matters. Use `proposed` for an
+  unsettled choice; do not mark it accepted without evidence of agreement.
+- **Considered options:** explain alternatives actually considered when their
+  rejection is worth preserving.
+- **Consequences:** state material costs, limits, or downstream effects that
+  the short paragraph cannot explain clearly.
+
+Keep one decision per record. Edit an existing record for corrections or
+clarifications when requested. When a new decision replaces an accepted one,
+write a new ADR and link to the earlier record to make the replacement clear.
+Update the earlier record only when requested. Documenting a decision does
+not implement it or establish that implementation is complete.
+
+## Verify and deliver
+
+Reread the record without the preceding conversation. Check that the choice,
+scope, rationale, and decision state are understandable, claims match the
+available evidence, and referenced files or records exist.
+
+Report the file path, the recorded decision, and any open questions or
+proposal status.

package/engineering/skills/write-adr/templates/adr.md

@@ -0,0 +1,4 @@
+# <Decision title>
+
+<In one to three sentences, explain the situation, the chosen approach, and
+the reason for the choice, including the key accepted trade-off.>

package/engineering/skills/write-glossary/README.md

@@ -0,0 +1,14 @@
+# Write Glossary
+
+Create or update a project's vocabulary with short definitions, canonical
+terms, and names to avoid. Respects existing document formats.
+
+New glossaries default to `/tmp/write-glossary-<safe-project-slug>.md`. A
+supplied destination takes precedence, and requests to revise a specific
+glossary edit that file.
+
+## Credits
+
+Shout-out to [Matt Pocock](https://github.com/mattpocock) for the glossary format
+in [domain-modeling](https://github.com/mattpocock/skills/blob/main/skills/engineering/domain-modeling/GLOSSARY-FORMAT.md).
+This skill adapts that format for standalone glossary writing.

package/engineering/skills/write-glossary/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: write-glossary
+description: Create or update a project's GLOSSARY.md with precise definitions and canonical terminology. Use when the user asks to write a glossary, document project vocabulary, or revise existing definitions.
+disable-model-invocation: true
+---
+
+# Write Glossary
+
+Write a glossary that gives the project a shared vocabulary. Capture the
+meaning of terms; keep implementation choices and decision rationale in
+their own documents.
+
+## Gather context
+
+Read the relevant discussion, documentation, and existing glossary. Inspect
+code when it helps establish how a term is currently used. Distinguish current
+usage from an intended definition; surface material contradictions instead of
+silently treating either as authoritative.
+
+Choose a canonical term for each concept. If a word names several concepts,
+separate their definitions and make their scope clear. Ask only when the
+available context cannot resolve a distinction that changes the meaning.
+Do not invent agreement or turn unresolved terminology into a settled entry.
+
+## Write
+
+Save a new glossary to the path the user supplies; otherwise use
+`/tmp/write-glossary-<safe-project-slug>.md`, appending a timestamp when needed
+to avoid a collision. This default applies even when the repository already
+has a glossary. When the user asks to revise a specific glossary, edit that
+file. Create a repository directory only when the user specifies it as the
+destination. Write once there is a resolved term to record. A single glossary
+can group terms by area and qualify names whose meaning varies by area.
+
+Follow an established document format when one exists. Otherwise use
+[templates/glossary.md](templates/glossary.md). Write in the user's language
+and preserve canonical names used by the project.
+
+- Keep each definition to one or two sentences explaining the concept and
+  the boundary that distinguishes it from nearby concepts.
+- Include vocabulary with a specific meaning in this project. Omit generic
+  programming definitions unless the project gives them a distinct meaning.
+- List competing names under `_Avoid_` when they refer to the same concept or
+  would mislead readers. Omit the line when there are none.
+- Group entries only when it helps readers find or distinguish terms.
+- Keep schemas, algorithms, storage choices, and decision histories out of
+  glossary entries. Include conceptual relationships only when they clarify
+  the definition.
+
+Update the relevant entries without rewriting unrelated content. This skill
+produces the glossary; it does not rename code or create decision records.
+
+## Verify and deliver
+
+Reread the definitions without the preceding conversation. Check that each
+term has a clear meaning within its stated scope, nearby concepts remain
+distinct, and no entry presents an unresolved assumption as fact.
+
+Report the file path, the vocabulary added or changed, and any unresolved
+definitions left out.

package/engineering/skills/write-glossary/templates/glossary.md

@@ -0,0 +1,9 @@
+# <Project or area name>
+
+<One or two sentences describing the scope of this vocabulary.>
+
+## Language
+
+**<Canonical term>**:
+<One or two sentences defining the concept and its distinguishing boundary.>
+_Avoid_: <Competing or misleading names; omit this line when none apply.>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solaqua/ghosts",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Reusable agent skills and reviewers.",
   "license": "MIT",
   "repository": {