lazyclaude-ai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LazyClaude contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# LazyClaude
+
+LazyClaude is a Claude Code-native retrofit of the LazyCodex workflow style:
+simple local activation, prompt-triggered ultrawork discipline,
+planner/executor/reviewer agents, lifecycle hooks, MCP scaffolding, and
+LSP-backed code checks.
+
+LazyClaude is intended as a quiet personal distribution. It can be prepared for
+public npm installation convenience without advertising, public repo promotion,
+or Claude marketplace publication. Do not run `npm publish`, mutate a
+marketplace, or promote this as publicly available without explicit user
+approval. Until that approval is given, this package is not published.
+
+## Fresh PC Install
+
+Use one of these npm-compatible entrypoints on a new machine:
+
+```bash
+npx lazyclaude-ai install
+bunx lazyclaude-ai install
+npm install -g lazyclaude-ai
+lazyclaude install
+```
+
+The installer copies the packaged Claude Code plugin into a LazyClaude-managed
+user directory and prints the exact launch command:
+
+```bash
+claude --plugin-dir ~/.lazyclaude/current/plugins/lazyclaude
+```
+
+Validate the install:
+
+```bash
+lazyclaude doctor
+```
+
+Launch Claude Code through the installed plugin:
+
+```bash
+lazyclaude run -- --help
+lazyclaude run
+```
+
+Remove only LazyClaude-managed install state:
+
+```bash
+lazyclaude uninstall
+```
+
+Set `LAZYCLAUDE_HOME=/some/path` to install into a custom directory for testing
+or isolated machines.
+
+## Local Install
+
+Use the plugin directly from this checkout while it is under development:
+
+```bash
+claude --plugin-dir ./plugins/lazyclaude
+```
+
+If you already have an OMC/omc Claude plugin installed, do not co-load it with
+LazyClaude during this local MVP test. LazyClaude intentionally avoids a root
+Claude marketplace skeleton now, so it can be loaded directly by
+path without competing with an existing OMC marketplace or plugin namespace.
+If your user-level Claude config still enables OMC, Claude may create a local
+`.omc/` state directory during smoke tests; LazyClaude ignores and excludes that
+directory from git and npm package surfaces.
+
+Inside Claude Code, reload local plugin metadata after edits:
+
+```text
+/reload-plugins
+```
+
+## ULW Usage
+
+Start Claude Code from this repo:
+
+```bash
+claude --plugin-dir ./plugins/lazyclaude
+```
+
+Then type one of these prompts in Claude Code:
+
+```text
+ulw
+ultrawork
+$ulw-plan <what you want planned>
+$ulw-loop <what you want executed with evidence>
+$start-work plans/lazyclaude-retrofit.md
+```
+
+Expected behavior: LazyClaude's prompt hook adds `ULTRAWORK MODE ENABLED`
+context, then the matching skill/agent instructions steer Claude toward
+test-first work, real manual QA evidence, cleanup receipts, and no publish step
+without approval.
+
+Plain `ulw` is hook context activation, so it may not show a separate Skill
+tool invocation in Claude Code history. Use visible namespaced commands when
+you want explicit LazyClaude skill/command activation:
+
+```text
+/lazyclaude:ulw-loop <what you want executed with evidence>
+/lazyclaude:ulw-plan <what you want planned>
+/lazyclaude:start-work plans/lazyclaude-retrofit.md
+```
+
+The package alias can be inspected without installing anything globally:
+
+```bash
+node bin/lazyclaude-ai.js --dry-run install
+node bin/lazyclaude-ai.js --dry-run doctor
+```
+
+## Local Development
+
+```bash
+npm test
+npm run validate:plugin
+npm run qa:tmux
+npm run pack:dry-run
+```
+
+`validate:plugin` and `qa:tmux` are local checks. If Claude Code is not
+available on the machine, the smoke harness records a controlled skip with the
+version probe evidence instead of failing mysteriously.
+
+## Rollback And Uninstall
+
+For npm-installed LazyClaude, run:
+
+```bash
+lazyclaude uninstall
+```
+
+Because the local MVP can also be loaded with
+`claude --plugin-dir ./plugins/lazyclaude`, checkout rollback is local and
+reversible:
+
+1. Stop the Claude Code session that loaded the plugin.
+2. Start Claude Code without the `--plugin-dir` flag.
+3. Remove any temporary plugin-dir reference you added for testing.
+4. Run `/reload-plugins` in any remaining Claude Code session that should stop
+   seeing LazyClaude.
+
+No global install step is required for this MVP.
+
+## Safety Model
+
+LazyClaude is intentionally local-first:
+
+- Hooks read Claude Code event JSON from stdin and return bounded JSON context.
+- Hooks do not execute user prompt text.
+- The ultrawork prompt hook returns constant guidance and does not echo prompt
+  text back into the context.
+- Any `.omc/` directory created by a user-level OMC plugin is ignored and is not
+  included in the LazyClaude package.
+- The planner agent is read-only and has no edit tools.
+- MCP and LSP helpers are local stdio commands.
+- Publication, remote marketplace mutation, and package release all require
+  explicit user approval.
+
+## MVP Scope
+
+- Package/bin: `lazyclaude-ai`
+- Plugin namespace: `lazyclaude`
+- Claude Code platform: `claude-code`
+- Skills: ultrawork planning, ultrawork loop, start-work, rules, LSP,
+  programming, review-work
+- Agents: planner, executor, verifier, reviewer, librarian, QA runner
+- Hooks: session-start, user-prompt-submit, post-tool-use, post-compact
+- Config: local MCP server and TypeScript-family LSP doctor
+
+See `REFERENCE.md` for the pinned LazyCodex source. See `docs/migration.md` for
+the Codex-to-Claude migration table.

