create-yss-spec 2.1.10 → 2.1.11

package/template/.cursor/skills/alibaba-java-code-style/references/java-programming.md

@@ -0,0 +1,178 @@
+# Java Programming Rules
+
+Use this reference for Java implementation and review: naming, constants, formatting, OOP, collections, concurrency, control flow, comments, and general coding traps.
+
+## Naming
+
+Mandatory:
+
+- Do not start or end identifiers with `_` or `$`.
+- Do not mix pinyin and English; do not use Chinese identifiers. Widely recognized names such as `alibaba`, `taobao`, `youku`, and `hangzhou` are acceptable.
+- Use `UpperCamelCase` for classes, except suffix acronyms such as `DO`, `BO`, `DTO`, `VO`, `AO`, `PO`, and `UID`.
+- Use `lowerCamelCase` for methods, parameters, member variables, and local variables.
+- Use uppercase words separated by underscores for constants, with complete semantics such as `MAX_STOCK_COUNT`.
+- Name abstract classes with `Abstract` or `Base` prefixes, exception classes with `Exception` suffixes, and test classes as the tested class name plus `Test`.
+- Put brackets next to the type for arrays: `String[] args`, not `String args[]`.
+- Do not prefix POJO boolean properties with `is`; frameworks may mis-detect the property name. Map database `is_xxx` fields explicitly.
+- Package names must be lowercase, singular, dot-separated, and each segment should be one natural English word.
+- Avoid nonstandard abbreviations that hide meaning.
+
+Recommended/reference:
+
+- Prefer complete words for self-explanatory names.
+- If a module, interface, class, or method uses a design pattern, reflect the pattern in the name, such as `OrderFactory`, `LoginProxy`, or `ResourceObserver`.
+- Interface methods and fields should omit redundant `public` modifiers and include useful Javadoc.
+- For `Service` and `DAO`, expose interfaces and name implementations with `Impl`.
+- Capability interfaces may use adjective names such as `Translatable`.
+- Enum class names may end with `Enum`; enum members use uppercase underscores.
+- Layer method prefixes: `get` for one object, `list` for multiple objects, `count`, `save`/`insert`, `remove`/`delete`, and `update`.
+- Model suffixes: `xxxDO`, `xxxDTO`, `xxxVO`; do not name a class `xxxPOJO`.
+
+## Constants
+
+Mandatory:
+
+- Do not use magic values directly in code. Define named constants.
+- Use uppercase `L` for `long`/`Long` literals, never lowercase `l`.
+
+Recommended:
+
+- Do not keep every constant in one universal constant class. Group by function and scope.
+- Choose the smallest sensible reuse scope: cross-application library, application, submodule, package, or class-local `private static final`.
+- Use `enum` when values vary only within a fixed set, especially when values have attributes.
+
+## Formatting
+
+Mandatory:
+
+- For non-empty blocks, put `{` on the same line, newline after `{`, newline before `}`, and keep `} else {` on one line. Empty blocks may be `{}`.
+- Do not put spaces immediately inside parentheses. Put one space before `{`.
+- Put one space between reserved words and `(` for `if`, `for`, `while`, `switch`, and `do`.
+- Put one space around binary and ternary operators.
+- Use 4 spaces for indentation; do not use tab characters.
+- `//` comments must have exactly one space after the slashes.
+- Keep lines at or below 120 characters. When wrapping, indent the second line 4 spaces, keep operators and dots with the following line, wrap method arguments after commas, and do not break before `(`.
+- Add a space after commas in method definitions and calls.
+- Use UTF-8 and Unix line endings.
+
+Recommended:
+
+- Keep a single method under 80 lines, including signature, braces, code, comments, blank lines, and invisible characters.
+- Do not align variables by adding decorative spaces.
+- Insert one blank line between different logical or business sections; avoid multiple blank lines.
+
+## OOP And POJO
+
+Mandatory:
+
+- Access static members through the class name, not an object reference.
+- Add `@Override` to all overridden methods.
+- Use varargs only for same-type, same-meaning arguments; avoid `Object...`.
+- Do not change method signatures of externally used APIs or library APIs. Deprecate old interfaces with `@Deprecated` and document replacements.
+- Do not use deprecated classes or methods.
+- Call `equals` on constants or known non-null objects, or use `Objects.equals`.
+- Compare wrapper objects of the same type with `equals`, not `==`.
+- Use wrapper types for all POJO fields and RPC parameters/returns; prefer primitive types for local variables.
+- Do not set default values on DO/DTO/VO fields.
+- When adding fields to serializable classes, do not change `serialVersionUID` unless the change is intentionally incompatible.
+- Do not put business logic in constructors; use an init method or lifecycle hook.
+- POJO classes must implement `toString`; include `super.toString()` when extending another POJO.
+- Do not define both `isXxx()` and `getXxx()` for the same POJO property.
+
+Recommended:
+
+- Before indexing into `String.split` results, account for trailing separators.
+- Keep overloaded methods and multiple constructors adjacent.
+- Order methods as public/protected methods, private methods, then getters/setters, except overloaded groups.
+- Setter parameter names should match field names and use `this.field = field`.
+- Do not add business logic to getters or setters.
+- Use `StringBuilder.append` for string concatenation inside loops.
+- Use `final` for non-inheritable classes, non-overridable methods, immutable references, non-reassigned locals, or to avoid variable reuse confusion.
+- Be careful with `Object.clone`; default clone is shallow.
+- Minimize access scope: private constructors for non-instantiable classes, no public/default constructors in utility classes, private fields and methods unless broader access is truly required, and consider `final` for static fields.
+
+## Collections
+
+Mandatory:
+
+- If overriding `equals`, also override `hashCode`.
+- Objects stored in `Set` or used as `Map` keys must implement both `equals` and `hashCode`.
+- Do not cast `ArrayList.subList` results to `ArrayList`; it is a view.
+- Do not structurally modify the original list while iterating or changing a `subList`.
+- Convert collections to arrays with `toArray(new T[list.size()])`, not raw `toArray()`.
+- Do not call mutating methods on `Arrays.asList` results.
+- Respect PECS: `? extends T` is for producers/readers and cannot safely accept `add`; `? super T` is for consumers/writers and cannot safely provide typed `get`.
+- Do not remove/add elements inside foreach loops; use an `Iterator` and `iterator.remove()`. Lock the iterator if operations are concurrent.
+- Comparators must be symmetric, transitive, and handle equality consistently.
+
+Recommended:
+
+- Use diamond syntax or type inference where supported.
+- Specify initial collection capacity where size is known; for `HashMap`, use roughly `expectedSize / 0.75 + 1`, or default 16 when unknown.
+- Iterate maps with `entrySet` or `Map.forEach` when both key and value are needed.
+- Know map null support: `ConcurrentHashMap` and `Hashtable` reject null keys/values; `TreeMap` rejects null keys; `HashMap` allows null keys/values.
+- Use set uniqueness to de-duplicate rather than repeated `List.contains`.
+
+## Concurrency
+
+Mandatory:
+
+- Singleton acquisition and singleton methods must be thread-safe.
+- Name threads and thread pools meaningfully.
+- Provide thread resources through thread pools; do not create raw application threads casually.
+- Do not create production thread pools through `Executors`; use `ThreadPoolExecutor` so queue size, thread count, rejection policy, and resource limits are explicit.
+- Do not use static `SimpleDateFormat` without synchronization. Prefer `DateTimeFormatter`/`java.time`, `ThreadLocal`, or a safe date utility.
+- In high concurrency, minimize lock cost: prefer lock-free structures, small locked blocks, and object locks over class locks where suitable.
+- Keep a consistent lock acquisition order across resources to avoid deadlock.
+- For concurrent updates to one record, use application/cache locks or database optimistic locks with a `version` field; retry optimistic locks at least 3 times.
+- Prefer `ScheduledExecutorService` over `Timer` for multiple scheduled tasks, because one uncaught `TimerTask` exception stops other tasks.
+
+Recommended/reference:
+
+- With `CountDownLatch`, call `countDown` in `finally` or otherwise guarantee it runs even on exceptions.
+- Prefer `ThreadLocalRandom` over shared `Random`/`Math.random` in concurrent code.
+- If using double-checked locking on JDK 5+, declare the target field `volatile`.
+- `volatile` solves visibility for one writer/many readers but not compound writes; use `AtomicInteger`, `AtomicLong`, or `LongAdder` for counters.
+- Avoid unsynchronized high-concurrency `HashMap` resizing; use concurrent collections or locking.
+- Declare `ThreadLocal` fields as `static` when the per-thread value should be shared by all instances of the class.
+
+## Control Flow And Parameters
+
+Mandatory:
+
+- Every `switch` case must end with `break`, `return`, or a comment explaining fallthrough. Every `switch` must have a final `default`.
+- Always use braces for `if`, `else`, `for`, `while`, and `do`, even for one line.
+- In high-concurrency exit logic, avoid equality-only checks; prefer range checks that cannot be skipped by concurrent changes.
+- Do not exceed 3 levels of `if/else`; use guard clauses, strategy, or state pattern.
+
+Recommended:
+
+- Prefer guard clauses for exceptional branches.
+- Do not put complex expressions inside conditions. Assign them to well-named boolean variables first.
+- Move object creation, connection acquisition, unnecessary try/catch, and other expensive operations outside loops where possible.
+- Avoid negated logic when an equivalent positive condition is available.
+- Protect interface parameters, especially batch operations.
+- Validate parameters for low-frequency, expensive, high-stability, external, or sensitive-permission methods.
+- You may omit repeated validation for hot private or low-level methods only when callers have already validated and method docs state the expectation.
+
+## Comments And General Rules
+
+Mandatory:
+
+- Use Javadoc (`/** ... */`) for classes, fields, and methods. Do not use `//` as class or method API documentation.
+- Abstract methods and interface methods need Javadoc explaining purpose, parameters, returns, exceptions, and implementation notes.
+- Classes must include creator and creation date if the repository convention requires Alibaba manual compliance; otherwise follow local project header policy.
+- Place single-line comments above the code they explain. Align multi-line block comments with code.
+- Every enum value must have a comment explaining its purpose.
+- Precompile regular expressions; do not call `Pattern.compile` repeatedly inside method bodies.
+- Use `System.currentTimeMillis()` for current milliseconds, not `new Date().getTime()`. Use `System.nanoTime()` for elapsed time measurement; Java 8 may use `Instant`.
+
+Recommended/reference:
+
+- Prefer clear Chinese comments over awkward English; keep technical terms in English.
+- Update comments when changing parameters, returns, exceptions, or core logic.
+- Delete dead code. If temporarily commenting code, explain why above it.
+- Keep comments concise and focused on design intent, business meaning, and non-obvious logic.
+- Mark `TODO`/`FIXME` with owner, date, and expected handling time when possible.
+- Do not put complex logic in view templates.
+- Specify data structure capacity where possible.

