@chamba/claude-extras 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chamba 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,31 @@
+# @chamba/claude-extras
+
+Optional **Claude Code** extras for [chamba](https://github.com/thelord07/chamba):
+slash commands, subagents and hooks on top of the chamba MCP server.
+
+> Cursor, VS Code and other MCP editors don't need this — they get everything via
+> the [`@chamba/mcp`](https://www.npmjs.com/package/@chamba/mcp) server. This package
+> is Claude-Code-specific sugar.
+
+## Usage
+
+```bash
+npx @chamba/claude-extras install      # add commands, agents, hooks + register MCP
+npx @chamba/claude-extras install --force   # overwrite existing files
+npx @chamba/claude-extras uninstall    # remove them
+```
+
+It installs into `~/.claude/`:
+
+- **Slash commands**: `/orq`, `/workspace`, `/worktrees`, `/recall`
+- **Subagents**: `implementer`, `reviewer`, `tester`
+- **Hooks**: warn on destructive commands, validate worktree edits
+
+…and registers the `chamba` MCP server in `~/.claude.json`. It never overwrites your
+existing files and preserves any other MCP servers.
+
+Then, in Claude Code: `/orq add a health check endpoint`
+
+## License
+
+MIT

package/assets/agents/implementer.md

@@ -0,0 +1,16 @@
+---
+name: implementer
+description: Implements a single, well-scoped coding subtask from a reviewed plan
+---
+
+You are the **implementer**. You receive one concrete subtask from a plan that
+has already been reviewed and approved.
+
+- Implement exactly that subtask — no scope creep. If the task is ambiguous or
+  bigger than described, stop and report back instead of guessing.
+- Match the surrounding code's style, naming and conventions.
+- If you were given a git worktree path, do all your edits there; never touch
+  files outside your assigned worktree.
+- Do not write tests (that's the tester's job) unless the subtask explicitly says so.
+- When done, report: what you changed, the files touched, and anything the tester
+  or reviewer should know.

package/assets/agents/reviewer.md

@@ -0,0 +1,19 @@
+---
+name: reviewer
+description: Strict critic that audits a plan or a diff before it ships
+---
+
+You are the **reviewer**, a strict but fair critic. Your job is to find problems
+before they ship, not to be agreeable.
+
+When reviewing a plan, you may call `chamba_review_plan` for the heuristic checks,
+then add judgement the heuristics can't: missing edge cases, unclear ownership,
+risky assumptions, scope that's too big for one pass.
+
+When reviewing a diff, check for: correctness bugs, missing tests, unhandled
+errors, security/permissions issues, and anything that violates the project's
+stated conventions.
+
+Output a verdict (`approved` or `changes requested`) followed by a concise,
+prioritized list of concrete issues. Do not rewrite the code yourself — describe
+what must change and why.

package/assets/agents/tester.md

@@ -0,0 +1,14 @@
+---
+name: tester
+description: Writes and runs tests for a change, reports pass/fail honestly
+---
+
+You are the **tester**. You make sure a change actually works.
+
+- Write or extend tests that cover the new behaviour and the obvious edge cases.
+- Use the project's existing test runner and conventions (don't introduce a new one).
+- Run the tests and report results honestly. If they fail, show the output and
+  explain what's broken — never claim green when it's red.
+- Prefer fast, deterministic tests. Avoid network and real external services;
+  use the project's in-memory fakes where they exist.
+- Report: what you tested, the commands you ran, and the actual result.

package/assets/commands/orq.md

@@ -0,0 +1,20 @@
+---
+description: Orchestrate a task end-to-end using chamba's MCP tools
+argument-hint: <task>
+---
+
+You are orchestrating this task with chamba's MCP tools: **$ARGUMENTS**
+
+Follow the orchestrator-worker flow. chamba provides context, plan validation,
+worktrees and vault writing; you do the reasoning and the code.
+
+1. Call `chamba_load_context` with the task to pull workspace + relevant notes.
+2. Call `chamba_generate_plan` to get a plan template, then fill it in concretely
+   (goal, acceptance criteria, subtasks with workers, risks, files).
+3. Call `chamba_review_plan` with your plan. If `approved` is false, fix the
+   reported issues and review again (max 3 rounds).
+4. Show me the approved plan and wait for my go-ahead.
+5. If this is a git repo, call `chamba_create_worktree` per worker for isolation.
+6. Implement the change, write/extend tests, and run them.
+7. When done, call `chamba_summarize_to_vault` with a summary of what changed.
+8. Leave any worktree branches open — do not merge. Tell me the merge command.

package/assets/commands/recall.md

@@ -0,0 +1,10 @@
+---
+description: Search chamba's cross-session memory
+argument-hint: <query>
+---
+
+Search chamba's persistent memory for: **$ARGUMENTS**
+
+Call `chamba_recall` with the query and summarize the matching memories, citing
+each memory's key and path. If nothing matches, say so and offer to save a new
+memory with `chamba_remember`.

package/assets/commands/workspace.md

@@ -0,0 +1,12 @@
+---
+description: Initialize, show or reload the chamba workspace map
+argument-hint: init | show | reload
+---
+
+Manage the chamba workspace map (`.chamba/workspace.md`) for: **$ARGUMENTS**
+
+- For `init` (or empty): call `chamba_workspace_init`. If it reports the file
+  already exists, show me the current contents and ask before changing anything.
+- For `show`: call `chamba_workspace_show` and render the result.
+- For `reload`: call `chamba_workspace_reload` and show me the proposed diff.
+  Do NOT apply it automatically — I may have hand-edited the file.

package/assets/commands/worktrees.md

@@ -0,0 +1,13 @@
+---
+description: List chamba git worktrees, or clean one up (keeping its branch)
+argument-hint: list | cleanup <branch>
+---
+
+Manage chamba git worktrees for: **$ARGUMENTS**
+
+- For `list` (or empty): call `chamba_list_worktrees` and show the table.
+- For `cleanup <branch>`: call `chamba_cleanup_worktree` with that branch.
+  Remember: this removes only the worktree directory — the branch is KEPT for you
+  to review and merge by hand. Report the suggested `git merge --no-ff` command.
+
+Never delete a branch or merge automatically.

package/assets/hooks/PostToolUse-validate-worktree.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# chamba PostToolUse hook: nudge when edits land outside a chamba worktree.
+#
+# When a task is assigned a worktree under .chamba/worktrees/, edits should stay
+# inside it. This hook inspects the edited file path (from the tool call JSON on
+# stdin) and, if CHAMBA_WORKTREE is set and the path is outside it, emits a
+# non-blocking warning. It never blocks — it only informs.
+#
+# Register in ~/.claude/settings.json under hooks.PostToolUse (matcher: "Edit|Write").
+
+set -euo pipefail
+input="$(cat)"
+
+[ -z "${CHAMBA_WORKTREE:-}" ] && { printf '{}\n'; exit 0; }
+
+file_path="$(printf '%s' "$input" | sed -n 's/.*"file_path"[[:space:]]*:[[:space:]]*"\(.*\)".*/\1/p')"
+[ -z "$file_path" ] && { printf '{}\n'; exit 0; }
+
+case "$file_path" in
+  "$CHAMBA_WORKTREE"*)
+    printf '{}\n'
+    ;;
+  *)
+    printf '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"chamba: edited %s outside the assigned worktree (%s)."}}\n' "$file_path" "$CHAMBA_WORKTREE"
+    ;;
+esac

