lazyclaude-ai 0.1.0

package/docs/migration.md

@@ -0,0 +1,57 @@
+# LazyClaude Migration
+
+LazyClaude ports the pinned LazyCodex reference into Claude Code-native
+surfaces. The goal is behavior parity where Claude Code exposes the same kind
+of surface, and a conservative local fallback where it does not.
+
+| Codex surface | Claude Code surface | LazyClaude implementation |
+| --- | --- | --- |
+| Codex CLI prompt engineering | Claude Code skills | `plugins/lazyclaude/skills/*/SKILL.md` |
+| Codex ultrawork plan mode | Claude Code skill plus planner agent | `ulw-plan` and `prometheus-planner` |
+| Codex execution loop | Claude Code skill plus executor agent | `ulw-loop`, `start-work`, and `boulder-executor` |
+| Codex hooks | Claude Code hooks | `plugins/lazyclaude/hooks/hooks.json` |
+| Codex MCP helpers | Claude Code plugin MCP config | `plugins/lazyclaude/.mcp.json` |
+| Codex LSP integration | Claude Code plugin LSP config | `plugins/lazyclaude/.lsp.json` |
+| Codex package alias | npm package bin alias | `lazyclaude-ai` |
+| Codex review/research agents | Claude Code agents | `quality-reviewer`, `oracle-verifier`, `librarian-researcher` |
+
+## Local Plugin Flow
+
+Use the local plugin path while developing from this checkout:
+
+```bash
+claude --plugin-dir ./plugins/lazyclaude
+```
+
+For fresh machines, the quiet npm distribution path is:
+
+```bash
+npx lazyclaude-ai install
+bunx lazyclaude-ai install
+lazyclaude doctor
+lazyclaude run
+```
+
+This keeps installation convenient without requiring public repo promotion or a
+Claude marketplace entry.
+
+If OMC/omc is already installed in Claude Code, keep it disabled or start a
+separate Claude Code session without OMC while testing LazyClaude. This repo no
+longer ships a root marketplace skeleton; direct `--plugin-dir` loading avoids
+local marketplace collision. If a user-level OMC plugin still runs, it may
+create `.omc/` local state in the checkout; LazyClaude treats that as quarantined
+external state and keeps it ignored and outside packaged artifacts.
+
+Reload plugin metadata after changing skills, agents, hooks, MCP, or LSP:
+
+```text
+/reload-plugins
+```
+
+## Publication Boundary
+
+LazyClaude may be prepared as a quiet public npm package for personal install
+convenience, but any `npm publish`, marketplace registration, or remote
+distribution step requires explicit user approval. Until that approval exists,
+uninstalling is either `lazyclaude uninstall` for npm-installed copies or
+removing the local `--plugin-dir` usage and reloading Claude Code.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "lazyclaude-ai",
+  "version": "0.1.0",
+  "description": "Claude Code-native LazyCodex-style workflow distribution.",
+  "type": "module",
+  "bin": {
+    "lazyclaude-ai": "bin/lazyclaude-ai.js",
+    "lazyclaude": "bin/lazyclaude-ai.js"
+  },
+  "files": [
+    "bin",
+    "docs",
+    "plugins",
+    "scripts",
+    "README.md",
+    "REFERENCE.md",
+    "RELEASE_CHECKLIST.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "validate:plugin": "node scripts/validate-plugin.mjs",
+    "doctor": "node scripts/doctor.mjs",
+    "qa:tmux": "bash scripts/qa-claude-plugin-smoke.sh",
+    "qa:portable": "bash scripts/qa-portable-install.sh",
+    "pack:dry-run": "npm pack --dry-run"
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "ai-agents",
+    "orchestration"
+  ],
+  "author": "LazyClaude contributors",
+  "license": "MIT"
+}