package/template/.cursor/skills/alibaba-java-code-style/references/reliability-test-security.md

@@ -0,0 +1,89 @@
+# Reliability, Test, And Security Rules
+
+Use this reference for exception handling, logging, unit testing, and security-sensitive Java work.
+
+## Exception Handling
+
+Mandatory:
+
+- Do not catch avoidable runtime exceptions such as `NullPointerException` or `IndexOutOfBoundsException`; prevent them with prechecks.
+- Do not use exceptions for normal process or branch control.
+- Keep try blocks focused on unstable code. Catch specific exception types where behavior differs.
+- Never swallow caught exceptions. Handle them, translate them to user-understandable content at the outer business boundary, or rethrow.
+- In transactional code, if a caught exception requires rollback, explicitly trigger rollback according to the framework.
+- Always close resources and streams in `finally` or use try-with-resources. Handle close exceptions appropriately.
+- Do not `return` from a `finally` block.
+- Caught exception types must match thrown exceptions exactly or be an appropriate parent type.
+
+Recommended/reference:
+
+- A method may return `null`, but must document when that can happen. Callers remain responsible for NPE prevention.
+- Check common NPE sources: auto-unboxing wrapper return values, database nulls, null elements inside non-empty collections, remote calls, session reads, and chained calls such as `a.getB().getC()`.
+- Distinguish unchecked and checked exceptions. Avoid `new RuntimeException()`, `Exception`, or `Throwable` without business meaning; prefer domain-specific exceptions such as `DAOException` or `ServiceException`.
+- Public external HTTP/API interfaces should use error codes. Internal application code may throw exceptions. Cross-application RPC can prefer a result wrapper with success flag, code, and brief message.
+- Avoid duplicate code; extract common validation or behavior into methods/classes/components.
+
+## Logging
+
+Mandatory:
+
+- Use SLF4J facade APIs, not direct Log4j/Logback APIs:
+
+```java
+private static final Logger logger = LoggerFactory.getLogger(Abc.class);
+```
+
+- Keep application logs for at least 15 days when configuring retention.
+- Name extension logs as `appName_logType_logName.log`, where `logType` can be `stats`, `monitor`, `access`, etc.
+- For `trace`/`debug`/`info`, use placeholder logging or guard with `isXxxEnabled`; do not eagerly concatenate strings.
+- Avoid duplicate log printing, such as missing `additivity=false` in Log4j configuration.
+- Exception logs must include both scene/context information and stack trace. If not handled locally, throw upward.
+
+Recommended:
+
+- Production must not output debug logs. Emit info selectively.
+- Use `warn` for user input errors when no system fault occurred; reserve `error` for system logic errors, exceptions, or important failures.
+- Prefer English error messages where possible; use Chinese only when English would be unclear. Internationalized or overseas deployments require English logs/comments.
+- Before adding logs, ask whether someone will read them and what action they enable.
+
+## Unit Tests
+
+Mandatory:
+
+- Unit tests must follow AIR: Automatic, Independent, Repeatable.
+- Tests must be fully automated and non-interactive. Use assertions, not `System.out`, for verification.
+- Tests must not call each other or depend on execution order.
+- Tests must be repeatable and isolated from external environments such as network, remote services, or middleware. Inject local or mock dependencies.
+- Unit test granularity should be small: usually method-level, at most class-level.
+- Incremental code for core businesses, core applications, and core modules must pass unit tests.
+- Test code belongs under `src/test/java`, not production source directories.
+
+Recommended/reference:
+
+- Basic target: statement coverage at least 70%; core modules should reach 100% statement and branch coverage where feasible.
+- Use BCDE coverage thinking:
+  - Border: boundary values, loop boundaries, special values, special times, data ordering.
+  - Correct: valid inputs and expected outputs.
+  - Design: cases derived from design documents.
+  - Error: invalid data, exception flows, and disallowed business inputs.
+- Database tests should prepare data through programmatic insert/import, not manual pre-existing database edits.
+- Database tests should rollback automatically or mark generated data with a clear prefix.
+- Refactor untestable code instead of writing awkward tests to satisfy coverage.
+- Avoid business code that makes tests hard: heavy constructors, excessive globals/statics, too many external dependencies, and deep conditionals.
+
+## Security
+
+Mandatory:
+
+- User-owned pages or functions must perform authorization checks, including horizontal permission checks.
+- Sensitive user data must be masked before display, such as mobile numbers with hidden middle digits.
+- SQL parameters from users must use parameter binding or metadata-limited fields. Do not concatenate SQL strings.
+- Every user request parameter must be validated. Consider memory overflow, malicious `order by`, open redirect, SQL injection, deserialization injection, and ReDoS risks.
+- Do not output user data to HTML without proper filtering or escaping.
+- Forms and AJAX submissions must enforce CSRF protection.
+- Platform resources such as SMS, email, phone calls, orders, and payments must implement replay prevention, rate limits, fatigue control, or captcha as appropriate.
+
+Recommended:
+
+- User-generated content such as posts, comments, and instant messages should have anti-abuse, rate-limit, and prohibited-content controls.
+- Treat auth, payment, encryption, raw SQL, and database migration work as high-risk. If repository instructions mark them human-review-only, add `TODO-HUMAN-REVIEW` and do not present drafts as production-ready.

