@bugzy-ai/bugzy 1.2.0

package/dist/templates/init/.bugzy/runtime/testing-best-practices.md

@@ -0,0 +1,278 @@
+# Testing Best Practices Reference
+
+## Page Object Model (POM) Architecture
+
+**Core Principle**: Separate locators, actions, and assertions into distinct layers to isolate UI changes from test logic.
+
+### Page Object Structure
+
+```typescript
+import { type Page, type Locator } from '@playwright/test';
+
+export class LoginPage {
+  readonly page: Page;
+
+  // Centralized selectors as readonly properties
+  readonly emailInput: Locator;
+  readonly passwordInput: Locator;
+  readonly loginButton: Locator;
+
+  constructor(page: Page) {
+    this.page = page;
+    this.emailInput = page.getByLabel('Email');
+    this.passwordInput = page.getByLabel('Password');
+    this.loginButton = page.getByRole('button', { name: 'Sign In' });
+  }
+
+  async navigate(): Promise<void> {
+    await this.page.goto('/login');
+  }
+
+  async login(email: string, password: string): Promise<void> {
+    await this.emailInput.fill(email);
+    await this.passwordInput.fill(password);
+    await this.loginButton.click();
+  }
+}
+```
+
+### Key Rules for Page Objects
+
+- ✅ Define all locators as `readonly` properties
+- ✅ Initialize locators in constructor
+- ✅ Use method names that describe actions (login, fillEmail, clickSubmit)
+- ✅ Return data, never assert in page objects
+- ❌ Never put `expect()` assertions in page objects
+- ❌ Never use hardcoded waits (`waitForTimeout`)
+
+## Selector Priority (Most to Least Resilient)
+
+1. **Role-based**: `page.getByRole('button', { name: 'Submit' })` - Best for semantic HTML
+2. **Label**: `page.getByLabel('Email')` - Perfect for form inputs
+3. **Text**: `page.getByText('Welcome back')` - Good for headings/static content
+4. **Placeholder**: `page.getByPlaceholder('Enter email')` - Inputs without labels
+5. **Test ID**: `page.getByTestId('submit-btn')` - Stable but requires data-testid attributes
+6. **CSS selectors**: `page.locator('.btn-primary')` - Avoid; breaks with styling changes
+
+### When to Use Test IDs
+
+Add `data-testid` attributes for:
+- Critical user flows (checkout, login, signup)
+- Complex components (data tables, multi-step forms)
+- Elements where role-based selectors are ambiguous
+
+```html
+<button data-testid="checkout-submit">Complete Purchase</button>
+```
+
+```typescript
+await page.getByTestId('checkout-submit').click();
+```
+
+## Test Organization
+
+### File Structure by Feature
+
+```
+tests/
+├── specs/              # Tests organized by feature
+│   ├── auth/
+│   │   └── login.spec.ts
+│   └── checkout/
+│       └── purchase-flow.spec.ts
+├── pages/              # Page Object Models
+│   ├── LoginPage.ts
+│   └── CheckoutPage.ts
+├── components/         # Reusable UI components
+├── fixtures/           # Custom test fixtures
+├── helpers/            # Utility functions
+└── setup/              # Global setup/teardown
+```
+
+### Test Structure
+
+```typescript
+test.describe('Purchase flow', () => {
+  test.beforeEach(async ({ page }) => {
+    // Common setup
+  });
+
+  test('should complete purchase with credit card', async ({ page }) => {
+    // Arrange: Set up page objects
+    const checkoutPage = new CheckoutPage(page);
+
+    // Act: Perform actions
+    await checkoutPage.fillPaymentInfo({/*...*/});
+    await checkoutPage.submitOrder();
+
+    // Assert: Verify outcomes
+    await expect(page).toHaveURL('/confirmation');
+  });
+});
+```
+
+## Authentication & Session Management
+
+**Always authenticate once and reuse session state** across tests.
+
+```typescript
+// tests/setup/auth.setup.ts
+import { test as setup } from '@playwright/test';
+
+const authFile = 'playwright/.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill(process.env.USER_EMAIL!);
+  await page.getByLabel('Password').fill(process.env.USER_PASSWORD!);
+  await page.getByRole('button', { name: 'Sign in' }).click();
+
+  await page.waitForURL('/dashboard');
+  await page.context().storageState({ path: authFile });
+});
+```
+
+Configure in `playwright.config.ts`:
+
+```typescript
+projects: [
+  { name: 'setup', testMatch: /.*\.setup\.ts/ },
+  {
+    name: 'chromium',
+    use: { storageState: 'playwright/.auth/user.json' },
+    dependencies: ['setup'],
+  },
+]
+```
+
+## Async Operations & Waiting
+
+### Use Built-in Auto-waiting
+
+Playwright automatically waits for elements to be:
+- Visible
+- Enabled
+- Stable (not animating)
+- Ready to receive events
+
+```typescript
+// ✅ GOOD: Auto-waiting
+await page.click('#submit');
+await expect(page.locator('.result')).toBeVisible();
+
+// ❌ BAD: Manual arbitrary wait
+await page.click('#submit');
+await page.waitForTimeout(3000);
+```
+
+### Explicit Waiting (when needed)
+
+```typescript
+// Wait for element state
+await page.locator('.loading').waitFor({ state: 'hidden' });
+
+// Wait for URL change
+await page.waitForURL('**/dashboard');
+
+// Wait for network request
+const response = await page.waitForResponse(
+  resp => resp.url().includes('/api/data') && resp.status() === 200
+);
+```
+
+## Common Anti-Patterns to Avoid
+
+| ❌ Anti-Pattern | ✅ Correct Approach |
+|----------------|-------------------|
+| `await page.waitForTimeout(3000)` | `await expect(element).toBeVisible()` |
+| `const el = await page.$('.btn')` | `await page.locator('.btn').click()` |
+| Tests depend on execution order | Each test is fully independent |
+| Assertions in Page Objects | Assertions only in test files |
+| `#app > div:nth-child(2) > button` | `page.getByRole('button', { name: 'Submit' })` |
+| `retries: 5` to mask flakiness | `retries: 2` + fix root cause |
+
+## Debugging Workflow
+
+When a test fails:
+
+1. **Reproduce locally**: `npx playwright test failing-test.spec.ts --headed`
+2. **Enable trace**: `npx playwright test --trace on`
+3. **View trace**: `npx playwright show-trace test-results/.../trace.zip`
+4. **Identify failure**: Scrub timeline, check DOM snapshots
+5. **Review network**: Look for failed API calls
+6. **Check console**: JavaScript errors/warnings
+7. **Fix selector**: Use inspector's locator picker
+8. **Verify fix**: Run test 10 times to ensure stability
+
+## API Testing for Speed
+
+**Use API calls for test setup** (10-20x faster than UI):
+
+```typescript
+test('should display user dashboard', async ({ request, page }) => {
+  // FAST: Create test data via API
+  await request.post('/api/users', {
+    data: { name: 'Test User', email: 'test@example.com' }
+  });
+
+  // UI: Test the actual user experience
+  await page.goto('/dashboard');
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+## Configuration Essentials
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  testDir: './tests/specs',
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+
+  timeout: 30000,
+  expect: { timeout: 5000 },
+
+  use: {
+    baseURL: process.env.BASE_URL,
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    actionTimeout: 10000,
+  },
+});
+```
+
+## Production-Ready Checklist
+
+**Configuration:**
+- [ ] Parallel execution enabled (`fullyParallel: true`)
+- [ ] Retry strategy configured (2 in CI, 0 locally)
+- [ ] Base URL from environment variables
+- [ ] Artifact capture optimized (`on-first-retry`)
+
+**Architecture:**
+- [ ] Page Object Model for all major pages
+- [ ] Component Objects for reusable UI elements
+- [ ] Custom fixtures for common setup
+- [ ] Tests organized by feature/user journey
+
+**Best Practices:**
+- [ ] No `waitForTimeout()` usage
+- [ ] Tests are independent (run in any order)
+- [ ] Assertions in test files, not Page Objects
+- [ ] Role-based selectors prioritized
+- [ ] No hardcoded credentials
+
+**CI/CD:**
+- [ ] Tests run on every pull request
+- [ ] Artifacts uploaded (reports, traces)
+- [ ] Failure notifications configured
+
+---
+
+**Remember**: The three critical pillars are:
+1. **Page Object Model** - Isolate UI changes from test logic
+2. **Role-based selectors** - Resist breakage
+3. **Authentication state reuse** - Maximize speed

