codymaster 4.1.0

package/skills/cm-dockit/tests/runner.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execSync } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// Test the backend Bash Runner (dockit-runner.sh)
+
+describe('CM DocKit Runner (Backend Scripts)', () => {
+  let tempProjectDir: string;
+  let dockitRunnerPath: string;
+
+  beforeAll(() => {
+    // Create a temporary mock project
+    tempProjectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'dockit-test-'));
+    dockitRunnerPath = path.resolve(__dirname, '../scripts/dockit-runner.sh');
+    // Ensure scripts have execute permission
+    execSync(`chmod +x ${dockitRunnerPath}`);
+  });
+
+  afterAll(() => {
+    // Cleanup
+    fs.rmSync(tempProjectDir, { recursive: true, force: true });
+  });
+
+  it('should plan tasks correctly via dry-run and initialize progress file', () => {
+    // Run the script in dry-run mode
+    const cmd = `bash ${dockitRunnerPath} -p ${tempProjectDir} -t all --dry-run`;
+    let output = '';
+    try {
+      output = execSync(cmd, { encoding: 'utf-8' });
+    } catch (e: any) {
+      output = e.stdout || e.message;
+    }
+    
+    // Verify execution output contains plans
+    expect(output).toContain('Task Plan (dry-run)');
+    expect(output).toContain('Total: 12 tasks'); // Expecting 12 planned tasks for type=all
+    
+    // Verify that the _progress.json file was created during initialization
+    const progressFile = path.join(tempProjectDir, 'docs', '_progress.json');
+    expect(fs.existsSync(progressFile)).toBe(true);
+    
+    // Verify JSON structure and DAG paths
+    const progressData = JSON.parse(fs.readFileSync(progressFile, 'utf-8'));
+    expect(progressData).toHaveProperty('tasks');
+    expect(Array.isArray(progressData.tasks)).toBe(true);
+
+    const tasks = progressData.tasks;
+    
+    // 1. Initial Analysis Task
+    const analysisTask = tasks.find((t: any) => t.id === 'analysis');
+    expect(analysisTask).toBeDefined();
+    expect(analysisTask.depends_on).toBe(null); // Phase 0
+    
+    // 2. Tech Architecture Tasks depend on analysis
+    const archTask = tasks.find((t: any) => t.id === 'architecture');
+    expect(archTask).toBeDefined();
+    expect(archTask.depends_on).toBe('analysis');
+
+    // 3. SOP Tasks depend on analysis (or personas)
+    const sopTask = tasks.find((t: any) => t.id === 'sop-index');
+    expect(sopTask).toBeDefined();
+    expect(sopTask.depends_on).toBe('personas'); // when type=all
+  });
+});

package/skills/cm-dockit/workflows/export-markdown.md