package/REFERENCE.md

@@ -0,0 +1,21 @@
+# LazyClaude Reference Pin
+
+LazyCodex commit: 3fb8802e314dc0a1f23481dd3782cdca26b92dc2
+Claude docs snapshot: 2026-05-31
+
+## Source
+
+- Repository: https://github.com/code-yeongyu/lazycodex
+- Pinned tree: https://github.com/code-yeongyu/lazycodex/tree/3fb8802e314dc0a1f23481dd3782cdca26b92dc2
+- Observed reference clone: `/tmp/lazycodex-ref`
+
+## Migration Table
+
+| Codex surface | Claude Code surface | Notes |
+| --- | --- | --- |
+| `.codex-plugin/plugin.json` | `.claude-plugin/plugin.json` | Plugin identity and component paths are translated, not copied. |
+| Codex skills | Claude Code `skills/<name>/SKILL.md` | Skills keep workflow intent and remove Codex-only tool names. |
+| Codex hooks | Claude Code `hooks/hooks.json` | Hook events are mapped to Claude tool names and JSON stdin behavior. |
+| Codex MCP config | Claude Code `.mcp.json` | Local helper tools stay plugin-scoped. |
+| Codex LSP MCP component | Claude Code `.lsp.json` | MVP starts with TypeScript/JavaScript. |
+| Codex subagent orchestration | Claude Code `agents/*.md` | Agents get bounded tools, permissions, and optional preloaded skills. |

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,86 @@
+# LazyClaude Release Checklist
+
+Status: quiet public npm package candidate; currently unpublished until explicit
+user approval.
+
+DO NOT publish LazyClaude, run `npm publish`, push release tags, or add a
+remote Claude Code marketplace entry without explicit user approval.
+
+This release path is for personal install convenience, not advertisement,
+public repo promotion, or a public launch campaign.
+
+## Verified Locally
+
+- `npm test`
+- `npm run validate:plugin`
+- `npm run qa:tmux`
+- `npm run pack:dry-run`
+
+## Local / Private Checkout Use
+
+Use this track when testing from the current checkout:
+
+1. Run `npm test`.
+2. Run `npm run validate:plugin`.
+3. Run `npm run qa:tmux`.
+4. Start Claude Code with `claude --plugin-dir ./plugins/lazyclaude`.
+
+No npm publication is required for this track.
+
+## Quiet Public NPM Package Release
+
+Use this track only when the user explicitly approves making the package
+installable through `npm`, `npx`, and `bunx`.
+
+1. Confirm the target package name and version with the user.
+2. Review `REFERENCE.md` and `docs/migration.md` for accurate attribution.
+3. Run `npm whoami` and confirm the intended npm account.
+4. Re-run the full local verification set from a clean checkout:
+   - `npm test`
+   - `npm run validate:plugin`
+   - `npm run doctor`
+   - `npm run qa:tmux`
+   - `npm run qa:portable`
+   - `npm run pack:dry-run`
+5. Inspect `npm pack --dry-run --json` and confirm package contents.
+6. Ask for explicit user approval to publish.
+7. Only after approval, perform the selected publication path in a separate,
+   auditable release step.
+
+For the current unscoped `lazyclaude-ai` package name, use:
+
+```bash
+npm publish
+```
+
+If the package is renamed to a scoped package such as `@scope/lazyclaude-ai`,
+publish it publicly with:
+
+```bash
+npm publish --access public
+```
+
+## Accidental Publish Rollback
+
+If the wrong package or version is published, stop and report the incident
+before further mutation. Depending on npm policy and timing, choose one audited
+rollback action with user approval:
+
+1. `npm deprecate <package>@<version> "<message>"`
+2. `npm unpublish <package>@<version>` only when allowed and explicitly approved
+3. Publish a corrected patch version after verification
+
+## Marketplace Boundary
+
+LazyClaude is tested through `claude --plugin-dir ./plugins/lazyclaude`. A root
+Claude marketplace file is intentionally not shipped because users may already
+have an OMC/omc marketplace or plugin installed. Do not add a local or remote
+marketplace entry without explicit user approval. If user-level OMC creates
+`.omc/` state during validation, keep it ignored and confirm it is absent from
+the package dry-run.
+
+## Rollback
+
+If a local test load causes problems, stop Claude Code, restart without
+`claude --plugin-dir ./plugins/lazyclaude`, and run `/reload-plugins` in any
+remaining session that should drop the local plugin metadata.

