buildwithjpegg 1.0.0

package/lib/skills-core.js

@@ -0,0 +1,208 @@
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+/**
+ * Extract YAML frontmatter from a skill file.
+ * Current format:
+ * ---
+ * name: skill-name
+ * description: Use when [condition] - [what it does]
+ * ---
+ *
+ * @param {string} filePath - Path to SKILL.md file
+ * @returns {{name: string, description: string}}
+ */
+function extractFrontmatter(filePath) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf8');
+        const lines = content.split('\n');
+
+        let inFrontmatter = false;
+        let name = '';
+        let description = '';
+
+        for (const line of lines) {
+            if (line.trim() === '---') {
+                if (inFrontmatter) break;
+                inFrontmatter = true;
+                continue;
+            }
+
+            if (inFrontmatter) {
+                const match = line.match(/^(\w+):\s*(.*)$/);
+                if (match) {
+                    const [, key, value] = match;
+                    switch (key) {
+                        case 'name':
+                            name = value.trim();
+                            break;
+                        case 'description':
+                            description = value.trim();
+                            break;
+                    }
+                }
+            }
+        }
+
+        return { name, description };
+    } catch (error) {
+        return { name: '', description: '' };
+    }
+}
+
+/**
+ * Find all SKILL.md files in a directory recursively.
+ *
+ * @param {string} dir - Directory to search
+ * @param {string} sourceType - 'personal' or 'buildwithjpegg' for namespacing
+ * @param {number} maxDepth - Maximum recursion depth (default: 3)
+ * @returns {Array<{path: string, name: string, description: string, sourceType: string}>}
+ */
+function findSkillsInDir(dir, sourceType, maxDepth = 3) {
+    const skills = [];
+
+    if (!fs.existsSync(dir)) return skills;
+
+    function recurse(currentDir, depth) {
+        if (depth > maxDepth) return;
+
+        const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+
+            if (entry.isDirectory()) {
+                // Check for SKILL.md in this directory
+                const skillFile = path.join(fullPath, 'SKILL.md');
+                if (fs.existsSync(skillFile)) {
+                    const { name, description } = extractFrontmatter(skillFile);
+                    skills.push({
+                        path: fullPath,
+                        skillFile: skillFile,
+                        name: name || entry.name,
+                        description: description || '',
+                        sourceType: sourceType
+                    });
+                }
+
+                // Recurse into subdirectories
+                recurse(fullPath, depth + 1);
+            }
+        }
+    }
+
+    recurse(dir, 0);
+    return skills;
+}
+
+/**
+ * Resolve a skill name to its file path, handling shadowing
+ * (personal skills override buildwithjpegg skills).
+ *
+ * @param {string} skillName - Name like "jpegg:evaluate" or "my-skill"
+ * @param {string} pluginDir - Path to buildwithjpegg skills directory
+ * @param {string} personalDir - Path to personal skills directory
+ * @returns {{skillFile: string, sourceType: string, skillPath: string} | null}
+ */
+function resolveSkillPath(skillName, pluginDir, personalDir) {
+    // Strip jpegg: prefix if present
+    const forcePlugin = skillName.startsWith('jpegg:');
+    const actualSkillName = forcePlugin ? skillName.replace(/^jpegg:/, '') : skillName;
+
+    // Try personal skills first (unless explicitly jpegg:)
+    if (!forcePlugin && personalDir) {
+        const personalPath = path.join(personalDir, actualSkillName);
+        const personalSkillFile = path.join(personalPath, 'SKILL.md');
+        if (fs.existsSync(personalSkillFile)) {
+            return {
+                skillFile: personalSkillFile,
+                sourceType: 'personal',
+                skillPath: actualSkillName
+            };
+        }
+    }
+
+    // Try buildwithjpegg skills
+    if (pluginDir) {
+        const pluginPath = path.join(pluginDir, actualSkillName);
+        const pluginSkillFile = path.join(pluginPath, 'SKILL.md');
+        if (fs.existsSync(pluginSkillFile)) {
+            return {
+                skillFile: pluginSkillFile,
+                sourceType: 'buildwithjpegg',
+                skillPath: actualSkillName
+            };
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Check if a git repository has updates available.
+ *
+ * @param {string} repoDir - Path to git repository
+ * @returns {boolean} - True if updates are available
+ */
+function checkForUpdates(repoDir) {
+    try {
+        // Quick check with 3 second timeout to avoid delays if network is down
+        const output = execSync('git fetch origin && git status --porcelain=v1 --branch', {
+            cwd: repoDir,
+            timeout: 3000,
+            encoding: 'utf8',
+            stdio: 'pipe'
+        });
+
+        // Parse git status output to see if we're behind
+        const statusLines = output.split('\n');
+        for (const line of statusLines) {
+            if (line.startsWith('## ') && line.includes('[behind ')) {
+                return true; // We're behind remote
+            }
+        }
+        return false; // Up to date
+    } catch (error) {
+        // Network down, git error, timeout, etc. - don't block bootstrap
+        return false;
+    }
+}
+
+/**
+ * Strip YAML frontmatter from skill content, returning just the content.
+ *
+ * @param {string} content - Full content including frontmatter
+ * @returns {string} - Content without frontmatter
+ */
+function stripFrontmatter(content) {
+    const lines = content.split('\n');
+    let inFrontmatter = false;
+    let frontmatterEnded = false;
+    const contentLines = [];
+
+    for (const line of lines) {
+        if (line.trim() === '---') {
+            if (inFrontmatter) {
+                frontmatterEnded = true;
+                continue;
+            }
+            inFrontmatter = true;
+            continue;
+        }
+
+        if (frontmatterEnded || !inFrontmatter) {
+            contentLines.push(line);
+        }
+    }
+
+    return contentLines.join('\n').trim();
+}
+
+export {
+    extractFrontmatter,
+    findSkillsInDir,
+    resolveSkillPath,
+    checkForUpdates,
+    stripFrontmatter
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "buildwithjpegg",
+  "version": "1.0.0",
+  "description": "Development workflow skills for Claude Code: TDD, debugging, collaboration patterns, and proven techniques",
+  "author": "jpegg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jpeggdev/buildwithjpegg.git"
+  },
+  "homepage": "https://github.com/jpeggdev/buildwithjpegg",
+  "bugs": {
+    "url": "https://github.com/jpeggdev/buildwithjpegg/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "skills",
+    "tdd",
+    "debugging",
+    "collaboration",
+    "best-practices",
+    "workflows",
+    "ai-agent"
+  ],
+  "files": [
+    "agents/",
+    "commands/",
+    "hooks/",
+    "lib/",
+    "rules/",
+    "skills/",
+    ".claude-plugin/",
+    ".codex/",
+    ".opencode/",
+    "LICENSE",
+    "README.md",
+    "RELEASE-NOTES.md"
+  ]
+}

package/rules/conventions.md

@@ -0,0 +1,22 @@
+# Project Conventions
+
+## Package Manager
+
+Use `pnpm` for all package management commands (not npm or yarn).
+
+Exception: Global install instructions for end users should use `npm install -g` since it's universal.
+
+## Dependencies
+
+Always check for the latest npm version when adding dependencies. Use `pnpm add <package>` (without version) to get the latest, or verify with `npm view <package> version` first.
+
+## No Emojis
+
+Do not use emojis anywhere (code, comments, output, docs).
+
+## Docs Updates
+
+When a change affects how humans or agents use a codebase (new/changed/removed commands, flags, behavior, or config), update all of these:
+
+1. `README.md` -- user-facing documentation
+2. `CLAUDE.md` -- agent-facing documentation

package/rules/git.md

@@ -0,0 +1,18 @@
+# Git Conventions
+
+## Commits
+- Conventional commits: `type(scope): message`
+- Types: feat, fix, refactor, test, docs, chore, ci
+- Message in imperative mood, lowercase, no period
+- Keep commits atomic -- one logical change per commit
+
+## Branches
+- `main` is production
+- Feature branches: `feat/short-description`
+- Fix branches: `fix/short-description`
+- Never force-push to main
+
+## PRs
+- Title matches conventional commit format
+- Body: summary bullets + test plan
+- Squash merge to main

package/rules/mcp-servers.md

@@ -0,0 +1,28 @@
+# MCP Server Configuration
+
+On Windows, MCP servers using npx must go through `cmd /c` since MINGW64 bash cannot run npx directly as a stdio command.
+
+**Pattern:**
+```json
+"<server-name>": {
+    "type": "stdio",
+    "command": "cmd",
+    "args": ["/c", "npx", "-y", "<package>@latest"],
+    "env": {}
+}
+```
+
+**Example (Context7):**
+```json
+"context7": {
+    "type": "stdio",
+    "command": "cmd",
+    "args": ["/c", "npx", "-y", "@upstash/context7-mcp@latest"],
+    "env": {}
+}
+```
+
+Key points:
+- Always use `"command": "cmd"` with `"/c"` as the first arg.
+- Use `-y` with npx to auto-confirm install prompts.
+- The `env` object can pass environment variables the server needs (API keys, etc.).

package/rules/platform.md

@@ -0,0 +1,10 @@
+# Platform specific
+
+On Windows (MINGW64/Git Bash):
+
+- Use forward slashes in paths for cross-platform compatibility.
+- Shell commands run in bash (MINGW64), not cmd.exe or PowerShell.
+- Avoid `NUL` -- use `/dev/null` instead.
+- Quote paths containing spaces with double quotes.
+- The `/c` flag for cmd.exe must not be converted to `C:/`.
+- Always test MCP server registrations and hook commands for Windows compatibility.

package/rules/stack.md

@@ -0,0 +1,29 @@
+# Default Tech Stack
+
+When starting a new project or the user hasn't specified preferences:
+
+## Desktop Applications (default for this workspace)
+- **Language**: Python for everything — UI and backend in one language
+- **UI framework**: Flet (Python + Flutter renderer) — `flet build` produces native binaries
+- **Embedded server**: aiohttp or FastAPI for the local HTTP server
+- **Database**: SQLite via `aiosqlite` for async access, raw `sqlite3` for sync
+- **Validation**: Pydantic
+- **Templates**: Jinja2
+- **Testing**: pytest + pytest-asyncio
+- **MCP integration**: Official Anthropic MCP Python SDK
+- **Packaging**: `flet build windows/macos/linux` for native binaries
+
+## Web Applications
+- **Language**: TypeScript for everything
+- **Frontend**: React + Next.js (App Router), Tailwind CSS, Zustand or TanStack Query
+- **Backend**: Hono (lightweight) or Next.js API routes, PostgreSQL + Drizzle ORM, Zod
+- **Testing**: Vitest + Testing Library + Playwright
+
+## Infra (both)
+- GitHub Actions for CI/CD
+- Docker + Docker Compose for services that need it
+
+## AI/ML
+- Anthropic SDK (Claude) as primary LLM — Python or TypeScript depending on project type
+
+Always ask before deviating from these defaults on new projects.

package/rules/testing.md

@@ -0,0 +1,18 @@
+# Testing Conventions
+
+## Philosophy
+- Test behavior, not implementation
+- Integration tests over unit tests for most code
+- Unit tests for pure logic and edge cases
+- E2E tests for critical user flows only
+
+## Approach
+- New features: write tests alongside implementation
+- Bug fixes: write a failing test first, then fix
+- Refactors: ensure tests pass before and after
+
+## Tools (defaults)
+- Vitest for unit/integration
+- Playwright for E2E
+- Testing Library for component tests
+- pytest for Python projects

package/rules/ui-ux.md

@@ -0,0 +1,151 @@
+# UI/UX Guidelines
+
+Concise rules for building accessible, fast, delightful UIs. Use MUST/SHOULD/NEVER to guide decisions.
+
+## Interactions
+
+### Keyboard
+
+- MUST: Full keyboard support per [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/)
+- MUST: Visible focus rings (`:focus-visible`; group with `:focus-within`)
+- MUST: Manage focus (trap, move, return) per APG patterns
+- NEVER: `outline: none` without visible focus replacement
+
+### Targets & Input
+
+- MUST: Hit target >=24px (mobile >=44px); if visual <24px, expand hit area
+- MUST: Mobile `<input>` font-size >=16px to prevent iOS zoom
+- NEVER: Disable browser zoom (`user-scalable=no`, `maximum-scale=1`)
+- MUST: `touch-action: manipulation` to prevent double-tap zoom
+- SHOULD: Set `-webkit-tap-highlight-color` to match design
+
+### Forms
+
+- MUST: Hydration-safe inputs (no lost focus/value)
+- NEVER: Block paste in `<input>`/`<textarea>`
+- MUST: Loading buttons show spinner and keep original label
+- MUST: Enter submits focused input; in `<textarea>`, Cmd/Ctrl+Enter submits
+- MUST: Keep submit enabled until request starts; then disable with spinner
+- MUST: Accept free text, validate after--don't block typing
+- MUST: Allow incomplete form submission to surface validation
+- MUST: Errors inline next to fields; on submit, focus first error
+- MUST: `autocomplete` + meaningful `name`; correct `type` and `inputmode`
+- SHOULD: Disable spellcheck for emails/codes/usernames
+- SHOULD: Placeholders end with `...` and show example pattern
+- MUST: Warn on unsaved changes before navigation
+- MUST: Compatible with password managers & 2FA; allow pasting codes
+- MUST: Trim values to handle text expansion trailing spaces
+- MUST: No dead zones on checkboxes/radios; label+control share one hit target
+
+### State & Navigation
+
+- MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels)
+- MUST: Back/Forward restores scroll position
+- MUST: Links use `<a>`/`<Link>` for navigation (support Cmd/Ctrl/middle-click)
+- NEVER: Use `<div onClick>` for navigation
+
+### Feedback
+
+- SHOULD: Optimistic UI; reconcile on response; on failure rollback or offer Undo
+- MUST: Confirm destructive actions or provide Undo window
+- MUST: Use polite `aria-live` for toasts/inline validation
+- SHOULD: Ellipsis (`...`) for options opening follow-ups ("Rename...") and loading states ("Loading...")
+
+### Touch & Drag
+
+- MUST: Generous targets, clear affordances; avoid finicky interactions
+- MUST: Delay first tooltip; subsequent peers instant
+- MUST: `overscroll-behavior: contain` in modals/drawers
+- MUST: During drag, disable text selection and set `inert` on dragged elements
+- MUST: If it looks clickable, it must be clickable
+
+### Autofocus
+
+- SHOULD: Autofocus on desktop with single primary input; rarely on mobile
+
+## Animation
+
+- MUST: Honor `prefers-reduced-motion` (provide reduced variant or disable)
+- SHOULD: Prefer CSS > Web Animations API > JS libraries
+- MUST: Animate compositor-friendly props (`transform`, `opacity`) only
+- NEVER: Animate layout props (`top`, `left`, `width`, `height`)
+- NEVER: `transition: all`--list properties explicitly
+- SHOULD: Animate only to clarify cause/effect or add deliberate delight
+- SHOULD: Choose easing to match the change (size/distance/trigger)
+- MUST: Animations interruptible and input-driven (no autoplay)
+- MUST: Correct `transform-origin` (motion starts where it "physically" should)
+- MUST: SVG transforms on `<g>` wrapper with `transform-box: fill-box`
+
+## Layout
+
+- SHOULD: Optical alignment; adjust +/-1px when perception beats geometry
+- MUST: Deliberate alignment to grid/baseline/edges--no accidental placement
+- SHOULD: Balance icon/text lockups (weight/size/spacing/color)
+- MUST: Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom)
+- MUST: Respect safe areas (`env(safe-area-inset-*)`)
+- MUST: Avoid unwanted scrollbars; fix overflows
+- SHOULD: Flex/grid over JS measurement for layout
+
+## Content & Accessibility
+
+- SHOULD: Inline help first; tooltips last resort
+- MUST: Skeletons mirror final content to avoid layout shift
+- MUST: `<title>` matches current context
+- MUST: No dead ends; always offer next step/recovery
+- MUST: Design empty/sparse/dense/error states
+- SHOULD: Curly quotes; avoid widows/orphans (`text-wrap: balance`)
+- MUST: `font-variant-numeric: tabular-nums` for number comparisons
+- MUST: Redundant status cues (not color-only); icons have text labels
+- MUST: Accessible names exist even when visuals omit labels
+- MUST: Use `...` character (not `...` three dots)
+- MUST: `scroll-margin-top` on headings; "Skip to content" link; hierarchical `<h1>`-`<h6>`
+- MUST: Resilient to user-generated content (short/avg/very long)
+- MUST: Locale-aware dates/times/numbers (`Intl.DateTimeFormat`, `Intl.NumberFormat`)
+- MUST: Accurate `aria-label`; decorative elements `aria-hidden`
+- MUST: Icon-only buttons have descriptive `aria-label`
+- MUST: Prefer native semantics (`button`, `a`, `label`, `table`) before ARIA
+- MUST: Non-breaking spaces: `10&nbsp;MB`, `Cmd&nbsp;K`, brand names
+
+## Content Handling
+
+- MUST: Text containers handle long content (`truncate`, `line-clamp-*`, `break-words`)
+- MUST: Flex children need `min-w-0` to allow truncation
+- MUST: Handle empty states--no broken UI for empty strings/arrays
+
+## Performance
+
+- SHOULD: Test iOS Low Power Mode and macOS Safari
+- MUST: Measure reliably (disable extensions that skew runtime)
+- MUST: Track and minimize re-renders (React DevTools/React Scan)
+- MUST: Profile with CPU/network throttling
+- MUST: Batch layout reads/writes; avoid reflows/repaints
+- MUST: Mutations (`POST`/`PATCH`/`DELETE`) target <500ms
+- SHOULD: Prefer uncontrolled inputs; controlled inputs cheap per keystroke
+- MUST: Virtualize large lists (>50 items)
+- MUST: Preload above-fold images; lazy-load the rest
+- MUST: Prevent CLS (explicit image dimensions)
+- SHOULD: `<link rel="preconnect">` for CDN domains
+- SHOULD: Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
+
+## Dark Mode & Theming
+
+- MUST: `color-scheme: dark` on `<html>` for dark themes
+- SHOULD: `<meta name="theme-color">` matches page background
+- MUST: Native `<select>`: explicit `background-color` and `color` (Windows fix)
+
+## Hydration
+
+- MUST: Inputs with `value` need `onChange` (or use `defaultValue`)
+- SHOULD: Guard date/time rendering against hydration mismatch
+
+## Design
+
+- SHOULD: Layered shadows (ambient + direct)
+- SHOULD: Crisp edges via semi-transparent borders + shadows
+- SHOULD: Nested radii: child <= parent; concentric
+- SHOULD: Hue consistency: tint borders/shadows/text toward bg hue
+- MUST: Accessible charts (color-blind-friendly palettes)
+- MUST: Meet contrast--prefer [APCA](https://apcacontrast.com/) over WCAG 2
+- MUST: Increase contrast on `:hover`/`:active`/`:focus`
+- SHOULD: Match browser UI to bg
+- SHOULD: Avoid dark color gradient banding (use background images when needed)

package/rules/workflow.md

@@ -0,0 +1,48 @@
+# Development Workflow
+
+## Skill Invocation Sequence
+
+For any new feature or fix, skills fire in this order — do not skip steps:
+
+1. **`jpegg:evaluate`** — always first. Explores intent, asks clarifying questions, surfaces unstated requirements. Fires when a feature or fix is described.
+2. **`jpegg:blueprint`** — after evaluation. Produces the plan document. User reviews and approves before any code is written.
+3. **`jpegg:build`** — after plan approval. Works through the plan with PR-level checkpoints. One PR per logical chunk.
+
+Within each implementation chunk:
+
+4. **`jpegg:worktree`** — before writing code. Creates an isolated workspace for the branch.
+5. **`jpegg:test-first`** — before writing implementation code. Tests first, always.
+6. **`jpegg:pre-ship`** — before claiming done. Runs verification commands, reads actual output.
+7. **`jpegg:seek-review`** — before opening the PR. Internal review pass first.
+8. **`jpegg:draft-prs`** — when creating a PR in a stack. Downstream PRs are draft; promote on base merge.
+9. **`jpegg:ci-loop`** — after PR creation. Monitors CI and fixes failures before reporting back.
+10. **`jpegg:pr-stack`** — after every PR creation or merge. Updates `.claude/stack.json`.
+
+When receiving feedback on an open PR:
+
+11. **`jpegg:handle-review`** — fires before implementing any review comment. Evaluates feedback before acting.
+
+## Stacked PR Workflow
+
+- Each branch is created from the tip of the previous branch, not from `main`
+- Each PR targets the previous branch as its base, not `main`
+- Downstream PRs are always created as drafts until their base merges
+- When a base merges: rebase the next branch, update its PR base to `main`, promote from draft to ready
+- Session state is tracked in `.claude/stack.json` — read this at session start if it exists
+
+## Resuming After a Break
+
+1. Read `.claude/stack.json` to understand current stack state
+2. Read the plan document referenced in the stack file
+3. Check open PRs with `gh pr list`
+4. Continue from the current branch
+
+## After a PR is Merged
+
+When the user reports a PR is merged:
+1. `git fetch`
+2. Rebase the next branch in the stack onto `main`
+3. `git push --force-with-lease --force-if-includes`
+4. Update the PR base on GitHub: `gh pr edit <number> --base main`
+5. Promote from draft: `gh pr ready <number>`
+6. Update `.claude/stack.json`