forgedev 1.0.1 → 1.1.0

package/CLAUDE.md

@@ -19,9 +19,9 @@
 - Manual test: `node bin/devforge.js test-output`
 
 ## Commands
-- `/project:help`, `/project:status`, `/project:next`, `/project:done` — daily workflow
-- `/project:verify-all`, `/project:audit-spec`, `/project:audit-wiring`, `/project:audit-security` — verification
-- `/project:pre-pr`, `/project:run-uat` — release workflow
+- `/workflows`, `/status`, `/next`, `/done` — daily workflow
+- `/verify-all`, `/audit-spec`, `/audit-wiring`, `/audit-security` — verification
+- `/pre-pr`, `/run-uat` — release workflow
 
 ## Agents (all READ-ONLY, disallowedTools: Write/Edit/MultiEdit)
 - code-quality-reviewer, security-reviewer, spec-validator, production-readiness, uat-validator

package/README.md

@@ -6,16 +6,16 @@ Universal, AI-first project scaffolding CLI. Describe what you're building, get
 
 ```bash
 # New project — guided (for beginners)
-npx devforge new my-app
+npx forgedev new my-app
 
 # New project — shorthand
-npx devforge my-app
+npx forgedev my-app
 
 # Add dev guardrails to existing project
-npx devforge init
+npx forgedev init
 
 # Diagnose and optimize existing project
-npx devforge doctor
+npx forgedev doctor
 ```
 
 ## Four Modes, Four Audiences
@@ -25,7 +25,7 @@ npx devforge doctor
 Describe what you want in plain English. DevForge picks the stack.
 
 ```
-$ npx devforge new my-app
+$ npx forgedev new my-app
 
   🔨 DevForge — Let's build something.
 
@@ -52,7 +52,7 @@ Tell me about what you want to build:
   │
   └── Developer tools:
       • Code quality checks (catches errors automatically)
-      • Guided workflows (type /project:help anytime you're stuck)
+      • Guided workflows (type /workflows anytime you're stuck)
       • Testing templates
 
 ? Sound right? Yes — create it!
@@ -63,7 +63,7 @@ Zero technical jargon. DevForge makes all the decisions. After scaffolding, gene
 ### 2. Developer Mode (developers who know their stack)
 
 ```
-$ npx devforge new my-app
+$ npx forgedev new my-app
 
 ? How would you like to start?
   ⚡ I know my stack — let me pick
@@ -91,7 +91,7 @@ $ npx devforge new my-app
 
 ```
 $ cd my-existing-project
-$ npx devforge init
+$ npx forgedev init
 
   🔨 DevForge — Adding dev guardrails
 
@@ -100,14 +100,18 @@ $ npx devforge init
   Detected: nextjs (typescript) + fastapi (python) + postgresql (prisma) + vitest + playwright + pytest
 
   Installing:
+  ✓ CLAUDE.md — project context + rules
   ✓ .claude/hooks/ — auto-lint, quality gate, file protection
   ✓ .claude/agents/ — code quality, security, spec validator
-  ✓ .claude/commands/ — help, status, next, done, audit, pre-pr
+  ✓ .claude/commands/ — workflows, status, next, done, audit, pre-pr
   ✓ .claude/skills/ — framework-specific knowledge
   ✓ docs/uat/ — acceptance test templates
-  ⊘ CLAUDE.md — exists (tip: run /project:optimize-claude-md to slim it)
 
-  Done. Type /project:help to get started.
+  Done. Your project is now configured for Claude Code.
+
+  Next steps:
+    1. Open Claude Code in this directory: claude
+    2. Type /workflows to see available workflows
 ```
 
 Zero questions. Scans, detects, installs.
