KunoLu/sbtd-plugins

# Book DDD Distilled Modeling

Use this Skill to sharpen domain language before turning a business request into PRD, issues, design, or code.

It is derived from the `mini` rule style of `agent-rules-books` and should run after project evidence is read. It complements `grill-with-docs`, `to-spec`, and task planning.

## Mandatory Post-grill Review

Every fully completed `grill-with-docs` session MUST be followed immediately by this Skill, whether the Agent initiated that session or the user invoked it explicitly. The `domain-modeling` activity embedded in `grill-with-docs` is the active interview-time modeling pass; it does not satisfy or replace this independent second-pass review.

Re-read the completed clarification result and the supporting project facts. Look for boundary errors, hidden term collisions, unsupported invariants, misplaced responsibilities, and unresolved context ownership rather than merely restating the interview.

The review is a gate before requirement confirmation, PRD, design, task creation, or implementation:

# Book DDIA Data Design

Use this Skill when a change can fail because of data semantics, distributed behavior, or operational reality rather than ordinary code structure.

It is derived from the `mini` rule style of `agent-rules-books` and should complement project architecture, task design, source/LSP/contract impact analysis, tests, and production validation.

## Strict Development Gate

In a strict task, run this Skill before design artifacts become stable or implementation begins when the task changes any of the following:

- Persisted or shared data, databases, schemas, or migrations.
- shared, persistent, cross-request, or cross-process caches; queues, events, streams, jobs, ETL, or analytics pipelines.
- Cross-service data flow or API ownership.
- Data ownership, source of truth, transaction boundaries, or read / write paths.

# Book Legacy Change Safety

Use this Skill when the main risk is not the requested change itself, but the uncertainty around existing behavior.

It is derived from the `mini` rule style of `agent-rules-books` and is intended to complement `diagnosing-bugs`, `tdd`, source/LSP/contract impact analysis, and project validation.

## Strict Development Gate

In a strict task, run this Skill before the first behavior-changing edit when either condition is true:

- The task fixes a bug in existing observable behavior.
- Existing target code has weak / missing tests, unclear or undocumented behavior, hidden dependencies, or high regression risk.

Emit a separate visible review:

# Book Refactoring Pass

Use this Skill as a focused refactoring check before or during implementation.

It is derived from the `mini` rule style of `agent-rules-books`. It is a strict development gate for existing-production-code edits and an on-demand engineering lens in other structural-risk scenarios; it does not replace project rules, tests, task artifacts, source/LSP/contract impact analysis, or code review.

## Strict Development Gate

Whenever a strict task will modify existing production code, run this Skill before the first implementation edit to existing production code, even when the expected result is that no refactoring is needed.

Emit a separate visible review:

```text
Refactoring Review

# Book Release Readiness

Use this Skill as a production-readiness pass before considering a service or integration change complete.

It is derived from the `mini` rule style of `agent-rules-books` and complements project validation, Playwright, Maestro, Chrome DevTools diagnostics, task check, and human release review.

## Strict Development Gate

In a strict task, run this Skill after all applicable testing-tool gates and project validation, and before the task is declared complete or the final release decision when the task changes any production-path:

- Service, API, auth, billing, or notification behavior.
- Background job, queue, scheduler, or data pipeline.
- External integration.
- Deployment, rollout, migration, or runtime operational behavior.

# Domain Modeling

Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)

## File structure

Most repos have a single context:

```
/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md

Call the Skill tool with "grilling".

Call the Skill tool twice, for "grilling" and "domain-modeling".

Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.

Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.

Format a round like so:

