gsd-lite 0.1.0

package/commands/gsd-status.md

@@ -0,0 +1,114 @@
+---
+name: gsd-status
+description: Display project progress overview derived from canonical state fields
+---
+
+<role>
+你是 GSD-Lite 状态展示器。从 state.json 读取 canonical fields，推导并展示项目进度概览。
+用用户输入的语言进行所有后续输出。
+</role>
+
+<process>
+
+## STEP 1: 读取状态
+
+读取 `.gsd/state.json`:
+- 如果文件不存在 → 告知用户 "未找到 GSD 项目状态，请先运行 /gsd:start 或 /gsd:prd"，停止
+- 如果文件损坏 → 告知用户并停止
+
+## STEP 2: 展示进度面板
+
+从 canonical fields 实时推导所有展示数据 (不使用任何 derived/cached 值):
+
+### 项目概览
+
+```
+项目: {project}
+工作流模式: {workflow_mode}
+计划版本: {plan_version}
+```
+
+### 总体进度
+
+- 从 `phases` 数组推导:
+  - 总 phase 数: `total_phases`
+  - 已完成 phase 数: lifecycle=accepted 的 phase 数量
+  - 总 task 数: 所有 phase 的 `tasks` 之和
+  - 已完成 task 数: 所有 phase 的 `done` 之和
+  - 进度百分比: `已完成 task / 总 task * 100`
+
+```
+进度: ████████░░░░ {done}/{total} tasks ({percentage}%)
+阶段: {completed_phases}/{total_phases} phases
+```
+
+### 各阶段状态
+
+遍历 `phases` 数组，展示每个 phase:
+
+```
+Phase {id}: {name}
+  状态: {lifecycle}
+  任务: {done}/{tasks}
+  审查: {phase_review.status} (如有)
+  交接: {phase_handoff 各项状态}
+```
+
+### 当前活跃任务
+
+- 从 `current_phase` + `current_task` 推导:
+
+```
+当前任务: {current_task} — {task_name}
+任务状态: {task.lifecycle}
+审查级别: {task.level}
+重试次数: {task.retry_count}
+```
+
+### 审查状态
+
+- 如果 `current_review` 存在:
+
+```
+审查中: {current_review.scope} — {current_review.scope_id}
+审查阶段: {current_review.stage}
+```
+
+### Blocked 摘要
+
+- 遍历当前 phase 的 todo，找出 lifecycle=blocked 的 task:
+
+```
+Blocked 任务:
+  - {task_id}: {blocked_reason}
+    解除条件: {unblock_condition}
+```
+
+如无 blocked task → 不显示此段
+
+### 下一步操作建议
+
+根据 `workflow_mode` 推导:
+
+| workflow_mode | 建议 |
+|---|---|
+| executing_task | "自动执行中，等待完成" |
+| reviewing_task | "L2 审查进行中" |
+| reviewing_phase | "L1 阶段审查进行中" |
+| awaiting_clear | "请执行 /clear 然后 /gsd:resume 继续" |
+| awaiting_user | "有 blocked 问题需要用户决策，运行 /gsd:resume 查看详情" |
+| paused_by_user | "已暂停，运行 /gsd:resume 继续" |
+| reconcile_workspace | "工作区不一致，运行 /gsd:resume 进行 reconcile" |
+| replan_required | "计划需要更新，运行 /gsd:resume 查看详情" |
+| research_refresh_needed | "研究已过期，运行 /gsd:resume 刷新" |
+| completed | "项目已完成" |
+| failed | "项目执行失败，运行 /gsd:resume 查看详情" |
+
+</process>
+
+<rules>
+- 只读操作: 不修改 state.json，不修改任何文件
+- 只使用 canonical fields: 所有展示数据从 canonical fields 实时推导
+- 不展示 derived/cached 值: 每次执行时重新计算
+- 不展示敏感信息: evidence 中的命令输出仅展示摘要
+</rules>

package/commands/gsd-stop.md