package/template/.cursor/skills/ask-matt/PHASE-BOUNDARIES.md

@@ -0,0 +1,55 @@
+# Phase boundaries
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. The definition is fuzzy on purpose: a phase ends when you think *"ok, we're done with that"*.
+
+The **phase boundary** is the gap between two phases, and it is the only place this decision belongs. Mid-phase there is no decision to make — continue, or split the work that's left into subagents. Compacting mid-phase makes the agent lose the thread.
+
+## The five options
+
+| Option       | What it does                                                    |
+| ------------ | --------------------------------------------------------------- |
+| **Continue** | Stay in the session. No context switch at all.                    |
+| **`/clear`** | Empty the context window and start from nothing.                  |
+| **`/handoff`** | Write a portable markdown file and seed a session anywhere with it. |
+| **Subagent** | Send the task to its own context window and get a report back.     |
+| **`/compact`** | Compress this context and seed a fresh session with the summary.  |
+
+## The tree
+
+Work top to bottom at the boundary. The first **yes** wins.
+
+**1. Can you continue in this session?** Two things make the answer yes: the next phase needs this phase as a **primary source**, or you have enough [smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone) left (~150k tokens) for the next phase to fit. Grilling → implementation is the standard yes: the implementation wants the reasoning verbatim, not a summary of it. Continue costs nothing and loses nothing, so rule it out before anything else.
+
+**2. Is the context irrelevant to what comes next?** Is everything in this session — the exploration, the decisions, the dead ends — disposable? If so, **`/clear`**. It is the cheapest move on the board: it takes no time and hands back the whole window. `/clear` also isn't terminal — the old session stays resumable.
+
+The cost of getting this wrong is one-way. Clear a *relevant* context and you lose the **why** behind what you built, and no amount of reading the diff back gets it returned.
+
+**3. Do you need to hand off?** `/handoff` is narrow. You need it only when you are:
+
+- swapping to a **new harness** (Claude → Codex),
+- moving to a **new directory** or repo,
+- sending the work to a **colleague**,
+- or forking a side task you found **mid-phase** without derailing what you're doing.
+
+That list is the whole clause. What `/handoff` buys is **portability** — a file that travels. If nothing is travelling, you don't need it.
+
+**4. Can the task be done AFK?** Is it scoped tightly enough to run with you away from the keyboard, no steering? Then send it to a **subagent** and leave this session untouched. Automated review is the standard case: the agent reads the diff and reports, and you aren't needed while it does.
+
+**5. Otherwise, `/compact`.** Relevant context, same harness, same directory, and you need to stay in the loop — this is where the tree lands, and it lands here often. Pass it an instruction (`/compact we're going to QA this area`) so the summary keeps what the next phase needs.
+
+`/compact` is the **default, not the first reach**. It sits at the bottom because the four questions above it are all cheaper or more precise. The failure mode when people start here is a fresh session that is confidently wrong about a decision the summary flattened.
+
+## Primary and secondary sources
+
+Every move except **Continue** turns a **primary source** into a **secondary source** — the session as it happened, replaced by a summary of it. The trade is always the same shape:
+
+| Source                            | Information | Noise | Room to move |
+| --------------------------------- | ----------- | ----- | ------------ |
+| Primary (Continue)                | Full        | Lots  | Little       |
+| Secondary (`/compact`, `/handoff`) | Lossy       | Less  | Lots         |
+
+This is why question 1 comes first. You only pay the lossiness when staying costs more than it saves.
+
+## These are judgement calls
+
+The questions are not objective — each has taste in it, and the same boundary can go two ways on two days. The value is in asking them **in order**, at the boundary rather than in the middle of the work.

