mindforge-cc 6.2.0-alpha → 6.2.0

package/.claude/commands/mindforge/new-runtime.md

@@ -1,29 +1,23 @@
 ---
-name: mindforge:new-runtime
-description: Scaffold support for a new AI coding runtime
-argument-hint: [name]
-allowed-tools:
-  - run_command
-  - list_dir
-  - write_to_file
+description: Scaffold support for a new AI coding runtime.
 ---
 
-<objective>
-Extend MindForge to support additional AI environments (Zed, Cursor, Void, etc.) by scaffolding the necessary instruction files and updating the global installer configuration.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/new-runtime.md
-</execution_context>
-
-<context>
-Config: bin/installer-core.js
-Targets: Global and Local scopes.
-</context>
-
-<process>
-1. **Identify**: Determine the specific instruction file format for the target runtime.
-2. **Scaffold**: Create the directory structure and placeholder documentation for the new integration.
-3. **Configure**: Update the central `installer-core.js` mapping to include the new runtime identifier.
-4. **Onboard**: Generate customized first-run instructions for the user to enable the runtime immediately.
-</process>
+# /mindforge:new-runtime
+
+Scaffold support for a new AI coding runtime.
+
+## Usage
+
+/mindforge:new-runtime [name]
+
+## Action
+
+1.  Identify target runtime's entry file format (e.g. .myrules, instructions.md)
+2.  Scaffold the required directories in both global and local scopes
+3.  Add a new entry to the RUNTIMES configuration in `bin/installer-core.js`
+4.  Generate first-run instructions for the new runtime
+
+## Examples
+
+/mindforge:new-runtime void-editor
+/mindforge:new-runtime zed-ai

package/.claude/commands/mindforge/next.md

@@ -1,34 +1,109 @@
 ---
-name: mindforge:next
-description: Auto-detect the current state and execute the appropriate next step
-argument-hint: none
-allowed-tools:
-  - list_dir
-  - view_file
+description: Auto-detect the current project state and execute the appropriate next step.
 ---
 
