buildwithjpegg 1.0.0

package/skills/auto-release/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: auto-release
+description: One-time setup that wires semantic-release into a repository for automated versioning, changelog generation, and GitHub releases from conventional commits. Use when setting up a new repo that will be publicly released.
+disable-model-invocation: true
+---
+
+# Semantic Release Setup
+
+Automates version bumping, changelog generation, and GitHub release creation from conventional commit history.
+
+**Announce at start:** "Setting up semantic-release for automated versioning."
+
+## What This Does
+
+After setup, every merge to `main` that contains at least one `feat:` or `fix:` commit will:
+- Determine the next version automatically (`feat` → minor, `fix` → patch, `BREAKING CHANGE` → major)
+- Generate/update `CHANGELOG.md`
+- Bump the version in `package.json` (or equivalent config files)
+- Create a GitHub release with generated release notes
+- Tag the commit with the version
+
+## Step 1: Identify the project type
+
+Check what config files exist to determine version file locations:
+
+```bash
+ls package.json pyproject.toml Cargo.toml tauri.conf.json 2>/dev/null
+```
+
+Note which files contain version numbers -- they all need to be updated on release.
+
+## Step 2: Install semantic-release
+
+For Node.js projects (or projects using it as a dev tool):
+
+```bash
+pnpm add -D semantic-release \
+  @semantic-release/changelog \
+  @semantic-release/git \
+  @semantic-release/github \
+  @semantic-release/exec
+```
+
+For Python projects without a package.json, create a minimal one:
+
+```json
+{
+  "name": "<project-name>",
+  "private": true,
+  "devDependencies": {}
+}
+```
+
+Then run the pnpm install above.
+
+## Step 3: Create `.releaserc.json`
+
+Adapt to the project's version file locations:
+
+```json
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "node .semantic-release/bump-versions.js ${nextRelease.version}"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["CHANGELOG.md", "package.json", "<other version files>"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}
+```
+
+## Step 4: Create version bump script
+
+For projects with multiple version files, create `.semantic-release/bump-versions.js`:
+
+```javascript
+const fs = require('fs');
+const version = process.argv[2];
+
+// Example: bump version in tauri.conf.json
+const tauriConf = JSON.parse(fs.readFileSync('src-tauri/tauri.conf.json', 'utf8'));
+tauriConf.version = version;
+fs.writeFileSync('src-tauri/tauri.conf.json', JSON.stringify(tauriConf, null, 2));
+
+// Example: bump version in Cargo.toml (simple string replace)
+let cargo = fs.readFileSync('src-tauri/Cargo.toml', 'utf8');
+cargo = cargo.replace(/^version = ".*"/m, `version = "${version}"`);
+fs.writeFileSync('src-tauri/Cargo.toml', cargo);
+
+console.log(`Bumped to ${version}`);
+```
+
+Adapt this to the actual version files in the project.
+
+## Step 5: Add GitHub Actions workflow
+
+Create `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: pnpm exec semantic-release
+```
+
+**Note:** If the existing release workflow already handles binary builds (Tauri, native apps), integrate semantic-release as the version-determination step that runs *before* the build, not as a replacement for the entire workflow. In that case, use `semantic-release` in `--dry-run` mode to get the next version, pass it to the build, then tag after a successful build.
+
+## Step 6: Add `CHANGELOG.md` to `.gitignore` exceptions
+
+If `CHANGELOG.md` is currently gitignored, remove it. semantic-release commits it.
+
+## Step 7: Verify
+
+```bash
+# Dry run to confirm configuration is valid
+pnpm exec semantic-release --dry-run
+```
+
+Check output for errors. Common issues:
+- Missing `GITHUB_TOKEN` locally (expected -- it runs in CI only)
+- Version files not found by bump script
+- Branch name mismatch
+
+## What NOT to change
+
+Do not modify the existing deploy/release scripts unless the user explicitly asks. semantic-release adds automated versioning on top of the existing workflow -- it does not replace CI/CD pipelines or build processes.
+
+## After Setup
+
+The manual version bump step in `deploy-application.sh` (or equivalent) can be removed once you confirm semantic-release is working correctly. Do not remove it until at least one automated release has succeeded.