package/template/.cursor/skills/ask-matt/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ask-matt
+description: Ask which skill or flow fits your situation. A router over the skills in this repo.
+disable-model-invocation: true
+---
+
+# Ask Matt
+
+You don't remember every skill, so ask.
+
+## YSS default (read this first)
+
+In this template, **`yss-product-lifecycle` is the default orchestrator**. Native work-units own Spec, tickets, implementation authorization, and gates.
+
+This skill is a **Matt compatibility map**. Use `/grill-with-docs`, `/to-spec`, `/to-tickets`, and `/implement` only when the user **explicitly** names them. Do not treat the idea→ship list below as the YSS default. `/implement` does not grant git commit/push. Spec drafts from `/to-spec` stay `ready-for-human` until a human approves the Spec baseline.
+
+A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
+
+## Matt compatibility flow: idea → ship
+
+The route most work travels. You have an idea and want it built.
+
+1. **`/grill-with-docs`** — sharpen the idea by interview. Start here whenever you are **working in a working directory**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No working directory? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail, which makes it the better of the two whenever a repo is there to leave it in.)
+2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (a prototype lives in its own directory, which is exactly what `/handoff` is for — see Phase boundaries):
+   - **`/handoff`** out, then open a fresh session against that file,
+   - **`/prototype`** to answer the question with throwaway code,
+   - **`/handoff`** back what you learned, and reference it from the original idea thread.
+3. **Branch — is this a multi-session build?**
+   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `docs/.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **`/clear`ing context between each one**. Each ticket is self-contained, so the last one's context is disposable.
+   - **No** → **`/implement`** right here, in the same context window.
+
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`** (Standards + Spec, plus UI fidelity when UI is in scope). Do not commit or push from `/implement`. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+
+### Context hygiene
+
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
+
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~150k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/compact` at the nearest phase boundary and carry on (see Phase boundaries).
+
+## On-ramps
+
+A starting situation that generates work, then merges onto the main flow.
+
+- **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
+
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**.
+
+- **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
+
+- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a **shared map** of **decision tickets** on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't — and it's slower and denser, so save it for exactly that, never a well-scoped feature.
+
+  When the map clears, **it hands off, it doesn't build**: merge onto the main flow at **`/to-spec`**, which collapses the map's linked decisions into a buildable plan, then `/to-tickets` and `/implement` as usual. Looping the map straight into `/implement` skips that collapse and throws the linked detail away — go straight to `/implement` only when the effort turned out genuinely small.
+
+## Codebase health
+
+Not feature work — upkeep.
+
+- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on.
+
+## Vocabulary underneath
+
+Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
+
+- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
+- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
+
+## Phase boundaries
+
+A **phase** is a chunk of work inside a session — the grilling, the implementation, the QA. At the **boundary** between two of them you have five options, and picking between them is the fuzziest decision in this whole map:
+
+- **Continue** — stay put. Costs nothing, loses nothing.
+- **`/clear`** — empty the window, when nothing here matters to what's next.
+- **`/handoff`** — write a portable markdown file. Narrow: only for a **new harness**, a **new directory**, a **colleague**, or forking a side task **mid-phase**. What it buys is portability.
+- **Subagent** — send a tightly-scoped task to its own window and get a report back.
+- **`/compact`** — compress this context and seed a fresh session with it. The **default**, at the bottom of the tree rather than the first reach.
+
+Read [PHASE-BOUNDARIES.md](PHASE-BOUNDARIES.md) for the ordered tree — the five questions, the reasoning behind each branch, and why the primary-source cost makes **Continue** the one to rule out first. Make the decision **at** a boundary; mid-phase, continue or split the rest into subagents.
+
+## Standalone
+
+Off the main flow entirely.
+
+- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but **stateless**: it saves nothing locally and builds no `CONTEXT.md`. Reach for it when you are **not working in a working directory** — sharpening a plan, a design, a piece of writing, anything with no repo under it. If you are in a working directory, use `/grill-with-docs` instead: it runs the same interview and leaves a paper trail, so it is strictly the better one.
+- **`/grilling`** — the interview primitive itself: rounds, the frontier, facts are the agent's job and decisions are yours. `/grill-me` and `/grill-with-docs` are the two named ways in, and `/triage`, `/wayfinder` and `/improve-codebase-architecture` all run it internally. Reach for it directly only when you want the interview with no wrapper around it.
+- **`/resolving-merge-conflicts`** — work an in-progress merge or rebase conflict hunk by hunk, resolving by **intent** traced to each side's primary source rather than by picking lines, then finish the operation. It never runs `--abort`. Standalone and off every flow: reach for it when you are already mid-conflict.
+- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway is a constraint on how the code is written, not a promise to destroy it: the answer folds into the real code, and the prototype itself is kept as a **primary source** on a `prototype/<name>` branch out of main, pointed at from the implementation issue. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
+- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
+- **`/to-questionnaire`** — when the thing blocking you isn't in your head or the codebase but in **someone else's**, this writes them a questionnaire to fill in. It's the inverse of `/grill-me`: instead of interviewing you about the subject, it interviews you about the **send** — who it's going to, what you need back — and aims the questions at the gap. What comes back is material for `/grill-with-docs` or `/to-spec`.
+- **`/wait-what`** — the corrective for a message that didn't land. Use it mid-conversation, inside any other skill, and the agent re-pitches what it just said with the context you were missing, in plain English, using the `CONTEXT.md` vocabulary. It works after the fact; `/grill-with-docs` is the upfront cure, because a shared language agreed early is what stops the jargon arriving at all.
+- **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
+- **`/writing-for-agents`** — reference for writing documents agents consume: skills, AGENTS.md, pointed-at docs.
+
+## Precondition
+
+**`/setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.

