engsys 1.0.0

package/core/skills/web-design-reviewer/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: web-design-reviewer
+description: 'This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level.'
+---
+
+# Web Design Reviewer
+
+This skill enables visual inspection and validation of website design quality, identifying and fixing issues at the source code level.
+
+## Scope of Application
+
+- Static sites (HTML/CSS/JS)
+- SPA frameworks such as React / Vue / Angular / Svelte
+- Full-stack frameworks such as Next.js / Nuxt / SvelteKit
+- CMS platforms such as WordPress / Drupal
+- Any other web application
+
+## Prerequisites
+
+### Required
+
+1. **Target website must be running**
+   - Local development server (e.g., `http://localhost:3000`)
+   - Staging environment
+   - Production environment (for read-only reviews)
+
+2. **Browser automation must be available**
+   - Screenshot capture
+   - Page navigation
+   - DOM information retrieval
+
+3. **Access to source code (when making fixes)**
+   - Project must exist within the workspace
+
+## Workflow Overview
+
+```mermaid
+flowchart TD
+    A[Step 1: Information Gathering] --> B[Step 2: Visual Inspection]
+    B --> C[Step 3: Issue Fixing]
+    C --> D[Step 4: Re-verification]
+    D --> E{Issues Remaining?}
+    E -->|Yes| B
+    E -->|No| F[Completion Report]
+```
+
+---
+
+## Step 1: Information Gathering Phase
+
+### 1.1 URL Confirmation
+
+If the URL is not provided, ask the user:
+
+> Please provide the URL of the website to review (e.g., `http://localhost:3000`)
+
+### 1.2 Understanding Project Structure
+
+When making fixes, gather the following information:
+
+| Item            | Example Question                              |
+| --------------- | --------------------------------------------- |
+| Framework       | Are you using React / Vue / Next.js, etc.?    |
+| Styling Method  | CSS / SCSS / Tailwind / CSS-in-JS, etc.       |
+| Source Location | Where are style files and components located? |
+| Review Scope    | Specific pages only or entire site?           |
+
+### 1.3 Automatic Project Detection
+
+Attempt automatic detection from files in the workspace:
+
+```text
+Detection targets:
+├── package.json     → Framework and dependencies
+├── tsconfig.json    → TypeScript usage
+├── tailwind.config  → Tailwind CSS
+├── next.config      → Next.js
+├── vite.config      → Vite
+├── nuxt.config      → Nuxt
+└── src/ or app/     → Source directory
+```
+
+### 1.4 Identifying Styling Method
+
+| Method            | Detection           | Edit Target                 |
+| ----------------- | ------------------- | --------------------------- |
+| Pure CSS          | `*.css` files       | Global CSS or component CSS |
+| SCSS/Sass         | `*.scss`, `*.sass`  | SCSS files                  |
+| CSS Modules       | `*.module.css`      | Module CSS files            |
+| Tailwind CSS      | `tailwind.config.*` | className in components     |
+| styled-components | `styled.` in code   | JS/TS files                 |
+| Emotion           | `@emotion/` imports | JS/TS files                 |
+| CSS-in-JS (other) | Inline styles       | JS/TS files                 |
+
+---
+
+## Step 2: Visual Inspection Phase
+
+### 2.1 Page Traversal
+
+1. Navigate to the specified URL
+2. Capture screenshots
+3. Retrieve DOM structure/snapshot (if possible)
+4. If additional pages exist, traverse through navigation
+
+### 2.2 Inspection Items
+
+#### Layout Issues
+
+| Issue                | Description                                       | Severity |
+| -------------------- | ------------------------------------------------- | -------- |
+| Element Overflow     | Content overflows from parent element or viewport | High     |
+| Element Overlap      | Unintended overlapping of elements                | High     |
+| Alignment Issues     | Grid or flex alignment problems                   | Medium   |
+| Inconsistent Spacing | Padding/margin inconsistencies                    | Medium   |
+| Text Clipping        | Long text not handled properly                    | Medium   |
+
+#### Responsive Issues
+
+| Issue               | Description                                    | Severity |
+| ------------------- | ---------------------------------------------- | -------- |
+| Non-mobile Friendly | Layout breaks on small screens                 | High     |
+| Breakpoint Issues   | Unnatural transitions when screen size changes | Medium   |
+| Touch Targets       | Buttons too small on mobile                    | Medium   |
+
+#### Accessibility Issues
+
+| Issue                 | Description                                       | Severity |
+| --------------------- | ------------------------------------------------- | -------- |
+| Insufficient Contrast | Low contrast ratio between text and background    | High     |
+| No Focus State        | Cannot determine state during keyboard navigation | High     |
+| Missing alt Text      | No alternative text for images                    | Medium   |
+
+#### Visual Consistency
+
+| Issue                 | Description                                  | Severity |
+| --------------------- | -------------------------------------------- | -------- |
+| Font Inconsistency    | Mixed font families                          | Medium   |
+| Color Inconsistency   | Non-unified brand colors                     | Medium   |
+| Spacing Inconsistency | Non-uniform spacing between similar elements | Low      |
+
+### 2.3 Viewport Testing (Responsive)
+
+Test at the following viewports:
+
+| Name    | Width  | Representative Device |
+| ------- | ------ | --------------------- |
+| Mobile  | 375px  | iPhone SE/12 mini     |
+| Tablet  | 768px  | iPad                  |
+| Desktop | 1280px | Standard PC           |
+| Wide    | 1920px | Large display         |
+
+---
+
+## Step 3: Issue Fixing Phase
+
+### 3.1 Issue Prioritization
+
+```mermaid
+block-beta
+    columns 1
+    block:priority["Priority Matrix"]
+        P1["P1: Fix Immediately\n(Layout issues affecting functionality)"]
+        P2["P2: Fix Next\n(Visual issues degrading UX)"]
+        P3["P3: Fix If Possible\n(Minor visual inconsistencies)"]
+    end
+```
+
+### 3.2 Identifying Source Files
+
+Identify source files from problematic elements:
+
+1. **Selector-based Search**
+   - Search codebase by class name or ID
+   - Explore style definitions with `grep_search`
+
+2. **Component-based Search**
+   - Identify components from element text or structure
+   - Explore related files with `semantic_search`
+
+3. **File Pattern Filtering**
+
+   ```text
+   Style files: src/**/*.css, styles/**/*
+   Components: src/components/**/*
+   Pages: src/pages/**, app/**
+   ```
+
+### 3.3 Applying Fixes
+
+#### Framework-specific Fix Guidelines
+
+See [references/framework-fixes.md](references/framework-fixes.md) for details.
+
+#### Fix Principles
+
+1. **Minimal Changes**: Only make the minimum changes necessary to resolve the issue
+2. **Respect Existing Patterns**: Follow existing code style in the project
+3. **Avoid Breaking Changes**: Be careful not to affect other areas
+4. **Add Comments**: Add comments to explain the reason for fixes where appropriate
+
+---
+
+## Step 4: Re-verification Phase
+
+### 4.1 Post-fix Confirmation
+
+1. Reload browser (or wait for development server HMR)
+2. Capture screenshots of fixed areas
+3. Compare before and after
+
+### 4.2 Regression Testing
+
+- Verify that fixes haven't affected other areas
+- Confirm responsive display is not broken
+
+### 4.3 Iteration Decision
+
+```mermaid
+flowchart TD
+    A{Issues Remaining?}
+    A -->|Yes| B[Return to Step 2]
+    A -->|No| C[Proceed to Completion Report]
+```
+
+**Iteration Limit**: If more than 3 fix attempts are needed for a specific issue, consult the user
+
+---
+
+## Output Format
+
+### Review Results Report
+
+```markdown
+# Web Design Review Results
+
+## Summary
+
+| Item             | Value                   |
+| ---------------- | ----------------------- |
+| Target URL       | {URL}                   |
+| Framework        | {Detected framework}    |
+| Styling          | {CSS / Tailwind / etc.} |
+| Tested Viewports | Desktop, Mobile         |
+| Issues Detected  | {N}                     |
+| Issues Fixed     | {M}                     |
+
+## Detected Issues
+
+### [P1] {Issue Title}
+
+- **Page**: {Page path}
+- **Element**: {Selector or description}
+- **Issue**: {Detailed description of the issue}
+- **Fixed File**: `{File path}`
+- **Fix Details**: {Description of changes}
+- **Screenshot**: Before/After
+
+### [P2] {Issue Title}
+
+...
+
+## Unfixed Issues (if any)
+
+### {Issue Title}
+
+- **Reason**: {Why it was not fixed/could not be fixed}
+- **Recommended Action**: {Recommendations for user}
+
+## Recommendations
+
+- {Suggestions for future improvements}
+```
+
+---
+
+## Required Capabilities
+
+| Capability          | Description                     | Required           |
+| ------------------- | ------------------------------- | ------------------ |
+| Web Page Navigation | Access URLs, page transitions   | ✅                 |
+| Screenshot Capture  | Page image capture              | ✅                 |
+| Image Analysis      | Visual issue detection          | ✅                 |
+| DOM Retrieval       | Page structure retrieval        | Recommended        |
+| File Read/Write     | Source code reading and editing | Required for fixes |
+| Code Search         | Code search within project      | Required for fixes |
+
+---
+
+## Reference Implementation
+
+### Implementation with Playwright MCP
+
+[Playwright MCP](https://github.com/microsoft/playwright-mcp) is recommended as the reference implementation for this skill.
+
+| Capability | Playwright MCP Tool        | Purpose                            |
+| ---------- | -------------------------- | ---------------------------------- |
+| Navigation | `browser_navigate`         | Access URLs                        |
+| Snapshot   | `browser_snapshot`         | Retrieve DOM structure             |
+| Screenshot | `browser_take_screenshot`  | Images for visual inspection       |
+| Click      | `browser_click`            | Interact with interactive elements |
+| Resize     | `browser_resize`           | Responsive testing                 |
+| Console    | `browser_console_messages` | Detect JS errors                   |
+
+#### Configuration Example (MCP Server)
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest", "--caps=vision"]
+    }
+  }
+}
+```
+
+### Other Compatible Browser Automation Tools
+
+| Tool           | Features                                      |
+| -------------- | --------------------------------------------- |
+| Selenium       | Broad browser support, multi-language support |
+| Puppeteer      | Chrome/Chromium focused, Node.js              |
+| Cypress        | Easy integration with E2E testing             |
+| WebDriver BiDi | Standardized next-generation protocol         |
+
+The same workflow can be implemented with these tools. As long as they provide the necessary capabilities (navigation, screenshot, DOM retrieval), the choice of tool is flexible.
+
+---
+
+## Best Practices
+
+### DO (Recommended)
+
+- ✅ Always save screenshots before making fixes
+- ✅ Fix one issue at a time and verify each
+- ✅ Follow the project's existing code style
+- ✅ Confirm with user before major changes
+- ✅ Document fix details thoroughly
+
+### DON'T (Not Recommended)
+
+- ❌ Large-scale refactoring without confirmation
+- ❌ Ignoring design systems or brand guidelines
+- ❌ Fixes that ignore performance
+- ❌ Fixing multiple issues at once (difficult to verify)
+
+---
+
+## Troubleshooting
+
+### Problem: Style files not found
+
+1. Check dependencies in `package.json`
+2. Consider the possibility of CSS-in-JS
+3. Consider CSS generated at build time
+4. Ask user about styling method
+
+### Problem: Fixes not reflected
+
+1. Check if development server HMR is working
+2. Clear browser cache
+3. Rebuild if project requires build
+4. Check CSS specificity issues
+
+### Problem: Fixes affecting other areas
+
+1. Rollback changes
+2. Use more specific selectors
+3. Consider using CSS Modules or scoped styles
+4. Consult user to confirm impact scope

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

@@ -0,0 +1,127 @@
+---
+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.
+
+## 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

package/core/skills/webapp-testing/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/core/templates/CLAUDE.md.tmpl

@@ -0,0 +1,98 @@
+# {{PROJECT_NAME}} — Claude Code working notes
+
+{{PROJECT_DESCRIPTION}}
+
+This file is loaded into every Claude Code session in this repo. Keep it tight; link out to `docs/` for depth.
+
+## Communication
+
+Layer these on top of the system defaults:
+
+- Factual tone. Don't say "fixed!" / "works!" — say "changes applied" or "ready for testing". **Ship ≠ verified** until the human confirms end-to-end.
+- Push back on weak assumptions instead of agreeing politely.
+- No PII in logs. No ad-hoc loggers in production app code — use the project's logging convention. Log route templates, not raw paths. Never log tokens, cookies, email addresses, IPs, or authorization headers.
+
+## Model strategy
+
+{{MODEL_STRATEGY}}
+
+{{STACK_FRAGMENTS}}
+
+## Code review (local, before push)
+
+Review happens **locally before `git push`** — run a local code review with the built-in `/code-review` skill so PRs open already-reviewed.
+
+```bash
+git fetch origin   # so origin/main is current before scoping the diff
+# then run a local code review with the built-in /code-review skill against origin/main
+```
+
+Triage: fix **Critical** + **Warning**; **Info** at discretion. Cap at ~2 passes. Compare against `origin/main`, not local `main` (local main is often stale). For deeper passes the built-in `/security-review` command is also available. Skill: [`.claude/skills/code-review/SKILL.md`](.claude/skills/code-review/SKILL.md).
+
+## Git / PR conventions
+
+- **Never** `git push origin main`. Direct main commits go via PR.
+- **Open PRs as draft** (`gh pr create --draft`); mark Ready only after the local CLI review is resolved and checks are green.
+- Branches: `agent/<phase-or-project-slug>` for batches, `agent/<n>-<slug>` for single-issue work.
+- Commit messages: `type(scope): subject (#issue)`. Types: `feat | fix | chore | docs | test | refactor | style | perf | build | ci | revert`. No `enh:` — use `feat:`.
+- PR closes syntax: **one keyword per line**. `Closes #1, #2` only closes #1 — use `Closes #1` then `Closes #2` on separate lines.
+- Stacked branches: after each upstream merge, `git fetch origin && git rebase origin/main`; already-applied commits → `git rebase --skip`; then `git push --force-with-lease`. **Never** `git push --force`.
+- Write PR/issue/commit bodies to a file under `tmp/` with the Write tool, then pass `--body-file`/`--file`. **No heredocs** — they mangle newlines.
+- Commit/push only when the user asks. End commit messages with the `Co-Authored-By: Claude` trailer.
+
+## Filing issues
+
+1. **Investigate first** — search, root cause, real fix. No band-aids.
+2. **Write the body to `tmp/issue-body-{slug}.md`** with the Write tool (no heredocs).
+3. **Create with `gh`**: `gh issue create --body-file tmp/issue-body-{slug}.md`.
+4. Report back: issue number, URL, short RCA + fix summary, labels.
+
+Quality over speed. Typos / one-liners — just fix.
+
+## Tool preference order
+
+Prefer the most direct, scriptable tool first; fall back to MCP, then manual:
+
+| Need                          | First                            | Fallback                                    |
+| ----------------------------- | -------------------------------- | ------------------------------------------- |
+| GitHub issues / PRs / Actions | `gh` CLI                         | `github` MCP (when `gh` auth/network fails) |
+| GitHub ProjectV2 (boards)     | `gh project` / `gh api graphql`  | — MCP can't do ProjectV2                    |
+| Browser automation (testing)  | `playwright` MCP                 | direct Playwright API                       |
+| Browser debugging (UI)        | `chrome-devtools` MCP            | manual DevTools                             |
+
+General rule: **gh CLI > MCP > manual/UI fallback.**
+
+## MCP servers
+
+{{MCP_SERVERS}}
+
+Project-scoped config lives in [`.mcp.json`](.mcp.json). Approve each server on first startup.
+
+## Slash commands
+
+Imported into [`.claude/commands/`](.claude/commands/):
+
+{{COMMANDS_LIST}}
+
+## Hooks
+
+A `PostToolUse` hook on `Edit|Write|MultiEdit` runs `.claude/hooks/post-edit-reminders.sh`, which emits one-time nudges after edits to sensitive files. It is wired in [`.claude/settings.json`](.claude/settings.json).
+
+## Memory & rules
+
+When the user says "remember this" / "create a rule" — drop a memory file in the memory dir (format in the system prompt). If the guidance should apply to **anyone** in this repo, add it here or to a nested `CLAUDE.md` instead. Don't ask first — "remember" means write it.
+
+## Lessons
+
+{{LESSONS_NOTE}}
+
+<!--
+  ENGSYS:PROJECT-FACTS region.
+  The installer (and/or the model during init) fills the block below with project-specific
+  facts: stack details, service names, conventions, key paths, north star, etc.
+  `engsys update` regenerates everything OUTSIDE this region but NEVER overwrites what's
+  between the START and END markers. Hand-edit freely inside it.
+-->
+<!-- ENGSYS:PROJECT-FACTS:START -->
+{{PROJECT_FACTS}}
+<!-- ENGSYS:PROJECT-FACTS:END -->