@etus/bhono-app 0.1.1

package/templates/base/.claude/skills/linear/workflows/issue-lifecycle.md

@@ -0,0 +1,317 @@
+# Issue Lifecycle Workflow
+
+Complete workflow guide for managing Linear issues from triage to completion.
+
+## Status Lifecycle
+
+```
+┌─────────┐    ┌─────────┐    ┌───────────┐    ┌───────────┐    ┌───────────┐    ┌──────────┐
+│ Triage  │───▶│ Backlog │───▶│   Todo    │───▶│In Progress│───▶│ In Review │───▶│   Done   │
+└─────────┘    └─────────┘    └───────────┘    └───────────┘    └───────────┘    └──────────┘
+     │              │              │                │                 │                │
+     │              ▼              │                │                 │                │
+     │         ┌─────────┐        │                │                 │                │
+     │         │ Icebox  │        │                │                 │                │
+     │         └─────────┘        │                │                 │                │
+     ▼              ▼              ▼                ▼                 ▼                │
+┌────────────────────────────────────────────────────────────────────────────────┐    │
+│                              Canceled / Duplicate                               │◀───┘
+└────────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Workflow Stages
+
+### 1. Triage (type: `triage`)
+
+**When**: Issue is newly created and awaiting review.
+
+**Actions**:
+- Review issue description and requirements
+- Assess priority and effort
+- Assign to appropriate team/project
+- Move to Backlog or Todo
+
+### 2. Backlog (type: `backlog`)
+
+**When**: Issue is prioritized but not scheduled.
+
+**Actions**:
+- Refine requirements if needed
+- Estimate effort
+- Schedule for upcoming sprint/cycle
+
+### 2b. Icebox (type: `backlog`)
+
+**When**: Issue is valid but deferred indefinitely.
+
+**Actions**:
+- Add comment explaining why it's being iceboxed
+- Review periodically during planning sessions
+
+```bash
+ICEBOX=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "Icebox") | .id')
+npx tsx scripts/comments/create.ts ABC-123 "Moving to Icebox: Lower priority, will revisit in Q2" --json
+npx tsx scripts/status/update.ts ABC-123 "$ICEBOX" --json
+```
+
+### 3. Todo (type: `unstarted`)
+
+**When**: Issue is ready to be picked up.
+
+**Actions**:
+- Self-assign or get assigned
+- Review acceptance criteria
+- Prepare to start work
+
+### 4. In Progress (type: `started`)
+
+**When**: Actively working on the issue.
+
+**Actions required upon starting**:
+```bash
+cd .claude/skills/linear
+
+# Get current user
+ME=$(npx tsx scripts/users/me.ts --json | jq -r '.id')
+
+# Get "In Progress" state (use name for precision)
+STATES=$(npx tsx scripts/status/list.ts --json)
+IN_PROGRESS=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "In Progress") | .id')
+
+# Update issue
+npx tsx scripts/issues/update.ts --issue ABC-123 --assignee "$ME" --json
+npx tsx scripts/status/update.ts ABC-123 "$IN_PROGRESS" --json
+```
+
+### 5. In Review (type: `started`)
+
+**When**: Work is complete and awaiting review.
+
+**Actions**:
+- Code review requested
+- PR submitted
+- Awaiting approval
+
+```bash
+IN_REVIEW=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "In Review") | .id')
+npx tsx scripts/status/update.ts ABC-123 "$IN_REVIEW" --json
+```
+
+### 6. Done (type: `completed`)
+
+**When**: Work is complete and verified.
+
+**Actions required before marking done**:
+1. Verify all acceptance criteria met
+2. Check related issues
+3. Add completion documentation
+4. Update status
+
+## Completion Checklist
+
+Before marking ANY issue as Done, verify:
+
+- [ ] **Code complete**: All implementation finished
+- [ ] **Tests passing**: Unit/integration tests green
+- [ ] **Documentation**: Code comments where needed
+- [ ] **Related issues checked**: Parent, siblings, children reviewed
+- [ ] **Completion comment added**: Summary of changes
+
+## Completion Comment Template
+
+```markdown
+## Completion Summary
+
+**Status**: ✅ COMPLETED
+
+### Changes Made
+- `path/to/file.ts`: Brief description of changes
+- `path/to/another.ts`: Brief description of changes
+
+### Features Implemented
+- Feature 1: What it does
+- Feature 2: What it does
+
+### Testing
+- [ ] Unit tests added/updated
+- [ ] Manual testing completed
+- [ ] Edge cases verified
+
+### Next Steps (if any)
+- Follow-up task description
+- Configuration required
+- Related work to schedule
+
+### Related Issues
+- Parent: ABC-100 (if applicable)
+- Subtasks: ABC-101, ABC-102 (if applicable)
+```
+
+## Related Issue Management
+
+### Working on Subtasks
+
+When completing a subtask:
+
+1. **Update the subtask** with completion comment
+2. **Check sibling subtasks**: Are others complete?
+3. **Update parent issue**:
+   - If all subtasks done → Mark parent Done
+   - If partial → Update parent with progress comment
+
+```bash
+# Get parent issue details
+npx tsx scripts/issues/get.ts ABC-100 --json
+
+# Add progress comment to parent
+npx tsx scripts/comments/create.ts ABC-100 "Subtask ABC-101 completed. 2/3 subtasks done." --json
+```
+
+### Completing Parent Issues
+
+When all subtasks are complete:
+
+```bash
+# Add summary comment
+npx tsx scripts/comments/create.ts ABC-100 "$(cat <<'EOF'
+## All Subtasks Completed
+
+**Status**: ✅ COMPLETED
+
+### Completed Subtasks
+- ABC-101: Feature A implementation
+- ABC-102: Feature B implementation
+- ABC-103: Testing and documentation
+
+### Summary
+All acceptance criteria met. Feature ready for release.
+EOF
+)" --json
+
+# Update status
+DONE=$(npx tsx scripts/status/list.ts --json | jq -r '.statuses[] | select(.type == "completed") | .id' | head -1)
+npx tsx scripts/status/update.ts ABC-100 $DONE --json
+```
+
+## Documentation Quality Examples
+
+### Good Documentation
+
+```markdown
+## Completion Summary
+
+**Status**: ✅ COMPLETED
+
+### Changes Made
+- `src/auth/oauth.ts`: Implemented OAuth 2.1 PKCE flow with state validation
+- `src/auth/tokens.ts`: Added secure token storage with encryption
+- `tests/auth/oauth.test.ts`: 12 unit tests covering happy path and edge cases
+
+### Features Implemented
+- OAuth authorization with PKCE challenge
+- Automatic token refresh before expiry
+- Secure token storage in encrypted format
+- Error handling with user-friendly messages
+
+### Testing
+- [x] Unit tests (12 passing)
+- [x] Integration test with mock OAuth server
+- [x] Manual testing with Google OAuth
+
+### Configuration Required
+Set environment variables:
+- `OAUTH_CLIENT_ID`
+- `OAUTH_REDIRECT_URI`
+```
+
+### Poor Documentation
+
+```
+Done.
+```
+
+```
+Fixed the bug.
+```
+
+```
+Implemented feature.
+```
+
+**Why this matters**: Poor documentation creates confusion about what was delivered and makes it hard to debug issues later.
+
+## Edge Cases
+
+### Blocked Issues
+
+If an issue is blocked:
+
+1. Add comment explaining the blocker
+2. Create linked blocking issue if needed
+3. Keep status as In Progress or move to Backlog
+4. Do NOT mark as Done
+
+```bash
+npx tsx scripts/comments/create.ts ABC-123 "Blocked by: Need API credentials from external team. Created follow-up ABC-124." --json
+```
+
+### Reopened Issues
+
+If a completed issue needs more work:
+
+1. Move back to In Progress
+2. Add comment explaining why reopened
+3. Follow normal completion flow when done again
+
+### Canceled Issues
+
+When canceling:
+
+1. Add comment explaining why
+2. Move to Canceled status
+3. Update any parent issues
+
+```bash
+CANCELED=$(npx tsx scripts/status/list.ts --json | jq -r '.statuses[] | select(.type == "canceled") | .id' | head -1)
+npx tsx scripts/comments/create.ts ABC-123 "Canceled: Requirements changed, no longer needed." --json
+npx tsx scripts/status/update.ts ABC-123 $CANCELED --json
+```
+
+## Quick Reference Commands
+
+```bash
+cd .claude/skills/linear
+
+# Get statuses (run once, reuse $STATES)
+STATES=$(npx tsx scripts/status/list.ts --json)
+
+# Start work on issue
+ME=$(npx tsx scripts/users/me.ts --json | jq -r '.id')
+IN_PROGRESS=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "In Progress") | .id')
+npx tsx scripts/issues/update.ts --issue ABC-123 --assignee "$ME" --json
+npx tsx scripts/status/update.ts ABC-123 "$IN_PROGRESS" --json
+
+# Move to review
+IN_REVIEW=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "In Review") | .id')
+npx tsx scripts/status/update.ts ABC-123 "$IN_REVIEW" --json
+
+# Complete issue
+DONE=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "Done") | .id')
+npx tsx scripts/comments/create.ts ABC-123 "Completion summary here..." --json
+npx tsx scripts/status/update.ts ABC-123 "$DONE" --json
+
+# Move to icebox
+ICEBOX=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "Icebox") | .id')
+npx tsx scripts/comments/create.ts ABC-123 "Moving to Icebox: reason..." --json
+npx tsx scripts/status/update.ts ABC-123 "$ICEBOX" --json
+
+# Cancel issue
+CANCELED=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "Canceled") | .id')
+npx tsx scripts/comments/create.ts ABC-123 "Reason for cancellation..." --json
+npx tsx scripts/status/update.ts ABC-123 "$CANCELED" --json
+
+# Mark as duplicate
+DUPLICATE=$(echo "$STATES" | jq -r '.statuses[] | select(.name == "Duplicate") | .id')
+npx tsx scripts/comments/create.ts ABC-123 "Duplicate of ABC-100" --json
+npx tsx scripts/status/update.ts ABC-123 "$DUPLICATE" --json
+```

package/templates/base/.claude/skills/playwright-e2e-testing/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: playwright-e2e-testing
+description: Design, implement, debug, and optimize Playwright Test E2E/UI test suites (mobile emulation, traces/video, visual + a11y snapshots, API setup/auth, and CI sharding/reporting). Use when adding new Playwright tests, stabilizing flaky tests, improving execution speed, validating ad rendering/placement, or setting up Playwright in a repo.
+allowed-tools: Read, Write, Edit, MultiEdit, Grep, Glob, Bash
+---
+
+# Playwright E2E Testing
+
+You are an expert Playwright Test engineer. When this Skill is active, produce **production-grade, low-flake** E2E/UI tests and the supporting scaffolding (config, fixtures, helpers, CI) with **fast feedback** and **strong debugging artifacts**.
+
+## When to use this Skill
+
+Use this Skill when the user asks for:
+
+1. New Playwright E2E/UI tests or test architecture.
+2. Stabilizing flaky tests (timing, race conditions, non-determinism).
+3. Performance-focused testing (mobile realism, cache control, throttling, tracing).
+4. Visual verification (screenshots) and accessibility snapshots.
+5. CI pipelines (parallelism, sharding, report merging, artifacts).
+6. Testing ad behavior (e.g., GPT slots render/viewable timing, layout stability).
+
+## Non-negotiable rules (anti-flake defaults)
+
+1. **No arbitrary sleeps** (`waitForTimeout`) unless the user explicitly demands it (and then isolate it behind a helper + document why).
+2. Prefer **web-first assertions** (`expect(locator).toBeVisible()` etc.) over manual DOM reads.
+3. Prefer **user-facing locators** (`getByRole`, `getByLabel`, `getByText`) over brittle CSS.
+4. Make tests **idempotent** and **isolated**:
+   - New context per test unless intentionally reusing state.
+   - Avoid shared mutable state across tests; clean up created data.
+5. Make failures debuggable:
+   - Traces on retry, screenshots on failure, and videos on failure (or first retry).
+6. Use **progressive disclosure**:
+   - Keep SKILL.md guidance short.
+   - Pull details from `references/` only when needed.
+
+## Standard workflow (use this sequence)
+
+### 1) Intake and test design
+1. Identify the **user journey** (start state → actions → expected result).
+2. Choose the **test type**:
+   - E2E (full journey)
+   - UI regression (visual snapshots)
+   - a11y regression (ARIA snapshots)
+   - API + light UI (fast setup)
+   - Component testing (when UI can be tested without full app)
+3. Define the **acceptance checks**:
+   - UI state (text/role/visibility)
+   - Network behavior (requests fired, caching)
+   - Ads (slot rendered, viewable, no CLS spikes)
+
+### 2) Build scaffolding (only if missing)
+Use the templates in `templates/` to add quickly:
+- `templates/playwright.config.ts` (projects + artifacts + CI defaults)
+- `templates/global.setup.ts` (optional storageState)
+- `templates/fixtures.ts` (custom fixtures)
+- `templates/helpers/` (throttling, cache bypass, ad observers)
+- `templates/ci/` (GitHub Actions sharding + merged report)
+
+### 3) Implement tests
+1. Use **tags** (`@smoke`, `@critical`, `@ads`, `@mobile`, `@visual`) to create runnable subsets.
+2. Prefer **Page Objects** only where they reduce duplication (keep them small).
+3. Prefer **APIRequestContext** for setup (create users/data) and reuse `storageState` where appropriate.
+
+### 4) Run + debug
+Use Playwright’s strongest DX features:
+- UI Mode: `npx playwright test --ui`
+- Debug: `npx playwright test --debug`
+- Trace viewer: `npx playwright show-trace <trace.zip>`
+
+### 5) CI hardening
+1. Enable retries in CI only.
+2. Use **blob reporter** with sharding and merge reports into a single HTML report.
+3. Always upload HTML report + traces/videos as CI artifacts.
+
+## Included scripts
+
+1. `scripts/auth-setup.js`  
+   Creates `storageState` (auth) for reuse.
+
+2. `scripts/performance-analyzer.js`  
+   Analyzes Playwright JSON results to identify slow tests.
+
+3. `scripts/trace-url.js`  
+   Captures a Playwright trace (trace.zip) for a URL with optional mobile presets (cache disabled + optional throttle).
+
+## References (open only when needed)
+
+- `references/best-practices.md` — test philosophy, selectors, waiting
+- `references/patterns.md` — fixtures/POM/tagging, data strategies
+- `references/debugging.md` — traces, UI mode, inspector, CI triage
+- `references/optimization.md` — speed, parallelism, CI
+- `references/architecture.md` — scalable folder structure, responsibilities
+- `references/ci-reporting.md` — sharding + blob reports + merge-reports
+- `references/visual-a11y.md` — screenshots + ARIA snapshots + masking
+- `references/mobile-realism.md` — device emulation, cache/service workers, throttling
+- `references/resources.md` — curated official docs + recent high-signal blog posts
+
+## Example prompts (what the user can ask)
+
+1. “Add a @critical E2E test for the email deep link → page load → first ad slot renders.”
+2. “This test flakes in CI only; use traces to find the root cause and fix it.”
+3. “Set up Playwright with sharding and a merged HTML report in GitHub Actions.”
+4. “Create a visual regression suite for the main templates, masking ad slots.”
+5. “Simulate mid-tier mobile (throttled CPU/network) and report time to first ad viewable.”
+
+## Output requirements (how you respond)
+
+When implementing or updating tests, always provide:
+
+1. The **plan** (brief, 5–10 bullets).
+2. The **code changes** (files created/modified).
+3. The **commands to run** (local + CI).
+4. A **debug playbook** if the change introduces new moving parts.

package/templates/base/.claude/skills/playwright-e2e-testing/assets/global-setup.template.js

@@ -0,0 +1,97 @@
+import { chromium } from '@playwright/test';
+import { LoginPage } from './tests-config/pages/LoginPage';
+
+/**
+ * Global Setup Script
+ * 
+ * This script runs once before all tests.
+ * Use it for:
+ * - Creating authentication state
+ * - Seeding test data
+ * - Starting services
+ * - Database migrations
+ */
+
+async function globalSetup(config) {
+  console.log('Running global setup...');
+
+  // Setup authentication state
+  await setupAuthentication(config);
+
+  // Optional: Setup test data
+  // await setupTestData();
+
+  console.log('Global setup complete\n');
+}
+
+/**
+ * Setup authentication and save state
+ */
+async function setupAuthentication(config) {
+  console.log('🔐 Setting up authentication...');
+
+  const browser = await chromium.launch();
+  const context = await browser.newContext();
+  const page = await context.newPage();
+
+  try {
+    // Use your login page object
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+
+    // Login with test credentials
+    const email = process.env.TEST_EMAIL || 'test@example.com';
+    const password = process.env.TEST_PASSWORD || 'password123';
+
+    await loginPage.login(email, password);
+
+    // Verify login was successful
+    await page.waitForURL('**/dashboard', { timeout: 10000 });
+
+    // Save authentication state
+    await context.storageState({ path: 'auth.json' });
+
+    console.log('Authentication state saved to auth.json');
+
+  } catch (error) {
+    console.error('Authentication setup failed:', error.message);
+    throw error;
+  } finally {
+    await browser.close();
+  }
+}
+
+/**
+ * Optional: Setup test data
+ */
+async function setupTestData() {
+  console.log('📦 Setting up test data...');
+
+  // Example: Seed database with test data
+  try {
+    // Call your API or database to create test data
+    const response = await fetch('http://localhost:3000/api/seed', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        users: 10,
+        products: 50,
+        orders: 100
+      })
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to seed data: ${response.statusText}`);
+    }
+
+    console.log('Test data seeded successfully');
+
+  } catch (error) {
+    console.error('Test data setup failed:', error.message);
+    // Don't throw - continue with tests even if seeding fails
+  }
+}
+
+export default globalSetup;