-<objective>
-Simplify the developer workflow by automatically determining the most logical next action based on the current project state, guided by `STATE.md` and `HANDOFF.json`.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/next.md
-</execution_context>
-
-<context>
-Priority: `HANDOFF.json` is used for session continuity if updated within 48 hours.
-State Awareness: Detects missing initialisation, missing plans, partial execution, or pending verification/shipping.
-</context>
-
-<process>
-1. **Session Check**: Read `HANDOFF.json`. If a fresh `next_task` exists, offer to resume.
-2. **State Analysis**: Run the decision tree against `STATE.md`:
-    - Not initialised? → `init-project`.
-    - No phases? → `plan-phase 1`.
-    - Plan missing? → `plan-phase [N]`.
-    - Partial execution? → Offer to resume `execute-phase [N]`.
-    - Pending verification? → `verify-phase [N]`.
-    - Pending shipping? → `ship [N]`.
-3. **Handling Partially Executed Phases**: Identify specifically which plans lack SUMMARY files and offer targeted resumption.
-4. **Confirm**: Present the detected next step and command to the user for confirmation before acting.
-</process>
+# MindForge — Next Command
+# Usage: /mindforge:next
+
+Auto-detect the current project state and execute the appropriate next step.
+The user does not need to know the workflow. MindForge figures it out.
+
+## HANDOFF.json priority rule
+Check HANDOFF.json BEFORE running the decision tree.
+
+If HANDOFF.json exists AND `updated_at` is within 48 hours AND `next_task` is not null:
+present the HANDOFF state first. Only run the decision tree if the user declines
+or the HANDOFF.json is stale.
+
+## State detection logic
+
+Read STATE.md and HANDOFF.json. Then follow this decision tree:
+
+### Decision tree
+
+```
+Does .planning/PROJECT.md exist AND have content?
+  NO  → Run /mindforge:init-project
+  YES → Continue
+
+Does .planning/ROADMAP.md exist AND have phases defined?
+  NO  → Tell user: "Project is initialised but no phases are defined yet.
+         Describe what Phase 1 should accomplish and I'll plan it."
+         Then run /mindforge:plan-phase 1
+  YES → Continue
+
+Read the phase status from STATE.md.
+
+Does the current phase have plans? (check .planning/phases/[N]/PLAN-[N]-*.md)
+  NO  → Run /mindforge:plan-phase [N]
+  YES → Continue
+
+Do SUMMARY files exist for all plans in the current phase?
+  NO  → Run /mindforge:execute-phase [N]
+  YES → Continue
+
+Does VERIFICATION.md exist for the current phase?
+  NO  → Run /mindforge:verify-phase [N] (automated part)
+  YES → Continue
+
+Does UAT.md exist and show all tests passing?
+  NO  → Run /mindforge:verify-phase [N] (UAT part)
+  YES → Continue
+
+Is this phase marked as shipped in STATE.md?
+  NO  → Run /mindforge:ship [N]
+  YES → Continue
+
+Are there more phases in ROADMAP.md?
+  YES → Increment phase number. Run /mindforge:plan-phase [N+1]
+  NO  → Tell user: "All phases complete! Run /mindforge:ship [N] for the final release."
+```
+
+## Partial phase execution handling
+In the decision tree step "Do SUMMARY files exist for all plans?":
+
+Do not treat this as binary. Check individually:
+
+```
+PLAN-[N]-01.md exists?          SUMMARY-[N]-01.md exists?
+PLAN-[N]-02.md exists?          SUMMARY-[N]-02.md exists?
+PLAN-[N]-03.md exists?          SUMMARY-[N]-03.md exists?
+```
+
+If some SUMMARY files exist and some don't: this is a partially-executed phase.
+Report: "Phase [N] is partially executed: plans [X, Y] are done, [Z] is not."
+Ask: "Resume execution from Plan [Z]? (yes/no)"
+Do not restart the entire phase — resume from the first missing SUMMARY.
+
+## Before auto-executing: always confirm
+Before running any command automatically, tell the user:
+
+```
+MindForge next step detected:
+  Current state : [description of current state]
+  Next action   : [what will be run]
+  Command       : /mindforge:[command] [args]
+
+Run this now? (yes/no/different)
+```
+
+If user says "different": ask what they want to do instead.
+If user says "yes": proceed with the detected command.
+
+## Handling HANDOFF.json (session restart)
+If HANDOFF.json has a `next_task` field from a previous session:
+Present it prominently:
+
+```
+Previous session found:
+  Saved at  : [updated_at from HANDOFF.json]
+  Left off  : [last_completed_task]
+  Next task : [next_task]
+
+Options:
+  1. Continue from where we left off
+  2. Check current state and determine next step fresh
+  3. Tell me what you want to do
+
+Choose 1, 2, or 3:
+```

package/.claude/commands/mindforge/plan-phase.md

@@ -1,34 +1,131 @@
 ---
-name: mindforge:plan-phase
-description: Plan a project phase by generating atomic task plans
-argument-hint: [N]
-allowed-tools:
-  - view_file
-  - write_to_file
-  - list_dir
+description: Plan a project phase. Usage: /mindforge:plan-phase [N]
 ---
 