package/dist/templates/init/.gitignore-template

@@ -0,0 +1,4 @@
+
+# Bugzy
+.env
+.env.local

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@bugzy-ai/bugzy",
+  "version": "1.2.0",
+  "description": "Open-source AI agent configuration for QA automation with Claude Code",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "ai",
+    "testing",
+    "qa",
+    "automation",
+    "claude",
+    "mcp",
+    "agent",
+    "test-automation",
+    "claude-code"
+  ],
+  "homepage": "https://github.com/bugzy-ai/bugzy#readme",
+  "bugs": {
+    "url": "https://github.com/bugzy-ai/bugzy/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bugzy-ai/bugzy.git"
+  },
+  "license": "MIT",
+  "author": "Bugzy Team",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./tasks": {
+      "types": "./dist/tasks/index.d.ts",
+      "import": "./dist/tasks/index.js"
+    },
+    "./subagents": {
+      "types": "./dist/subagents/index.d.ts",
+      "import": "./dist/subagents/index.js"
+    },
+    "./subagents/metadata": {
+      "types": "./dist/subagents/metadata.d.ts",
+      "import": "./dist/subagents/metadata.js"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "bugzy": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:ci": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build && pnpm run test:ci"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "dotenv": "^16.3.1",
+    "figlet": "^1.9.3",
+    "gradient-string": "^3.0.0",
+    "inquirer": "^9.2.12",
+    "ora": "^7.0.1"
+  },
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/gradient-string": "^1.1.6",
+    "@types/inquirer": "^9.0.7",
+    "@types/node": "^20.10.5",
+    "@typescript-eslint/eslint-plugin": "^6.15.0",
+    "@typescript-eslint/parser": "^6.15.0",
+    "eslint": "^8.56.0",
+    "gray-matter": "^4.0.3",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.1.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/init/.bugzy/runtime/knowledge-base.md