package/assets/hooks/PreToolUse-warn-destructive.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# chamba PreToolUse hook: warn on obviously destructive shell commands.
+#
+# Claude Code passes the tool call as JSON on stdin. This hook scans Bash
+# commands for destructive patterns and asks for confirmation by emitting a
+# permissionDecision of "ask". Anything else is allowed through untouched.
+#
+# Register in ~/.claude/settings.json under hooks.PreToolUse (matcher: "Bash").
+
+set -euo pipefail
+input="$(cat)"
+
+# Pull the command out of the JSON without requiring jq.
+command="$(printf '%s' "$input" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\(.*\)".*/\1/p')"
+
+case "$command" in
+  *"rm -rf"*|*"git push --force"*|*"git reset --hard"*|*":(){:|:&};:"*)
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"chamba: this command looks destructive — confirm before running."}}\n'
+    ;;
+  *)
+    printf '{}\n'
+    ;;
+esac

package/bin/chamba-install

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/cli.js

@@ -0,0 +1,167 @@
+// src/cli.ts
+import { homedir } from "os";
+import { fileURLToPath } from "url";
+import { NodeFilesystem } from "@chamba/adapters";
+import { joinPath as joinPath2 } from "@chamba/core";
+
+// src/installer.ts
+import { joinPath } from "@chamba/core";
+var CATEGORIES = [
+  { dir: "commands", label: "slash commands" },
+  { dir: "agents", label: "subagents" },
+  { dir: "hooks", label: "hooks" }
+];
+var MCP_SERVER_NAME = "chamba";
+var MCP_SERVER_ENTRY = { command: "npx", args: ["-y", "@chamba/mcp"] };
+var Installer = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  /** True if Claude Code seems present (a config dir or file already exists). */
+  async detectClaudeCode() {
+    return await this.opts.fs.exists(this.opts.claudeDir) || await this.opts.fs.exists(this.opts.claudeJsonPath);
+  }
+  async install(options = {}) {
+    const claudeDetected = await this.detectClaudeCode();
+    const installed = [];
+    const skipped = [];
+    const counts = {};
+    for (const { dir } of CATEGORIES) {
+      const names = await this.assetNames(dir);
+      counts[dir] = 0;
+      const targetDir = joinPath(this.opts.claudeDir, dir);
+      await this.opts.fs.mkdir(targetDir);
+      for (const name of names) {
+        const target = joinPath(targetDir, name);
+        if (!options.force && await this.opts.fs.exists(target)) {
+          skipped.push(`${dir}/${name}`);
+          continue;
+        }
+        const content = await this.opts.fs.readFile(joinPath(this.opts.assetsDir, dir, name));
+        await this.opts.fs.writeFile(target, content);
+        installed.push(`${dir}/${name}`);
+        counts[dir] = (counts[dir] ?? 0) + 1;
+      }
+    }
+    const { mcpAdded, mcpAlreadyPresent } = await this.addMcpServer();
+    return { installed, skipped, counts, mcpAdded, mcpAlreadyPresent, claudeDetected };
+  }
+  async uninstall() {
+    const removed = [];
+    for (const { dir } of CATEGORIES) {
+      const names = await this.assetNames(dir);
+      for (const name of names) {
+        const target = joinPath(this.opts.claudeDir, dir, name);
+        if (await this.opts.fs.exists(target)) {
+          await this.opts.fs.remove(target);
+          removed.push(`${dir}/${name}`);
+        }
+      }
+    }
+    const mcpRemoved = await this.removeMcpServer();
+    return { removed, mcpRemoved };
+  }
+  async assetNames(dir) {
+    try {
+      const entries = await this.opts.fs.readDir(joinPath(this.opts.assetsDir, dir));
+      return entries.filter((e) => e.isFile).map((e) => e.name).sort();
+    } catch {
+      return [];
+    }
+  }
+  async readClaudeJson() {
+    try {
+      const text = await this.opts.fs.readFile(this.opts.claudeJsonPath);
+      const parsed = JSON.parse(text);
+      return typeof parsed === "object" && parsed !== null ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
+  async addMcpServer() {
+    const config = await this.readClaudeJson();
+    const servers = asRecord(config.mcpServers) ?? {};
+    if (MCP_SERVER_NAME in servers) {
+      return { mcpAdded: false, mcpAlreadyPresent: true };
+    }
+    servers[MCP_SERVER_NAME] = MCP_SERVER_ENTRY;
+    config.mcpServers = servers;
+    await this.opts.fs.writeFile(this.opts.claudeJsonPath, `${JSON.stringify(config, null, 2)}
+`);
+    return { mcpAdded: true, mcpAlreadyPresent: false };
+  }
+  async removeMcpServer() {
+    const config = await this.readClaudeJson();
+    const servers = asRecord(config.mcpServers);
+    if (!servers || !(MCP_SERVER_NAME in servers)) return false;
+    delete servers[MCP_SERVER_NAME];
+    config.mcpServers = servers;
+    await this.opts.fs.writeFile(this.opts.claudeJsonPath, `${JSON.stringify(config, null, 2)}
+`);
+    return true;
+  }
+};
+function asRecord(value) {
+  return typeof value === "object" && value !== null ? value : null;
+}
+
+// src/cli.ts
+function buildInstaller() {
+  const home = homedir();
+  const assetsDir = fileURLToPath(new URL("../assets", import.meta.url));
+  return new Installer({
+    fs: new NodeFilesystem(),
+    assetsDir,
+    claudeDir: joinPath2(home, ".claude"),
+    claudeJsonPath: joinPath2(home, ".claude.json")
+  });
+}
+function summarize(result) {
+  const part = (dir) => `${result.counts[dir] ?? 0} ${labelFor(dir)}`;
+  const mcpSentence = result.mcpAdded ? "Added chamba MCP server to ~/.claude.json" : result.mcpAlreadyPresent ? "chamba MCP server already present in ~/.claude.json" : "Could not add chamba MCP server to ~/.claude.json";
+  const lines = [];
+  lines.push(`Installed ${CATEGORIES.map(({ dir }) => part(dir)).join(", ")}. ${mcpSentence}`);
+  if (result.skipped.length > 0) {
+    lines.push(`Skipped ${result.skipped.length} existing file(s): ${result.skipped.join(", ")}`);
+    lines.push("Re-run with --force to overwrite them.");
+  }
+  if (!result.claudeDetected) {
+    lines.push(
+      "Note: Claude Code was not detected (~/.claude not found). Files were created anyway."
+    );
+  }
+  return lines.join("\n");
+}
+function labelFor(dir) {
+  return CATEGORIES.find((c) => c.dir === dir)?.label ?? dir;
+}
+async function main() {
+  const [command, ...rest] = process.argv.slice(2);
+  const installer = buildInstaller();
+  if (command === "uninstall") {
+    const result = await installer.uninstall();
+    process.stdout.write(
+      `Removed ${result.removed.length} file(s). ${result.mcpRemoved ? "Removed" : "Did not find"} chamba MCP server in ~/.claude.json
+`
+    );
+    return;
+  }
+  if (command === void 0 || command === "install") {
+    const force = rest.includes("--force");
+    const result = await installer.install({ force });
+    process.stdout.write(`${summarize(result)}
+`);
+    return;
+  }
+  process.stderr.write(
+    `Unknown command "${command}". Usage: chamba-install [install|uninstall] [--force]
+`
+  );
+  process.exitCode = 1;
+}
+main().catch((err) => {
+  process.stderr.write(`chamba-install failed: ${err.message}
+`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@chamba/claude-extras",
+  "version": "0.1.0",
+  "description": "Optional Claude Code extras for chamba: slash commands, subagents and hooks installer",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "chamba-install": "./bin/chamba-install"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "assets"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thelord07/chamba.git",
+    "directory": "packages/claude-extras"
+  },
+  "homepage": "https://github.com/thelord07/chamba#readme",
+  "bugs": {
+    "url": "https://github.com/thelord07/chamba/issues"
+  },
+  "keywords": [
+    "chamba",
+    "claude-code",
+    "mcp",
+    "slash-commands",
+    "subagents",
+    "hooks"
+  ],
+  "dependencies": {
+    "@chamba/adapters": "0.1.0",
+    "@chamba/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}