package/templates/base/.claude/skills/playwright-e2e-testing/assets/playwright.config.template.js

@@ -0,0 +1,171 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Optimized Playwright Configuration Template
+ * 
+ * This configuration follows best practices for:
+ * - Fast execution
+ * - Reliable tests
+ * - Comprehensive reporting
+ * - CI/CD compatibility
+ */
+
+export default defineConfig({
+  // Test directory
+  testDir: './tests',
+  
+  // Run tests in parallel for speed
+  fullyParallel: true,
+  
+  // Fail the build on CI if you accidentally left test.only in source code
+  forbidOnly: !!process.env.CI,
+  
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+  
+  // Optimal worker configuration
+  // Use 50% of cores locally, 4 workers in CI
+  workers: process.env.CI ? 4 : '50%',
+  
+  // Reporter configuration
+  // HTML report locally, JUnit + HTML in CI
+  reporter: process.env.CI 
+    ? [
+        ['html', { open: 'never' }],
+        ['junit', { outputFile: 'test-results/junit.xml' }],
+        ['json', { outputFile: 'test-results/results.json' }]
+      ]
+    : [
+        ['html', { open: 'on-failure' }],
+        ['list']
+      ],
+
+  // Shared settings for all projects
+  use: {
+    // Base URL for all navigation
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    
+    // Collect trace only on first retry to save space
+    trace: 'on-first-retry',
+    
+    // Screenshots only on failure
+    screenshot: 'only-on-failure',
+    
+    // Video only on failure
+    video: 'retain-on-failure',
+    
+    // Run in headless mode in CI
+    headless: process.env.CI ? true : false,
+    
+    // Default viewport
+    viewport: { width: 1280, height: 720 },
+    
+    // Ignore HTTPS errors
+    ignoreHTTPSErrors: true,
+    
+    // Timeouts
+    navigationTimeout: 30000,
+    actionTimeout: 10000,
+  },
+
+  // Global timeout for each test
+  timeout: 30000,
+  
+  // Timeout for each assertion
+  expect: {
+    timeout: 5000,
+  },
+
+  // Configure projects for different browsers and scenarios
+  projects: [
+    // Setup project - runs first, creates auth state
+    {
+      name: 'setup',
+      testMatch: /.*\.setup\.js/,
+    },
+
+    // Chromium - main browser for most tests
+    {
+      name: 'chromium',
+      use: { 
+        ...devices['Desktop Chrome'],
+        // Use saved authentication state
+        storageState: 'auth.json',
+      },
+      dependencies: ['setup'],
+    },
+
+    // Firefox - run critical tests only
+    {
+      name: 'firefox',
+      use: { 
+        ...devices['Desktop Firefox'],
+        storageState: 'auth.json',
+      },
+      testMatch: /.*\.critical\.spec\.js/,
+      dependencies: ['setup'],
+    },
+
+    // WebKit - run critical tests only
+    {
+      name: 'webkit',
+      use: { 
+        ...devices['Desktop Safari'],
+        storageState: 'auth.json',
+      },
+      testMatch: /.*\.critical\.spec\.js/,
+      dependencies: ['setup'],
+    },
+
+    // Mobile Chrome
+    {
+      name: 'mobile-chrome',
+      use: { 
+        ...devices['Pixel 5'],
+        storageState: 'auth.json',
+      },
+      testMatch: /.*\.mobile\.spec\.js/,
+      dependencies: ['setup'],
+    },
+
+    // Mobile Safari
+    {
+      name: 'mobile-safari',
+      use: { 
+        ...devices['iPhone 13'],
+        storageState: 'auth.json',
+      },
+      testMatch: /.*\.mobile\.spec\.js/,
+      dependencies: ['setup'],
+    },
+
+    // API testing project
+    {
+      name: 'api',
+      testMatch: /api\/.*\.spec\.js/,
+      use: {
+        baseURL: process.env.API_URL || 'http://localhost:3001/api',
+      },
+    },
+  ],
+
+  // Web Server configuration (optional)
+  // Uncomment if you want Playwright to start your dev server
+  /*
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+    stdout: 'ignore',
+    stderr: 'pipe',
+  },
+  */
+
+  // Global Setup and Teardown (optional)
+  // Uncomment to use global setup/teardown scripts
+  /*
+  globalSetup: require.resolve('./tests-config/global-setup'),
+  globalTeardown: require.resolve('./tests-config/global-teardown'),
+  */
+});