@chamba/claude-extras 0.2.0 → 0.3.0

package/README.md

@@ -117,6 +117,60 @@ records why — the config still drives every other editor through the MCP tool.
 - **Why does `extreme` become `max` in Claude Code?** Claude Code's effort scale tops
   out at `max`; `extreme` is chamba's name for "the ceiling".
 
+## Multi-repo worktrees + the `/ticket` flow
+
+If you work in a **workspace of several repos** (a parent dir with N git repos), chamba
+can create an isolated worktree per repo for a ticket, reuse or fork the branch, copy
+git-ignored `.env*` files, and write a `.code-workspace` — all driven by config.
+
+```bash
+npx @chamba/claude-extras config worktrees init   # interactive setup
+npx @chamba/claude-extras config worktrees show   # inspect the resolved policy
+```
+
+This writes a `worktrees` block to `~/.chamba/config.json` (or per project in
+`./.chamba/config.json`):
+
+```json
+{
+  "version": 1,
+  "worktrees": {
+    "layout": "sibling",
+    "root": "WORKTREES",
+    "branchPrefix": "ticket/",
+    "baseBranch": "main",
+    "copyEnvFiles": true,
+    "editorWorkspace": "code-workspace",
+    "repos": ["api", "web", "functions"]
+  }
+}
+```
+
+- **layout** — `sibling` puts everything under `<workspace>/WORKTREES/<ticket>/<repo>`;
+  `nested` puts a worktree under each repo.
+- **repos** — omit to autodetect the workspace's git repos.
+- **command** — escape hatch: set it to your own script (e.g.
+  `"./ticket-create.sh {ticket} {repos}"`) and chamba shells out instead of using the
+  built-in. Migrate from a bespoke script to config whenever you want.
+
+Then, in Claude Code:
+
+```
+/ticket TICKET-123
+```
+
+`/ticket` runs the full orchestrator-worker flow: create worktrees →
+`chamba_load_context` → delegate the plan to the **planner** subagent →
+`chamba_review_plan` + the **reviewer** subagent → delegate code to **implementer** and
+tests to **tester** (all inside the worktrees) → `chamba_summarize_to_vault`. It runs to
+the end and stops for your review. It **never commits, merges or pushes** — you review,
+commit and send to code review by hand. Each worker runs with the model + effort you
+configured above.
+
+> **Security:** `copyEnvFiles` copies secrets into the worktree directories. Add your
+> `worktrees.root` (e.g. `WORKTREES/`) to `.gitignore` so they're never committed. It's
+> off by default.
+
 ## License
 
 MIT

package/assets/agents/planner.md

@@ -0,0 +1,18 @@
+---
+name: planner
+description: Produces a detailed, reviewable implementation plan for a ticket, decomposed by repo
+---
+
+You are the **planner**. You receive a ticket and the loaded context (workspace
+map + relevant notes). Produce a concrete, reviewable plan — do not write code.
+
+- Decompose the work into subtasks, grouped by repo when it spans several.
+- For each subtask: the goal, the files likely touched, and which worker does it.
+- State explicit acceptance criteria and how they'll be verified (tests).
+- Call out risks and any sensitive areas (auth, payments, migrations, data).
+- Keep it tight and concrete enough that an implementer can execute it without
+  guessing. If the ticket is ambiguous, state the assumptions you made instead of
+  inventing scope.
+
+Return the plan as structured markdown. The orchestrator runs it through
+`chamba_review_plan` and the reviewer subagent before any code is written.

package/assets/commands/orq.md

@@ -6,15 +6,17 @@ 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.
+worktrees and vault writing; you orchestrate and delegate to the subagents (which
+run with the model + effort you configured via `chamba-config`).
 
 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).
+2. Delegate to the **planner** subagent to produce the plan (goal, acceptance
+   criteria, subtasks with workers, risks, files).
+3. Call `chamba_review_plan` with the plan and have the **reviewer** subagent
+   audit it. If not approved, fix the 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.
+6. Delegate implementation to the **implementer** subagent (in its worktree) and
+   the tests to the **tester** subagent; 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/ticket.md