```
❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>

➡<U+FE0F> <your recommended answer>

---

❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>

# SBTD Task

Use host-native tools to carry out the user's task. This Skill supplies task rules, not a scheduler, daemon, hook system, or new CLI. Project rules and explicit delivery requirements remain binding. Do not invent commands or claim unavailable helpers ran.

## Route before work

1. Identify the task, authorized project root, branch, and read-only constraints using only necessary reads. An existing task's branch mismatch pauses business and metadata writes: offer its correct worktree, explicitly authorized rebinding, or read-only inspection. "Continue" or choosing a mode does not authorize rebinding.
2. Mode precedence: the user's current explicit choice; otherwise the same task's confirmed/effective record; otherwise `default` for a genuinely new task. A missing, invalid, or ambiguous old record is not a new task: ask which task or mode to use. Do not choose by mtime. A valid task outranks an old handoff.
3. Assess fit without implementing first. If another mode is preferable, explain the current mode, recommendation and reason, and the option to keep the current mode; pause substantive work for the user's decision. Upgrades and downgrades use the same confirmation rule. Never infer a mode from output compression, installed tools, task complexity, or an existing task directory.
4. Honor a refusal, preserve its reason where writing is allowed, and continue in the selected mode. Do not repeatedly recommend the same change without new substantive risk. Same-task continuation preserves its choice; a new unrelated task does not inherit it.
5. For a writable project task with no branch conflict, save the confirmed mode and source promptly using [task state](references/state.md). Do not wait for handoff. If saving fails, keep the current-session choice, report that it was not persisted, and do not promise reliable recovery. `default/lite` may continue unrelated safe work; required `strict` artifacts remain incomplete.
6. Then assess clarification. Read facts the project can answer. If requirements are clear, explain why full `grill-with-docs` was not needed and proceed. For consequential domain ambiguity, explain the unresolved point and ask about grill. Declining a method does not authorize guessing required answers.
7. After every completed full `grill-with-docs` session, invoke `book-ddd-distilled-modeling` and present its separate visible `DDD Boundary Review` in every mode. Follow that Skill's result and correction loop: advance requirement confirmation/design only at `confirmed`; `needs-clarification` returns to clarification and `blocked` stops the dependent step. An unavailable/unreadable reviewer or missing required evidence is blocked for default, lite and strict until the gate can run and pass. Interview-time modeling and informal substitute checks do not satisfy this post-grill gate. This gate has no default/lite substitute; it does not disable fallback for unrelated optional tools.

This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.

The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.

## Process

1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.

2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.

Check with the user that these seams match their expectations.

3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.

# To Tickets

Break a plan, spec, or conversation into a set of **tickets**: tracer-bullet vertical slices, each declaring the tickets that **block** it.

The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.

## Process

### 1. Gather context

Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.

### 2. Explore the codebase (optional)

fixture-skill

# Codebase Design

Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.

## Glossary

Use these terms exactly: don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.

**Module**: anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.

**Interface**: everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow, they refer only to the type-level surface).

**Implementation**: what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.

# Diagnosing Bugs

A discipline for hard bugs. Skip phases only when explicitly justified.

When exploring the codebase, read `CONTEXT.md` (if it exists) to get a clear mental model of the relevant modules, and check ADRs in the area you're touching.

## Redact

This skill has you show commands, outputs and captured artifacts. **Redact every secret first**: write `<REDACTED>` in its place. Build loops against env vars, so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.

If the redacted output is not enough to diagnose the bug, say so and ask the user.

## Phase 1: Build a feedback loop

# Domain Modeling

Actively build and sharpen the project's domain model as you design. This is the *active* discipline: challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallise. (Merely *reading* `CONTEXT.md` for vocabulary is not this skill: that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)

## File structure

Most repos have a single context:

```
/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md

Call the Skill tool with "grilling".

Call the Skill tool twice, for "grilling" and "domain-modeling".

Interview the user relentlessly until you reach a shared understanding. Map this as a **design tree**: every decision branches into the decisions that hang off it.

Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled: the questions you can ask _now_ without guessing at answers you haven't heard yet. Ask the whole frontier in one round: number each question and give your recommended answer. Then wait for the user's answers before the next round.

Format a round like so:

```
❓ **Q1** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>

➡<U+FE0F> <your recommended answer>

---

❓ **Q2** - **<question title>**: <question body, might be multiple paragraphs, including multiple choices>

Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.

Include a "suggested skills" section in the document, naming which skills the next agent should call the Skill tool for.

Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.

Redact any sensitive information, such as API keys, passwords, or personally identifiable information.

If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

# Ponytail

You are a lazy senior developer. Lazy means efficient, not careless. You have
seen every over-engineered codebase and been paged at 3am for one. The best
code is the code never written.

## Persistence

ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if
unsure. Off only: "stop ponytail" / "normal mode". Default: **full**.
Switch: `/ponytail lite|full|ultra`.

## The ladder

ponytail-review, repo-wide. Scan the whole tree instead of a diff. Rank
findings biggest cut first.

## Tags

Same as ponytail-review:

- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
- `stdlib:` hand-rolled thing the standard library ships. Name the function.
- `native:` dependency or code doing what the platform already does. Name the feature.
- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
- `shrink:` same logic, fewer lines. Show the shorter form.

## Hunt

Every deliberate ponytail shortcut is marked with a `ponytail:` comment naming
its ceiling and upgrade path. This collects them into one ledger so a deferral
can't quietly become permanent.

## Scan

Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
output:

`grep -rnE '(#|//) ?ponytail:' .`  (add other comment prefixes if your stack uses them)

Each hit is one ledger row. The comment prefix keeps prose that merely mentions
the convention out of the ledger.

Review diffs for unnecessary complexity. One line per finding: location, what
to cut, what replaces it. The diff's best outcome is getting shorter.

## Format

`L<line>: <tag> <what>. <replacement>.`, or `<file>:L<line>: ...` for
multi-file diffs.

Tags:

- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
- `stdlib:` hand-rolled thing the standard library ships. Name the function.
- `native:` dependency or code doing what the platform already does. Name the feature.
- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.

# Test-Driven Development

TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle: consult them before and during the loop, not after.

When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.

## What a good test is

Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification: "user can checkout with valid cart" tells you exactly what capability exists, and it survives refactors because it doesn't care about internal structure.

See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.

## Seams: where tests go

This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.

The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.

## Process

1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.

2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.

Check with the user that these seams match their expectations.

3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.

# To Tickets

Break a plan, spec, or conversation into a set of **tickets**: tracer-bullet vertical slices, each declaring the tickets that **block** it.

The issue tracker and triage label vocabulary should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`.