-<objective>
-Generate a series of atomic, verifiable task plans for a specific project phase, incorporating domain research and captured implementation decisions.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/plan-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (Phase N)
-Prerequisites: PROJECT.md, REQUIREMENTS.md, ARCHITECTURE.md, STATE.md, and optionally CONTEXT.md.
-Output: .planning/phases/phase-[N]/PLAN-[N]-[NN].md
-</context>
-
-<process>
-1. **Pre-read**: Resolve phase number and read all foundational context files. If `CONTEXT.md` exists, respect prior decisions.
-2. **Domain Research**: Investigate best libraries, pitfalls, and patterns. Save to `RESEARCH.md`.
-3. **Task Planning**: Create 3-6 atomic PLAN files using the MindForge XML task format. Each plan must be:
-    - Completatable in one window.
-    - Targeted at <6 files.
-    - Verifiable via a deterministic command.
-4. **Validation**: Cross-reference plans against requirements and architecture. Ensure `<verify>` steps are runnable.
-5. **Finalize**: Update `STATE.md` and display the list of generated plans to the user.
-</process>
+Plan a project phase. Usage: /mindforge:plan-phase [N]
+
+## Pre-check
+If N is not given, read STATE.md for the current phase number and increment by 1.
+Read PROJECT.md, REQUIREMENTS.md, ARCHITECTURE.md, and STATE.md before proceeding.
+
+## Pre-read (before any questions or planning)
+
+Read these files in order:
+1. `AGENTS_LEARNING.md` (MUST READ to avoid repeating past mistakes)
+2. `.planning/PROJECT.md`
+3. `.planning/REQUIREMENTS.md`
+4. `.planning/ARCHITECTURE.md`
+5. `.planning/STATE.md`
+6. `.planning/phases/phase-[N]/CONTEXT.md` (if it exists)
+
+### If CONTEXT.md exists for phase [N]:
+This means `/mindforge:discuss-phase [N]` was already run.
+The user's implementation decisions are already captured.
+DO NOT re-ask questions that CONTEXT.md already answers.
+Read CONTEXT.md completely before asking any clarifying questions.
+Report: "I've read the phase discussion context. [N] decisions were captured.
+Planning will follow these decisions."
+
+### If CONTEXT.md has open questions:
+Read the "Open questions" section in CONTEXT.md.
+Present unresolved questions to the user NOW, before planning begins.
+Do not create plans that assume answers to open questions without confirming first.
+
+### If CONTEXT.md does NOT exist for phase [N]:
+Proceed normally with the discussion → planning flow.
+
+## Step 1 — Discuss phase scope
+Ask:
+1. "Describe what Phase [N] should accomplish. 2-3 sentences."
+2. "Have you already made any implementation decisions for this phase?
+    (libraries, patterns, approaches) If yes, list them."
+3. "Are there any constraints I should know about?
+    (deadlines, dependencies on other teams, tech limitations)"
+
+Write answers to `.planning/phases/phase-[N]/CONTEXT.md`.
+
+If `.planning/phases/phase-[N]/CONTEXT.md` already exists:
+1. Read it first.
+2. If it has "Open questions", ask the user to resolve them before planning.
+3. Update CONTEXT.md with the answers and mark those questions as resolved.
+
+### If CONTEXT.md exists — skip already-answered questions
+Only ask about areas NOT covered in CONTEXT.md.
+Example: if CONTEXT.md captures the layout decision, do not ask "What layout do you want?"
+Respect the prior discussion. Build on it. Do not repeat it.
+
+## Step 2 — Domain research (spawn subagent)
+Spawn a research subagent with this context only:
+- The tech stack from PROJECT.md
+- The phase scope from CONTEXT.md
+- CONVENTIONS.md
+
+Instruct it to investigate:
+1. Best available libraries for this phase's requirements (with version numbers)
+2. Common pitfalls and anti-patterns for this tech domain
+3. Project-specific anti-patterns from `AGENTS_LEARNING.md`
+4. Relevant architectural patterns (with tradeoffs)
+5. Any known security considerations specific to this domain
+
+Write findings to `.planning/phases/phase-[N]/RESEARCH.md`.
+
+## Step 3 — Create atomic task plans
+Based on CONTEXT.md and RESEARCH.md, create 3-6 PLAN files.
+Each plan must be completable in a single fresh context window.
+Each plan targets specific files — no plan should touch more than 6 files.
+
+File naming: `.planning/phases/phase-[N]/PLAN-[N]-[NN].md`
+Example: `.planning/phases/1/PLAN-1-01.md`
+
+Each plan uses this XML format:
+
+```xml
+<task type="auto">
+  <n>Short descriptive task name</n>
+  <persona>developer</persona>
+  <phase>[N]</phase>
+  <plan>[NN]</plan>
+  <dependencies>List any PLAN files that must complete before this one, or "none"</dependencies>
+  <files>
+    src/exact/file/path.ts
+    src/another/file.ts
+  </files>
+  <context>
+    Relevant decisions from ARCHITECTURE.md:
+    - [decision]
+    Skills to load before starting:
+    - [skill name if applicable, or "none"]
+  </context>
+  <action>
+    Precise implementation instructions.
+    Include exact library names and versions.
+    Include the approach, not just the goal.
+    Include specific anti-patterns to avoid.
+  </action>
+  <verify>
+    [Exact runnable command or check]
+    Example: curl -X POST localhost:3000/api/auth/login -d '{"email":"test@test.com","password":"test"}' | jq .status
+    Must produce a deterministic pass/fail result.
+  </verify>
+  <done>One sentence definition of done.</done>
+</task>
+```
+
+## Step 4 — Validate plans
+Check every plan against REQUIREMENTS.md:
+- Does this plan implement anything out of scope? If yes: revise.
+- Does this plan contradict ARCHITECTURE.md? If yes: create an ADR first.
+- Is the `<verify>` step actually runnable? If no: rewrite it.
+
+## Step 5 — Update state and confirm
+Update STATE.md: current phase = N, status = "Phase N planned, ready to execute".
+
+Tell the user:
+"✅ Phase [N] planned. [X] task plans created.
+
+Plans:
+  PLAN-[N]-01: [task name]
+  PLAN-[N]-02: [task name]
+  ...
+
+Run /mindforge:execute-phase [N] to begin execution."

