openclaw-node-harness 2.0.0

package/skills/cc-godmode/docs/TROUBLESHOOTING.md

@@ -0,0 +1,357 @@
+# CC_GodMode Troubleshooting
+
+Common issues and solutions when using the CC_GodMode skill.
+
+## Table of Contents
+
+1. [Installation Issues](#installation-issues)
+2. [MCP Server Issues](#mcp-server-issues)
+3. [Agent Issues](#agent-issues)
+4. [Workflow Issues](#workflow-issues)
+5. [Quality Gate Issues](#quality-gate-issues)
+
+---
+
+## Installation Issues
+
+### Skill not found after installation
+
+**Symptoms:**
+- `clawdhub list` doesn't show cc-godmode
+- Agent doesn't recognize CC_GodMode commands
+
+**Solutions:**
+
+1. Verify installation:
+```bash
+clawdhub list | grep cc-godmode
+```
+
+2. Try reinstalling:
+```bash
+clawdhub uninstall cc-godmode
+clawdhub install cc-godmode
+```
+
+3. Check skill directory:
+```bash
+ls ~/.clawdbot/skills/cc-godmode/
+```
+
+### Version mismatch
+
+**Symptoms:**
+- Skill reports different version than expected
+- Features from newer version not working
+
+**Solutions:**
+
+1. Check installed version:
+```bash
+grep "version:" ~/.clawdbot/skills/cc-godmode/SKILL.md
+```
+
+2. Update to latest:
+```bash
+clawdhub update cc-godmode
+```
+
+---
+
+## MCP Server Issues
+
+### Playwright MCP not available
+
+**Symptoms:**
+- @tester fails to start
+- "Playwright MCP not responding" error
+- No screenshots generated
+
+**Solutions:**
+
+1. Check MCP status:
+```bash
+claude mcp list
+```
+
+2. Verify Playwright is configured:
+```bash
+# In your MCP config (mcp.json)
+{
+  "playwright": {
+    "command": "npx",
+    "args": ["playwright-mcp"]
+  }
+}
+```
+
+3. Install Playwright:
+```bash
+npm install -g playwright-mcp
+npx playwright install
+```
+
+### GitHub MCP not responding
+
+**Symptoms:**
+- @github-manager can't create issues/PRs
+- "GitHub API rate limit" errors
+
+**Solutions:**
+
+1. Check authentication:
+```bash
+gh auth status
+```
+
+2. Re-authenticate:
+```bash
+gh auth login
+```
+
+3. Check rate limit:
+```bash
+gh api rate_limit --jq '.rate.remaining'
+```
+
+---
+
+## Agent Issues
+
+### @researcher timeout
+
+**Symptoms:**
+- Research takes too long
+- Partial results only
+
+**Solutions:**
+
+This is by design. @researcher has a 30-second hard timeout.
+
+1. For complex research, break into smaller queries
+2. Use the partial results and request follow-up research
+3. Check if specific URLs are slow to fetch
+
+### @architect not providing enough detail
+
+**Symptoms:**
+- Architecture report too brief
+- Missing trade-off analysis
+
+**Solutions:**
+
+1. Provide more context in your request:
+```
+New Feature: Add user authentication
+- Expected users: 10,000+
+- Security requirements: OAuth2, MFA
+- Target platforms: Web, Mobile
+```
+
+2. Ask for specific decisions:
+```
+@architect: Also evaluate caching strategy and session management
+```
+
+### @api-guardian missing consumers
+
+**Symptoms:**
+- Some consumers not found
+- Breaking changes not detected
+
+**Solutions:**
+
+1. Ensure grep patterns are correct for your codebase
+2. Check for unusual import patterns:
+```javascript
+// These might be missed
+const { type } = await import('./types')
+require('./types')
+```
+
+3. Add custom search patterns in request
+
+### @builder not running tests
+
+**Symptoms:**
+- Tests skipped
+- "No tests found" message
+
+**Solutions:**
+
+1. Verify test setup:
+```bash
+npm test
+```
+
+2. Check test configuration in package.json
+3. Ensure test files follow naming conventions (`*.test.ts`, `*.spec.ts`)
+
+---
+
+## Workflow Issues
+
+### Wrong workflow selected
+
+**Symptoms:**
+- Bug fix using full feature workflow
+- API change not triggering @api-guardian
+
+**Solutions:**
+
+1. Be explicit in your command:
+```
+Bug Fix: [description]
+API Change: [description]
+```
+
+2. For API changes, mention the path:
+```
+API Change: Update User type in shared/types/user.ts
+```
+
+### Agents not called in order
+
+**Symptoms:**
+- @builder called before @architect
+- Quality gates skipped
+
+**Solutions:**
+
+This indicates orchestrator confusion. Be explicit:
+
+```
+I want the full feature workflow:
+1. First @architect for design
+2. Then @builder for implementation
+3. Then both quality gates
+4. Finally @scribe for documentation
+```
+
+### Workflow stuck in loop
+
+**Symptoms:**
+- @builder → @validator → @builder repeating
+- Never reaching @scribe
+
+**Solutions:**
+
+1. Check @validator output for persistent issues
+2. Ask @validator to list ALL remaining issues
+3. Consider marking non-critical issues as "defer to next version"
+
+---
+
+## Quality Gate Issues
+
+### @validator always failing
+
+**Symptoms:**
+- TypeScript errors persist
+- Tests keep failing
+
+**Solutions:**
+
+1. Run locally first:
+```bash
+npm run typecheck
+npm test
+```
+
+2. Check if @builder received correct specs from @architect
+3. Review @api-guardian consumer list for missed updates
+
+### @tester screenshots not generated
+
+**Symptoms:**
+- No files in `.playwright-mcp/`
+- Screenshot section empty in report
+
+**Solutions:**
+
+1. Verify Playwright MCP is working:
+```javascript
+await mcp__playwright__browser_take_screenshot({
+  filename: "test.png"
+});
+```
+
+2. Check directory permissions:
+```bash
+ls -la .playwright-mcp/
+```
+
+3. Ensure dev server is running:
+```bash
+npm run dev
+```
+
+### Parallel gates not working
+
+**Symptoms:**
+- @validator and @tester running sequentially
+- Taking longer than expected
+
+**Solutions:**
+
+Parallel execution requires proper orchestrator coordination. Check:
+
+1. Both agents are called simultaneously via Task tool
+2. Results are collected at sync point
+3. Decision matrix is applied correctly
+
+---
+
+## General Tips
+
+### Reset workflow state
+
+If things get confused:
+
+```
+Status
+```
+
+Then start fresh with explicit command.
+
+### Check MCP availability
+
+Before starting work:
+
+```bash
+claude mcp list
+```
+
+Expected:
+- `playwright` ✓
+- `github` ✓
+- `lighthouse` (optional)
+- `a11y` (optional)
+
+### Force specific agent
+
+If orchestrator isn't calling the right agent:
+
+```
+Call @researcher to research [topic]
+Call @architect to design [feature]
+```
+
+### Skip to documentation
+
+For documentation-only changes:
+
+```
+Documentation only: Update README installation section
+```
+
+This goes directly to @scribe without quality gates.
+
+---
+
+## Getting Help
+
+1. Check [SKILL.md](../SKILL.md) for complete reference
+2. Review [WORKFLOWS.md](./WORKFLOWS.md) for workflow details
+3. See [AGENTS.md](./AGENTS.md) for agent specifications
+4. Open an issue on GitHub for bugs

package/skills/cc-godmode/docs/WORKFLOWS.md

@@ -0,0 +1,329 @@
+# CC_GodMode Workflows
+
+Detailed documentation of all 7 standard workflows.
+
+## Table of Contents
+
+1. [New Feature](#1-new-feature)
+2. [Bug Fix](#2-bug-fix)
+3. [API Change](#3-api-change)
+4. [Refactoring](#4-refactoring)
+5. [Release](#5-release)
+6. [Process Issue](#6-process-issue)
+7. [Research Task](#7-research-task)
+
+---
+
+## 1. New Feature
+
+**Trigger:** `New Feature: [description]`
+
+### Flow
+```
+                                          ┌──▶ @validator ──┐
+User ──▶ (@researcher)* ──▶ @architect ──▶ @builder              ├──▶ @scribe
+                                          └──▶ @tester   ──┘
+                                               (PARALLEL)
+```
+
+### Steps
+
+1. **@researcher** (optional) - If new technology research is needed
+   - Evaluates technologies
+   - Finds best practices
+   - Creates research report
+
+2. **@architect** - Design phase
+   - Analyzes requirements
+   - Creates module structure
+   - Documents trade-offs
+   - Produces architecture decision
+
+3. **@builder** - Implementation
+   - Implements types first
+   - Then backend (if needed)
+   - Then frontend
+   - Writes tests
+
+4. **@validator + @tester** (parallel)
+   - @validator: TypeScript, unit tests, security
+   - @tester: E2E, screenshots, a11y, performance
+
+5. **@scribe** - Documentation
+   - Updates VERSION
+   - Updates CHANGELOG
+   - Updates README if needed
+
+### Example
+
+```
+User: "New Feature: Add dark mode toggle to settings page"
+
+Orchestrator:
+→ @architect: Design state management for theme, component structure
+→ @builder: Implement ThemeContext, SettingsToggle component
+→ @validator: Verify TypeScript, run unit tests
+→ @tester: Screenshot dark/light modes at 3 viewports
+→ @scribe: Update CHANGELOG with dark mode feature
+```
+
+---
+
+## 2. Bug Fix
+
+**Trigger:** `Bug Fix: [description]`
+
+### Flow
+```
+                ┌──▶ @validator ──┐
+User ──▶ @builder                  ├──▶ (done)
+                └──▶ @tester   ──┘
+                     (PARALLEL)
+```
+
+### Steps
+
+1. **@builder** - Fix implementation
+   - Locate bug
+   - Implement fix
+   - Add regression test
+
+2. **@validator + @tester** (parallel)
+   - Verify fix doesn't break anything
+   - Run relevant E2E tests
+
+### Example
+
+```
+User: "Bug Fix: Login button not responding on mobile"
+
+Orchestrator:
+→ @builder: Fix click handler, add touch event support
+→ @validator: Run existing tests
+→ @tester: Test login flow on mobile viewport
+```
+
+---
+
+## 3. API Change
+
+**Trigger:** `API Change: [description]`
+
+### Flow
+```
+                                                              ┌──▶ @validator ──┐
+User ──▶ (@researcher)* ──▶ @architect ──▶ @api-guardian ──▶ @builder              ├──▶ @scribe
+                                                              └──▶ @tester   ──┘
+                                                                   (PARALLEL)
+```
+
+### Steps
+
+1. **@architect** - Design API change
+   - Define new schema
+   - Plan migration
+
+2. **@api-guardian** - Impact analysis (MANDATORY!)
+   - Find ALL consumers
+   - Classify breaking changes
+   - Create migration checklist
+
+3. **@builder** - Implement with consumer updates
+   - Update API/types first
+   - Update ALL consumers from checklist
+
+4. **@validator + @tester** (parallel)
+   - Verify ALL consumers updated
+   - Test API endpoints
+
+5. **@scribe** - Document breaking changes
+   - Add breaking change section to CHANGELOG
+   - Update API_CONSUMERS.md
+
+### Critical Paths
+
+These file patterns trigger @api-guardian:
+
+- `src/api/**`
+- `backend/routes/**`
+- `shared/types/**`
+- `types/`
+- `*.d.ts`
+- `openapi.yaml` / `openapi.json`
+- `schema.graphql`
+
+### Example
+
+```
+User: "API Change: Rename User.email to User.emailAddress"
+
+Orchestrator:
+→ @architect: Plan schema migration
+→ @api-guardian: Find 5 consumers, mark as BREAKING
+→ @builder: Update type + all 5 consumer files
+→ @validator: Verify all imports correct, TypeScript passes
+→ @tester: Test user-related flows
+→ @scribe: Document breaking change, update API_CONSUMERS.md
+```
+
+---
+
+## 4. Refactoring
+
+**Trigger:** `Refactor: [description]`
+
+### Flow
+```
+                            ┌──▶ @validator ──┐
+User ──▶ @architect ──▶ @builder              ├──▶ (done)
+                            └──▶ @tester   ──┘
+                                 (PARALLEL)
+```
+
+### Steps
+
+1. **@architect** - Plan refactoring
+   - Analyze current structure
+   - Design improved structure
+   - Document affected modules
+
+2. **@builder** - Execute refactoring
+   - Move/rename files
+   - Update imports
+   - Keep tests passing
+
+3. **@validator + @tester** (parallel)
+   - Verify behavior unchanged
+   - No regressions
+
+---
+
+## 5. Release
+
+**Trigger:** `Prepare Release`
+
+### Flow
+```
+User ──▶ @scribe ──▶ @github-manager
+```
+
+### Steps
+
+1. **@scribe** - Prepare release
+   - Finalize VERSION
+   - Complete CHANGELOG
+   - Update README
+
+2. **@github-manager** - Publish
+   - Create git tag
+   - Create GitHub release
+   - Trigger CI/CD
+
+---
+
+## 6. Process Issue
+
+**Trigger:** `Process Issue #X`
+
+### Flow
+```
+User: "Process Issue #X"
+  │
+  ▼
+@github-manager loads Issue
+  │
+  ▼
+Orchestrator analyzes: Type, Complexity, Areas
+  │
+  ▼
+Appropriate workflow is executed
+  │
+  ▼
+@github-manager creates PR with "Fixes #X"
+```
+
+### Issue Classification
+
+| Type | Workflow |
+|------|----------|
+| Bug | Bug Fix workflow |
+| Feature | New Feature workflow |
+| Enhancement | Refactoring or Feature workflow |
+| Documentation | @scribe only |
+
+---
+
+## 7. Research Task
+
+**Trigger:** `Research: [topic]`
+
+### Flow
+```
+User: "Research [topic]"
+  │
+  ▼
+@researcher gathers knowledge
+  │
+  ▼
+Report with findings + sources
+```
+
+### Steps
+
+1. **@researcher** - Gather knowledge
+   - WebSearch for current info
+   - WebFetch documentation
+   - Compare alternatives
+   - Check security advisories
+
+2. **Report** - Actionable findings
+   - Key findings with sources
+   - Recommendation
+   - Next steps
+
+### Example
+
+```
+User: "Research: Best state management for React in 2026"
+
+@researcher:
+→ Search: "React state management comparison 2026"
+→ Fetch: Official docs for Zustand, Jotai, Redux
+→ Compare: Bundle size, learning curve, performance
+→ Report: Recommend Zustand for this project size
+```
+
+---
+
+## Parallel Quality Gates
+
+All workflows (except Release and Research) end with parallel quality gates:
+
+```
+                    ┌────────────────────┐
+                    │      @builder      │
+                    └─────────┬──────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              │               │               │
+              ▼               │               ▼
+    ┌─────────────────┐       │     ┌─────────────────┐
+    │   @validator    │       │     │    @tester      │
+    │ (Code Quality)  │       │     │  (UX Quality)   │
+    └────────┬────────┘       │     └────────┬────────┘
+              │               │               │
+              └───────────────┼───────────────┘
+                              │
+                        SYNC POINT
+                              │
+                    ┌─────────┴─────────┐
+                    │                   │
+                    ▼                   ▼
+              BOTH PASS            ANY FAIL
+                    │                   │
+                    ▼                   ▼
+               @scribe             @builder
+                                   (fix it)
+```
+
+**Performance:** 40% faster than sequential execution!