@event4u/agent-config 1.33.0 → 1.35.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (218) hide show
  1. package/.agent-src/commands/review-changes.md +13 -8
  2. package/.agent-src/commands/roadmap/process-full.md +17 -15
  3. package/.agent-src/contexts/execution/roadmap-process-loop.md +11 -10
  4. package/.agent-src/personas/README.md +12 -21
  5. package/.agent-src/personas/_template-specialist/persona.md +89 -0
  6. package/.agent-src/personas/backend-architect.md +96 -0
  7. package/.agent-src/personas/discovery-lead.md +99 -0
  8. package/.agent-src/personas/eloquent-tamer.md +96 -0
  9. package/.agent-src/personas/frontend-engineer.md +100 -0
  10. package/.agent-src/personas/product-owner.md +71 -52
  11. package/.agent-src/personas/qa.md +27 -2
  12. package/.agent-src/personas/revops-maintainer.md +100 -0
  13. package/.agent-src/personas/security-engineer.md +100 -0
  14. package/.agent-src/personas/tech-writer.md +99 -0
  15. package/.agent-src/skills/accessibility-auditor/SKILL.md +132 -0
  16. package/.agent-src/skills/adr-create/SKILL.md +1 -0
  17. package/.agent-src/skills/adversarial-review/SKILL.md +1 -0
  18. package/.agent-src/skills/agent-docs-writing/SKILL.md +1 -0
  19. package/.agent-src/skills/agents-md-thin-root/SKILL.md +1 -0
  20. package/.agent-src/skills/ai-council/SKILL.md +1 -0
  21. package/.agent-src/skills/analysis-autonomous-mode/SKILL.md +1 -0
  22. package/.agent-src/skills/analysis-skill-router/SKILL.md +1 -0
  23. package/.agent-src/skills/api-design/SKILL.md +3 -0
  24. package/.agent-src/skills/api-endpoint/SKILL.md +1 -0
  25. package/.agent-src/skills/api-testing/SKILL.md +1 -0
  26. package/.agent-src/skills/architecture-review-lens/SKILL.md +137 -0
  27. package/.agent-src/skills/artisan-commands/SKILL.md +1 -0
  28. package/.agent-src/skills/async-python-patterns/SKILL.md +1 -0
  29. package/.agent-src/skills/authz-review/SKILL.md +4 -0
  30. package/.agent-src/skills/aws-infrastructure/SKILL.md +1 -0
  31. package/.agent-src/skills/blade-ui/SKILL.md +1 -0
  32. package/.agent-src/skills/blast-radius-analyzer/SKILL.md +3 -0
  33. package/.agent-src/skills/bug-analyzer/SKILL.md +1 -0
  34. package/.agent-src/skills/check-refs/SKILL.md +1 -0
  35. package/.agent-src/skills/code-refactoring/SKILL.md +1 -0
  36. package/.agent-src/skills/code-review/SKILL.md +1 -0
  37. package/.agent-src/skills/command-routing/SKILL.md +1 -0
  38. package/.agent-src/skills/command-writing/SKILL.md +1 -0
  39. package/.agent-src/skills/competitive-positioning/SKILL.md +152 -0
  40. package/.agent-src/skills/composer-packages/SKILL.md +1 -0
  41. package/.agent-src/skills/context-authoring/SKILL.md +1 -0
  42. package/.agent-src/skills/context-document/SKILL.md +1 -0
  43. package/.agent-src/skills/conventional-commits-writing/SKILL.md +1 -0
  44. package/.agent-src/skills/copilot-agents-optimization/SKILL.md +1 -0
  45. package/.agent-src/skills/copilot-config/SKILL.md +1 -0
  46. package/.agent-src/skills/customer-research/SKILL.md +116 -0
  47. package/.agent-src/skills/dashboard-design/SKILL.md +1 -0
  48. package/.agent-src/skills/data-flow-mapper/SKILL.md +1 -0
  49. package/.agent-src/skills/database/SKILL.md +3 -0
  50. package/.agent-src/skills/dcf-modeling/SKILL.md +1 -0
  51. package/.agent-src/skills/decision-record/SKILL.md +218 -0
  52. package/.agent-src/skills/deep-reading-analyst/SKILL.md +1 -0
  53. package/.agent-src/skills/defense-in-depth/SKILL.md +1 -0
  54. package/.agent-src/skills/dependency-upgrade/SKILL.md +1 -0
  55. package/.agent-src/skills/description-assist/SKILL.md +1 -0
  56. package/.agent-src/skills/design-review/SKILL.md +1 -0
  57. package/.agent-src/skills/devcontainer/SKILL.md +1 -0
  58. package/.agent-src/skills/developer-like-execution/SKILL.md +1 -0
  59. package/.agent-src/skills/discovery-interview/SKILL.md +152 -0
  60. package/.agent-src/skills/docker/SKILL.md +1 -0
  61. package/.agent-src/skills/dto-creator/SKILL.md +1 -0
  62. package/.agent-src/skills/eloquent/SKILL.md +3 -0
  63. package/.agent-src/skills/error-handling-patterns/SKILL.md +1 -0
  64. package/.agent-src/skills/estimate-ticket/SKILL.md +1 -0
  65. package/.agent-src/skills/existing-ui-audit/SKILL.md +3 -0
  66. package/.agent-src/skills/fe-design/SKILL.md +4 -1
  67. package/.agent-src/skills/feature-planning/SKILL.md +1 -0
  68. package/.agent-src/skills/file-editor/SKILL.md +1 -0
  69. package/.agent-src/skills/finishing-a-development-branch/SKILL.md +1 -0
  70. package/.agent-src/skills/flux/SKILL.md +1 -0
  71. package/.agent-src/skills/form-handler/SKILL.md +145 -0
  72. package/.agent-src/skills/funnel-analysis/SKILL.md +1 -0
  73. package/.agent-src/skills/git-workflow/SKILL.md +1 -0
  74. package/.agent-src/skills/github-ci/SKILL.md +1 -0
  75. package/.agent-src/skills/grafana/SKILL.md +1 -0
  76. package/.agent-src/skills/guideline-writing/SKILL.md +1 -0
  77. package/.agent-src/skills/incident-commander/SKILL.md +140 -0
  78. package/.agent-src/skills/jira-integration/SKILL.md +1 -0
  79. package/.agent-src/skills/jobs-events/SKILL.md +1 -0
  80. package/.agent-src/skills/judge-bug-hunter/SKILL.md +1 -0
  81. package/.agent-src/skills/judge-code-quality/SKILL.md +1 -0
  82. package/.agent-src/skills/judge-security-auditor/SKILL.md +3 -0
  83. package/.agent-src/skills/judge-test-coverage/SKILL.md +1 -0
  84. package/.agent-src/skills/laravel/SKILL.md +1 -0
  85. package/.agent-src/skills/laravel-horizon/SKILL.md +1 -0
  86. package/.agent-src/skills/laravel-mail/SKILL.md +1 -0
  87. package/.agent-src/skills/laravel-middleware/SKILL.md +1 -0
  88. package/.agent-src/skills/laravel-notifications/SKILL.md +1 -0
  89. package/.agent-src/skills/laravel-pennant/SKILL.md +1 -0
  90. package/.agent-src/skills/laravel-pulse/SKILL.md +1 -0
  91. package/.agent-src/skills/laravel-reverb/SKILL.md +1 -0
  92. package/.agent-src/skills/laravel-scheduling/SKILL.md +1 -0
  93. package/.agent-src/skills/laravel-validation/SKILL.md +1 -0
  94. package/.agent-src/skills/launch-readiness/SKILL.md +156 -0
  95. package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md +1 -0
  96. package/.agent-src/skills/lint-skills/SKILL.md +1 -0
  97. package/.agent-src/skills/livewire/SKILL.md +1 -0
  98. package/.agent-src/skills/livewire-architect/SKILL.md +158 -0
  99. package/.agent-src/skills/logging-monitoring/SKILL.md +1 -0
  100. package/.agent-src/skills/markitdown/SKILL.md +1 -0
  101. package/.agent-src/skills/mcp/SKILL.md +1 -0
  102. package/.agent-src/skills/mcp-builder/SKILL.md +1 -0
  103. package/.agent-src/skills/md-language-check/SKILL.md +1 -0
  104. package/.agent-src/skills/merge-conflicts/SKILL.md +1 -0
  105. package/.agent-src/skills/migration-architect/SKILL.md +119 -0
  106. package/.agent-src/skills/migration-creator/SKILL.md +1 -0
  107. package/.agent-src/skills/mobile-e2e-strategy/SKILL.md +2 -1
  108. package/.agent-src/skills/module-management/SKILL.md +1 -0
  109. package/.agent-src/skills/multi-tenancy/SKILL.md +1 -0
  110. package/.agent-src/skills/okr-tree-modeling/SKILL.md +1 -0
  111. package/.agent-src/skills/openapi/SKILL.md +1 -0
  112. package/.agent-src/skills/override-management/SKILL.md +1 -0
  113. package/.agent-src/skills/performance/SKILL.md +1 -0
  114. package/.agent-src/skills/performance-analysis/SKILL.md +1 -0
  115. package/.agent-src/skills/persona-writing/SKILL.md +1 -0
  116. package/.agent-src/skills/pest-testing/SKILL.md +1 -0
  117. package/.agent-src/skills/php-coder/SKILL.md +1 -0
  118. package/.agent-src/skills/php-debugging/SKILL.md +1 -0
  119. package/.agent-src/skills/php-service/SKILL.md +1 -0
  120. package/.agent-src/skills/playwright-architect/SKILL.md +141 -0
  121. package/.agent-src/skills/playwright-testing/SKILL.md +1 -0
  122. package/.agent-src/skills/po-discovery/SKILL.md +127 -0
  123. package/.agent-src/skills/project-analysis-core/SKILL.md +1 -0
  124. package/.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md +1 -0
  125. package/.agent-src/skills/project-analysis-laravel/SKILL.md +1 -0
  126. package/.agent-src/skills/project-analysis-nextjs/SKILL.md +1 -0
  127. package/.agent-src/skills/project-analysis-node-express/SKILL.md +1 -0
  128. package/.agent-src/skills/project-analysis-react/SKILL.md +1 -0
  129. package/.agent-src/skills/project-analysis-symfony/SKILL.md +1 -0
  130. package/.agent-src/skills/project-analysis-zend-laminas/SKILL.md +1 -0
  131. package/.agent-src/skills/project-analyzer/SKILL.md +1 -0
  132. package/.agent-src/skills/project-docs/SKILL.md +1 -0
  133. package/.agent-src/skills/prompt-engineering-patterns/SKILL.md +1 -0
  134. package/.agent-src/skills/prompt-optimizer/SKILL.md +1 -0
  135. package/.agent-src/skills/quality-tools/SKILL.md +1 -0
  136. package/.agent-src/skills/react-native-setup/SKILL.md +1 -0
  137. package/.agent-src/skills/react-shadcn-ui/SKILL.md +1 -0
  138. package/.agent-src/skills/readme-reviewer/SKILL.md +1 -0
  139. package/.agent-src/skills/readme-writing/SKILL.md +1 -0
  140. package/.agent-src/skills/readme-writing-package/SKILL.md +1 -0
  141. package/.agent-src/skills/receiving-code-review/SKILL.md +1 -0
  142. package/.agent-src/skills/refine-prompt/SKILL.md +1 -0
  143. package/.agent-src/skills/refine-ticket/SKILL.md +1 -0
  144. package/.agent-src/skills/release-comms/SKILL.md +123 -0
  145. package/.agent-src/skills/repomix-packer/SKILL.md +1 -0
  146. package/.agent-src/skills/requesting-code-review/SKILL.md +1 -0
  147. package/.agent-src/skills/review-routing/SKILL.md +1 -0
  148. package/.agent-src/skills/rice-prioritization/SKILL.md +1 -0
  149. package/.agent-src/skills/risk-officer/SKILL.md +141 -0
  150. package/.agent-src/skills/roadmap-management/SKILL.md +1 -0
  151. package/.agent-src/skills/roadmap-writing/SKILL.md +2 -1
  152. package/.agent-src/skills/rtk-output-filtering/SKILL.md +1 -0
  153. package/.agent-src/skills/rule-writing/SKILL.md +1 -0
  154. package/.agent-src/skills/script-writing/SKILL.md +1 -0
  155. package/.agent-src/skills/secrets-management/SKILL.md +1 -0
  156. package/.agent-src/skills/security/SKILL.md +1 -0
  157. package/.agent-src/skills/security-audit/SKILL.md +1 -0
  158. package/.agent-src/skills/sentry-integration/SKILL.md +1 -0
  159. package/.agent-src/skills/sequential-thinking/SKILL.md +1 -0
  160. package/.agent-src/skills/skill-improvement-pipeline/SKILL.md +1 -0
  161. package/.agent-src/skills/skill-management/SKILL.md +1 -0
  162. package/.agent-src/skills/skill-reviewer/SKILL.md +1 -0
  163. package/.agent-src/skills/skill-writing/SKILL.md +1 -0
  164. package/.agent-src/skills/sql-writing/SKILL.md +1 -0
  165. package/.agent-src/skills/stakeholder-tradeoff/SKILL.md +237 -0
  166. package/.agent-src/skills/subagent-orchestration/SKILL.md +13 -0
  167. package/.agent-src/skills/systematic-debugging/SKILL.md +1 -0
  168. package/.agent-src/skills/tailwind-engineer/SKILL.md +130 -0
  169. package/.agent-src/skills/tech-debt-tracker/SKILL.md +152 -0
  170. package/.agent-src/skills/technical-specification/SKILL.md +1 -0
  171. package/.agent-src/skills/terraform/SKILL.md +1 -0
  172. package/.agent-src/skills/terragrunt/SKILL.md +1 -0
  173. package/.agent-src/skills/test-driven-development/SKILL.md +1 -0
  174. package/.agent-src/skills/test-performance/SKILL.md +1 -0
  175. package/.agent-src/skills/testing-anti-patterns/SKILL.md +1 -0
  176. package/.agent-src/skills/threat-modeling/SKILL.md +3 -0
  177. package/.agent-src/skills/token-optimizer/SKILL.md +1 -0
  178. package/.agent-src/skills/traefik/SKILL.md +1 -0
  179. package/.agent-src/skills/ui-component-architect/SKILL.md +153 -0
  180. package/.agent-src/skills/unit-economics-modeling/SKILL.md +1 -0
  181. package/.agent-src/skills/universal-project-analysis/SKILL.md +1 -0
  182. package/.agent-src/skills/upstream-contribute/SKILL.md +1 -0
  183. package/.agent-src/skills/using-git-worktrees/SKILL.md +1 -0
  184. package/.agent-src/skills/validate-feature-fit/SKILL.md +1 -0
  185. package/.agent-src/skills/verify-completion-evidence/SKILL.md +1 -0
  186. package/.agent-src/skills/voc-extract/SKILL.md +164 -0
  187. package/.agent-src/skills/websocket/SKILL.md +1 -0
  188. package/.agent-src/templates/roadmaps.md +9 -0
  189. package/.claude-plugin/marketplace.json +21 -1
  190. package/AGENTS.md +1 -0
  191. package/CHANGELOG.md +75 -0
  192. package/README.md +2 -2
  193. package/docs/architecture.md +2 -2
  194. package/docs/catalog.md +21 -4
  195. package/docs/contracts/context-spine.md +133 -0
  196. package/docs/contracts/file-ownership-matrix.json +616 -0
  197. package/docs/contracts/mental-models.md +336 -0
  198. package/docs/contracts/persona-schema.md +136 -0
  199. package/docs/contracts/skill-domains.md +143 -0
  200. package/docs/decisions/ADR-005-subagent-worktrees.md +120 -0
  201. package/docs/decisions/ADR-006-skill-tools-python-pilot.md +114 -0
  202. package/docs/decisions/INDEX.md +3 -0
  203. package/docs/guidelines/cross-role-handoff.md +127 -0
  204. package/docs/personas.md +115 -0
  205. package/package.json +1 -1
  206. package/scripts/_backfill_skill_domains.py +140 -0
  207. package/scripts/_emit_domain_table.py +35 -0
  208. package/scripts/install-hooks.sh +21 -4
  209. package/scripts/lint_context_spine_usage.py +133 -0
  210. package/scripts/lint_roadmap_complexity.py +37 -0
  211. package/scripts/lint_skill_tools.py +168 -0
  212. package/scripts/schemas/skill.schema.json +15 -1
  213. package/scripts/skill_linter.py +19 -4
  214. package/scripts/skill_tools/__init__.py +22 -0
  215. package/scripts/skill_tools/audit_persona_coverage.py +147 -0
  216. package/scripts/skill_tools/run_block_d_eval.py +129 -0
  217. package/scripts/skill_tools/score_skill_relevance.py +169 -0
  218. package/scripts/skill_tools/suggest_skill_for_task.py +113 -0
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: playwright-architect
3
+ description: "Use when shaping a Playwright suite — locator strategy, Page Object boundaries, fixture composition, flake-prevention architecture, CI-vs-local split — even on 'design our E2E tests'."
4
+ personas:
5
+ - frontend-engineer
6
+ source: package
7
+ domain: quality
8
+ ---
9
+
10
+ # playwright-architect
11
+
12
+ > Architectural lens **above** the existing tactical
13
+ > [`playwright-testing`](../playwright-testing/SKILL.md). Decides
14
+ > locator philosophy, Page Object boundaries, fixture composition,
15
+ > and the CI-vs-local split *before* the first test is written.
16
+ > The `playwright-testing` skill handles concrete assertions,
17
+ > selectors, and visual-regression mechanics once the design is
18
+ > locked.
19
+
20
+ ## When to use
21
+
22
+ - A new Playwright suite is starting and the directory shape, fixture
23
+ hierarchy, and locator strategy are unsettled.
24
+ - An existing suite has flake > 2 % runs, slow CI (> 10 min), or a
25
+ god-test file mixing unrelated journeys.
26
+ - A second app / surface (admin, mobile-web, embedded widget) needs
27
+ to share fixtures with the main suite.
28
+ - German triggers: "Playwright Setup planen", "Page Objects schneiden",
29
+ "warum flaket der Test?".
30
+
31
+ Do NOT use when:
32
+
33
+ - A single test fails and the question is the assertion or selector
34
+ — route to [`playwright-testing`](../playwright-testing/SKILL.md).
35
+ - The platform is mobile-native (Detox, Appium, Maestro) — route to
36
+ [`mobile-e2e-strategy`](../mobile-e2e-strategy/SKILL.md).
37
+ - Unit / component tests are the question — Playwright is the wrong
38
+ tool; route to the stack-specific testing skill.
39
+
40
+ ## Procedure
41
+
42
+ ### 1. Inspect the suite, pick the locator philosophy
43
+
44
+ Review existing tests for current locator patterns; the established
45
+ strategy wins unless it is the "last resort" tier. One philosophy
46
+ per suite, written into `CONTRIBUTING-tests.md`:
47
+
48
+ | Strategy | When |
49
+ |---|---|
50
+ | `getByRole` + accessible name | Default — couples tests to the user contract, not markup |
51
+ | `data-testid` | Legacy markup, third-party widgets, hash-suffixed CSS modules |
52
+ | Text content (`getByText`) | Static marketing pages, copy-stable surfaces |
53
+ | CSS / XPath | Last resort — every use is a debt entry |
54
+
55
+ Mixing strategies inside one test file is the smell — pick one and
56
+ fall back only with comment.
57
+
58
+ ### 2. Cut Page Object boundaries
59
+
60
+ A Page Object owns: (a) one URL or one logical surface (modal,
61
+ drawer), (b) the locators on that surface, (c) the **actions** a
62
+ user can perform there. It does NOT own assertions about other
63
+ surfaces or test setup. Boundary rule: if two POs need to call
64
+ each other, introduce a **flow object** (`SignupFlow`) above them.
65
+
66
+ ### 3. Compose fixtures, don't inherit
67
+
68
+ Playwright fixtures stack via `test.extend()`. Three layers max:
69
+
70
+ | Layer | Owns |
71
+ |---|---|
72
+ | Base | Browser, context, storageState, network mocks |
73
+ | Auth | Logged-in user states (admin, member, guest) |
74
+ | Domain | Pre-seeded entities for a journey |
75
+
76
+ Deeper stacks become un-debuggable; flatten by extracting helpers.
77
+
78
+ ### 4. Plan flake prevention before the first failure
79
+
80
+ Bake in: auto-retry on network idle, soft assertions for parallel
81
+ checks, deterministic seed data, time freezing (`page.clock`),
82
+ explicit `expect.poll()` for eventual consistency, no
83
+ `waitForTimeout` ever. If a test needs `sleep`, the fixture is
84
+ wrong.
85
+
86
+ ### 5. Split CI vs local execution
87
+
88
+ Local: headed browser, single worker, slowMo enabled, video off,
89
+ trace-on-retry. CI: headless, sharded workers (2–8), trace-on-first-retry,
90
+ video-on-failure, Github reporter + HTML. Document both in
91
+ `playwright.config.ts`; do not let local config leak into CI.
92
+
93
+ ## Output format
94
+
95
+ Return:
96
+
97
+ 1. Locator + Page Object plan — chosen strategy, PO list with surface
98
+ and action count, flow objects when ≥ 2 POs collaborate.
99
+ 2. Fixture composition — base / auth / domain layer with what each
100
+ layer sets up.
101
+ 3. Parallelism + flake budget — worker count, shard strategy,
102
+ isolation, target flake ceiling, CI-vs-local config delta.
103
+
104
+ Concrete shape:
105
+
106
+ ```
107
+ Suite: <name>
108
+ Locator strategy: <getByRole | data-testid | text | mixed (justified)>
109
+ Page Objects: <list with surface owned + action count>
110
+ Flow objects: <list — only when ≥ 2 POs collaborate>
111
+ Fixture layers: base / auth / domain — each with what it sets up
112
+ Parallelism: <workers, shards, isolation strategy>
113
+ Flake budget: ≤ 1 % failure on green main; alert threshold
114
+ CI-vs-local: <key config delta, one bullet each>
115
+ ```
116
+
117
+ ## Gotcha
118
+
119
+ - `page.waitForSelector` is almost always wrong — `expect(locator).toBeVisible()`
120
+ has built-in retry. The former teaches devs to think "wait, then
121
+ assert" instead of "auto-retry assertion".
122
+ - Storage-state reuse across workers requires cookie domain
123
+ isolation; the same `auth.json` across two browsers in parallel
124
+ shares a session and corrupts state.
125
+ - Visual regression in CI requires identical fonts and renderer —
126
+ pin the Docker image, never run visual tests against host
127
+ Chromium.
128
+ - One Page Object per URL **looks** clean but creates god-objects
129
+ for SPA routes; cut by *user surface*, not by `pathname`.
130
+
131
+ ## Do NOT
132
+
133
+ - Do NOT cite this skill alongside [`playwright-testing`](../playwright-testing/SKILL.md)
134
+ in the same step — they sit at different tiers; pick one per phase.
135
+ - Do NOT design suites for component tests with this skill —
136
+ Playwright Component Testing has different fixture rules; route
137
+ there instead.
138
+ - Do NOT promise zero flake; budget for ≤ 1 % and instrument the
139
+ metric. Zero is a goal that disguises silent retries.
140
+ - Do NOT push the architecture into the tracker as code AC — output
141
+ is a design note for refinement, not implementation steps.
@@ -2,6 +2,7 @@
2
2
  name: playwright-testing
