@chlrc/aiw 0.1.0 → 0.1.1

package/skills/aiw-reference/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: aiw-reference
+description: Operate the AIW CLI directly for workspace automation, Git review, diff inspection, AI commits, cmux layout launching, Worktrunk worktree lifecycle, workspace garbage collection, and finishing feature branches. Use when the user asks an agent to run AIW commands, clean workspaces, merge back to a target branch, open or create AIW workspaces, automate AIW flows, or explain AIW command behavior.
+---
+
+# AIW Reference
+
+## Purpose
+
+Use AIW as the orchestration layer around existing terminal tools. AIW decides the workflow path, runs dependency gates, and delegates to Worktrunk, cmux, lazygit, delta, yazi, nvim, Git, and agent CLIs.
+
+## Operating Rules
+
+- Run real state checks before making lifecycle changes. Prefer `aiw doctor`, `git status --short`, and `aiw workspace list` as the first evidence.
+- Treat these as high-impact operations: `aiw workspace done`, `aiw workspace remove`, `aiw workspace gc --apply`, `aiw workspace gc --yes`, and any `--force` use.
+- Use dry-run or preview modes when available before applying changes. `gc --dry-run` is the default safe way to inspect cleanup.
+- Do not run `aiw done` from the main checkout. It is only valid inside a feature worktree and refuses dirty worktrees.
+- Do not silently stage files for `aiw commit`. AIW commit reads staged changes only; the user or agent must intentionally stage changes first.
+- Keep personal AIW workflow files out of business repositories unless the user explicitly asks for project-local config.
+
+## Resolve the AIW Command
+
+Use the installed `aiw` binary for normal workspace operations:
+
+```bash
+aiw --help
+```
+
+Use `npx @chlrc/aiw ...` for first-run or one-off package-based access:
+
+```bash
+npx @chlrc/aiw doctor
+```
+
+Use a local checkout only when developing or deeply customizing AIW itself:
+
+```bash
+node bin/aiw --help
+```
+
+## Read-Only Orientation
+
+Start with the smallest useful checks:
+
+```bash
+aiw doctor
+aiw doctor --gate workspace
+git status --short
+aiw workspace list
+aiw ls
+aiw als
+aiw workspace list --json
+aiw workspace states
+```
+
+Use `--json` when automating decisions. The workspace table combines Worktrunk, Git, cmux, target-branch, merge-state, age, dirty, and GC signals.
+
+## Open or Create Workspaces
+
+Create or switch to a worktree and open the standard three-pane cmux layout:
+
+```bash
+aiw cmux-new --agent codex
+aiw new --agent codex
+aiw cmux-new --pick-repo --agent codex
+aiw cmux-new --repo ~/Code/my-repo --branch feat/foo --agent codex --dry-run
+aiw cmux-new --repo ~/Code/my-repo --branch feat/foo --base main --agent codex --dry-run
+aiw cmux-new --local --agent codex
+```
+
+Behavior:
+
+- New branch from current `HEAD`: `wt switch --create <branch> --base @ -x "aiw layout --agent <agent>"`.
+- New branch from a base branch: pass `--base <branch>` or `--from <branch>`.
+- Existing branch: `wt switch <branch> -x "aiw layout --agent <agent>"`.
+- Current checkout without Worktrunk: `--local`.
+
+Open an existing workspace or branch:
+
+```bash
+aiw workspace open feat/foo --agent codex --dry-run
+aiw workspace open /path/to/worktree --agent codex --dry-run
+aiw open feat/foo --agent codex
+```
+
+## Review, Diff, and Commit
+
+Use AIW surfaces without replacing native tool responsibilities:
+
+```bash
+aiw git
+aiw diff
+aiw diff --watch
+aiw diff --staged
+aiw files
+aiw edit src/file.ts:10
+aiw grep keyword
+aiw tree 3
+```
+
+Commit flow:
+
+```bash
+git status --short
+git add <path>
+aiw commit --agent codex --dry-run
+aiw commit --agent codex
+```
+
+`aiw git` opens lazygit with the AIW overlay. In that lazygit session, `Ctrl-A` triggers `aiw commit --prompt ...` for staged changes while leaving native lazygit commit behavior available.
+
+## Finish a Feature Worktree
+
+Use this flow when the user asks to merge a feature workspace back to a target branch:
+
+```bash
+git status --short
+aiw workspace list
+aiw workspace done dev --no-close-cmux
+aiw workspace done dev --agent codex --no-close-cmux
+aiw workspace done dev --retries 3 --no-close-cmux
+aiw workspace done dev --agent codex --retries 3 --no-close-cmux
+```
+
+Rules:
+
+- Run from the feature worktree, not the main workspace.
+- Continue only when `git status --short` is empty.
+- `done` defaults retries from `commit.retries` and restores the source worktree, target branch, and Worktrunk backup ref after failed merge attempts.
+- Pass an explicit target such as `dev`, `main`, or `master` when the recorded AIW target is unclear.
+- Use `--agent <name>` when the Worktrunk squash commit message should be generated by a specific AIW agent.
+- If a Worktrunk squash commit fails commitlint with a fallback subject like `Squash commits from ...`, inspect `git status --short`; if the index now contains the squashed changes, create a valid Conventional Commit manually or restore from `refs/wt-backup/<branch>` before retrying.
+- Omit `--no-close-cmux` when the user wants the matching cmux workspace closed after a successful Worktrunk merge.
+
+Short alias:
+
+```bash
+aiw done dev
+```
+
+## Garbage-Collect Workspaces
+
+Preview first:
+
+```bash
+aiw workspace gc --dry-run
+aiw workspace gc --json
+```
+
+AIW GC separates signals:
+
+- `dirty`: blocks automatic cleanup.
+- `merged`: branch is integrated, same commit, empty, or known contained by a target.
+- `stale`: last commit age exceeds `workspace.stale_seconds`; stale alone does not make a workspace removable.
+
+Only clean, merged, non-current workspaces are removable. Stale dirty or unmerged workspaces are warnings only.
+
+Apply only when the user wants cleanup:
+
+```bash
+aiw workspace gc --apply
+aiw workspace gc --yes
+```
+
+Short aliases:
+
+```bash
+aiw gc --dry-run
+aiw clean --dry-run
+```
+
+## Remove a Specific Workspace
+
+Use removal for a named target after checking state:
+
+```bash
+aiw workspace list
+aiw workspace remove feat/foo
+```
+
+`remove` performs a dirty check before calling Worktrunk. Use `--force` only when the user explicitly intends to hand the decision to Worktrunk:
+
+```bash
+aiw workspace remove feat/foo --force
+```
+
+## Automation Pattern
+
+For agent-run automation, report the exact evidence and command sequence:
+
+1. Show the current repo/worktree state.
+2. Show the AIW preview or dry-run output when available.
+3. State which operation is about to mutate worktrees, commits, or cmux.
+4. Run the apply command only when the user has authorized that operation.
+5. Verify with `aiw workspace list`, `git status --short`, or the relevant `doctor` gate.
+
+Do not stop at a single local command if the user's request is an end-to-end AIW workflow. Carry the task through state inspection, action, verification, and a concise result.