@@ -0,0 +1,27 @@
+---
+description: Resolve a ticket end-to-end in isolated worktrees, delegating to chamba's agents
+argument-hint: <ticket> [repo ...]
+---
+
+You are orchestrating ticket **$ARGUMENTS** end-to-end. chamba provides the
+worktrees, context, plan validation and vault memory; you delegate the thinking
+and the code to the configured subagents. **Run to the end and stop only for my
+final review** — do not pause for approval mid-way.
+
+1. Create isolated worktrees: call `chamba_create_worktrees` with the ticket id
+   (and the repos if I named any). ALL work happens INSIDE these worktrees —
+   never edit the main checkouts. Note the branch and per-repo worktree paths.
+2. Call `chamba_load_context` with the ticket to pull the workspace map + relevant
+   Obsidian notes.
+3. Delegate to the **planner** subagent to produce the detailed plan. Run it
+   through `chamba_review_plan`; if not approved, fix and re-review (max 3 rounds).
+   Also have the **reviewer** subagent audit it. Do all of this WITHOUT stopping to
+   ask me — the heuristic review + the reviewer agent are the quality gate.
+4. For each subtask/repo, delegate implementation to the **implementer** subagent,
+   working only in that repo's worktree. Delegate the tests to the **tester**
+   subagent and run them.
+5. Call `chamba_summarize_to_vault` with a summary of what changed.
+6. STOP and report for my review: per repo, what changed and the test results; the
+   `.code-workspace` to open; and the suggested commit + `git merge --no-ff`
+   commands. Do NOT commit, merge or push — I review, commit and send to my
+   company's code review by hand.

package/dist/cli.js

@@ -56,6 +56,19 @@ var ConfigStore = class {
     await this.write(parsed.value);
     return parsed.value;
   }