3
3
  description: "Use when writing Playwright E2E tests — browser automation, visual regression testing, Page Objects, fixtures, and reliable test patterns."
4
4
  source: package
5
+ domain: quality
5
6
  ---
6
7
 
7
8
  # playwright-testing
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: po-discovery
3
+ description: "Use when shaping a fuzzy product ask into a refined backlog item — problem framing, user-story rewrite, AC tightening — even if the user just says 'help me write this ticket'."
4
+ personas:
5
+ - product-owner
6
+ - stakeholder
7
+ source: package
8
+ domain: product
9
+ ---
10
+
11
+ # po-discovery
12
+
13
+ > Take a vague product request and return a **problem-framed**,
14
+ > **user-story-shaped**, **AC-tight** backlog item ready for refinement.
15
+ > Output is copy-paste ready; write-back to the tracker is user-gated.
16
+ > Sibling of [`refine-ticket`](../refine-ticket/SKILL.md) — that one
17
+ > tightens an existing ticket, this one shapes the *raw input* before
18
+ > a ticket exists.
19
+
20
+ ## When to use
21
+
22
+ - The user pastes a fuzzy idea ("we should let users export their data")
23
+ and asks to turn it into a ticket.
24
+ - A stakeholder request arrives without a clear problem statement.
25
+ - Acceptance criteria are missing, contradictory, or written as
26
+ implementation steps instead of observable outcomes.
27
+ - German triggers: "schreib daraus ein Ticket", "ist die Story klar?",
28
+ "AC fehlen noch".
29
+
30
+ Do NOT use when:
31
+
32
+ - A ticket already exists and needs tightening — route to
33
+ [`refine-ticket`](../refine-ticket/SKILL.md).
34
+ - The ask is already a clear, well-formed user story with measurable
35
+ AC — skip discovery and proceed to estimation.
36
+ - The request is an engineering task with no product framing
37
+ ("upgrade Laravel to 11") — discovery adds noise; skip.
38
+
39
+ ## Procedure
40
+
41
+ ### 1. Capture the raw input and identify the asker
42
+
43
+ Read the user's text verbatim. Do NOT rephrase yet. Identify: who is
44
+ the asker (PO, support, eng, exec)? What artefact did they hand over
45
+ (slack thread, screenshot, voice note transcript, free text)?
46
+
47
+ ### 2. Frame the problem
48
+
49
+ Answer four questions, every answer cited from the input or marked
50
+ `unknown`:
51
+
52
+ | Question | Why it matters |
53
+ |---|---|
54
+ | Who has the problem? | Personas, segments, internal vs external |
55
+ | What outcome do they want? | Distinguishes need from solution |
56
+ | What is the current pain or workaround? | Sizes the gap |
57
+ | What changes if we ship this? | Surfaces success signals |
58
+
59
+ Any answer marked `unknown` blocks story shaping — surface the gap
60
+ back to the user before continuing.
61
+
62
+ ### 3. Shape the user story
63
+
64
+ Use the canonical form: *As a `{persona}`, I want `{capability}`, so
65
+ that `{outcome}`*. Capability ≠ implementation. If the input says
66
+ "add a CSV button", reframe to "I want my data in a portable format,
67
+ so that I can use it outside the product".
68
+
69
+ ### 4. Tighten acceptance criteria
70
+
71
+ Each AC is **observable**, **binary** (passes or fails), and **does
72
+ not name an implementation**. Use Given / When / Then or a numbered
73
+ list. Reject ACs that hide assumptions ("works correctly", "is fast
74
+ enough") — replace with measurable thresholds or strike them.
75
+
76
+ ### 5. Surface non-functional gaps
77
+
78
+ Flag anything missing that downstream skills will need: success
79
+ metric, target users, rollout window, accessibility, security or
80
+ privacy boundary, multi-tenant scope. Do NOT invent values — list
81
+ them as `gap` items for the user to fill.
82
+
83
+ ## Output format
84
+
85
+ ```
86
+ Asker: <role / name>
87
+ Source: <slack / email / verbal / pasted text>
88
+ Problem: <one sentence — who, want, why>
89
+
90
+ User story:
91
+ As a <persona>, I want <capability>, so that <outcome>.
92
+
93
+ Acceptance criteria:
94
+ 1. Given <state>, when <action>, then <observable result>.
95
+ 2. ...
96
+
97
+ Open gaps (block estimation):
98
+ - <gap 1>
99
+ - <gap 2>
100
+
101
+ Suggested next step: /refine-ticket | /estimate-ticket | fill gaps
102
+ ```
103
+
104
+ If gaps remain, surface them and stop — do NOT push to estimation.
105
+
106
+ ## Gotcha
107
+
108
+ - If the asker is the agent itself (autopilot, roadmap), still run the
109
+ full procedure — the gap list is what catches the agent inventing
110
+ requirements.
111
+ - "Outcome" is what the user *gets*, not what we *build*. "Faster
112
+ page" is an outcome; "switch to Postgres" is an implementation.
113
+ - AC count is not a quality signal. Three sharp AC beat eight vague
114
+ ones; merge or split as needed.
115
+
116
+ ## Do NOT
117
+
118
+ - Do NOT write code, plan tasks, or estimate effort — those are
119
+ downstream skills.
120
+ - Do NOT silently fill gaps with plausible-looking defaults; the
121
+ whole point of discovery is to surface what the user has not
122
+ decided.
123
+ - Do NOT rewrite the asker's wording into agent voice in the
124
+ Problem field — preserve their framing so they recognise it.
125
+ - Do NOT push the rewritten ticket into Jira / Linear without the
126
+ user explicitly asking — output is copy-paste ready, write-back
127
+ is gated.
@@ -2,6 +2,7 @@
2
2
  name: project-analysis-core
3
3
  description: "Use for the universal deep-analysis workflow: project discovery, version resolution, docs loading, architecture mapping, execution flow, and package research."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analysis-core
@@ -2,6 +2,7 @@
2
2
  name: project-analysis-hypothesis-driven
3
3
  description: "Use when a bug has multiple plausible causes across layers — competing hypotheses, validation loops, evidence-based conclusions — even when the user just says 'why is this happening?'."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analysis-hypothesis-driven
@@ -2,6 +2,7 @@
2
2
  name: project-analysis-laravel
3
3
  description: "Use for deep Laravel project analysis: boot flow, request lifecycle, container usage, Eloquent/data flow, async systems, and Laravel-specific failure patterns."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analysis-laravel
@@ -2,6 +2,7 @@
2
2
  name: project-analysis-nextjs
3
3
  description: "Use for deep Next.js analysis: server vs client boundaries, routing, data fetching, caching, rendering modes, and hydration/runtime issues."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analysis-nextjs
@@ -2,6 +2,7 @@
2
2
  name: project-analysis-node-express
3
3
  description: "Use for deep Node.js / Express project analysis: boot flow, middleware order, async behavior, data layer, auth/security, and Node-specific runtime failure patterns."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analysis-node-express
@@ -2,6 +2,7 @@
2
2
  name: project-analysis-react
3
3
  description: "Use for deep React analysis: component tree, state flow, props flow, hooks usage, rendering behavior, and React-specific failure patterns."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analysis-react
@@ -2,6 +2,7 @@
2
2
  name: project-analysis-symfony
3
3
  description: "Use for deep Symfony project analysis: kernel/bootstrap, container wiring, routing/request flow, Doctrine, security, Messenger, and Symfony-specific failure patterns."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analysis-symfony
@@ -2,6 +2,7 @@
2
2
  name: project-analysis-zend-laminas
3
3
  description: "Use for deep Zend Framework or Laminas project analysis: bootstrap, config merge order, service manager, MVC flow, data layer, and migration-specific risks."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analysis-zend-laminas
@@ -2,6 +2,7 @@
2
2
  name: project-analyzer
3
3
  description: "ONLY when user explicitly requests: full project analysis, tech stack detection, or structured analysis documents for agents/analysis/. NOT for regular feature work."
4
4
  source: package
5
+ domain: discovery
5
6
  ---
6
7
 
7
8
  # project-analyzer
@@ -2,6 +2,7 @@
2
2
  name: project-docs
3
3
  description: "Use when looking for project-specific documentation. Knows which docs exist in agents/docs/ and agents/contexts/ and maps work areas to relevant docs."
4
4
  source: package
5
+ domain: process
5
6
  ---
6
7
 
7
8
  # project-docs
@@ -2,6 +2,7 @@
2
2
  name: prompt-engineering-patterns
3
3
  description: "Use when designing production-LLM prompts — few-shot, chain-of-thought, system prompts, templates, self-verification — distinct from prompt-optimizer and refine-prompt."
4
4
  source: package
5
+ domain: product
5
6
  status: active
6
7
  ---
7
8
 
@@ -2,6 +2,7 @@
2
2
  name: prompt-optimizer
3
3
  description: "Use when the user wants a prompt optimized for ChatGPT, Claude, Gemini, or another AI — 'make this prompt better', 'optimize for ChatGPT', 'rewrite my prompt' — even without saying 'optimize'."
4
4
  source: package
5
+ domain: product
5
6
  ---
6
7
 
7
8
  # prompt-optimizer
@@ -2,6 +2,7 @@
2
2
  name: quality-tools
3
3
  description: "Use when PHPStan, Rector, or ECS output appears — \"phpstan says mixed\", type errors, \"fix code style\", \"run rector\" — even when Eloquent/Laravel/model code is also mentioned."
4
4
  source: package
5
+ domain: quality
5
6
  execution:
6
7
  type: assisted
7
8
  handler: shell
@@ -2,6 +2,7 @@
2
2
  name: react-native-setup
3
3
  description: "Use when setting up React Native or Expo dev environments — Xcode, Android Studio, CocoaPods, EAS, Metro, New Architecture — even when the user just says 'my RN build won't start'."
4
4
  source: package
5
+ domain: devops
5
6
  ---
6
7
 
7
8
  # react-native-setup
@@ -2,6 +2,7 @@
2
2
  name: react-shadcn-ui
3
3
  description: "Use when building React UI on shadcn/ui primitives + Tailwind — the apply/review/polish skill dispatched by `directives/ui/*` for the `react-shadcn` stack."
4
4
  source: package
5
+ domain: engineering
5
6
  ---
6
7
 
7
8
  # react-shadcn-ui
@@ -2,6 +2,7 @@
2
2
  name: readme-reviewer
3
3
  description: "Use when reviewing a README for accuracy, usability, and alignment with the actual repository. Detects invented content, broken setup steps, and structural issues."
4
4
  source: package
5
+ domain: quality
5
6
  execution:
6
7
  type: assisted
7
8
  handler: internal
@@ -2,6 +2,7 @@
2
2
  name: readme-writing
3
3
  description: "Use when creating, rewriting, or significantly improving a README based on the actual repository structure, commands, and intended audience."
4
4
  source: package
5
+ domain: process
5
6
  execution:
6
7
  type: assisted
7
8
  handler: internal
@@ -2,6 +2,7 @@
2
2
  name: readme-writing-package
3
3
  description: "Use when creating or rewriting a README for a reusable package or library. Focus on installability, minimal usage example, compatibility, and developer onboarding."
4
4
  source: package
5
+ domain: process
5
6
  execution:
6
7
  type: assisted
7
8
  handler: internal
@@ -4,6 +4,7 @@ description: "Use when processing code review feedback (bot or human) before cha
4
4
  personas:
5
5
  - critical-challenger
6
6
  source: package
7
+ domain: process
7
8
  ---
8
9
 
9
10
  # receiving-code-review
@@ -6,6 +6,7 @@ personas:
6
6
  - senior-engineer
7
7
  - ai-agent
8
8
  source: package
9
+ domain: product
9
10
  execution:
10
11
  type: assisted
11
12
  handler: internal
@@ -9,6 +9,7 @@ personas:
9
9
  - critical-challenger
10
10
  - ai-agent
11
11
  source: package
12
+ domain: product
12
13
  execution:
13
14
  type: assisted
14
15
  handler: internal
@@ -0,0 +1,123 @@
1
+ ---
2
+ name: release-comms
3
+ description: "Use when turning a shipped changelog into a release narrative — value-not-feature framing, audience-segmented surfaces, one source of truth. Triggers on 'announce the release', 'write changelog post'."
4
+ status: active
5
+ tier: senior
6
+ source: package
7
+ domain: product
8
+ context_spine: [product, team]
9
+ ---
10
+
11
+ # release-comms
12
+
13
+ ## When to use
14
+
15
+ - Release shipping with user-facing change, team about to send feature-list email.
16
+ - Changelog draft reads like commit log — engineering-honest, unparseable for user.
17
+ - Multiple comms surfaces (in-app, email, social, docs) about to be written by different people from same release.
18
+
19
+ Do NOT use for incident comms (see `incident-commander`),
20
+ deprecation announcements needing legal sign-off, or pre-release
21
+ discovery — this skill assumes change is **shipped**.
22
+
23
+ ## Cognition cluster
24
+
25
+ - **Mental model 16 — Leading vs. lagging indicators.** Release note
26
+ is lagging artifact; leading version = in-app prompt that fired
27
+ before user found change-log. See
28
+ [`docs/contracts/mental-models.md`](../../../docs/contracts/mental-models.md) § 16.
29
+ - **Value-not-feature heuristic.** Every paragraph passes *"so the
30
+ user can ___"* completion. Failing rows go back for re-write.
31
+
32
+ ## Procedure
33
+
34
+ ### Step 0: Ground the release
35
+
36
+ 1. Read merged PR list / changelog block / release branch diff. Release = **what**; comms = **so what**. Conflate the two → ship marketing.
37
+ 2. Read **product** and **team** slots of [context-spine](../../../docs/contracts/context-spine.md) (if consumer filled them) for bounded scope and cadence — surface choice depends on cadence (weekly: in-app + log; quarterly: email + post; major: all four).
38
+ 3. Identify **single dominant change** the release ships. Three "headliners" reads as three half-announcements.
39
+
40
+ ### Step 1: Audience-segment
41
+
42
+ 1. Three audiences max: **active user**, **at-risk / lapsed user**, **prospect**. More fragments message; fewer hides routing.
43
+ 2. Per audience, write one sentence: *"After this release, you can …"* completing with user-side verb, not product-side feature.
44
+ 3. If two audiences end up with same sentence, collapse — segmentation that does not change message = theatre.
45
+
46
+ ### Step 2: Map surfaces to audiences
47
+
48
+ 1. **Changelog** (always) — engineers + power users; truthful, dense, link-heavy. Source of truth — every other surface points back here.
49
+ 2. **In-app prompt** — active users; ≤ 1 sentence + 1 CTA; fires for users whose past behaviour predicts they'll touch the new path.
50
+ 3. **Email** — at-risk / lapsed; one headline value, one CTA, one paragraph of context. No feature lists.
51
+ 4. **Social / blog** — prospect; the **why**, not the **what** — frame against user job (cite [`customer-research`](../customer-research/SKILL.md) if switch-event surfaced).
52
+
53
+ Cut surfaces aggressively. Weekly release does not need blog post.
54
+
55
+ ### Step 3: Draft each surface from the changelog
56
+
57
+ 1. Open changelog. Per surface, copy dominant change line, then **rewrite verb subject** from "we" to "you".
58
+ 2. Strip qualifiers ("now", "even better", "lightning-fast"). Noise, not signal.
59
+ 3. Run *"so the user can ___"* completion on every paragraph. Failing paragraphs cut, not edited.
60
+
61
+ ### Step 4: Truth-check
62
+
63
+ 1. Every claim links back to changelog row or doc URL. Unsourced claim → cut.
64
+ 2. No tense games — past for shipped, future for coming-soon (and only if date is committed). "Roadmap" lives outside this skill.
65
+ 3. Names match product surface. In-app says "Reports" and email says "Insights" → user fires lookup tax.
66
+
67
+ ### Step 5: Hand off
68
+
69
+ 1. Produce four artifacts (see `## Output`).
70
+ 2. Hand to whoever owns send. Do not embed scheduling or A/B test plans here — that is RevOps.
71
+
72
+ ## Related Skills
73
+
74
+ **WHEN to use this**
75
+
76
+ - Change is **shipped** and needs to reach existing users.
77
+ - Multiple comms surfaces written by different people from same source.
78
+ - Team about to default to feature-list email.
79
+
80
+ **WHEN NOT to use this**
81
+
82
+ - Production incident comms → [`incident-commander`](../incident-commander/SKILL.md).
83
+ - Pre-release discovery / validation → [`customer-research`](../customer-research/SKILL.md).
84
+ - Funnel-stage diagnostics post-release → [`funnel-analysis`](../funnel-analysis/SKILL.md).
85
+ - Ranking which release to comms next → [`rice-prioritization`](../rice-prioritization/SKILL.md).
86
+
87
+ ## When the agent should load this
88
+
89
+ - "Write the release notes for sprint 47."
90
+ - "We're shipping the new export — how do we announce it?"
91
+ - "Draft the changelog email for last week's batch."
92
+ - "What's the in-app prompt copy for the redesign?"
93
+ - "Turn the merged PR list into something users can read."
94
+
95
+ ## Output
96
+
97
+ 1. **`release-narrative.md`** — single source of truth: dominant change, audiences (1–3), per-audience *"After this release, you can …"* sentence, links to source changelog rows.
98
+ 2. **`changelog-entry.md`** — engineer-honest, dense, link-heavy block ready to paste into project's changelog.
99
+ 3. **`comms-pack.md`** — per-surface drafts (in-app prompt, email, optional social/blog), each ≤ surface's hard cap, each pointing back to `changelog-entry.md`.
100
+ 4. **`comms-checklist.md`** — pre-send checks: every claim sourced, names consistent across surfaces, audience match, "so the user can …" completion passing on every paragraph. Hand-off artifact for senior PO ([`product-owner`](../../personas/product-owner.md)).
101
+
102
+ ## Gotcha
103
+
104
+ - Default failure mode = feature-list email — written to make engineering feel seen, not to help user.
105
+ - Marketing puffery ("revolutionary", "delightful") fails source check; cut on sight.
106
+ - Two surfaces using different names for same thing = highest-frequency support-ticket trigger after release.
107
+ - Hidden coming-soon claims in past-tense paragraphs erode trust faster than missing the comms entirely.
108
+
109
+ ## Do NOT
110
+
111
+ - Do NOT promote coming-soon item alongside shipped items — user cannot tell which is which and stops trusting next note.
112
+ - Do NOT let long-tail change steal the headline — dominant change earns headline, long tail goes in changelog.
113
+ - Do NOT ship surfaces without truth-check pass; unsourced claim survives in social longer than release does.
114
+
115
+ ## Runnable example
116
+
117
+ Sprint 47 ships a one-click monthly export and three small bug fixes:
118
+
119
+ - Dominant change: one-click export. Bug fixes go in changelog only.
120
+ - Audiences: active user (will use it), at-risk (export friction was churn trigger per [`customer-research`](../customer-research/SKILL.md) evidence-log).
121
+ - "After this release, you can pull a board-ready monthly report in one click." (active, at-risk — same sentence ⇒ collapse to one).
122
+ - Surfaces: changelog (full), in-app prompt to active users on next month-end, email to at-risk cohort with same sentence and one CTA. No social.
123
+ - Truth-check: claim links to export PR; "one click" is literal — verified against shipped UI.
@@ -2,6 +2,7 @@
2
2
  name: repomix-packer
3
3
  description: "Use when packaging a codebase to a single AI-friendly file for LLM analysis — local or remote, XML/Markdown/JSON, token counting, gitignore filtering, peer-side `repomix` CLI."
4
4
  source: package
5
+ domain: process
5
6
  ---
6
7
 
7
8
  > **Pinned upstream:** `repomix` CLI (npm: `repomix`, brew: `repomix`). Re-verify per minor bump. Repomix is an **optional dependency** — this skill never installs it silently.
@@ -4,6 +4,7 @@ description: "Use when asking for a review or creating a PR — self-review firs
4
4
  personas:
5
5
  - critical-challenger
6
6
  source: package
7
+ domain: process
7
8
  ---
8
9
 
9
10
  # requesting-code-review
@@ -2,6 +2,7 @@
2
2
  name: review-routing
3
3
  description: "Use when preparing a PR description, suggesting reviewers, or flagging risk — produces owner-mapped roles plus historical bug-pattern matches from project-local YAML."
4
4
  source: package
5
+ domain: quality
5
6
  ---
6
7
 
7
8
  # review-routing
@@ -4,6 +4,7 @@ description: "Use when ranking competing initiatives for a roadmap, breaking a t
4
4
  status: active
5
5
  tier: senior
6
6
  source: package
7
+ domain: product
7
8
  ---
8
9
 
9
10
  # rice-prioritization