@c0x12c/ai-toolkit 1.15.0

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: brainstorm
+description: Run a structured brainstorm session for startup ideas. Takes a theme or problem and generates ideas with quick gut-checks. Use when the user wants to explore a space or generate new ideas.
+allowed_tools:
+  - WebSearch
+---
+
+# Brainstorm
+
+Turn a vague direction into a list of concrete ideas worth testing.
+
+## When to Use
+
+- User has a theme, problem, or space they want to explore
+- Generating new project ideas
+- Expanding on a half-baked idea
+- Looking for adjacent opportunities
+
+## Process
+
+### 1. Set the Frame
+Ask or confirm:
+- What space? (health, finance, dev tools, etc.)
+- Who's the user? (founders, students, parents, etc.)
+- Any limits? (no hardware, must be B2B, etc.)
+- What's the goal? (side project, VC-backed, bootstrap)
+
+### 2. Generate Ideas (Go Wide)
+Produce 8-15 ideas. For each:
+- **Name** - Working title
+- **One-liner** - What it does in 10 words
+- **Who** - Target user
+- **Problem** - What pain it fixes
+- **Why now** - Why this didn't work before
+- **Quick risk** - Biggest thing that could kill it
+
+### 3. Gut-Check Filter
+Rate each idea on:
+- Demand signal (0-5): Are people searching for this? Paying for alternatives?
+- Buildability (0-5): Can you build an MVP in 2 weeks?
+- Moat potential (0-5): Can you defend this?
+
+### 4. Pick Top 3
+Pick the 3 best ideas. For each, write:
+- The key bet (what must be true for this to work)
+- First validation step (cheapest way to test)
+- Existing competitors (who's doing something close)
+
+## Interaction Style
+
+**No BS. Honest feedback only.**
+
+This is a two-way talk:
+- I ask you questions → you answer
+- You ask me questions → I think hard, give you options, then answer
+
+**When I ask you a question, I always:**
+1. Think about it first
+2. Give you 2-3 options with my honest take on each
+3. Tell you which one I'd pick and why
+4. Then ask what you think
+
+**When you ask me something:**
+- I give you a straight answer
+- I tell you what's wrong with your thinking if I see it
+- I push back if your idea is weak
+
+**Never:**
+- Ask a question without giving options
+- Sugarcoat bad ideas
+- Say "it depends" without picking a side
+- Give soft answers to hard questions
+- Skip the tough feedback to be nice
+
+## Rules
+
+- No idea is too dumb during generation
+- But be brutal during filtering
+- "Interesting" is not enough. Need a real pain point.
+- If the user already has a direction, skip to expanding that
+- Don't fall in love with clever solutions to fake problems
+
+## Gotchas
+
+- **Don't brainstorm solutions — brainstorm problems.** Founders jump to features too fast. Force "what pain?" before "what product?"
+- **"Interesting" ≠ real demand.** If you can't find anyone searching for it, paying for alternatives, or complaining online, the problem might be fake.
+- **Avoid clever-founder bias.** Technical founders fall in love with clever solutions to problems nobody has. Test the problem first.
+- **Don't skip "Why now?"** Every good idea needs a timing argument. If this could've been built 5 years ago and nobody did, ask why.
+- **Too many ideas = no decision.** If you generate 15 ideas and can't pick 3, the frame is too broad. Narrow the space.
+
+## Output
+
+Save to the project's `01-brainstorm/` folder.
+
+After delivering, suggest: "Want me to run /validate on any of these?"

package/skills/browser-qa/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: browser-qa
+description: "Run real browser QA with Playwright. Use when testing a frontend feature, verifying UI before PR, smoke testing after deploy, or investigating reported visual bugs."
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+---
+
+# Browser QA Skill
+
+Test web apps with a real browser. Find bugs users would find.
+
+## When to Use
+
+- After building a frontend feature
+- Before creating a PR for UI changes
+- When user reports "something looks broken"
+- Smoke testing after deploy
+
+## What This Skill Does
+
+1. Launches Playwright with real Chromium
+2. Hits every discoverable page in the app
+3. Checks for console errors, network failures, broken assets
+4. Tests interactive elements (forms, buttons, links)
+5. Verifies mobile responsiveness
+6. Produces a structured QA report
+
+## QA Check Categories
+
+### 1. Page Health
+Every page gets these checks:
+- HTTP status is 2xx
+- No JavaScript console errors
+- No failed network requests (4xx/5xx)
+- No missing images or assets
+- Page loads in under 3 seconds
+
+### 2. Layout & Responsive
+- Desktop (1280px): no horizontal scroll, no overlapping elements
+- Mobile (375px): no horizontal scroll, text is readable, buttons are tappable
+- No content clipped or hidden unintentionally
+
+### 3. Interactive Elements
+- Buttons: click → something happens (no dead buttons)
+- Links: click → navigates to valid page (no 404s)
+- Forms: submit empty → validation shows. Submit valid → success feedback.
+- Dropdowns/modals: open → content visible. Close → content hidden.
+
+### 4. Navigation Flow
+- Every link in nav goes somewhere valid
+- Back button works as expected
+- Breadcrumbs (if present) are accurate
+- Auth redirects work (protected page → login → redirect back)
+
+### 5. Data Display
+- Lists show data (not empty state when data exists)
+- Pagination works (if present)
+- Search/filter updates results
+- Loading states show during data fetch
+- Error states show when API fails
+
+## Playwright Patterns & Report Template
+
+> See playwright-snippets.md for ready-to-use Playwright code (page tests, mobile viewport, form testing, screenshot on failure) and the QA report template.
+
+## Gotchas
+
+- **`networkidle` waits forever on apps with websockets or polling.** Use `domcontentloaded` or a specific element selector instead if the app has live connections.
+- **`page.click()` on invisible elements passes silently.** Always verify the element is visible before interacting. Use `await expect(locator).toBeVisible()` first.
+- **Mobile viewport test without touch simulation misses real bugs.** Set `hasTouch: true` in the browser context, not just the viewport size.
+- **Console warnings are not console errors.** Don't report React hydration warnings or deprecation notices as bugs. Only `console.error` and failed network requests are bugs.
+- **Screenshots on CI look different than local.** Font rendering, antialiasing, and DPI differ between macOS and Linux. Use visual comparison thresholds, not pixel-perfect matching.
+
+## Rules
+
+- **Real browser only.** Playwright + Chromium. No HTTP-only testing.
+- **Headless by default.** Don't open visible windows unless asked.
+- **Test both viewports.** Desktop (1280px) and mobile (375px).
+- **Console errors = bugs.** Always report them.
+- **One-shot mode.** Launch browser, test, close. No daemon.
+- **Screenshot failures.** Take a screenshot when something breaks.
+- **Don't fix without asking.** Report first, then offer fixes.

package/skills/browser-qa/playwright-snippets.md

@@ -0,0 +1,110 @@
+# Playwright QA — Code Snippets
+
+> This file is referenced by SKILL.md. Read it when writing QA scripts or generating reports.
+
+## Basic Page Test
+
+```typescript
+import { chromium } from 'playwright'
+
+const browser = await chromium.launch({ headless: true })
+const page = await browser.newPage()
+
+// Collect errors
+const errors: string[] = []
+page.on('console', msg => {
+  if (msg.type() === 'error') errors.push(msg.text())
+})
+page.on('requestfailed', req => {
+  errors.push(`NETWORK: ${req.url()} — ${req.failure()?.errorText}`)
+})
+
+await page.goto('http://localhost:3000')
+await page.waitForLoadState('networkidle')
+
+// Check for errors
+if (errors.length > 0) {
+  console.log('BUGS FOUND:', errors)
+}
+
+await browser.close()
+```
+
+## Mobile Viewport Test
+
+```typescript
+const context = await browser.newContext({
+  viewport: { width: 375, height: 812 },
+  userAgent: 'Mozilla/5.0 (iPhone 14)',
+})
+const page = await context.newPage()
+await page.goto('http://localhost:3000')
+
+// Check for horizontal scroll (layout bug)
+const hasHScroll = await page.evaluate(() =>
+  document.documentElement.scrollWidth > document.documentElement.clientWidth
+)
+if (hasHScroll) {
+  console.log('BUG: Horizontal scroll on mobile')
+}
+```
+
+## Form Test
+
+```typescript
+// Test empty submit (should show validation)
+await page.click('button[type="submit"]')
+const validationVisible = await page.locator('.error, [role="alert"]').count()
+
+// Test valid submit
+await page.fill('input[name="email"]', 'test@example.com')
+await page.fill('input[name="password"]', 'password123')
+await page.click('button[type="submit"]')
+await page.waitForURL('**/dashboard')
+```
+
+## Screenshot on Failure
+
+```typescript
+try {
+  await page.goto(url)
+  // ... checks ...
+} catch (e) {
+  await page.screenshot({ path: `qa-failure-${Date.now()}.png`, fullPage: true })
+  throw e
+}
+```
+
+## QA Report Template
+
+```markdown
+## QA Report
+Date: YYYY-MM-DD
+Target: http://localhost:3000
+
+### Summary
+| Metric | Count |
+|--------|-------|
+| Pages tested | N |
+| Bugs found | N |
+| Warnings | N |
+| Passed | N |
+
+### Bugs
+BUG-1: [title]
+- Page: [URL]
+- Steps: [reproduce]
+- Expected: [what should happen]
+- Actual: [what happened]
+- Severity: blocker / major / minor
+- Auto-fixable: yes / no
+
+### Warnings
+WARN-1: [title]
+- Page: [URL]
+- Issue: [description]
+
+### Passed
+- /page-a — all checks clear
+- /page-b — all checks clear
+```

package/skills/ci-cd-patterns/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: ci-cd-patterns
+description: "CI/CD pipeline patterns for GitHub Actions, PR automation, and deployment workflows. Use when setting up CI, fixing broken pipelines, automating PR checks, or configuring deployment."
+allowed_tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+---
+
+# CI/CD Patterns
+
+Patterns for GitHub Actions, PR automation, and deployment workflows.
+
+## When to Use
+
+- Setting up or fixing GitHub Actions workflows
+- Automating PR checks (lint, test, build)
+- Configuring deployment pipelines
+- Monitoring PR status and retrying flaky CI
+- Setting up multi-environment deployment (dev, staging, prod)
+
+## GitHub Actions --- Common Patterns
+
+### Basic CI Workflow
+```yaml
+name: CI
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests
+        run: ./gradlew test
+```
+
+### PR Check Workflow
+```yaml
+name: PR Check
+on: pull_request
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./gradlew ktlintCheck
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./gradlew test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - run: ./gradlew build
+```
+
+## PR Babysitting Pattern
+
+Monitor a PR through CI, handle common failures:
+
+1. **Check CI status** --- `gh pr checks <number>`
+2. **Identify failure type** --- flaky test, lint error, build failure
+3. **Fix and push** --- for lint/build errors, fix locally and push
+4. **Retry flaky tests** --- re-run the workflow: `gh run rerun <run-id> --failed`
+5. **Resolve merge conflicts** --- rebase onto target branch
+6. **Enable auto-merge** --- `gh pr merge <number> --auto --squash`
+
+> See `workflows.md` for ready-to-use GitHub Actions YAML templates.
+
+## Deployment Checklist
+
+Before deploying:
+- [ ] All CI checks pass
+- [ ] No merge conflicts
+- [ ] Database migrations reviewed (if any)
+- [ ] Environment variables set in target environment
+- [ ] Rollback plan identified
+
+## Gotchas
+
+- **Caching saves minutes per run.** Always cache dependencies (`actions/cache` or `actions/setup-java` with cache). A cold Gradle build takes 3-5 minutes, cached takes 30 seconds.
+- **`needs:` creates sequential dependencies.** Without it, all jobs run in parallel. Use `needs: [lint, test]` to make build wait for checks.
+- **Secret names are case-sensitive.** `secrets.DB_PASSWORD` and `secrets.db_password` are different. Match the exact name from Settings > Secrets.
+- **Don't use `actions/checkout@v3` --- use `v4`.** v3 uses Node 16 which is deprecated. v4 uses Node 20.
+- **Flaky tests need investigation, not just retry.** If you re-run a workflow more than twice for the same test, fix the test. Common causes: race conditions, time-dependent assertions, shared test state.
+- **Force-pushing during CI review resets the check suite.** Wait for CI to finish before force-pushing, or you'll waste runner minutes.
+
+## Rules
+
+- Every PR must pass CI before merge
+- Don't skip CI checks (`[skip ci]`) unless it's docs-only
+- Keep workflows under 10 minutes total
+- Use matrix builds for multi-version testing
+- Store secrets in GitHub Secrets, never in code

package/skills/ci-cd-patterns/workflows.md

@@ -0,0 +1,149 @@
+# CI/CD --- Workflow Templates
+
+> This file is referenced by SKILL.md. Read it when setting up specific GitHub Actions workflows.
+
+## Kotlin/Micronaut --- Full CI
+
+```yaml
+name: CI
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main, develop]
+
+env:
+  JAVA_VERSION: '17'
+  GRADLE_OPTS: '-Dorg.gradle.daemon=false'
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ env.JAVA_VERSION }}
+          cache: gradle
+      - run: ./gradlew ktlintCheck
+
+  test:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_DB: test_db
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+        ports: ['5432:5432']
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ env.JAVA_VERSION }}
+          cache: gradle
+      - run: ./gradlew test
+        env:
+          DB_HOST: localhost
+          DB_PORT: 5432
+          DB_NAME: test_db
+          DB_USER: test
+          DB_PASSWORD: test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: ${{ env.JAVA_VERSION }}
+          cache: gradle
+      - run: ./gradlew build -x test
+```
+
+## Next.js --- Full CI
+
+```yaml
+name: Frontend CI
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+      - run: yarn install --frozen-lockfile
+      - run: yarn lint
+      - run: yarn type-check
+      - run: yarn build
+      - run: yarn test --ci
+```
+
+## Docker Build + Push
+
+```yaml
+name: Docker
+on:
+  push:
+    branches: [main]
+
+jobs:
+  build-push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+```
+
+## Auto-merge Dependabot PRs
+
+```yaml
+name: Auto-merge Dependabot
+on: pull_request
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: dependabot/fetch-metadata@v2
+        id: metadata
+      - if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```

package/skills/competitive-teardown/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: competitive-teardown
+description: Deep competitor analysis. Tear apart a specific competitor or compare multiple competitors. Use when the user names a competitor or asks "who else is doing this?"
+allowed_tools:
+  - WebSearch
+  - WebFetch
+  - Read
+---
+
+# Competitive Teardown
+
+Study competitors like you're planning to beat them.
+
+## When to Use
+
+- User names a specific competitor
+- "Who else is doing this?"
+- Before building, to find gaps
+- Preparing for investor "competition slide"
+
+> See `example-analysis.md` for a filled-in competitor teardown showing the format and depth expected.
+
+## Single Competitor Teardown
+
+### Product
+- What do they actually do? (use the product, not just the landing page)
+- Key features
+- What's good about it
+- What sucks (check 1-star reviews on App Store, G2, Reddit)
+- Pricing tiers
+
+### Business
+- Funding (Crunchbase, PitchBook)
+- Revenue if known (press, SimilarWeb traffic guesses)
+- Team size (LinkedIn)
+- Founded when
+- Growth signals (hiring? launching new features? going quiet?)
+
+### Users
+- Who uses it? (check case studies, reviews, social mentions)
+- How do they get users? (SEO, ads, viral, sales team)
+- Community size (Discord, Reddit, Twitter followers)
+- NPS or satisfaction signals
+
+### Weaknesses
+- Negative reviews (patterns, not one-offs)
+- Missing features users ask for
+- Pricing complaints
+- Technical limitations
+- Support complaints
+
+## Multi-Competitor Comparison
+
+Create a table:
+
+| | Competitor A | Competitor B | Competitor C | Us (planned) |
+|---|---|---|---|---|
+| One-liner | | | | |
+| Target user | | | | |
+| Key feature | | | | |
+| Pricing | | | | |
+| Funding | | | | |
+| Weakness | | | | |
+| Our advantage | | | | |
+
+## Find the Gap
+
+After analysis, answer:
+- Where are ALL competitors weak?
+- What do users want that nobody does well?
+- Is there an underserved segment?
+- What positioning would make us different?
+
+## Rules
+
+- Use the product. Don't just read the landing page.
+- Check reviews on multiple platforms
+- Look for patterns in complaints, not single reviews
+- Be fair. Give credit where it's due.
+- If a competitor is way ahead, say so. Don't hide it.
+
+## Gotchas
+
+- **Don't just read the landing page.** Sign up for free trials. Watch demo videos. Read user forums. The landing page is marketing, not the product.
+- **One-star reviews are gold, but look for patterns.** A single angry review means nothing. Ten people saying the same thing is a signal.
+- **Funding ≠ success.** A competitor with $50M raised and no revenue is weaker than one with $2M raised and growing 20% monthly.
+- **Don't confuse features with moat.** A feature can be copied in a sprint. Distribution, data, and network effects can't.
+- **Check if they're growing or coasting.** Recent job postings, new features, blog activity — these signal momentum. Silence signals trouble.
+
+## Output
+
+Save to the project's `02-research/` folder.
+Use the template from `templates/competitor-analysis.md` if it fits.

package/skills/competitive-teardown/example-analysis.md

@@ -0,0 +1,50 @@
+# Competitive Teardown — Example Analysis
+
+> This file is referenced by SKILL.md. Use this format when producing a competitor teardown.
+
+## Example: Project Management Tool Teardown
+
+### Linear
+
+**Product**
+- Task tracking with keyboard-first UX, built for dev teams
+- Key features: cycles, roadmaps, triage, GitHub/GitLab integration
+- Strengths: incredibly fast UI, opinionated workflow, developer-loved
+- Weaknesses: no time tracking, limited reporting, no resource management
+- Pricing: $8/user/mo (Standard), $14/user/mo (Plus)
+
+**Business**
+- Founded: 2019, San Francisco
+- Funding: $52M Series B (2021), valued ~$400M
+- Team: ~80 employees (LinkedIn estimate)
+- Growth signals: active hiring (8 open roles), weekly changelog updates, active Discord (15K+ members)
+
+**Users**
+- Primary: engineering teams at startups and mid-size companies
+- Acquisition: word-of-mouth, developer communities, Twitter/X
+- Community: Discord (15K), Twitter (50K followers)
+- Sentiment: very positive on Reddit/HN, main complaint is "too opinionated"
+
+**Weaknesses (from 1-star reviews)**
+- "Can't customize workflow beyond their model" (repeated 12x on G2)
+- "No time tracking means we need a second tool" (repeated 8x)
+- "Reporting is basic — can't build custom dashboards"
+- "Mobile app is an afterthought"
+
+---
+
+### Comparison Table
+
+| | Linear | Jira | Shortcut | Our Product |
+|---|---|---|---|---|
+| One-liner | Fast PM for devs | Enterprise PM | Balanced PM for teams | [TBD] |
+| Target user | Dev teams 10-200 | Enterprise 500+ | Teams 20-500 | [TBD] |
+| Key strength | Speed + UX | Customization | Balance | [TBD] |
+| Pricing | $8-14/user | $0-15/user | $8.50/user | [TBD] |
+| Funding | $52M | Public (Atlassian) | $62M | [TBD] |
+| Main weakness | Too opinionated | Too complex | No standout feature | [TBD] |
+| Our advantage | [what we'd do better] | [what we'd do better] | [what we'd do better] | — |
+
+### The Gap
+
+All three competitors are weak on: **real-time collaboration during planning sessions.** Nobody does live sprint planning well. Linear is closest but it's still turn-based. This is our angle.