pattyeng 1.0.4 → 1.0.7

package/skills/review/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: review
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+---
+
+# Review
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Don't be opinionated; pass it through. If they didn't specify one, ask: "Review against what — a branch, a commit, or `main`?" Don't proceed until you have it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. A path the user passed as an argument.
+3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written. Common locations:
+
+- `CLAUDE.md`, `AGENTS.md`
+- `CONTRIBUTING.md`
+- `CONTEXT.md`, `CONTEXT-MAP.md`, per-context `CONTEXT.md` files
+- `docs/adr/` (architectural decisions are standards)
+- `.editorconfig`, `eslint.config.*`, `biome.json`, `prettier.config.*`, `tsconfig.json` (machine-enforced standards — note them but don't re-check what tooling already checks)
+- Any `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md`, or similar at the repo root or under `docs/`
+
+Collect the list of files. The **Standards** sub-agent will read them.
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3.
+- The brief: "Read the standards docs. Then read the diff. Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Read the spec. Then read the diff. Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate so the user can see them independently.
+
+End with a one-line summary: total findings per axis, and the worst single issue (if any) flagged.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

package/skills/review-mp/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: review-mp
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+---
+
+# Review
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. Don't be opinionated; pass it through. If they didn't specify one, ask: "Review against what — a branch, a commit, or `main`?" Don't proceed until you have it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. A path the user passed as an argument.
+3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written. Common locations:
+
+- `CLAUDE.md`, `AGENTS.md`
+- `CONTRIBUTING.md`
+- `CONTEXT.md`, `CONTEXT-MAP.md`, per-context `CONTEXT.md` files
+- `docs/adr/` (architectural decisions are standards)
+- `.editorconfig`, `eslint.config.*`, `biome.json`, `prettier.config.*`, `tsconfig.json` (machine-enforced standards — note them but don't re-check what tooling already checks)
+- Any `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md`, or similar at the repo root or under `docs/`
+
+Collect the list of files. The **Standards** sub-agent will read them.
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3.
+- The brief: "Read the standards docs. Then read the diff. Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Read the spec. Then read the diff. Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate so the user can see them independently.
+
+End with a one-line summary: total findings per axis, and the worst single issue (if any) flagged.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

package/skills/scope-boundary/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: scope-boundary
+description: 'Use when the agent is mid-conversation, about to declare done, transition, or move on — especially after a long stretch of work. Forces the agent to name the original ask and check whether the work delivered still matches it, surface any drift explicitly, and get user sign-off before continuing with the drifted scope. Catches the failure mode where the agent expands into adjacent work or shifts to a different sub-task without telling the user.'
+user-invocable: true
+---
+
+# Scope Boundary
+
+## What this does
+
+Before declaring done, transitioning, or moving on, you name the original ask — what the user actually requested — and check whether the work you're about to ship still matches it. If you've drifted (added adjacent work, shifted to a different sub-task, expanded scope), you surface the drift explicitly and get sign-off before continuing.
+
+This skill exists because **scope drift is the most natural form of long-task failure.** The agent starts working on X, encounters an interesting Y, follows the thread, ends up delivering Y (or X + Y) when the user asked for X. None of the existing skills catch this: `surface-assumptions` is *before* work, `verify-done` is *at* completion (and only checks the work against the plan, not against the *original ask*).
+
+## Authority
+
+This skill is authoritative. The agent cannot silently expand or shift scope. Acknowledging the skill and then continuing with drift is the violation, not compliance.
+
+If you want to deviate from the original ask, the protocol is: surface the drift explicitly, explain why, get user sign-off. Not to silently expand.
+
+**Acknowledging the skill and then doing the drift anyway is the violation, not compliance.** Sentences like *"I understand scope-boundary, but Y was the natural next step"* are the same dismissal pattern as `no-wall`'s *"I understand the skill but I have no other way."* Surface; wait for sign-off; no sign-off → revert to the original ask.
+
+## When it applies
+
+Triggered by:
+- About to write "done", "complete", "moving on", "next phase", "wrapping this up", "shipping this", or close a goal
+- After a long stretch of work (more than 5–10 exchanges on one task) without re-checking alignment
+- About to start a new sub-task within a larger task
+- The user asks "are you still doing what I asked?" or "did you drift from what I asked?"
+- You feel the urge to say "I also did X while I was at it" or "I added Y because it was related"
+
+## The Protocol
+
+When triggered, run these steps **in order, in writing, in the conversation**.
+
+### 1. Name the original ask
+Quote or paraphrase the user's request. "The user asked for {X}." If you can't recall the original ask clearly, look it up — it's in the conversation, the work-log, or the plan. Don't drift from something you can't even name.
+
+### 2. Check the current work against it
+List what you've actually done (or are about to do). For each item, classify:
+- **In scope** — directly requested, or a clearly implied sub-task
+- **Adjacent** — related but not requested; you decided to do it
+- **Drift** — unrelated to the original ask; you shifted focus
+
+If everything is "in scope" → proceed. If any item is "adjacent" or "drift" → continue to step 3.
+
+### 3. Surface the drift
+For each adjacent or drift item, ask the user explicitly. The format:
+
+> "You asked for {X}. I did {X, Y, Z}. Y was related but not requested; Z was unrelated drift. Should I:
+> - Keep Y, drop Z?
+> - Keep both, get sign-off now?
+> - Drop both, revert to just X?"
+
+Don't ask "is this okay?" rhetorically. Ask the specific scope question.
+
+### 4. Get sign-off
+Wait for the user's response. If they confirm → proceed. If they correct → revert or adjust, re-run step 2.
+
+Implicit silence is not sign-off. Wait.
+
+### 5. Log (if armed)
+If `work-log` is armed, append a checkpoint: *"## {HH:MM KST} — Scope check: {state, in-scope, dropped Y, kept Z}"*. This makes the scope decision auditable.
+
+## Behavior in edge cases
+
+- **The user explicitly invited the expansion:** "while you're at it, also fix X" — that's sign-off for X. Note it in the log; proceed.
+- **The sub-task is genuinely implicit:** the user said "implement auth" and you had to add a session table; the session table is in-scope as a sub-task of "implement auth". The implicit-test is **strict**: "implicit" means the user used words that, taken literally, require X as a sub-step, OR X is in a written-down spec/plan/PRD the user references. A session table is implicit in "implement auth" because auth has sessions by definition. A `format_phone_number()` helper is NOT implicit in "implement auth" — that's adjacent, surface it. If unsure → surface.
+- **The drift is small (a one-line bonus fix):** if it's <5 lines and purely mechanical, log it and proceed without asking. If it has any logic or behavior implications, surface it.
+- **The user said "do whatever you think is right":** that's wide sign-off. Use judgment, but log what you did and why so the user can correct after the fact.
+- **You caught yourself mid-drift:** surface the drift retroactively. *"I was doing X, but I noticed Y and started working on it — should I continue, drop it, or split the work?"* Don't continue the drift while you ask.
+
+## Write-Time Self-Check
+
+Before sending any message that says "done", "complete", "moving on", "next phase", "wrapping this up", "shipping this", or closes a goal, scan it for these patterns:
+
+- "I also did X" / "while I was at it, I also..." / "I added Y because it was related" (silent scope expansion — surface Y before sending)
+- "I fixed the bug I noticed" (drift from the task to a different bug — surface it)
+- "I noticed X and decided to address it" (drift framed as helpful — surface it)
+- "Done — that included X, Y, Z" (delivered Y or Z without asking — check whether Y/Z were in scope)
+- "I went ahead and refactored X" (silent architectural change — surface it)
+
+If any pattern is present, the scope may have drifted. **Do not send.** Re-run the protocol — name the ask, classify the work, surface the drift — then send.
+
+## Override Protocol — what you may NOT do unilaterally
+
+You may not expand or shift scope based on agent judgment. Specifically:
+
+- You may not add "related" or "while I was at it" work without surfacing it first.
+- You may not follow a thread that surfaced during the task without asking whether the user wants it.
+- You may not deliver a different sub-task than what was requested without surfacing the swap.
+- You may not dismiss the skill ("I understand scope-boundary, but Y was the natural next step") and proceed. That's the violation, not the protocol.
+
+If you want to deviate, the protocol is: surface the drift, explain why, get sign-off. Without sign-off, revert to the original ask.
+
+## Red Flags
+
+| Thought | What it really means |
+|---------|----------------------|
+| "While I was at it, I also..." | Silent scope expansion — surface Y first |
+| "This was the natural next step" | I'm justifying drift with momentum |
+| "I noticed a related issue and fixed it" | Drift framed as helpfulness — surface it |
+| "Done — that included X, Y, Z" | I delivered Y or Z without asking; the user may not want them |
+| "I'll address that in a follow-up" | I noticed drift but won't fix it now — that's promise-tracking, not scope |
+| "I went ahead and refactored" | Silent architectural change — surface it |
+| Continuing the drifted work while "asking" | I'm not actually asking, I'm reporting after the fact |
+| "I understand scope-boundary, but..." | Dismissing the skill mid-piece (same as `no-wall` / `professional`) |
+
+## The deeper point
+
+Drift feels productive. The agent is doing work, the work is good, why interrupt to ask? Because the user is the only one who can decide whether Y was wanted. The agent's judgment that Y is "related" or "the natural next step" is a guess — and the same guess that produced the drift in the first place. The check is cheap (one sentence, one question); the cost of unwinding drift is hours.
+
+`surface-assumptions` governs hidden assumptions at the start. `scope-boundary` governs hidden expansions during the work. Same discipline at different moments: name what's unstated, surface it, get sign-off.
+
+## Related
+
+- **`surface-assumptions`** — runs *before* work; scope-boundary runs *during* work. surface-assumptions enumerates; scope-boundary detects drift.
+- **`verify-done`** — runs *at* completion; scope-boundary is a pre-completion check. verify-done checks the checklist; scope-boundary checks the original ask.
+- **`work-log`** — open promises and dropped scope are checkpoint entries; promise-tracking is the dedicated skill.
+- **`team-protocol`** — one loop per piece; scope-boundary keeps each piece scoped to the original ask.
+- **`no-wall`** / **`professional`** — same dismissal pattern; scope-boundary is one more place the "I understand but..." pattern bites.

package/skills/semble-search/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: semble-search
+description: Code search agent for exploring any codebase. Use for finding code by intent, locating implementations, understanding how something works, or discovering related code. Prefer over Bash/Read for any semantic or exploratory question.
+---
+
+Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep:
+
+```bash
+semble search "authentication flow" ./my-project --max-snippet-lines 10  # first 10 lines only, concise
+semble search "save_pretrained" ./my-project                          # full chunk content
+semble search "save model to disk" ./my-project --top-k 10           # more results
+```
+
+Results are cached automatically on first run and invalidated when files change.
+
+Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
+
+```bash
+semble search "deployment guide" ./my-project --content docs
+semble search "database host port" ./my-project --content config
+semble search "authentication" ./my-project --content all
+```
+
+Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result):
+
+```bash
+semble find-related src/auth.py 42 ./my-project
+```
+
+`path` defaults to the current directory when omitted; git URLs are accepted.
+
+If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place.
+
+### Workflow
+
+1. Start with `semble search` to find relevant chunks. The index is built and cached automatically.
+2. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything.
+3. Navigate directly to the returned file and line. Do not re-search or grep for the same content.
+4. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations.
+5. Use grep only when you need every occurrence of a literal string across the whole repo (e.g., all callers of a renamed function).

package/skills/sitrep/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: sitrep
+description: Use when the user asks "do you understand?", "what's going on?", "what's the situation?", "catch me up", "are you with me?", "give me the situation and next actions", or runs /sitrep — first grounds itself in real project state (latest worklogs, commits, handoffs, recently-touched docs), then produces a situation report (current state, goal, assumptions, open questions, next actions) and PAUSES for confirmation before doing anything.
+---
+
+# Sitrep (situation report)
+
+## What this does
+
+Stop. Re-read the conversation. **Then ground yourself in the real project state** — the latest worklogs, recent commits, the latest handoff, and recently-touched docs — not just what's in the conversation window. Confirm you actually understand what's going on, in your own words, not by echoing the user's phrasing back. Then surface your assumptions, your open questions, and the next actions you propose — and **wait**.
+
+This is a checkpoint, not an action. The whole point is to catch silent misunderstandings before they cost you. Do not produce the report and then immediately charge off and do things. Produce the report, then stop.
+
+The conversation window is one source of truth, but not the only one. Worklogs, commits, and handoffs often carry state the window has dropped (especially after compaction, across sessions, or when picking up cold). A sitrep built only on the conversation is a sitrep that may have already drifted from reality.
+
+## The two levels of understanding
+
+"I read it" is not the same as "I understand it."
+
+- **Shallow:** restating the user's words. "You want a function." Worthless.
+- **Deep:** stating the goal, the constraint, and the why in your own words. "You want a function that handles null inputs because the upstream source sometimes returns null and the current code crashes on it — and it needs to land before tomorrow's deploy."
+
+Produce the deep version. If you can only produce the shallow version, you don't understand it yet — say so out loud.
+
+## Grounding — consult before writing the report
+
+Before you write a single line of the report, consult the real project state. The conversation is one source; these are the others. **Read the *latest* of each — not everything.** This is a checkpoint, not an audit.
+
+All "today" / "latest" determinations use **KST (Asia/Seoul)** — prefix every `date` call with `TZ='Asia/Seoul'`. Never trust the system default. (This project operates in KST; see AGENTS.md.)
+
+### 1. Latest worklogs
+- **Find:** a `work-log/` directory under `docs/`, sometimes nested (e.g. `docs/{project}/active/work-log/`). In this project: `docs/korean-equity-scalper/active/work-log/YYYY-MM-DD/`.
+- **Read:** today's folder first (KST). If empty or missing, the most recent prior date. Read the newest 1–2 files. Files are `HHMM-topic.md` (new format); older ones may be `.html`.
+- **What you're looking for:** what was just worked on, what was found, what's blocked, what was decided — the agent's own running notes beat memory.
+
+### 2. Latest commits
+- **Run:** `git log --oneline -20` (recent momentum) and `git status` + `git diff --stat` (current WIP state).
+- **What you're looking for:** what just landed, what's uncommitted/in-flight, whether the tree is clean. If the user is mid-task, the uncommitted diff is often the most important signal of all.
+
+### 3. Latest handoff(s)
+- **Find:** `handoffs/` under docs, typically `docs/{project}/active/handoffs/YYYY-MM-DD/HANDOFF-*.md`. In this project: `docs/korean-equity-scalper/active/handoffs/YYYY-MM-DD/HANDOFF-*.md`.
+- **Read:** the most recent 1–2 handoff files.
+- **What you're looking for:** the explicit "here's where we are / here's what's next" from the last person (or agent) who stopped. Handoffs are designed to be read cold — trust them.
+
+### 4. Recently-touched docs
+- **Find:** recently-modified `.md` files under `docs/` — `find docs -name "*.md" -mtime -7` (last ~7 days) is a good starting lens. Also check `docs/adr/` (decisions), `docs/plans/` (active plans), and any `CONTEXT.md` at the repo root or under `docs/`.
+- **Read:** only what's recent AND relevant to the current conversation. Don't read all docs — read the few that intersect with what we're doing.
+- **What you're looking for:** decisions that constrain us (ADRs), plans that define "done," domain vocabulary that disambiguates terms.
+
+### Grounding rules
+- **Missing source = skip, don't fail.** No `work-log/` dir? Skip it. No handoffs? Skip it. Never error out because a source doesn't exist.
+- **Latest, not exhaustive.** You're calibrating, not writing a history. If a source has 200 files, read the 1–2 most recent that matter.
+- **Cite what you consulted.** The report opens with a one-line "Sources consulted" list (see report section 0) so the user can see what you grounded in — and tell you if you missed something.
+- **Flag conflicts.** If a worklog says X but the latest commit did Y, surface that. Conflicts between sources are exactly the kind of drift this checkpoint exists to catch.
+- **Don't pad with sources.** If the conversation alone is enough and the sources add nothing, say so: "Sources consulted: git log (no recent relevant commits); no worklogs/handoffs found." Brief is fine.
+
+## The report
+
+Output this structure, in this order:
+
+### 0. Sources consulted
+One line. What you grounded in. e.g. "Conversation + worklog `2026-06-20/0915-...md` + `git log -20` (last commit: `<sha> <subject>`) + handoff `2026-06-19/HANDOFF-*.md`." This makes your grounding visible and lets the user say "you missed X."
+
+### 1. Situation
+Current state, in your own words. What exists now, what's broken, what's working, what's in flight. Two or three sentences. If you can't state it crisply, you don't have it yet.
+
+### 2. Goal
+What we're driving toward. Not "the task" — the outcome. Why does this matter? What does success look like?
+
+### 3. Assumptions
+Explicit list. Things you're taking as given but haven't verified. The user can correct each one in a single line. This is where most silent misalignment lives — surface them, don't act on them silently.
+
+### 4. Open questions
+Things you don't know. Do not hide confusion. "I'm not sure whether X or Y" is a valid and valuable output. Listing unknowns is not weakness — it's the whole point of this checkpoint.
+
+### 5. Next actions
+Ordered, concrete, owner-tagged:
+- **"I will do X"** — agent-owned
+- **"You should do Y"** — user-owned
+- **"We need to decide Z before proceeding"** — blocking
+
+Vague actions like "improve testing" are banned. Specific only: "add a test for null-input in `parse_orders`."
+
+### 6. Awaiting your go-ahead
+Say it explicitly: "I'll wait for your confirmation before acting." Then wait.
+
+## Critical behaviors
+
+- **Re-read the whole conversation.** Not skim. Not the last few messages. The full context — especially if it's long or has been compacted.
+- **Ground in real project state.** Worklogs, commits, handoffs, recent docs — consult them before writing the report. The conversation window alone is not enough, especially after compaction or when picking up cold.
+- **Don't fake understanding.** If you don't get something, say so. "I don't fully understand X" is a better output than a confident wrong summary.
+- **State assumptions out loud.** Don't act on them silently. The user correcting one assumption now saves an hour of wrong work later.
+- **Don't charge off.** The report ends with a pause. The user confirming is what unlocks action.
+- **Don't pad.** If the situation is one sentence, write one sentence. Depth ≠ length. Depth = correctness and completeness of what matters.
+
+## When to use
+
+Triggered by:
+- "do you understand?"
+- "what's going on?"
+- "what's the situation?"
+- "catch me up"
+- "are you with me?"
+- "give me the situation and the next actions"
+- `/sitrep`
+
+Also appropriate to self-invoke when:
+- The conversation is long or has been compacted
+- Multiple topics have been juggled
+- You're starting fresh after a break
+- The user just gave you a wall of context
+- You're about to do something expensive or irreversible and want to verify alignment first
+
+## Failure modes this prevents
+
+- Charging off and doing the wrong thing because you skimmed
+- Faking "got it!" when you actually missed something
+- Agent and user carrying different mental models for 30 minutes before the divergence surfaces
+- Acting on an assumption the user would have corrected in one word if you'd said it out loud
+- Forgetting an earlier constraint or decision
+
+## Related
+
+- **`professional`** — don't fake understanding to seem fast; real professionals surface what they don't know.
+- **`no-wall`** — if "I don't understand" comes up, that's an unfinished search, not a wall. Re-read, ask, search.
+- **`next-step`** — similar output shape but narrower: answers "what's next?" only, not the full situation. Use `sitrep` for the full alignment checkpoint; use `next-step` when you just want the next move.

package/skills/structure-code/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: structure-code
+description: Use when multiple workflows duplicate the same operational logic, when deciding what belongs in actions vs shared services, or when refactoring repeated operational blocks across domain flows. Use when adding new features that share mechanics with existing ones.
+---
+
+# Service Layer Architecture
+
+## Overview
+
+**Two-layer separation:** Actions orchestrate domain rules (the "why/when"), while a service layer centralizes reusable operational mechanics (the "how").
+
+This prevents duplicated code, inconsistent behavior, and bugs fixed in one path but not others.
+
+## When to Use
+
+- Multiple callers need the same low-level operation (sandbox creation, email sending, payment processing)
+- You're copy-pasting operational logic between action files
+- A bug fix in one workflow doesn't propagate to others doing the same thing
+- Adding a new feature that shares mechanics with existing flows
+
+**Don't use when:** Logic is truly domain-specific and used by only one caller.
+
+## Core Pattern
+
+```
+Orchestration Layer (Actions)          Service Layer (Shared Mechanics)
+├── owns business rules                ├── owns reusable operations
+├── owns state transitions             ├── owns provider/SDK interactions
+├── owns auth/ownership checks         ├── owns command execution details
+├── owns failure classification        ├── owns health checks / readiness
+├── owns retries / user-facing errors  └── returns structured results
+└── calls service functions
+```
+
+**Rule of thumb:**
+- "What this product flow means" → keep in actions
+- "How to do this operation reliably" → move to service layer
+
+## Quick Reference
+
+| Design Principle | Do | Don't |
+|---|---|---|
+| API shape | Composable capability blocks | One giant "do everything" method |
+| Inputs/outputs | Explicit params, structured returns | Hidden global state, reaching into DB |
+| Migration | Extract one block, replace one caller, verify, then migrate rest | Refactor everything at once |
+| Domain logic | Keep auth, policy, error classification in actions | Let service mutate domain state directly |
+| Extraction trigger | Logic repeated across 2+ callers | Logic used once (over-abstraction) |
+
+## Designing Service Functions
+
+Design as **capability blocks**, not monoliths:
+
+```ts
+// Good: composable, each caller chooses what to use
+createManagedSandbox(...)
+prepareRepo(...)
+detectPackageManager(...)
+installDependencies(...)
+runBuildCommand(...)
+startSandboxRuntime(...)
+```
+
+Each function should:
+- Accept all required data as **explicit parameters**
+- Return **structured outputs** (e.g., `{ ready, previewUrl, proxyPort }`)
+- Never reach into database/state directly
+- Make failure explicit (structured results, not swallowed errors)
+
+This lets callers choose strict vs relaxed behavior per flow.
+
+## Migration Checklist
+
+When extracting shared logic:
+
+1. Write the flow in action code first (clear behavior)
+2. Mark repeated operational chunks across callers
+3. Extract **only** repeated, non-domain chunks to service
+4. Replace one caller → verify → replace remaining callers
+5. Keep domain policy in actions (auth, status transitions, error classification)
+6. Run verification: typecheck, lint, confirm all flows still work
+
+## Anti-Patterns
+
+| Anti-Pattern | Problem |
+|---|---|
+| **God service** | One huge function hides all control flow |
+| **Leaky service** | Service mutates database tables directly |
+| **Inconsistent API** | Each function uses different argument styles and error semantics |
+| **Over-abstraction** | Extracting logic used by only one caller |
+
+## Example: Email Service (Simple)
+
+```ts
+// emailService.ts — shared mechanics
+export async function sendWelcomeEmail(params: { to: string; name: string }) {
+  const html = `<h1>Welcome ${params.name}</h1>`;
+  await emailProvider.send(params.to, "Welcome", html);
+}
+
+// userSignup.ts — orchestration (owns WHEN to send)
+if (user.marketingOptIn) {
+  await sendWelcomeEmail({ to: user.email, name: user.name });
+}
+
+// adminInvite.ts — orchestration (different business rule, same mechanic)
+await sendWelcomeEmail({ to: invitee.email, name: invitee.name });
+```
+
+## Mental Model
+
+```
+New feature? → Write in action first → See repeated ops? → Extract to service
+                                      → No repetition?  → Keep in action
+```
+
+Your architecture in one sentence: **Actions orchestrate domain rules, while the service layer centralizes reusable operational mechanics with a composable, explicit-input API.**