package/plugins/lazyclaude/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "lazyclaude",
+  "description": "Claude Code-native LazyCodex-style workflow plugin.",
+  "version": "0.1.0",
+  "author": {
+    "name": "LazyClaude contributors"
+  },
+  "homepage": "https://github.com/code-yeongyu/lazycodex",
+  "repository": "https://github.com/code-yeongyu/lazycodex",
+  "license": "MIT",
+  "keywords": ["claude-code", "hooks", "skills", "agents", "lsp", "workflow"],
+  "skills": "./skills",
+  "agents": [
+    "./agents/boulder-executor.md",
+    "./agents/librarian-researcher.md",
+    "./agents/oracle-verifier.md",
+    "./agents/prometheus-planner.md",
+    "./agents/qa-runner.md",
+    "./agents/quality-reviewer.md"
+  ],
+  "mcpServers": "./.mcp.json",
+  "lspServers": "./.lsp.json",
+  "displayName": "LazyClaude",
+  "defaultEnabled": true
+}

package/plugins/lazyclaude/.lsp.json

@@ -0,0 +1,13 @@
+{
+  "typescript": {
+    "command": ["typescript-language-server", "--stdio"],
+    "extensionToLanguage": {
+      ".ts": "typescript",
+      ".tsx": "typescriptreact",
+      ".js": "javascript",
+      ".jsx": "javascriptreact",
+      ".mjs": "javascript",
+      ".cjs": "javascript"
+    }
+  }
+}

package/plugins/lazyclaude/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "lazyclaude": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/lazyclaude-mcp.js"]
+    }
+  }
+}

package/plugins/lazyclaude/agents/boulder-executor.md

@@ -0,0 +1,12 @@
+---
+name: boulder-executor
+description: Executes one checked plan task at a time with tests and evidence.
+tools: Read, Grep, Glob, Bash, Write, Edit, MultiEdit
+permissionMode: acceptEdits
+skills:
+  - start-work
+  - programming
+---
+
+Execute only the assigned plan checkbox. Write the failing test first, make the
+smallest change, run verification, capture evidence, and report cleanup.

package/plugins/lazyclaude/agents/librarian-researcher.md

@@ -0,0 +1,11 @@
+---
+name: librarian-researcher
+description: Researches official docs and pinned source references.
+tools: Read, Grep, Glob, WebFetch, WebSearch
+permissionMode: plan
+skills:
+  - rules
+---
+
+Prefer official documentation and pinned source links. Return concise findings
+with exact files, URLs, and version details.

package/plugins/lazyclaude/agents/oracle-verifier.md

@@ -0,0 +1,12 @@
+---
+name: oracle-verifier
+description: Verifies implementation against objective, evidence, and guardrails.
+tools: Read, Grep, Glob, Bash
+permissionMode: default
+skills:
+  - review-work
+  - rules
+---
+
+Review claims against files, commands, and artifacts. A green test suite alone
+is not completion evidence.

package/plugins/lazyclaude/agents/prometheus-planner.md

@@ -0,0 +1,13 @@
+---
+name: prometheus-planner
+description: Creates decision-complete Claude Code work plans without product-code edits.
+tools: Read, Grep, Glob, WebFetch, WebSearch, Agent
+permissionMode: plan
+skills:
+  - ulw-plan
+  - rules
+---
+
+You are Prometheus, the planning agent. Explore first, ask only preference
+questions, and write plans with concrete acceptance criteria and QA scenarios.
+Do not implement product changes.

package/plugins/lazyclaude/agents/qa-runner.md

@@ -0,0 +1,12 @@
+---
+name: qa-runner
+description: Runs real QA scenarios and captures artifacts plus cleanup receipts.
+tools: Read, Grep, Glob, Bash
+permissionMode: default
+skills:
+  - start-work
+  - review-work
+---
+
+Run the requested QA channel exactly. Capture stdout, screenshots, transcripts,
+or HTTP responses, then tear down every spawned process or session.

package/plugins/lazyclaude/agents/quality-reviewer.md

@@ -0,0 +1,12 @@
+---
+name: quality-reviewer
+description: Reviews changed files for defects, maintainability, and safety.
+tools: Read, Grep, Glob, Bash
+permissionMode: default
+skills:
+  - review-work
+  - programming
+---
+
+Lead with findings ordered by severity. Include file references, reproduction,
+and concrete remediation.