## Process

### 1. Gather context

Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.

### 2. Explore the codebase (optional)

# UI/UX Pro Max - Design Intelligence

Searchable local UI/UX guidance: 79 searchable styles (50 active), 192 product palettes and exact reasoning profiles, 74 font pairings, 119 UX guidelines, 105 curated icons, 17 GSAP presets, 25 chart types, and 22 technology stacks.

## When to Apply

Use this Skill when the task involves **UI structure, visual design decisions, interaction patterns, or user experience quality control**: designing new pages, creating/refactoring UI components, choosing color/typography/spacing/layout systems, reviewing UI for UX/accessibility/consistency, implementing navigation/animation/responsive behavior, or improving perceived quality and usability.

Skip it for pure backend logic, API/database design, non-visual performance work, infrastructure/DevOps, or non-visual scripts — unless the task changes how something **looks, feels, moves, or is interacted with**.

## Rule Categories by Priority

*Follow priority 1→10 to decide which category to focus on first; use `--domain <Domain>` to query full details. The full rule text for every category lives in `references/quick-reference.md` — read it on demand rather than loading it every time.*

Reference for writing any document an agent consumes: a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, since the agent takes the same _process_ every run rather than producing the same output.

When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, and router skills.

## Context pointers

A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.

A pointer does two jobs: state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:

- **Front-load the leading word**: the pointer is where it does its triggering work.
- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only genuinely distinct branches.
- **Cut identity the body already carries.**

# Book DDD Distilled Modeling

Use this Skill to sharpen domain language before turning a business request into PRD, issues, design, or code.

It is derived from the `mini` rule style of `agent-rules-books` and should run after project evidence is read. It complements `grill-with-docs`, `to-spec`, and task planning.

## Mandatory Post-grill Review

Every fully completed `grill-with-docs` session MUST be followed immediately by this Skill, whether the Agent initiated that session or the user invoked it explicitly. The `domain-modeling` activity embedded in `grill-with-docs` is the active interview-time modeling pass; it does not satisfy or replace this independent second-pass review.

Re-read the completed clarification result and the supporting project facts. Look for boundary errors, hidden term collisions, unsupported invariants, misplaced responsibilities, and unresolved context ownership rather than merely restating the interview.

The review is a gate before requirement confirmation, PRD, design, task creation, or implementation:

# Book DDIA Data Design

Use this Skill when a change can fail because of data semantics, distributed behavior, or operational reality rather than ordinary code structure.

It is derived from the `mini` rule style of `agent-rules-books` and should complement project architecture, task design, source/LSP/contract impact analysis, tests, and production validation.

## Strict Development Gate

In a strict task, run this Skill before design artifacts become stable or implementation begins when the task changes any of the following:

- Persisted or shared data, databases, schemas, or migrations.
- shared, persistent, cross-request, or cross-process caches; queues, events, streams, jobs, ETL, or analytics pipelines.
- Cross-service data flow or API ownership.
- Data ownership, source of truth, transaction boundaries, or read / write paths.

# Book Legacy Change Safety

Use this Skill when the main risk is not the requested change itself, but the uncertainty around existing behavior.

It is derived from the `mini` rule style of `agent-rules-books` and is intended to complement `diagnosing-bugs`, `tdd`, source/LSP/contract impact analysis, and project validation.

## Strict Development Gate

In a strict task, run this Skill before the first behavior-changing edit when either condition is true:

- The task fixes a bug in existing observable behavior.
- Existing target code has weak / missing tests, unclear or undocumented behavior, hidden dependencies, or high regression risk.

Emit a separate visible review:

# Book Refactoring Pass

Use this Skill as a focused refactoring check before or during implementation.

It is derived from the `mini` rule style of `agent-rules-books`. It is a strict development gate for existing-production-code edits and an on-demand engineering lens in other structural-risk scenarios; it does not replace project rules, tests, task artifacts, source/LSP/contract impact analysis, or code review.

## Strict Development Gate

Whenever a strict task will modify existing production code, run this Skill before the first implementation edit to existing production code, even when the expected result is that no refactoring is needed.

Emit a separate visible review:

```text
Refactoring Review

# Book Release Readiness

Use this Skill as a production-readiness pass before considering a service or integration change complete.

It is derived from the `mini` rule style of `agent-rules-books` and complements project validation, Playwright, Maestro, Chrome DevTools diagnostics, task check, and human release review.

## Strict Development Gate

In a strict task, run this Skill after all applicable testing-tool gates and project validation, and before the task is declared complete or the final release decision when the task changes any production-path:

- Service, API, auth, billing, or notification behavior.
- Background job, queue, scheduler, or data pipeline.
- External integration.
- Deployment, rollout, migration, or runtime operational behavior.

# Gherkin BDD

Use this Skill for user-visible behavior. BDD is a default hard rule: new or changed behavior that a user, administrator, API client, CLI user, integration system, exported file consumer, notification recipient, or permission/error-state observer can see must have a persistent BDD scenario before implementation is completed.

BDD does not replace PRD, DDD, TDD, project validation, or Trellis. It turns confirmed acceptance behavior into executable examples. PRD explains intent and scope, DDD stabilizes vocabulary and boundaries, BDD specifies observable behavior, and TDD turns the scenario into red tests and green implementation.

## When To Use

Use this Skill when:

- The user asks for BDD, Gherkin, Given/When/Then, `.feature`, scenarios, acceptance criteria, or behavior specs.
- A task adds or changes UI, API, CLI, exported files, notifications, permissions, errors, status changes, or externally observable integration behavior.
- A user-visible bug is being fixed.
- A Trellis task has acceptance criteria that describe user-visible behavior.

# Knowledge Base Integration

Use this Skill for the P1 read-only integration runtime. Repository-owned `.feature` files at configured target refs remain the behavior SOT. The runtime produces rebuildable catalogs and evidence bundles; it does not change source repositories.

## Steps

1. Read the product registry and server workspace mapping. Validate both with `scripts/knowledge_base_p1.py validate-config`. Completion: every required repository has an explicit remote, role, target ref, feature root, and contained local mapping.
2. Resolve Evidence intent before a formal run with `decision`. Completion: the immutable decision records `required` / `not-required` / `blocked`, targets, source rule, reason, policy version, and digest.
3. For `read / 读取`, run `ingest`. Completion: every available ref is fixed to a full commit SHA; complete no-ID Gherkin structures, locators, bindings, conflict candidates, `metrics.json`, and `ingest-summary.json` exist; `mutation` is `none`.
4. For CI or knowledge-server smoke, run `smoke` only after runner, environment, account, data, service, device, and app-artifact prerequisites are known. Completion: staged native commands ran through the local or configured command Runner Adapter; current-run reports, Chinese summaries, artifact manifest, checksums, metrics and evidence bundle exist, or the run is explicitly `blocked`.
5. Report exact status and paths. P1 publication is always `not-configured`; PR checks, remote publication, invalidation, retention, quarantine and gates belong to P2.

## Commands

# Lessons Recording

Record reusable prevention knowledge, not a task diary. A bug fix, rollback, incorrect tool judgment, workflow/mode mistake, failed validation, unsuitable task decomposition or lost multi-agent context warrants assessing whether a durable lesson exists. Do not create a lesson just to satisfy a ritual.

Project rules and explicit deliverables remain binding. Default/lite may defer a nonessential lesson and continue unrelated safe work; strict leaves a required lesson incomplete until its identity, authority and evidence are available. No mode permits a guessed author, fabricated cause, anonymous placeholder or false saved claim. A request only to read lessons never creates identity or lesson files.

## One layered library

Use the project's explicit compatible layout. Otherwise:

- `docs/spec/lessons.md`: the single short entry, reading protocol, topic routing and high-frequency prevention summaries.
- `docs/lessons/index.md`: searchable id/tags/read_when/summary/detail rows.
- `docs/lessons/topics/<topic>.md`: complete records.
- `docs/lessons/archive/YYYY-QN.md`: low-frequency history, read only when relevant.

# Maestro Mobile E2E

Use this Skill for Mobile / Hybrid E2E work that uses Maestro.

This Skill does not replace `gherkin-bdd`, `project-validation`, task workflows, project tests, or human review. BDD `.feature` files are the behavior source of truth; Maestro flow YAML files are executable Mobile / Hybrid E2E assets derived from selected BDD scenarios.

## Workflow

1. Confirm the task involves Android, iOS, React Native, Flutter, Hybrid App, mobile smoke, or cross-device user journeys.
2. Read the relevant BDD `.feature` scenarios first. If no BDD scenario exists for user-visible behavior, return to `gherkin-bdd` before generating flow assets.
3. Run the mobile context gate before generating or running flows.
4. Decide whether the BDD scenario should become a Maestro flow. Use Maestro for device-level journeys, native permissions, deep links, system UI, mobile navigation, or Hybrid flows that cannot be covered reliably by Web E2E alone.
5. Classify the run mode: `full-stack`, `contract-backed`, `app-mocked`, `smoke-only`, or `blocked`.
6. Generate or update flow assets under `maestro/flow/`.

# Project Validation Skill

Use this Skill after code changes.

## General Rules

- Prefer commands already defined by the project.
- When `rtk` is available, prefer `rtk` for non-reporting commands; for unit tests, API / integration tests, Playwright Web E2E, Maestro Mobile / Hybrid E2E, or any command that must generate report files, first apply the `rtk` and reporting-test Gate.
- Do not bypass project configuration.
- Do not modify lock files unless required by the task.
- If full checks are expensive, run focused checks first.
- State which checks were skipped and the remaining risks.

## `rtk` and Reporting-Test Gate

# SBTD Task

Use host-native tools to carry out the user's task. This Skill supplies task rules, not a scheduler, daemon, hook system, or new CLI. Project rules and explicit delivery requirements remain binding. Do not invent commands or claim unavailable helpers ran.

## Route before work

1. Identify the task, authorized project root, branch, and read-only constraints using only necessary reads. An existing task's branch mismatch pauses business and metadata writes: offer its correct worktree, explicitly authorized rebinding, or read-only inspection. "Continue" or choosing a mode does not authorize rebinding.
2. Mode precedence: the user's current explicit choice; otherwise the same task's confirmed/effective record; otherwise `default` for a genuinely new task. A missing, invalid, or ambiguous old record is not a new task: ask which task or mode to use. Do not choose by mtime. A valid task outranks an old handoff.
3. Assess fit without implementing first. If another mode is preferable, explain the current mode, recommendation and reason, and the option to keep the current mode; pause substantive work for the user's decision. Upgrades and downgrades use the same confirmation rule. Never infer a mode from output compression, installed tools, task complexity, or an existing task directory.
4. Honor a refusal, preserve its reason where writing is allowed, and continue in the selected mode. Do not repeatedly recommend the same change without new substantive risk. Same-task continuation preserves its choice; a new unrelated task does not inherit it.
5. For a writable project task with no branch conflict, save the confirmed mode and source promptly using [task state](references/state.md). Do not wait for handoff. If saving fails, keep the current-session choice, report that it was not persisted, and do not promise reliable recovery. `default/lite` may continue unrelated safe work; required `strict` artifacts remain incomplete.
6. Then assess clarification. Read facts the project can answer. If requirements are clear, explain why full `grill-with-docs` was not needed and proceed. For consequential domain ambiguity, explain the unresolved point and ask about grill. Declining a method does not authorize guessing required answers.
7. After every completed full `grill-with-docs` session, invoke `book-ddd-distilled-modeling` and present its separate visible `DDD Boundary Review` in every mode. Follow that Skill's result and correction loop: advance requirement confirmation/design only at `confirmed`; `needs-clarification` returns to clarification and `blocked` stops the dependent step. An unavailable/unreadable reviewer or missing required evidence is blocked for default, lite and strict until the gate can run and pass. Interview-time modeling and informal substitute checks do not satisfy this post-grill gate. This gate has no default/lite substitute; it does not disable fallback for unrelated optional tools.

# SEO/GEO Optimization Skill

Comprehensive SEO and GEO (Generative Engine Optimization) for websites. Optimize for both traditional search engines (Google, Bing) and AI search engines (ChatGPT, Perplexity, Gemini, Copilot, Claude).

## Quick Reference

**GEO = Generative Engine Optimization** - Optimizing content to be cited by AI search engines.

**Key Insight:** AI search engines don't rank pages - they **cite sources**. Being cited is the new "ranking #1".

## Workflow

### Step 1: Website Audit

# Web UI 自动化测试生成器

使用本 skill 可以把一个 Web 项目整理成可执行、可复查、可持续维护的 UI 自动化测试套件。

目标不是只写几条临时脚本，而是先分析前端页面、后端接口、用户流程和 UI 状态，再生成 Playwright 测试、覆盖率清单、执行命令和中文报告。生成后的测试资产应能脱离本 skill 独立运行。

## 默认技术栈

除非目标仓库已经明确使用其他 UI 测试框架，否则默认使用 Playwright + TypeScript。

默认输出结构：

```text
tests/e2e/