package/bin/lazyclaude-ai.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const version = packageJson.version;
+
+const usage = `Usage: lazyclaude-ai [--dry-run] <install|doctor|path|run|update|uninstall> [...args]
+
+Commands:
+  install       Copy the packaged LazyClaude plugin into LAZYCLAUDE_HOME.
+  doctor        Validate the installed LazyClaude plugin path.
+  path          Print the installed Claude plugin path.
+  run -- ...    Run Claude Code with the installed plugin path.
+  update        Reinstall this package version and refresh the current pointer.
+  uninstall     Remove LazyClaude-managed install state.
+`;
+
+const parseArgs = (argv) => {
+  const args = [...argv];
+  const dryRun = args[0] === "--dry-run";
+  if (dryRun) args.shift();
+  return { dryRun, command: args[0], rest: args.slice(1) };
+};
+
+const lazyHome = () => resolve(process.env.LAZYCLAUDE_HOME ?? join(homedir(), ".lazyclaude"));
+const versionRoot = (home = lazyHome()) => join(home, "lazyclaude-ai", version);
+const currentRoot = (home = lazyHome()) => join(home, "current");
+const pluginPathForRoot = (installRoot) => join(installRoot, "plugins", "lazyclaude");
+const intendedPluginPath = (home = lazyHome()) => pluginPathForRoot(currentRoot(home));
+const sourcePluginPath = () => join(root, "plugins", "lazyclaude");
+
+const printUsage = () => {
+  process.stderr.write(usage);
+};
+
+const fail = (message, status = 1) => {
+  process.stderr.write(`${message}\n`);
+  process.exit(status);
+};
+
+const currentExists = (home = lazyHome()) => existsSync(currentRoot(home));
+
+const requireInstalledPluginPath = (home = lazyHome()) => {
+  if (!currentExists(home)) {
+    fail("LazyClaude is not installed. Run `lazyclaude install` first.");
+  }
+  const path = intendedPluginPath(home);
+  if (!existsSync(join(path, ".claude-plugin", "plugin.json"))) {
+    fail("LazyClaude install is incomplete. Run `lazyclaude install` again.");
+  }
+  return path;
+};
+
+const resetCurrentPointer = (home, target) => {
+  const current = currentRoot(home);
+  rmSync(current, { recursive: true, force: true });
+  try {
+    symlinkSync(target, current, "dir");
+  } catch {
+    mkdirSync(current, { recursive: true });
+    cpSync(target, current, { recursive: true });
+  }
+};
+
+const install = ({ dryRun }) => {
+  const home = lazyHome();
+  const targetRoot = versionRoot(home);
+  const targetPlugin = pluginPathForRoot(targetRoot);
+  const sourcePlugin = sourcePluginPath();
+
+  if (dryRun) {
+    process.stdout.write(`DRY_RUN: install LazyClaude ${version}\n`);
+    process.stdout.write(`Would copy: ${sourcePlugin} -> ${targetPlugin}\n`);
+    process.stdout.write(`Would point current: ${currentRoot(home)} -> ${targetRoot}\n`);
+    process.stdout.write(`Launch with: claude --plugin-dir ${intendedPluginPath(home)}\n`);
+    return;
+  }
+
+  if (!existsSync(sourcePlugin)) {
+    fail(`Packaged LazyClaude plugin payload is missing: ${sourcePlugin}`);
+  }
+
+  rmSync(targetRoot, { recursive: true, force: true });
+  mkdirSync(dirname(targetPlugin), { recursive: true });
+  cpSync(sourcePlugin, targetPlugin, { recursive: true });
+  resetCurrentPointer(home, targetRoot);
+
+  process.stdout.write(`INSTALL_PASS: LazyClaude ${version} installed\n`);
+  process.stdout.write(`Plugin path: ${intendedPluginPath(home)}\n`);
+  process.stdout.write(`Launch with: claude --plugin-dir ${intendedPluginPath(home)}\n`);
+};
+
+const doctor = ({ dryRun }) => {
+  if (dryRun) {
+    const pluginPath = intendedPluginPath();
+    process.stdout.write("DRY_RUN: doctor LazyClaude install\n");
+    process.stdout.write(`Would check plugin files under: ${pluginPath}\n`);
+    process.stdout.write(`Would run: claude plugin validate ${pluginPath}\n`);
+    return;
+  }
+
+  const pluginPath = requireInstalledPluginPath();
+  const requiredFiles = [
+    ".claude-plugin/plugin.json",
+    ".mcp.json",
+    ".lsp.json",
+    "hooks/hooks.json",
+    "bin/lazyclaude-hook.js",
+    "bin/lazyclaude-mcp.js",
+    "skills/ulw-loop/SKILL.md",
+    "skills/ulw-plan/SKILL.md",
+  ];
+
+  for (const file of requiredFiles) {
+    const path = join(pluginPath, file);
+    if (!existsSync(path)) fail(`LazyClaude install is missing ${file}. Run \`lazyclaude install\` again.`);
+  }
+
+  const claude = spawnSync("claude", ["--version"], { encoding: "utf8" });
+  if (claude.error) {
+    process.stdout.write("CLAUDE_WARNING: claude executable not found in PATH\n");
+  } else {
+    process.stdout.write(`CLAUDE_VERSION: ${(claude.stdout || claude.stderr).trim()}\n`);
+    const validation = spawnSync("claude", ["plugin", "validate", pluginPath], { encoding: "utf8" });
+    if (validation.status !== 0) {
+      if (validation.stdout) process.stderr.write(validation.stdout);
+      if (validation.stderr) process.stderr.write(validation.stderr);
+      fail("Claude plugin validation failed.");
+    }
+    process.stdout.write("CLAUDE_PLUGIN_VALIDATE_PASS\n");
+  }
+
+  process.stdout.write(`Plugin path: ${pluginPath}\n`);
+  process.stdout.write(`Launch with: claude --plugin-dir ${pluginPath}\n`);
+  process.stdout.write("DOCTOR_PASS\n");
+};
+
+const printPath = () => {
+  process.stdout.write(`${requireInstalledPluginPath()}\n`);
+};
+
+const runClaude = ({ dryRun, rest }) => {
+  const separatorIndex = rest.indexOf("--");
+  const claudeArgs = separatorIndex === -1 ? rest : rest.slice(separatorIndex + 1);
+  const pluginPath = dryRun ? intendedPluginPath() : requireInstalledPluginPath();
+  const command = ["claude", "--plugin-dir", pluginPath, ...claudeArgs];
+
+  if (dryRun) {
+    process.stdout.write(command.join(" "));
+    process.stdout.write("\n");
+    return;
+  }
+
+  const result = spawnSync(command[0], command.slice(1), { stdio: "inherit" });
+  if (result.error) fail(`failed to start claude: ${result.error.message}`);
+  process.exit(result.status ?? 1);
+};
+
+const uninstall = ({ dryRun }) => {
+  const home = lazyHome();
+  if (dryRun) {
+    process.stdout.write(`DRY_RUN: remove ${join(home, "lazyclaude-ai")} and ${currentRoot(home)}\n`);
+    return;
+  }
+  rmSync(currentRoot(home), { recursive: true, force: true });
+  rmSync(join(home, "lazyclaude-ai"), { recursive: true, force: true });
+  process.stdout.write("UNINSTALL_PASS\n");
+};
+
+const main = () => {
+  const parsed = parseArgs(process.argv.slice(2));
+  const { command } = parsed;
+
+  if (!command) {
+    printUsage();
+    process.exit(64);
+  }
+
+  switch (command) {
+    case "install":
+    case "update":
+      install(parsed);
+      break;
+    case "doctor":
+      doctor(parsed);
+      break;
+    case "path":
+      printPath(parsed);
+      break;
+    case "run":
+      runClaude(parsed);
+      break;
+    case "uninstall":
+      uninstall(parsed);
+      break;
+    default:
+      printUsage();
+      fail(`Unknown command: ${command}`, 64);
+  }
+};
+
+main();