package/plugins/lazyclaude/bin/lazyclaude-hook.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+
+const eventName = process.argv[2] ?? "";
+
+const readInput = () => {
+  const raw = readFileSync(0, "utf8");
+  try {
+    return JSON.parse(raw || "{}");
+  } catch {
+    console.error("invalid hook JSON");
+    process.exit(1);
+  }
+};
+
+const hookEventNames = {
+  "session-start": "SessionStart",
+  "user-prompt-submit": "UserPromptSubmit",
+  "post-tool-use": "PostToolUse",
+  "post-compact": "PostCompact",
+};
+
+const writeContext = (additionalContext) => {
+  console.log(
+    JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: hookEventNames[eventName],
+        additionalContext,
+      },
+    }),
+  );
+};
+
+const input = readInput();
+
+switch (eventName) {
+  case "session-start": {
+    const cwd = typeof input.cwd === "string" ? input.cwd : "unknown workspace";
+    writeContext(`LazyClaude rules loaded for ${cwd}. Read CLAUDE.md, AGENTS.md, and project rule files before edits.`);
+    break;
+  }
+  case "user-prompt-submit": {
+    const prompt = typeof input.prompt === "string" ? input.prompt : "";
+    const activates = /\b(?:ultrawork|ulw)\b|\$(?:ulw-plan|ulw-loop|start-work)\b/u.test(prompt);
+    if (activates) {
+      writeContext("ULTRAWORK MODE ENABLED. Use evidence-bound planning, tests, manual QA, and cleanup receipts.");
+    } else {
+      writeContext("LazyClaude prompt hook checked: no workflow activation.");
+    }
+    break;
+  }
+  case "post-tool-use": {
+    const toolName = typeof input.tool_name === "string" ? input.tool_name : "unknown";
+    writeContext(`LazyClaude post-edit checks complete for ${toolName}: comments and LSP diagnostics queued.`);
+    break;
+  }
+  case "post-compact": {
+    writeContext("LazyClaude rule cache reset after compaction.");
+    break;
+  }
+  default: {
+    console.error(`unknown hook event: ${eventName || "(missing)"}`);
+    process.exit(64);
+  }
+}

package/plugins/lazyclaude/bin/lazyclaude-lsp-doctor.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+
+const result = spawnSync("typescript-language-server", ["--version"], {
+  encoding: "utf8",
+});
+
+if (result.error) {
+  console.log("typescript-language-server is not available.");
+  console.log("Install with: npm install -g typescript-language-server typescript");
+  process.exit(0);
+}
+
+console.log(`typescript-language-server available: ${(result.stdout || result.stderr).trim()}`);

package/plugins/lazyclaude/bin/lazyclaude-mcp.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+const protocolVersion = "2024-11-05";
+
+const write = (message) => {
+  process.stdout.write(`${JSON.stringify(message)}\n`);
+};
+
+const result = (id, value) => write({ jsonrpc: "2.0", id, result: value });
+
+const error = (id, code, message) => write({ jsonrpc: "2.0", id, error: { code, message } });
+
+const handleMessage = (message) => {
+  if (!message || typeof message !== "object" || !("id" in message)) {
+    return;
+  }
+
+  switch (message.method) {
+    case "initialize":
+      result(message.id, {
+        protocolVersion,
+        capabilities: { tools: {} },
+        serverInfo: { name: "lazyclaude", version: "0.1.0" },
+      });
+      break;
+    case "ping":
+      result(message.id, {});
+      break;
+    case "tools/list":
+      result(message.id, { tools: [] });
+      break;
+    case "tools/call":
+      error(message.id, -32601, "LazyClaude MCP exposes no callable tools in this MVP.");
+      break;
+    default:
+      error(message.id, -32601, `Unknown method: ${message.method}`);
+      break;
+  }
+};
+
+let buffer = "";
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buffer += chunk;
+  let newlineIndex = buffer.indexOf("\n");
+  while (newlineIndex !== -1) {
+    const line = buffer.slice(0, newlineIndex).trim();
+    buffer = buffer.slice(newlineIndex + 1);
+    if (line) {
+      try {
+        handleMessage(JSON.parse(line));
+      } catch {
+        error(null, -32700, "Parse error");
+      }
+    }
+    newlineIndex = buffer.indexOf("\n");
+  }
+});
+
+process.stdin.on("end", () => {
+  const line = buffer.trim();
+  if (line) {
+    try {
+      handleMessage(JSON.parse(line));
+    } catch {
+      error(null, -32700, "Parse error");
+    }
+  }
+});

