@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.
- package/.agent-src/commands/review-changes.md +13 -8
- package/.agent-src/commands/roadmap/process-full.md +17 -15
- package/.agent-src/contexts/execution/roadmap-process-loop.md +11 -10
- package/.agent-src/personas/README.md +12 -21
- package/.agent-src/personas/_template-specialist/persona.md +89 -0
- package/.agent-src/personas/backend-architect.md +96 -0
- package/.agent-src/personas/discovery-lead.md +99 -0
- package/.agent-src/personas/eloquent-tamer.md +96 -0
- package/.agent-src/personas/frontend-engineer.md +100 -0
- package/.agent-src/personas/product-owner.md +71 -52
- package/.agent-src/personas/qa.md +27 -2
- package/.agent-src/personas/revops-maintainer.md +100 -0
- package/.agent-src/personas/security-engineer.md +100 -0
- package/.agent-src/personas/tech-writer.md +99 -0
- package/.agent-src/skills/accessibility-auditor/SKILL.md +132 -0
- package/.agent-src/skills/adr-create/SKILL.md +1 -0
- package/.agent-src/skills/adversarial-review/SKILL.md +1 -0
- package/.agent-src/skills/agent-docs-writing/SKILL.md +1 -0
- package/.agent-src/skills/agents-md-thin-root/SKILL.md +1 -0
- package/.agent-src/skills/ai-council/SKILL.md +1 -0
- package/.agent-src/skills/analysis-autonomous-mode/SKILL.md +1 -0
- package/.agent-src/skills/analysis-skill-router/SKILL.md +1 -0
- package/.agent-src/skills/api-design/SKILL.md +3 -0
- package/.agent-src/skills/api-endpoint/SKILL.md +1 -0
- package/.agent-src/skills/api-testing/SKILL.md +1 -0
- package/.agent-src/skills/architecture-review-lens/SKILL.md +137 -0
- package/.agent-src/skills/artisan-commands/SKILL.md +1 -0
- package/.agent-src/skills/async-python-patterns/SKILL.md +1 -0
- package/.agent-src/skills/authz-review/SKILL.md +4 -0
- package/.agent-src/skills/aws-infrastructure/SKILL.md +1 -0
- package/.agent-src/skills/blade-ui/SKILL.md +1 -0
- package/.agent-src/skills/blast-radius-analyzer/SKILL.md +3 -0
- package/.agent-src/skills/bug-analyzer/SKILL.md +1 -0
- package/.agent-src/skills/check-refs/SKILL.md +1 -0
- package/.agent-src/skills/code-refactoring/SKILL.md +1 -0
- package/.agent-src/skills/code-review/SKILL.md +1 -0
- package/.agent-src/skills/command-routing/SKILL.md +1 -0
- package/.agent-src/skills/command-writing/SKILL.md +1 -0
- package/.agent-src/skills/competitive-positioning/SKILL.md +152 -0
- package/.agent-src/skills/composer-packages/SKILL.md +1 -0
- package/.agent-src/skills/context-authoring/SKILL.md +1 -0
- package/.agent-src/skills/context-document/SKILL.md +1 -0
- package/.agent-src/skills/conventional-commits-writing/SKILL.md +1 -0
- package/.agent-src/skills/copilot-agents-optimization/SKILL.md +1 -0
- package/.agent-src/skills/copilot-config/SKILL.md +1 -0
- package/.agent-src/skills/customer-research/SKILL.md +116 -0
- package/.agent-src/skills/dashboard-design/SKILL.md +1 -0
- package/.agent-src/skills/data-flow-mapper/SKILL.md +1 -0
- package/.agent-src/skills/database/SKILL.md +3 -0
- package/.agent-src/skills/dcf-modeling/SKILL.md +1 -0
- package/.agent-src/skills/decision-record/SKILL.md +218 -0
- package/.agent-src/skills/deep-reading-analyst/SKILL.md +1 -0
- package/.agent-src/skills/defense-in-depth/SKILL.md +1 -0
- package/.agent-src/skills/dependency-upgrade/SKILL.md +1 -0
- package/.agent-src/skills/description-assist/SKILL.md +1 -0
- package/.agent-src/skills/design-review/SKILL.md +1 -0
- package/.agent-src/skills/devcontainer/SKILL.md +1 -0
- package/.agent-src/skills/developer-like-execution/SKILL.md +1 -0
- package/.agent-src/skills/discovery-interview/SKILL.md +152 -0
- package/.agent-src/skills/docker/SKILL.md +1 -0
- package/.agent-src/skills/dto-creator/SKILL.md +1 -0
- package/.agent-src/skills/eloquent/SKILL.md +3 -0
- package/.agent-src/skills/error-handling-patterns/SKILL.md +1 -0
- package/.agent-src/skills/estimate-ticket/SKILL.md +1 -0
- package/.agent-src/skills/existing-ui-audit/SKILL.md +3 -0
- package/.agent-src/skills/fe-design/SKILL.md +4 -1
- package/.agent-src/skills/feature-planning/SKILL.md +1 -0
- package/.agent-src/skills/file-editor/SKILL.md +1 -0
- package/.agent-src/skills/finishing-a-development-branch/SKILL.md +1 -0
- package/.agent-src/skills/flux/SKILL.md +1 -0
- package/.agent-src/skills/form-handler/SKILL.md +145 -0
- package/.agent-src/skills/funnel-analysis/SKILL.md +1 -0
- package/.agent-src/skills/git-workflow/SKILL.md +1 -0
- package/.agent-src/skills/github-ci/SKILL.md +1 -0
- package/.agent-src/skills/grafana/SKILL.md +1 -0
- package/.agent-src/skills/guideline-writing/SKILL.md +1 -0
- package/.agent-src/skills/incident-commander/SKILL.md +140 -0
- package/.agent-src/skills/jira-integration/SKILL.md +1 -0
- package/.agent-src/skills/jobs-events/SKILL.md +1 -0
- package/.agent-src/skills/judge-bug-hunter/SKILL.md +1 -0
- package/.agent-src/skills/judge-code-quality/SKILL.md +1 -0
- package/.agent-src/skills/judge-security-auditor/SKILL.md +3 -0
- package/.agent-src/skills/judge-test-coverage/SKILL.md +1 -0
- package/.agent-src/skills/laravel/SKILL.md +1 -0
- package/.agent-src/skills/laravel-horizon/SKILL.md +1 -0
- package/.agent-src/skills/laravel-mail/SKILL.md +1 -0
- package/.agent-src/skills/laravel-middleware/SKILL.md +1 -0
- package/.agent-src/skills/laravel-notifications/SKILL.md +1 -0
- package/.agent-src/skills/laravel-pennant/SKILL.md +1 -0
- package/.agent-src/skills/laravel-pulse/SKILL.md +1 -0
- package/.agent-src/skills/laravel-reverb/SKILL.md +1 -0
- package/.agent-src/skills/laravel-scheduling/SKILL.md +1 -0
- package/.agent-src/skills/laravel-validation/SKILL.md +1 -0
- package/.agent-src/skills/launch-readiness/SKILL.md +156 -0
- package/.agent-src/skills/learning-to-rule-or-skill/SKILL.md +1 -0
- package/.agent-src/skills/lint-skills/SKILL.md +1 -0
- package/.agent-src/skills/livewire/SKILL.md +1 -0
- package/.agent-src/skills/livewire-architect/SKILL.md +158 -0
- package/.agent-src/skills/logging-monitoring/SKILL.md +1 -0
- package/.agent-src/skills/markitdown/SKILL.md +1 -0
- package/.agent-src/skills/mcp/SKILL.md +1 -0
- package/.agent-src/skills/mcp-builder/SKILL.md +1 -0
- package/.agent-src/skills/md-language-check/SKILL.md +1 -0
- package/.agent-src/skills/merge-conflicts/SKILL.md +1 -0
- package/.agent-src/skills/migration-architect/SKILL.md +119 -0
- package/.agent-src/skills/migration-creator/SKILL.md +1 -0
- package/.agent-src/skills/mobile-e2e-strategy/SKILL.md +2 -1
- package/.agent-src/skills/module-management/SKILL.md +1 -0
- package/.agent-src/skills/multi-tenancy/SKILL.md +1 -0
- package/.agent-src/skills/okr-tree-modeling/SKILL.md +1 -0
- package/.agent-src/skills/openapi/SKILL.md +1 -0
- package/.agent-src/skills/override-management/SKILL.md +1 -0
- package/.agent-src/skills/performance/SKILL.md +1 -0
- package/.agent-src/skills/performance-analysis/SKILL.md +1 -0
- package/.agent-src/skills/persona-writing/SKILL.md +1 -0
- package/.agent-src/skills/pest-testing/SKILL.md +1 -0
- package/.agent-src/skills/php-coder/SKILL.md +1 -0
- package/.agent-src/skills/php-debugging/SKILL.md +1 -0
- package/.agent-src/skills/php-service/SKILL.md +1 -0
- package/.agent-src/skills/playwright-architect/SKILL.md +141 -0
- package/.agent-src/skills/playwright-testing/SKILL.md +1 -0
- package/.agent-src/skills/po-discovery/SKILL.md +127 -0
- package/.agent-src/skills/project-analysis-core/SKILL.md +1 -0
- package/.agent-src/skills/project-analysis-hypothesis-driven/SKILL.md +1 -0
- package/.agent-src/skills/project-analysis-laravel/SKILL.md +1 -0
- package/.agent-src/skills/project-analysis-nextjs/SKILL.md +1 -0
- package/.agent-src/skills/project-analysis-node-express/SKILL.md +1 -0
- package/.agent-src/skills/project-analysis-react/SKILL.md +1 -0
- package/.agent-src/skills/project-analysis-symfony/SKILL.md +1 -0
- package/.agent-src/skills/project-analysis-zend-laminas/SKILL.md +1 -0
- package/.agent-src/skills/project-analyzer/SKILL.md +1 -0
- package/.agent-src/skills/project-docs/SKILL.md +1 -0
- package/.agent-src/skills/prompt-engineering-patterns/SKILL.md +1 -0
- package/.agent-src/skills/prompt-optimizer/SKILL.md +1 -0
- package/.agent-src/skills/quality-tools/SKILL.md +1 -0
- package/.agent-src/skills/react-native-setup/SKILL.md +1 -0
- package/.agent-src/skills/react-shadcn-ui/SKILL.md +1 -0
- package/.agent-src/skills/readme-reviewer/SKILL.md +1 -0
- package/.agent-src/skills/readme-writing/SKILL.md +1 -0
- package/.agent-src/skills/readme-writing-package/SKILL.md +1 -0
- package/.agent-src/skills/receiving-code-review/SKILL.md +1 -0
- package/.agent-src/skills/refine-prompt/SKILL.md +1 -0
- package/.agent-src/skills/refine-ticket/SKILL.md +1 -0
- package/.agent-src/skills/release-comms/SKILL.md +123 -0
- package/.agent-src/skills/repomix-packer/SKILL.md +1 -0
- package/.agent-src/skills/requesting-code-review/SKILL.md +1 -0
- package/.agent-src/skills/review-routing/SKILL.md +1 -0
- package/.agent-src/skills/rice-prioritization/SKILL.md +1 -0
- package/.agent-src/skills/risk-officer/SKILL.md +141 -0
- package/.agent-src/skills/roadmap-management/SKILL.md +1 -0
- package/.agent-src/skills/roadmap-writing/SKILL.md +2 -1
- package/.agent-src/skills/rtk-output-filtering/SKILL.md +1 -0
- package/.agent-src/skills/rule-writing/SKILL.md +1 -0
- package/.agent-src/skills/script-writing/SKILL.md +1 -0
- package/.agent-src/skills/secrets-management/SKILL.md +1 -0
- package/.agent-src/skills/security/SKILL.md +1 -0
- package/.agent-src/skills/security-audit/SKILL.md +1 -0
- package/.agent-src/skills/sentry-integration/SKILL.md +1 -0
- package/.agent-src/skills/sequential-thinking/SKILL.md +1 -0
- package/.agent-src/skills/skill-improvement-pipeline/SKILL.md +1 -0
- package/.agent-src/skills/skill-management/SKILL.md +1 -0
- package/.agent-src/skills/skill-reviewer/SKILL.md +1 -0
- package/.agent-src/skills/skill-writing/SKILL.md +1 -0
- package/.agent-src/skills/sql-writing/SKILL.md +1 -0
- package/.agent-src/skills/stakeholder-tradeoff/SKILL.md +237 -0
- package/.agent-src/skills/subagent-orchestration/SKILL.md +13 -0
- package/.agent-src/skills/systematic-debugging/SKILL.md +1 -0
- package/.agent-src/skills/tailwind-engineer/SKILL.md +130 -0
- package/.agent-src/skills/tech-debt-tracker/SKILL.md +152 -0
- package/.agent-src/skills/technical-specification/SKILL.md +1 -0
- package/.agent-src/skills/terraform/SKILL.md +1 -0
- package/.agent-src/skills/terragrunt/SKILL.md +1 -0
- package/.agent-src/skills/test-driven-development/SKILL.md +1 -0
- package/.agent-src/skills/test-performance/SKILL.md +1 -0
- package/.agent-src/skills/testing-anti-patterns/SKILL.md +1 -0
- package/.agent-src/skills/threat-modeling/SKILL.md +3 -0
- package/.agent-src/skills/token-optimizer/SKILL.md +1 -0
- package/.agent-src/skills/traefik/SKILL.md +1 -0
- package/.agent-src/skills/ui-component-architect/SKILL.md +153 -0
- package/.agent-src/skills/unit-economics-modeling/SKILL.md +1 -0
- package/.agent-src/skills/universal-project-analysis/SKILL.md +1 -0
- package/.agent-src/skills/upstream-contribute/SKILL.md +1 -0
- package/.agent-src/skills/using-git-worktrees/SKILL.md +1 -0
- package/.agent-src/skills/validate-feature-fit/SKILL.md +1 -0
- package/.agent-src/skills/verify-completion-evidence/SKILL.md +1 -0
- package/.agent-src/skills/voc-extract/SKILL.md +164 -0
- package/.agent-src/skills/websocket/SKILL.md +1 -0
- package/.agent-src/templates/roadmaps.md +9 -0
- package/.claude-plugin/marketplace.json +21 -1
- package/AGENTS.md +1 -0
- package/CHANGELOG.md +75 -0
- package/README.md +2 -2
- package/docs/architecture.md +2 -2
- package/docs/catalog.md +21 -4
- package/docs/contracts/context-spine.md +133 -0
- package/docs/contracts/file-ownership-matrix.json +616 -0
- package/docs/contracts/mental-models.md +336 -0
- package/docs/contracts/persona-schema.md +136 -0
- package/docs/contracts/skill-domains.md +143 -0
- package/docs/decisions/ADR-005-subagent-worktrees.md +120 -0
- package/docs/decisions/ADR-006-skill-tools-python-pilot.md +114 -0
- package/docs/decisions/INDEX.md +3 -0
- package/docs/guidelines/cross-role-handoff.md +127 -0
- package/docs/personas.md +115 -0
- package/package.json +1 -1
- package/scripts/_backfill_skill_domains.py +140 -0
- package/scripts/_emit_domain_table.py +35 -0
- package/scripts/install-hooks.sh +21 -4
- package/scripts/lint_context_spine_usage.py +133 -0
- package/scripts/lint_roadmap_complexity.py +37 -0
- package/scripts/lint_skill_tools.py +168 -0
- package/scripts/schemas/skill.schema.json +15 -1
- package/scripts/skill_linter.py +19 -4
- package/scripts/skill_tools/__init__.py +22 -0
- package/scripts/skill_tools/audit_persona_coverage.py +147 -0
- package/scripts/skill_tools/run_block_d_eval.py +129 -0
- package/scripts/skill_tools/score_skill_relevance.py +169 -0
- 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.
|
|
@@ -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-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-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: 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: 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-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
|
|
@@ -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.
|