package/template/.cursor/skills/ask-matt/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Ask Matt"
+  short_description: "Find the right skill or workflow"
+policy:
+  allow_implicit_invocation: false

package/template/.cursor/skills/code-review/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: code-review
+description: Use when the user wants to review a branch, PR, committed candidate, uncommitted work-in-progress changes, or changes since a fixed point.
+---
+
+Review of a pinned candidate against a fixed point on two core axes, plus UI fidelity when UI is in scope:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / spec?
+- **UI fidelity** (only when the change has UI impact) — does the candidate match the confirmed prototype and `yss-design-system` / `yss-ui`? Type-check or claiming "already aligned" is not a pass. Invoke those skills' verification notes; do not collapse this axis into Standards or Spec.
+
+Standards and Spec run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. When UI is in scope, add a separate UI fidelity pass after those two reports (do not merge it into either axis).
+
+If `docs/agents/issue-tracker.md` is missing, tell the user to run `/setup-matt-pocock-skills`; do not invoke another user-invoked skill yourself.
+
+## Process
+
+### 1. Pin the fixed point and candidate
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Choose one candidate mode from the request or an upstream review contract:
+
+- **Committed candidate** — review committed branch/PR state. Capture `git diff <fixed-point>...HEAD` and `git log <fixed-point>..HEAD --oneline`.
+- **Worktree candidate** — review work in progress without requiring a commit. Resolve `<merge-base>` with `git merge-base <fixed-point> HEAD`, then capture:
+  - `git diff --no-ext-diff --binary --full-index <merge-base>` for committed, staged and unstaged tracked content as it exists in the working tree;
+  - `git ls-files -z --others --exclude-standard` for NUL-delimited raw untracked paths;
+  - each untracked file's content, using `git diff --no-index --no-ext-diff --binary --full-index -- /dev/null <path>` when a diff representation is useful. Exit code `1` from this command means a difference was found, not that review failed;
+  - `git log <fixed-point>..HEAD --oneline` for the committed portion of the candidate.
+
+Record one **candidate manifest** before spawning reviewers:
+
+```yaml
+review_mode: committed # or worktree
+review_base_ref: <fixed-point>
+merge_base: <resolved-sha>
+implementation_candidate_ref: HEAD # or working-tree
+candidate_snapshot_ref: <immutable-commit-or-captured-snapshot>
+candidate_digest: <sha256-or-immutable-tree-id>
+tracked_diff_command: <command>
+untracked_inventory_command: <command-or-null>
+untracked_files: []
+commit_list_command: <command>
+```
+
+For a Committed candidate, resolve `HEAD` to an immutable commit and tree before review. Its manifest must include `merge_base`, `tracked_diff_command` and `commit_list_command`. For a Worktree candidate, the manifest must additionally include `untracked_inventory_command`, `untracked_diff_command` and the exact `untracked_files` inventory.
+
+For a Worktree candidate, capture the tracked binary diff and every untracked file's bytes once into an immutable snapshot, compute `candidate_digest`, and make that **captured candidate** available to both reviewers. The following is normative, not illustrative: use the `yss-worktree-candidate-v1` byte stream. Start with ASCII `YSS-WORKTREE-CANDIDATE-V1` followed by one NUL byte. Append one tracked record: byte `0x54`, unsigned 64-bit big-endian binary-diff byte length, then the exact stdout bytes from `git diff --no-ext-diff --binary --full-index <merge-base>`. Then append one untracked record for each NUL-delimited raw path from `git ls-files -z --others --exclude-standard`, sorted bytewise by the raw path: byte `0x55`, unsigned 64-bit big-endian path length, raw path bytes, unsigned 32-bit big-endian `lstat` mode, entry-kind byte (`0x52` regular or `0x4c` symlink), unsigned 64-bit big-endian content length, then raw regular-file bytes or raw symlink-target bytes. Other entry kinds block capture. This is the sole length-prefixed framing and bytewise path order for the digest. SHA-256 is calculated over exactly this stream. The immutable snapshot stores `candidate-manifest.yaml`, `tracked.diff` and the `untracked/` bytes under the digest identity; both reviewers must consume those captured bytes and must not independently reread a live worktree.
+
+Before going further, confirm the fixed point and merge-base resolve. A committed candidate must have a non-empty committed diff. A Worktree candidate is non-empty when either its tracked diff or untracked inventory is non-empty. A bad ref, missing candidate part or empty candidate should fail here — not inside two parallel sub-agents. Do not silently downgrade Worktree review to `HEAD`-only review.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. A spec/Ticket/contract reference supplied by the user or an upstream lifecycle review input.
+2. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+3. A spec file under `docs/`, `specs/`, or `docs/.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, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+**Standards sub-agent prompt** — include:
+
+- The full candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list. For Worktree candidates, explicitly include every untracked file.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The same candidate manifest, captured candidate, `candidate_digest`, diff/inventory commands and commit list.
+- The path or fetched contents of the spec.
+- The brief: "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 reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. If UI is in scope, add `## UI fidelity` from the separate pass. Do **not** merge or rerank findings — the axes are deliberately separate (see _Why separate axes_).
+
+For Worktree mode, recapture the candidate digest after both reports return. If it differs from `candidate_digest`, mark both reports as reviewing a **stale candidate** and return `blocked`; the caller may start a new review against a new capture, but this invocation must not aggregate findings from different bytes. Recheck the same digest again at the completion/checkpoint boundary.
+
+State the reviewed `review_mode`, fixed point, candidate digest and coverage before the two reports. End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why separate 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.**
+- Code that implements the spec but diverges from the confirmed prototype or design system → **Spec pass, UI fidelity fail.**
+
+Reporting them separately stops one axis from masking the other.

package/template/.cursor/skills/code-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Code Review"
+  short_description: "Review a diff on standards and spec"

package/template/.cursor/skills/codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.