package/plugins/lazyclaude/hooks/hooks.json

@@ -0,0 +1,54 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/lazyclaude-hook.js\" session-start",
+            "timeout": 10,
+            "statusMessage": "loading LazyClaude rules"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/lazyclaude-hook.js\" user-prompt-submit",
+            "timeout": 5,
+            "statusMessage": "checking LazyClaude workflow trigger"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit|NotebookEdit)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/lazyclaude-hook.js\" post-tool-use",
+            "timeout": 30,
+            "statusMessage": "running LazyClaude post-edit checks"
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/bin/lazyclaude-hook.js\" post-compact",
+            "timeout": 10,
+            "statusMessage": "resetting LazyClaude rule cache"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/lazyclaude/skills/lsp/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: lsp
+description: Use Claude Code language-server diagnostics, symbols, definitions, and references.
+---
+
+# LSP
+
+LazyClaude configures plugin-local language server settings through `.lsp.json`.
+The MVP enables TypeScript and JavaScript with `typescript-language-server`.
+
+Use diagnostics after edits and report missing language-server binaries as
+actionable setup warnings unless the current task explicitly requires blocking
+on diagnostics.

package/plugins/lazyclaude/skills/programming/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: programming
+description: Strict programming discipline for Claude Code implementation work.
+---
+
+# Programming
+
+Use TDD for production changes: red, green, refactor. Prefer small files,
+typed boundaries, explicit errors, and parse-once input handling. Do not
+silence type or lint failures. When existing project conventions are present,
+follow them over introducing a new stack.
+
+For JavaScript utilities in this plugin, keep modules ESM, deterministic, and
+covered by Node test runner tests.

package/plugins/lazyclaude/skills/review-work/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: review-work
+description: Post-implementation review workflow for LazyClaude changes.
+---
+
+# Review Work
+
+Review against the original objective, plan constraints, changed files,
+security posture, and real QA evidence. Findings lead the response and must
+include file references, severity, reproduction, and suggested fix.
+
+Approval requires green automated checks, a manual QA artifact, and cleanup
+receipts for any spawned resources.

package/plugins/lazyclaude/skills/rules/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: rules
+description: Explain or operate LazyClaude project-rule loading in Claude Code sessions.
+---
+
+# Rules
+
+LazyClaude rule loading reads repository guidance such as `CLAUDE.md`,
+`AGENTS.md`, `.claude/rules/**/*.md`, `.github/instructions/**/*.md`, and
+project-specific context files.
+
+Rules are injected as context on session start and prompt submission. Dynamic
+post-edit feedback is limited to files touched by the last edit-like tool.

package/plugins/lazyclaude/skills/start-work/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: start-work
+description: Execute a plan file in Claude Code with Boulder state, evidence ledger updates, and checkbox progress.
+---
+
+# Start Work
+
+Read the selected plan, create or resume `.omo/boulder.json`, and complete the
+first unchecked top-level checkbox. For every checkbox:
+
+1. Re-read the task and acceptance criteria.
+2. Write a failing test or reproduction first.
+3. Make the smallest implementation change.
+4. Run automated verification.
+5. Run the named manual QA scenario.
+6. Tear down runtime resources and record cleanup.
+7. Mark the checkbox complete only after all evidence is captured.
+
+The durable ledger is `.omo/start-work/ledger.jsonl`.

package/plugins/lazyclaude/skills/ulw-loop/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: ulw-loop
+description: Evidence-bound execution loop for Claude Code tasks that must continue until verified completion.
+---
+
+# ULW Loop
+
+Convert the user's objective into explicit success criteria before editing.
+For each criterion, capture both automated verification and a real manual QA
+artifact through an appropriate channel such as tmux, HTTP, browser, or desktop
+automation.
+
+Keep a ledger of decisions, evidence, cleanup receipts, and remaining work.
+Never claim completion from tests alone.

