@junheep/gwt 0.1.1 → 0.2.0

package/README.md

@@ -33,6 +33,38 @@ confirmation. The integration also provides Zsh completion for commands,
 options, worktrees, and Git refs. It only changes directories; it does not load
 environment variables or run project hooks.
 
+## Coding agents
+
+Coding agents do not know about `gwt` and reach for `git worktree add`, which
+skips the copied files, assigned ports, and setup hooks. Install a skill that
+tells them otherwise:
+
+```sh
+gwt skill install claude
+gwt skill install codex
+```
+
+The installer shows the target path and asks for confirmation before writing.
+Both agents read the same `SKILL.md` format and differ only in location, so
+the installed skill is identical:
+
+| Agent  | Default                        | With `--project`             |
+| ------ | ------------------------------ | ---------------------------- |
+| Claude | `~/.claude/skills/gwt/SKILL.md` | `.claude/skills/gwt/SKILL.md` |
+| Codex  | `~/.agents/skills/gwt/SKILL.md` | `.agents/skills/gwt/SKILL.md` |
+
+`--project` writes into the primary worktree so the skill can be committed for
+the team.
+
+The skill covers what `gwt --help` does not: that gwt is preferred over native
+`git worktree`, that project hooks need `gwt trust`, that a failed setup is
+retried rather than recreated, that ports come from `gwt info`, and that
+removal is destructive. It points at `gwt <command> --help` for command
+details instead of repeating them, so it does not go stale as gwt changes.
+Reinstall after upgrading to pick up a revised skill; an unchanged file is
+reported as already installed, and a modified one is replaced only after
+confirmation.
+
 ## Configuration
 
 Create user configuration for the current repository:
@@ -167,6 +199,7 @@ gwt trust [--revoke]
 gwt config create [--project]
 gwt config show
 gwt shell install zsh [--dry-run] [--yes]
+gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
 ```
 
 Run `gwt --help` for the command overview, or `gwt <command> --help` for

package/bin/gwt.mjs

@@ -23,12 +23,13 @@ import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 import { emitKeypressEvents } from "node:readline"
 import { createInterface } from "node:readline/promises"
 
-const VERSION = "0.1.0"
 const PROJECT_CONFIG_FILE = ".gwt.json"
 const PORT_MIN = 20_000
 const PORT_MAX = 39_999
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/
 const DEFAULT_CONFIG = { worktreeDirectory: ".worktrees", copyFiles: [], ports: [] }
+const SKILL_DIRECTORIES = { claude: ".claude", codex: ".agents" }
+const SKILL_USAGE = `Usage: gwt skill install <${Object.keys(SKILL_DIRECTORIES).join("|")}> [--project] [--dry-run] [--yes]`
 
 class CliError extends Error {}
 
@@ -1076,6 +1077,7 @@ if command -v gwt >/dev/null 2>&1; then
       'trust:Approve project hooks'
       'config:Manage user and project configuration'
       'shell:Install shell integration'
+      'skill:Install the gwt skill for coding agents'
     )
 
     if (( CURRENT == 2 )); then
@@ -1133,6 +1135,15 @@ if command -v gwt >/dev/null 2>&1; then
           '--yes[skip installation confirmation]' \
           '(-h --help)'{-h,--help}'[show help]'
         ;;
+      skill)
+        _arguments \
+          '2:action:(install)' \
+          '3:agent:(claude codex)' \
+          '--project[install into the repository instead of the home directory]' \
+          '--dry-run[show the change without writing]' \
+          '--yes[skip installation confirmation]' \
+          '(-h --help)'{-h,--help}'[show help]'
+        ;;
     esac
   }
 
@@ -1142,6 +1153,92 @@ if command -v gwt >/dev/null 2>&1; then
 fi`
 }
 
+function agentSkill() {
+  return `---
+name: gwt
+description: Use gwt to create, list, switch, and remove Git worktrees. Use whenever a task needs an isolated worktree, or in place of running 'git worktree' directly.
+---
+
+gwt wraps native Git worktrees and prepares each one with the project's local
+files, assigned ports, and setup hooks.
+
+## Prefer gwt over 'git worktree'
+
+Create worktrees with \`gwt new\`, not \`git worktree add\`. A worktree added with
+plain Git skips the configured file copies, port assignment, and postCreate
+hook, and records no gwt metadata, so \`gwt list\` and \`gwt remove\` cannot manage
+it. Adopt an existing one with \`gwt setup <path>\`.
+
+## Read the help instead of guessing flags
+
+\`gwt --help\` lists the commands, \`gwt <command> --help\` documents arguments,
+options, and behavior, and nested commands such as \`gwt config create --help\`
+have their own help. This skill does not repeat command signatures so that they
+stay accurate across versions.
+
+## What the help does not make obvious
+
+- Hooks declared by a committed \`.gwt.json\` do not run until the repository is
+  approved with \`gwt trust\`. Approval is invalidated whenever the config or a
+  hook changes, so a repository that worked before can start asking again.
+- A failed setup keeps the worktree and records the failure. Retry it with
+  \`gwt setup <id>\` rather than removing and recreating the worktree.
+- Ports are assigned per worktree. Read them from \`gwt info\` instead of assuming
+  a project default; two worktrees of the same project never share a port.
+- \`gwt switch\` changes the shell's directory only when the shell integration is
+  installed. Otherwise it just prints the path.
+- \`gwt switch\` with no target opens an interactive picker, so always pass an
+  explicit target when running non-interactively.
+
+## Removal is destructive
+
+\`gwt remove\` deletes the worktree and, by default, its branch. Confirm with the
+user before running it, and never pass \`--discard --yes\` on your own: together
+they discard uncommitted changes and force-delete an unmerged branch.
+`
+}
+
+function skillPath(agent, project) {
+  const base = project ? discoverRepository().primaryPath : homedir()
+  return join(base, SKILL_DIRECTORIES[agent], "skills", "gwt", "SKILL.md")
+}
+
+async function installSkill(agent, args) {
+  const { options, positionals } = parseOptions(args, {
+    "--project": "boolean",
+    "--dry-run": "boolean",
+    "--yes": "boolean",
+  })
+  if (positionals.length > 0) throw new CliError(SKILL_USAGE)
+
+  const path = skillPath(agent, options.project)
+  const contents = agentSkill()
+  const existing = existsSync(path) ? readFileSync(path, "utf8") : null
+  if (existing === contents) {
+    console.log(`Skill is already installed in ${path}`)
+    return
+  }
+
+  const verb = existing === null ? "Create" : "Replace"
+  console.log(`${verb} ${path}`)
+  if (options["dry-run"]) {
+    console.log(`\n${contents}`)
+    return
+  }
+  if (!options.yes && !(await ask(`${verb}? [y/N] `))) throw new CliError("Skill installation cancelled")
+
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, contents)
+  console.log(`Installed skill in ${path}`)
+}
+
+async function commandSkill(args) {
+  if (args[0] === "install" && Object.hasOwn(SKILL_DIRECTORIES, args[1])) {
+    return installSkill(args[1], args.slice(2))
+  }
+  throw new CliError(SKILL_USAGE)
+}
+
 function zshConfigPath() {
   return join(process.env.ZDOTDIR ? resolve(process.env.ZDOTDIR) : homedir(), ".zshrc")
 }
