@muggleai/works 2.0.2 → 3.0.0

package/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/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/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/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/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/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/scripts/postinstall.mjs

@@ -857,6 +857,6 @@ async function installSkills() {
 // Run postinstall
 initLogFile();
 removeVersionOverrideFile();
-updateCursorMcpConfig();
-installSkills().catch(logError);
+log("Skipping Cursor MCP auto-registration (plugin-first mode). Install via: /plugin marketplace add <url>");
+log("Skipping ~/.claude skill installation (plugin-first mode). Install via: /plugin install muggle@<marketplace>");
 downloadElectronApp().catch(logError);