package/.claude/commands/mindforge/plugins.md

@@ -1,34 +1,44 @@
 ---
-name: mindforge:plugins
-description: Manage MindForge plugins and their permission scopes
-argument-hint: [list|install|uninstall|info|validate|create]
-allowed-tools:
-  - run_command
-  - list_dir
-  - view_file
-  - write_to_file
+description: Read PLUGINS-MANIFEST.md. Display installed plugins with version and permissions.
 ---
 
-<objective>
-Extend MindForge core functionality through a secure plugin architecture, managing the lifecycle and security boundaries of installed extensions.
-</objective>
+# MindForge — Plugins Command
+# Usage: /mindforge:plugins [list|install|uninstall|info|validate|create] [name]
 
-<execution_context>
-.claude/commands/mindforge/plugins.md
-</execution_context>
+## list
+Read PLUGINS-MANIFEST.md. Display installed plugins with version and permissions.
+If no plugins: "No plugins installed. Find plugins: npm search mindforge-plugin"
 
-<context>
-Manifest: PLUGINS-MANIFEST.md
-Loader: plugin-loader.md
-Security: Level 1+2 skill validation, injection guards, and explicit permission prompts.
-</context>
+## install [plugin-name]
+Full installation protocol per plugin-loader.md:
+1. Resolve package: `mindforge-plugin-[name]` convention
+2. Download to chmod 700 temp directory
+3. Validate plugin.json manifest
+4. Check plugin_api_version compatibility (1.0.0 required)
+5. Run injection guard on ALL .md files in the plugin
+6. Run Level 1 + 2 skill validation on all SKILL.md files
+7. Display permission list for user approval:
+   ```
+   Plugin: mindforge-plugin-jira-advanced v1.0.0
+   Requests these permissions:
+     • read_audit_log:  read AUDIT.jsonl ✅ (safe)
+     • write_audit_log: append to AUDIT.jsonl ⚠️
+     • network_access:  make HTTP requests ⚠️
+   Install? (yes/no)
+   ```
+8. Install components (commands, skills, personas, hooks)
+9. Add to PLUGINS-MANIFEST.md
+10. Write AUDIT entry
 
-<process>
-1. **Route Action**:
-    - `list`: Show installed plugins and versions.
-    - `install`: Execute the full installation protocol (download, validate manifest, run security guards, prompt for permissions).
-    - `uninstall`: Cleanly remove all components and update the manifest.
-    - `validate`: Audit all installed plugins for injection safety and permission compliance.
-2. **Permission Management**: Display a clear list of requested permissions (network, registry, audit write) and await user approval.
-3. **Audit**: Log all plugin installations and removals.
-</process>
+## uninstall [plugin-name]
+Remove all installed components. Update PLUGINS-MANIFEST.md.
+Confirm: "This will remove [N] commands, [N] skills from this plugin."
+
+## info [plugin-name]
+Display: version, description, author, permissions, commands, skills, personas, hooks.
+
+## validate
+Validate all installed plugins for compatibility, injection safety, permission scope.
+
+## create [plugin-name]
+Generate a plugin scaffold:

package/.claude/commands/mindforge/pr-review.md

@@ -1,32 +1,45 @@
 ---
-name: mindforge:pr-review
-description: Run the AI PR review engine on a pull request diff
-argument-hint: [--diff path] [--sha base..head] [--output github|json|markdown]
-allowed-tools:
-  - run_command
-  - view_file
-  - write_to_file
+description: Run the AI PR review engine on a pull request diff.
 ---
 
