@solaqua/ghosts 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# ghosts
+
+Reusable agent skills and reviewers.
+
+Default bias: delete needless layers, reuse what exists, and keep the smallest
+safe instruction that preserves the behavior.
+
+## Install
+
+Install all skills globally for your agent:
+
+```sh
+npx @solaqua/skul@latest add --global --agent codex sjquant/ghosts --all
+```
+
+Replace `codex` with the name of the agent you use, if different.
+
+## Bundles
+
+- `engineering/`: implementation, planning, review, and collaboration skills
+  with their reviewers.
+- `research/`: bounded, evidence-grounded research and explanation skills.
+- `writing/`: writing, rewriting, and change-explanation skills.
+- `tools/skills/`: directly maintained tool-integration skills, including
+  `vibe-notion`.
+- `registry/`: external skill references that are not maintained in this
+  repository.
+
+## Upstream sources
+
+| Local component | Upstream | Pinned revision | License |
+| --- | --- | --- | --- |
+| `writing/skills/humanize-korean/references` | [`epoko77-ai/im-not-ai`](https://github.com/epoko77-ai/im-not-ai), `skills/humanize-korean/references` | [`9747f03`](https://github.com/epoko77-ai/im-not-ai/tree/9747f036cdc28a1a8aea4dc71fef1f7846eb96f7) | MIT |
+| `tools/skills/vibe-notion` | [`devxoul/vibe-notion`](https://github.com/devxoul/vibe-notion), `skills/vibe-notion` | [`89c6643`](https://github.com/devxoul/vibe-notion/tree/89c6643cebb4e4c56bbde826b6557da77f9d9d2f) | MIT, declared in the upstream README |
+
+The vendored Vibe Notion skill includes an `UPSTREAM.md` file with its source
+path and maintenance notes.
+
+The standalone `humanize-korean` skill selectively syncs applicable rules from
+the upstream revision above. Upstream orchestrator, plugin, and agent-runtime
+paths are intentionally excluded.

package/common/AGENTS.md

@@ -0,0 +1,19 @@
+## Coding
+
+- Order functions so each callee appears below its caller.
+- Write tests as behavioral specifications: each test docstring or doc comment must stand alone, describe the scenario and observable outcome, and avoid relying on surrounding context, implementation details, or comparative wording. Keep names concise and behavior-based (JS/TS `it(...)` / `test(...)` descriptions suffice), and use `Given` / `When` / `Then` sections in the body.
+- When complex setup, concurrency, timing, or multi-step control flow makes a test hard to follow, add concise comments at key transitions to explain the scenario and synchronization; do not narrate obvious code.
+- Avoid low-value, brittle, implementation-coupled, or over-mocked tests—including tests that merely restate literals, constants, or configuration wiring; prefer outside-in integration tests through public interfaces, and add tests only when they specify meaningful externally observable behavior or guard against a substantive regression.
+- Treat test-suite growth as a cost: avoid redundant or low-signal tests whose behavior is already meaningfully covered elsewhere, unless they add independent behavioral confidence or protect a distinct regression risk.
+- Do not expose private members solely for testing.
+- Keep tests focused on current, externally observable behavior: do not add temporary tests solely for intermediate layers when a planned integration test better specifies the behavior, or regression tests for intentionally removed code paths; add tests only when omitting them leaves an immediate regression or safety gap, and update or remove obsolete tests instead.
+- Do not preserve backward compatibility. Remove obsolete paths instead of adding compatibility layers, fallbacks, or migrations.
+
+## Agent Browser CLI
+
+- Standardize the startup routine to `agent-browser close` → `agent-browser --profile <abs-path>`.
+- Restrict profile paths to `~/.agent-browser/profiles/sjquant`; if login is required, relaunch headed and ask the user to authenticate before proceeding.
+
+## Obsidian CLI
+
+- If the obsidian CLI is unavailable, start the Obsidian desktop app first and retry.

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

@@ -0,0 +1,46 @@
+---
+name: code-review
+description: Broad, read-only code review using general agents and complete result synthesis.
+disable-model-invocation: true
+---
+
+Review the change read-only. Use general agents; give them the change context and questions only—no roles, review commands, or extra prompts.
+
+Consider every question below. Mark irrelevant questions `N/A — <reason>`. The main agent answers each applicable question. Assign applicable questions once across one, two, or three agents without overlap.
+
+- `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?`
+
+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`.
+
+- Write in the user's language.
+- If a GitHub URL is supplied, use a bare, commit-pinned `blob` permalink with the smallest relevant line range in each `Location`.
+- Otherwise, use repository-relative paths.
+- `P0` is release-blocking, `P1` major, `P2` actionable, and `P3` low-priority.
+
+```markdown
+## Findings
+
+### <P0|P1|P2|P3|SKIP> - <title>
+
+- Location: [path/to/file.ext](path/to/file.ext:Lx)
+- Kind: bug|performance|security|design|test|simplification|other
+- Triage: <priority> — <why this feedback received this priority, including why it is low-value or unsupported when priority is `SKIP`>
+- Evidence: <why this matters>
+- Impact / fix: <impact and smallest useful action>
+
+## Review Summary
+
+- Agents used: `<n>`
+- Verdict: `no blocking findings|findings require attention|manual review still required`
+
+## Reviewer Results
+
+- `<agent>`: <every response and the corresponding Findings item>
+```
+
+For GitHub-linked reviews, make `Location` a bare GitHub permalink, for example: `- Location: https://github.com/acme/project/blob/0123abc/src/parser.ts#L42-L48`.
+
+If there are no actionable findings, say so while retaining every candidate in `Findings` with `SKIP` priority and its reason.

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

@@ -0,0 +1,9 @@
+---
+name: deep-module
+description: Assess whether a module hides implementation details behind a simple interface for its callers.
+disable-model-invocation: true
+---
+
+Any excessive implementation details that callers must know from a deep-module perspective?
+
+Assess the module from the intended caller's perspective. Check whether it concentrates complexity behind a simple, stable interface, and identify implementation details, state, lifecycle, ordering, error/retry, or concurrency obligations that callers must know or coordinate themselves, plus any internal collaboration methods exposed as public API. Cite the relevant APIs and call sites, explain the material impact, and distinguish genuine abstraction leaks from legitimate domain requirements. If there is no material issue, say so.

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

@@ -0,0 +1,24 @@
+---
+name: 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
+---
+
+Make the explanation visual-first. Explain like I'm someone who knows nothing about this topic, using an HTML artifact with big pictures and few words. Create one self-contained lesson for the complete target change; prose should label, orient, or clarify the visuals, not replace them. Tell one small visual story instead of dumping code line by line. If the target is missing, ask before acting. Do not invent behavior; distinguish observed facts, inferences, and unknowns.
+
+## Scope and content
+
+- Inspect the complete diff, every commit in the target branch or PR, and enough surrounding code to explain the change.
+- Cover every changed file and symbol. Explain behavior changes; summarize the purpose of tests, configuration, documentation, and mechanical changes instead of omitting them.
+- Use a small set of large HTML/CSS diagrams, cards, arrows, timelines, or inline SVG. Never use ASCII. Each visual has one idea, example data, a short caption, and accessible text, and the set covers every meaningful changed path.
+- Assume zero domain knowledge. Use familiar words, define jargon only when needed, use one concrete example, and keep text blocks to one or two short sentences. Put optional technical depth in `details`.
+- Include these sections in order: **Takeaway**, **Before**, **After**, **How it works**, **Why it matters**, and **Quiz**. Make **How it works** cover every changed path and connect it to the relevant code without adding a separate inventory section. Make **Quiz** five medium-difficulty interactive multiple-choice questions with concise feedback; avoid trivia and gotchas.
+- Add one callout for the key definition, edge case, or tradeoff. Use progressive disclosure for low-impact or mechanical changes, but name their purpose so the whole change remains covered.
+
+## Artifact requirements
+
+- Write one responsive HTML file with a table of contents, semantic headings, inline CSS, and inline JavaScript. Do not load fonts, scripts, images, or data from the network.
+- Save it outside the repository as `/tmp/YYYY-MM-DD-explanation-<slug>.html`, using today’s date and a filesystem-safe slug. Return the absolute path.
+- Make visuals the dominant content and large enough to understand without zooming. Use high-contrast type, large visual targets, visible focus states, keyboard-accessible controls, and feedback that does not rely on color alone. Keep the page viewable by opening it directly.
+- Put code in `<pre><code>…</code></pre>` and preserve whitespace with `white-space: pre` or `white-space: pre-wrap`.
+- Verify links, quiz behavior, code blocks, full-scope coverage, accessibility, and final file existence before delivery.

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

@@ -0,0 +1,36 @@
+---
+name: 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
+
+- If the project's commit message style is unknown, run `git log --oneline -n 2` to identify the existing pattern and language.
+- After this skill is triggered, commit and push every change. If there is no PR yet, create it first.
+- Use the `gh` CLI for GitHub-related work.
+
+## Pull request
+
+### Before updating
+
+- Before updating a pull request, check its current title and body.
+
+### Body
+
+- Use `gh pr edit --body-file - <<'EOF'` as the default PR body path.
+- If `.github/pull_request_template.md` exists, preserve its required structure. Otherwise, structure the body with problem and changes sections as bullet lists.
+  - Explain the problem and its impact in 1–2 sentences.
+  - Summarize the chosen solution direction and key behavioral changes.
+- Write for a reviewer who may not know the repository or the work's prior context. Use direct language, preserve precise domain terms, and make essential premises explicit.
+- Treat length as a cost. Group related points with headings or lists, and include files or implementation details only when essential for review. For complex flows or relationships, use a compact diagram or table abstracted to the level needed to understand the overall change.
+- Base the body on the final diff against the base branch. Recheck that diff before publishing, then remove intermediate iterations, reverted or removed work, review history, and abandoned approaches.
+
+### Title and scope
+
+- Follow the commit message convention for PR titles.
+- Do not include internal planning IDs in the PR title or body, including Waypoint IDs, Task IDs, or roadmap labels such as `W1-A3`.
+
+### Gotchas
+
+- Use the same language as the commits being published for the PR title, body, and headings you add; do not default to English.
+- Upload screenshots with the relevant `gh` CLI command and `--attach <file>#<alt text>`. If `--attach` is unavailable, upgrade `gh` first. Put the uploaded images in Markdown tables with at most 4 columns.
+

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

@@ -0,0 +1,46 @@
+---
+name: loop-coding
+description: Approval-gated loop for building, changing, fixing, or refactoring code.
+disable-model-invocation: true
+---
+
+# Loop Coding
+
+Use this skill when the user asks for an implementation change. Do not use it for read-only review, explanation, specification, or design-only work.
+
+## Runtime loop
+
+Before acting, create `/tmp/loop-coding-<safe-task-slug>.md` with a unique short slug or timestamp. Add `Current state: Pass 1 / Next: Understand`, a task-specific checklist, and an empty append-only `Repair log:`. Process the checklist top to bottom: finish the current item before moving on, record a short outcome, update `Current state`, mark `[x]` only after completion, and use `[-]` only with a reason. Never erase or uncheck historical rows. After a repair, append a numbered `[ ]` recheck row for the earliest affected item, update `Current state`, and log the trigger, change, rechecked items, and result. Finish only after final validation.
+
+Answer every `Any ...?` row Yes or No in its outcome. On Yes, use the earliest affected state and append a row such as `- [ ] Recheck P2: Run relevant checks` before continuing.
+
+Use this checklist, adding only task-specific items that materially affect the
+work:
+
+```text
+- [ ] Understand the request and inspect the relevant code
+- [ ] Draft the plan: behavior, scope, affected files, validation, and any materially better alternative
+- [ ] Any unresolved ambiguity or material design choice? (Ask before implementation when Yes.)
+- [ ] Present the chosen plan and receive explicit approval, unless the user already approved that specific plan
+- [ ] Implement the approved plan
+- [ ] Run relevant checks
+- [ ] Any correctness or operational risk: bugs, edge cases, races, leaks, performance, scalability, or security?
+- [ ] Any design or API issue from outside-in, deep-module, or dependency-direction perspectives?
+- [ ] Any opportunity to simplify or clarify through naming, standard libraries, utilities, or existing abstractions?
+- [ ] Any test smell: brittleness, implementation coupling, over-mocking, unclear intent, missing negative paths, or surviving mutants?
+- [ ] Any excessive implementation details that callers must know from a deep-module perspective?
+- [ ] Final validation
+```
+
+For the plan, state the chosen direction, relevant alternative and tradeoff, affected files, and validation. Present it as a structured, execution-oriented implementation plan in Markdown format. Wait for explicit approval such as `go` or `approve`; a bare request is not approval unless it already specifies the plan. If requirements or a material scope/design choice remain unresolved, stop and ask the user rather than guessing.
+
+After implementation and checks, answer each review question in order. For a Yes, make the smallest useful repair, rerun relevant checks, append the required recheck row and repair-log entry, then resume from the earliest affected state. A material scope or design change requires a revised plan and approval. Stop when every answer is No, checks pass, and the diff stays within the approved scope.
+
+```text
+[Start] → [Understand] → [Plan + approval] → [Implement] → [Checks] → [Review] → Any issue?
+                                                                            ├─ No → [Final validation] → [Done]
+                                                                            ├─ scope/design → [Re-plan + approval] → [Implement]
+                                                                            └─ code/tests/checks → [Repair] → [Checks] → [Review]
+```
+
+Final response: summarize what changed, the checks run, and any remaining uncertainty.

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

@@ -0,0 +1,229 @@
+---
+name: 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
+---
+# Loop Plan
+
+Create a plan another person or agent can execute without rediscovering key
+decisions. Inspect context and write planning artifacts only; stop before
+implementation or invoking an execution skill. Scale depth to uncertainty and
+the cost of a wrong decision, not the number of tasks or document length. For
+other domains, replace files, interfaces, and tests with the relevant
+deliverables, dependencies, and verification; omit software-only checks.
+
+## Runtime loop
+
+Before acting, create `/tmp/loop-plan-<safe-task-slug>.md` with a unique slug
+or timestamp, `Current state: Pass 1 / Next: Understand`, the checklist below,
+and an empty append-only `Repair log:`. Process items in order, finish each
+before moving on, record a short outcome, and update `Current state`. Mark
+`[x]` only after completion and `[-]` only with a reason; never erase or
+uncheck historical rows. After a repair, append a numbered `[ ] Recheck P2: ...`
+row for the earliest affected item and record the trigger, change, rechecked
+items, and result in the repair log. Finish only after final validation.
+
+```text
+- [ ] Understand the outcome, constraints, and relevant evidence
+- [ ] Resolve research and user-decision dependencies before framing
+- [ ] Frame success, scope, principles, and decision drivers
+- [ ] Set the review budget from uncertainty, impact, and reversibility
+- [ ] Compare viable approaches and choose a provisional direction
+- [ ] Draft ordered work packages and validation
+- [ ] Challenge the design and run a premortem
+- [ ] Any unsupported assumption, unresolved decision, or stronger alternative that changes the plan?
+- [ ] Any unaddressed failure, dependency, or unverifiable completion criterion?
+- [ ] Any unnecessary scope, complexity, or detail?
+- [ ] Final validation and delivery of the plan
+```
+
+Answer every `Any ...?` row Yes or No. On Yes, repair the smallest material
+issue and return to the earliest affected step before repeating the review. If
+progress depends on missing evidence or a user decision, identify the exact
+blocker instead of repeating the review or claiming readiness.
+
+## Adaptive review
+
+Do not make the user choose a mode. After framing, keep a decision ledger with
+each material decision's impact, uncertainty, reversibility, and needed
+evidence. Use qualitative `low`, `medium`, or `high` values and states such as
+`open`, `investigating`, `supported`, `disputed`, `gated`, and `closed`.
+Require at least one independent targeted review for a decision with high
+impact and high uncertainty, low reversibility, or cross-component effects. A
+request for `ralplan` or subagents raises the review budget without imposing a
+fixed ceremony.
+
+```text
+[Understand] → [Route unknowns]
+                  ├─ evidence → [$loop-research] ┐
+                  ├─ user decision → [$socratic-interview] ├→ [Frame + ledger] → [Draft]
+                  └─ known →─────────────────────┘              ↓
+                                                     [Any high-impact uncertainty?]
+                                                       ├─ No → [Self challenge]
+                                                       └─ Yes → [Targeted subagent questions]
+                                                                   → [Synthesize] → [Revise] ↺
+                                                         → [Premortem] → [Any material issue?]
+                                                         → [Validate + deliver]
+```
+
+For each unresolved ledger item, record a question ID, covered decision IDs,
+capability, required inputs, `depends_on` question IDs, decision criterion,
+and required evidence. Dispatch only ready questions; run independent ones in
+parallel and refresh the snapshot after upstream results.
+
+Choose a narrow capability rather than a permanent role:
+
+- **Investigation:** establish a missing fact, constraint, dependency, or
+  feasibility signal.
+- **Design challenge:** test boundaries, responsibilities, dependency
+  direction, and the strongest case against the chosen approach.
+- **Execution challenge:** test prerequisites, rollout, recovery,
+  observability, and demonstrable completion.
+- **Adversarial challenge:** identify a credible failure or attack path when
+  relevant.
+
+Give each subagent the exact question, context snapshot, candidate options,
+decision criterion, and required evidence. Keep it read-only and request
+`finding`, `evidence`, `consequence`, and `recommendation`. Record each call as
+`complete`, `failed`, `timed_out`, or `invalid`. Retry or reassign once when
+useful, counting that attempt against the single follow-up budget; then use
+self-review only when the risk permits. An unresolved high-impact item stays
+`conditional` or `blocked`.
+
+When two independent reviews are warranted, give them the same snapshot without
+either review's findings, then record disagreements and their resolution. The
+primary agent alone synthesizes the findings, records which decision changed
+and why, and revises the draft.
+
+When a finding changes a material decision, scope, or acceptance criterion,
+send the revised delta to the relevant completed reviewer for one confirmation
+pass. Ask whether the original concern is resolved, what new consequence the
+revision creates, and whether a material objection remains. Record the response
+and any objection in the question record and Review manifest. Skip the pass
+when no material change occurred; when used, it counts against the single
+follow-up budget and is review evidence, not user approval.
+Preserve blind independence for reviews that have not run. If confirmation is
+unavailable or a material objection remains, keep the item `conditional` or
+`blocked`.
+
+Set a bounded budget at delegation: one initial question per high-impact item,
+one follow-up per item for conflicting, insufficient, or materially changed
+evidence or drafts (including retry, reassignment, or confirmation), and at
+most five synthesis passes. Repeat only while a material item lacks support or
+a credible objection remains. Stop when high-impact decisions have evidence or
+explicit gates, no unresolved objection changes the recommendation, and
+acceptance and verification criteria are concrete. If the budget is exhausted
+or the same material objection survives two revisions, deliver `conditional`
+or `blocked` with the exact reason. If delegation is unavailable, perform the
+same questions as self-review and state that no independent review occurred.
+Subagent findings are review evidence, never user approval or authorization to
+implement.
+
+For high-risk work, deepen relevant challenges with three premortem scenarios
+and the verification levels the problem needs. Do not add irrelevant test
+layers to a design-only problem.
+
+## Understand and frame
+
+Inspect relevant code, documents, existing plans, and constraints before asking
+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,
+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.
+
+## Compare and draft
+
+Compare at least two genuinely viable approaches against the same principles
+and drivers, including a smaller change or no change when viable. Give each its
+strongest case, cost, and downside. If only one survives the constraints,
+explain why the alternatives fail. Recommend a direction, name the accepted
+tradeoff, and state what evidence would reverse it.
+
+Break the direction into dependency-ordered, independently verifiable work
+packages. For each, name the outcome, affected components or files, important
+interfaces, prerequisites, and completion evidence. Prefer end-to-end slices;
+mark proposed paths as new and verify existing references. Specify correctness
+contracts and ordering without prescribing incidental implementation details.
+Do not invent precise estimates or parallelism without a basis.
+
+Map success criteria to concrete checks, including material failure paths and
+relevant existing tests. Add tests only for meaningful behavior. Include
+rollout, observability, recovery, or stop conditions when operational
+consequences require them.
+
+## Challenge and repair
+
+Review a fixed draft in two separate self-review passes before revising:
+
+1. **Design challenge:** make the strongest case against the recommendation;
+   check principle violations, responsibility boundaries, dependency direction,
+   and whether a simpler alternative achieves the outcome. Resolve a real
+   tension through evidence or an explicit tradeoff.
+2. **Execution challenge:** walk through representative work packages as an
+   implementer, including a failure path; check prerequisites, missing
+   decisions, feasibility, and demonstrable completion.
+
+These are not independent agent consensus. If the user requests separate
+reviewers, give them the same draft and source context without the other
+review's conclusions, combine findings only after both finish, and do not claim
+independent review unless it occurred.
+
+Run a premortem: assume failure at a meaningful milestone and trace the most
+consequential plausible failures to plan details. For each, capture the causal
+sequence, enabling assumption, likelihood and impact separately, earliest
+warning, check time, mitigation, and revision or stop trigger. Label unverified
+scenarios as hypotheses and thresholds as provisional; do not invent numerical
+probabilities or promise to eliminate every risk. Include an adversary's
+response only when adversarial behavior is relevant to the actual problem.
+
+Use findings to change the plan and give a short reason for each material
+revision. Put cheap checks of critical assumptions before expensive dependent
+work. Resolve material objections or expose them as blockers; do not bury them
+in a risk list. Recheck affected decisions and packages after each repair.
+
+## Deliver
+
+Save the plan to the user-specified path if one is given; otherwise use
+`/tmp/loop-plan-<safe-task-slug>-result.md` (append a timestamp when a collision
+is possible). Keep the runtime log separate. Make the plan understandable
+without the preceding conversation and include only what the task needs:
+
+- Outcome, success criteria, scope, constraints, and evidence or assumptions.
+- Decision principles, ranked drivers, alternatives, chosen direction, and
+  accepted consequences or conditions that would change the decision.
+- Decision ledger with material uncertainties, review evidence, revisions, and
+  explicit gates.
+- Review manifest mapping each material decision to question or call IDs,
+  initial and follow-up evidence, confirmation status, affected plan section,
+  verification criterion, and unresolved disagreement.
+- Ordered work packages, dependencies, affected files or interfaces, and
+  completion checks.
+- Premortem findings, mitigations, early signals, and revision or stop criteria.
+- Unresolved questions or prerequisite investigations, material review changes,
+  and readiness: `ready for approval`, `conditional`, or `blocked`, with reasons.
+
+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
+approval of that plan and let its implementation workflow own execution. End
+with the plan path, chosen direction, and remaining decisions.

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

@@ -0,0 +1,22 @@
+---
+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:
+```

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

@@ -0,0 +1,37 @@
+---
+name: task-handoff
+description: Generate concise task handoffs for independent implementation workstreams.
+disable-model-invocation: true
+---
+
+Generate up to two concise English handoffs for independent implementation tasks by default. If the invocation specifies a positive maximum N, generate up to N handoffs; treat N as a cap. Output each handoff in a code block; do not create a handoff document.
+
+Use the configured project-notes and task-tracker system. If the source is unclear, ask which one to use before making updates.
+
+Before writing:
+
+1. Read relevant project notes and task entries.
+2. Sync the base branch with the latest remote state.
+3. Mark implementation tasks with merged PRs `DONE`; keep implemented but unmerged tasks `REVIEW`.
+4. Select implementation tasks not marked `[DOING]` and mark selected tasks `[DOING]`.
+5. If all tracked tasks are complete, report that instead of creating handoffs.
+
+## Handoff Content
+
+Include only:
+
+- task
+- problem
+- solution direction
+- completed work
+- next task and starting point
+- done criteria
+- required project-notes and repository startup commands, including base-branch sync
+
+Keep the problem and solution direction concise. Do not repeat commands already required by `AGENTS.md` or `CLAUDE.md`.
+
+## Constraints
+
+- Include only tasks that can proceed fully in parallel; do not combine tasks with ordering or dependency relationships.
+- When generating multiple handoffs, choose the eligible set of up to N tasks that minimizes overlap in files or modules they are likely to modify. Use the task scopes and file/module references in project notes and task entries to estimate overlap.
+- Do not mention branch or worktree details.

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

@@ -0,0 +1,26 @@
+---
+name: 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
+---
+
+Given a destination, recursively decompose it into independently reviewable work packages. Do not implement; the only deliverable is the confirmed work breakdown.
+
+- Keep each leaf within the review budget, normally `<= 1000 LOC`.
+- Define the upper-layer interface before decomposing its children.
+- Prefer end-to-end slices that can be tested and merged independently.
+- Stop when every leaf is reviewable, testable, and mergeable.
+- Use Socratic questioning only for material design or decomposition trade-offs.
+
+For each package, capture its scope, rough LOC estimate, dependencies, and status:
+
+- `TODO`: not started
+- `DOING`: in progress
+- `REVIEW`: pull request open
+- `DONE`: pull request merged into the base branch
+
+After confirmation, output:
+
+1. The hierarchical work-breakdown tree.
+2. The dependency and parallel-execution graph.
+3. The dependency-ordered execution list.

package/manifest.json

@@ -0,0 +1,3 @@
+{
+"root_instruction_mode": "replace"
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@solaqua/ghosts",
+  "version": "0.1.0",
+  "description": "Reusable agent skills and reviewers.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sjquant/ghosts.git"
+  },
+  "files": [
+    "common",
+    "engineering",
+    "registry",
+    "research",
+    "tools",
+    "writing",
+    "manifest.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/registry/skul.refs.json

@@ -0,0 +1,55 @@
+{
+  "refs": [
+    {
+      "target": "skills",
+      "name": "insane-search",
+      "source": "fivetaku/insane-search",
+      "ref": "c020292fedcf1213d815acceacf600402fe72332"
+    },
+    {
+      "target": "skills",
+      "name": "obsidian-cli",
+      "source": "kepano/obsidian-skills",
+      "ref": "8ccef29ae8624eccc734e77ced4a6e54baf5d83a"
+    },
+    {
+      "target": "skills",
+      "name": "context7-cli",
+      "source": "upstash/context7",
+      "ref": "6f42b66f3b6dee20ba870dd6f70f1b565eb62e6e"
+    },
+    {
+      "target": "skills",
+      "name": "agent-browser",
+      "source": "vercel-labs/agent-browser",
+      "ref": "8c15ff9f71ae60c7e99e66afe1e2d4b9bf414fe2"
+    },
+    {
+      "target": "skills",
+      "name": "sentry-cli",
+      "source": "getsentry/cli",
+      "bundle": "sentry-cli",
+      "ref": "0b43edad47386844ece1f9f288310e2683afce49"
+    },
+    {
+      "target": "skills",
+      "name": "orca-cli",
+      "source": "stablyai/orca",
+      "ref": "fe4237cd41e4d48793fd135640939ef8aa5418e0"
+    },
+    {
+      "target": "skills",
+      "name": "cram",
+      "source": "sjquant/cram",
+      "ref": "f79db070a29e9e719b55fc9084f4a29580c6f1d4",
+      "disable-model-invocation": true
+    },
+    {
+      "target": "skills",
+      "name": "pr-tour",
+      "source": "YunSinLee/pr-tour",
+      "ref": "baf67b724298a874be88e8124141aa4b9950988c",
+      "disable-model-invocation": true
+    }
+  ]
+}