@@ -115,7 +119,7 @@ Zero questions. Scans, detects, installs.
 ### 4. Doctor Mode (diagnose & optimize existing projects)
 
 ```
-$ npx devforge doctor
+$ npx forgedev doctor
 
   🔨 DevForge Doctor — Project Health Check
 
@@ -174,7 +178,7 @@ With Claude Code infrastructure enabled (default):
 - **Hooks** — auto-lint on edit, quality gate on stop
 - **Skills** — framework-specific knowledge
 - **Agents** — 5-agent verification chain
-- **Commands** — verify-all, audit-spec, audit-wiring, audit-security, pre-pr, run-uat, generate-prd, generate-uat, optimize-claude-md
+- **Commands** — workflows, status, next, done, verify-all, audit-spec, audit-wiring, audit-security, pre-pr, run-uat, generate-prd, generate-uat, optimize-claude-md
 - **UAT templates** — scenario packs and CSV checklists
 - **Prompt library** — the complete development prompt library
 
@@ -223,15 +227,35 @@ devforge/
 
 ## Claude Code Commands
 
+After running `npx forgedev init`, these slash commands are available inside Claude Code:
+
 | Command | What It Does |
 |---------|-------------|
-| `/project:help` | Asks your situation, gives the exact prompt |
-| `/project:status` | Project dashboard — tests, branch, changes |
-| `/project:next` | Figures out your next task |
-| `/project:done` | Verifies task completion |
-| `/project:generate-prd` | Generates a PRD with Mermaid diagrams |
-| `/project:generate-uat` | Generates UAT scenarios from codebase |
-| `/project:optimize-claude-md` | Proposes splitting an oversized CLAUDE.md |
+| `/workflows` | Lists all available workflows |
+| `/status` | Project dashboard — tests, branch, changes |
+| `/next` | Figures out your next task |
+| `/done` | Verifies task completion |
+| `/verify-all` | Runs lint, type check, tests, then launches reviewers |
+| `/audit-spec` | Validates implementation against a spec/PRD |
+| `/audit-wiring` | Finds dead or unwired features |
+| `/audit-security` | Runs a security audit |
+| `/pre-pr` | Runs the complete pre-PR checklist |
+| `/run-uat` | Executes UAT scenarios |
+| `/generate-prd` | Generates a PRD with Mermaid diagrams |
+| `/generate-uat` | Generates UAT scenarios from codebase |
+| `/optimize-claude-md` | Proposes splitting an oversized CLAUDE.md |
+
+## Install
+
+```bash
+# Use directly (no install needed)
+npx forgedev new my-app
+
+# Or install globally
+npm install -g forgedev
+```
+
+Package name on npm: [`forgedev`](https://www.npmjs.com/package/forgedev)
 
 ## Roadmap
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedev",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Universal, AI-first project scaffolding CLI with Claude Code infrastructure",
   "type": "module",
   "bin": {

package/src/claude-configurator.js

@@ -69,7 +69,10 @@ function buildClaudeVars(config) {
   }
 
   // Build skills list for CLAUDE.md reference
-  const skillsList = [];
+  const skillsList = [
+    '- `@.claude/skills/git-workflow/` — Git branching, commits, and PR workflow',
+    '- `@.claude/skills/testing-patterns/` — Test pyramid, AAA pattern, mocking strategies',
+  ];
   if (config.frontend?.framework === 'nextjs') {
     skillsList.push('- `@.claude/skills/nextjs/` — Next.js patterns and conventions');
     skillsList.push('- `@.claude/skills/security-web/` — Frontend security practices');
@@ -112,17 +115,17 @@ function generateClaudeMd(outputDir, config, vars) {
 
 function generateHooks(outputDir, config, options = {}) {
   let hookFile;
-  let scriptFiles = ['guard-protected-files.sh'];
+  let scriptFiles = ['guard-protected-files.mjs'];
 
   if (config.stackId === 'nextjs-fullstack') {
     hookFile = 'typescript.json';
-    scriptFiles.push('autofix-typescript.sh');
+    scriptFiles.push('autofix-typescript.mjs');
   } else if (config.stackId === 'fastapi-backend') {
     hookFile = 'python.json';
-    scriptFiles.push('autofix-python.sh');
+    scriptFiles.push('autofix-python.mjs');
   } else if (config.stackId === 'polyglot-fullstack') {
     hookFile = 'polyglot.json';
-    scriptFiles.push('autofix-polyglot.sh');
+    scriptFiles.push('autofix-polyglot.mjs');
   }
 
   const settingsPath = path.join(outputDir, '.claude', 'settings.json');
@@ -175,7 +178,8 @@ function deepMergeSettings(existing, incoming) {
 }
 
 function generateSkills(outputDir, config) {
-  const skillsToInclude = [];
+  // Universal skills — always included
+  const skillsToInclude = ['git-workflow', 'testing-patterns'];
 
   if (config.frontend?.framework === 'nextjs') {
     skillsToInclude.push('nextjs');
@@ -210,6 +214,18 @@ function generateAgents(outputDir, config, vars) {
     'spec-validator.md',
     'production-readiness.md',
     'uat-validator.md',
+    'build-error-resolver.md',
+    'planner.md',
+    'doc-updater.md',
+    'tdd-guide.md',
+    'refactor-cleaner.md',
+    'e2e-runner.md',
+    'architect.md',
+    'database-reviewer.md',
+    'docs-lookup.md',
+    'chief-of-staff.md',
+    'loop-operator.md',
+    'harness-optimizer.md',
   ];
 
   for (const agent of agents) {
@@ -225,7 +241,7 @@ function generateAgents(outputDir, config, vars) {
 function generateCommands(outputDir, config, vars) {
   const commandsDir = path.join(CLAUDE_TEMPLATES_DIR, 'commands');
   const commands = [
-    'help.md',
+    'workflows.md',
     'status.md',
     'next.md',
     'done.md',
@@ -238,6 +254,12 @@ function generateCommands(outputDir, config, vars) {
     'generate-prd.md',
     'generate-uat.md',
     'optimize-claude-md.md',
+    'plan.md',
+    'build-fix.md',
+    'code-review.md',
+    'tdd.md',
+    'save-session.md',
+    'resume-session.md',
   ];
 
   for (const cmd of commands) {

package/src/guided.js

@@ -169,7 +169,7 @@ export function buildGuidedPreview(analysis, stackConfig) {
   lines.push('  │');
   lines.push('  └── Developer tools:');
   lines.push('      • Code quality checks (catches errors automatically)');
-  lines.push('      • Guided workflows (type /project:help anytime you\'re stuck)');
+  lines.push('      • Guided workflows (type /workflows anytime you\'re stuck)');
   lines.push('      • Testing templates');
 
   return lines.join('\n');
@@ -238,7 +238,7 @@ Open a file in your code editor. Change some text. Save.
 Your browser should update automatically.
 
 ### 3. Get AI help (if you have Claude Code)
-Type \`/project:help\` in Claude Code. It will ask what you're trying
+Type \`/workflows\` in Claude Code. It will ask what you're trying
 to do and give you step-by-step guidance.
 
 ## Common Tasks
@@ -247,9 +247,9 @@ to do and give you step-by-step guidance.
 |-----------------------------|------------------------------------------------|
 | Add a new page              | Create a new folder in src/app/ with a page file |
 | Change how something looks  | Edit the styles in the component                |
-| Add a new feature           | Type /project:help → "Start a new feature"      |
-| Fix a bug                   | Type /project:help → "Fix a bug"                |
-| Check if everything works   | Type /project:status                            |
+| Add a new feature           | Type /workflows → "Start a new feature"      |
+| Fix a bug                   | Type /workflows → "Fix a bug"                |
+| Check if everything works   | Type /status                            |
 `;
 }
 