# Book DDD Distilled Modeling

Use this Skill to sharpen domain language before turning a business request into PRD, issues, design, or code.

It is derived from the `mini` rule style of `agent-rules-books` and should run after project evidence is read. It complements `grill-with-docs`, `to-spec`, and task planning.

## Mandatory Post-grill Review

Every fully completed `grill-with-docs` session MUST be followed immediately by this Skill, whether the Agent initiated that session or the user invoked it explicitly. The `domain-modeling` activity embedded in `grill-with-docs` is the active interview-time modeling pass; it does not satisfy or replace this independent second-pass review.

Re-read the completed clarification result and the supporting project facts. Look for boundary errors, hidden term collisions, unsupported invariants, misplaced responsibilities, and unresolved context ownership rather than merely restating the interview.

The review is a gate before requirement confirmation, PRD, design, task creation, or implementation:

# Book DDIA Data Design

Use this Skill when a change can fail because of data semantics, distributed behavior, or operational reality rather than ordinary code structure.

It is derived from the `mini` rule style of `agent-rules-books` and should complement project architecture, task design, source/LSP/contract impact analysis, tests, and production validation.

## Strict Development Gate

In a strict task, run this Skill before design artifacts become stable or implementation begins when the task changes any of the following:

- Persisted or shared data, databases, schemas, or migrations.
- shared, persistent, cross-request, or cross-process caches; queues, events, streams, jobs, ETL, or analytics pipelines.
- Cross-service data flow or API ownership.
- Data ownership, source of truth, transaction boundaries, or read / write paths.

# Book Legacy Change Safety

Use this Skill when the main risk is not the requested change itself, but the uncertainty around existing behavior.

It is derived from the `mini` rule style of `agent-rules-books` and is intended to complement `diagnosing-bugs`, `tdd`, source/LSP/contract impact analysis, and project validation.

## Strict Development Gate

In a strict task, run this Skill before the first behavior-changing edit when either condition is true:

- The task fixes a bug in existing observable behavior.
- Existing target code has weak / missing tests, unclear or undocumented behavior, hidden dependencies, or high regression risk.

