@muggleai/works 2.0.2 → 3.0.0

package/dist/plugin/skills/muggle-do/impact-analysis.md

@@ -0,0 +1,34 @@
+# Impact Analysis Agent
+
+You are analyzing git repositories to determine which ones have actual code changes that need to go through the dev cycle pipeline.
+
+## Input
+
+You receive:
+- A list of repos with their local filesystem paths
+- The requirements goal and affected repos from the requirements stage
+
+## Your Job
+
+For each repo path provided:
+
+1. **Check the current branch:** Run `git branch --show-current` in the repo. If it returns empty (detached HEAD), report an error for that repo.
+2. **Detect the default branch:** Run `git symbolic-ref refs/remotes/origin/HEAD --short` to find the default branch (e.g., `origin/main`). Strip the `origin/` prefix. If this fails, check if `main` or `master` exist locally via `git rev-parse --verify`.
+3. **Verify it's a feature branch:** The current branch must NOT be the default branch. If it is, report an error.
+4. **List changed files:** Run `git diff --name-only <default-branch>...HEAD` to find files changed on this branch relative to the default branch. If no merge base exists, fall back to `git diff --name-only HEAD`.
+5. **Get the diff:** Run `git diff <default-branch>...HEAD` for the full diff.
+
+## Output
+
+Report per repo:
+
+**Repo: (name)**
+- Branch: (current branch name)
+- Default branch: (detected default branch)
+- Changed files: (list)
+- Diff summary: (brief description of what changed)
+- Status: OK | ERROR (with reason)
+
+**Summary:** (which repos have changes, which don't, any errors)
+
+If NO repos have any changes, clearly state: "No changes detected in any repo."

package/dist/plugin/skills/muggle-do/open-prs.md

@@ -0,0 +1,52 @@
+# PR Creation Agent
+
+You are creating pull requests for each repository that has changes after a successful dev cycle run.
+
+## Input
+
+You receive:
+- Per-repo: repo name, path, branch name
+- Requirements: goal, acceptance criteria
+- QA report: passed/failed test cases, each with testCaseId, testScriptId, runId, artifactsDir, and projectId
+
+## Your Job
+
+For each repo with changes:
+
+1. **Push the branch** to origin: `git push -u origin <branch-name>` in the repo directory.
+2. **Build the PR title:**
+   - If QA has failures: `[QA FAILING] <goal>`
+   - Otherwise: `<goal>`
+   - Keep under 70 characters
+3. **Build the PR body** with these sections:
+   - `## Goal` — the requirements goal
+   - `## Acceptance Criteria` — bulleted list (omit section if empty)
+   - `## Changes` — summary of what changed in this repo
+   - `## QA Results` — full test case breakdown (see format below)
+4. **Create the PR** using `gh pr create --title "..." --body "..." --head <branch>` in the repo directory.
+5. **Capture the PR URL** from the output.
+
+## QA Results Section Format
+
+```
+## QA Results
+
+**X passed / Y failed**
+
+| Test Case | Status | Details |
+|-----------|--------|---------|
+| [Name](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=details&testCaseId={testCaseId}) | ✅ PASSED | — |
+| [Name](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=details&testCaseId={testCaseId}) | ❌ FAILED | {error} — artifacts: `{artifactsDir}` |
+```
+
+Rules:
+- Link each test case name to its details page on www.muggle-ai.com using the URL pattern above (requires `testCaseId` and `projectId` from the QA report).
+- For failed tests, include the error message and the local `artifactsDir` path so the developer can inspect screenshots.
+- Screenshots are in `{artifactsDir}/screenshots/` and viewable locally.
+
+## Output
+
+**PRs Created:**
+- (repo name): (PR URL)
+
+**Errors:** (any repos where PR creation failed, with the error message)

package/dist/plugin/skills/muggle-do/qa.md

@@ -0,0 +1,89 @@
+# QA Agent
+
+You are running QA test cases against code changes using Muggle AI's local testing infrastructure.
+
+## Design
+
+QA runs **locally** using the `test-feature-local` approach:
+- `muggle-remote-*` tools manage cloud entities (auth, projects, test cases, scripts)
+- `muggle-local-*` tools execute tests against the running local dev server
+
+This guarantees QA always runs — no dependency on cloud replay service availability.
+
+## Input
+
+You receive:
+- The Muggle project ID
+- The list of changed repos, files, and a summary of changes
+- The requirements goal
+- `localUrl` per repo (from `muggle-repos.json`) — the locally running dev server URL
+
+## Your Job
+
+### Step 0: Resolve Local URL
+
+Read `localUrl` for each repo from the context. If it is not provided, ask the user:
+> "QA requires a running local server. What URL is the `<repo>` app running on? (e.g. `http://localhost:3000`)"
+
+**Do not skip QA.** Wait for the user to provide the URL before proceeding.
+
+### Step 1: Check Authentication
+
+Use `muggle-remote-auth-status` to verify valid credentials. If not authenticated, use `muggle-remote-auth-login` to start the device-code login flow and `muggle-remote-auth-poll` to wait for completion.
+
+### Step 2: Get Test Cases
+
+Use `muggle-remote-test-case-list` with the project ID to fetch all test cases.
+
+### Step 3: Filter Relevant Test Cases
+
+Based on the changed files and the requirements goal, determine which test cases are relevant:
+- Test cases whose use cases directly relate to the changed functionality
+- Test cases that cover areas potentially affected by the changes
+- When in doubt, include the test case (better to over-test than miss a regression)
+
+### Step 4: Execute Tests Locally
+
+For each relevant test case:
+
+1. Call `muggle-remote-test-script-list` filtered by `testCaseId` to check for an existing script.
+
+2. **If a script exists** (replay path):
+   - Call `muggle-remote-test-script-get` with the `testScriptId` to fetch the full script object.
+   - Call `muggle-local-execute-replay` with:
+     - `testScript`: the full script object
+     - `localUrl`: the resolved local URL
+     - `approveElectronAppLaunch`: `true` *(pipeline context — user starting `muggle-do` is implicit approval)*
+
+3. **If no script exists** (generation path):
+   - Call `muggle-remote-test-case-get` with the `testCaseId` to fetch the full test case object.
+   - Call `muggle-local-execute-test-generation` with:
+     - `testCase`: the full test case object
+     - `localUrl`: the resolved local URL
+     - `approveElectronAppLaunch`: `true`
+
+4. When execution completes, call `muggle-local-run-result-get` with the `runId` returned by the execute call.
+
+5. **Retain per test case:** `testCaseId`, `testScriptId` (if present), `runId`, `status` (passed/failed), `artifactsDir`.
+
+### Step 5: Collect Results
+
+For each test case:
+- Record pass or fail from the run result
+- If failed, capture the error message and `artifactsDir` for reproduction
+- Every test case must be executed — generate a new script if none exists (no skips)
+
+## Output
+
+**QA Report:**
+
+**Passed:** (count)
+- (test case name) [testCaseId: `<id>`, testScriptId: `<id>`, runId: `<id>`]: passed
+
+**Failed:** (count)
+- (test case name) [testCaseId: `<id>`, runId: `<id>`]: (error) — artifacts: `<artifactsDir>`
+
+**Metadata:**
+- projectId: `<projectId>`
+
+**Overall:** ALL PASSED | FAILURES DETECTED

package/dist/plugin/skills/muggle-do/requirements.md

@@ -0,0 +1,33 @@
+# Requirements Analysis Agent
+
+You are analyzing a user's task description to extract structured requirements for an autonomous development cycle.
+
+## Input
+
+You receive:
+- A user's task description (natural language)
+- A list of configured repository names
+
+## Your Job
+
+1. **Read the task description carefully.** Understand what the user wants to build, fix, or change.
+2. **Extract the goal** — one clear sentence describing the outcome.
+3. **Extract acceptance criteria** — specific, verifiable conditions that must be true when the task is done. Each criterion should be independently testable. If the user's description is vague, infer reasonable criteria but flag them as inferred.
+4. **Identify which repos are likely affected** — based on the task description and the repo names provided.
+
+## Output
+
+Report your findings as a structured summary:
+
+**Goal:** (one sentence)
+
+**Acceptance Criteria:**
+- (criterion 1)
+- (criterion 2)
+- ...
+
+**Affected Repos:** (comma-separated list)
+
+**Notes:** (any ambiguities, assumptions, or questions — optional)
+
+Do NOT ask the user questions. Make reasonable inferences and flag assumptions in Notes.

package/dist/plugin/skills/muggle-do/unit-tests.md

@@ -0,0 +1,31 @@
+# Unit Test Runner Agent
+
+You are running unit tests for each repository that has changes in the dev cycle pipeline.
+
+## Input
+
+You receive:
+- A list of repos with their paths and test commands (e.g., `pnpm test`)
+
+## Your Job
+
+For each repo:
+
+1. **Run the test command** using Bash in the repo's directory. Use the provided test command (default: `pnpm test`).
+2. **Capture the full output** — both stdout and stderr.
+3. **Determine pass/fail** — exit code 0 means pass, anything else means fail.
+4. **If tests fail**, extract the specific failing test names/descriptions from the output.
+
+## Output
+
+Per repo:
+
+**Repo: (name)**
+- Test command: (what was run)
+- Result: PASS | FAIL
+- Failed tests: (list, if any)
+- Output: (relevant portion of test output — full output if failed, summary if passed)
+
+**Overall:** ALL PASSED | FAILURES DETECTED
+
+If any repo fails, clearly state which repos failed and include enough output for the user to diagnose the issue.

package/dist/plugin/skills/muggle-do/validate-code.md

@@ -0,0 +1,30 @@
+# Code Validation Agent
+
+You are validating that each repository's git state is ready for the dev cycle pipeline.
+
+## Input
+
+You receive:
+- A list of repos with changes (from impact analysis), including their paths and branch names
+
+## Your Job
+
+For each repo:
+
+1. **Verify the branch is a feature branch** (not main/master/the default branch). This should already be validated by impact analysis, but double-check.
+2. **Check for uncommitted changes:** Run `git status --porcelain` in the repo. If there are uncommitted changes, warn the user — uncommitted changes won't be included in PRs.
+3. **Get the branch diff:** Run `git diff <default-branch>...HEAD --stat` for a summary of changes.
+4. **Verify commits exist on the branch:** Run `git log <default-branch>..HEAD --oneline` to confirm there are commits to push.
+
+## Output
+
+Per repo:
+
+**Repo: (name)**
+- Branch: (name)
+- Commits on branch: (count and one-line summaries)
+- Uncommitted changes: yes/no (with warning if yes)
+- Diff stat: (file change summary)
+- Status: READY | WARNING | ERROR
+
+**Overall:** READY to proceed / BLOCKED (with reasons)

package/dist/plugin/skills/publish-test-to-cloud/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: publish-test-to-cloud
+description: Publish a local generation run to cloud workflow records using MCP tools.
+---
+
+# Publish Test To Cloud
+
+Publish a locally generated run to Muggle AI cloud so it appears in cloud workflow and test result views.
+
+## Required tools
+
+- `muggle-remote-auth-status`
+- `muggle-remote-auth-login`
+- `muggle-remote-auth-poll`
+- `muggle-local-run-result-list`
+- `muggle-local-run-result-get`
+- `muggle-local-publish-test-script`
+- `muggle-remote-local-run-upload` (manual fallback)
+
+## Default flow
+
+1. Check auth with `muggle-remote-auth-status`.
+2. If not authenticated:
+   - `muggle-remote-auth-login`
+   - `muggle-remote-auth-poll` as needed.
+3. Find a local run:
+   - `muggle-local-run-result-list`
+   - choose a generation run in `passed` or `failed` state.
+4. Validate run:
+   - `muggle-local-run-result-get`
+   - ensure required metadata exists (`projectId`, `useCaseId`, `cloudTestCaseId`, `executionTimeMs`).
+5. Publish:
+   - `muggle-local-publish-test-script` with `runId` and `cloudTestCaseId`.
+6. Return cloud identifiers and view URL from tool response.
+
+## Notes
+
+- Prefer `muggle-local-publish-test-script`.
+- Use `muggle-remote-local-run-upload` only for advanced/manual fallback.
+- Replay runs are not publishable through this flow.
+- If required metadata is missing, fail fast with explicit error context.

package/dist/plugin/skills/test-feature-local/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: test-feature-local
+description: Test a feature's user experience on localhost. Manage entities in cloud with muggle-remote tools and execute locally with muggle-local tools.
+---
+
+# Test Feature Local
+
+Run end-to-end feature testing against a local URL using a cloud-first workflow:
+
+- Cloud management: `muggle-remote-*`
+- Local execution and artifacts: `muggle-local-*`
+
+## Workflow
+
+1. **Auth**
+   - `muggle-remote-auth-status`
+   - If needed: `muggle-remote-auth-login` + `muggle-remote-auth-poll`
+
+2. **Select project/use case/test case**
+   - `muggle-remote-project-list`
+   - `muggle-remote-use-case-list`
+   - `muggle-remote-test-case-list-by-use-case`
+
+3. **Resolve local URL**
+   - Use the URL provided by the user.
+   - If missing, ask explicitly (do not guess).
+
+4. **Check script availability**
+   - `muggle-remote-test-script-list` filtered by testCaseId
+   - If script exists, recommend replay unless user-flow changes suggest regeneration.
+
+5. **Execute**
+   - Replay path:
+     - `muggle-remote-test-script-get`
+     - `muggle-local-execute-replay`
+   - Generation path:
+     - `muggle-remote-test-case-get`
+     - `muggle-local-execute-test-generation`
+
+6. **Approval requirement**
+   - Before execution, get explicit user approval for launching Electron app.
+   - Only then set `approveElectronAppLaunch: true`.
+
+7. **Report results**
+   - `muggle-local-run-result-get` with returned runId.
+   - Report:
+     - status
+     - duration
+     - artifacts path
+     - pass/fail summary
+
+8. **Optional publish**
+   - Offer `muggle-local-publish-test-script` to publish generated script to cloud.
+
+## Tool map
+
+### Auth
+- `muggle-remote-auth-status`
+- `muggle-remote-auth-login`
+- `muggle-remote-auth-poll`
+- `muggle-remote-auth-logout`
+
+### Cloud entities
+- `muggle-remote-project-list`
+- `muggle-remote-project-create`
+- `muggle-remote-use-case-list`
+- `muggle-remote-use-case-create-from-prompts`
+- `muggle-remote-test-case-list-by-use-case`
+- `muggle-remote-test-case-get`
+- `muggle-remote-test-case-generate-from-prompt`
+- `muggle-remote-test-script-list`
+- `muggle-remote-test-script-get`
+
+### Local execution
+- `muggle-local-execute-test-generation`
+- `muggle-local-execute-replay`
+- `muggle-local-run-result-list`
+- `muggle-local-run-result-get`
+- `muggle-local-publish-test-script`
+
+## Guardrails
+
+- Do not silently skip auth.
+- Do not silently skip test execution when no script exists; generate one.
+- Do not launch Electron without explicit approval.
+- Do not hide failing run details; include error and artifacts path.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@muggleai/works",
-    "version": "2.0.2",
-    "description": "Ship quality products, not just code. AI-powered QA that validates your app's user experience — from Claude Code and Cursor to PR.",
+    "version": "3.0.0",
+    "description": "Deliver quality web products with an AI agent team. Autonomous pipeline that codes, tests, and QA-validates your app — from Claude Code and Cursor to PR.",
     "type": "module",
     "main": "dist/index.js",
     "bin": {
@@ -9,13 +9,14 @@
     },
     "files": [
         "dist",
+        "plugin",
         "bin/muggle.js",
-        "scripts/postinstall.mjs",
-        "skills-dist"
+        "scripts/postinstall.mjs"
     ],
     "scripts": {
         "clean": "rimraf dist",
-        "build": "tsup",
+        "build": "tsup && node scripts/build-plugin.mjs",
+        "build:plugin": "node scripts/build-plugin.mjs",
         "build:release": "npm run build",
         "build:workspace": "turbo run build",
         "typecheck:workspace": "turbo run typecheck",
@@ -59,7 +60,7 @@
     "devDependencies": {
         "@eslint/js": "^10.0.1",
         "@types/node": "^25.5.0",
-        "@types/uuid": "^10.0.0",
+        "@types/uuid": "^11.0.0",
         "@typescript-eslint/eslint-plugin": "^8.34.0",
         "@typescript-eslint/parser": "^8.34.0",
         "eslint": "^10.1.0",

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "muggle",
+  "description": "Muggle AI QA and autonomous dev workflow plugin.",
+  "version": "2.0.2",
+  "author": {
+    "name": "Muggle AI"
+  }
+}

package/plugin/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "muggle": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@muggleai/works",
+        "serve"
+      ]
+    }
+  }
+}

