@solaqua/ghosts 0.2.1 → 0.3.0

package/engineering/skills/grill-me/README.md

@@ -0,0 +1,11 @@
+# Grill Me
+
+An interview that stress-tests a plan, decision, or idea through question rounds
+ordered by their dependencies, ending with a short, grouped decision summary.
+
+## Credits
+
+Shout-out to [Matt Pocock](https://github.com/mattpocock) for the original
+[grilling skill](https://github.com/mattpocock/skills/blob/main/skills/productivity/grilling/SKILL.md).
+This adaptation keeps its interview flow and adds guidance for a concise,
+readable result summary.

package/engineering/skills/grill-me/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: grill-me
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking or asks to be grilled.
+---
+
+Interview the user relentlessly until you reach a shared understanding. Map
+this as a design tree: every decision branches into the decisions that depend
+on it.
+
+Work the tree in rounds. The frontier is every decision whose prerequisites
+are already settled: questions you can ask now without guessing at answers you
+have not heard yet. Ask the whole frontier in one round, number each question,
+and give your recommended answer. Then wait for the user's answers.
+
+Format a round like this:
+
+```md
+❓ **Q1** - **<Question title>**: <Question, with choices when useful>
+
+➡️ <Recommended answer>
+
+---
+
+❓ **Q2** - **<Question title>**: <Question, with choices when useful>
+
+➡️ <Recommended answer>
+```
+
+Each round reshapes the tree. Settled decisions unblock their dependent
+questions; recompute the frontier and ask the next round. A question depending
+on another question still open in this round belongs to a later round.
+
+Finding facts is your job, never the user's. When a question needs a fact from
+the environment, dispatch a subagent to find it. A running exploration is an
+unsettled prerequisite: only downstream questions wait; ask the rest of the
+frontier now. The decisions are the user's: put each to them and wait.
+
+The session is done when every branch within scope is resolved and nothing
+remains silently assumed. An empty frontier while research is pending is not
+completion. Do not act until the user confirms the shared understanding.
+
+Present the result using this template in the user's language. Replace
+placeholders, repeat decision groups as needed, and omit constraints when none:
+
+```md
+## Outcome
+
+<Agreed goal and direction in 1–2 sentences>
+
+## Decisions
+
+### <Related decision group>
+
+- <Agreed choice and its key reason or accepted trade-off>
+
+## Constraints
+
+- <Material scope boundary or constraint>
+
+Does this capture our shared understanding?
+```
+
+Keep it readable in one screen without scrolling. Include only what someone
+needs to understand the result; omit the interview transcript, question IDs,
+and full decision tree. Use a compact table or diagram only when it makes the
+decisions easier to understand.

package/engineering/skills/loop-plan/SKILL.md

@@ -58,7 +58,7 @@ fixed ceremony.
 ```text
 [Understand] → [Route unknowns]
                   ├─ evidence → [$loop-research] ┐
-                  ├─ user decision → [$socratic-interview] ├→ [Frame + ledger] → [Draft]
+                  ├─ user decision → [$grill-me] ├→ [Frame + ledger] → [Draft]
                   └─ known →─────────────────────┘              ↓
                                                      [Any high-impact uncertainty?]
                                                        ├─ No → [Self challenge]
@@ -136,20 +136,20 @@ Route unresolved inputs before making design decisions. Use `$loop-research` for
 repository or document investigation, current or contested evidence,
 comparisons, feasibility checks, or source citations; it returns verified
 claims, provenance, uncertainty, and leads that could change the plan. Use
-`$socratic-interview` for choices only the user can make, such as outcome,
-scope, priority, risk tolerance, or external action; it asks one focused
-question at a time and returns an execution brief, but does not plan or edit.
-Do not ask the user for facts inspection or research can establish, and do not
-replace a user decision with an inferred preference. Carry both outputs into
-the decision ledger.
-
-Ask the smallest question when an unknown could change scope, success, or a
-costly decision; continue independent inspection while waiting. State ordinary
-assumptions and proceed. If feasibility remains unestablished, put the cheapest
-useful investigation first with a decision criterion and keep dependent work
-conditional rather than inventing certainty. State task-specific principles,
-rank decision drivers, resolve conflicts explicitly, and define observable
-success before choosing.
+`$grill-me` for choices only the user can make, such as outcome, scope, priority,
+risk tolerance, or external action. It asks the whole ready frontier in each
+round and returns a short, grouped decision summary. Wait for the user to confirm
+the shared understanding before carrying its decisions into the plan. Do not
+ask the user for facts that inspection or research can establish, or infer a
+material preference. Carry both outputs into the decision ledger.
+
+Resolve material user choices through the interview's dependency-aware rounds;
+continue independent inspection while waiting. State ordinary assumptions only
+when they do not replace a material user decision. If feasibility remains
+unestablished, put the cheapest useful investigation first with a decision
+criterion and keep dependent work conditional rather than inventing certainty.
+State task-specific principles, rank decision drivers, resolve conflicts
+explicitly, and define observable success before choosing.
 
 ## Compare and draft
 

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.1",
+  "version": "0.3.0",
   "description": "Reusable agent skills and reviewers.",
   "license": "MIT",
   "repository": {

package/engineering/skills/socratic-interview/SKILL.md

@@ -1,22 +0,0 @@
----
-name: socratic-interview
-description: Conduct a Socratic interview to resolve only material uncertainty, then provide a concise execution brief.
-disable-model-invocation: true
----
-
-Conduct a Socratic interview only when missing information could materially change the outcome, scope, behavior, safety, cost, or external action. Inspect context first and make normal in-scope assumptions when sufficient.
-
-Ask the smallest useful question, one at a time. Do not collect background that will not change the work. Stop when remaining uncertainty is immaterial; state assumptions and proceed unless doing so could cause an unwanted or costly result.
-
-Do not plan, implement, create tasks, write specs, or edit files during the interview.
-
-When sufficient, summarize only the decisions needed to execute:
-
-```md
-# Execution Brief
-
-- Outcome:
-- Decisions:
-- Scope and constraints:
-- Assumptions:
-```