@@ -0,0 +1,50 @@
+---
+name: gsd-stop
+description: Save current state and pause project execution
+---
+
+<role>
+你是 GSD-Lite 编排器。保存当前项目完整状态并暂停执行。
+用用户输入的语言进行所有后续输出。
+</role>
+
+<process>
+
+## STEP 1: 保存完整状态
+
+读取并更新 `.gsd/state.json`:
+- 如果文件不存在 → 告知用户 "未找到 GSD 项目状态，无需停止"，停止
+
+确保以下信息已保存到 state.json:
+- `current_phase` / `current_task` — 当前执行位置
+- `current_review` — 当前审查状态 (如有进行中的审查)
+- 当前 phase 的 todo 列表中每个 task 的 lifecycle 状态
+- 所有 blocked task 的 `blocked_reason` 和 `unblock_condition`
+- `git_head` — 更新为当前 `git rev-parse HEAD`
+- `context.last_session` — 更新为当前时间
+
+## STEP 2: 写入暂停状态
+
+将 `workflow_mode` 设置为 `paused_by_user`
+
+使用原子写入: 先写 `.gsd/state.json.tmp`，成功后 rename 为 `.gsd/state.json`
+
+## STEP 3: 确认输出
+
+输出: "已暂停。运行 /gsd:resume 继续"
+
+附带简要进度 (从 canonical fields 推导):
+```
+项目: {project}
+停在: Phase {current_phase} / Task {current_task}
+进度: {done}/{total} tasks
+```
+
+</process>
+
+<rules>
+- 原子写入: 先写 .tmp 再 rename，避免写入中断导致状态损坏
+- 只更新 canonical fields: 不写入 derived fields
+- 不执行任何代码/测试/构建操作
+- 不清理任何临时文件 (让 /gsd:resume 恢复时处理)
+</rules>

package/hooks/context-monitor.js

@@ -0,0 +1,64 @@
+// hooks/context-monitor.js
+// This file exports TWO hook handlers used by Claude Code's hooks system.
+// Can also be invoked via CLI: node context-monitor.js <statusLine|postToolUse>
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * StatusLine hook — called after each tool use.
+ * Reads remaining_percentage and writes to .gsd/.context-health
+ */
+export function statusLine(data, basePath) {
+  try {
+    const remaining = data?.context_window?.remaining_percentage;
+    if (remaining == null) return;
+
+    const gsdDir = join(basePath || process.cwd(), '.gsd');
+    mkdirSync(gsdDir, { recursive: true });
+    writeFileSync(join(gsdDir, '.context-health'), String(remaining));
+  } catch (err) {
+    if (process.env.GSD_DEBUG) console.error('[context-monitor:statusLine]', err);
+  }
+}
+
+/**
+ * PostToolUse hook — called after each tool use.
+ * Reads .context-health and returns warning/stop text if threshold breached.
+ */
+export function postToolUse(basePath) {
+  try {
+    const gsdDir = join(basePath || process.cwd(), '.gsd');
+    const health = parseInt(readFileSync(join(gsdDir, '.context-health'), 'utf-8'), 10);
+
+    if (health < 20) {
+      return `🛑 CONTEXT EMERGENCY (${health}% remaining): Save state NOW. Set workflow_mode = awaiting_clear. Tell user to /clear then /gsd:resume.`;
+    }
+    if (health < 40) {
+      return `⚠️ CONTEXT LOW (${health}% remaining): Complete current task, save state, set workflow_mode = awaiting_clear. Tell user to /clear then /gsd:resume.`;
+    }
+  } catch (err) {
+    if (process.env.GSD_DEBUG) console.error('[context-monitor:postToolUse]', err);
+  }
+  return null;
+}
+
+// I-6: CLI dispatch — allows hook registration as shell command
+const cmd = process.argv[2];
+if (cmd === 'statusLine') {
+  // Read JSON data from stdin for statusLine
+  let input = '';
+  process.stdin.setEncoding('utf-8');
+  process.stdin.on('data', chunk => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      statusLine(data);
+    } catch (err) {
+      if (process.env.GSD_DEBUG) console.error('[context-monitor:cli]', err);
+    }
+  });
+} else if (cmd === 'postToolUse') {
+  const result = postToolUse();
+  if (result) console.log(result);
+}

package/hooks/hooks.json

@@ -0,0 +1,19 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-monitor.js\" postToolUse"
+          }
+        ]
+      }
+    ]
+  },
+  "statusLine": {
+    "type": "command",
+    "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/context-monitor.js\" statusLine"
+  }
+}