Emit a separate visible review:

# Book Refactoring Pass

Use this Skill as a focused refactoring check before or during implementation.

It is derived from the `mini` rule style of `agent-rules-books`. It is a strict development gate for existing-production-code edits and an on-demand engineering lens in other structural-risk scenarios; it does not replace project rules, tests, task artifacts, source/LSP/contract impact analysis, or code review.

## Strict Development Gate

Whenever a strict task will modify existing production code, run this Skill before the first implementation edit to existing production code, even when the expected result is that no refactoring is needed.

Emit a separate visible review:

```text
Refactoring Review

# Book Release Readiness

Use this Skill as a production-readiness pass before considering a service or integration change complete.

It is derived from the `mini` rule style of `agent-rules-books` and complements project validation, Playwright, Maestro, Chrome DevTools diagnostics, task check, and human release review.

## Strict Development Gate

In a strict task, run this Skill after all applicable testing-tool gates and project validation, and before the task is declared complete or the final release decision when the task changes any production-path:

- Service, API, auth, billing, or notification behavior.
- Background job, queue, scheduler, or data pipeline.
- External integration.
- Deployment, rollout, migration, or runtime operational behavior.

# Gherkin BDD

Use this Skill for user-visible behavior. In strict tasks, new or changed behavior that a user, administrator, API client, CLI user, integration system, exported file consumer, notification recipient, or permission/error-state observer can see must have a persistent BDD scenario before implementation is completed. In default/lite tasks, apply this Skill when user-visible behavior, project rules, risk, or explicit delivery requirements call for persistent behavior evidence.

BDD does not replace PRD, DDD, TDD, project validation, or task workflows. It turns confirmed acceptance behavior into executable examples. PRD explains intent and scope, DDD stabilizes vocabulary and boundaries, BDD specifies observable behavior, and TDD turns the scenario into red tests and green implementation.

## When To Use

Use this Skill when:

- The user asks for BDD, Gherkin, Given/When/Then, `.feature`, scenarios, acceptance criteria, or behavior specs.
- A task adds or changes UI, API, CLI, exported files, notifications, permissions, errors, status changes, or externally observable integration behavior.
- A user-visible bug is being fixed.
- A task has acceptance criteria that describe user-visible behavior.

# Knowledge Base Integration

Use this Skill for the P1 read-only integration runtime. Repository-owned `.feature` files at configured target refs remain the behavior SOT. The runtime produces rebuildable catalogs and evidence bundles; it does not change source repositories.

## Steps

1. Read the product registry and server workspace mapping. Validate both with `scripts/knowledge_base_p1.py validate-config`. Completion: every required repository has an explicit remote, role, target ref, feature root, and contained local mapping.
2. Resolve Evidence intent before a formal run with `decision`. Completion: the immutable decision records `required` / `not-required` / `blocked`, targets, source rule, reason, policy version, and digest.
3. For `read / 读取`, run `ingest`. Completion: every available ref is fixed to a full commit SHA; complete no-ID Gherkin structures, locators, bindings, conflict candidates, `metrics.json`, and `ingest-summary.json` exist; `mutation` is `none`.
4. For CI or knowledge-server smoke, run `smoke` only after runner, environment, account, data, service, device, and app-artifact prerequisites are known. Completion: staged native commands ran through the local or configured command Runner Adapter; current-run reports, Chinese summaries, artifact manifest, checksums, metrics and evidence bundle exist, or the run is explicitly `blocked`.
5. Report exact status and paths. P1 publication is always `not-configured`; PR checks, remote publication, invalidation, retention, quarantine and gates belong to P2.

## Commands

# Lessons Recording

Record reusable prevention knowledge, not a task diary. A bug fix, rollback, incorrect tool judgment, workflow/mode mistake, failed validation, unsuitable task decomposition or lost multi-agent context warrants assessing whether a durable lesson exists. Do not create a lesson just to satisfy a ritual.

Project rules and explicit deliverables remain binding. Default/lite may defer a nonessential lesson and continue unrelated safe work; strict leaves a required lesson incomplete until its identity, authority and evidence are available. No mode permits a guessed author, fabricated cause, anonymous placeholder or false saved claim. A request only to read lessons never creates identity or lesson files.

## One layered library

Use the project's explicit compatible layout. Otherwise:

- `docs/spec/lessons.md`: the single short entry, reading protocol, topic routing and high-frequency prevention summaries.
- `docs/lessons/index.md`: searchable id/tags/read_when/summary/detail rows.
- `docs/lessons/topics/<topic>.md`: complete records.
- `docs/lessons/archive/YYYY-QN.md`: low-frequency history, read only when relevant.

# Maestro Mobile E2E

Use this Skill for Mobile / Hybrid E2E work that uses Maestro.

This Skill does not replace `gherkin-bdd`, `project-validation`, task workflows, project tests, or human review. BDD `.feature` files are the behavior source of truth; Maestro flow YAML files are executable Mobile / Hybrid E2E assets derived from selected BDD scenarios.

## Workflow

1. Confirm the task involves Android, iOS, React Native, Flutter, Hybrid App, mobile smoke, or cross-device user journeys.
2. Read the relevant BDD `.feature` scenarios first. If no BDD scenario exists for user-visible behavior, return to `gherkin-bdd` before generating flow assets.
3. Run the mobile context gate before generating or running flows.
4. Decide whether the BDD scenario should become a Maestro flow. Use Maestro for device-level journeys, native permissions, deep links, system UI, mobile navigation, or Hybrid flows that cannot be covered reliably by Web E2E alone.
5. Classify the run mode: `full-stack`, `contract-backed`, `app-mocked`, `smoke-only`, or `blocked`.
6. Generate or update flow assets under `maestro/flow/`.

# Project Validation Skill

Use this Skill after code changes.

## General Rules

- Prefer commands already defined by the project.
- When `rtk` is available, prefer `rtk` for non-reporting commands; for unit tests, API / integration tests, Playwright Web E2E, Maestro Mobile / Hybrid E2E, or any command that must generate report files, first apply the `rtk` and reporting-test Gate.
- Do not bypass project configuration.
- Do not modify lock files unless required by the task.
- If full checks are expensive, run focused checks first.
- State which checks were skipped and the remaining risks.

## `rtk` and Reporting-Test Gate

# SEO/GEO Optimization Skill

Comprehensive SEO and GEO (Generative Engine Optimization) for websites. Optimize for both traditional search engines (Google, Bing) and AI search engines (ChatGPT, Perplexity, Gemini, Copilot, Claude).

## Quick Reference

**GEO = Generative Engine Optimization** - Optimizing content to be cited by AI search engines.

**Key Insight:** AI search engines don't rank pages - they **cite sources**. Being cited is the new "ranking #1".

## Workflow

### Step 1: Website Audit

# Web UI 自动化测试生成器

使用本 skill 可以把一个 Web 项目整理成可执行、可复查、可持续维护的 UI 自动化测试套件。

目标不是只写几条临时脚本，而是先分析前端页面、后端接口、用户流程和 UI 状态，再生成 Playwright 测试、覆盖率清单、执行命令和中文报告。生成后的测试资产应能脱离本 skill 独立运行。

## 默认技术栈

除非目标仓库已经明确使用其他 UI 测试框架，否则默认使用 Playwright + TypeScript。

默认输出结构：

```text
tests/e2e/

