@brunosps00/dev-workflow 0.0.3 → 0.0.6

package/scaffold/skills/vercel-react-best-practices/rules/server-parallel-fetching.md

@@ -0,0 +1,83 @@
+---
+title: Parallel Data Fetching with Component Composition
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, composition
+---
+
+## Parallel Data Fetching with Component Composition
+
+React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
+
+**Incorrect (Sidebar waits for Page's fetch to complete):**
+
+```tsx
+export default async function Page() {
+  const header = await fetchHeader()
+  return (
+    <div>
+      <div>{header}</div>
+      <Sidebar />
+    </div>
+  )
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+```
+
+**Correct (both fetch simultaneously):**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+export default function Page() {
+  return (
+    <div>
+      <Header />
+      <Sidebar />
+    </div>
+  )
+}
+```
+
+**Alternative with children prop:**
+
+```tsx
+async function Header() {
+  const data = await fetchHeader()
+  return <div>{data}</div>
+}
+
+async function Sidebar() {
+  const items = await fetchSidebarItems()
+  return <nav>{items.map(renderItem)}</nav>
+}
+
+function Layout({ children }: { children: ReactNode }) {
+  return (
+    <div>
+      <Header />
+      {children}
+    </div>
+  )
+}
+
+export default function Page() {
+  return (
+    <Layout>
+      <Sidebar />
+    </Layout>
+  )
+}
+```

package/scaffold/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md

@@ -0,0 +1,34 @@
+---
+title: Parallel Nested Data Fetching
+impact: CRITICAL
+impactDescription: eliminates server-side waterfalls
+tags: server, rsc, parallel-fetching, promise-chaining
+---
+
+## Parallel Nested Data Fetching
+
+When fetching nested data in parallel, chain dependent fetches within each item's promise so a slow item doesn't block the rest.
+
+**Incorrect (a single slow item blocks all nested fetches):**
+
+```tsx
+const chats = await Promise.all(
+  chatIds.map(id => getChat(id))
+)
+
+const chatAuthors = await Promise.all(
+  chats.map(chat => getUser(chat.author))
+)
+```
+
+If one `getChat(id)` out of 100 is extremely slow, the authors of the other 99 chats can't start loading even though their data is ready.
+
+**Correct (each item chains its own nested fetch):**
+
+```tsx
+const chatAuthors = await Promise.all(
+  chatIds.map(id => getChat(id).then(chat => getUser(chat.author)))
+)
+```
+
+Each item independently chains `getChat` → `getUser`, so a slow chat doesn't block author fetches for the others.

package/scaffold/skills/vercel-react-best-practices/rules/server-serialization.md

@@ -0,0 +1,38 @@
+---
+title: Minimize Serialization at RSC Boundaries
+impact: HIGH
+impactDescription: reduces data transfer size
+tags: server, rsc, serialization, props
+---
+
+## Minimize Serialization at RSC Boundaries
+
+The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
+
+**Incorrect (serializes all 50 fields):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()  // 50 fields
+  return <Profile user={user} />
+}
+
+'use client'
+function Profile({ user }: { user: User }) {
+  return <div>{user.name}</div>  // uses 1 field
+}
+```
+
+**Correct (serializes only 1 field):**
+
+```tsx
+async function Page() {
+  const user = await fetchUser()
+  return <Profile name={user.name} />
+}
+
+'use client'
+function Profile({ name }: { name: string }) {
+  return <div>{name}</div>
+}
+```

package/scaffold/skills/webapp-testing/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: webapp-testing
+description: Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.
+---
+
+# Web Application Testing
+
+This skill enables comprehensive testing and debugging of local web applications using Playwright automation.
+
+You should use the Playwright MCP Server to undertake the work if possible. If the MCP Server is unavailable, you can run the code in a local Node.js environment with Playwright installed.
+
+## When to Use This Skill
+
+Use this skill when you need to:
+
+- Test frontend functionality in a real browser
+- Verify UI behavior and interactions
+- Debug web application issues
+- Capture screenshots for documentation or debugging
+- Inspect browser console logs
+- Validate form submissions and user flows
+- Check responsive design across viewports
+
+## Prerequisites
+
+- Node.js installed on the system
+- A locally running web application (or accessible URL)
+- Playwright will be installed automatically if not present
+
+## Core Capabilities
+
+### 1. Browser Automation
+
+- Navigate to URLs
+- Click buttons and links
+- Fill form fields
+- Select dropdowns
+- Handle dialogs and alerts
+
+### 2. Verification
+
+- Assert element presence
+- Verify text content
+- Check element visibility
+- Validate URLs
+- Test responsive behavior
+
+### 3. Debugging
+
+- Capture screenshots
+- View console logs
+- Inspect network requests
+- Debug failed tests
+
+## Usage Examples
+
+### Example 1: Basic Navigation Test
+
+```javascript
+// Navigate to a page and verify title
+await page.goto("http://localhost:3000");
+const title = await page.title();
+console.log("Page title:", title);
+```
+
+### Example 2: Form Interaction
+
+```javascript
+// Fill out and submit a form
+await page.fill("#username", "testuser");
+await page.fill("#password", "password123");
+await page.click('button[type="submit"]');
+await page.waitForURL("**/dashboard");
+```
+
+### Example 3: Screenshot Capture
+
+```javascript
+// Capture a screenshot for debugging
+await page.screenshot({ path: "debug.png", fullPage: true });
+```
+
+## Guidelines
+
+1. **Always verify the app is running** - Check that the local server is accessible before running tests
+2. **Use explicit waits** - Wait for elements or navigation to complete before interacting
+3. **Capture screenshots on failure** - Take screenshots to help debug issues
+4. **Clean up resources** - Always close the browser when done
+5. **Handle timeouts gracefully** - Set reasonable timeouts for slow operations
+6. **Test incrementally** - Start with simple interactions before complex flows
+7. **Use selectors wisely** - Prefer data-testid or role-based selectors over CSS classes
+
+## Common Patterns
+
+### Pattern: Wait for Element
+
+```javascript
+await page.waitForSelector("#element-id", { state: "visible" });
+```
+
+### Pattern: Check if Element Exists
+
+```javascript
+const exists = (await page.locator("#element-id").count()) > 0;
+```
+
+### Pattern: Get Console Logs
+
+```javascript
+page.on("console", (msg) => console.log("Browser log:", msg.text()));
+```
+
+### Pattern: Handle Errors
+
+```javascript
+try {
+  await page.click("#button");
+} catch (error) {
+  await page.screenshot({ path: "error.png" });
+  throw error;
+}
+```
+
+## Limitations
+
+- Requires Node.js environment
+- Cannot test native mobile apps (use React Native Testing Library instead)
+- May have issues with complex authentication flows
+- Some modern frameworks may require specific configuration
+
+## Helper Functions
+
+Some helper functions are available in [`test-helper.js`](./assets/test-helper.js) to simplify common tasks like waiting for elements, capturing screenshots, and handling errors. You can import and use these functions in your tests to improve readability and maintainability.

package/scaffold/skills/webapp-testing/assets/test-helper.js

@@ -0,0 +1,56 @@
+/**
+ * Helper utilities for web application testing with Playwright
+ */
+
+/**
+ * Wait for a condition to be true with timeout
+ * @param {Function} condition - Function that returns boolean
+ * @param {number} timeout - Timeout in milliseconds
+ * @param {number} interval - Check interval in milliseconds
+ */
+async function waitForCondition(condition, timeout = 5000, interval = 100) {
+  const startTime = Date.now();
+  while (Date.now() - startTime < timeout) {
+    if (await condition()) {
+      return true;
+    }
+    await new Promise(resolve => setTimeout(resolve, interval));
+  }
+  throw new Error('Condition not met within timeout');
+}
+
+/**
+ * Capture browser console logs
+ * @param {Page} page - Playwright page object
+ * @returns {Array} Array of console messages
+ */
+function captureConsoleLogs(page) {
+  const logs = [];
+  page.on('console', msg => {
+    logs.push({
+      type: msg.type(),
+      text: msg.text(),
+      timestamp: new Date().toISOString()
+    });
+  });
+  return logs;
+}
+
+/**
+ * Take screenshot with automatic naming
+ * @param {Page} page - Playwright page object
+ * @param {string} name - Base name for screenshot
+ */
+async function captureScreenshot(page, name) {
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const filename = `${name}-${timestamp}.png`;
+  await page.screenshot({ path: filename, fullPage: true });
+  console.log(`Screenshot saved: ${filename}`);
+  return filename;
+}
+
+module.exports = {
+  waitForCondition,
+  captureConsoleLogs,
+  captureScreenshot
+};

package/scaffold/en/commands/help.md

@@ -1,289 +0,0 @@
-<system_instructions>
-You are a workspace help assistant. When invoked, present the user with a complete guide of available commands, their integration flows, and when to use each one.
-
-## Behavior
-
-- If invoked without arguments (`/help`): show the complete guide below
-- If invoked with an argument (`/help create-prd`): show only the detailed section for that command
-
----
-
-# Command Guide - AI Dev Workflow
-
-## Overview
-
-This workspace uses an AI command system that automates the full development cycle: from planning (PRD) to merge (PR). Commands are in `ai/commands/` and are accessible in supported AI CLIs (e.g., Codex, Claude Code, OpenCode, GitHub Copilot), using the CLI prefix (`/command` or `$command`).
-
-## Main Development Flow
-
-```
-┌──────────────┐     ┌─────────────────┐     ┌───────────────┐
-│ /create-prd  │────>│/create-techspec │────>│ /create-tasks │
-│ (WHAT)       │     │ (HOW)           │     │ (WHEN)        │
-└──────────────┘     └─────────────────┘     └───────┬───────┘
-                                                     │
-                                       ┌─────────────┴─────────────┐
-                                       ▼                           ▼
-                              ┌────────────────┐         ┌─────────────────┐
-                              │  /run-task     │         │  /run-plan      │
-                              │ (one at a time)│         │  (all auto)     │
-                              └───────┬────────┘         └────────┬────────┘
-                                      │                           │
-                                      └─────────┬─────────────────┘
-                                                │
-                                                ▼
-                                      ┌─────────────────┐
-                                      │ Validation Lv 1 │ (automatic, embedded)
-                                      │ criteria+tests  │
-                                      └────────┬────────┘
-                                               │
-                                ┌──────────────┼──────────────┐
-                                ▼              ▼              ▼
-                      ┌──────────────┐ ┌──────────────┐ ┌─────────────────────┐
-                      │  /run-qa     │ │/review-impl. │ │  /code-review       │
-                      │ (visual QA)  │ │(PRD compliance│ │ (formal code review)│
-                      └──────────────┘ │  Level 2)    │ │ (Level 3)           │
-                                       └──────────────┘ └─────────────────────┘
-                                                │
-                                ┌───────────────┴───────────────┐
-                                ▼                               ▼
-                      ┌──────────────┐                 ┌────────────────┐
-                      │  /commit     │                 │ /commit-all    │
-                      │ (one project)│                 │ (submodules)   │
-                      └──────┬───────┘                 └───────┬────────┘
-                             │                                 │
-                             └────────────┬────────────────────┘
-                                          ▼
-                                ┌──────────────────┐
-                                │  /generate-pr    │
-                                │ (push + PR + URL)│
-                                └──────────────────┘
-                                          │
-                                          ▼
-                                ┌──────────────────┐
-                                │  /archive-prd    │
-                                │  (post-merge)    │
-                                └──────────────────┘
-```
-
-## Command Table
-
-### Planning
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/brainstorm` | Facilitates structured ideation before PRD or implementation | Problem, idea, or context | Options + trade-offs + recommendation |
-| `/create-prd` | Creates PRD with min. 7 clarification questions | Feature description | `ai/spec/prd-[name]/prd.md` |
-| `/create-techspec` | Creates technical specification from the PRD | PRD path | `ai/spec/prd-[name]/techspec.md` |
-| `/create-tasks` | Breaks PRD+TechSpec into tasks (max 2 RFs/task) | PRD path | `ai/spec/prd-[name]/tasks.md` + `*_task.md` |
-
-### Execution
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/run-task` | Implements ONE task + Level 1 validation + commit | PRD path | Code + commit |
-| `/run-plan` | Executes ALL tasks + final Level 2 review | PRD path | Code + commits + report |
-| `/bugfix` | Analyzes and fixes bugs (bug vs feature triage) | Target + description | Fix + commit OR PRD (if feature) |
-| `/fix-qa` | Fixes documented QA bugs and retests with evidence | PRD path | Code + `QA/bugs.md` + `QA/qa-report.md` updated |
-
-### Research
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/analyze-project` | Analyzes project structure and generates documentation | Project path | Architecture overview |
-| `/deep-research` | Multi-source research with citation tracking and verification | Topic or question | Research report with bibliography |
-
-### Quality (3 Levels)
-
-| Level | Command | When | Generates Report? |
-|-------|---------|------|-------------------|
-| **1** | *(embedded in /run-task)* | After each task | No (terminal output) |
-| **2** | `/review-implementation` | After all tasks / manual | Yes (formatted output) |
-| **3** | `/code-review` | Before PR / manual | Yes (`code-review.md`) |
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/run-qa` | Visual QA with Playwright MCP + accessibility | PRD path | `QA/qa-report.md` + `QA/screenshots/` + `QA/logs/` |
-| `/review-implementation` | Compares PRD vs code (RFs, endpoints, tasks) | PRD path | Gap report |
-| `/code-review` | Formal code review (quality, rules, tests) | PRD path | `code-review.md` |
-| `/refactoring-analysis` | Audit code smells and refactoring opportunities (Fowler's catalog) | PRD path | `refactoring-analysis.md` |
-
-### Versioning
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/commit` | Semantic commit (Conventional Commits) | - | Commit |
-| `/commit-all` | Commit across all submodules (inside-out) | - | Commits |
-| `/generate-pr` | Push + create PR + copy body + open URL | Target branch | PR on GitHub |
-
-### Maintenance
-
-| Command | What it does | Input | Output |
-|---------|-------------|-------|--------|
-| `/list-tasks` | Lists tasks and progress for a PRD | PRD path | Status table |
-| `/task-summary` | Shows details of a task without executing | Number + path | Task summary |
-| `/archive-prd` | Moves completed PRD to `ai/archived/prd/` | PRD path | Archived PRD |
-| `/help` | This command guide | (optional) command | This document |
-
-## Review Architecture (3 Levels)
-
-```
-LEVEL 1 - Post-Task Validation (automatic, lightweight)
-├── Embedded in /run-task
-├── Verifies task acceptance criteria
-├── Runs tests (pnpm test / npm test)
-├── Checks basic patterns (types, imports)
-├── No report file
-└── If fails: PAUSES execution
-
-LEVEL 2 - PRD Compliance (/review-implementation)
-├── Compares ALL RFs from PRD vs actual code
-├── Verifies ALL endpoints from TechSpec
-├── Checks real status of each task (ignores checkboxes)
-├── Identifies gaps, partial implementations, extra code
-├── Called automatically at end of /run-plan
-└── Available manually
-
-LEVEL 3 - Formal Code Review (/code-review)
-├── Everything from Level 2 +
-├── Quality analysis (SOLID, DRY, complexity, security)
-├── Conformance with project rules (ai/rules/)
-├── Tests with coverage
-├── Generates code-review.md in PRD directory
-└── Status: APPROVED / WITH CAVEATS / REJECTED
-```
-
-## Common Flows
-
-### New Feature (Full)
-```bash
-/brainstorm "initial idea"                      # 0. Explore options and trade-offs
-/create-prd                                     # 1. Describe the feature
-/create-techspec ai/spec/prd-name              # 2. Generate tech spec
-/create-tasks ai/spec/prd-name                 # 3. Break into tasks
-/run-plan ai/spec/prd-name                     # 4. Execute all (includes Level 1+2)
-/refactoring-analysis ai/spec/prd-name         # 5. Audit code smells (optional)
-/code-review ai/spec/prd-name                  # 6. Formal code review (Level 3)
-/generate-pr main                               # 7. Create PR
-/archive-prd ai/spec/prd-name                  # 8. After merge
-```
-
-### New Feature (Incremental)
-```bash
-/brainstorm "initial idea"                      # 0. Explore options and trade-offs
-/create-prd                                     # 1. PRD
-/create-techspec ai/spec/prd-name              # 2. TechSpec
-/create-tasks ai/spec/prd-name                 # 3. Tasks
-/run-task ai/spec/prd-name                     # 4. Task 1 (with Level 1)
-/run-task ai/spec/prd-name                     # 5. Task 2 (with Level 1)
-# ... repeat for each task
-/review-implementation ai/spec/prd-name        # 6. PRD review (Level 2)
-/code-review ai/spec/prd-name                  # 7. Code review (Level 3)
-/generate-pr main                               # 8. PR
-```
-
-### Simple Bug
-```bash
-/bugfix "bug description"                       # Analyze and fix
-/commit                                         # Commit the fix
-/generate-pr main                               # PR
-```
-
-### Complex Bug
-```bash
-/bugfix "description" --analysis                # Generate analysis document
-/create-techspec ai/spec/bugfix-name           # TechSpec for the fix
-/create-tasks ai/spec/bugfix-name              # Tasks for the fix
-/run-plan ai/spec/bugfix-name                  # Execute all
-/generate-pr main                               # PR
-```
-
-### Visual QA (Frontend)
-```bash
-/run-qa ai/spec/prd-name                       # QA with Playwright MCP
-# If bugs found:
-/bugfix "description"                           # Fix each bug
-/fix-qa ai/spec/prd-name                       # Fix + retest full cycle
-```
-
-### Deep Research
-```bash
-/deep-research "topic or question"              # Multi-source research with citations
-```
-
-## File Structure
-
-```
-your-project/
-├── ai/
-│   ├── commands/              # Source of truth for commands
-│   │   ├── help.md            # This guide
-│   │   ├── brainstorm.md
-│   │   ├── create-prd.md
-│   │   ├── create-techspec.md
-│   │   ├── create-tasks.md
-│   │   ├── run-task.md
-│   │   ├── run-plan.md
-│   │   ├── run-qa.md
-│   │   ├── code-review.md
-│   │   ├── refactoring-analysis.md
-│   │   ├── review-implementation.md
-│   │   ├── analyze-project.md
-│   │   ├── deep-research.md
-│   │   ├── bugfix.md
-│   │   ├── commit.md
-│   │   ├── commit-all.md
-│   │   ├── generate-pr.md
-│   │   └── archive-prd.md
-│   ├── templates/             # Document templates
-│   │   ├── prd-template.md
-│   │   ├── techspec-template.md
-│   │   ├── tasks-template.md
-│   │   ├── task-template.md
-│   │   └── bugfix-template.md
-│   ├── rules/                 # Project-specific rules
-│   │   └── *.md
-│   ├── tasks/                 # Active PRDs and tasks
-│   │   └── prd-[name]/
-│   │       ├── prd.md
-│   │       ├── techspec.md
-│   │       ├── tasks.md
-│   │       └── *_task.md
-│   └── archived/prd/          # Completed PRDs
-├── .codex/skills/             # Codex skills
-├── .claude/skills/            # Claude Code skills
-├── .opencode/commands/        # OpenCode commands
-└── .github/copilot-instructions.md  # Copilot instructions
-```
-
-## Tool Integration
-
-Commands work across multiple AI tools, all pointing to the same source `ai/commands/`:
-
-| Tool | Location | Format |
-|------|----------|--------|
-| **Codex CLI** | `.codex/skills/*/SKILL.md` | Skill referencing `ai/commands/` |
-| **Claude Code** | `.claude/skills/*/SKILL.md` | Skill referencing `ai/commands/` |
-| **OpenCode** | `.opencode/commands/*.md` | Command referencing `ai/commands/` |
-| **GitHub Copilot** | `.github/copilot-instructions.md` | Instructions listing the commands |
-
-## FAQ
-
-**Q: What is the difference between `/run-task` and `/run-plan`?**
-- `/run-task` executes ONE task with manual control between each one
-- `/run-plan` executes ALL automatically with a final review
-
-**Q: Do I need to run `/review-implementation` manually?**
-- Not if using `/run-plan` (already included). Yes if using `/run-task` incrementally.
-
-**Q: When to use `/code-review` vs `/review-implementation`?**
-- `/review-implementation` (Level 2): Checks if PRD RFs were implemented
-- `/code-review` (Level 3): Additionally analyzes code quality and generates a formal report
-
-**Q: Does `/bugfix` always fix directly?**
-- No. It performs triage. If it is a feature (not a bug), it redirects to `/create-prd`. If it is a complex bug, it can generate an analysis document with `--analysis`.
-
-**Q: When should I use `/deep-research`?**
-- For comprehensive multi-source analysis, technology comparisons, state-of-the-art reviews, or any topic requiring cited evidence. Not for simple lookups or debugging.
-
-</system_instructions>