@@ -0,0 +1,61 @@
+# Knowledge Base
+
+> A curated collection of factual knowledge about this project - what we currently know and believe to be true. This is NOT a historical log, but a living reference that evolves as understanding improves.
+
+**Maintenance Guide**: See `knowledge-maintenance-guide.md` for instructions on how to maintain this knowledge base.
+
+**Core Principle**: This document represents current understanding, not a history. When knowledge evolves, update existing entries rather than appending new ones.
+
+---
+
+## Project Knowledge
+
+_This knowledge base will be populated as you work. Add new discoveries, update existing understanding, and remove outdated information following the maintenance guide principles._
+
+### When to Update This File
+
+- **ADD**: New factual information discovered, new patterns emerge, new areas become relevant
+- **UPDATE**: Facts change, understanding deepens, multiple facts can be consolidated, language can be clarified
+- **REMOVE**: Information becomes irrelevant, facts proven incorrect, entries superseded by better content
+
+### Format Guidelines
+
+- Use clear, declarative statements in present tense
+- State facts confidently when known; flag uncertainty when it exists
+- Write for someone reading this 6 months from now
+- Keep entries relevant and actionable
+- Favor consolidation over accumulation
+
+---
+
+## Example Structure
+
+Below is an example structure. Feel free to organize knowledge in the way that makes most sense for this project:
+
+### Architecture & Infrastructure
+
+_System architecture, deployment patterns, infrastructure details_
+
+### Testing Patterns
+
+_Test strategies, common test scenarios, testing conventions_
+
+### UI/UX Patterns
+
+_User interface conventions, interaction patterns, design system details_
+
+### Data & APIs
+
+_Data models, API behaviors, integration patterns_
+
+### Known Issues & Workarounds
+
+_Current limitations, known bugs, and their workarounds_
+
+### Domain Knowledge
+
+_Business domain facts, terminology, rules, and context_
+
+---
+
+**Remember**: Every entry should answer "Will this help someone working on this project in 6 months?"