package/skills/aiw-reference/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AIW Reference"
+  short_description: "Run AIW workspace automation safely"
+  default_prompt: "Use $aiw-reference to inspect AIW workspace state and cleanly finish or garbage-collect worktrees."

package/src/cli.mjs

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { expandHome, loadConfig, resolveAgent, aiwBinPath } from "./config.mjs";
-import { runCommit } from "./commit.mjs";
+import { runCommit, runCommitMessage } from "./commit.mjs";
 import { assertGate, printDoctor } from "./deps.mjs";
 import { assertGitRoot, gitRoot, isDirty, resolveRepo, selectBranch } from "./git.mjs";
 import { runWorkspaceHook } from "./hooks.mjs";
@@ -12,7 +12,7 @@ import { commandExists, quoteShell, runInherit, sleep } from "./run.mjs";
 import { commandWorkspace, recordWorkspaceTarget } from "./workspace.mjs";
 
 export async function main(argv) {
-  const command = argv[0] || "help";
+  const command = normalizeCommand(argv[0] || "help");
   const rest = argv.slice(1);
   const config = loadConfig();
 
@@ -32,6 +32,12 @@ export async function main(argv) {
     case "new":
       await commandCmuxNew(config, rest, command);
       return;
+    case "cmux":
+      if (normalizeCommand(rest[0] || "") === "new") {
+        await commandCmuxNew(config, rest.slice(1), "cmux-new");
+        return;
+      }
+      break;
     case "layout":
       await commandLayout(config, rest);
       return;
@@ -46,6 +52,8 @@ export async function main(argv) {
       await commandWorkspace(config, ["open", ...rest]);
       return;
     case "list":
+    case "ls":
+    case "als":
       await commandWorkspace(config, ["list", ...rest]);
       return;
     case "done":
@@ -64,6 +72,9 @@ export async function main(argv) {
     case "commit":
       await commandCommit(config, rest);
       return;
+    case "commit-message":
+      await commandCommitMessage(config, rest);
+      return;
     case "git":
       await commandGit(config, rest);
       return;
@@ -83,12 +94,11 @@ export async function main(argv) {
     case "tree":
       await commandTree(config, rest);
       return;
-    default: {
-      const error = new Error(`unknown command: ${command}`);
-      error.exitCode = 2;
-      throw error;
-    }
   }
+
+  const error = new Error(`unknown command: ${command}`);
+  error.exitCode = 2;
+  throw error;
 }
 
 async function commandDoctor(config, argv) {
@@ -114,11 +124,9 @@ async function commandCmuxNew(config, argv, commandName) {
   const branchFromArgs = flags.positionals[0] && !isKnownAgent(config, flags.positionals[0])
     ? flags.positionals[0]
     : "";
-  const agentFromArgs = commandName === "new"
-    ? flags.positionals[1]
-    : flags.positionals.find((item) => isKnownAgent(config, item));
-  if (flags.local && (flags.branch || branchFromArgs || flags.create)) {
-    const error = new Error("--local cannot be combined with --branch, a branch argument, or --create");
+  const agentFromArgs = flags.positionals.find((item) => isKnownAgent(config, item));
+  if (flags.local && (flags.branch || branchFromArgs || flags.create || flags.base)) {
+    const error = new Error("--local cannot be combined with --branch, a branch argument, --create, or --base");
     error.exitCode = 2;
     throw error;
   }
@@ -129,7 +137,8 @@ async function commandCmuxNew(config, argv, commandName) {
   const branchSelection = flags.local
     ? { local: true }
     : await selectBranch(repo, flags.branch || branchFromArgs, {
-        forceCreate: flags.create
+        forceCreate: flags.create,
+        baseBranch: flags.base
       });
   const agent = await selectAgent(config, flags.agent || agentFromArgs);
 
@@ -152,7 +161,7 @@ async function commandCmuxNew(config, argv, commandName) {
 
   const layoutCommand = `${quoteShell(aiwBinPath())} layout --agent ${quoteShell(agent.name)}`;
   const wtArgs = branchSelection.create
-    ? ["switch", "--create", branchSelection.branch, "--base", "@", "-x", layoutCommand]
+    ? ["switch", "--create", branchSelection.branch, "--base", branchSelection.baseBranch || "@", "-x", layoutCommand]
     : ["switch", branchSelection.branch, "-x", layoutCommand];
   if (flags.dryRun) {
     console.log(`cd ${quoteShell(repo)} && wt ${wtArgs.map(quoteShell).join(" ")}`);
@@ -240,6 +249,13 @@ async function commandCommit(config, argv) {
   await runCommit(config, flags);
 }
 
+async function commandCommitMessage(config, argv) {
+  const flags = parseFlags(argv);
+  const agent = resolveAgent(config, flags.agent || config.commit.agent || config.defaults.agent);
+  assertGate("commit", config, agent);
+  runCommitMessage(config, flags);
+}
+
 function resolveConfigFile(config, value) {
   if (!value) {
     return "";
@@ -325,6 +341,10 @@ function parseFlags(argv) {
       case "--branch":
         flags.branch = argv[++index];
         break;
+      case "--base":
+      case "--from":
+        flags.base = argv[++index];
+        break;
       case "--repo":
         flags.repo = argv[++index];
         break;
@@ -410,13 +430,18 @@ function printHelp() {
 Commands:
   init [--cmux-scope <home|code|none>] [--code-root <path>] [--config-dir <path>] [--dry-run]
   doctor [--json] [--gate <p0|init|layout|cmux-new|workspace|worktrunk|diff|commit>] [--agent <name>]
-  cmux-new [--branch <branch>] [--agent <name>] [--repo <path>] [--pick-repo] [--create] [--local] [--dry-run]
+  cmux-new|new [--branch <branch>] [--base <branch>] [--agent <name>] [--repo <path>] [--pick-repo] [--create] [--local] [--dry-run]
   layout [--agent <name>] [--print-json] [--dry-run]
   workspace|ws <list|open|done|remove|gc> [options]
   commit [--agent <name>] [--prompt <text>] [--prompt-file <path>] [--retries <n>] [--dry-run] [--print-prompt]
-  open | switch | list | done | remove | gc | clean
+  commit-message [--agent <name>] [--prompt <text>]
+  open | switch | list | ls | als | done | remove | gc | clean
   diff [--watch] [--staged] [--all]
   git | files [path] | edit <file[:line]> | grep <query> | pick | tree [depth]
 
 Main workflow commands run dependency gates before creating worktrees or opening cmux layouts.`);
 }
+
+function normalizeCommand(command) {
+  return String(command || "").toLowerCase();
+}

package/src/commit.mjs

@@ -83,6 +83,37 @@ export async function runCommit(config, flags) {
   throw withExit(`git commit failed after ${retries} attempts`, 8);
 }
 
+export function runCommitMessage(config, flags) {
+  const prompt = flags.prompt || readStdin();
+  if (!prompt.trim()) {
+    throw withExit("commit-message prompt is required on stdin or via --prompt", 2);
+  }
+  const repo = capture("git", ["rev-parse", "--show-toplevel"], { cwd: process.cwd() });
+  const message = generateCommitMessage(config, flags, prompt, repo);
+  console.log(message);
+}
+
+function generateCommitMessage(config, flags, prompt, repo) {
+  const agent = resolveAgent(config, flags.agent || config.commit.agent || config.defaults.agent);
+  const agentResult = runAgentForText(agent, prompt, { cwd: repo });
+  if (!agentResult.ok) {
+    throw withExit(
+      [
+        `agent '${agent.name}' failed while generating commit message`,
+        agentResult.stderr.trim(),
+        agentResult.stdout.trim()
+      ].filter(Boolean).join("\n"),
+      agentResult.status || 1
+    );
+  }
+
+  const message = cleanAgentText(agentResult.stdout);
+  if (!message) {
+    throw withExit(`agent '${agent.name}' returned an empty commit message`, 7);
+  }
+  return message;
+}
+
 function readStagedDiff(config, repo) {
   const diff = capture("git", ["diff", "--cached", "--no-ext-diff"], { cwd: repo });
   const statResult = tryCapture("git", ["diff", "--cached", "--stat"], { cwd: repo });
@@ -97,6 +128,14 @@ function readStagedDiff(config, repo) {
   };
 }
 
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+
 function buildCommitPrompt({ basePrompt, staged, attempt, retries, lastFailure }) {
   const sections = [
     basePrompt,

package/src/deps.mjs

@@ -126,29 +126,24 @@ export function printDoctor(config, options = {}) {
 
 function requirementsFor(profile, config, agent) {
   const agentCmd = agent?.cmd;
+  const gitDeps = [config.defaults.git || "lazygit", ...lazygitOverlayDeps(config)];
   switch (profile) {
     case "base":
       return req(["git"]);
     case "init":
-      return req(["sh", "git", "cmux", "wt", "yazi", "nvim", "lazygit", "rg", "fzf", "bat", agentCmd].filter(Boolean), [
-        ["cmux-git-diff", "delta"]
-      ]);
+      return req(["sh", "git", "cmux", "wt", "yazi", "nvim", ...gitDeps, "rg", "fzf", "bat", agentCmd].filter(Boolean));
     case "layout":
-      return req(["git", "cmux", "yazi", "lazygit", "nvim", agentCmd].filter(Boolean), [
-        ["cmux-git-diff", "delta"]
-      ]);
+      return req(["git", "cmux", "yazi", "nvim", ...gitDeps, agentCmd].filter(Boolean));
     case "cmux-new":
     case "new":
-      return req(["git", "wt", "cmux", "yazi", "lazygit", "nvim", agentCmd].filter(Boolean), [
-        ["cmux-git-diff", "delta"]
-      ]);
+      return req(["git", "wt", "cmux", "yazi", "nvim", ...gitDeps, agentCmd].filter(Boolean));
     case "worktrunk":
     case "workspace":
       return req(["git", "wt"]);
     case "files":
       return req([config.defaults.files || "yazi"]);
     case "git":
-      return req([config.defaults.git || "lazygit", ...(config.git.lazygit_config ? ["delta"] : [])]);
+      return req(gitDeps);
     case "edit":
       return req([config.defaults.editor || "nvim"]);
     case "grep":
@@ -170,3 +165,7 @@ function requirementsFor(profile, config, agent) {
 function req(commands, anyOf = []) {
   return { commands, anyOf };
 }
+
+function lazygitOverlayDeps(config) {
+  return config.git.lazygit_config ? ["delta"] : [];
+}

package/src/git.mjs

@@ -86,19 +86,7 @@ export function currentBranch(repo) {
 }
 
 export function branchExists(repo, branch) {
-  if (!branch) {
-    return false;
-  }
-  const local = tryCapture("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: repo });
-  if (local.ok) {
-    return true;
-  }
-  const remote = tryCapture("git", ["show-ref", "--verify", "--quiet", `refs/remotes/${branch}`], { cwd: repo });
-  if (remote.ok) {
-    return true;
-  }
-  const originRemote = tryCapture("git", ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${branch}`], { cwd: repo });
-  return originRemote.ok;
+  return Boolean(resolveBranchRef(repo, branch));
 }
 
 export function listBranches(repo) {
@@ -115,19 +103,34 @@ export function listBranches(repo) {
 
 export async function selectBranch(repo, requestedBranch, options = {}) {
   const current = currentBranch(repo);
+  const requestedBase = options.baseBranch || "";
+  const baseBranch = requestedBase ? resolveBranchRef(repo, requestedBase) : "";
+  if (requestedBase && !baseBranch) {
+    throw withExit(`base branch not found: ${requestedBase}`, 4);
+  }
   if (requestedBranch) {
-    const create = options.forceCreate || !branchExists(repo, requestedBranch);
+    const branchAlreadyExists = branchExists(repo, requestedBranch);
+    const create = options.forceCreate || !branchAlreadyExists;
+    if (requestedBase && !create) {
+      throw withExit(`--base can only be used when creating a new branch: ${requestedBranch} already exists`, 2);
+    }
     return {
       branch: requestedBranch,
       create,
-      targetBranch: create ? current : ""
+      baseBranch: create ? baseBranch || "@" : "",
+      targetBranch: create ? requestedBase || current : ""
     };
   }
 
   const branches = listBranches(repo).filter((branch) => branch !== current);
+  if (requestedBase) {
+    return createBranchSelection(repo, baseBranch, requestedBase);
+  }
+
   const createChoice = "Create new branch from current HEAD...";
+  const createFromBranchChoice = "Create new branch from existing branch...";
   const localChoice = "Open current checkout...";
-  const selected = await pickFromList("Select worktree", [createChoice, localChoice, ...branches], {
+  const selected = await pickFromList("Select worktree", [createChoice, createFromBranchChoice, localChoice, ...branches], {
     defaultItem: createChoice
   });
   if (selected === localChoice) {
@@ -136,21 +139,46 @@ export async function selectBranch(repo, requestedBranch, options = {}) {
     };
   }
   if (selected !== createChoice) {
+    if (selected === createFromBranchChoice) {
+      const base = await pickFromList("Base branch", listBranches(repo), {
+        defaultItem: current
+      });
+      return createBranchSelection(repo, resolveBranchRef(repo, base), base);
+    }
     return {
       branch: selected,
       create: false
     };
   }
 
+  return {
+    ...(await promptNewBranch()),
+    create: true,
+    baseBranch: "@",
+    targetBranch: current
+  };
+}
+
+async function createBranchSelection(repo, baseBranch, targetBranch) {
+  if (!baseBranch) {
+    throw withExit(`base branch not found: ${targetBranch}`, 4);
+  }
+  return {
+    ...(await promptNewBranch()),
+    create: true,
+    baseBranch,
+    targetBranch
+  };
+}
+
+async function promptNewBranch() {
   const { askInput } = await import("./prompt.mjs");
   const branch = await askInput("New branch");
   if (!branch) {
     throw withExit("branch is required", 4);
   }
   return {
-    branch,
-    create: true,
-    targetBranch: current
+    branch
   };
 }
 
@@ -198,6 +226,22 @@ function listRefs(repo, refPath) {
   }
 }
 
+function resolveBranchRef(repo, branch) {
+  if (!branch) {
+    return "";
+  }
+  const local = tryCapture("git", ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`], { cwd: repo });
+  if (local.ok) {
+    return branch;
+  }
+  const remote = tryCapture("git", ["show-ref", "--verify", "--quiet", `refs/remotes/${branch}`], { cwd: repo });
+  if (remote.ok) {
+    return branch;
+  }
+  const originRemote = tryCapture("git", ["show-ref", "--verify", "--quiet", `refs/remotes/origin/${branch}`], { cwd: repo });
+  return originRemote.ok ? `origin/${branch}` : "";
+}
+
 function isInside(child, parent) {
   const relative = path.relative(parent, child);
   return relative === "" || (!!relative && !relative.startsWith("..") && !path.isAbsolute(relative));

package/src/layout.mjs

@@ -18,14 +18,7 @@ export function buildLayout(config, agentName) {
           terminalPane(agentTitle(agent.name), agentCommand)
         ]
       },
-      {
-        direction: "horizontal",
-        split: 0.5,
-        children: [
-          terminalPane("Git", `${aiw} git`),
-          terminalPane("Diff", `${aiw} diff --watch`)
-        ]
-      }
+      terminalPane("Git", `${aiw} git`)
     ]
   };
 }