@solaqua/ghosts 0.2.2 → 0.3.1

package/README.md

@@ -10,7 +10,7 @@ safe instruction that preserves the behavior.
 ### GitHub source
 
 ```sh
-npx @solaqua/skul@latest add --global --agent codex sjquant/ghosts --all
+npx @solaqua/skul@latest add --global sjquant/ghosts --all
 ```
 
 ### npm package
@@ -18,10 +18,29 @@ npx @solaqua/skul@latest add --global --agent codex sjquant/ghosts --all
 This repository is also published as [`@solaqua/ghosts`](https://www.npmjs.com/package/@solaqua/ghosts). Install it through [`@solaqua/skul`](https://www.npmjs.com/package/@solaqua/skul):
 
 ```sh
-npx @solaqua/skul@latest add --global --agent codex npm:@solaqua/ghosts
+npx @solaqua/skul@latest add --global npm:@solaqua/ghosts --all
 ```
 
-Replace `codex` with the name of the agent you use, if different. The `--global` flag controls where Skul materializes the skills; it does not install `@solaqua/ghosts` as a Node.js dependency. Requires Node.js >=20 and git.
+Both examples use `--all` to install every bundle in the repository. Skul installs skills for every supported agent by default. Add `--agent <name>` to target one agent, or repeat the option to target several. The `--global` flag controls where Skul materializes the skills; it does not install `@solaqua/ghosts` as a Node.js dependency. Requires Node.js >=20 and git.
+
+## Skill names
+
+Skills maintained in this repository use the `ghosts:` namespace to distinguish
+them from built-in skills and skills from other sources. Skul uses each
+`SKILL.md`'s `name` to create the installed skill directory. Skills are
+materialized in each supported agent's native location; invocation syntax
+depends on the agent.
+
+| Agent | Invocation example |
+| --- | --- |
+| Claude Code | `/ghosts:code-review` |
+| Codex | `$ghosts:code-review` |
+
+These are examples; installation is not limited to Claude Code and Codex.
+
+Source directories keep their short names, so Skul item selectors still use
+paths such as `--include skills/code-review`. External skills installed through
+`registry/skul.refs.json` retain their upstream names.
 
 ## Bundles
 

package/engineering/skills/code-review/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: code-review
+name: ghosts:code-review
 description: Broad, read-only code review using general agents and complete result synthesis.
 disable-model-invocation: true
 ---
@@ -11,7 +11,7 @@ Consider every question below. Mark irrelevant questions `N/A — <reason>`. The
 - `Any correctness or operational risks, including bugs, edge cases, race conditions, resource leaks, performance bottlenecks, scalability concerns, or security issues?`
 - `Any design or API issues when viewed from the intended caller's perspective and from outside-in, deep-module, and dependency-direction perspectives, including whether the module hides state, lifecycle, and ordering details, or exposes internal collaboration methods as public API; also consider hidden obligations, awkward call sites, leaky abstractions, or circular dependencies?`
 - `Any opportunities to simplify or clarify the code through better naming, standard libraries, utilities, or existing abstractions?`
-- `Any test smells or test-suite bloat—such as brittle or implementation-coupled tests, over-mocking, unclear intent, missing negative-path coverage, surviving mutants, or redundant, overlapping, or low-signal tests whose maintenance, execution, and review costs outweigh the independent behavioral confidence they add?`
+- `Any test smells or test-suite bloat—such as brittle or implementation-coupled tests, tautological tests that repeat the implementation or assert only mock setup, over-mocking, unclear intent, missing negative-path coverage, surviving mutants, or redundant, overlapping, or low-signal tests whose maintenance, execution, and review costs outweigh the independent behavioral confidence they add?`
 
 After all agents respond and before synthesizing the final findings, triage every candidate point through this question: `Does this feedback identify a real, evidenced, material issue, or would addressing it add unnecessary complexity, flag a nonexistent or unsupported bug, or provide little value?` Judge the feedback itself, not only whether another agent made the same point. Do not omit any candidate point. Assign `P0`, `P1`, `P2`, or `P3` when it is actionable; assign `SKIP` only as a priority label when it is false, unsupported, duplicate, contradicted, out of scope, or not worth acting on. `SKIP` never means remove the item: every candidate must remain in `Findings` with its priority and the reason for that judgment. Do not leave skipped candidates only in `Reviewer Results`.
 

package/engineering/skills/deep-module/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: deep-module
+name: ghosts:deep-module
 description: Assess whether a module hides implementation details behind a simple interface for its callers.
 disable-model-invocation: true
 ---

package/engineering/skills/explain-diff/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: explain-diff
+name: ghosts:explain-diff
 description: Explain a complete code change, diff, branch, or PR as a visual, novice-first HTML lesson with large diagrams, few words, concrete examples, and an interactive quiz.
 disable-model-invocation: true
 ---

package/engineering/skills/github-pr/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: github-pr
+name: ghosts:github-pr
 description: When the user asks to publish, sync, or manage GitHub work, commit and push each change and create or update its pull request.
 ---
 ## Git workflow

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

@@ -1,5 +1,5 @@
 ---
-name: grill-me
+name: ghosts: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.
 ---
 

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

@@ -1,5 +1,5 @@
 ---
-name: loop-coding
+name: ghosts:loop-coding
 description: Approval-gated loop for building, changing, fixing, or refactoring code.
 disable-model-invocation: true
 ---

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

@@ -1,5 +1,5 @@
 ---
-name: loop-plan
+name: ghosts:loop-plan
 description: Planning-only loop for complex development and design problems, adaptable to other domains; uses evidence, alternatives, counterarguments, and premortems to resolve material uncertainty or costly tradeoffs. Skip routine implementation planning.
 disable-model-invocation: true
 ---
@@ -57,9 +57,9 @@ fixed ceremony.
 
 ```text
 [Understand] → [Route unknowns]
-                  ├─ evidence → [$loop-research] ┐
-                  ├─ user decision → [$grill-me] ├→ [Frame + ledger] → [Draft]
-                  └─ known →─────────────────────┘              ↓
+                  ├─ evidence → [$ghosts:loop-research]┐
+                  ├─ user decision → [$ghosts:grill-me] ├→ [Frame + ledger] → [Draft]
+                  └─ known →──────────────────────────┘              ↓
                                                      [Any high-impact uncertainty?]
                                                        ├─ No → [Self challenge]
                                                        └─ Yes → [Targeted subagent questions]
@@ -132,14 +132,15 @@ questions that inspection can answer. Distinguish observed facts, inferences,
 and assumptions; cite supporting files or sources. Identify the observable
 outcome, non-goals, affected users or systems, and material constraints.
 
-Route unresolved inputs before making design decisions. Use `$loop-research` for
-repository or document investigation, current or contested evidence,
+Route unresolved inputs before making design decisions. Use `$ghosts: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
-`$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
+`$ghosts: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.
 
@@ -214,6 +215,6 @@ Before delivery, verify references are accurate, critical assumptions are
 validated or explicitly gated, acceptance checks cover intended behavior, and
 another implementer can proceed without hidden design decisions.
 Readiness describes the plan; it is not user approval or evidence that planned
-checks passed. If handing the document to `loop-coding`, preserve explicit
+checks passed. If handing the document to `ghosts:loop-coding`, preserve explicit
 approval of that plan and let its implementation workflow own execution. End
 with the plan path, chosen direction, and remaining decisions.

package/engineering/skills/task-handoff/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: task-handoff
+name: ghosts:task-handoff
 description: Generate concise task handoffs for independent implementation workstreams.
 disable-model-invocation: true
 ---

package/engineering/skills/test-review/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: test-review
+name: ghosts:test-review
 description: Read-only review of tests in a change, PR, or path against shared, frontend, and backend testing standards.
 disable-model-invocation: true
 ---
@@ -8,7 +8,7 @@ disable-model-invocation: true
 
 Review the tests read-only. If no target is given, review the tests in the current branch's diff against the base branch. Write in the user's language.
 
-Always apply [references/common.md](references/common.md). Add [references/frontend.md](references/frontend.md) for UI or browser tests and [references/backend.md](references/backend.md) for server, worker, or data tests; use both when the change spans them. For another stack, apply only `common.md`.
+Read and apply [references/common.md](references/common.md) for every review. Read [references/frontend.md](references/frontend.md) for UI or browser tests and [references/backend.md](references/backend.md) for server, worker, or data tests as supplements; use both when the change spans them. For another stack, apply only the common standards.
 
 1. Map each changed behavior to the existing and new tests that protect it. Flag behavior no test would catch if it broke, and removed tests whose protection is not covered elsewhere.
 2. Review each added, changed, or removed test against the guides' review checklists.

package/engineering/skills/test-review/references/backend.md

@@ -1,24 +1,10 @@
 # Backend Testing Guide
 
-This document defines the shared testing standards for backend teams. Tests are not written just to see `Pass`. They are written to fail quickly and clearly when important behavior is broken.
+This guide adds backend-specific rules and examples to the shared standards in `common.md`.
 
 Repository structure, fixture names, and test commands may differ by repository. This guide focuses on shared judgment criteria for writing and reviewing backend tests, rather than repository-specific usage.
 
-## 1. Testing Philosophy
-
-### 1.1 Meaningful Failure
-
-- A test should fail when the behavior it protects is broken.
-- A test that keeps passing after a requirement change or bug does not provide safety. It only adds maintenance cost.
-- If a refactor breaks a test while observable behavior remains the same, the test is likely coupled too tightly to implementation details.
-- Regression tests and snapshot tests are useful when they protect contracts that must not change accidentally.
-- If a test failure does not reveal which requirement was broken, improve the test name, setup, or assertions.
-
-### 1.2 Choose Test Targets By Value
-
-Apply [Test Target Value](common.md#test-target-value), and:
-
-- When an integration test already protects a behavior, do not automatically repeat it in unit tests for every participating layer. Add focused tests where they provide additional protection or clearer checks of important edge cases.
+## 1. Test Targets
 
 High-priority targets:
 
@@ -28,53 +14,17 @@ High-priority targets:
 - Logic that interprets external system responses and mutates local state
 - Edge-case-heavy logic such as dates, timezones, market holidays, exchange rates, decimals, and discounts
 
-Lower-priority targets:
-
-- Simple getters, setters, and DTO declarations
-- Behavior already guaranteed by the library
-- Shape errors that static analysis, type checkers, or linters catch better
-- Tests that only repeat the implementation without improving behavioral safety
-
 ## 2. Test Scope Strategy
 
-Prefer tests that keep the real collaboration needed to deliver a feature intact. A test can exercise an API, service, repository, and DB together while protecting one clearly defined behavior. The number of participating components and the number of concerns being tested are separate choices.
-
-Apply [Focused Scenarios](common.md#focused-scenarios).
-
-Recommended approach:
-
-1. First check whether the behavior can be tested through an existing public entrypoint from the perspective of a user or external system. Do not expand production interfaces solely for testing convenience.
-2. Prefer integration tests when API, service, repository, DB, and cache behavior can be verified together clearly.
-3. Narrow the scope one level when the integration test becomes too slow, too hard to set up, or too hard to debug.
-4. Use unit tests directly for naturally small units such as pure calculations, parsers, and validators.
-5. Replace external systems we do not control at the test boundary, such as third-party APIs, payment providers, email, and object storage.
-
-Why we prefer larger tests:
-
-- They catch real wiring, transaction, serialization, and dependency override issues.
-- They remain stable when internal calls change but the feature behavior stays the same.
-- They produce a signal closer to production behavior than tests with heavy mocking.
-
-When to narrow the scope:
-
-- The setup is so large that the important condition is hard to see.
-- The failure cause is difficult to isolate.
-- Replacing external dependencies takes up most of the test.
-- Slow tests start hurting the feedback loop.
-- One complex rule needs many focused edge-case checks.
+API, service, repository, DB, and cache integration tests can catch wiring, transaction, serialization, and dependency override issues.
 
 ## 3. Test Naming And Grouping
 
-Test names should reveal both the situation and the expected outcome.
-
 Basic rules:
 
 - Use `test_<situation>_<expected_outcome>` for test function names.
 - Every test should have a docstring.
-- For complex tests, use the docstring to describe the requirement or intent more specifically.
-- Prefer capability- and outcome-oriented names over implementation-shaped names.
-- Describe what the test actually exercises and observes. Do not claim to verify behavior that has been replaced by a test double.
-- Use `pytest.mark.parametrize` with readable `ids` for cases of the same behavior that share an execution flow. Split cases when combining them introduces branches that obscure their different scenarios.
+- Use `pytest.mark.parametrize` with readable `ids` for cases that share an execution flow.
 
 Example:
 
@@ -96,7 +46,6 @@ Use classes when related tests are easier to read as one group. Standalone test
 
 - Group tests by feature or public entrypoint.
 - Do not use classes to hide important setup or build complex lifecycles.
-- Each test inside the class should still be understandable on its own.
 
 ## 4. AAA Pattern
 
@@ -121,12 +70,6 @@ async def test_expired_subscription_removes_user_role(...) -> None:
     assert not user_has_role(subscription.user_id, "premium")
 ```
 
-Notes:
-
-- If `when` contains several independent actions, it becomes unclear which action caused the failure.
-- One test may verify multiple results, but they should all come from the same behavior.
-- Use helpers when setup becomes long, but keep the important scenario conditions visible in the test body.
-
 ## 5. Layer-Specific Guidelines
 
 Use the largest layer that still gives a clear signal.
@@ -139,30 +82,7 @@ Use the largest layer that still gives a clear signal.
 
 ## 6. Fixture And Test Data
 
-Fixtures are tools for readability. They should not hide the important conditions of a test.
-
-Good fixtures:
-
-- Hide repeated infrastructure setup.
-- Provide common dependencies such as DB sessions, clients, caches, repositories, and services.
-- Make their provided state clear from the name.
-
-Fixtures to be careful with:
-
-- Fixtures that automatically create too many rows and make test conditions hard to trace.
-- Fixtures that hide the core condition of a scenario.
-- Fixtures that accept many scenario-specific parameters and become a small DSL.
-- Deep fixture dependency chains that make failures hard to diagnose.
-
-Recommended approach:
-
-- Promote helpers or fixtures to a shared place when multiple domains reuse them.
-- Keep domain-specific helpers near that domain.
-- Keep scenario-specific core conditions in the test body.
-- Reuse established setup helpers when their behavior is outside the test's concern.
-- Extract helpers to make scenarios easier to understand, not just to remove repeated lines. A little duplication is preferable to an abstraction that hides the important conditions or execution flow.
-- Use helper and factory names that reveal intent. Examples: `create_expired_subscription`, `create_verified_user`
-- Create only the minimum rows required by the test.
+Backend fixtures commonly provide DB sessions, clients, caches, repositories, and services; scenario factories can use names such as `create_expired_subscription` or `create_verified_user`.
 
 ### 6.1 DB Setup
 
@@ -174,19 +94,15 @@ Recommended approach:
 
 ### 6.2 Cache And External State
 
-- Prefer shared fixtures for cache cleanup, dependency overrides, monkeypatches, and environment overrides.
-- Do not repeat cleanup setup in individual tests when the repository already handles it globally.
+- Isolate cache state and restore dependency overrides, monkeypatches, and environment overrides through the established fixture lifecycle.
 - Verify cache keys, TTLs, and session values directly when they are part of the contract.
 
 ## 7. Test Double Policy
 
-Use test doubles to move the external world and unstable inputs to the test boundary.
-
 Good targets for test doubles:
 
 - Payment providers, Google Play, Apple, Firebase, S3, Discord, email, and Kafka producers
 - Other servers or external HTTP clients
-- Current time, randomness, and UUIDs
 - Very slow or nondeterministic library calls
 
 Avoid replacing when possible:
@@ -199,8 +115,6 @@ Avoid replacing when possible:
 
 Guidelines:
 
-- Test doubles should make the test condition clearer.
-- If replacing internal collaborators makes the test fragile during refactoring, switch to a larger-scope test.
 - If a dependency is already mocked at an upper boundary, do not also mock the lower DAO unnecessarily.
 - Use `spec` or real-object-based `patch.object` for `Mock` and `AsyncMock` whenever possible.
 - Patch where the object is used, not where it is defined.
@@ -209,72 +123,23 @@ Partial replacement can be better than replacing the whole object. For example,
 
 ## 8. Time, Randomness, And Determinism
 
-Tests should produce the same result every time they run.
-
-- Freeze or patch the current time.
-- When timezone behavior matters, assert the base timezone, UTC conversion, and epoch values explicitly.
-- Use fixed values when randomness, UUIDs, or current time appear in DB values or responses.
-- For ordering-sensitive tests, make `created_at`, `id`, and cursor values explicit.
-- External API response fixtures should contain only the fields needed, but enough fields to represent the edge case.
+For ordering-sensitive queries and pagination, make `created_at`, IDs, and cursor values explicit. Verify timezone conversion or epoch values when they form the storage or response contract.
 
 ## 9. Assertions
 
-Good assertions make it clear what broke when the test fails.
-
-Recommended:
-
 - In API tests, assert `status_code` first.
-- Use snapshots or exact dictionaries when the whole response is the contract.
-- Assert only the important fields explicitly when only some fields are contractual.
 - Verify DB side effects by reading them back through a repository or query.
 - Assert downstream contracts directly, such as event payloads, unique keys, and published flags.
-- For lists, assert length, order, and important identifiers together.
-
-Avoid:
-
-- Assertions that provide little signal, such as `assert response.json() is not None`
-- Overly broad snapshots that fail on unrelated field changes
-- Tests that only assert mock call counts without verifying actual state changes
-- Recomputing the expected value with the same logic as the implementation under test
+- Verify authentication and authorization failures at the server boundary, including rejected requests and the absence of unauthorized side effects.
 
 ## 10. Snapshot Usage
 
-Snapshots are useful when protecting large JSON responses or complex payload contracts.
-
-Use snapshots when:
-
-- The entire response structure is part of the API contract.
-- Volatile values are stabilized with matchers, fixed time, or fixed IDs.
-- Snapshot updates are intentional and reviewed in the same PR as the code change.
-- The diff is small enough for reviewers to understand.
-
-Avoid snapshots when:
-
-- Only a few fields matter.
-- The collection ordering is not stable.
-- Timestamps, UUIDs, or ordering change on every run.
-- The payload is so large that failures are hard to interpret.
-
-## 11. Coverage
-
-Coverage is a signal, not the quality goal itself.
-
-- Whether changed code protects important branches and failure cases matters more than total coverage.
-- If PR coverage is low, explain why the code does not need tests or which higher-level test covers it.
-- Use missing lines in the coverage report to find candidate test targets.
-- Do not add meaningless tests just to increase coverage.
+Response JSON and event payloads can be snapshot targets when their full shape is a stable backend contract.
 
-## 12. Review Checklist
+## 11. Review Checklist
 
-Apply the [Review Checklist](common.md#review-checklist), and check the implementation and remaining risks:
+Check these backend-specific concerns:
 
-- If the scope was narrowed, is the reason clear?
-- Do the name and docstring accurately describe what the test exercises and observes?
-- Is the `given / when / then` flow clear?
 - Can DB, cache, and dependency overrides leak between tests?
-- Are time, UUIDs, randomness, and ordering deterministic?
-- Are necessary failure, permission, and authentication cases covered?
+- Are server authentication and authorization enforced, including rejected requests and unauthorized side effects?
 - Are backend-specific concerns such as pagination, cursors, idempotency, and transactions covered?
-- If a snapshot is used, can reviewers understand the diff?
-- If test doubles keep increasing, should the test move to a larger scope?
-- If fixtures hide too many conditions, should those conditions move back into the test body?

package/engineering/skills/test-review/references/common.md

@@ -1,6 +1,10 @@
 # Common Testing Standards
 
-Sections shared by [frontend.md](frontend.md) and [backend.md](backend.md).
+Apply these standards to every test review. Frontend and backend guides add stack-specific rules and examples.
+
+## Meaningful Failure
+
+Tests should fail when the behavior they protect is broken and make the broken requirement clear. Improve the name, setup, or assertions when a failure is hard to interpret. If a refactor breaks a test without changing observable behavior, reconsider its implementation coupling.
 
 ## Test Target Value
 
@@ -8,12 +12,62 @@ Do not try to test all code at the same density. Evaluate the protection each te
 
 - Before adding or retaining a test, identify the important regression it catches that existing tests do not adequately cover.
 - When a new feature reuses shared behavior, check what existing tests already protect. Add tests for how the feature uses that behavior and for any differences in its contract, rather than copying all tests for the shared behavior.
+- When an integration test already protects a behavior, add narrower tests only when they provide independent protection or clearer checks of important edge cases.
 - Before removing a test, confirm that important requirements and failure cases remain protected.
+- Give lower priority to simple getters, setters, type declarations, and behavior already guaranteed by libraries or static analysis. Test application requirements those guarantees do not cover.
+
+## Test Scope
+
+Start from an existing public entrypoint and preserve the real collaboration needed to deliver the behavior. A test can involve several components while protecting one focused concern. Prefer integration tests when they give a clear signal; unit tests suit naturally small rules such as calculations, parsers, and validators.
+
+- Narrow the scope when setup obscures the scenario, failures are difficult to isolate, dependency replacement dominates the test, execution cost hurts feedback, or one rule needs many focused edge cases. Keep the reason clear and check what integration protection remains.
+- Replace external or unstable dependencies at the test boundary without replacing the behavior under test. If internal mocks keep increasing or make refactoring fragile, reconsider a larger scope.
+- Before changing production code for testability, check existing public interfaces. Do not expose private members or add abstractions solely for testing convenience; require a clear behavioral testing benefit for design changes.
 
 ## Focused Scenarios
 
 Keep each scenario focused on its intended behavior. Combine multiple actions when their sequence is itself the requirement, not merely because they can be placed in one workflow. Do not extend an existing test with unrelated assertions for a new feature when that behavior belongs in another test.
 
+- Make each test understandable on its own, including when setup is shared. Names and descriptions should reveal the scenario and observable outcome; do not claim to verify behavior replaced by a test double.
+- Keep setup, action, and observable results in the Given / When / Then flow. Multiple assertions should describe results of the same behavior.
+- Parameterize cases of the same behavior with readable case names when they share an execution flow. Split cases when branches obscure their distinct scenarios.
+
+## Fixtures And Isolation
+
+- Reuse established setup for infrastructure outside the test's concern, while keeping scenario-specific conditions and actions visible.
+- Create only the data required for the scenario, with enough fields and variation to represent its edge cases.
+- Avoid helpers that create excessive data, accept many scenario-specific parameters, or hide conditions behind deep dependency chains.
+- Extract helpers for clarity; a little duplication is preferable to hiding the scenario. Use names that reveal the provided state, share helpers when multiple features reuse them, and keep feature-specific helpers near the feature.
+- Ensure mutable state and test overrides cannot leak between tests. Choose isolation or restoration appropriate to the resource; reuse established cleanup instead of repeating it when the environment already handles it.
+
+## Deterministic Inputs
+
+Control unstable inputs when they affect the behavior or assertions.
+
+- Use fixed or controlled time, randomness, and UUIDs when their values matter to the scenario.
+- For ordering-sensitive behavior, make sort inputs explicit and verify the required order.
+- When timezone behavior is contractual, verify the relevant timezone, conversion, or epoch values.
+
+## Assertions And Failure Cases
+
+- Derive expected outcomes from requirements, independently of production logic. Avoid tautological tests that repeat production logic or assert only mock setup.
+- Assert the observable results and outgoing interactions that form the contract. Check specific fields when only those fields matter, and exact objects when the whole payload is contractual.
+- For lists, verify length, order, and item identities when those properties are requirements.
+- Existence checks or mock call counts are sufficient only when existence or call count is itself the contract, such as preventing duplicate sends. Otherwise verify the intended result or payload.
+- Cover failure, permission, and authentication cases relevant to the changed behavior through observable outcomes at the tested boundary.
+
+## Snapshots
+
+Use snapshots when the full shape of a focused output is a stable contract and reviewers can understand its diff.
+
+- Stabilize volatile values and ordering using appropriate matchers or controlled inputs.
+- Update snapshots intentionally and review their changes with the code change.
+- Prefer explicit assertions when only a few fields matter. Avoid snapshots covering unrelated output or producing too much data to interpret.
+
+## Coverage
+
+Coverage is a signal for finding test gaps, not a quality goal. Protection of important branches and failure cases matters more than the percentage. Use uncovered code to identify candidate scenarios, explain protection elsewhere or low-value targets when relevant, and do not add meaningless tests to raise coverage.
+
 ## Review Checklist
 
 Start with the test's purpose and contribution to the suite:
@@ -24,7 +78,15 @@ Start with the test's purpose and contribution to the suite:
 
 Then check:
 
-- Would this test actually fail if that behavior broke?
+- Would this test actually fail if that behavior broke, or do its assertions merely repeat production logic or mock setup?
 - Does it preserve useful collaboration between real components while keeping its concern focused?
+- If the scope was narrowed, is the reason clear and is necessary integration protection retained?
+- Do the name and description accurately reflect the scenario and observable outcome, with a clear Given / When / Then flow?
 - Does the test verify externally observable behavior instead of internal implementation?
 - Do test doubles replace external or unstable dependencies without replacing the behavior under test?
+- Do fixtures expose the important conditions with only the necessary data, or should hidden setup move into the test body?
+- Can mutable state or test overrides leak between tests?
+- Are inputs that affect the result controlled, including time, UUIDs, randomness, and ordering?
+- Do assertions verify the required results, payloads, or interactions rather than incidental properties?
+- Are relevant failure, permission, and authentication cases covered?
+- If a snapshot is used, does it protect a focused contract with a readable diff?

package/engineering/skills/test-review/references/frontend.md

@@ -1,23 +1,8 @@
 # Frontend Testing Guide
 
-This guide defines the frontend testing standards our team uses when deciding what to test, how to structure tests, and which tradeoffs to make in this codebase.
+This guide adds frontend-specific rules and examples to the shared standards in `common.md`.
 
-## 1. Testing Philosophy And Value
-
-### 1.1 Meaningful Failure
-
-Tests are not written just to see `Pass`. They should fail when the behavior they protect is broken.
-
-- A test that can keep passing after a meaningful regression does not improve safety. It only increases maintenance cost.
-- When requirements change or a bug is introduced, the test must fail and provide a signal.
-- Regression tests and snapshot tests are still valuable when they protect behavior that would fail after an unintended change.
-- If a test does not meaningfully fail for any realistic change, reconsider whether it should exist at all. In many cases, deleting it is the better choice.
-
-### 1.2 Value-Driven Target Selection
-
-Apply [Test Target Value](common.md#test-target-value), and:
-
-- When an integration test already protects a behavior, do not automatically repeat it in unit tests for every participating component or composable. Add focused tests where they provide additional protection or clearer checks of important edge cases.
+## 1. Test Targets
 
 Prioritize behaviors that matter most to users and the business:
 
@@ -30,14 +15,12 @@ Prioritize behaviors that matter most to users and the business:
 
 We follow Kent C. Dodds' `Testing Trophy` model, with the strongest emphasis on integration tests.
 
-Prefer tests that keep the real collaboration needed to deliver a feature intact. A test can exercise components, composables, and state management together while protecting one clearly defined behavior. The number of participating components and the number of concerns being tested are separate choices.
-
-Apply [Focused Scenarios](common.md#focused-scenarios).
+Component integration tests can exercise rendering, composables, and state management together.
 
 1. `Static (Lint/Type)`
-   Use TypeScript and ESLint to catch typos, type mismatches, and other basic mistakes. Do not duplicate test coverage for things that static analysis already verifies well.
+   Use TypeScript and ESLint to catch typos, type mismatches, and other basic mistakes.
 2. `Unit`
-   Verify highly complex calculations or isolated pure functions.
+   Verify calculations or naturally small units such as pure functions, parsers, and validators.
 3. `Integration`
    This is our primary tactic. Verify whether multiple components work together to deliver a feature. Prefer sociable tests with minimal mocking.
 4. `E2E`
@@ -105,31 +88,14 @@ describe('applyDiscount', () => {
 ```
 
 - Name each `describe` block after the test target. Example: component name, hook name, public function name
-- Write each `it` or `test` block as a sentence that describes the expected outcome in that context.
+- Write each `it` or `test` block as a scenario and observable outcome.
 - Do not nest child `describe` blocks. If you need another context, split it into another top-level `describe` block instead.
-- Make test names specific enough to reveal both the situation and the expected result.
-- Prefer capability-oriented names over implementation-shaped names.
-  Example: `user can checkout with a valid cart` is better than `calls submitOrder with transformed payload`.
-- Describe what the test actually exercises and observes. Do not claim to verify behavior that has been replaced by a test double.
-- Use parameterized tests with readable case names for cases of the same behavior that share an execution flow. Split cases when combining them introduces branches that obscure their different scenarios.
-
-## 4. Test Writing Principles
-
-### 4.1 Black-box Tests
+- Use `it.each` or `test.each` for cases that share an execution flow.
 
-Test externally observable behavior, not internal implementation details.
+## 4. Black-box Component Tests
 
 - Do not read private properties or component-internal state directly.
 - Write tests from a black-box perspective. If input A is applied, does the user observe result B?
-- If a refactor breaks the test without changing behavior, the test was too coupled to the implementation.
-
-### 4.2 Avoid Designing Only For Tests
-
-Be careful not to damage production code readability or introduce unnecessary abstractions just to make tests easier to write.
-
-- First check whether the behavior can be verified through an existing public entrypoint before changing production code for testability.
-- Change the design only when the testing value clearly outweighs the design cost.
-- In most cases, improving a function interface is better than making the design more complex for testability.
 
 ## 5. Practical Guide
 
@@ -141,8 +107,6 @@ For consistency, every test follows the `AAA (Given-When-Then)` pattern, and eac
 - `When`: The behavior under test
 - `Then`: Observable results of `When`, such as rendered UI, user-visible state, and outgoing requests or events
 
-One test may verify multiple results, but they should all come from the same behavior.
-
 ```tsx
 it('상품 수량을 변경하면 장바구니 총액이 재계산된다', async () => {
   // Given
@@ -178,8 +142,6 @@ it('쿠폰을 적용하면 최소 주문 금액 조건을 만족할 때만 할
 
 ### 5.2 Mocking Policy
 
-Limit mocking to the external world that we do not control. Compared with unit tests that heavily mock internal collaborators, integration tests with real collaboration boundaries are more resilient to refactoring and more trustworthy from the user's perspective.
-
 - Mock API calls at the network boundary with `MSW (Mock Service Worker)` instead of mocking server logic directly.
 - Prefer testing the integrated state where parent and child components actually collaborate.
 
@@ -187,7 +149,6 @@ Limit mocking to the external world that we do not control. Compared with unit t
 
 For MSW-based tests, do not repeat the same setup in every spec. Build tests on top of a shared test environment, then override only the conditions required for the scenario with `server.use(...)`.
 
-- Control behavior at the network boundary.
 - Do not default to fine-grained `vi.mock()` calls against internal composables or API modules.
 - Write overrides so that they reveal only the condition the test is trying to validate.
 - Prefer helpers with obvious intent over large and noisy fixture payloads.
@@ -196,13 +157,12 @@ For MSW-based tests, do not repeat the same setup in every spec. Build tests on
 
 Reuse established setup helpers for dependencies outside the test's concern. For example, query client, store, injectables, and browser storage are usually better provided by the default test environment than recreated in each spec.
 
-Keep scenario-specific conditions and the execution flow visible in the test body. Extract helpers to make scenarios easier to understand, not just to remove repeated lines. A little duplication is preferable to an abstraction that hides those details.
+Isolate or reset query caches, stores, and browser storage, and restore MSW handlers, mocks, and environment overrides between tests.
 
 #### 5.2.3 Test Double Usage Standard
 
 In black-box component tests, keep real rendering whenever possible.
 
-- Do not increase test double usage just to make the test easier to write.
 - Consider stubs, spies, or mocks only when unrelated side effects make the test unstable or too noisy.
 - If a test double is necessary, its reason should be easy to explain.
 
@@ -219,7 +179,7 @@ In component tests, the synchronization point should not be "has the request fin
 
 ### 5.4 Handling Non-Deterministic Inputs
 
-Move unstable values such as current time or randomness to the test boundary.
+For date-dependent UI, pass a fixed base date when the interface supports it:
 
 ```ts
 // Before
@@ -239,6 +199,15 @@ it('마감일은 기준일로부터 7일 후다', () => {
 });
 ```
 
+### 5.5 Assertions And Failure Cases
+
+- Verify rendered results, user-visible state, and outgoing request or event payloads that form the frontend contract.
+- Verify failures through error feedback, restricted actions, and sign-in flows as appropriate to the changed behavior.
+
+### 5.6 Snapshot Targets
+
+Use rendered-structure or payload snapshots when their full shape is a stable frontend contract.
+
 ## 6. UI Verification And Accessibility
 
 We avoid pixel-perfect visual regression tests by default. Screen structure and styles change often, and their maintenance cost is high. Instead, prioritize stable properties that users actually perceive and interact with.
@@ -292,10 +261,12 @@ expect(within(row).getByText('72,000')).toBeInTheDocument();
 - Positional selectors such as `nth-child`
 - Auto-generated or meaningless `id` values
 - Text that is likely to change often
-- Broad snapshot comparisons
 
 ## 7. Review Checklist
 
-Apply the [Review Checklist](common.md#review-checklist), and check:
+Check these frontend-specific concerns:
 
-- Do the name and description accurately reflect what the test exercises and observes?
+- Do queries identify UI through accessible roles, labels, or meaningful user-visible context?
+- Does async synchronization wait for the intended DOM state?
+- Can query caches, stores, browser storage, or MSW overrides leak between tests?
+- Are relevant errors, restricted actions, and sign-in flows verified through observable frontend behavior?

package/engineering/skills/work-breakdown/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: work-breakdown
+name: ghosts:work-breakdown
 description: Design-only recursive work breakdown of a destination into independently reviewable work packages with interfaces, dependencies, and execution order.
 disable-model-invocation: true
 ---

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

package/research/skills/loop-research/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: loop-research
+name: ghosts:loop-research
 description: Use for evidence-backed research or explanations of current, contested, comparative, learning-oriented, or consequential questions; skip simple stable facts.
 ---
 

package/tools/skills/vibe-notion/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: vibe-notion
+name: ghosts:vibe-notion
 description: Manage Notion pages, databases, blocks, users, and comments with the Vibe Notion CLI.
 version: 1.10.0
 allowed-tools: Bash(vibe-notion:*)

package/writing/skills/cold-reader/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: cold-reader
+name: ghosts:cold-reader
 description: Draft or revise PR descriptions, ADRs, design documents, implementation plans, review responses, and other engineering artifacts for readers who did not participate in the preceding conversation. Do not use for casual conversation, ordinary code comments, or documents explicitly intended to rely on linked prior context.
 ---
 

package/writing/skills/eli5/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: eli5
+name: ghosts:eli5
 description: Explain any supplied topic to a complete beginner as a self-contained HTML artifact with big visuals, few words, and simple examples.
 disable-model-invocation: true
 ---

package/writing/skills/humanize-korean/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: humanize-korean
+name: ghosts:humanize-korean
 description: 한국어 원문의 의미·사실·장르를 보존하면서 번역투, AI 관용구, 기계적인 구조와 리듬만 필요한 범위에서 국소적으로 줄인다.
 disable-model-invocation: true
 ---

package/writing/skills/loop-skills/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: loop-skills
+name: ghosts:loop-skills
 description: Simple loop for creating, reviewing, or improving concise agent skills.
 disable-model-invocation: true
 ---

package/writing/skills/rewrite/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: rewrite
+name: ghosts:rewrite
 description: Rewrite a prompt for maximum signal-to-noise without changing its intended behavior.
 disable-model-invocation: true
 ---