@@ -1211,10 +1308,15 @@ function commandComplete(args) {
   throw new CliError("Invalid completion request")
 }
 
+function version() {
+  const path = join(import.meta.dirname, "..", "package.json")
+  return JSON.parse(readFileSync(path, "utf8")).version
+}
+
 function help(command, subcommand) {
   const topic = [command, subcommand].filter(Boolean).join(" ")
   const texts = {
-    "": `gwt ${VERSION} - lightweight native Git worktree workflows
+    "": `gwt ${version()} - lightweight native Git worktree workflows
 
 Usage:
   gwt <command> [options]
@@ -1229,6 +1331,7 @@ Commands:
   trust     Approve or revoke repository project hooks
   config    Create or inspect configuration
   shell     Install shell integration
+  skill     Install the gwt skill for coding agents
 
 Options:
   -h, --help      Show help.
@@ -1240,6 +1343,7 @@ Examples:
   gwt remove
   gwt config create
   gwt shell install zsh
+  gwt skill install claude
 
 Run 'gwt <command> --help' for command behavior and more examples.`,
     new: `Create a worktree, prepare its development environment, and switch to it.
@@ -1460,6 +1564,50 @@ when ZDOTDIR is set. Restart Zsh or source the file after installation.
 Examples:
   gwt shell install zsh
   gwt shell install zsh --dry-run`,
+    skill: `Install the gwt skill so coding agents use gwt correctly.
+
+Usage:
+  gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
+
+Options:
+  -h, --help      Show help for this command.
+
+The skill teaches an agent to prefer gwt over native 'git worktree', to read
+'gwt <command> --help' for command details, and to treat removal as
+destructive. It does not duplicate command signatures, so it stays accurate
+as gwt changes.
+
+Examples:
+  gwt skill install claude
+  gwt skill install codex`,
+    "skill install": `Install the gwt skill for a coding agent.
+
+Usage:
+  gwt skill install <claude|codex> [--project] [--dry-run] [--yes]
+
+Arguments:
+  claude          Install for Claude Code, under .claude/skills.
+  codex           Install for Codex, under .agents/skills.
+
+Options:
+  --project       Write the skill inside the primary worktree, so it can be
+                  committed for the team, instead of the home directory.
+  --dry-run       Print the target path and the skill without writing it.
+  --yes           Install without asking for confirmation.
+  -h, --help      Show help for this command.
+
+Both agents read the same SKILL.md format and only differ in location, so the
+installed skill is identical. Install it once per agent.
+
+Reinstall after upgrading gwt to pick up a revised skill. The command reports
+an unchanged file as already installed and asks before replacing a modified
+one.
+
+Examples:
+  gwt skill install claude
+  gwt skill install codex
+  gwt skill install codex --project
+  gwt skill install claude --dry-run`,
   }
 
   if (!Object.hasOwn(texts, topic)) throw new CliError(`Unknown help topic: ${topic}`)
@@ -1470,9 +1618,9 @@ async function main() {
   const [command, ...args] = process.argv.slice(2)
   if (!command || command === "--help" || command === "-h") return help()
   if (command === "help") return help(args[0], args[1])
-  if (command === "--version" || command === "-V") return console.log(VERSION)
+  if (command === "--version" || command === "-V") return console.log(version())
   if (args.includes("--help") || args.includes("-h")) {
-    const subcommand = ["config", "shell"].includes(command)
+    const subcommand = ["config", "shell", "skill"].includes(command)
       ? args.find((argument) => !argument.startsWith("-"))
       : undefined
     return help(command, subcommand)
@@ -1486,6 +1634,7 @@ async function main() {
   if (command === "trust") return commandTrust(args)
   if (command === "config") return commandConfig(args)
   if (command === "shell") return commandShell(args)
+  if (command === "skill") return commandSkill(args)
   if (command === "__complete") return commandComplete(args)
   throw new CliError(`Unknown command: ${command}`)
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@junheep/gwt",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Lightweight native Git worktree workflows",
   "license": "MIT",
   "author": "Junhee Park",