package/docs/agents.md

@@ -0,0 +1,31 @@
+# LazyClaude Agents
+
+LazyClaude agents map the LazyCodex team workflow into Claude Code subagents
+with bounded responsibilities.
+
+| Agent | Responsibility | Boundary |
+| --- | --- | --- |
+| `prometheus-planner` | Build implementation plans and identify risks. | Read-only tools, no write/edit/bash tools. |
+| `boulder-executor` | Execute checked plan tasks. | Must follow task acceptance criteria and collect evidence. |
+| `oracle-verifier` | Verify tests, artifacts, and task completion. | Reviews evidence before approval. |
+| `quality-reviewer` | Perform code-review style risk checks. | Findings first, no unrelated rewrites. |
+| `librarian-researcher` | Fetch and summarize external references. | Use primary sources and cite them. |
+| `qa-runner` | Run tmux/manual QA scenarios. | Must clean up sessions and capture receipts. |
+
+The planner is deliberately constrained because the safest Claude Code retrofit
+keeps planning separate from mutation. Executor and QA agents can act only
+inside the plan and evidence contract.
+
+## Local Use
+
+Load the plugin from this checkout:
+
+```bash
+claude --plugin-dir ./plugins/lazyclaude
+```
+
+Then reload after edits:
+
+```text
+/reload-plugins
+```