# Book DDD Distilled Modeling

Use this Skill to sharpen domain language before turning a business request into PRD, issues, design, or code.

It is derived from the `mini` rule style of `agent-rules-books` and should run after project evidence is read. It complements `grill-with-docs`, `to-spec`, and task planning.

## Mandatory Post-grill Review

Every fully completed `grill-with-docs` session MUST be followed immediately by this Skill, whether the Agent initiated that session or the user invoked it explicitly. The `domain-modeling` activity embedded in `grill-with-docs` is the active interview-time modeling pass; it does not satisfy or replace this independent second-pass review.

Re-read the completed clarification result and the supporting project facts. Look for boundary errors, hidden term collisions, unsupported invariants, misplaced responsibilities, and unresolved context ownership rather than merely restating the interview.

The review is a gate before requirement confirmation, PRD, design, task creation, or implementation:

# Book DDIA Data Design

Use this Skill when a change can fail because of data semantics, distributed behavior, or operational reality rather than ordinary code structure.

It is derived from the `mini` rule style of `agent-rules-books` and should complement project architecture, task design, source/LSP/contract impact analysis, tests, and production validation.

## Strict Development Gate

In a strict task, run this Skill before design artifacts become stable or implementation begins when the task changes any of the following:

- Persisted or shared data, databases, schemas, or migrations.
- shared, persistent, cross-request, or cross-process caches; queues, events, streams, jobs, ETL, or analytics pipelines.
- Cross-service data flow or API ownership.
- Data ownership, source of truth, transaction boundaries, or read / write paths.

# Book Legacy Change Safety

Use this Skill when the main risk is not the requested change itself, but the uncertainty around existing behavior.

It is derived from the `mini` rule style of `agent-rules-books` and is intended to complement `diagnosing-bugs`, `tdd`, source/LSP/contract impact analysis, and project validation.

## Strict Development Gate

In a strict task, run this Skill before the first behavior-changing edit when either condition is true:

- The task fixes a bug in existing observable behavior.
- Existing target code has weak / missing tests, unclear or undocumented behavior, hidden dependencies, or high regression risk.

Emit a separate visible review:

# Book Refactoring Pass

Use this Skill as a focused refactoring check before or during implementation.

It is derived from the `mini` rule style of `agent-rules-books`. It is a strict development gate for existing-production-code edits and an on-demand engineering lens in other structural-risk scenarios; it does not replace project rules, tests, task artifacts, source/LSP/contract impact analysis, or code review.

## Strict Development Gate

Whenever a strict task will modify existing production code, run this Skill before the first implementation edit to existing production code, even when the expected result is that no refactoring is needed.

Emit a separate visible review:

```text
Refactoring Review

# Book Release Readiness

Use this Skill as a production-readiness pass before considering a service or integration change complete.

It is derived from the `mini` rule style of `agent-rules-books` and complements project validation, Playwright, Maestro, Chrome DevTools diagnostics, task check, and human release review.

## Strict Development Gate

In a strict task, run this Skill after all applicable testing-tool gates and project validation, and before the task is declared complete or the final release decision when the task changes any production-path:

- Service, API, auth, billing, or notification behavior.
- Background job, queue, scheduler, or data pipeline.
- External integration.
- Deployment, rollout, migration, or runtime operational behavior.

# Gherkin BDD

Use this Skill for user-visible behavior. In strict tasks, new or changed behavior that a user, administrator, API client, CLI user, integration system, exported file consumer, notification recipient, or permission/error-state observer can see must have a persistent BDD scenario before implementation is completed. In default/lite tasks, apply this Skill when user-visible behavior, project rules, risk, or explicit delivery requirements call for persistent behavior evidence.

BDD does not replace PRD, DDD, TDD, project validation, or task workflows. It turns confirmed acceptance behavior into executable examples. PRD explains intent and scope, DDD stabilizes vocabulary and boundaries, BDD specifies observable behavior, and TDD turns the scenario into red tests and green implementation.

## When To Use

Use this Skill when:

- The user asks for BDD, Gherkin, Given/When/Then, `.feature`, scenarios, acceptance criteria, or behavior specs.
- A task adds or changes UI, API, CLI, exported files, notifications, permissions, errors, status changes, or externally observable integration behavior.
- A user-visible bug is being fixed.
- A task has acceptance criteria that describe user-visible behavior.

# Knowledge Base Integration

Use this Skill for the P1 read-only integration runtime. Repository-owned `.feature` files at configured target refs remain the behavior SOT. The runtime produces rebuildable catalogs and evidence bundles; it does not change source repositories.

## Steps

1. Read the product registry and server workspace mapping. Validate both with `scripts/knowledge_base_p1.py validate-config`. Completion: every required repository has an explicit remote, role, target ref, feature root, and contained local mapping.
2. Resolve Evidence intent before a formal run with `decision`. Completion: the immutable decision records `required` / `not-required` / `blocked`, targets, source rule, reason, policy version, and digest.
3. For `read / 读取`, run `ingest`. Completion: every available ref is fixed to a full commit SHA; complete no-ID Gherkin structures, locators, bindings, conflict candidates, `metrics.json`, and `ingest-summary.json` exist; `mutation` is `none`.
4. For CI or knowledge-server smoke, run `smoke` only after runner, environment, account, data, service, device, and app-artifact prerequisites are known. Completion: staged native commands ran through the local or configured command Runner Adapter; current-run reports, Chinese summaries, artifact manifest, checksums, metrics and evidence bundle exist, or the run is explicitly `blocked`.
5. Report exact status and paths. P1 publication is always `not-configured`; PR checks, remote publication, invalidation, retention, quarantine and gates belong to P2.

## Commands

# Lessons Recording

Record reusable prevention knowledge, not a task diary. A bug fix, rollback, incorrect tool judgment, workflow/mode mistake, failed validation, unsuitable task decomposition or lost multi-agent context warrants assessing whether a durable lesson exists. Do not create a lesson just to satisfy a ritual.

Project rules and explicit deliverables remain binding. Default/lite may defer a nonessential lesson and continue unrelated safe work; strict leaves a required lesson incomplete until its identity, authority and evidence are available. No mode permits a guessed author, fabricated cause, anonymous placeholder or false saved claim. A request only to read lessons never creates identity or lesson files.

## One layered library

Use the project's explicit compatible layout. Otherwise:

- `docs/spec/lessons.md`: the single short entry, reading protocol, topic routing and high-frequency prevention summaries.
- `docs/lessons/index.md`: searchable id/tags/read_when/summary/detail rows.
- `docs/lessons/topics/<topic>.md`: complete records.
- `docs/lessons/archive/YYYY-QN.md`: low-frequency history, read only when relevant.

# Maestro Mobile E2E

Use this Skill for Mobile / Hybrid E2E work that uses Maestro.

This Skill does not replace `gherkin-bdd`, `project-validation`, task workflows, project tests, or human review. BDD `.feature` files are the behavior source of truth; Maestro flow YAML files are executable Mobile / Hybrid E2E assets derived from selected BDD scenarios.

## Workflow

1. Confirm the task involves Android, iOS, React Native, Flutter, Hybrid App, mobile smoke, or cross-device user journeys.
2. Read the relevant BDD `.feature` scenarios first. If no BDD scenario exists for user-visible behavior, return to `gherkin-bdd` before generating flow assets.
3. Run the mobile context gate before generating or running flows.
4. Decide whether the BDD scenario should become a Maestro flow. Use Maestro for device-level journeys, native permissions, deep links, system UI, mobile navigation, or Hybrid flows that cannot be covered reliably by Web E2E alone.
5. Classify the run mode: `full-stack`, `contract-backed`, `app-mocked`, `smoke-only`, or `blocked`.
6. Generate or update flow assets under `maestro/flow/`.