@@ -0,0 +1,82 @@
+---
+description: "Export generated documentation as clean Markdown files with proper folder structure."
+---
+
+# Export Markdown Workflow
+
+Export documentation as plain Markdown with a clean folder structure.
+
+## Steps
+
+### 1. Ensure Directory Structure
+
+// turbo
+Create the following structure in `[project_root]/docs/`:
+
+```
+docs/
+├── README.md           ← Index/landing page
+├── _analysis.md        ← Codebase analysis (internal)
+├── architecture.md     ← System architecture
+├── database.md         ← Database schema
+├── deployment.md       ← Deployment guide
+├── data-flow.md        ← Data flow diagrams
+├── sop/
+│   ├── index.md        ← SOP overview
+│   └── [module].md     ← One per feature
+└── api/
+    ├── index.md        ← API overview
+    └── [resource].md   ← One per resource
+```
+
+### 2. Generate README.md (Index)
+
+Create `docs/README.md`:
+
+```markdown
+# [Project Name] — Documentation
+
+## 📐 Technical Documentation
+- [Architecture](./architecture.md)
+- [Database](./database.md)
+- [Deployment](./deployment.md)
+- [Data Flow](./data-flow.md)
+
+## 📋 SOP — User Guides
+- [Overview](./sop/index.md)
+- [List of all SOPs by module]
+
+## 🔌 API Reference
+- [Overview](./api/index.md)
+- [List of all API docs by resource]
+
+---
+
+> Generated by **Doc-Kit** for Google Antigravity
+> Last updated: [date]
+```
+
+### 3. Clean Up
+
+- Remove `_analysis.md` from final output (it's internal)
+- Ensure all Markdown files have YAML frontmatter with `title` and `description`
+- Verify all relative links between files work
+- Check Mermaid syntax is valid
+
+### 4. Summary
+
+Report to user:
+```
+✅ Documentation generated successfully!
+
+📁 Location: [project_root]/docs/
+📄 Files: [count] files generated
+📝 Format: Markdown
+
+To view:
+  - Open docs/README.md in any Markdown viewer
+  - Or use: npx serve docs/
+
+To convert to website later:
+  - Run /doc-kit and choose 'vitepress' format
+```

package/skills/cm-dockit/workflows/generate-docs.md

@@ -0,0 +1,68 @@
+---
+description: "Generate documentation from codebase analysis. Interactive CLI: choose doc type (tech/sop/api/all) and format (markdown/vitepress)."
+---
+
+# Generate Documentation Workflow
+
+Main workflow to generate documentation from code analysis.
+
+## Prerequisites
+
+- Source code path must be accessible
+- Node.js 18+ (if choosing VitePress format)
+
+## Workflow
+
+### Step 1: Choose Document Type
+
+Ask the user which type of documentation to generate:
+
+- **tech** — Technical system documentation (architecture, database, deployment, data flow)
+- **sop** — SOP user guides (step-by-step, troubleshooting, FAQ)
+- **api** — API reference (endpoints, schemas, examples)
+- **all** — Generate all of the above
+
+### Step 2: Choose Output Format
+
+Ask the user which output format:
+
+- **markdown** — Plain Markdown files in `docs/` folder. Simple, portable, works anywhere.
+- **vitepress** — Premium VitePress static site. Beautiful, searchable, built-in Mermaid, deployable.
+
+### Step 3: Specify Source Code Path
+
+Ask for the absolute path to the project root directory.
+
+### Step 4: Run Analysis
+
+// turbo
+Read the skill file at `skills/cm-dockit/skills/analyze-codebase.md` and follow its procedure to analyze the codebase.
+
+Save output to `[project_root]/docs/analysis.md`.
+
+### Step 5: Generate Documents
+
+Based on the chosen type, read the corresponding skill file and follow its procedure:
+
+- **tech**: Read `skills/cm-dockit/skills/tech-docs.md`
+- **sop**: Read `skills/cm-dockit/skills/sop-guide.md`
+- **api**: Read `skills/cm-dockit/skills/api-reference.md`
+- **all**: Read and execute all three sequentially
+
+### Step 6: Export
+
+Based on the chosen format:
+
+**If markdown:**
+Read `skills/cm-dockit/workflows/export-markdown.md` and follow its procedure.
+
+**If vitepress:**
+Read `skills/cm-dockit/workflows/setup-vitepress.md` and follow its procedure.
+
+### Step 7: Summary
+
+Present to user:
+- ✅ List of all generated files
+- 📁 Output directory location
+- 🚀 How to view/serve the docs
+- 📝 Suggestions for customization

package/skills/cm-dockit/workflows/setup-vitepress.md

@@ -0,0 +1,181 @@
+---
+description: "Scaffold a premium VitePress site from generated documentation files."
+---
+
+# Setup VitePress — Premium Workflow
+
+Create a professional VitePress static site from the generated documentation.
+
+## Prerequisites
+
+- Node.js 18+
+- Generated docs in `[project_root]/docs/`
+
+## Steps
+
+### 1. Scaffold Premium Boilerplate
+
+// turbo
+```bash
+cd [project_root]
+# Copy the entire robust boilerplate (includes package.json, tests, and .vitepress)
+cp -r ~/.gemini/antigravity/skills/cm-dockit/templates/vitepress-premium docs-site
+
+# Install dependencies
+cd docs-site
+npm install
+```
+
+> **Note:** The new boilerplate is configured with `srcDir: '../docs'`. This means VitePress will automatically read your generated Markdown from `[project_root]/docs/` without needing to copy them into `docs-site/`! This prevents duplicate files and sync issues.
+
+### 2. Verify Output & Run Test Gate
+
+// turbo
+```bash
+cd [project_root]/docs-site
+# Run the automated frontend testing gate to verify config and dependencies
+npm run test:gate
+```
+
+> **Important:** If `test:gate` fails, the `config.mts` or Markdown frontmatter may have syntax errors. Fix them before proceeding.
+
+### 3. Customize Configuration
+
+Edit `docs-site/.vitepress/config.mts`:
+
+Replace all `[PLACEHOLDER]` values:
+- `[Project Name]` → actual project name
+- Update `sitemap.hostname` for deployment target
+- Add social links (GitHub, etc.)
+
+### 4. Generate Sidebar
+
+Update the `sidebar` in `docs-site/.vitepress/config.mts` based on actual docs structure.
+
+**Method:** Scan `docs-site/` and build sidebar config:
+
+```typescript
+sidebar: [
+  {
+    text: 'Overview',
+    items: [
+      { text: 'Introduction', link: '/' },
+    ],
+  },
+  {
+    text: 'Architecture & Technical',
+    items: [
+      // List actual filenames found in docs-site/
+      // e.g., { text: 'Architecture', link: '/architecture' },
+      // e.g., { text: 'Database', link: '/database' },
+    ],
+  },
+  {
+    text: 'User Guides',
+    items: [
+      // Auto-populate from docs-site/sop/*.md
+    ],
+  },
+  {
+    text: 'API Reference',
+    items: [
+      // Auto-populate from docs-site/api/*.md
+    ],
+  },
+],
+```
+
+> **Important:** VitePress sidebar `link` values are file paths without `.md` extension.
+> Example: `architecture.md` → `link: '/architecture'`
+
+### 5. Build & Verify
+
+// turbo
+```bash
+cd docs-site
+npm run build 2>&1 | tee build.log
+```
+
+**Expected:** Build completes with exit code 0. Check `build.log` for warnings.
+
+**Common build errors and fixes:**
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `dead link found` | Broken relative link | Fix link path |
+| `sidebar item not found` | Wrong link in sidebar config | Match actual filenames |
+| `YAML parse error` | Invalid frontmatter | Fix YAML syntax |
+
+> **Note:** VitePress uses pure markdown — no MDX escaping issues!
+> Characters like `<`, `{`, `}` work normally in markdown content.
+
+### 6. Preview
+
+```bash
+cd docs-site
+npm run dev -- --port 3000
+```
+
+Open `http://localhost:3000` to preview.
+
+**Verify checklist:**
+- [ ] Mermaid diagrams render correctly ← **CRITICAL**
+- [ ] Dark/light mode toggle works
+- [ ] Sidebar navigation works
+- [ ] Search works (type `/` to focus)
+- [ ] Admonitions (:::tip, :::warning) display correctly
+- [ ] `<details>` sections expand/collapse
+- [ ] Mobile responsive (hamburger menu)
+
+### 7. Post-Setup Optimizations (Optional)
+
+#### Code Groups (Multi-platform examples)
+
+VitePress has built-in code groups (replaces Docusaurus Tabs):
+
+```md
+::: code-group
+
+```bash [npm]
+npm install myapp
+```
+
+```bash [yarn]
+yarn add myapp
+```
+
+```bash [pnpm]
+pnpm add myapp
+```
+
+:::
+```
+
+#### Deploy to GitHub Pages
+
+```bash
+# Add to package.json scripts:
+# "docs:build": "vitepress build",
+# "docs:preview": "vitepress preview"
+
+# Build and deploy
+cd docs-site
+npx vitepress build
+# Output is in .vitepress/dist/
+```
+
+#### Deploy to Cloudflare Pages
+
+```bash
+# Build command: npx vitepress build
+# Build output directory: .vitepress/dist
+# Node.js version: 18
+```
+
+#### Deploy to Vercel
+
+```bash
+# Framework Preset: VitePress
+# Build command: npx vitepress build
+# Output directory: .vitepress/dist
+```

package/skills/cm-example/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: cm-example
+description: A template demonstrating the universal format compatible with Antigravity, Claude, Cursor, and OpenClaw.
+version: 1.0.0
+platforms: 
+  - all
+---
+
+# Universal Skill Example
+
+This skill demonstrates the unified format that `omni-agent` will compile into platform-specific configurations.
+
+## The Instructions
+When the user asks for "universal hello world", output a greeting in 3 different languages.
+
+## Sub-agent Instructions
+> [!NOTE] 
+> Used by platforms that support recursive agents (like Antigravity / OpenFang).
+1. Subagent A: Translate into French.
+2. Subagent B: Translate into Spanish.
+3. Subagent C: Translate into Japanese.
+
+## Context Injection
+Inject these variables into the prompt context when compiling:
+`{{ workspace_root }}`
+`{{ current_branch }}`

package/skills/cm-execution/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: cm-execution
+description: "Use when executing implementation plans — choose mode: batch execution with checkpoints, subagent-per-task, or parallel dispatch for independent problems."
+---
+
+# Execution — Execute Plans at Scale
+
+> **Role: Lead Developer** — You execute implementation plans systematically with quality gates at every checkpoint.
+
+> **Three modes, one skill.** Choose based on task structure.
+
+## Step 0: Load Working Memory (MANDATORY)
+
+Per `_shared/helpers.md#Load-Working-Memory`
+
+After EACH completed task: Per `_shared/helpers.md#Update-Continuity`
+
+### Pre-flight: Skill Coverage Audit
+
+Before choosing execution mode, scan plan tasks for technology keywords:
+
+```
+1. Extract technologies/frameworks/tools from ALL task descriptions
+2. Cross-reference with cm-skill-index Layer 1 triggers
+3. Check installed external skills: npx skills list
+4. If gap found → trigger Discovery Loop (cm-skill-mastery Part C)
+   → npx skills find "{keyword}" → review → ask user → install
+5. Log any installations to .cm-skills-log.json
+6. Only proceed to Mode Selection after all gaps resolved
+```
+
+---
+
+## Mode Selection
+
+```
+Have a plan with independent tasks?
+├── Need SPEED + QUALITY on 3+ tasks?
+│   └── YES → Mode E: TRIZ-Parallel ⚡ (recommended)
+├── Stay in this session?
+│   ├── YES → Mode B: Subagent-Driven
+│   └── NO → Mode A: Batch Execution
+└── Multiple independent failures/problems?
+    └── YES → Mode C: Parallel Dispatch
+```
+
+| Mode | When | Strategy |
+|------|------|----------|
+| **A: Batch** | Plan with checkpoints | Execute 3 tasks → report → feedback → next batch |
+| **B: Subagent** | Plan with independent tasks, same session | Fresh subagent per task + 2-stage review |
+| **C: Parallel** | 2+ independent problems | One agent per problem domain |
+| **E: TRIZ-Parallel** ⚡ | 3+ independent tasks, need speed + quality | Dependency-aware parallel dispatch with per-agent quality gates |
+
+---
+
+## Mode A: Batch Execution
+
+### Process
+1. **Load plan** → review critically → raise concerns
+2. **Execute batch** (default: 3 tasks)
+   - Mark in_progress → follow steps → verify → mark complete
+3. **Report** → show what was done + verification output
+4. **Continue** → apply feedback → next batch
+5. **Complete** → use `cm-code-review` to finish
+
+### Rules
+- Follow plan steps exactly
+- Don't skip verifications
+- Between batches: report and wait
+- Stop when blocked, don't guess
+
+---
+
+## Mode B: Subagent-Driven Development
+
+### Process
+1. **Read plan** → extract ALL tasks with full text
+2. **Per task:**
+   - Dispatch implementer subagent with full task text
+   - Answer subagent questions if any
+   - Subagent implements, tests, commits, self-reviews
+   - Dispatch spec reviewer → confirm matches spec
+   - Dispatch code quality reviewer → confirm quality
+   - If issues → implementer fixes → re-review → repeat
+3. **After all tasks** → final code review → `cm-code-review`
+
+### Prompt Template (Implementer)
+```markdown
+Implement [TASK_NAME]:
+
+[Full task text from plan]
+
+Context: [Where this fits in the project]
+
+Rules:
+- Follow TDD (cm-tdd)
+- Commit when done
+- Self-review before reporting
+- Ask questions if unclear
+
+Return: Summary of what you did + test results
+```
+
+### Red Flags
+- Never start on main/master without consent
+- Never skip reviews (spec OR quality)
+- Never dispatch parallel implementers (conflicts)
+- Never accept "close enough" on spec compliance
+
+---
+
+## Mode C: Parallel Dispatch
+
+### When
+- 3+ test files failing with different root causes
+- Multiple subsystems broken independently
+- Each problem doesn't need context from others
+
+### Process
+1. **Group failures** by independent domain
+2. **Create focused agent prompt** per domain:
+   - Specific scope (one file/subsystem)
+   - Clear goal
+   - Constraints (don't change other code)
+   - Expected output format
+3. **Dispatch in parallel**
+4. **Review + integrate** → verify no conflicts → run full suite
+
+### Common Mistakes
+- ❌ Too broad: "Fix all the tests"
+- ✅ Specific: "Fix agent-tool-abort.test.ts"
+- ❌ No context: "Fix the race condition"
+- ✅ Context: Paste error messages + test names
+
+---
+
+## Mode D: Autonomous RARV
+
+> **Self-driving execution.** Tasks flow through Reason → Act → Reflect → Verify automatically.
+
+### When
+- User runs `/cm-start` with a goal
+- `cm-tasks.json` exists with backlog items
+- You want continuous autonomous execution
+
+### Process (RARV Cycle)
+
+```
+LOOP until backlog empty or user interrupts:
+  1. REASON  → Read cm-tasks.json → pick highest-priority backlog task
+                Update task status to "in_progress"
+                Log: { phase: "REASON", message: "Selected: <title>" }
+
+  2. ACT     → Execute using the task's assigned CM skill
+                (cm-tdd, cm-debugging, cm-safe-deploy, etc.)
+                Log: { phase: "ACT", message: "<what was done>" }
+
+  3. REFLECT → Update cm-tasks.json with results
+                Log: { phase: "REFLECT", message: "<outcome summary>" }
+
+  4. VERIFY  → Run tests/checks (cm-quality-gate)
+                If PASS → status = "done", completed_at = now()
+                If FAIL → rarv_cycles++, log error, retry from REASON
+                If rarv_cycles >= 2 → attempt Skill Discovery Fallback:
+                  → npx skills find "{task keywords}"
+                  → If skill found + user approves → install, reset rarv_cycles = 0, retry
+                  → If NOT found → rarv_cycles >= 3 → status = "blocked"
+                Log: { phase: "VERIFY", message: "✅ passed" or "❌ <error>" }
+
+  5. NEXT    → Recalculate stats, pick next task
+```
+
+### cm-tasks.json Update Protocol
+
+After EVERY phase, you MUST:
+1. Read current `cm-tasks.json`
+2. Find the active task by `id`
+3. Update `status`, `logs[]`, timestamps
+4. Recalculate `stats` object:
+   ```
+   stats.total = tasks.length
+   stats.done = tasks.filter(t => t.status === 'done').length
+   stats.in_progress = tasks.filter(t => t.status === 'in_progress').length
+   stats.blocked = tasks.filter(t => t.status === 'blocked').length
+   stats.backlog = tasks.filter(t => t.status === 'backlog').length
+   stats.rarv_cycles_total = tasks.reduce((sum, t) => sum + (t.rarv_cycles || 0), 0)
+   ```
+5. Set `updated` to current ISO timestamp
+6. Write back to `cm-tasks.json`
+
+### Rules
+- **Max 3 retries** per task before marking "blocked"
+- **Always log** — the dashboard reads logs in real-time
+- **Don't batch-skip** — execute one task at a time through full RARV
+- **Respect interrupts** — if user sends a message, pause and respond
+
+---
+
+## Mode E: TRIZ-Parallel ⚡
+
+> **Speed AND quality.** 6 TRIZ principles resolve the contradiction.
+
+### When
+- 3+ tasks that can potentially run in parallel
+- Speed is important but quality cannot be sacrificed
+- Tasks are well-defined with clear file scope
+- You need to maximize throughput without merge conflicts
+
+### TRIZ Principles Applied
+
+| # | Principle | How Applied |
+|---|-----------|-------------|
+| **#1** | Segmentation | Tasks split by file-dependency graph → only truly independent tasks run together |
+| **#3** | Local Quality | Each agent runs its own mini quality gate (syntax + tests) before reporting |
+| **#10** | Prior Action | Pre-flight check scans for file overlaps BEFORE dispatch |
+| **#15** | Dynamicity | Batch size adapts: starts at 2, scales up after clean runs, down after conflicts |
+| **#18** | Feedback | Real-time conflict detection via shared ledger of modified files |
+| **#40** | Composite | Each agent = implementer + tester + reviewer (3 roles in 1) |
+
+### Process
+
+```
+1. ANALYZE    → Extract file dependencies from task descriptions
+2. GRAPH      → Build dependency graph, group into independent batches
+3. ADAPT      → Read parallel history, compute optimal batch size
+4. PRE-FLIGHT → Check conflict ledger for overlaps with running agents
+5. DISPATCH   → Send batch to agents with quality contracts
+6. MONITOR    → Each agent reports modified files → detect conflicts
+7. VERIFY     → Each agent runs mini quality gate before reporting done
+8. RECORD     → Update parallel history for future batch sizing
+```
+
+### Rules
+- **Never dispatch conflicting tasks** — pre-flight must pass
+- **Each agent must self-validate** — no "trust me it works"
+- **Adaptive sizing is mandatory** — don't hardcode batch sizes
+- **File scope is enforced** — agents must not modify files outside their scope
+- **Conflict = halt** — stop further dispatch until conflict is resolved
+
+### Common Mistakes
+- ❌ "All tasks are independent" → Always run dependency analysis first
+- ❌ "Skip pre-flight, save time" → Pre-flight prevents wasted agent work
+- ❌ "Batch size 5 for everything" → Start at 2, let the system adapt
+- ❌ "One task failed, continue anyway" → Fix before next batch
+
+---
+
+## Integration
+
+| Skill | When |
+|-------|------|
+| `cm-git-worktrees` | REQUIRED: isolated workspace before starting |
+| `cm-planning` | Creates the plan this skill executes |
+| `cm-code-review` | Complete development after all tasks |
+| `cm-tdd` | Subagents follow TDD for each task |
+| `cm-quality-gate` | VERIFY phase uses this for validation |
+| `cm-ui-preview` | RECOMMENDED: Preview UI on Google Stitch before implementing frontend tasks |
+
+### Workflows
+| Command | Purpose |
+|---------|---------|
+| `/cm-start` | Create tasks + launch RARV + open dashboard |
+| `/cm-status` | Quick terminal progress summary |
+| `/cm-dashboard` | Open browser dashboard |
+
+## The Bottom Line
+
+**Choose your mode. Execute systematically. Review at every checkpoint.**