package/docs/hooks.md

@@ -0,0 +1,60 @@
+# LazyClaude Hooks
+
+LazyClaude hooks translate the LazyCodex prompt workflow into Claude Code hook
+events while keeping execution local and bounded.
+
+## Hook Events
+
+| Event | Runner | Purpose |
+| --- | --- | --- |
+| `SessionStart` | `plugins/lazyclaude/bin/lazyclaude-hook.js session-start` | Adds a compact rules-loaded context line. |
+| `UserPromptSubmit` | `plugins/lazyclaude/bin/lazyclaude-hook.js user-prompt-submit` | Detects ultrawork prompts and injects workflow context. |
+| `PostToolUse` | `plugins/lazyclaude/bin/lazyclaude-hook.js post-tool-use` | Reminds the session to run post-edit checks. |
+| `PostCompact` | `plugins/lazyclaude/bin/lazyclaude-hook.js post-compact` | Resets compacted rule context after summarization. |
+
+## ULW Trigger Phrases
+
+The `UserPromptSubmit` hook activates on any of these phrases:
+
+```text
+ulw
+ultrawork
+$ulw-plan
+$ulw-loop
+$start-work
+```
+
+When a trigger is present, the hook returns additional context containing
+`ULTRAWORK MODE ENABLED`. That context is guidance for Claude Code; it is not
+executed as a command.
+
+Plain `ulw` therefore activates hook context, not a visible Skill tool call.
+For a visible LazyClaude command/skill invocation, use the namespaced Claude
+Code commands:
+
+```text
+/lazyclaude:ulw-loop <goal>
+/lazyclaude:ulw-plan <planning brief>
+/lazyclaude:start-work plans/lazyclaude-retrofit.md
+```
+
+## Safety
+
+Hooks parse JSON from stdin and return JSON to Claude Code. The hook does not
+execute prompt text and does not echo prompt text into the returned context. The
+ultrawork detector returns constant workflow guidance, so a prompt cannot become
+a shell command through the hook response.
+
+## Local Smoke
+
+Run the hook fixture directly:
+
+```bash
+node plugins/lazyclaude/bin/lazyclaude-hook.js user-prompt-submit < fixtures/hooks/user-prompt-ultrawork.json
+```
+
+Reload local plugin metadata in Claude Code after hook edits:
+
+```text
+/reload-plugins
+```

package/docs/lsp.md

@@ -0,0 +1,35 @@
+# LazyClaude LSP
+
+LazyClaude includes a Claude Code plugin LSP config and a local doctor command
+for TypeScript-family projects.
+
+## Configuration
+
+`plugins/lazyclaude/.lsp.json` declares a TypeScript language server command:
+
+```json
+["typescript-language-server", "--stdio"]
+```
+
+It covers `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, and `.cjs` files.
+
+## Doctor
+
+Run the doctor locally:
+
+```bash
+node plugins/lazyclaude/bin/lazyclaude-lsp-doctor.js
+```
+
+If `typescript-language-server` is unavailable, the doctor exits successfully
+with installation guidance so local smoke tests can distinguish an environment
+gap from a plugin failure.
+
+## Claude Code Reload
+
+After changing `.lsp.json`, restart Claude Code with the local plugin directory
+or use:
+
+```text
+/reload-plugins
+```