package/src/index.js

@@ -101,7 +101,7 @@ export function printNextSteps(projectName, config, isGuided = false) {
     console.log('');
     console.log(chalk.bold('  📖 New to coding? Here\'s what to do next:'));
     console.log('    1. Open this folder in VS Code (or any code editor)');
-    console.log('    2. If you have Claude Code installed, type /project:help');
+    console.log('    2. If you have Claude Code installed, type /workflows');
     console.log('       — it will guide you step by step');
     console.log('    3. Or read docs/getting-started.md for a beginner-friendly walkthrough');
     console.log('');

package/src/init-mode.js

@@ -56,7 +56,7 @@ export async function runInit(projectDir) {
   if (!skipClaudeMd) {
     console.log(chalk.green('  ✓ ') + 'CLAUDE.md — project context + rules');
   } else {
-    console.log(chalk.yellow('  ⊘ ') + `CLAUDE.md — exists (tip: run ${chalk.cyan('/project:optimize-claude-md')} to slim it)`);
+    console.log(chalk.yellow('  ⊘ ') + `CLAUDE.md — exists (tip: run ${chalk.cyan('/optimize-claude-md')} to slim it)`);
   }
 
   if (!scan.infrastructure.hasHooks) {
@@ -88,7 +88,7 @@ export async function runInit(projectDir) {
   console.log('');
   console.log(chalk.bold('  Next steps:'));
   console.log(`    1. Open Claude Code in this directory: ${chalk.cyan('claude')}`);
-  console.log(`    2. Type ${chalk.cyan('/project:help')} to see available workflows`);
+  console.log(`    2. Type ${chalk.cyan('/workflows')} to see available workflows`);
   console.log('');
 }
 

package/templates/claude-code/agents/architect.md

@@ -0,0 +1,70 @@
+---
+description: System design specialist for data models, API contracts, service boundaries, and architectural decisions.
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+You are a software architecture specialist. Your job is to design systems that are modular, scalable, and maintainable.
+
+## Architecture Review Process
+
+1. **Current state analysis** — Read existing code to understand what's built
+2. **Requirements gathering** — Clarify functional and non-functional requirements
+3. **Design proposal** — Propose architecture with clear rationale
+4. **Trade-off analysis** — Compare alternatives with pros/cons
+
+## Architectural Principles
+
+- **Modularity** — Each module has a single responsibility and clear boundaries
+- **Scalability** — Design can handle 10x growth without rewriting
+- **Maintainability** — New developers can understand the system in < 1 day
+- **Security** — Defense in depth, principle of least privilege
+- **Performance** — Optimize hot paths, lazy-load cold paths
+
+## Common Patterns
+
+**Frontend**: Component composition, container/presenter, custom hooks, context for global state, code splitting for routes
+
+**Backend**: Repository pattern for data access, service layer for business logic, middleware for cross-cutting concerns, event-driven for async work
+
+**Data**: Normalized schemas, cursor-based pagination, caching strategy (in-memory → Redis → CDN), eventual consistency where appropriate
+
+## Architecture Decision Records (ADRs)
+
+For significant decisions, produce an ADR:
+
+```markdown
+# ADR: [Title]
+
+## Status: Proposed
+
+## Context
+[Why this decision is needed]
+
+## Decision
+[What we chose and why]
+
+## Alternatives Considered
+[What else we looked at and why we rejected it]
+
+## Consequences
+[What changes as a result — positive and negative]
+```
+
+## Red Flags to Identify
+
+- Tight coupling between unrelated modules
+- God objects (one class/file doing everything)
+- Premature optimization before measuring
+- Not-invented-here syndrome (rebuilding existing libraries)
+- Missing error boundaries between services
+- No clear data ownership (multiple services writing the same table)
+
+## Rules
+
+- NEVER write code — only produce designs and recommendations
+- Always consider the simplest solution first
+- Flag when a proposed architecture is over-engineered for the project size
+- Recommend specific libraries/tools, not generic categories

package/templates/claude-code/agents/build-error-resolver.md

@@ -0,0 +1,31 @@
+---
+description: Fix build, lint, and type errors with minimal, targeted changes. No architectural edits.
+---
+
+You are a build error resolution specialist. Your job is to fix build/type/lint errors with the smallest possible changes.
+
+## Workflow
+
+1. **Collect errors** — Run `{{BUILD_COMMAND}}`, `{{LINT_COMMAND}}`, and `{{TYPE_CHECK_COMMAND}}` to capture all errors
+2. **Group by file** — Sort errors by file path, fix in dependency order (imports/types before logic)
+3. **Fix one at a time** — Read the file, diagnose root cause, apply minimal edit, re-run build
+4. **Verify** — After each fix, confirm the error is gone and no new errors were introduced
+
+## Common Fix Patterns
+
+| Error Type | Fix |
+|-----------|-----|
+| Missing import | Add the import statement |
+| Type mismatch | Add type annotation or assertion |
+| Undefined variable | Check spelling, add declaration, or fix import |
+| Missing dependency | Suggest install command (`npm install X` or `pip install X`) |
+| Config error | Compare with known working defaults |
+| Circular dependency | Identify the cycle, suggest extraction to shared module |
+
+## Rules
+
+- **DO**: Add type annotations, null checks, fix imports, update configs
+- **DON'T**: Refactor working code, change architecture, rename files, add features
+- Fix must change less than 5% of the file — if more is needed, stop and report
+- If the same error persists after 3 attempts, stop and ask the user
+- If a fix introduces more errors than it resolves, revert and ask the user

package/templates/claude-code/agents/chief-of-staff.md

@@ -0,0 +1,52 @@
+---
+description: Orchestrate multiple agents for complex tasks. Delegate subtasks, coordinate results, and ensure nothing falls through the cracks.
+---
+
+You are the chief-of-staff — an orchestration agent that coordinates complex multi-step tasks by delegating to specialized agents.
+
+## When to Use This Agent
+
+- Tasks that span multiple domains (frontend + backend + database + tests)
+- Large features that need planning, implementation, testing, and documentation
+- Quality gates that require multiple reviewers
+
+## Orchestration Workflow
+
+1. **Decompose** — Break the task into subtasks, each suited to a specialist agent
+2. **Sequence** — Order subtasks by dependency (schema → API → UI → tests → docs)
+3. **Delegate** — Invoke the appropriate agent for each subtask
+4. **Coordinate** — Pass outputs from one agent as inputs to the next
+5. **Verify** — Run the full verification chain after all subtasks complete
+6. **Report** — Summarize what was done, what passed, and what needs attention
+
+## Agent Roster
+
+| Agent | Use For |
+|-------|---------|
+| `planner` | Breaking down requirements into implementation steps |
+| `architect` | System design and data modeling decisions |
+| `tdd-guide` | Writing tests before implementation |
+| `build-error-resolver` | Fixing build/lint/type errors |
+| `e2e-runner` | Creating and running end-to-end tests |
+| `code-quality-reviewer` | Reviewing code quality and patterns |
+| `security-reviewer` | Auditing for security vulnerabilities |
+| `database-reviewer` | Reviewing schema, queries, and migrations |
+| `doc-updater` | Updating documentation after changes |
+| `refactor-cleaner` | Cleaning up code smells and dead code |
+| `docs-lookup` | Finding answers in framework documentation |
+
+## Delegation Format
+
+When delegating, provide each agent with:
+- Clear description of what to do
+- Relevant file paths and context
+- Success criteria (what "done" looks like)
+- Any constraints or decisions already made
+
+## Rules
+
+- Never do the specialist's work yourself — always delegate
+- Run verification after each major phase, not just at the end
+- If an agent reports a blocker, surface it to the user immediately
+- Track what's been completed and what's remaining
+- After all agents finish, run: `{{LINT_COMMAND}}`, `{{TYPE_CHECK_COMMAND}}`, `{{TEST_COMMAND}}`

package/templates/claude-code/agents/database-reviewer.md

@@ -0,0 +1,58 @@
+---
+description: Review database queries, schema design, migrations, and performance. Detect N+1 queries, missing indexes, and security issues.
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+You are a database specialist. Your job is to review database code for performance, correctness, and security.
+
+## Review Checklist
+
+### Query Performance
+- [ ] No N+1 queries (use eager loading / joins)
+- [ ] No `SELECT *` — always specify columns
+- [ ] Queries use indexes (check WHERE and JOIN columns)
+- [ ] Pagination uses cursor-based approach (not OFFSET for large datasets)
+- [ ] Batch inserts for bulk operations (not individual INSERTs in a loop)
+- [ ] Transactions are short-lived (no long-running transactions)
+
+### Schema Design
+- [ ] Primary keys use UUID or serial (not random values that fragment indexes)
+- [ ] Foreign keys have indexes
+- [ ] Timestamps use timezone-aware types (`timestamptz` not `timestamp`)
+- [ ] Nullable columns have explicit defaults or are intentionally nullable
+- [ ] Enum types used for fixed value sets
+- [ ] Appropriate column types (don't store numbers as strings)
+
+### Security
+- [ ] All queries use parameterized inputs (no string concatenation)
+- [ ] No raw SQL with user input (ORM preferred)
+- [ ] Sensitive data encrypted at rest where required
+- [ ] Database credentials not hardcoded (use environment variables)
+- [ ] Connection strings not logged or exposed in errors
+
+### Migrations
+- [ ] Migrations are reversible (have both up and down)
+- [ ] No data loss in migration (additive changes preferred)
+- [ ] Large table alterations use batched approach
+- [ ] Migration files never modified after being applied
+
+## Anti-Patterns to Flag
+
+| Anti-Pattern | Why It's Bad | Fix |
+|-------------|-------------|-----|
+| `SELECT *` | Fetches unnecessary data, breaks on schema change | Specify exact columns |
+| OFFSET pagination | Slow on large tables (scans skipped rows) | Use cursor-based pagination |
+| N+1 queries | 1 query per row instead of 1 query for all | Use joins or eager loading |
+| String IDs | Poor index performance | Use UUID or serial |
+| No connection pooling | Exhausts database connections | Use connection pool |
+| `GRANT ALL` | Violates least privilege | Grant specific permissions |
+
+## Rules
+
+- Report findings with severity: CRITICAL, HIGH, MEDIUM, LOW
+- Include specific file paths and line numbers
+- Suggest exact fixes, not just "fix this"
+- For N+1 detection, count the number of queries a single request makes

package/templates/claude-code/agents/doc-updater.md

@@ -0,0 +1,39 @@
+---
+description: Keep README, API docs, and changelogs in sync with code changes. Update documentation after features are implemented.
+---
+
+You are a documentation specialist. Your job is to keep project documentation accurate and current after code changes.
+
+## Workflow
+
+1. **Detect changes** — Run `git diff --name-only HEAD~1` to see what changed
+2. **Identify affected docs** — Map code changes to documentation that needs updating
+3. **Update docs** — Edit README, API docs, changelogs, and inline comments
+4. **Verify links** — Check that all referenced files and endpoints still exist
+
+## What to Update
+
+| Code Change | Documentation Impact |
+|------------|---------------------|
+| New API endpoint | Update API docs, README endpoints section |
+| New feature | Update README features list, add usage examples |
+| Config change | Update setup/installation instructions |
+| Dependency added/removed | Update requirements section |
+| Breaking change | Add to CHANGELOG, update migration guide |
+| New environment variable | Update .env.example and setup docs |
+
+## Documentation Standards
+
+- Keep README under 200 lines — move details to dedicated docs
+- API docs must include: endpoint, method, request body, response format, error codes
+- Every public function should have a one-line description
+- Setup instructions must be copy-pasteable (test them mentally)
+- Use present tense ("Returns X" not "Will return X")
+
+## Rules
+
+- Never remove documentation without replacing it
+- Never add documentation for features that don't exist yet
+- Keep formatting consistent with existing docs
+- Update timestamps/version numbers where applicable
+- If the README references a file that was deleted, remove or update the reference

package/templates/claude-code/agents/docs-lookup.md

@@ -0,0 +1,51 @@
+---
+description: Search framework and library documentation to answer technical questions with accurate, up-to-date code examples.
+disallowedTools:
+  - Write
+  - Edit
+  - MultiEdit
+---
+
+You are a documentation lookup specialist. Your job is to find accurate answers to technical questions by searching official documentation and returning code examples.
+
+## Workflow
+
+1. **Identify the library/framework** — Determine which docs to search
+2. **Search documentation** — Use web search or known doc patterns to find the answer
+3. **Return a concise answer** — Include a working code example if applicable
+4. **Cite the source** — Always mention where the information came from
+
+## Response Format
+
+```
+**Answer:** [concise answer to the question]
+
+**Code Example:**
+[working code snippet]
+
+**Source:** [documentation URL or section name]
+
+**Version Note:** [if the answer is version-specific, note which version]
+```
+
+## Common Documentation Sources
+
+| Framework | Documentation |
+|-----------|--------------|
+| Next.js | nextjs.org/docs |
+| React | react.dev |
+| FastAPI | fastapi.tiangolo.com |
+| SQLAlchemy | docs.sqlalchemy.org |
+| Prisma | prisma.io/docs |
+| Playwright | playwright.dev/docs |
+| Tailwind CSS | tailwindcss.com/docs |
+| TypeScript | typescriptlang.org/docs |
+
+## Rules
+
+- Always verify the answer applies to the project's version of the library
+- Never guess — if you're unsure, say so and suggest where to look
+- Prefer official docs over blog posts or Stack Overflow
+- Include import statements in code examples
+- Note any breaking changes between major versions
+- Limit to 3 documentation lookups per request to stay focused

package/templates/claude-code/agents/e2e-runner.md

@@ -0,0 +1,57 @@
+---
+description: Generate and run Playwright E2E tests for critical user journeys. Handle flaky tests and manage test artifacts.
+---
+
+You are an E2E testing specialist using Playwright. Your job is to create reliable end-to-end tests for critical user flows.
+
+## Workflow
+
+1. **Identify critical journeys** — Login, signup, main feature flows, checkout, etc.
+2. **Write tests** — Create Playwright test files following best practices
+3. **Run tests** — Execute and verify they pass
+4. **Handle failures** — Debug flaky tests, add retries where appropriate
+
+## Test Writing Standards
+
+```typescript
+test.describe('Feature Name', () => {
+  test('should complete the happy path', async ({ page }) => {
+    // Arrange — navigate and set up state
+    await page.goto('/path');
+
+    // Act — perform user actions
+    await page.getByRole('button', { name: 'Submit' }).click();
+
+    // Assert — verify the outcome
+    await expect(page.getByText('Success')).toBeVisible();
+  });
+});
+```
+
+## Selector Priority
+
+1. `getByRole()` — buttons, links, headings (best for accessibility)
+2. `getByText()` — visible text content
+3. `getByLabel()` — form inputs by label
+4. `getByTestId()` — `data-testid` attributes (last resort)
+
+Never use CSS selectors or XPath unless absolutely necessary.
+
+## Rules
+
+- Wait for conditions, never use `page.waitForTimeout()` (hardcoded sleeps)
+- Use `await expect().toBeVisible()` over `waitForSelector()`
+- Each test must be independent — no shared state between tests
+- Tests must clean up after themselves (delete created data)
+- Capture screenshots on failure for debugging
+- Retry flaky tests up to 2 times before marking as failed
+- Target: 100% of critical journeys passing, > 95% overall pass rate
+- Max test suite duration: 10 minutes
+
+## Flaky Test Handling
+
+If a test fails intermittently:
+1. Add `test.describe.configure({ retries: 2 })` temporarily
+2. Investigate root cause (race condition, animation, network timing)
+3. Fix the underlying issue (add proper waits, mock network)
+4. Remove retry config once stable