package/skills/blueprint/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: blueprint
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+---
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the blueprint skill to create the implementation plan."
+
+**Context:** This should be run in a dedicated worktree (created by evaluate skill).
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use jpegg:build to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## Remember
+- Exact file paths always
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- Reference relevant skills with @ syntax
+- DRY, YAGNI, TDD, frequent commits
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete and saved to `docs/plans/<filename>.md`. Two execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
+
+**2. Parallel Session (separate)** - Open new session with build, batch execution with checkpoints
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- **REQUIRED SUB-SKILL:** Use jpegg:delegate
+- Stay in this session
+- Fresh subagent per task + code review
+
+**If Parallel Session chosen:**
+- Guide them to open new session in worktree
+- **REQUIRED SUB-SKILL:** New session uses jpegg:build

package/skills/build/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: build
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute tasks in batches, report for review between batches.
+
+**Core principle:** Batch execution with checkpoints for architect review.
+
+**Announce at start:** "I'm using the build skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Batch
+**Default: First 3 tasks**
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Report
+When batch complete:
+- Show what was implemented
+- Show verification output
+- Say: "Ready for feedback."
+
+### Step 4: Continue
+Based on feedback:
+- Apply changes if needed
+- Execute next batch
+- Repeat until complete
+
+### Step 5: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the wrap-up skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use jpegg:wrap-up
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Between batches: just report and wait
+- Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- **jpegg:worktree** - REQUIRED: Set up isolated workspace before starting
+- **jpegg:blueprint** - Creates the plan this skill executes
+- **jpegg:wrap-up** - Complete development after all tasks

package/skills/ci-loop/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: ci-loop
+description: Use after creating a PR to monitor CI and automatically fix failures before reporting back. Fires automatically after PR creation. Do not report the PR as ready until CI is green.
+---
+
+# CI Watch and Fix
+
+**Announce at start:** "Monitoring CI for this PR -- will fix any failures before reporting back."
+
+## Current PR Context
+- Branch: !`git branch --show-current`
+- Open PRs: !`gh pr list --head $(git branch --show-current) --json number,title,url,statusCheckRollup 2>/dev/null`
+
+## Process
+
+### Step 1: Wait for CI to start
+
+```bash
+gh run list --branch $(git branch --show-current) --limit 5
+```
+
+If no runs found yet, wait 15 seconds and retry. CI may not have triggered immediately after push.
+
+### Step 2: Watch the run
+
+```bash
+# Get the most recent run ID
+RUN_ID=$(gh run list --branch $(git branch --show-current) --limit 1 --json databaseId -q '.[0].databaseId')
+
+# Watch it to completion
+gh run watch $RUN_ID
+```
+
+### Step 3: Check the result
+
+```bash
+gh run view $RUN_ID --json conclusion -q '.conclusion'
+```
+
+**If `success`:** Report back. CI is green. PR is ready for review.
+
+**If `failure`:** Proceed to Step 4.
+
+**If `cancelled` or `skipped`:** Note it and report -- do not attempt to fix.
+
+### Step 4: Diagnose the failure
+
+```bash
+# Get failed job details
+gh run view $RUN_ID --log-failed
+```
+
+Read the full failure output. Identify:
+- Which job failed
+- The exact error message and file/line if available
+- Whether it is a test failure, lint error, type error, or build error
+
+### Step 5: Fix the failure
+
+Apply the minimal fix. Do not refactor surrounding code.
+
+For test failures: check if the test expectation is wrong (requirement changed) or the implementation is wrong. Fix the right one.
+
+For lint/type errors: fix the specific violation only.
+
+After fixing:
+
+```bash
+git add <changed files>
+git commit -m "fix: address CI failure -- <brief description>"
+git push
+```
+
+### Step 6: Repeat
+
+Go back to Step 1. Watch the new run triggered by the push.
+
+**Attempt limit:** After 3 fix attempts with continued failures, stop and report:
+
+```
+CI is still failing after 3 fix attempts.
+
+Failing job: <name>
+Error: <message>
+
+Cannot resolve automatically -- needs your attention.
+PR: <url>
+```
+
+## When CI is Green
+
+Report back concisely:
+
+```
+CI passed. PR is ready for review: <url>
+```
+
+Do not summarize what was fixed unless asked.