package/install.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// Plugin installer for GSD-Lite
+
+import { existsSync, mkdirSync, cpSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CLAUDE_DIR = join(homedir(), '.claude');
+const RUNTIME_DIR = join(CLAUDE_DIR, 'gsd-lite');
+const DRY_RUN = process.argv.includes('--dry-run');
+
+function log(msg) { console.log(msg); }
+
+function formatHookCommand(scriptPath, hookName) {
+  return `node ${JSON.stringify(scriptPath)} ${hookName}`;
+}
+
+function registerStatusLine(settings, hookPath) {
+  const command = formatHookCommand(hookPath, 'statusLine');
+  // Don't overwrite non-GSD statusLine
+  if (settings.statusLine && typeof settings.statusLine === 'object'
+      && !settings.statusLine.command?.includes('context-monitor.js')) {
+    log('  ! Preserved existing statusLine');
+    return false;
+  }
+  settings.statusLine = { type: 'command', command };
+  // Clean up legacy format (was incorrectly placed in hooks)
+  if (settings.hooks?.StatusLine) delete settings.hooks.StatusLine;
+  return true;
+}
+
+function registerPostToolUseHook(hooks, hookPath) {
+  const command = formatHookCommand(hookPath, 'postToolUse');
+  const entry = { matcher: '*', hooks: [{ type: 'command', command }] };
+  if (!hooks.PostToolUse) {
+    hooks.PostToolUse = [entry];
+    return true;
+  }
+  // Handle legacy string format
+  if (typeof hooks.PostToolUse === 'string') {
+    if (!hooks.PostToolUse.includes('context-monitor.js')) {
+      log('  ! Preserved existing PostToolUse hook');
+      return false;
+    }
+    hooks.PostToolUse = [entry];
+    return true;
+  }
+  if (Array.isArray(hooks.PostToolUse)) {
+    const idx = hooks.PostToolUse.findIndex(e =>
+      e.hooks?.some(h => h.command?.includes('context-monitor.js')));
+    if (idx >= 0) hooks.PostToolUse[idx] = entry;
+    else hooks.PostToolUse.push(entry);
+    return true;
+  }
+  return false;
+}
+
+function copyDir(src, dest, label) {
+  if (DRY_RUN) {
+    log(`  [dry-run] Would copy ${src} → ${dest}`);
+    return;
+  }
+  mkdirSync(dest, { recursive: true });
+  cpSync(src, dest, { recursive: true });
+  log(`  ✓ ${label}`);
+}
+
+function copyFile(src, dest, label) {
+  if (DRY_RUN) {
+    log(`  [dry-run] Would copy ${src} → ${dest}`);
+    return;
+  }
+  mkdirSync(dirname(dest), { recursive: true });
+  cpSync(src, dest);
+  log(`  ✓ ${label}`);
+}
+
+export function main() {
+  log('GSD-Lite Installer\n');
+
+  if (!existsSync(CLAUDE_DIR)) {
+    log(`Error: ${CLAUDE_DIR} not found. Is Claude Code installed?`);
+    process.exit(1);
+  }
+
+  log('Installing files...');
+
+  // Reset managed runtime directory to avoid stale files on reinstall
+  if (!DRY_RUN && existsSync(RUNTIME_DIR)) {
+    rmSync(RUNTIME_DIR, { recursive: true, force: true });
+  }
+
+  // 1. Commands
+  copyDir(join(__dirname, 'commands'), join(CLAUDE_DIR, 'commands', 'gsd'), 'commands → ~/.claude/commands/gsd/');
+
+  // 2. Agents (namespaced under gsd/ to avoid collisions) [I-5]
+  copyDir(join(__dirname, 'agents'), join(CLAUDE_DIR, 'agents', 'gsd'), 'agents → ~/.claude/agents/gsd/');
+
+  // 3. Workflows
+  copyDir(join(__dirname, 'workflows'), join(CLAUDE_DIR, 'workflows', 'gsd'), 'workflows → ~/.claude/workflows/gsd/');
+
+  // 4. References
+  copyDir(join(__dirname, 'references'), join(CLAUDE_DIR, 'references', 'gsd'), 'references → ~/.claude/references/gsd/');
+
+  // 5. Hooks
+  copyDir(join(__dirname, 'hooks'), join(CLAUDE_DIR, 'hooks'), 'hooks → ~/.claude/hooks/');
+
+  // 6. Stable runtime for MCP server
+  copyDir(join(__dirname, 'src'), join(RUNTIME_DIR, 'src'), 'runtime/src → ~/.claude/gsd-lite/src/');
+  copyDir(join(__dirname, 'node_modules'), join(RUNTIME_DIR, 'node_modules'), 'runtime/node_modules → ~/.claude/gsd-lite/node_modules/');
+  copyFile(join(__dirname, 'package.json'), join(RUNTIME_DIR, 'package.json'), 'runtime/package.json → ~/.claude/gsd-lite/package.json');
+
+  // 7. Register MCP server in settings.json
+  const settingsPath = join(CLAUDE_DIR, 'settings.json');
+  if (!DRY_RUN) {
+    let settings = {};
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {}
+
+    if (!settings.mcpServers) settings.mcpServers = {};
+    settings.mcpServers['gsd-lite'] = {
+      command: 'node',
+      args: [join(RUNTIME_DIR, 'src', 'server.js')],
+    };
+
+    // Register statusLine (top-level setting) and PostToolUse hook
+    if (!settings.hooks) settings.hooks = {};
+    const hookPath = join(CLAUDE_DIR, 'hooks', 'context-monitor.js');
+    const statusLineRegistered = registerStatusLine(settings, hookPath);
+    const postToolUseRegistered = registerPostToolUseHook(settings.hooks, hookPath);
+
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+    log('  ✓ MCP server registered in settings.json');
+    if (statusLineRegistered || postToolUseRegistered) {
+      log('  ✓ GSD-Lite hooks registered in settings.json');
+    }
+  } else {
+    log('  [dry-run] Would register MCP server in settings.json');
+  }
+
+  log('\n✓ GSD-Lite installed successfully!');
+  log('  Use /gsd:start to begin a new project');
+  log('  Use /gsd:resume to continue an existing project');
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "gsd-lite",
+  "version": "0.1.0",
+  "description": "AI orchestration tool for Claude Code — GSD management shell + Superpowers quality core",
+  "type": "module",
+  "bin": {
+    "gsd-lite": "./cli.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "test:coverage": "c8 --reporter=text --reporter=lcov node --test tests/*.test.js",
+    "lint": "biome check src/ tests/ hooks/",
+    "lint:fix": "biome check --write src/ tests/ hooks/",
+    "start": "node src/server.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sdsrss/gsd-lite"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "orchestration",
+    "ai-agent",
+    "task-management"
+  ],
+  "files": [
+    ".claude-plugin/",
+    "src/",
+    "commands/",
+    "agents/",
+    "workflows/",
+    "references/",
+    "hooks/",
+    "cli.js",
+    "install.js",
+    "uninstall.js"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "c8": "^11.0.0"
+  }
+}

package/references/anti-rationalization-full.md

@@ -0,0 +1,112 @@
+# 反合理化完整参考 (Anti-Rationalization Full Reference)
+
+> 本文档是所有 Agent 红旗/合理化模式的 **主参考**。
+> Agent 内联版本为精简摘要；本文档为完整版，供按需读取。
+> 目的: 识别并阻断 AI 跳过质量流程的合理化思维。
+
+---
+
+## 1. Executor 红旗 (测试相关)
+
+| 想法 (Thought) | 现实 (Reality) | 行动 (Action) |
+|----------------|---------------|---------------|
+| "太简单了不需要测试" | 简单代码也会出错。复杂度不是跳过测试的理由。 | 检查 TDD 例外列表。不在例外中 → 写测试。 |
+| "我先写完再测试" | 后写的测试立即通过，证明不了任何东西。它只是在验证你写的代码"能跑"，不是在验证"正确"。 | 回到 RED-GREEN-REFACTOR。先写失败测试。 |
+| "就这一次跳过" | 你在合理化。每一次"就这一次"都是纪律崩溃的开始。 | 停止。回到正确流程。没有例外。 |
+| "我已经手动测试过了" | 手动测试不可重复，不可验证，不能防回归。 | 写自动测试。手动验证只是补充，不是替代。 |
+
+---
+
+## 2. Reviewer 红旗 (证据相关)
+
+| 想法 (Thought) | 现实 (Reality) | 行动 (Action) |
+|----------------|---------------|---------------|
+| "executor 说测试通过了" | 你是独立审查器。不信任任何人的报告。 | 自己运行测试，用自己的眼睛看结果。 |
+| "看起来没问题" | "看起来"不是证据。没有具体观察结果的判断是无效的。 | 列出具体检查项和观察到的结果。 |
+
+---
+
+## 3. Debugger 红旗 (根因相关)
+
+| 想法 (Thought) | 现实 (Reality) | 行动 (Action) |
+|----------------|---------------|---------------|
+| "快速修一下先" | 你在跳过根因调查。没有根因分析的修复是在赌博。 | 停止。完成 Phase 1 (根因调查) 后再提修复方案。 |
+| "应该是 X 的问题" | 没有证据的假设。直觉在调试中不可靠。 | 先调查。用数据和日志支撑假设，不是猜测。 |
+| "再试一个修复" (已尝试 2+) | 盲目重试说明你没有理解根因。 | 停止尝试修复。退后一步，质疑架构假设。 |
+
+---
+
+## 4. 通用合理化模式
+
+### 4.1 流程跳过类
+
+| 想法 (Thought) | 现实 (Reality) | 行动 (Action) |
+|----------------|---------------|---------------|
+| "这个改动太小了，不需要走流程" | 小改动也可能引入 bug。流程的价值不取决于改动大小。 | 按任务级别走对应流程 (L0/L1/L2)。 |
+| "赶时间，先跳过审查" | 跳过审查省的时间，远小于修 bug 花的时间。 | 审查是必经步骤，不是可选项。 |
+| "我很确定这是对的" | 确信不等于正确。验证铁律: 必须有 fresh evidence。 | 运行验证，用结果说话。 |
+
+### 4.2 质量妥协类
+
+| 想法 (Thought) | 现实 (Reality) | 行动 (Action) |
+|----------------|---------------|---------------|
+| "先让它能跑，之后再重构" | "之后"几乎不会到来。技术债是复利。 | 现在就写干净的代码。REFACTOR 是 TDD 循环的一部分。 |
+| "这只是 POC/原型" | 原型代码常常变成生产代码。 | 即使是原型，也遵守基本质量标准。 |
+| "测试覆盖率够了" | 覆盖率是数字，不是质量指标。100% 覆盖率的测试可能全是无意义的。 | 关注测试质量: 是否覆盖了边界条件和错误路径？ |
+
+### 4.3 范围蔓延类
+
+| 想法 (Thought) | 现实 (Reality) | 行动 (Action) |
+|----------------|---------------|---------------|
+| "顺便把这个也改了" | 范围蔓延。未计划的修改可能引入意外问题。 | 标注 `[DECISION]` 或返回编排器确认。 |
+| "这个 bug 我现在就能修" | 如果不在当前 task 范围内，它就不是你现在的工作。 | 记录到 blockers 或建议后续 task。 |
+| "加个小功能不影响" | 每个"小功能"都增加测试、维护和复杂度。 | 遵守 YAGNI。当前 task 只做计划内的事。 |
+
+### 4.4 知识盲区类
+
+| 想法 (Thought) | 现实 (Reality) | 行动 (Action) |
+|----------------|---------------|---------------|
+| "文档里没说不行" | 文档没覆盖 ≠ 允许。缺失信息应当确认，不是默认通过。 | 查阅源码或测试验证实际行为。 |
+| "这个 API 应该是这样用的" | "应该"是假设。API 行为以官方文档和实际测试为准。 | 写集成测试验证 API 行为。 |
+| "以前都是这样做的" | 惯性不等于正确。技术和需求在变化。 | 评估当前上下文，确认做法仍然适用。 |
+
+---
+
+## 5. 识别合理化的信号
+
+当你发现自己在想以下内容时，你正在合理化:
+
+```
+"只是..."    → 在最小化问题的严重性
+"应该..."    → 在用假设替代验证
+"先...后..." → 在推迟质量步骤 (且"后"几乎不会到来)
+"太...了"    → 在用极端程度作为跳过的借口
+"这次..."    → 在为破例寻找理由
+```
+
+---
+
+## 6. 应对策略
+
+1. **意识到** → 识别合理化想法 (参考上方表格)
+2. **停止** → 不要继续当前动作
+3. **回到流程** → 找到正确的下一步 (参考 agent 内联规则)
+4. **如果不确定** → 返回 `[BLOCKED]`，让编排器决策
+
+> 铁律: 流程存在的原因是防止你在"感觉对"的时候犯错。
+> 当你想跳过流程时，恰恰是最需要流程的时候。
+
+---
+
+## 7. 快速自检清单
+
+每次完成任务前，过一遍:
+
+```
+□ 我是否跳过了任何测试？ (检查 §1)
+□ 我的证据是自己验证的，还是别人告诉我的？ (检查 §2)
+□ 我是否在没有根因分析的情况下提出修复？ (检查 §3)
+□ 我是否做了计划外的修改？ (检查 §4.3)
+□ 我的脑中是否出现过 §5 中的信号词？
+→ 任何一项为"是" → 停止，回到流程
+```

package/references/git-worktrees.md

@@ -0,0 +1,77 @@
+# Git Worktree 工作流参考 (Git Worktrees Reference)
+
+> 本文档介绍 Git Worktree 在隔离开发中的用法。
+> 适用场景: 需要在不影响当前工作的情况下创建独立开发环境。
+
+---
+
+## 1. 什么是 Worktree
+
+Git Worktree 允许你从同一个仓库创建多个工作目录，每个目录关联不同分支。
+好处: 切换任务时不需要 stash/commit 当前工作，每个 worktree 完全独立。
+
+```
+主仓库:  /project (main branch)
+Worktree: /project-feat-auth (feat/auth branch)
+Worktree: /project-fix-bug (fix/login-bug branch)
+→ 三个目录独立工作，共享同一个 .git 数据
+```
+
+---
+
+## 2. 何时使用
+
+| 场景 | 推荐 |
+|------|------|
+| 紧急 bug 修复，但当前分支有未完成工作 | Worktree |
+| 需要同时对比两个分支的运行结果 | Worktree |
+| 长期特性开发 + 日常维护并行 | Worktree |
+| 简单的分支切换 (无未提交修改) | `git checkout` 即可 |
+
+---
+
+## 3. 基本操作
+
+```bash
+# 创建 (基于现有分支)
+git worktree add ../project-feat-auth feat/auth
+
+# 创建 (新分支)
+git worktree add -b feat/new-feature ../project-new-feature main
+
+# 查看所有 worktree
+git worktree list
+
+# 在 worktree 中工作 (正常 git 操作)
+cd ../project-feat-auth
+git add . && git commit -m "feat(auth): add JWT validation"
+git push -u origin feat/auth
+
+# 删除 worktree
+git worktree remove ../project-feat-auth       # 正常删除
+git worktree remove --force ../project-feat-auth  # 有未提交修改时
+
+# 清理无效引用 (手动删除目录后)
+git worktree prune
+```
+
+---
+
+## 4. 常见问题和解决方案
+
+| 问题 | 原因 | 解决 |
+|------|------|------|
+| `fatal: 'branch' is already checked out` | 同一分支不能同时被两个 worktree checkout | 创建新分支，或先在另一个 worktree 切换分支 |
+| Worktree 中 `node_modules` 缺失 | 每个 worktree 需要独立安装依赖 | 在 worktree 目录中运行 `npm install` (或对应包管理器) |
+| Worktree 中 IDE 打开错误项目 | IDE 可能缓存了主仓库路径 | 用 `code ../project-feat-auth` 打开新窗口 |
+| 删除 worktree 后分支还在 | `worktree remove` 不删除分支 | 按需手动删除: `git branch -d feat/auth` |
+
+---
+
+## 5. 最佳实践
+
+- **命名规范:** worktree 目录名用 `项目名-分支描述`，便于识别
+- **及时清理:** 分支合并后立即删除对应 worktree
+- **独立依赖:** 每个 worktree 安装独立的 `node_modules` (不要软链接)
+- **避免嵌套:** 不要在 worktree 内创建 worktree
+- **用 list 检查:** 定期 `git worktree list` 清理废弃的 worktree