package/plugin/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/scripts/ensure-electron-app.sh\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugin/scripts/ensure-electron-app.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+# Ensure the Electron QA runtime is installed/up to date.
+# This is intentionally best-effort so plugin startup is resilient.
+if command -v muggle >/dev/null 2>&1; then
+  muggle setup >/dev/null 2>&1 || true
+  exit 0
+fi
+
+npx -y @muggleai/works setup >/dev/null 2>&1 || true

package/plugin/skills/muggle-do/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: muggle-do
+description: Unified Muggle AI workflow entry point. Routes to autonomous dev cycle, status, repair, or upgrade.
+disable-model-invocation: true
+---
+
+# Muggle Do
+
+Muggle Do is the top-level command for the Muggle AI development workflow.
+
+It supports two categories of execution:
+
+1. **Dev cycle**: requirements -> impact analysis -> validate code -> coding -> unit tests -> QA -> open PRs
+2. **Maintenance**: status, repair, upgrade
+
+## Input routing
+
+Treat `$ARGUMENTS` as the user command:
+
+- Empty / `help` / `menu` / `?` -> show menu and session selector.
+- `status` -> run installation and auth status checks.
+- `repair` -> run repair workflow.
+- `upgrade` -> run upgrade workflow.
+- Anything else -> treat as a new task description and start/resume a dev-cycle session.
+
+## Session model
+
+Use `.muggle-do/sessions/<slug>/` with these files:
+
+- `state.md`
+- `requirements.md`
+- `iterations/<NNN>.md`
+- `result.md`
+
+On each stage transition, update `state.md` and append stage output to the active iteration file.
+
+## Dev cycle agents
+
+Use the supporting files in this directory as stage-specific instructions:
+
+- [requirements.md](requirements.md)
+- [impact-analysis.md](impact-analysis.md)
+- [validate-code.md](validate-code.md)
+- [unit-tests.md](unit-tests.md)
+- [qa.md](qa.md)
+- [open-prs.md](open-prs.md)
+
+## Guardrails
+
+- Do not skip unit tests before QA.
+- Do not skip QA due to missing scripts; generate when needed.
+- If the same stage fails 3 times in a row, escalate with details.
+- If total iterations reach 3 and QA still fails, continue to PR creation with `[QA FAILING]`.