+  /** Merge a patch into the `worktrees` block and persist (validated). */
+  async setWorktrees(patch) {
+    const current = await this.read();
+    const next = {
+      ...current,
+      version: 1,
+      worktrees: { ...current.worktrees ?? {}, ...patch }
+    };
+    const parsed = parseChambaConfig(next);
+    if (!parsed.ok) throw new ConfigError(parsed.error);
+    await this.write(parsed.value);
+    return parsed.value;
+  }
   /** Write the compiled defaults as the full config. */
   async reset() {
     await this.write({ version: 1, defaults: DEFAULT_CONFIG.defaults });
@@ -71,6 +84,7 @@ import { joinPath, loadConfig } from "@chamba/core";
 // src/agent-frontmatter.ts
 import { getModel } from "@chamba/core";
 var AGENT_ROLE_BY_FILE = {
+  "planner.md": "planner",
   "implementer.md": "implementer",
   "reviewer.md": "reviewer",
   "tester.md": "tester"
@@ -269,11 +283,12 @@ function asRecord(value) {
 import {
   AGENT_ROLES,
   DEFAULT_CONFIG as DEFAULT_CONFIG2,
+  DEFAULT_WORKTREE_CONFIG,
   EFFORT_LEVELS,
   MODEL_CATALOG,
   ROLE_DESCRIPTIONS
 } from "@chamba/core";
-import { confirm, select } from "@inquirer/prompts";
+import { confirm, input, select } from "@inquirer/prompts";
 function defaultConfigFile() {
   return { version: 1, defaults: DEFAULT_CONFIG2.defaults };
 }
@@ -298,6 +313,42 @@ function effortChoices() {
 function isCancellation(e) {
   return e instanceof Error && e.name === "ExitPromptError";
 }
+async function runWorktreesWizard() {
+  const d = DEFAULT_WORKTREE_CONFIG;
+  const layout = await select({
+    message: "Worktree layout",
+    choices: [
+      {
+        name: "sibling \u2014 one folder per ticket (<root>/<ticket>/<repo>)",
+        value: "sibling"
+      },
+      { name: "nested \u2014 a worktree under each repo", value: "nested" }
+    ],
+    default: d.layout
+  });
+  const root = await input({
+    message: "Worktree root directory",
+    default: layout === "sibling" ? "WORKTREES" : ".chamba/worktrees"
+  });
+  const branchPrefix = await input({ message: "Branch prefix", default: "ticket/" });
+  const baseBranch = await input({ message: "Base branch to fork from", default: d.baseBranch });
+  const copyEnvFiles = await confirm({
+    message: "Copy git-ignored .env* files into worktrees?",
+    default: false
+  });
+  const editor = await confirm({
+    message: "Generate a .code-workspace per ticket?",
+    default: true
+  });
+  return {
+    layout,
+    root,
+    branchPrefix,
+    baseBranch,
+    copyEnvFiles,
+    editorWorkspace: editor ? "code-workspace" : null
+  };
+}
 async function runWizard(opts = {}) {
   if (opts.nonInteractive) return defaultConfigFile();
   try {
@@ -379,6 +430,19 @@ async function cmdSet(store, args) {
   const effortNote = args.effort ? ` with effort ${args.effort}` : "";
   return `Set ${args.role} \u2192 ${args.model}${effortNote}. Run 'config apply' to regenerate subagents.`;
 }
+function formatWorktrees(w) {
+  return [
+    "worktrees config:",
+    `  layout           ${w.layout}`,
+    `  root             ${w.root}`,
+    `  branchPrefix     ${w.branchPrefix}`,
+    `  baseBranch       ${w.baseBranch}`,
+    `  copyEnvFiles     ${w.copyEnvFiles}`,
+    `  editorWorkspace  ${w.editorWorkspace ?? "(none)"}`,
+    `  repos            ${w.repos ? w.repos.join(", ") : "(autodetect)"}`,
+    `  command          ${w.command ?? "(none)"}`
+  ].join("\n");
+}
 function buildInstaller(fs) {
   const home = homedir();
   const assetsDir = fileURLToPath(new URL("../assets", import.meta.url));
@@ -394,7 +458,7 @@ function parseEffortFlag(rest) {
   const i = rest.indexOf("--effort");
   return i >= 0 ? rest[i + 1] : void 0;
 }
-var USAGE = "Usage: chamba-install config <show|models|set|reset|wizard|apply|edit>\n  show                                   resolved config + where each value comes from\n  models                                 list the available models\n  set <role> <model> [--effort <level>]  change one role\n  reset [--yes]                          restore defaults\n  wizard [--defaults]                    (re)run the interactive wizard\n  apply                                  regenerate ~/.claude/agents from the config\n  edit                                   open the config in $EDITOR\n";
+var USAGE = "Usage: chamba-install config <show|models|set|reset|wizard|apply|edit>\n  show                                   resolved config + where each value comes from\n  models                                 list the available models\n  set <role> <model> [--effort <level>]  change one role\n  reset [--yes]                          restore defaults\n  wizard [--defaults]                    (re)run the interactive wizard\n  worktrees <show|init>                  show or configure the multi-repo worktree policy\n  apply                                  regenerate ~/.claude/agents from the config\n  edit                                   open the config in $EDITOR\n";
 async function runConfigCommand(args) {
   const [command, ...rest] = args;
   const fs = new NodeFilesystem();
@@ -447,6 +511,30 @@ async function runConfigCommand(args) {
 `);
         return;
       }
+      case "worktrees": {
+        const sub = rest[0];
+        if (sub === "show") {
+          const { worktrees } = await loadConfig2(fs, {
+            globalPath: globalConfigPath(),
+            projectPath: projectConfigPath()
+          });
+          process.stdout.write(`${formatWorktrees(worktrees)}
+`);
+          return;
+        }
+        if (sub === "init") {
+          const patch = await runWorktreesWizard();
+          await store.setWorktrees(patch);
+          process.stdout.write(
+            `Wrote worktrees config to ${store.filePath}.${patch.copyEnvFiles ? ` Tip: add '${patch.root}/' to your .gitignore.` : ""}
+`
+          );
+          return;
+        }
+        process.stderr.write("Usage: config worktrees <show|init>\n");
+        process.exitCode = sub ? 1 : 0;
+        return;
+      }
       case "apply": {
         const result = await buildInstaller(fs).applyConfig();
         process.stdout.write(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chamba/claude-extras",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Optional Claude Code extras for chamba: slash commands, subagents and hooks installer",
   "license": "MIT",
   "type": "module",
@@ -31,8 +31,8 @@
   ],
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
-    "@chamba/adapters": "0.2.0",
-    "@chamba/core": "0.2.0"
+    "@chamba/adapters": "0.3.0",
+    "@chamba/core": "0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",