lathe-cli 1.0.1 → 1.1.0

package/README.md

@@ -43,15 +43,30 @@ myapp/
 ## 日常コマンド
 
 ```sh
+lathe feature <name> [--from main|develop]
+                            # features/<name>/ worktree + feature/<name> 枝
+lathe feature-done <name>   # 安全に worktree + branch + remote を一掃
+lathe ls                    # worktree / branch / 最近の runs / improvements
+lathe process <pr#>         # PR pickup → tasks/<pr#>/ worktree → target 起動
 lathe target [args...]      # cd develop/target && claude args
 lathe meta   [args...]      # cd meta/meta && claude args
 lathe sync                  # develop/bin/sync.sh 手動実行
-lathe process <pr#>         # PR pickup → tasks/<pr#>/ worktree 作成 → target 起動
 lathe help                  # ヘルプ
 ```
 
 どの worktree や project root で実行しても、git の共通 dir から自動で正しい場所に移動します。
 
+## helper agent（project root の `.claude/`）
+
+`lathe init` 中に「helper agent を Claude Code か Codex か」を対話で聞かれます（デフォルト: Claude Code）。選んだ template が project root の `.claude/` に配置され、`lathe-cli` skill が入ります。
+
+```sh
+cd <project_root>
+claude              # Lathe 操作の質問はここで聞ける
+```
+
+helper は **Lathe 操作のアシスタント**で、target/meta のような実装エージェントではありません。`lathe feature` や PR 処理のフローに迷ったら相談する相手として常駐します。
+
 ## 標準ワークフロー
 
 ```sh

package/bin/lathe

@@ -28,17 +28,28 @@ lathe — agent harness CLI
 Initialize a project with main / develop / meta worktrees backed by a
 shared bare git repo, then drive target / meta agents over Claude Code.
 
-Commands:
+Setup:
   init             Initialize Lathe in current (empty) directory.
-                   Creates ./.git (bare) and three worktrees:
-                     ./main      your app code
-                     ./develop   target harness, runs/ auto-commit here
-                     ./meta      meta agent + improvements/
+                   Creates ./.git (bare), three worktrees, post-merge
+                   hook, and (interactively) a project-root .claude/
+                   helper for Lathe operations.
+
+Daily ops:
+  feature <name>   Create features/<name>/ worktree on a new
+                   feature/<name> branch (default base: main; --from develop)
+  feature-done <name>
+                   Tear down a feature: worktree + branch (+ remote if any).
+                   Refuses if uncommitted/unpushed unless --force.
   process <pr#>    Pick up a GitHub PR for target processing
                    (creates ./tasks/<pr#>/ worktree, launches target)
-  sync             Re-sync harness/ -> target/.claude/ in develop worktree
-  target [args]    Launch target agent (cd develop/target, claude args)
-  meta   [args]    Launch meta agent (cd meta/meta, claude args)
+  ls               List worktrees, branches, recent runs/improvements
+
+Agent launchers:
+  target [args]    cd develop/target, claude args
+  meta   [args]    cd meta/meta, claude args
+  sync             Re-run sync.sh in develop (only if post-merge missed)
+
+Other:
   help             This message
 
 LATHE_HOME=$LATHE_HOME

package/bin/lathe-feature

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# lathe feature <name> [--from main|develop]
+#   Create a feature worktree at ./features/<name> on a new branch
+#   feature/<name>, branched from main (default) or develop.
+
+set -euo pipefail
+: "${LATHE_HOME:?must be set by lathe dispatcher}"
+source "$LATHE_HOME/bin/_lathe-lib.sh"
+
+NAME=""
+FROM="main"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --from)
+      FROM="$2"; shift 2 ;;
+    --from=*)
+      FROM="${1#--from=}"; shift ;;
+    -*)
+      echo "lathe feature: unknown flag $1" >&2; exit 1 ;;
+    *)
+      if [ -z "$NAME" ]; then NAME="$1"; else
+        echo "lathe feature: extra argument $1" >&2; exit 1
+      fi
+      shift ;;
+  esac
+done
+
+if [ -z "$NAME" ]; then
+  echo "Usage: lathe feature <name> [--from main|develop]" >&2
+  exit 1
+fi
+
+PROJECT_ROOT="$(lathe_project_root)" || {
+  echo "lathe feature: not inside a Lathe project" >&2
+  exit 1
+}
+
+GIT_DIR="$PROJECT_ROOT/.git"
+BRANCH="feature/$NAME"
+WT="$PROJECT_ROOT/features/$NAME"
+
+# Sanity: base branch exists
+if ! git --git-dir="$GIT_DIR" rev-parse --verify "$FROM" >/dev/null 2>&1; then
+  echo "lathe feature: base branch '$FROM' does not exist" >&2
+  exit 1
+fi
+
+# Sanity: feature branch / worktree don't already exist
+if git --git-dir="$GIT_DIR" rev-parse --verify "$BRANCH" >/dev/null 2>&1; then
+  echo "lathe feature: branch '$BRANCH' already exists" >&2
+  exit 1
+fi
+if [ -e "$WT" ]; then
+  echo "lathe feature: $WT already exists" >&2
+  exit 1
+fi
+
+mkdir -p "$PROJECT_ROOT/features"
+git --git-dir="$GIT_DIR" worktree add --quiet -b "$BRANCH" "$WT" "$FROM"
+
+cat <<EOF
+Created feature worktree:
+
+  branch: $BRANCH (from $FROM)
+  path:   $WT
+
+Next:
+  cd $WT
+  # vibe code, commit, push
+  git push -u origin $BRANCH
+  gh pr create --base develop --title "..." --body "..."
+EOF

package/bin/lathe-feature-done

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# lathe feature-done <name> [--keep-branch] [--keep-remote] [--force]
+#   Tear down a feature worktree safely:
+#     1. refuse if uncommitted changes exist (unless --force)
+#     2. refuse if local has commits not pushed to upstream (unless --force)
+#     3. git worktree remove features/<name>
+#     4. (unless --keep-branch) git branch -D feature/<name>
+#     5. (unless --keep-remote)  git push origin :feature/<name>
+
+set -euo pipefail
+: "${LATHE_HOME:?must be set by lathe dispatcher}"
+source "$LATHE_HOME/bin/_lathe-lib.sh"
+
+NAME=""
+KEEP_BRANCH=0
+KEEP_REMOTE=0
+FORCE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --keep-branch) KEEP_BRANCH=1; shift ;;
+    --keep-remote) KEEP_REMOTE=1; shift ;;
+    --force)       FORCE=1; shift ;;
+    -*) echo "lathe feature-done: unknown flag $1" >&2; exit 1 ;;
+    *)
+      if [ -z "$NAME" ]; then NAME="$1"; else
+        echo "lathe feature-done: extra argument $1" >&2; exit 1
+      fi
+      shift ;;
+  esac
+done
+
+if [ -z "$NAME" ]; then
+  echo "Usage: lathe feature-done <name> [--keep-branch] [--keep-remote] [--force]" >&2
+  exit 1
+fi
+
+PROJECT_ROOT="$(lathe_project_root)" || {
+  echo "lathe feature-done: not inside a Lathe project" >&2
+  exit 1
+}
+
+GIT_DIR="$PROJECT_ROOT/.git"
+BRANCH="feature/$NAME"
+WT="$PROJECT_ROOT/features/$NAME"
+
+if [ ! -d "$WT" ]; then
+  echo "lathe feature-done: $WT does not exist" >&2
+  exit 1
+fi
+
+# 1. uncommitted changes?
+if [ -n "$(git -C "$WT" status --porcelain 2>/dev/null)" ]; then
+  if [ "$FORCE" = 0 ]; then
+    echo "lathe feature-done: uncommitted changes in $WT. Commit or use --force." >&2
+    exit 1
+  fi
+fi
+
+# 2. unpushed commits?
+if [ "$FORCE" = 0 ]; then
+  upstream="$(git -C "$WT" rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || true)"
+  if [ -n "$upstream" ]; then
+    ahead="$(git -C "$WT" rev-list --count "$upstream..HEAD" 2>/dev/null || echo 0)"
+    if [ "$ahead" -gt 0 ]; then
+      echo "lathe feature-done: $ahead local commit(s) ahead of $upstream. Push or use --force." >&2
+      exit 1
+    fi
+  fi
+fi
+
+echo "==> Removing worktree $WT ..."
+git --git-dir="$GIT_DIR" worktree remove "$WT"
+
+if [ "$KEEP_BRANCH" = 0 ]; then
+  echo "==> Deleting local branch $BRANCH ..."
+  git --git-dir="$GIT_DIR" branch -D "$BRANCH" 2>&1 || true
+fi
+
+if [ "$KEEP_REMOTE" = 0 ]; then
+  if git --git-dir="$GIT_DIR" remote get-url origin >/dev/null 2>&1; then
+    if git --git-dir="$GIT_DIR" ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then
+      echo "==> Deleting remote branch origin/$BRANCH ..."
+      git --git-dir="$GIT_DIR" push origin --delete "$BRANCH" 2>&1 || true
+    fi
+  fi
+fi
+
+echo "Done."

package/bin/lathe-init

@@ -80,22 +80,71 @@ git -C "$PROJECT_ROOT/meta" \
   -c user.email="lathe@local" -c user.name="lathe" \
   commit --quiet -m "lathe: meta agent on meta"
 
-echo "==> [5/5] Installing post-merge hook (auto-sync on develop merges)..."
+echo "==> [5/6] Installing post-merge hook (auto-sync on develop merges)..."
 mkdir -p "$GIT_DIR/hooks"
 cp "$LATHE_HOME/template/git-hooks/post-merge" "$GIT_DIR/hooks/post-merge"
 chmod +x "$GIT_DIR/hooks/post-merge"
 
+echo "==> [6/6] Helper agent setup ..."
+echo ""
+echo "Which CLI agent will you use as the project-root helper?"
+echo "(Helper sits at the project root and assists with Lathe commands. Doesn't"
+echo " participate in implementation — that's target/meta's job.)"
+echo ""
+echo "  1) Claude Code (recommended)"
+echo "  2) Codex CLI (WIP — falls back to Claude Code template for now)"
+echo "  3) skip (no helper config)"
+echo ""
+HELPER_CHOICE=""
+if [ -t 0 ]; then
+  printf "Choice [1]: "
+  read -r HELPER_CHOICE
+fi
+case "${HELPER_CHOICE:-1}" in
+  1|"") HELPER_KIND="claude" ;;
+  2)
+    echo "(Codex helper template not yet implemented; using Claude Code template)"
+    HELPER_KIND="claude"
+    ;;
+  3) HELPER_KIND="" ;;
+  *)
+    echo "(unrecognized choice; using Claude Code template)"
+    HELPER_KIND="claude"
+    ;;
+esac
+
+if [ -n "$HELPER_KIND" ]; then
+  HELPER_SRC="$LATHE_HOME/template/helper-${HELPER_KIND}"
+  if [ -d "$HELPER_SRC" ]; then
+    cp -R "$HELPER_SRC/." "$PROJECT_ROOT/"
+    echo "Helper config installed at $PROJECT_ROOT/.claude/"
+  else
+    echo "Warning: $HELPER_SRC not found, skipping helper install"
+  fi
+fi
+
 cat <<EOF
 
 Lathe initialized at $PROJECT_ROOT/
 
-  main/      your app code (cd here to start working)
-  develop/   target harness (target launches from here)
-  meta/      meta agent (improvements/ live here)
-  .git/      shared bare repo
+  main/        your app code (or branch base)
+  develop/     target harness, runs/ auto-commit here
+  meta/        meta agent + improvements/
+  .git/        shared bare repo (don't touch)
+EOF
+if [ -n "$HELPER_KIND" ]; then
+  echo "  .claude/     project-root helper (skill: lathe-cli)"
+fi
+cat <<EOF
 
 Next:
-  cd $PROJECT_ROOT/main
-  # vibe code; commit; PR a feature branch to develop
-  # then:  lathe process <pr#>
+  cd $PROJECT_ROOT
+EOF
+if [ -n "$HELPER_KIND" ]; then
+  echo "  claude            # ask Lathe questions; the lathe-cli skill is loaded"
+fi
+cat <<EOF
+  lathe feature <name>   # start a new feature in features/<name>/
+  lathe process <pr#>    # have target process a PR
+  lathe ls               # list worktrees, branches, recent runs
 EOF

package/bin/lathe-ls

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# lathe ls — list worktrees, branches, runs, improvements at a glance.
+
+set -euo pipefail
+: "${LATHE_HOME:?must be set by lathe dispatcher}"
+source "$LATHE_HOME/bin/_lathe-lib.sh"
+
+PROJECT_ROOT="$(lathe_project_root)" || {
+  echo "lathe ls: not inside a Lathe project" >&2
+  exit 1
+}
+GIT_DIR="$PROJECT_ROOT/.git"
+
+echo "=== worktrees ==="
+git --git-dir="$GIT_DIR" worktree list
+
+echo ""
+echo "=== branches ==="
+git --git-dir="$GIT_DIR" branch -a
+
+DEVELOP_WT="$(lathe_wt_for_branch develop 2>/dev/null || true)"
+if [ -n "$DEVELOP_WT" ] && [ -d "$DEVELOP_WT/runs" ]; then
+  echo ""
+  echo "=== recent runs (develop/runs/) ==="
+  ls -1t "$DEVELOP_WT/runs/" 2>/dev/null | grep -v gitkeep | head -10 || echo "(none)"
+fi
+
+META_WT="$(lathe_wt_for_branch meta 2>/dev/null || true)"
+if [ -n "$META_WT" ] && [ -d "$META_WT/improvements" ]; then
+  echo ""
+  echo "=== recent improvements (meta/improvements/) ==="
+  ls -1t "$META_WT/improvements/" 2>/dev/null | grep -v gitkeep | head -10 || echo "(none)"
+fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lathe-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Agent harness CLI: target/meta git worktrees driven by Claude Code",
   "bin": {
     "lathe": "./bin/lathe"

package/template/helper-claude/.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "env": {
+    "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1"
+  }
+}

package/template/helper-claude/.claude/skills/lathe-cli/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: lathe-cli
+description: ユーザーが Lathe project（main/develop/meta worktree + bare .git の構成）の操作で詰まったときに参照する。コマンド一覧、branch / worktree モデル、典型操作（feature 作成・PR 処理・harness 改善・cleanup）、トラブル時の復旧手順を扱う。"lathe", "feature branch", "worktree", "develop", "meta", "PR を処理" 等の言葉が出たら起動する。
+---
+
+# Lathe CLI 操作リファレンス
+
+このプロジェクトは Lathe で初期化された agent harness。あなたはユーザーの **Lathe 操作のアシスタント**。実装そのものは target / meta agent が別 worktree で行うので、あなたは「コマンドを案内する / 代行する / 状態を説明する」役。
+
+## 構成（`lathe init` 直後の姿）
+
+```
+project_root/
+├── .git/         共有 bare repo（worktree 全部がここを参照）
+├── .claude/      この skill とユーザーの helper 設定
+├── main/         worktree on main 枝（user の app code）
+├── develop/     worktree on develop 枝（target が住む。harness/ + 生成された target/.claude/）
+└── meta/         worktree on meta 枝（meta agent + improvements/）
+```
+
+加えて、運用中に動的に増えるもの：
+
+- `features/<name>/` — `lathe feature <name>` で作る、user の vibe coding 用 worktree
+- `tasks/<pr#>/` — `lathe process <pr#>` で作る、target が PR を polish する用 worktree
+
+## branch モデル
+
+| branch | 役割 | 誰が触る |
+|---|---|---|
+| `main` | release stable | 普段は user、最終的に develop からの PR で更新 |
+| `develop` | integration、target の住処、runs/ の auto-commit 先 | target session、meta からの PR が merge される |
+| `meta` | harness 改善 + improvements/ 蓄積 | meta operator + meta agent |
+| `feature/<name>` | user の vibe code | user が `lathe feature` で生やす |
+
+## コマンド一覧
+
+```
+lathe init                          ← 既に走った前提
+lathe target [args...]              develop/target で claude 起動（debug or 直接 task）
+lathe meta [args...]                meta/meta で claude 起動
+lathe sync                          develop の bin/sync.sh 手動実行（post-merge hook が動かない時）
+lathe process <pr#>                 PR pickup → tasks/<pr#>/ worktree 作成 → target 起動
+lathe feature <name> [--from main|develop]
+                                    features/<name>/ worktree 作成、新 feature/<name> 枝
+lathe feature-done <name> [--keep-branch] [--keep-remote] [--force]
+                                    feature 終了処理（worktree 削除、branch 削除、remote push :branch）
+lathe ls                            worktree / branch / runs / improvements を一覧
+lathe help                          help
+```
+
+## 典型操作
+
+### 新 feature を始める
+
+```sh
+cd project_root
+lathe feature <name>            # features/<name>/ ができる
+cd features/<name>
+# vibe code（claude を別 session で立ち上げて自由に）
+git add . && git commit -m "WIP: vibe ..."
+git push -u origin feature/<name>
+gh pr create --base develop --title "..." --body "..."
+```
+
+### PR を target に処理させる
+
+PR が立ったら（overseer 役）：
+
+```sh
+cd project_root
+lathe process <pr#>             # tasks/<pr#>/ worktree が新規作成、target が起動
+```
+
+claude TUI が立ち上がるので、表示された prompt：「Read .lathe-task.md from the added directory and process it.」を貼る。
+
+orchestrator が plan HTML を起こして承認待ちで止まる。承認したら coder/reviewer に dispatch、PR branch に commit/push されて PR が更新される。
+
+### feature を終わらせる
+
+```sh
+cd project_root
+gh pr merge <pr#>               # GitHub 側で merge
+lathe feature-done <name>       # local worktree + branch + remote branch を一掃
+```
+
+### meta で harness を改善する
+
+```sh
+cd project_root/meta
+git fetch && git merge --no-edit develop   # 最新 runs/ を取り込み
+lathe meta                                  # meta agent 起動
+# meta が runs/ 観察 → harness/ 編集 → improvements/<id>/ 記録 → commit
+git push -u origin meta
+gh pr create --base develop --head meta --title "harness: ..."
+gh pr merge <meta pr#>
+# → develop 側 post-merge hook が sync.sh 自動実行 → target/.claude/ 更新
+```
+
+### release（develop → main）
+
+```sh
+cd project_root/main
+git pull
+git merge develop
+git push origin main
+```
+
+### 全体俯瞰
+
+```sh
+lathe ls                        # worktree, branch, recent runs/improvements
+```
+
+## やってはいけない / 詰まりやすい点
+
+1. **`main/`, `develop/`, `meta/` の中で `git checkout` で別 branch に切り替えない**
+   - それぞれの worktree は固定の枝。別枝は別 worktree。switch すると `fatal: 'X' is already used by worktree at '...'`
+   - feature を始めたいなら `lathe feature <name>` を使う
+
+2. **`target/.claude/`、`target/CLAUDE.md` などを直接編集しない**
+   - これは `harness/` から sync.sh で生成されたコピー。次回 sync で上書きされる
+   - 改善は `harness/` 配下を編集（meta worktree 内で）→ develop に PR → post-merge で反映
+
+3. **`features/<name>/` を `rm -rf` で消すと metadata が残る**
+   - `git worktree list` にゾンビが出る
+   - 正しい手順：`lathe feature-done <name>`（または `git --git-dir=.git worktree remove features/<name>`）
+
+4. **branch だけ消そうとして `git branch -D feature/X` でエラー**
+   - その branch を worktree が checkout 中だから。先に worktree を消す
+   - `lathe feature-done` は両方やる
+
+5. **post-merge hook は local merge のみ発火**
+   - GitHub UI で merge した場合は hook 走らない。`cd develop && git pull && lathe sync` で手動
+
+6. **runs/ の auto-commit は local のみ（remote push しない）**
+   - 別 machine の meta から見たいなら、`cd develop && git push origin develop` を手動 or 自動化要
+
+## トラブルシュート
+
+| 症状 | 対処 |
+|---|---|
+| `lathe target` が "develop worktree not found" | `git --git-dir=.git worktree list` で確認、抜けてたら `git worktree add` で復活 |
+| `git worktree list` にゾンビ entry | `git --git-dir=.git worktree prune` |
+| `git branch -D` で "checked out at" エラー | 該当 worktree を先に remove |
+| post-merge hook が走らない | `.git/hooks/post-merge` の存在・実行ビット確認、無ければ template から copy |
+| PR にコードが上がらない | task worktree から `git push` 忘れ、target session 内で確認 |
+
+## あなたの責任範囲
+
+- ユーザーが Lathe 操作で迷ったら **このコマンド使え** と案内
+- 求められれば Bash で代行実行
+- 構造（worktree / branch / 状態）の質問には git 直接叩いて答える
+- target / meta が何をしているかの質問には、各 worktree の CLAUDE.md（develop の harness/CLAUDE.md、meta の meta/CLAUDE.md）を Read してから答える
+
+実装そのもの（user の app コードを書くなど）は **しない**。それは feature worktree で user 自身か、target agent の仕事。