-<objective>
-Automate the review of pull request diffs using an AI engine, providing structured feedback in various formats (GitHub, JSON, Markdown) tailored to the type of changes made.
-</objective>
-
-<execution_context>
-.claude/commands/mindforge/pr-review.md
-</execution_context>
-
-<context>
-Source: Diff file, SHA range, or staged changes.
-Knowledge: PROJECT.md, ARCHITECTURE.md, CONVENTIONS.md, SECURITY.md.
-Environment: Requires ANTHROPIC_API_KEY for external model calls.
-</context>
-
-<process>
-1. **Determine Source**: Extract the diff from the provided path, SHA range, or git state.
-2. **Load Context**: Gather project-level documentation and relevant ADRs.
-3. **Select Template**: Detect change type (Auth, DB, API) and select the corresponding review template.
-4. **Execute Review**: Invoke the Claude API with the built system/review prompts.
-5. **Format Output**: Generate the report according to the `--output` flag (GitHub-flavoured MD, JSON, or standard MD).
-6. **Finalize**: Write to the specified destination (CI /tmp/ or interactive console) and log the event.
-</process>
+# MindForge — PR Review Command
+# Usage: /mindforge:pr-review [--diff path] [--sha base..head] [--output github|json|markdown]
+
+Run the AI PR review engine on a pull request diff.
+
+Steps:
+1. Determine diff source:
+   - `--diff path`: read diff from file
+   - `--sha base..head`: run `git diff base..head`
+   - Default: `git diff HEAD~1` (last commit) or `git diff --staged` (staged changes)
+
+2. Load review context (per ai-reviewer.md):
+   - PROJECT.md, ARCHITECTURE.md, CONVENTIONS.md, SECURITY.md
+   - Current phase's CONTEXT.md (if in an active phase)
+   - Any active ADRs relevant to changed files
+
+3. Detect change type and select review template:
+   - Auth/security changes → Security-focused review template
+   - Database migrations → Database migration review template
+   - API changes → API breaking change review template
+   - Default → Standard review template
+
+4. Check API availability:
+   - ANTHROPIC_API_KEY set? If not: warn and skip AI review
+   - Check daily review limit (from ai-reviewer.md)
+   - Check cache: has this SHA been reviewed in the last 60 minutes?
+
+5. Call Claude API (per ai-reviewer.md buildSystemPrompt + buildReviewPrompt)
+   - Handle errors gracefully — API unavailable is NOT a build failure
+   - Timeout: 60 seconds
+
+6. Format output per --output flag:
+   - github: GitHub-flavoured markdown for PR comment
+   - json: structured JSON with findings array
+   - markdown: standard markdown
+
+7. Write to output:
+   - If in CI: write to /tmp/mindforge-review.md (read by GitHub Actions step)
+   - If interactive: display to user
+
+8. Write AUDIT entry

package/.claude/commands/mindforge/profile-team.md

@@ -1,30 +1,27 @@
 ---
-name: mindforge:profile-team
-description: Generate and maintain team/developer profiles for response personalization
-argument-hint: [--refresh] [--developer email] [--questionnaire]
-allowed-tools:
-  - view_file
-  - write_to_file
-  - run_command
+description: Generate and maintain team/developer profiles for response personalization.
 ---
 
-<objective>
-Enhance agent collaboration by building profiles of individual developers and the team as a whole, tailoring guidance and responses based on observed patterns and declared preferences.
-</objective>
+# MindForge — Profile Team Command
+# Usage: /mindforge:profile-team [--refresh] [--developer email] [--questionnaire]
 
-<execution_context>
-.claude/commands/mindforge/profile-team.md
-</execution_context>
+Generate and maintain team/developer profiles for response personalization.
 
-<context>
-Sources: AUDIT logs, git history, metrics, and interactive questionnaires.
-Storage: .mindforge/team/profiles/
-</context>
+## Data sources
+1. Declared questionnaire preferences
+2. Inferred patterns from AUDIT + git history + metrics
+3. Defaults from org conventions
 
-<process>
-1. **Data Harvest**: Analyze recent commits and audit logs to infer developer style and expertise.
-2. **Preference Intake**: If `--questionnaire` is set, ask preference questions about verbosity, explanation depth, and review style.
-3. **Synthesis**: Update the `.mindforge/team/TEAM-PROFILE.md` and individual developer profile files.
-4. **Refresh**: Run periodic updates to account for shifting team dynamics or new members.
-5. **Audit**: Log `team_profile_updated` with developer counts.
-</process>
+## Outputs
+- `.mindforge/team/TEAM-PROFILE.md`
+- `.mindforge/team/profiles/PROFILE-[dev-id].md`
+
+## Modes
+- `--refresh`: inference-only update
+- `--developer`: target one developer profile
+- `--questionnaire`: prompt preference questions before writing
+
+## AUDIT
+```json
+{ "event": "team_profile_updated", "developers_profiled": 1, "method": "inferred" }
+```