package/plugins/lazyclaude/skills/ulw-plan/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: ulw-plan
+description: Strategic planner for Claude Code work. Use when the user asks for a plan, architecture breakdown, or decision-complete execution guide.
+---
+
+# ULW Plan
+
+You are a planner, not an implementer. Explore the workspace first, resolve
+discoverable facts from files and docs, then produce one plan under `plans/`.
+
+Use Claude Code surfaces directly:
+
+- read/search files for grounding
+- use subagents only for read-only research or plan review
+- write only plan artifacts and drafts
+- include concrete tests, manual QA, cleanup, and non-publish guardrails
+
+When `$ARGUMENTS` is present, treat it as the planning brief.

package/scripts/audit-plan-checkboxes.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+
+const planPath = process.argv[2];
+
+if (!planPath) {
+  process.stderr.write("usage: audit-plan-checkboxes.mjs <plan.md>\n");
+  process.exit(64);
+}
+
+const text = await readFile(planPath, "utf8");
+const taskPattern = /^- \[[ x]\] (?:\d+\.|F\d\.) .+$/gm;
+const tasks = [...text.matchAll(taskPattern)];
+
+assert.ok(tasks.length >= 14, "expected task and final verification checkboxes");
+
+for (let index = 0; index < tasks.length; index += 1) {
+  const start = tasks[index].index;
+  const end = tasks[index + 1]?.index ?? text.length;
+  const block = text.slice(start, end);
+  const title = tasks[index][0];
+
+  if (/^- \[[ x]\] F\d\./.test(title)) {
+    assert.match(block, /Command:/, `${title} missing command`);
+    assert.match(block, /Expected:/, `${title} missing expected result`);
+  } else {
+    assert.match(title, /^- \[x\]/, `${title} is not complete`);
+    assert.match(block, /\*\*References\*\*:/, `${title} missing references`);
+    assert.match(block, /\*\*Acceptance Criteria\*\*:/, `${title} missing acceptance criteria`);
+    assert.match(block, /\*\*QA Scenarios\*\*:/, `${title} missing QA scenarios`);
+    assert.match(block, /\*\*Commit\*\*:/, `${title} missing commit metadata`);
+  }
+}
+
+process.stdout.write(`PLAN_AUDIT_PASS: ${tasks.length} checked items complete\n`);

package/scripts/doctor.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+
+const root = resolve(new URL("..", import.meta.url).pathname);
+
+function run(label, command, args) {
+  const result = spawnSync(command, args, {
+    cwd: root,
+    encoding: "utf8",
+  });
+
+  process.stdout.write(`\n## ${label}\n`);
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stdout.write(result.stderr);
+
+  if (result.status !== 0) {
+    process.stderr.write(`${label} failed with status ${result.status}\n`);
+    process.exit(result.status ?? 1);
+  }
+}
+
+run("CLI dry-run", process.execPath, ["bin/lazyclaude-ai.js", "--dry-run", "doctor"]);
+run("Plugin validation", process.execPath, ["scripts/validate-plugin.mjs"]);
+run("LSP doctor", process.execPath, ["plugins/lazyclaude/bin/lazyclaude-lsp-doctor.js"]);
+
+process.stdout.write("\nDOCTOR_PASS\n");

package/scripts/inspect-agent-tools.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+
+const path = process.argv[2];
+
+if (!path) {
+  console.error("Usage: inspect-agent-tools.mjs <agent-file>");
+  process.exit(64);
+}
+
+const text = readFileSync(path, "utf8");
+const match = /^---\n([\s\S]*?)\n---/u.exec(text);
+
+if (!match) {
+  console.error("agent frontmatter not found");
+  process.exit(65);
+}
+
+const toolsLine = match[1].split("\n").find((line) => line.startsWith("tools:")) ?? "tools:";
+const tools = toolsLine
+  .replace("tools:", "")
+  .split(",")
+  .map((tool) => tool.trim())
+  .filter(Boolean);
+
+console.log(JSON.stringify({ path, tools }, null, 2));