package/plugin/skills/muggle-do/impact-analysis.md

@@ -0,0 +1,34 @@
+# Impact Analysis Agent
+
+You are analyzing git repositories to determine which ones have actual code changes that need to go through the dev cycle pipeline.
+
+## Input
+
+You receive:
+- A list of repos with their local filesystem paths
+- The requirements goal and affected repos from the requirements stage
+
+## Your Job
+
+For each repo path provided:
+
+1. **Check the current branch:** Run `git branch --show-current` in the repo. If it returns empty (detached HEAD), report an error for that repo.
+2. **Detect the default branch:** Run `git symbolic-ref refs/remotes/origin/HEAD --short` to find the default branch (e.g., `origin/main`). Strip the `origin/` prefix. If this fails, check if `main` or `master` exist locally via `git rev-parse --verify`.
+3. **Verify it's a feature branch:** The current branch must NOT be the default branch. If it is, report an error.
+4. **List changed files:** Run `git diff --name-only <default-branch>...HEAD` to find files changed on this branch relative to the default branch. If no merge base exists, fall back to `git diff --name-only HEAD`.
+5. **Get the diff:** Run `git diff <default-branch>...HEAD` for the full diff.
+
+## Output
+
+Report per repo:
+
+**Repo: (name)**
+- Branch: (current branch name)
+- Default branch: (detected default branch)
+- Changed files: (list)
+- Diff summary: (brief description of what changed)
+- Status: OK | ERROR (with reason)
+
+**Summary:** (which repos have changes, which don't, any errors)
+
+If NO repos have any changes, clearly state: "No changes detected in any repo."

package/plugin/skills/muggle-do/open-prs.md

@@ -0,0 +1,52 @@
+# PR Creation Agent
+
+You are creating pull requests for each repository that has changes after a successful dev cycle run.
+
+## Input
+
+You receive:
+- Per-repo: repo name, path, branch name
+- Requirements: goal, acceptance criteria
+- QA report: passed/failed test cases, each with testCaseId, testScriptId, runId, artifactsDir, and projectId
+
+## Your Job
+
+For each repo with changes:
+
+1. **Push the branch** to origin: `git push -u origin <branch-name>` in the repo directory.
+2. **Build the PR title:**
+   - If QA has failures: `[QA FAILING] <goal>`
+   - Otherwise: `<goal>`
+   - Keep under 70 characters
+3. **Build the PR body** with these sections:
+   - `## Goal` — the requirements goal
+   - `## Acceptance Criteria` — bulleted list (omit section if empty)
+   - `## Changes` — summary of what changed in this repo
+   - `## QA Results` — full test case breakdown (see format below)
+4. **Create the PR** using `gh pr create --title "..." --body "..." --head <branch>` in the repo directory.
+5. **Capture the PR URL** from the output.
+
+## QA Results Section Format
+
+```
+## QA Results
+
+**X passed / Y failed**
+
+| Test Case | Status | Details |
+|-----------|--------|---------|
+| [Name](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=details&testCaseId={testCaseId}) | ✅ PASSED | — |
+| [Name](https://www.muggle-ai.com/muggleTestV0/dashboard/projects/{projectId}/scripts?modal=details&testCaseId={testCaseId}) | ❌ FAILED | {error} — artifacts: `{artifactsDir}` |
+```
+
+Rules:
+- Link each test case name to its details page on www.muggle-ai.com using the URL pattern above (requires `testCaseId` and `projectId` from the QA report).
+- For failed tests, include the error message and the local `artifactsDir` path so the developer can inspect screenshots.
+- Screenshots are in `{artifactsDir}/screenshots/` and viewable locally.
+
+## Output
+
+**PRs Created:**
+- (repo name): (PR URL)
+
+**Errors:** (any repos where PR creation failed, with the error message)