package/templates/init/.bugzy/runtime/knowledge-maintenance-guide.md

@@ -0,0 +1,97 @@
+# Knowledge Maintenance Guide
+
+## Overview
+
+This document provides instructions for maintaining a **Context** or **Knowledge Base** - a living collection of factual knowledge that is actively curated and updated rather than simply accumulated over time.
+
+---
+
+## Core Principle: This is a Curated Snapshot, Not a Log
+
+This document represents **what we currently know and believe to be true**, not a history of what we've learned. Think of it as a living reference that evolves as understanding improves.
+
+---
+
+## When to ADD
+
+Add new entries when:
+
+- New factual information is discovered
+- New patterns or relationships emerge
+- New areas of knowledge become relevant
+
+**Check first**: Does this duplicate or overlap with existing entries?
+
+---
+
+## When to UPDATE
+
+Update existing entries when:
+
+- Facts change or we discover more accurate information
+- Understanding deepens (replace shallow with deeper insight)
+- Multiple related facts can be consolidated into one coherent statement
+- Language can be clarified or made more precise
+
+**Goal**: Replace outdated understanding with current understanding
+
+---
+
+## When to REMOVE
+
+Remove entries when:
+
+- Information becomes irrelevant to current needs
+- Facts are proven incorrect (unless there's value in noting the correction)
+- Information is superseded by better, more comprehensive entries
+- Entry is redundant with other content
+
+**Key question**: "If someone reads this in 6 months, will it help them?"
+
+---
+
+## Maintenance Principles
+
+### 1. Favor Consolidation Over Addition
+
+- Before adding, ask: "Can this merge with existing knowledge?"
+- Example: Instead of 10 facts about a person, maintain 2-3 well-organized paragraphs
+
+### 2. Update Rather Than Append
+
+- When information evolves, replace the old statement
+- Keep history only if the evolution itself is important
+- Example: ~~"User is learning Python"~~ → "User is proficient in Python and focusing on FastAPI"
+
+### 3. Regular Pruning
+
+- Periodically review for outdated or low-value entries
+- Ask: "Is this still accurate? Still relevant? Could it be stated better?"
+- Aim for signal-to-noise ratio improvement
+
+### 4. Quality Over Completeness
+
+- Better to have 50 highly relevant, accurate facts than 500 marginally useful ones
+- Prioritize insights over raw data
+- Focus on what's actionable or decision-relevant
+
+### 5. Resolve Contradictions Immediately
+
+- If new information contradicts old, investigate and keep only the truth
+- Don't accumulate conflicting statements
+
+### 6. Use Clear, Declarative Statements
+
+- Write in present tense: "User works at X" not "User mentioned they work at X"
+- State facts confidently when known; flag uncertainty when it exists
+- Avoid hedging unless genuinely uncertain
+
+---
+
+## Anti-Patterns to Avoid
+
+| ❌ Don't Do This | ✅ Do This Instead |
+|-----------------|-------------------|
+| "On Tuesday user said X, then on Friday user said Y" | "User's position on X is Y" (keep most current) |
+| Keeping every detail ever mentioned | Keeping relevant, current details |
+| "User might like coffee, user mentioned tea once, user drinks water" | "User prefers tea; also drinks coffee occasionally" |

package/templates/init/.bugzy/runtime/project-context.md

@@ -0,0 +1,35 @@
+# Project Context
+
+## Customer Information
+**Customer Name:** {{CUSTOMER_NAME}}
+**Primary Contact:** [To be filled]
+
+## Project Information
+**Project Name:** {{PROJECT_NAME}}
+**Description:** [To be filled]
+**Repository:** [To be filled]
+
+## Development Process
+**Methodology:** [Agile/Waterfall/Hybrid - To be filled]
+**Sprint Length:** [e.g., 2 weeks - To be filled]
+**Current Sprint:** [To be filled]
+
+## QA Integration
+**QA Entry Point:** [e.g., After development complete, During development - To be filled]
+**Definition of Done:** [QA criteria for story completion - To be filled]
+**Sign-off Process:** [Who approves test results - To be filled]
+
+## Tools & Systems
+**Bug Tracking:** {{BUG_TRACKING_SYSTEM}}
+**Documentation:** {{DOCUMENTATION_SYSTEM}}
+**CI/CD Platform:** [e.g., GitHub Actions, Jenkins - To be filled]
+**Communication:** [e.g., Slack channel - To be filled]
+
+## Team Contacts
+**Product Owner:** [Name and contact - To be filled]
+**Tech Lead:** [Name and contact - To be filled]
+**QA Lead:** [Name and contact - To be filled]
+**DevOps Contact:** [Name and contact - To be filled]
+
+## Notes
+[Any additional context about the project, special requirements, or considerations]

package/templates/init/.bugzy/runtime/subagent-memory-guide.md

@@ -0,0 +1,87 @@
+# Sub-Agent Memory: Maintenance Instructions
+
+## What This Memory Is
+
+A focused collection of knowledge relevant to your specific role. This is your working knowledge, not a log of interactions.
+
+---
+
+## When to ADD
+
+Add when information:
+- Directly impacts your decisions or outputs
+- Represents a pattern or learning within your domain
+- Prevents repeated mistakes in your area
+
+**Check first**: Does this overlap with main agent knowledge or another sub-agent's domain?
+
+---
+
+## When to UPDATE
+
+Update when:
+- Preferences or requirements change within your domain
+- Understanding deepens through repeated interactions
+- Patterns evolve or are refined
+- Multiple related facts can be consolidated
+
+**Replace** outdated information with current understanding.
+
+---
+
+## When to REMOVE
+
+Remove when:
+- No longer relevant to current work
+- Better handled by main agent's knowledge
+- Proven incorrect or outdated
+- Never actually used in decision-making
+
+**Test**: "Has this influenced a decision recently? Will it influence one soon?"
+
+---
+
+## Core Rules
+
+1. **Stay in your domain** - Don't duplicate main agent knowledge
+2. **Operational over historical** - Keep patterns, not logs
+3. **Patterns over instances** - Generalize from specific events
+4. **Actionable over observational** - Every entry must answer "How does this change what I do?"
+5. **Consolidate aggressively** - Aim for 10-30 high-signal entries
+6. **Update as understanding crystallizes** - Refine vague into specific
+
+---
+
+## Quick Decision Tree
+
+```
+New information
+│
+├─ Relevant to my function? No → Ignore or suggest for main agent
+│                           Yes ↓
+│
+├─ Actionable (changes what I do)? No → Don't store
+│                                   Yes ↓
+│
+├─ Duplicates existing? Yes → UPDATE existing entry
+│                       No ↓
+│
+└─ Belongs in main agent? Yes → Move to main agent
+                          No → ADD to my memory
+```
+
+---
+
+## Division with Main Agent
+
+**Main Agent** stores:
+- User's overall preferences and background
+- Project-wide decisions
+- Cross-cutting concerns
+
+**You (Sub-Agent)** store:
+- Domain-specific preferences and patterns
+- Tactical learnings within your scope
+- Working knowledge for your specific tasks
+
+**When in doubt**: If multiple sub-agents could use it → Main agent

package/templates/init/.bugzy/runtime/templates/test-plan-template.md

@@ -0,0 +1,25 @@
+# Test Plan Template
+
+## Test Scenarios
+
+### Scenario 1: [Name]
+**Objective**: [What are we testing?]
+
+**Test Cases**:
+1. [Test case description]
+2. [Test case description]
+
+**Expected Results**:
+- [Expected outcome]
+
+### Scenario 2: [Name]
+**Objective**: [What are we testing?]
+
+**Test Cases**:
+1. [Test case description]
+
+**Expected Results**:
+- [Expected outcome]
+
+## Notes
+[Add any additional context or requirements]