package/.claude/commands/mindforge/publish-skill.md

@@ -1,30 +1,23 @@
 ---
-name: mindforge:publish-skill
-description: Validate and publish a skill to a registry
-argument-hint: [skill-dir] [--registry URL] [--dry-run]
-allowed-tools:
-  - run_command
-  - view_file
+description: Publish a skill to the npm registry (or private registry).
 ---
 
-<objective>
-Facilitate code reuse and community contribution by verifying, packaging, and uploading local skills to an npm or private registry after passing rigorous quality checks.
-</objective>
+# MindForge — Publish Skill Command
+# Usage: /mindforge:publish-skill [skill-dir] [--registry URL] [--dry-run]
 
-<execution_context>
-.claude/commands/mindforge/publish-skill.md
-</execution_context>
+Publish a skill to the npm registry (or private registry).
 
-<context>
-Auditors: Level 1, 2, and 3 validation from skill-validator.md.
-Format: Standard npm package with `mindforge` fields.
-</context>
-
-<process>
-1. **Audit**: Run full multi-level validation. Fail on structural or security issues.
-2. **Metadata Check**: Ensure `package.json`, `SKILL.md`, and `CHANGELOG.md` are in sync and complete.
-3. **Preview**: Run `npm pack --dry-run` and list files for user confirmation.
-4. **Publish**: Upload the package (public by default) to the resolved registry.
-5. **Verify**: Query the registry to confirm the version is live.
-6. **Audit**: Log `skill_published` with package name and version.
-</process>
+Pre-publication checklist:
+1. Run full skill validation (Level 1 + 2 + 3 from skill-validator.md)
+   Fail if Level 1 or 2 fails. Warn if Level 3 fails.
+2. Verify package.json has `mindforge` field with all required sub-fields
+3. Verify CHANGELOG.md has an entry for the current version
+4. Check if version already published: `npm info [package-name]@[version]`
+   If already published: error "Version already exists. Bump the version."
+5. Run `npm pack --dry-run` to preview what will be published
+6. Confirm with user: "These files will be published: [list]. Proceed? (yes/no)"
+7. If --dry-run: stop here, show preview only
+8. Publish: `npm publish --access public`
+9. Verify: `npm info [package-name]@[version]` — confirm publication succeeded
+10. Write AUDIT: `{ "event": "skill_published", "package": "...", "version": "..." }`
+11. Report: "✅ [package-name]@[version] published to npm registry"

package/.claude/commands/mindforge/qa.md

@@ -1,31 +1,20 @@
 ---
-name: mindforge:qa
-description: Run systematic visual QA on changed UI surfaces
-argument-hint: [--phase N] [--auto]
-allowed-tools:
-  - run_command
-  - list_dir
-  - open_browser_url
-  - view_file
+description: @mindforge qa [--phase N] [--auto]
 ---
 
-<objective>
-Automatically identify UI regressions and visual bugs by scanning phase diffs for frontend changes, navigating to affected pages, and performing automated sanity checks.
-</objective>
+# /mindforge:qa
 
-<execution_context>
-.claude/commands/mindforge/qa.md
-</execution_context>
+## Usage
+`@mindforge qa [--phase N] [--auto]`
 
-<context>
-Scope: Files changed in the target phase.
-Output: QA-REPORT report and automated Playwright regression tests.
-</context>
+## Description
+Runs systematic visual QA on UI surfaces changed in the current phase.
+Analyzes git diff to find pages, navigates to them, and looks for errors.
 
-<process>
-1. **Diff Analysis**: Identify changed pages/routes from git history.
-2. **Visual Scan**: Navigate to affected URLs using the browser tool.
-3. **Bug Hunting**: Look for console errors, hydration issues, and visual brokenness.
-4. **Reporting**: Generate a `QA-REPORT-[N].md` with screenshots of findings.
-5. **Sanitization**: Draft regression tests in `tests/regression/` to prevent recurrence.
-</process>
+## Options
+- `--phase N`: Target specific phase for reporting (defaults to current).
+- `--auto`: Automatically run after successful wave execution if configured.
+
+## Output
+- `QA-REPORT-[N].md`: Found bugs with screenshots.
+- `tests/regression/*.test.ts`: Playwright tests to prevent bug recurrence.