From 451eaaf2915175c921cca4c69ffa41bbc56dcf75 Mon Sep 17 00:00:00 2001 From: liuhao Date: Sun, 4 Jan 2026 15:30:12 +0800 Subject: [PATCH 01/99] Add design document for personal developer adaptation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the plan to adapt Superpowers for personal development workflow: - Configuration system for personal/team modes - Decision points with user confirmation - Enhanced brainstorming with document-driven workflow - Modified skills: using-git-worktrees, TDD, finishing-a-development-branch - Local plugin installation and upstream sync strategy 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../2025-01-04-personal-superpowers-design.md | 319 ++++++++++++++++++ 1 file changed, 319 insertions(+) create mode 100644 docs/plans/2025-01-04-personal-superpowers-design.md diff --git a/docs/plans/2025-01-04-personal-superpowers-design.md b/docs/plans/2025-01-04-personal-superpowers-design.md new file mode 100644 index 000000000..5704d8513 --- /dev/null +++ b/docs/plans/2025-01-04-personal-superpowers-design.md @@ -0,0 +1,319 @@ +# Superpowers 个人开发者适配设计方案 + +**日期**: 2025-01-04 +**设计目标**: 将 Superpowers 插件适配为个人开发者工作流，保留核心能力但提供灵活的决策选择 + +## 背景和需求 + +用户是一名个人开发者，从 Superpowers 原仓库 fork 了插件进行定制。当前 Superpowers 的某些重型流程（TDD、git worktree、PR）对个人开发场景来说过于复杂。 + +**核心需求**: +1. 保留原有 Superpowers 的完整能力和 skills +2. 在关键决策点提供选择，让用户决定使用哪种流程 +3. 支持用户的工作模式：对话驱动设计 → 文档沉淀 → 编码实现 +4. 首次配置后提供默认值，但关键决策点仍需二次确认 + +## 系统架构 + +### 1. 配置系统 + +创建项目级配置文件 `.superpowers-config.yaml`（gitignored），包含： + +```yaml +# 开发模式：personal（个人）或 team（团队） +development_mode: personal + +# 分支策略：worktree（隔离工作树）或 simple（普通分支） +branch_strategy: simple + +# 测试策略：tdd（先测试后代码）或 test-after（先代码后测试） +testing_strategy: test-after + +# 完成策略：pr（创建 PR）、merge（本地合并）或 keep（保留分支） +completion_strategy: merge +``` + +**配置文件位置**: 项目根目录，向上遍历查找 + +**配置创建时机**: 首次使用插件时，通过 AskUserQuestion 工具引导用户创建 + +### 2. 配置管理模块 + +创建 `lib/config-manager.js`（ES 模块），提供： + +- `detectConfig(projectDir)` - 向上遍历目录树查找配置文件 +- `readConfig(projectDir)` - 读取并解析 YAML +- `writeConfig(projectDir, config)` - 创建配置文件 +- `promptForInitialConfig()` - 返回 AskUserQuestion 结构用于首次配置 + +**技术选择**: 使用 YAML 格式（易读、支持注释）。如果没有 js-yaml 依赖，使用轻量级纯 JS 解析器。 + +### 3. Session Start Hook 增强 + +修改 `hooks/session-start.sh`： + +1. 调用 `config-manager.js` 检测配置文件 +2. 如果配置不存在，在 `additionalContext` 中注入 `` 标记 +3. `using-superpowers` skill 检测到标记后，触发初始配置流程 + +### 4. Skill 修改策略 + +#### using-git-worktrees + +**修改点**: 在创建 worktree 前增加决策 + +``` +[决策点] 分支创建策略 + +当前配置建议：使用普通分支（simple） +原因：个人模式下，普通分支更轻量，无需 worktree 隔离 + +选项： +1. 采用建议（普通分支） +2. 更改为：worktree（隔离环境） +3. 跳过此步骤 +``` + +#### test-driven-development + +**修改点**: 不强制"先写测试"，支持配置驱动 + +``` +[决策点] 测试策略 + +当前配置允许：先写代码再补充测试 +建议流程：实现功能 → 编写测试 → 验证通过 +注意：这偏离了严格 TDD，但适合个人开发场景 + +选项： +1. 按配置执行（代码优先） +2. 改用严格 TDD（测试优先） +3. 跳过测试 +``` + +#### finishing-a-development-branch + +**修改点**: 根据配置调整推荐选项 + +**个人模式**： +- 默认推荐：本地 merge +- 次选：保留分支（继续开发） +- 不可见：创建 PR（除非明确选择） + +**团队模式**： +- 默认推荐：创建 PR +- 次选：本地 merge +- 可选：保留分支 + +#### brainstorming + +**修改点**: 增强文档输出功能 + +1. 设计阶段完成后，自动创建 `docs/plans/YYYY-MM-DD--design.md` +2. 设计文档包含：需求概述、架构设计、实施要点 +3. 提示用户："设计已保存到文档。你可以通过编辑文档来调整设计，完成后说'继续'进入实施阶段。" + +### 5. 决策确认模板 + +统一的决策交互格式： + +``` +[决策点] <决策名称> + +当前配置建议：<<建议方案>> + +原因：<<基于当前配置的解释>> + +选项： +1. 采用建议 +2. 更改为：<<替代方案>> +3. 跳过此步骤 + +请选择： +``` + +## 实施计划 + +### 第一阶段：Brainstorming 文档增强 + +**文件修改**: +- `skills/brainstorming/SKILL.md` + +**改动内容**: +- 在设计完成后增加文档输出步骤 +- 创建 `docs/plans/` 目录（如果不存在） +- 保存设计为 Markdown 文件 +- 提示用户可以通过编辑文档继续完善设计 + +**验证方法**: +1. 运行 `/superpowers:brainstorm` +2. 完成设计对话 +3. 确认 `docs/plans/` 下生成了设计文档 +4. 编辑文档，说"继续"，验证 Claude 能读取更新后的设计 + +### 第二阶段：配置系统基础 + +**文件新增**: +- `lib/config-manager.js` + +**文件修改**: +- `hooks/session-start.sh` - 增加配置检测逻辑 + +**改动内容**: +1. 实现 `config-manager.js` 的四个核心函数 +2. 修改 session start hook，调用配置检测 +3. 在 `using-superpowers` skill 中增加配置初始化逻辑 + +**验证方法**: +1. 在新项目中首次使用插件 +2. 验证触发配置创建流程 +3. 检查 `.superpowers-config.yaml` 是否正确创建 +4. 重新启动会话，验证配置能被正确读取 + +### 第三阶段：Git 流程适配 + +**文件修改**: +- `skills/using-git-worktrees/SKILL.md` +- `skills/finishing-a-development-branch/SKILL.md` + +**改动内容**: +1. 在 worktree 创建前增加决策点 +2. 在分支完成时根据配置调整选项 +3. 实现普通分支的创建和切换逻辑 + +**验证方法**: +1. 设置 `branch_strategy: simple` +2. 启动一个新功能开发 +3. 验证提示使用普通分支 +4. 完成功能后验证推荐本地 merge + +### 第四阶段：测试策略适配 + +**文件修改**: +- `skills/test-driven-development/SKILL.md` + +**改动内容**: +1. 读取 `testing_strategy` 配置 +2. 支持"先代码后测试"流程 +3. 保留决策确认机制 + +**验证方法**: +1. 设置 `testing_strategy: test-after` +2. 实现一个功能 +3. 验证不强制先写测试 +4. 确认完成后提醒补充测试 + +### 第五阶段：端到端测试 + +**测试场景**: 完整的"设计 → 编码 → 完成"流程 + +1. 使用 `/superpowers:brainstorm` 完成设计 +2. 编辑设计文档进行调整 +3. 进入实施阶段 +4. 在各个决策点选择个人模式偏好 +5. 验证完整的开发流程 + +## 本地插件安装 + +### 配置本地 Marketplace + +在 `~/.claude/settings.json` 中添加： + +```json +{ + "localMarketplaces": [ + { + "directory": "/Users/zego/Zego/horspowers", + "name": "horspowers-dev" + } + ] +} +``` + +### 安装和切换 + +```bash +# 安装本地版本 +/plugin install superpowers@horspowers-dev + +# 卸载旧版本 +/plugin uninstall superpowers@superpowers-marketplace +``` + +### 回退机制 + +如遇问题可随时切回原版： + +```bash +/plugin uninstall superpowers@horspowers-dev +/plugin install superpowers@superpowers-marketplace +``` + +## 与上游同步 + +### Git 工作流 + +```bash +# 获取上游更新 +git fetch upstream + +# 查看变化 +git log main..upstream/main --oneline + +# 合并或 rebase +git merge upstream/main +# 或 +git rebase upstream/main +``` + +### 冲突处理原则 + +1. **优先保留你的修改** - 定制的 skills 是核心功能 +2. **手动审查上游变更** - 评估是否需要合并改进 +3. **实验性功能用分支** - 测试可行后再合并到 main + +### 版本号管理 + +修改 `plugin.json`，使用独立版本号： + +```json +{ + "version": "4.0.3-lh.1" +} +``` + +### Gitignore + +添加 `.superpowers-config.yaml` 到 `.gitignore`： + +```bash +echo ".superpowers-config.yaml" >> .gitignore +``` + +可选：创建 `.superpowers-config.yaml.example` 作为模板提交到 git。 + +## 文件清单 + +### 新增文件 + +- `lib/config-manager.js` - 配置管理模块 +- `.superpowers-config.yaml.example` - 配置模板 + +### 修改文件 + +- `skills/brainstorming/SKILL.md` - 增强文档输出 +- `skills/using-git-worktrees/SKILL.md` - 添加决策点 +- `skills/test-driven-development/SKILL.md` - 支持配置驱动 +- `skills/finishing-a-development-branch/SKILL.md` - 根据配置调整选项 +- `hooks/session-start.sh` - 增加配置检测 +- `plugin.json` - 更新版本号 +- `.gitignore` - 忽略配置文件 + +## 成功标准 + +1. ✅ 配置系统正常工作，能创建和读取配置 +2. ✅ 所有关键决策点提供选择，且显示配置建议 +3. ✅ 个人模式下默认使用轻量级流程（普通分支、本地 merge、可选测试） +4. ✅ 文档作为沟通媒介，支持编辑后继续 +5. ✅ 能与上游保持同步，不丢失核心功能 +6. ✅ 可以随时切换回原版 superpowers From b79b7740603ec2b9670a7c2e5f63653b884e11f8 Mon Sep 17 00:00:00 2001 From: liuhao Date: Sun, 4 Jan 2026 15:34:10 +0800 Subject: [PATCH 02/99] Enhance brainstorming skill to support document-driven workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - Add prompt telling users they can edit the design document - Re-read design document when user says "继续" or "ready" - Treat the document as source of truth if modified - Ask user whether they need isolated workspace (worktree) before implementation This supports the user's workflow: dialogue → document refinement → implementation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/brainstorming/SKILL.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index 2fd19ba1e..6d7d524ff 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -38,10 +38,18 @@ Start by understanding the current project context, then ask questions one at a - Write the validated design to `docs/plans/YYYY-MM-DD--design.md` - Use elements-of-style:writing-clearly-and-concisely skill if available - Commit the design document to git +- **Crucial**: Tell the user: "设计已保存到文档。你可以通过编辑文档来调整设计，完成后说'继续'或'ready'进入实施阶段。" +- Wait for user confirmation - they may edit the document before proceeding + +**Document as communication medium:** +- If user says "继续" or "ready" after documentation, re-read the design document +- The document may have been modified by the user - treat it as the source of truth +- Confirm understanding before proceeding: "基于文档中的设计，我们准备开始实施。确认继续？" **Implementation (if continuing):** -- Ask: "Ready to set up for implementation?" -- Use superpowers:using-git-worktrees to create isolated workspace +- After user confirms, ask: "需要创建隔离的开发环境吗？" +- If yes: Use superpowers:using-git-worktrees to create isolated workspace +- If no: Continue in current branch - Use superpowers:writing-plans to create detailed implementation plan ## Key Principles From e03223691c5bbadaa36d6880644d13cc2d46407c Mon Sep 17 00:00:00 2001 From: liuhao Date: Sun, 4 Jan 2026 15:36:05 +0800 Subject: [PATCH 03/99] Implement configuration system foundation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - Add lib/config-manager.js: ES module for config file detection and parsing - Modify hooks/session-start.sh: Detect .superpowers-config.yaml and inject markers - Update skills/using-superpowers/SKILL.md: Add configuration initialization logic Features: - Simple YAML parser for config files (no external dependencies) - Upward directory traversal to find config in parent directories - Session start hook detects existing config or marks for initial setup - using-superpowers skill guides first-time configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 161 +++++++++++++++++++++++ hooks/session-start.sh | 53 +++++++- lib/config-manager.js | 205 ++++++++++++++++++++++++++++++ skills/using-superpowers/SKILL.md | 42 ++++++ 4 files changed, 460 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md create mode 100644 lib/config-manager.js diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..2d9611f04 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,161 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Personal Rule +Always respond in *Simplified Chinese/中文* + +## Project Overview + +Superpowers is a skills library for Claude Code that provides composable workflows for software development. It's a plugin that injects skills at session start and provides slash commands for common workflows. + +**Key concept:** Skills are Markdown files with YAML frontmatter that Claude invokes via the `Skill` tool. The `using-superpowers` skill is injected automatically at session start via a hook. + +## Running Tests + +```bash +# Run fast tests (default) +./tests/claude-code/run-skill-tests.sh + +# Run integration tests (slow, 10-30 minutes) +./tests/claude-code/run-skill-tests.sh --integration + +# Run specific test with verbose output +./tests/claude-code/run-skill-tests.sh --test test-subagent-driven-development.sh --verbose +``` + +**Important:** Tests must run FROM the superpowers directory, not from temp directories. Integration tests create real projects and execute full workflows. + +## Architecture + +### Skill Structure + +Each skill lives in `skills//SKILL.md`: + +```yaml +--- +name: skill-name +description: Use when [condition] - [what it does] +--- + +# Skill Title + +## Overview +... + +## The Process +... +``` + +- **Frontmatter:** `name` (lowercase kebab-case), `description` (trigger-only, no process details) +- **Description trap:** Never include workflow steps in description - Claude will follow description instead of reading the skill +- **Cross-references:** Use `superpowers:skill-name` format for internal references + +### Slash Commands + +Commands in `commands/` are user-only wrappers around skills: + +```yaml +--- +description: Brief description +disable-model-invocation: true +--- + +Invoke the superpowers:skill-name skill and follow it exactly as presented to you +``` + +The `disable-model-invocation: true` prevents Claude from invoking commands - only users can invoke slash commands. + +### Session Start Hook + +`hooks/session-start.sh` injects `using-superpowers` skill content into every session via `additionalContext`. The hook uses a polyglot wrapper (`run-hook.cmd`) for cross-platform support. + +### Skill Resolution + +- Personal skills (`~/.claude/skills/`) override superpowers skills +- Use `superpowers:` prefix to force using a superpowers skill +- Skills are discovered by finding `SKILL.md` files recursively + +## The Superpowers Workflow + +1. **brainstorming** - Refine ideas through questions, present design in sections +2. **using-git-worktrees** - Create isolated workspace on new branch +3. **writing-plans** - Break work into bite-sized tasks (2-5 min each) +4. **subagent-driven-development** or **executing-plans** - Execute with reviews +5. **test-driven-development** - RED-GREEN-REFACTOR cycle +6. **requesting-code-review** - Pre-review checklist +7. **finishing-a-development-branch** - Merge/PR decision workflow + +## Key Skills + +**Process skills (run first):** +- `brainstorming` - Design refinement before implementation +- `systematic-debugging` - 4-phase root cause process + +**Implementation skills:** +- `test-driven-development` - TDD workflow with anti-patterns reference +- `writing-plans` - Detailed implementation plans +- `executing-plans` - Batch execution with checkpoints + +**Collaboration skills:** +- `subagent-driven-development` - Two-stage review: spec compliance THEN code quality +- `using-git-worktrees` - Parallel development branches +- `finishing-a-development-branch` - Branch completion options +- `receiving-code-review` - Responding to feedback + +**Meta skills:** +- `using-superpowers` - Introduction to skills system +- `writing-skills` - Creating and testing new skills + +## Testing Methodology + +Skills are tested using headless Claude Code sessions: + +```bash +claude -p "prompt" --allowed-tools=all --add-dir "$TEST_DIR" --permission-mode bypassPermissions +``` + +Session transcripts (`.jsonl` files) are parsed to verify: +- Skill tool was invoked +- Subagents were dispatched +- Files were created +- Tests pass +- Git commits show proper workflow + +See `docs/testing.md` for detailed testing guidance. + +## Skill Authoring + +When creating new skills: + +1. Follow patterns in `writing-skills/SKILL.md` +2. Use imperative descriptions: "You MUST use this when..." +3. Keep descriptions trigger-only - don't summarize the process +4. Use DOT flowcharts for non-obvious decision points +5. Test using the methodology in `writing-skills/testing-skills-with-subagents.md` + +**Token efficiency:** Aim for under 500 lines per skill. Use progressive disclosure - hide details behind "See X" references. + +## Platform Support + +- **Claude Code:** Native plugin via marketplace (this repo) +- **Codex:** See `docs/README.codex.md` - uses `lib/skills-core.js` +- **OpenCode:** See `docs/README.opencode.md` - shares `lib/skills-core.js` + +## Common Pitfalls + +**The Description Trap:** If description summarizes the workflow, Claude follows description instead of reading the skill. Keep descriptions trigger-only: "Use when X" not "Use when X to do Y via Z". + +**Rationalization:** Agents think "I know what this means" and skip skill invocation. The `using-superpowers` skill lists 12+ rationalization patterns to counter this. + +**Test before implementing:** The `test-driven-development` skill deletes any code written before tests. Always invoke TDD before implementation tasks. + +**Merge without testing:** The `finishing-a-development-branch` skill verifies tests pass BEFORE presenting merge/PR options. + +## Files of Interest + +- `plugin.json` - Plugin metadata +- `hooks/hooks.json` - Hook registration +- `lib/skills-core.js` - Shared utilities for Codex/OpenCode +- `agents/code-reviewer.md` - Code reviewer agent definition +- `RELEASE-NOTES.md` - Version history with detailed changelogs diff --git a/hooks/session-start.sh b/hooks/session-start.sh index f5d94497d..943fde0e3 100755 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -14,6 +14,55 @@ if [ -d "$legacy_skills_dir" ]; then warning_message="\n\nIN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead. To make this message go away, remove ~/.config/superpowers/skills" fi +# Detect configuration file in current working directory +config_message="" +config_detected_marker="" + +# Try to find .superpowers-config.yaml +current_dir="$PWD" +while [ "$current_dir" != "/" ]; do + if [ -f "$current_dir/.superpowers-config.yaml" ]; then + # Config found, read it using Node.js + if config_output=$(node -e " + const fs = require('fs'); + const path = require('path'); + const configPath = path.join('$current_dir', '.superpowers-config.yaml'); + try { + const content = fs.readFileSync(configPath, 'utf8'); + const lines = content.split('\\n'); + const config = {}; + for (const line of lines) { + const trimmed = line.trim(); + if (trimmed && !trimmed.startsWith('#')) { + const match = trimmed.match(/^(\\w+):\\s*(.+)$/); + if (match) { + config[match[1]] = match[2]; + } + } + } + console.log(JSON.stringify(config)); + } catch (e) { + console.error('Error:', e.message); + } + " 2>/dev/null); then + config_message="\n\n当前项目配置：$config_output" + config_detected_marker="true" + fi + break + fi + # Move up one directory + new_dir=$(dirname "$current_dir") + if [ "$new_dir" = "$current_dir" ]; then + break + fi + current_dir="$new_dir" +done + +# If no config found, add marker for initial setup +if [ -z "$config_detected_marker" ]; then + config_detected_marker="false" +fi + # Read using-superpowers content using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill") @@ -38,13 +87,15 @@ escape_for_json() { using_superpowers_escaped=$(escape_for_json "$using_superpowers_content") warning_escaped=$(escape_for_json "$warning_message") +config_escaped=$(escape_for_json "$config_message") +config_marker_escaped=$(escape_for_json "$config_detected_marker") # Output context injection as JSON cat <\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n" + "additionalContext": "\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${config_marker_escaped}${config_escaped}${warning_escaped}\n" } } EOF diff --git a/lib/config-manager.js b/lib/config-manager.js new file mode 100644 index 000000000..3e62cfaec --- /dev/null +++ b/lib/config-manager.js @@ -0,0 +1,205 @@ +/** + * Configuration Manager for Superpowers + * + * Manages project-level configuration for personal/team development modes. + */ + +import fs from 'fs'; +import path from 'path'; + +const CONFIG_FILENAME = '.superpowers-config.yaml'; +const CONFIG_TEMPLATE = `# Superpowers Configuration +# This file controls development workflow preferences + +# Development mode: personal (individual developer) or team (collaborative) +development_mode: personal + +# Branch strategy: worktree (isolated environment) or simple (regular branches) +branch_strategy: simple + +# Testing strategy: tdd (test-first) or test-after (code-first, add tests later) +testing_strategy: test-after + +# Completion strategy: pr (create pull request), merge (local merge), or keep (preserve branch) +completion_strategy: merge +`; + +/** + * Find the configuration file by traversing up the directory tree + * + * @param {string} startDir - Directory to start searching from + * @returns {string|null} - Path to config file or null if not found + */ +function findConfigFile(startDir) { + let currentDir = startDir; + + while (currentDir !== path.parse(currentDir).root) { + const configPath = path.join(currentDir, CONFIG_FILENAME); + + if (fs.existsSync(configPath)) { + return configPath; + } + + // Move up one directory + const parentDir = path.dirname(currentDir); + if (parentDir === currentDir) { + break; // Reached the root + } + currentDir = parentDir; + } + + return null; +} + +/** + * Simple YAML parser for our specific config format + * Handles key: value pairs and ignores comments + * + * @param {string} content - YAML content + * @returns {Object} - Parsed configuration + */ +function parseSimpleYAML(content) { + const config = {}; + const lines = content.split('\n'); + + for (const line of lines) { + const trimmed = line.trim(); + + // Skip empty lines and comments + if (!trimmed || trimmed.startsWith('#')) { + continue; + } + + // Parse key: value pairs + const match = trimmed.match(/^(\w+):\s*(.+)$/); + if (match) { + const [, key, value] = match; + + // Convert value to appropriate type + if (value === 'true') { + config[key] = true; + } else if (value === 'false') { + config[key] = false; + } else if (!isNaN(value)) { + config[key] = Number(value); + } else { + config[key] = value; + } + } + } + + return config; +} + +/** + * Detect configuration file in project directory + * + * @param {string} projectDir - Project directory path + * @returns {Object} - { found: boolean, path: string|null } + */ +function detectConfig(projectDir) { + const configPath = findConfigFile(projectDir); + + return { + found: !!configPath, + path: configPath + }; +} + +/** + * Read and parse configuration file + * + * @param {string} projectDir - Project directory path + * @returns {Object|null} - Parsed configuration or null if not found + */ +function readConfig(projectDir) { + const { found, path: configPath } = detectConfig(projectDir); + + if (!found) { + return null; + } + + try { + const content = fs.readFileSync(configPath, 'utf8'); + return parseSimpleYAML(content); + } catch (error) { + console.error(`Error reading config file: ${error.message}`); + return null; + } +} + +/** + * Write configuration file to project directory + * + * @param {string} projectDir - Project directory path + * @param {Object} config - Configuration object to write + * @returns {boolean} - Success status + */ +function writeConfig(projectDir, config) { + const configPath = path.join(projectDir, CONFIG_FILENAME); + + try { + // Convert config object to YAML format + const yamlContent = Object.entries(config) + .map(([key, value]) => `${key}: ${value}`) + .join('\n'); + + const content = `# Superpowers Configuration +# This file controls development workflow preferences + +${yamlContent} +`; + + fs.writeFileSync(configPath, content, 'utf8'); + return true; + } catch (error) { + console.error(`Error writing config file: ${error.message}`); + return false; + } +} + +/** + * Get the structure for initial configuration prompt + * Returns AskUserQuestion compatible structure + * + * @returns {Object} - Question structure for initial setup + */ +function promptForInitialConfig() { + return { + questions: [ + { + question: '请选择你的开发模式：', + header: '开发模式', + options: [ + { + label: '个人开发者', + description: '单人开发，使用简化的工作流程（普通分支、本地合并、可选测试）' + }, + { + label: '团队协作', + description: '团队开发，使用完整的工作流程（worktree 隔离、PR 流程、TDD）' + } + ], + multiSelect: false + } + ] + }; +} + +/** + * Get configuration template content + * + * @returns {string} - Template YAML content + */ +function getTemplate() { + return CONFIG_TEMPLATE; +} + +export { + detectConfig, + readConfig, + writeConfig, + promptForInitialConfig, + getTemplate, + CONFIG_FILENAME +}; diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index 7867fcfc0..56088c000 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -85,3 +85,45 @@ The skill itself tells you which. ## User Instructions Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows. + +## Configuration System (Personal/Team Modes) + +**Check for configuration marker on session start:** + +When this skill is injected via session start hook, check for `` marker: + +**If `false`:** +- On your FIRST response to the user, you MUST guide them through initial configuration +- Use AskUserQuestion to ask about their development preferences: + +``` +欢迎使用 Superpowers！检测到这是首次使用，需要配置开发模式。 + +**请选择你的开发模式：** + +1. **个人开发者** - 单人开发，使用简化的工作流程： + - 使用普通分支而非 worktree + - 本地合并而非创建 PR + - 可选的测试（可以写完代码再测试） + +2. **团队协作** - 团队开发，使用完整的工程化流程： + - 使用 worktree 隔离环境 + - 创建 PR 进行代码审查 + - 严格的 TDD 流程 + +请选择 1 或 2： +``` + +- After user selects, create `.superpowers-config.yaml` in current directory with appropriate settings +- Personal mode: `development_mode: personal`, `branch_strategy: simple`, `testing_strategy: test-after`, `completion_strategy: merge` +- Team mode: `development_mode: team`, `branch_strategy: worktree`, `testing_strategy: tdd`, `completion_strategy: pr` + +**If `true`:** +- Configuration file exists - read `` marker for current settings +- Store these settings in memory for use by other skills +- Don't mention configuration unless user asks or a skill needs to make a decision + +**Config usage by other skills:** +- Skills should read the configuration from session context +- At decision points, show "根据当前配置（），建议：..." with confirmation +- Always allow user to override the suggestion From 2973ced4f00cf93e70a44c7a941a4bfcd76be8db Mon Sep 17 00:00:00 2001 From: liuhao Date: Sun, 4 Jan 2026 15:37:41 +0800 Subject: [PATCH 04/99] Add decision point to using-git-worktrees skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - Add "Decision Point: Branch Strategy" section before creation steps - Check configuration for branch_strategy setting - Present user with choice: simple branch vs worktree vs skip - Support personal mode workflow (simple branches) alongside team mode (worktrees) This allows personal developers to use lightweight branching while preserving the full worktree capability for team collaboration scenarios. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/using-git-worktrees/SKILL.md | 43 +++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/skills/using-git-worktrees/SKILL.md b/skills/using-git-worktrees/SKILL.md index 9d52d80cc..7f2e6279f 100644 --- a/skills/using-git-worktrees/SKILL.md +++ b/skills/using-git-worktrees/SKILL.md @@ -72,6 +72,49 @@ Per Jesse's rule "Fix broken things immediately": No .gitignore verification needed - outside project entirely. +## Decision Point: Branch Strategy + +**Before creating worktree, check configuration:** + +Read session context for `` marker to get current `branch_strategy` setting. + +**Present decision to user:** + +``` +[决策点] 分支创建策略 + +根据当前配置，建议使用：<> + +**个人模式（simple 分支策略）：** +- 使用普通分支，更轻量 +- 适合单人开发，无需环境隔离 +- 可以直接在当前项目目录中工作 + +**团队模式（worktree 分支策略）：** +- 使用 worktree 隔离环境 +- 适合多人协作或需要并行开发多个分支 +- 保持主分支环境干净 + +选项： +1. 采用建议（<<建议方案>>） +2. 改用：<<替代方案>> +3. 跳过分支创建，直接在当前分支工作 + +请选择： +``` + +**If user chooses simple branch:** +- Create new branch without worktree: `git checkout -b ` +- Skip worktree directory logic +- Continue with project setup in current directory + +**If user chooses worktree:** +- Proceed with worktree creation steps below + +**If user chooses skip:** +- Continue working in current branch +- Don't create any new branches + ## Creation Steps ### 1. Detect Project Name From 885f52b6dcef0b69b9948be91d9c38eebfc63818 Mon Sep 17 00:00:00 2001 From: liuhao Date: Sun, 4 Jan 2026 15:38:09 +0800 Subject: [PATCH 05/99] Add configuration-aware workflow to test-driven-development skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - Add "Configuration-Aware Workflow" section before Iron Law - Check testing_strategy from configuration - Present decision point for personal mode: code-first vs test-first vs skip - Support test-after workflow for personal developers - Team mode enforces strict TDD without decision point This allows personal developers to use flexible testing strategies while preserving strict TDD for team collaboration scenarios. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/test-driven-development/SKILL.md | 43 +++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/skills/test-driven-development/SKILL.md b/skills/test-driven-development/SKILL.md index 7a751fa94..bec24ab56 100644 --- a/skills/test-driven-development/SKILL.md +++ b/skills/test-driven-development/SKILL.md @@ -28,6 +28,49 @@ Write the test first. Watch it fail. Write minimal code to pass. Thinking "skip TDD just this once"? Stop. That's rationalization. +## Configuration-Aware Workflow + +**Before starting TDD cycle, check configuration:** + +Read session context for `` marker to get current `testing_strategy` setting. + +**If `testing_strategy: test-after` (Personal Mode):** + +Present decision to user: + +``` +[决策点] 测试策略 + +当前配置允许：先写代码再补充测试 +建议流程：实现功能 → 编写测试 → 验证通过 +注意：这偏离了严格 TDD，但适合个人开发场景 + +选项： +1. 按配置执行（代码优先，后续补充测试） +2. 改用严格 TDD（测试优先，RED-GREEN-REFACTOR） +3. 跳过测试（不推荐，仅用于原型验证） + +请选择： +``` + +**If user chooses "代码优先" (test-after):** +- Implement the feature first +- Then write tests to verify behavior +- Finally verify all tests pass +- Skip strict RED-GREEN-REFACTOR cycle for this iteration + +**If user chooses "严格 TDD":** +- Proceed with standard TDD cycle below (Red-Green-Refactor) + +**If user chooses "跳过测试":** +- Warn user this is for prototypes only +- Implement without tests +- Remind user to add tests later if code becomes production + +**If `testing_strategy: tdd` (Team Mode):** +- Proceed directly with strict TDD cycle below +- No decision point needed - TDD is mandatory for team collaboration + ## The Iron Law ``` From 4cfe8195d7799a0907e3cbb1a01b998b4c8dfda2 Mon Sep 17 00:00:00 2001 From: liuhao Date: Sun, 4 Jan 2026 15:38:39 +0800 Subject: [PATCH 06/99] Add configuration-aware options to finishing-a-development-branch skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Changes: - Check completion_strategy and development_mode from configuration - Personal mode: recommends local merge, excludes PR option (keeps 3 options) - Team mode: recommends PR, includes all 4 options - Support explicit completion_strategy override (merge/pr/keep) - Add visual recommendation marker (✨) to suggested option This tailors the completion workflow to the user's development mode while preserving full flexibility for team collaboration scenarios. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../finishing-a-development-branch/SKILL.md | 34 ++++++++++++++++--- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/skills/finishing-a-development-branch/SKILL.md b/skills/finishing-a-development-branch/SKILL.md index c308b43b4..336266eea 100644 --- a/skills/finishing-a-development-branch/SKILL.md +++ b/skills/finishing-a-development-branch/SKILL.md @@ -48,20 +48,46 @@ Or ask: "This branch split from main - is that correct?" ### Step 3: Present Options -Present exactly these 4 options: +**Check configuration first:** + +Read session context for `` marker to get current `completion_strategy` and `development_mode` settings. + +**Present options based on configuration:** + +**Personal Mode (`development_mode: personal`):** ``` Implementation complete. What would you like to do? -1. Merge back to locally -2. Push and create a Pull Request +根据当前配置（个人开发者模式），推荐： +1. ✨ Merge back to locally （推荐） +2. Keep the branch as-is (I'll handle it later) +3. Discard this work + +Which option? +``` + +**Team Mode (`development_mode: team`):** + +``` +Implementation complete. What would you like to do? + +根据当前配置（团队协作模式），推荐： +1. ✨ Push and create a Pull Request （推荐） +2. Merge back to locally 3. Keep the branch as-is (I'll handle it later) 4. Discard this work Which option? ``` -**Don't add explanation** - keep options concise. +**If `completion_strategy` is explicitly set:** + +- `completion_strategy: merge` → Recommend local merge (Option 1) +- `completion_strategy: pr` → Recommend PR (Option 2) +- `completion_strategy: keep` → Recommend keep as-is (Option 3) + +**Keep options concise** - don't add explanations beyond the recommendation marker. ### Step 4: Execute Choice From 9362e9f0188bae7a9f1766e8dd33c056bfa958c6 Mon Sep 17 00:00:00 2001 From: liuhao Date: Sun, 4 Jan 2026 15:44:23 +0800 Subject: [PATCH 07/99] Add testing summary and test configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add .superpowers-config.yaml: Test configuration for personal mode - Add docs/plans/2025-01-04-testing-summary.md: Complete test results Test results: ✅ Configuration system working correctly ✅ Session start hook detects and parses config ✅ config-manager.js module functions properly ✅ All skills have config reading logic Note: Real session testing needed for decision point interactions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .superpowers-config.yaml | 14 ++ docs/plans/2025-01-04-testing-summary.md | 209 +++++++++++++++++++++++ 2 files changed, 223 insertions(+) create mode 100644 .superpowers-config.yaml create mode 100644 docs/plans/2025-01-04-testing-summary.md diff --git a/.superpowers-config.yaml b/.superpowers-config.yaml new file mode 100644 index 000000000..8911b0bf8 --- /dev/null +++ b/.superpowers-config.yaml @@ -0,0 +1,14 @@ +# Superpowers Configuration +# Test configuration for personal developer mode + +# Development mode: personal (individual developer) or team (collaborative) +development_mode: personal + +# Branch strategy: worktree (isolated environment) or simple (regular branches) +branch_strategy: simple + +# Testing strategy: tdd (test-first) or test-after (code-first, add tests later) +testing_strategy: test-after + +# Completion strategy: pr (create pull request), merge (local merge), or keep (preserve branch) +completion_strategy: merge diff --git a/docs/plans/2025-01-04-testing-summary.md b/docs/plans/2025-01-04-testing-summary.md new file mode 100644 index 000000000..2f3d7251d --- /dev/null +++ b/docs/plans/2025-01-04-testing-summary.md @@ -0,0 +1,209 @@ +# Superpowers 个人开发者适配 - 测试总结 + +**测试日期**: 2025-01-04 +**测试环境**: macOS (darwin) +**配置模式**: 个人开发者 (personal) + +## 测试配置 + +测试配置文件 `.superpowers-config.yaml`: + +```yaml +development_mode: personal +branch_strategy: simple +testing_strategy: test-after +completion_strategy: merge +``` + +## 测试结果 + +### ✅ 第一阶段：Brainstorming 文档增强 + +**修改文件**: `skills/brainstorming/SKILL.md` + +**测试项**: +- ✅ 设计文档保存功能已添加 +- ✅ 用户提示"可以编辑文档来调整设计" +- ✅ 支持用户说"继续"后重新读取文档 +- ✅ 询问是否需要隔离开发环境 + +**验证方法**: 代码审查 - 修改点已正确添加到 "After the Design" 部分 + +--- + +### ✅ 第二阶段：配置系统基础 + +**修改文件**: +- `lib/config-manager.js` (新增) +- `hooks/session-start.sh` +- `skills/using-superpowers/SKILL.md` + +**测试项**: + +#### 1. Session Start Hook 配置检测 +```bash +$ bash hooks/session-start.sh +``` +**结果**: ✅ 通过 +- `true` 标记正确注入 +- `` 包含完整配置 JSON +- 配置值正确解析 + +#### 2. 配置管理模块 (config-manager.js) +```bash +$ node -e "import('./lib/config-manager.js')..." +``` +**结果**: ✅ 全部通过 +- `detectConfig()`: 正确检测配置文件存在 +- `readConfig()`: 正确解析 YAML 配置 +- `promptForInitialConfig()`: 返回正确的 AskUserQuestion 结构 +- 所有配置值验证通过 + +#### 3. using-superpowers 配置初始化逻辑 +**验证方法**: 代码审查 +- ✅ 添加了 "Configuration System" 部分 +- ✅ 检测 `` 标记 +- ✅ 首次使用时引导配置创建 +- ✅ 配置存在时读取到内存 + +--- + +### ✅ 第三阶段：using-git-worktrees 决策点 + +**修改文件**: `skills/using-git-worktrees/SKILL.md` + +**测试项**: +- ✅ 添加 "Decision Point: Branch Strategy" 部分 +- ✅ 读取 `branch_strategy` 配置 +- ✅ 展示决策选项：worktree vs simple branch vs skip +- ✅ 支持普通分支创建逻辑 + +**验证方法**: 代码审查 - 配置读取逻辑正确 + +--- + +### ✅ 第四阶段：test-driven-development 配置驱动 + +**修改文件**: `skills/test-driven-development/SKILL.md` + +**测试项**: +- ✅ 添加 "Configuration-Aware Workflow" 部分 +- ✅ 读取 `testing_strategy` 配置 +- ✅ 支持测试策略决策：test-after vs tdd vs skip +- ✅ 个人模式允许代码优先流程 + +**验证方法**: 代码审查 - 配置读取和决策逻辑正确 + +--- + +### ✅ 第五阶段：finishing-a-development-branch 配置选项 + +**修改文件**: `skills/finishing-a-development-branch/SKILL.md` + +**测试项**: +- ✅ 检查 `completion_strategy` 和 `development_mode` +- ✅ 个人模式：推荐本地 merge，3 个选项（排除 PR） +- ✅ 团队模式：推荐 PR，4 个选项 +- ✅ 支持 `completion_strategy` 显式设置 + +**验证方法**: 代码审查 - 选项展示逻辑正确 + +--- + +### ✅ 本地 Marketplace 配置 + +**修改文件**: `.claude/settings.local.json` + +**配置内容**: +```json +{ + "extraKnownMarketplaces": { + "horspowers-dev": { + "source": { + "source": "directory", + "path": "/Users/zego/Zego/horspowers" + } + } + }, + "enabledPlugins": { + "superpowers@horspowers-dev": true + } +} +``` + +**结果**: ✅ 配置正确，本地插件已启用 + +--- + +## 提交历史 + +```bash +451eaaf Add design document for personal superpowers adaptation +b79b774 Enhance brainstorming skill to support document-driven workflow +e032236 Implement configuration system foundation +2973ced Add decision point to using-git-worktrees skill +885f52b Add configuration-aware workflow to test-driven-development skill +4cfe819 Add configuration-aware options to finishing-a-development-branch skill +``` + +--- + +## 已知限制和后续工作 + +### 需要真实会话测试的功能 + +以下功能需要在真实的 Claude Code 会话中测试（当前仅进行了代码审查和配置系统测试）： + +1. **配置初始化流程** + - 在没有配置的项目中首次使用时 + - 验证 AskUserQuestion 是否正确触发 + - 验证配置文件是否正确创建 + +2. **Brainstorming 文档驱动流程** + - 完成设计后文档是否正确生成 + - 编辑文档后说"继续"是否重新读取 + - 是否询问是否需要隔离环境 + +3. **各个决策点的实际表现** + - using-git-worktrees: 分支策略选择 + - test-driven-development: 测试策略选择 + - finishing-a-development-branch: 完成选项展示 + +### 建议的端到端测试场景 + +1. **创建新项目** + - 在新目录初始化项目 + - 触发配置初始化 + - 选择个人开发者模式 + - 验证配置文件创建 + +2. **完整开发流程** + - 使用 brainstorming 设计功能 + - 编辑设计文档 + - 实施功能 + - 完成分支 + +3. **团队模式切换** + - 修改配置为团队模式 + - 验证决策点变化 + +--- + +## 性能警告 + +配置管理模块使用了 ES modules，Node.js 提示需要添加 `"type": "module"` 到 package.json。这不影响功能，但添加后可消除警告。 + +--- + +## 总结 + +所有代码修改已完成并通过静态验证： + +- ✅ 5 个阶段的代码修改全部完成 +- ✅ 配置系统正常工作 +- ✅ Session start hook 正确检测配置 +- ✅ 配置管理模块功能完整 +- ✅ 所有 skills 的配置读取逻辑正确 +- ✅ 本地 marketplace 配置完成 + +**下一步**: 在真实 Claude Code 会话中进行端到端测试，验证决策点的实际交互效果。 From ad92aee90ce5dacdaa968b0ce11ce6b059a1bd2e Mon Sep 17 00:00:00 2001 From: liuhao Date: Sun, 4 Jan 2026 15:44:44 +0800 Subject: [PATCH 08/99] Add config template and update gitignore MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add .superpowers-config.yaml.example: Configuration template with comments - Update .gitignore: Add .superpowers-config.yaml to ignore local configs This allows projects to have their own configuration while providing a template for reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .gitignore | 1 + .superpowers-config.yaml.example | 21 +++++++++++++++++++++ 2 files changed, 22 insertions(+) create mode 100644 .superpowers-config.yaml.example diff --git a/.gitignore b/.gitignore index 573cae048..9581b1ebf 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .worktrees/ .private-journal/ .claude/ +.superpowers-config.yaml diff --git a/.superpowers-config.yaml.example b/.superpowers-config.yaml.example new file mode 100644 index 000000000..65d873ab6 --- /dev/null +++ b/.superpowers-config.yaml.example @@ -0,0 +1,21 @@ +# Superpowers Configuration Example +# Copy this file to .superpowers-config.yaml and customize for your project + +# Development mode: personal (individual developer) or team (collaborative) +development_mode: personal + +# Branch strategy: worktree (isolated environment) or simple (regular branches) +# - worktree: Creates isolated worktree for parallel development +# - simple: Uses regular git branches (lighter for personal development) +branch_strategy: simple + +# Testing strategy: tdd (test-first) or test-after (code-first, add tests later) +# - tdd: Strict test-driven development (write failing test first) +# - test-after: Write code first, add tests later (better for prototypes) +testing_strategy: test-after + +# Completion strategy: pr (create pull request), merge (local merge), or keep (preserve branch) +# - pr: Create GitHub PR for code review (team mode) +# - merge: Merge locally to base branch (personal mode) +# - keep: Preserve branch for continued development +completion_strategy: merge From 7f4b656854a04fc76bfcc80867c4e149f758332c Mon Sep 17 00:00:00 2001 From: liuhao Date: Wed, 7 Jan 2026 12:08:17 +0800 Subject: [PATCH 09/99] Add document-driven-ai-workflow integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Integrate superpowers with document-driven-ai-workflow to enable automatic document generation at key workflow points, building cross-session AI context memory. Changes: - Add document-driven-bridge skill for unified document management - Add configuration template with full integration options - Add bilingual integration guides (English/Chinese) - Add quick start guides for 5-minute setup - Update README with documentation integration section Integration points: - brainstorming: Records technical decisions - writing-plans: Creates task tracking documents - test-driven-development: Logs bugs and fixes - finishing-a-development-branch: Archives completed work 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .superpowers-config.template.yaml | 200 +++++++++ README.md | 63 ++- docs/document-driven-integration-guide-en.md | 412 +++++++++++++++++++ docs/document-driven-integration-guide.md | 412 +++++++++++++++++++ docs/document-driven-quickstart-en.md | 309 ++++++++++++++ docs/document-driven-quickstart.md | 309 ++++++++++++++ skills/document-driven-bridge/SKILL.md | 268 ++++++++++++ 7 files changed, 1968 insertions(+), 5 deletions(-) create mode 100644 .superpowers-config.template.yaml create mode 100644 docs/document-driven-integration-guide-en.md create mode 100644 docs/document-driven-integration-guide.md create mode 100644 docs/document-driven-quickstart-en.md create mode 100644 docs/document-driven-quickstart.md create mode 100644 skills/document-driven-bridge/SKILL.md diff --git a/.superpowers-config.template.yaml b/.superpowers-config.template.yaml new file mode 100644 index 000000000..ee428fda7 --- /dev/null +++ b/.superpowers-config.template.yaml @@ -0,0 +1,200 @@ +# Superpowers 项目配置模板 +# 复制此文件到项目根目录并重命名为 .superpowers-config.yaml + +version: "1.0" + +# ============================================ +# 开发模式配置 +# ============================================ +# personal: 个人开发者，本地合并，可选测试 +# team: 团队协作，worktree 开发，PR 合并，强制测试 +development_mode: team + +# ============================================ +# 完成策略 +# ============================================ +# merge: 本地合并到主分支 +# pr: 创建 Pull Request +# keep: 保持分支，稍后处理 +completion_strategy: pr + +# ============================================ +# 文档驱动工作流集成 +# ============================================ +documentation: + # 是否启用文档集成 + enabled: true + + # document-driven-ai-workflow CLI 工具路径 + # 根据你的实际安装位置修改 + # 示例： + # - 全局安装：cli_path: "docs" + # - 本地路径：cli_path: "node /absolute/path/to/document-driven-ai-workflow/cli.js" + # - 相对路径：cli_path: "node ../document-driven-ai-workflow/cli.js" + cli_path: "node /path/to/document-driven-ai-workflow/cli.js" + + # 各工作流的文档集成配置 + workflows: + # brainstorming 技能集成 + brainstorming: + # 开始前搜索的文档类型 + pre_search: + - "项目架构" + - "技术决策" + - "相关设计" + # 完成后创建的文档 + create: + - type: decision + when: "technical_decisions_made" + title_template: "技术决策：{design_topic}" + + # writing-plans 技能集成 + writing-plans: + # 开始前搜索 + pre_search: + - "相关功能" + - "类似任务" + - "实施历史" + # 完成后创建 + create: + - type: task + always: true + title_template: "实现：{feature_name}" + + # test-driven-development 技能集成 + test-driven-development: + # 测试失败时 + create: + - type: bug + when: "test_fails_unexpectedly" + title_template: "Bug：{test_name}" + # 修复完成时 + update: + - type: bug + when: "bug_fixed" + status: "已修复" + + # subagent-driven-development 技能集成 + subagent-driven-development: + # 每个子任务完成后 + update: + - type: task + when: "checkpoint_complete" + progress_template: "完成：{checkpoint_description}" + + # finishing-a-development-branch 技能集成 + finishing-a-development-branch: + # 完成前的操作 + actions: + - type: status + always: true + - type: update + target: "task" + status: "已完成" + - type: archive + when: "merging_to_main" + + # 自动归档设置 + archive: + enabled: true + # 完成多少天后归档 + after_days: 30 + # 保持活跃的条件 + keep_active: + - type: task + status: ["进行中", "已阻塞"] + - type: bug + status: ["待修复", "调查中"] + + # 文档分类配置 + categories: + decision: + description: "重要的技术决策和选择" + required_fields: ["背景", "选项", "选择", "理由"] + task: + description: "开发任务和实施计划" + required_fields: ["目标", "步骤", "状态"] + bug: + description: "问题分析和修复过程" + required_fields: ["问题", "复现", "分析", "修复"] + context: + description: "项目背景和知识" + required_fields: ["概述", "细节"] + +# ============================================ +# 测试配置 +# ============================================ +testing: + # 是否强制测试通过才能完成 + required: true + + # 测试命令（根据项目类型选择） + commands: + npm: "npm test" + python: "pytest" + rust: "cargo test" + go: "go test ./..." + + # 自动检测测试命令 + auto_detect: true + +# ============================================ +# Git 配置 +# ============================================ +git: + # 主分支名称 + main_branch: "main" + + # 是否使用 worktree + use_worktrees: true # team 模式自动启用 + + # worktree 存放位置 + worktree_base: ".git-worktrees" + + # 提交前是否运行测试 + test_before_commit: true + +# ============================================ +# 技能覆盖配置 +# ============================================ +# 可以禁用特定技能或修改行为 +skills: + # 强制使用的技能 + required: + - "brainstorming" + - "writing-plans" + - "test-driven-development" + + # 可选技能 + optional: + - "subagent-driven-development" + - "document-driven-bridge" + + # 禁用的技能 + disabled: [] + +# ============================================ +# 通知配置 +# ============================================ +notifications: + # 完成时显示摘要 + show_summary: true + + # 文档创建时通知 + document_created: true + + # 任务状态变更时通知 + status_changed: true + +# ============================================ +# 高级配置 +# ============================================ +advanced: + # 是否在会话开始时显示配置 + announce_config: true + + # 是否记录详细的技能调用 + log_invocations: false + + # 配置文件版本检查 + version_check: true diff --git a/README.md b/README.md index 0e67aefcf..cdb1d5ffb 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,67 @@ +# HorsPowers! + +Just kidding :p + +A custom version based on Superpowers, just a rookie stand on the shoulders of giants. + +## What's different + +I'm a single developer, sometimes, off the work, e.g. + +So, as a lazy dog(Chinese slang), TDD? worktree? nuh, I dont need thoes heavy machine gun. + +I just add a "Personal/Single Mode" for the superpower skills, origin for team work, new mode for me. +- change the strategy in ./.superpowers-config.yaml + - braches strategy support regular branch strategy + - test strategy support test-after, code first + - push-merge strategy support pr or local merge + +## Use With My Document-Driven Skill + +This version includes integration with [document-driven-ai-workflow](https://github.com/LouisHors/document-driven-ai-workflow) - a documentation system that enables AI to maintain project context across sessions. + +### Quick Links + +**English:** +- **[📖 Integration Guide](docs/document-driven-integration-guide-en.md)** - Complete integration documentation +- **[🚀 Quick Start](docs/document-driven-quickstart-en.md)** - Get started in 5 minutes +- **[🔧 Bridge Skill](skills/document-driven-bridge/SKILL.md)** - Core integration skill + +**中文:** +- **[📖 集成指南](docs/document-driven-integration-guide.md)** - 完整的集成文档 +- **[🚀 快速开始](docs/document-driven-quickstart.md)** - 5 分钟上手指南 + +### What It Does + +Automatically creates and updates documentation at key workflow points: + +- **brainstorming** → Records technical decisions +- **writing-plans** → Creates task tracking documents +- **test-driven-development** → Logs bugs and fixes +- **finishing-a-development-branch** → Archives completed work + +### Setup + +1. Clone the workflow: `git clone https://github.com/LouisHors/document-driven-ai-workflow.git` +2. Copy config template: `cp .superpowers-config.template.yaml .superpowers-config.yaml` +3. Set `documentation.enabled: true` and configure `cli_path` +4. Initialize: `node /path/to/document-driven-ai-workflow/cli.js init` + +See [Quick Start](docs/document-driven-quickstart.md) for detailed instructions. + +--- + # Superpowers Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable "skills" and some initial instructions that make sure your agent uses them. ## How it works -It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it *doesn't* just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do. +It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it *doesn't* just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do. -Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest. +Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest. -After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. +After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together. @@ -19,7 +72,7 @@ There's a bunch more to it, but that's the core of the system. And because the s If Superpowers has helped you do stuff that makes money and you are so inclined, I'd greatly appreciate it if you'd consider [sponsoring my opensource work](https://github.com/sponsors/obra). -Thanks! +Thanks! - Jesse @@ -106,7 +159,7 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp - **systematic-debugging** - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques) - **verification-before-completion** - Ensure it's actually fixed -**Collaboration** +**Collaboration** - **brainstorming** - Socratic design refinement - **writing-plans** - Detailed implementation plans - **executing-plans** - Batch execution with checkpoints diff --git a/docs/document-driven-integration-guide-en.md b/docs/document-driven-integration-guide-en.md new file mode 100644 index 000000000..8a7484a61 --- /dev/null +++ b/docs/document-driven-integration-guide-en.md @@ -0,0 +1,412 @@ +# Document-Driven AI Workflow Integration Guide + +This document demonstrates how to integrate `document-driven-ai-workflow` into superpowers skills, enabling automatic document generation at key workflow operations. + +## 🎯 Integration Overview + +``` +superpowers skills (workflow orchestration) + ↓ + Check configuration enabled + ↓ + Invoke bridge skill + ↓ +document-driven CLI commands + ↓ + Unified .docs/ directory +``` + +## 📋 Integration Points Design + +### 1. brainstorming Skill Integration + +**Integration Location:** After design is complete, before writing design document + +**Add code** (in `brainstorming/SKILL.md` around line 37): + +```markdown +## After the Design + +**Documentation Integration:** + +IF `.superpowers-config.yaml` exists AND `documentation.enabled: true`: + **REQUIRED SUB-SKILL:** Use superpowers:document-driven-bridge + Run `$DOCS_CLI search "related design decisions"` to check for existing decisions + Run `$DOCS_CLI create decision "design topic"` to capture technical decisions + Update context if new architectural patterns discovered + +**Documentation (original):** +- Write the validated design to `docs/plans/YYYY-MM-DD--design.md` +... +``` + +**Effects:** +- ✅ Automatically record technical decisions +- ✅ Search related decisions to avoid duplication +- ✅ Build project knowledge base + +### 2. writing-plans Skill Integration + +**Integration Location:** After plan creation is complete + +**Add code** (in `writing-plans/SKILL.md` around line 100): + +```markdown +## Execution Handoff + +**Documentation Integration:** + +IF `.superpowers-config.yaml` exists AND `documentation.enabled: true`: + **REQUIRED SUB-SKILL:** Use superpowers:document-driven-bridge + + **Create task document:** + ```bash + $DOCS_CLI create task "Implement: [feature-name]" + ``` + + Store the returned document path as `$TASK_DOC` for progress tracking. + +**Original execution handoff:** +After saving the plan, offer execution choice: +... +``` + +**Effects:** +- ✅ Automatically create task tracking document +- ✅ Update task status later +- ✅ Form complete task history + +### 3. test-driven-development Skill Integration + +**Integration Location:** When test fails and debugging is needed + +**Add code** (in `test-driven-development/SKILL.md` RED phase): + +```markdown +## RED: Write a Failing Test + +**Documentation Integration:** + +IF test fails unexpectedly (not first run): + Use superpowers:document-driven-bridge + Run `$DOCS_CLI create bug "Test failure: [test-name]"` to document investigation + +**Original RED step:** +1. Write one test that fails +... +``` + +**Integration Location:** When bug fix is complete + +```markdown +## GREEN: Make the Test Pass + +**Documentation Integration:** + +IF `$BUG_DOC` is set (from RED phase): + Run `$DOCS_CLI update "$BUG_DOC" "status:fixed" "progress:[fix-description]"` + +**Original GREEN step:** +1. Write the minimal code to make the test pass +... +``` + +**Effects:** +- ✅ Automatically document bug investigation process +- ✅ Build bug knowledge base +- ✅ Traceable fix history + +### 4. finishing-a-development-branch Skill Integration + +**Integration Location:** After tests pass, before presenting options + +**Add code** (in `finishing-a-development-branch/SKILL.md` around line 39): + +```markdown +**If tests pass:** + +**Documentation Integration:** + +IF `.superpowers-config.yaml` exists AND `documentation.enabled: true`: + **REQUIRED SUB-SKILL:** Use superpowers:document-driven-bridge + + **Check project status:** + ```bash + $DOCS_CLI status + ``` + + **Archive completed documents:** + ```bash + # Archive completed tasks and bugs + find .docs/active -name "*.md" -exec grep -l "status:completed" {} \; | \ + xargs -I {} mv {} .docs/archive/ + ``` + + **Update task document:** + IF `$TASK_DOC` is set: + Run `$DOCS_CLI update "$TASK_DOC" "status:completed" "progress:Implementation complete, ready to merge"` + +Continue to Step 2. +``` + +**Effects:** +- ✅ Check project status before completion +- ✅ Auto-archive completed documents +- ✅ Update final task status + +## 🔧 Configuration File Example + +### Complete `.superpowers-config.yaml` + +```yaml +# Superpowers Project Configuration +version: "1.0" + +# Development mode: personal | team +development_mode: team + +# Completion strategy: merge | pr | keep +completion_strategy: pr + +# Document-driven workflow integration +documentation: + enabled: true + + # CLI tool path (adjust according to actual installation location) + cli_path: "node /path/to/document-driven-ai-workflow/cli.js" + # If globally installed: cli_path: "docs" + + # Workflow integration configuration + workflows: + brainstorming: + # Search before starting + pre_search: + - "project architecture" + - "related decisions" + # Create after completion + create: + - type: decision + when: "technical_decisions_made" + template: "Technical decision record" + + writing-plans: + # Search before starting + pre_search: + - "related features" + - "similar tasks" + # Create after completion + create: + - type: task + always: true + template: "Implementation task" + + test-driven-development: + # When test fails + create: + - type: bug + when: "test_fails_unexpectedly" + template: "Bug analysis" + # When fix is complete + update: + - type: bug + when: "bug_fixed" + status: "fixed" + + finishing-a-development-branch: + # Operations before completion + actions: + - type: status + always: true + - type: archive + when: "merging_to_main" + - type: update + target: "task" + status: "completed" + + # Auto-archiving settings + archive: + enabled: true + after_days: 30 + keep_active: + - type: task + status: ["in_progress", "blocked"] + - type: bug + status: ["pending", "investigating"] + + # Document categories + categories: + decision: + directory: ".docs/active" + archive_after: "merged" + task: + directory: ".docs/active" + archive_after: "completed" + bug: + directory: ".docs/active" + archive_after: "fixed" + context: + directory: ".docs/context" + archive_after: "never" +``` + +## 🚀 Quick Start + +### Step 1: Install document-driven-ai-workflow + +```bash +# Clone repository +git clone https://github.com/LouisHors/document-driven-ai-workflow.git +cd document-driven-ai-workflow + +# Verify CLI tool +node cli.js --help +``` + +### Step 2: Create Project Configuration + +```bash +# In your project root directory +cat > .superpowers-config.yaml << 'EOF' +documentation: + enabled: true + cli_path: "node /path/to/document-driven-ai-workflow/cli.js" +EOF +``` + +### Step 3: Initialize Documentation Directory + +```bash +# Run initialization +node /path/to/document-driven-ai-workflow/cli.js init + +# Create initial context +node /path/to/document-driven-ai-workflow/cli.js create context "Project Overview" +``` + +### Step 4: Start Using + +Now when you use superpowers skills, documents will be automatically created and updated: + +```bash +# Example workflow +claude "Help me design a user management feature" +# → brainstorming skill runs +# → Automatically creates decision document + +claude "Help me write implementation plan" +# → writing-plans skill runs +# → Automatically creates task document + +claude "Start implementation" +# → subagent-driven-development skill runs +# → Automatically updates task progress + +claude "Done" +# → finishing-a-development-branch skill runs +# → Automatically checks status and archives documents +``` + +## 📊 Integration Effect Comparison + +### Traditional superpowers Workflow + +``` +brainstorming → Design document (one-time) + ↓ +writing-plans → Implementation plan (one-time) + ↓ +implementation → Code implementation + ↓ +finishing → Merge/PR +``` + +**Problems:** +- ❌ Documents scattered in `docs/plans/` directory +- ❌ Cannot track task status changes +- ❌ Cannot get context across sessions +- ❌ Missing decision and bug records + +### After Document-Driven Workflow Integration + +``` +brainstorming → Search context → Create decision document + ↓ +writing-plans → Search related tasks → Create task document + ↓ +implementation → Update task progress → Create bug document (if any) + ↓ +finishing → Check status → Archive documents → Update final status +``` + +**Advantages:** +- ✅ Unified `.docs/` directory structure +- ✅ Complete task status history +- ✅ Cross-session context memory +- ✅ Comprehensive decision and bug knowledge base + +## 🎯 Best Practices + +### 1. Configuration Management + +- **Personal projects**: Use `development_mode: personal`, simplify documentation workflow +- **Team projects**: Use `development_mode: team`, enable complete documentation tracking +- **Temporary experiments**: Set `documentation.enabled: false` to skip document generation + +### 2. Document Maintenance + +- **Regular archiving**: Auto-archive when using `finishing-a-development-branch` +- **Context first**: Create more `context` documents in early project stages +- **Decision recording**: Record all important technical choices as `decision` documents + +### 3. Search Strategy + +- **Search before starting**: Use `docs:search` to understand existing work +- **Avoid duplication**: Search before creating new documents +- **Association finding**: Search related documents by keywords + +## 🔍 Troubleshooting + +### CLI Command Not Found + +**Symptom**: `command not found` error + +**Solution**: +```yaml +# Use absolute path +documentation: + cli_path: "/full/path/to/document-driven-ai-workflow/cli.js" +``` + +### Documents Not Created + +**Symptom**: Integration points are skipped + +**Check**: +1. Confirm `documentation.enabled: true` +2. Confirm `.superpowers-config.yaml` is in project root directory +3. Check if integration code is correctly added in skills + +### Cannot Find Previously Created Documents + +**Solution**: +```bash +# Run status check +node cli.js status + +# Search documents +node cli.js search "keyword" +``` + +## 📚 Related Resources + +- **[document-driven-bridge skill](../skills/document-driven-bridge/SKILL.md)** - Bridge skill documentation +- **[document-driven-ai-workflow](https://github.com/LouisHors/document-driven-ai-workflow)** - Original repository +- **[superpowers skills system](../README.md)** - Superpowers main documentation + +## 🤝 Contributing + +Contributions and issue feedback are welcome! + +--- + +**Make AI your long-term project partner!** 🚀 diff --git a/docs/document-driven-integration-guide.md b/docs/document-driven-integration-guide.md new file mode 100644 index 000000000..b858b236e --- /dev/null +++ b/docs/document-driven-integration-guide.md @@ -0,0 +1,412 @@ +# Document-Driven AI Workflow Integration Guide + +本文档展示如何在 superpowers 技能中集成 `document-driven-ai-workflow`，实现关键操作的自动文档生成。 + +## 🎯 集成概览 + +``` +superpowers 技能 (流程编排) + ↓ + 检测配置启用 + ↓ + 调用桥梁技能 + ↓ +document-driven CLI 命令 + ↓ + 统一的 .docs/ 目录 +``` + +## 📋 集成点设计 + +### 1. brainstorming 技能集成 + +**集成位置**：设计完成后，写入设计文档之前 + +**添加代码** (在 `brainstorming/SKILL.md` 第 37 行附近)： + +```markdown +## After the Design + +**Documentation Integration:** + +IF `.superpowers-config.yaml` exists AND `documentation.enabled: true`: + **REQUIRED SUB-SKILL:** Use superpowers:document-driven-bridge + Run `$DOCS_CLI search "相关设计决策"` to check for existing decisions + Run `$DOCS_CLI create decision "设计主题"` to capture technical decisions + Update context if new architectural patterns discovered + +**Documentation (original):** +- Write the validated design to `docs/plans/YYYY-MM-DD--design.md` +... +``` + +**效果**： +- ✅ 自动记录技术决策 +- ✅ 搜索相关决策避免重复 +- ✅ 建立项目知识库 + +### 2. writing-plans 技能集成 + +**集成位置**：计划创建完成后 + +**添加代码** (在 `writing-plans/SKILL.md` 第 100 行附近)： + +```markdown +## Execution Handoff + +**Documentation Integration:** + +IF `.superpowers-config.yaml` exists AND `documentation.enabled: true`: + **REQUIRED SUB-SKILL:** Use superpowers:document-driven-bridge + + **Create task document:** + ```bash + $DOCS_CLI create task "实现：[feature-name]" + ``` + + Store the returned document path as `$TASK_DOC` for progress tracking. + +**Original execution handoff:** +After saving the plan, offer execution choice: +... +``` + +**效果**： +- ✅ 自动创建任务跟踪文档 +- ✅ 后续可更新任务状态 +- ✅ 形成完整的任务历史 + +### 3. test-driven-development 技能集成 + +**集成位置**：测试失败需要调试时 + +**添加代码** (在 `test-driven-development/SKILL.md` RED 阶段)： + +```markdown +## RED: Write a Failing Test + +**Documentation Integration:** + +IF test fails unexpectedly (not first run): + Use superpowers:document-driven-bridge + Run `$DOCS_CLI create bug "测试失败：[test-name]"` to document investigation + +**Original RED step:** +1. Write one test that fails +... +``` + +**集成位置**：Bug 修复完成时 + +```markdown +## GREEN: Make the Test Pass + +**Documentation Integration:** + +IF `$BUG_DOC` is set (from RED phase): + Run `$DOCS_CLI update "$BUG_DOC" "status:已修复" "progress:[fix-description]"` + +**Original GREEN step:** +1. Write the minimal code to make the test pass +... +``` + +**效果**： +- ✅ 自动记录 Bug 调查过程 +- ✅ 建立 Bug 知识库 +- ✅ 可追溯的修复历史 + +### 4. finishing-a-development-branch 技能集成 + +**集成位置**：测试通过后，呈现选项前 + +**添加代码** (在 `finishing-a-development-branch/SKILL.md` 第 39 行附近)： + +```markdown +**If tests pass:** + +**Documentation Integration:** + +IF `.superpowers-config.yaml` exists AND `documentation.enabled: true`: + **REQUIRED SUB-SKILL:** Use superpowers:document-driven-bridge + + **Check project status:** + ```bash + $DOCS_CLI status + ``` + + **Archive completed documents:** + ```bash + # Archive completed tasks and bugs + find .docs/active -name "*.md" -exec grep -l "status:已完成" {} \; | \ + xargs -I {} mv {} .docs/archive/ + ``` + + **Update task document:** + IF `$TASK_DOC` is set: + Run `$DOCS_CLI update "$TASK_DOC" "status:已完成" "progress:代码已完成，准备合并"` + +Continue to Step 2. +``` + +**效果**： +- ✅ 完成前查看项目状态 +- ✅ 自动归档已完成文档 +- ✅ 更新任务最终状态 + +## 🔧 配置文件示例 + +### 完整的 `.superpowers-config.yaml` + +```yaml +# Superpowers 项目配置 +version: "1.0" + +# 开发模式：personal | team +development_mode: team + +# 完成策略：merge | pr | keep +completion_strategy: pr + +# 文档驱动工作流集成 +documentation: + enabled: true + + # CLI 工具路径（根据实际安装位置调整） + cli_path: "node /path/to/document-driven-ai-workflow/cli.js" + # 如果全局安装：cli_path: "docs" + + # 工作流集成配置 + workflows: + brainstorming: + # 开始前搜索 + pre_search: + - "项目架构" + - "相关决策" + # 完成后创建 + create: + - type: decision + when: "technical_decisions_made" + template: "技术决策记录" + + writing-plans: + # 开始前搜索 + pre_search: + - "相关功能" + - "类似任务" + # 完成后创建 + create: + - type: task + always: true + template: "实现任务" + + test-driven-development: + # 测试失败时 + create: + - type: bug + when: "test_fails_unexpectedly" + template: "Bug 分析" + # 修复完成时 + update: + - type: bug + when: "bug_fixed" + status: "已修复" + + finishing-a-development-branch: + # 完成前的操作 + actions: + - type: status + always: true + - type: archive + when: "merging_to_main" + - type: update + target: "task" + status: "已完成" + + # 自动归档设置 + archive: + enabled: true + after_days: 30 + keep_active: + - type: task + status: ["进行中", "已阻塞"] + - type: bug + status: ["待修复", "进行中"] + + # 文档分类 + categories: + decision: + directory: ".docs/active" + archive_after: "merged" + task: + directory: ".docs/active" + archive_after: "completed" + bug: + directory: ".docs/active" + archive_after: "fixed" + context: + directory: ".docs/context" + archive_after: "never" +``` + +## 🚀 快速开始 + +### 步骤 1：安装 document-driven-ai-workflow + +```bash +# 克隆仓库 +git clone https://github.com/LouisHors/document-driven-ai-workflow.git +cd document-driven-ai-workflow + +# 验证 CLI 工具 +node cli.js --help +``` + +### 步骤 2：创建项目配置 + +```bash +# 在你的项目根目录 +cat > .superpowers-config.yaml << 'EOF' +documentation: + enabled: true + cli_path: "node /path/to/document-driven-ai-workflow/cli.js" +EOF +``` + +### 步骤 3：初始化文档目录 + +```bash +# 运行初始化 +node /path/to/document-driven-ai-workflow/cli.js init + +# 创建初始上下文 +node /path/to/document-driven-ai-workflow/cli.js create context "项目概览" +``` + +### 步骤 4：开始使用 + +现在当你使用 superpowers 技能时，文档会自动创建和更新： + +```bash +# 示例工作流 +claude "帮我设计一个用户管理功能" +# → brainstorming 技能运行 +# → 自动创建 decision 文档 + +claude "帮我写实现计划" +# → writing-plans 技能运行 +# → 自动创建 task 文档 + +claude "开始实现" +# → subagent-driven-development 技能运行 +# → 自动更新 task 进度 + +claude "完成了" +# → finishing-a-development-branch 技能运行 +# → 自动查看状态并归档文档 +``` + +## 📊 集成效果对比 + +### 传统 superpowers 工作流 + +``` +brainstorming → 设计文档 (一次性) + ↓ +writing-plans → 实施计划 (一次性) + ↓ +implementation → 代码实现 + ↓ +finishing → 合并/PR +``` + +**问题**： +- ❌ 文档分散在 `docs/plans/` 目录 +- ❌ 无法追溯任务状态变化 +- ❌ 跨会话无法获取上下文 +- ❌ 决策和 Bug 记录缺失 + +### 集成文档驱动工作流后 + +``` +brainstorming → 搜索上下文 → 创建 decision 文档 + ↓ +writing-plans → 搜索相关任务 → 创建 task 文档 + ↓ +implementation → 更新 task 进度 → 创建 bug 文档（如有） + ↓ +finishing → 查看状态 → 归档文档 → 更新最终状态 +``` + +**优势**： +- ✅ 统一的 `.docs/` 目录结构 +- ✅ 完整的任务状态历史 +- ✅ 跨会话的上下文记忆 +- ✅ 全面的决策和 Bug 知识库 + +## 🎯 最佳实践 + +### 1. 配置管理 + +- **个人项目**：使用 `development_mode: personal`，简化文档流程 +- **团队项目**：使用 `development_mode: team`，启用完整文档跟踪 +- **临时实验**：设置 `documentation.enabled: false` 跳过文档生成 + +### 2. 文档维护 + +- **定期归档**：使用 `finishing-a-development-branch` 时自动归档 +- **上下文优先**：项目初期多创建 `context` 文档 +- **决策记录**：重要的技术选择都要记录 `decision` 文档 + +### 3. 搜索策略 + +- **开始前搜索**：使用 `docs:search` 了解现有工作 +- **避免重复**：搜索后再创建新文档 +- **关联查找**：按关键词搜索相关文档 + +## 🔍 故障排查 + +### CLI 命令找不到 + +**症状**：`command not found` 错误 + +**解决方案**： +```yaml +# 使用绝对路径 +documentation: + cli_path: "/full/path/to/document-driven-ai-workflow/cli.js" +``` + +### 文档未创建 + +**症状**：集成点被跳过 + +**检查**： +1. 确认 `documentation.enabled: true` +2. 确认 `.superpowers-config.yaml` 在项目根目录 +3. 检查技能中是否正确添加了集成代码 + +### 无法找到之前创建的文档 + +**解决方案**： +```bash +# 运行状态查看 +node cli.js status + +# 搜索文档 +node cli.js search "关键词" +``` + +## 📚 相关资源 + +- **[document-driven-bridge 技能](../skills/document-driven-bridge/SKILL.md)** - 桥梁技能文档 +- **[document-driven-ai-workflow](https://github.com/LouisHors/document-driven-ai-workflow)** - 原始仓库 +- **[superpowers 技能系统](../README.md)** - Superpowers 主文档 + +## 🤝 贡献 + +欢迎提交改进建议和问题反馈！ + +--- + +**让 AI 成为你的项目长期合作伙伴！** 🚀 diff --git a/docs/document-driven-quickstart-en.md b/docs/document-driven-quickstart-en.md new file mode 100644 index 000000000..300527598 --- /dev/null +++ b/docs/document-driven-quickstart-en.md @@ -0,0 +1,309 @@ +# Document-Driven Workflow Integration - Quick Start + +Enable document-driven AI workflow for superpowers in 5 minutes. + +## 🎯 Goal + +Automatically trigger document generation at key superpowers operation steps, building cross-session AI context memory. + +## 📋 Prerequisites + +- ✅ Superpowers installed (current directory) +- ✅ Node.js 16+ environment +- ✅ A project needing AI collaboration + +## 🚀 Quick Start (3 Steps) + +### Step 1: Install document-driven-ai-workflow + +```bash +# 1. Clone repository (recommended in parent directory) +cd /path/to/parent +git clone https://github.com/LouisHors/document-driven-ai-workflow.git + +# 2. Verify installation +cd document-driven-ai-workflow +node cli.js --help + +# 3. Test CLI +node cli.js init +``` + +**Expected output:** +``` +✓ Created .docs/active +✓ Created .docs/context +✓ Created .docs/templates +✓ Created .docs/archive +Documentation structure initialized! +``` + +### Step 2: Configure Your Project + +```bash +# 1. Enter your project directory +cd /path/to/your/project + +# 2. Copy configuration template +cp /path/to/horspowers/.superpowers-config.template.yaml .superpowers-config.yaml + +# 3. Edit configuration file +nano .superpowers-config.yaml # or use your preferred editor +``` + +**Minimum configuration** (only need to modify these two lines): + +```yaml +# Enable documentation integration +documentation: + enabled: true + # Modify to actual CLI path + cli_path: "node /absolute/path/to/document-driven-ai-workflow/cli.js" +``` + +**Full path example:** + +```yaml +documentation: + enabled: true + # Mac/Linux example + cli_path: "node /Users/username/document-driven-ai-workflow/cli.js" + # Windows example + # cli_path: "node C:\\Users\\username\\document-driven-ai-workflow\\cli.js" +``` + +### Step 3: Initialize Project Documentation + +```bash +# 1. Initialize documentation structure +node /path/to/document-driven-ai-workflow/cli.js init + +# 2. Create project context (optional but recommended) +node /path/to/document-driven-ai-workflow/cli.js create context "Project Overview" +node /path/to/document-driven-ai-workflow/cli.js create context "Tech Stack" +node /path/to/document-driven-ai-workflow/cli.js create context "Development Standards" + +# 3. Check status +node /path/to/document-driven-ai-workflow/cli.js status +``` + +**Done!** 🎉 + +Your project is now configured with document-driven workflow. + +## ✅ Verify Integration + +Create a test session to verify integration works: + +```bash +cd /path/to/your/project +claude +``` + +In Claude Code, enter: + +``` +I need to add a user login feature, help me design it +``` + +**Expected behavior:** + +1. **brainstorming skill starts** +2. **Auto search**: `docs:search "project architecture"` +3. **Design discussion** +4. **Auto create**: `docs:create decision "Technical decision: User authentication scheme"` +5. **Save design document** + +Continue with: + +``` +Help me write implementation plan +``` + +**Expected behavior:** + +1. **writing-plans skill starts** +2. **Auto search**: `docs:search "related features"` +3. **Create implementation plan** +4. **Auto create**: `docs:create task "Implement: User login feature"` + +## 📊 Effect Comparison + +### Before Integration + +``` +You: Help me add user login feature +AI: OK, let me start designing... +[Design process] +AI: Design complete, saved to docs/plans/2025-01-07-login-design.md + +[A few hours later, new session] +You: Continue the previous login feature +AI: What login feature? Let me re-read the documents... +``` + +### After Integration + +``` +You: Help me add user login feature +AI: Searching project context... + ✓ Found 3 related documents + ✓ Project architecture: React + Node.js + ✓ Technical decision: Use JWT authentication +AI: Based on project background, I suggest... +[Design process] +AI: Create decision document: .docs/active/2025-01-07-decision-login-auth-scheme.md +AI: Create task document: .docs/active/2025-01-07-task-user-login-feature.md + +[A few hours later, new session] +You: Continue the previous login feature +AI: Searching related tasks... + ✓ Found active task: User login feature (status: in_progress) + ✓ Current progress: Completed basic components +AI: I understand the situation. Last time we completed basic components, now continuing... +``` + +## 🎯 Common Commands + +### Project Management + +```bash +# View all active documents +docs:status + +# Search related documents +docs:search "login" + +# Create new document +docs:create context "New context" +docs:create task "New task" +docs:create decision "Technical decision" +docs:create bug "Bug description" +``` + +### Task Tracking + +```bash +# Update task status +docs:update ".docs/active/TaskDocument.md" "status:in_progress" "progress:Complete component development" + +# Mark as complete +docs:update ".docs/active/TaskDocument.md" "status:completed" +``` + +## 🔧 Custom Configuration + +### Personal Project (Simplified Mode) + +```yaml +development_mode: personal +completion_strategy: merge + +documentation: + enabled: true + cli_path: "node /path/to/cli.js" + workflows: + finishing-a-development-branch: + actions: + - type: update # Only update status, don't create PR +``` + +### Team Project (Full Mode) + +```yaml +development_mode: team +completion_strategy: pr + +documentation: + enabled: true + cli_path: "node /path/to/cli.js" + workflows: + brainstorming: + create: + - type: decision + when: "technical_decisions_made" + writing-plans: + create: + - type: task + always: true + test-driven-development: + create: + - type: bug + when: "test_fails" + finishing-a-development-branch: + actions: + - type: status + - type: archive +``` + +### Temporary Experiment (Disable Documentation) + +```yaml +documentation: + enabled: false # Temporarily disable document generation +``` + +## ❓ Frequently Asked Questions + +### Q: CLI path always reports error not found + +**A:** Use absolute path instead of relative path: + +```yaml +# ❌ Not recommended +cli_path: "node ../document-driven-ai-workflow/cli.js" + +# ✅ Recommended +cli_path: "node /Users/username/document-driven-ai-workflow/cli.js" +``` + +### Q: Where are documents created? + +**A:** In the `.docs/` folder in project root: + +``` +your-project/ +├── .docs/ +│ ├── active/ # Active tasks, bugs, decisions +│ ├── context/ # Project context documents +│ ├── templates/ # Document templates +│ └── archive/ # Completed documents +├── .superpowers-config.yaml +└── ... +``` + +### Q: Will it create too many documents? + +**A:** Depends on your usage frequency. Recommendations: + +1. **Only record important decisions** - Not all designs need decision documents +2. **Archive regularly** - Use `finishing-a-development-branch` to auto-archive +3. **Enable as needed** - Temporary work can set `documentation.enabled: false` + +### Q: How to disable documentation for a specific workflow? + +**A:** Remove the corresponding workflow configuration in config file: + +```yaml +workflows: + # Remove test-driven-development config to disable + brainstorming: + create: + - type: decision +``` + +## 📚 Next Steps + +- 📖 Read [Complete Integration Guide](document-driven-integration-guide-en.md) +- 🔧 View [Bridge Skill Documentation](../skills/document-driven-bridge/SKILL.md) +- 🎮 Try [Example Projects](../examples/) + +## 🆘 Need Help? + +1. **Check configuration**: Run `docs:status` to verify CLI tool is available +2. **View logs**: Skill invocations display executed commands +3. **Read documentation**: [Complete documentation](document-driven-integration-guide-en.md) + +--- + +**Start enjoying cross-session AI memory!** 🚀 diff --git a/docs/document-driven-quickstart.md b/docs/document-driven-quickstart.md new file mode 100644 index 000000000..4f003db5c --- /dev/null +++ b/docs/document-driven-quickstart.md @@ -0,0 +1,309 @@ +# 文档驱动工作流集成 - 快速开始 + +5 分钟内为 superpowers 启用文档驱动 AI 工作流。 + +## 🎯 目标 + +在 superpowers 的关键操作步骤中自动触发文档生成，建立跨会话的 AI 上下文记忆。 + +## 📋 前置要求 + +- ✅ 已安装 superpowers（当前目录） +- ✅ Node.js 16+ 环境 +- ✅ 一个需要 AI 协作的项目 + +## 🚀 快速开始（3 步） + +### 步骤 1：安装 document-driven-ai-workflow + +```bash +# 1. 克隆仓库（建议放在父目录） +cd /path/to/parent +git clone https://github.com/LouisHors/document-driven-ai-workflow.git + +# 2. 验证安装 +cd document-driven-ai-workflow +node cli.js --help + +# 3. 测试 CLI +node cli.js init +``` + +**预期输出**： +``` +✓ Created .docs/active +✓ Created .docs/context +✓ Created .docs/templates +✓ Created .docs/archive +Documentation structure initialized! +``` + +### 步骤 2：配置你的项目 + +```bash +# 1. 进入你的项目目录 +cd /path/to/your/project + +# 2. 复制配置模板 +cp /path/to/horspowers/.superpowers-config.template.yaml .superpowers-config.yaml + +# 3. 编辑配置文件 +nano .superpowers-config.yaml # 或使用你喜欢的编辑器 +``` + +**最小配置**（只需修改这两行）： + +```yaml +# 启用文档集成 +documentation: + enabled: true + # 修改为实际的 CLI 路径 + cli_path: "node /absolute/path/to/document-driven-ai-workflow/cli.js" +``` + +**完整路径示例**： + +```yaml +documentation: + enabled: true + # Mac/Linux 示例 + cli_path: "node /Users/username/document-driven-ai-workflow/cli.js" + # Windows 示例 + # cli_path: "node C:\\Users\\username\\document-driven-ai-workflow\\cli.js" +``` + +### 步骤 3：初始化项目文档 + +```bash +# 1. 初始化文档结构 +node /path/to/document-driven-ai-workflow/cli.js init + +# 2. 创建项目上下文（可选但推荐） +node /path/to/document-driven-ai-workflow/cli.js create context "项目概览" +node /path/to/document-driven-ai-workflow/cli.js create context "技术架构" +node /path/to/document-driven-ai-workflow/cli.js create context "开发规范" + +# 3. 查看状态 +node /path/to/document-driven-ai-workflow/cli.js status +``` + +**完成！** 🎉 + +现在你的项目已经配置好文档驱动工作流。 + +## ✅ 验证集成 + +创建一个测试会话来验证集成是否工作： + +```bash +cd /path/to/your/project +claude +``` + +在 Claude Code 中输入： + +``` +我需要添加一个用户登录功能，帮我设计一下 +``` + +**预期行为**： + +1. **brainstorming 技能启动** +2. **自动搜索**：`docs:search "项目架构"` +3. **设计讨论** +4. **自动创建**：`docs:create decision "技术决策：用户认证方案"` +5. **保存设计文档** + +继续输入： + +``` +帮我写实现计划 +``` + +**预期行为**： + +1. **writing-plans 技能启动** +2. **自动搜索**：`docs:search "相关功能"` +3. **创建实施计划** +4. **自动创建**：`docs:create task "实现：用户登录功能"` + +## 📊 效果对比 + +### 集成前 + +``` +你：帮我添加用户登录功能 +AI：好的，让我开始设计... +[设计过程] +AI：设计完成，保存到 docs/plans/2025-01-07-login-design.md + +[几小时后，新会话] +你：继续之前的登录功能 +AI：什么登录功能？让我重新看一下文档... +``` + +### 集成后 + +``` +你：帮我添加用户登录功能 +AI：正在搜索项目上下文... + ✓ 找到 3 个相关文档 + ✓ 项目架构：React + Node.js + ✓ 技术决策：使用 JWT 认证 +AI：基于项目背景，我建议以下方案... +[设计过程] +AI：创建决策文档：.docs/active/2025-01-07-decision-登录认证方案.md +AI：创建任务文档：.docs/active/2025-01-07-task-用户登录功能.md + +[几小时后，新会话] +你：继续之前的登录功能 +AI：正在搜索相关任务... + ✓ 找到活跃任务：用户登录功能（状态：进行中） + ✓ 当前进度：完成基础组件 +AI：我了解情况了，上次我们完成了基础组件，现在继续... +``` + +## 🎯 常用命令 + +### 项目管理 + +```bash +# 查看所有活跃文档 +docs:status + +# 搜索相关文档 +docs:search "登录" + +# 创建新文档 +docs:create context "新的上下文" +docs:create task "新任务" +docs:create decision "技术决策" +docs:create bug "Bug 描述" +``` + +### 任务跟踪 + +```bash +# 更新任务状态 +docs:update ".docs/active/任务文档.md" "status:进行中" "progress:完成组件开发" + +# 标记完成 +docs:update ".docs/active/任务文档.md" "status:已完成" +``` + +## 🔧 自定义配置 + +### 个人项目（简化模式） + +```yaml +development_mode: personal +completion_strategy: merge + +documentation: + enabled: true + cli_path: "node /path/to/cli.js" + workflows: + finishing-a-development-branch: + actions: + - type: update # 只更新状态，不创建 PR +``` + +### 团队项目（完整模式） + +```yaml +development_mode: team +completion_strategy: pr + +documentation: + enabled: true + cli_path: "node /path/to/cli.js" + workflows: + brainstorming: + create: + - type: decision + when: "technical_decisions_made" + writing-plans: + create: + - type: task + always: true + test-driven-development: + create: + - type: bug + when: "test_fails" + finishing-a-development-branch: + actions: + - type: status + - type: archive +``` + +### 临时实验（禁用文档） + +```yaml +documentation: + enabled: false # 临时禁用文档生成 +``` + +## ❓ 常见问题 + +### Q: CLI 路径总是报错找不到 + +**A:** 使用绝对路径而不是相对路径： + +```yaml +# ❌ 不推荐 +cli_path: "node ../document-driven-ai-workflow/cli.js" + +# ✅ 推荐 +cli_path: "node /Users/username/document-driven-ai-workflow/cli.js" +``` + +### Q: 文档创建在哪里？ + +**A:** 在项目根目录的 `.docs/` 文件夹： + +``` +your-project/ +├── .docs/ +│ ├── active/ # 活跃的任务、Bug、决策 +│ ├── context/ # 项目上下文文档 +│ ├── templates/ # 文档模板 +│ └── archive/ # 已完成的文档 +├── .superpowers-config.yaml +└── ... +``` + +### Q: 会产生太多文档吗？ + +**A:** 取决于你的使用频率。建议： + +1. **重要决策才记录** - 不是所有设计都需要 decision 文档 +2. **定期归档** - 使用 `finishing-a-development-branch` 自动归档 +3. **按需启用** - 临时工作可以设置 `documentation.enabled: false` + +### Q: 如何禁用某个工作流的文档？ + +**A:** 在配置文件中移除对应的 workflow 配置： + +```yaml +workflows: + # 移除 test-driven-development 配置即可禁用 + brainstorming: + create: + - type: decision +``` + +## 📚 下一步 + +- 📖 阅读 [完整集成指南](document-driven-integration-guide.md) +- 🔧 查看 [桥梁技能文档](../skills/document-driven-bridge/SKILL.md) +- 🎮 尝试 [示例项目](../examples/) + +## 🆘 需要帮助？ + +1. **检查配置**：运行 `docs:status` 验证 CLI 工具可用 +2. **查看日志**：技能调用时会显示执行的命令 +3. **阅读文档**：[完整文档](document-driven-integration-guide.md) + +--- + +**开始享受跨会话的 AI 记忆吧！** 🚀 diff --git a/skills/document-driven-bridge/SKILL.md b/skills/document-driven-bridge/SKILL.md new file mode 100644 index 000000000..9aefcf2ff --- /dev/null +++ b/skills/document-driven-bridge/SKILL.md @@ -0,0 +1,268 @@ +--- +name: document-driven-bridge +description: Use when document-driven-ai-workflow integration is enabled - Provides unified document management commands for superpowers workflows +--- + +# Document-Driven Bridge + +## Overview + +This skill bridges **superpowers** workflow skills with **document-driven-ai-workflow** CLI tool, enabling automatic document creation and management at key workflow points. + +## Prerequisites + +**REQUIRED:** The `document-driven-ai-workflow` skill must be installed and available. Check installation by running: + +```bash +# Check if docs command is available +which docs || node /path/to/document-driven-ai-workflow/cli.js --help +``` + +**Configuration Required:** `.superpowers-config.yaml` must have: + +```yaml +documentation: + enabled: true + cli_path: "node /path/to/document-driven-ai-workflow/cli.js" + # or if installed globally: + # cli_path: "docs" +``` + +## When This Skill Is Used + +This skill is **automatically invoked** by other superpowers skills when: + +1. **`brainstorming`** completes → Create/update context documents +2. **`writing-plans`** completes → Create task documents +3. **`test-driven-development`** finds bugs → Create bug documents +4. **`finishing-a-development-branch`** → Update project status and archive documents + +## The Bridge Commands + +### `docs:search "query"` + +Search existing documentation before starting any work. + +**Usage:** +```bash +# Before brainstorming +$DOCS_CLI search "project architecture" + +# Before writing plans +$DOCS_CLI search "related features" + +# Before debugging +$DOCS_CLI search "similar bugs" +``` + +**When to use:** ALWAYS search before creating new documents to avoid duplication. + +### `docs:create "title"` + +Create a new document with automatic timestamp. + +**Types:** `task`, `bug`, `decision`, `context` + +**Usage:** +```bash +# After brainstorming - capture design decisions +$DOCS_CLI create decision "Adopt React for frontend" + +# After writing-plans - track implementation tasks +$DOCS_CLI create task "Implement user authentication" + +# During TDD - record bugs for investigation +$DOCS_CLI create bug "Test failure in auth module" + +# During finishing - create context for future work +$DOCS_CLI create context "API integration patterns" +``` + +### `docs:update "status:value" "progress:note"` + +Update existing document status and progress. + +**Status values:** `待开始`, `进行中`, `已完成`, `已阻塞`, `已取消` + +**Usage:** +```bash +# Mark task as in progress +$DOCS_CLI update ".docs/active/2025-01-07-task-auth.md" "status:进行中" "progress:完成基础组件" + +# Mark bug as fixed +$DOCS_CLI update ".docs/active/2025-01-07-bug-auth-crash.md" "status:已修复" "progress:修复空指针问题" + +# Mark task as complete +$DOCS_CLI update ".docs/active/2025-01-07-task-auth.md" "status:已完成" +``` + +### `docs:status` + +View current project status including active tasks, bugs, and decisions. + +**Usage:** +```bash +# Before finishing development branch +$DOCS_CLI status + +# Output shows: +# - Active tasks with their status +# - Outstanding bugs +# - Recent decisions +# - Context documents available +``` + +## Integration Pattern + +### Standard Workflow Integration + +```mermaid +graph LR + A[Superpowers Skill] --> B{Docs Enabled?} + B -->|Yes| C[Invoke Bridge] + B -->|No| D[Skip Documentation] + C --> E[Search Existing Docs] + E --> F[Create New Document] + F --> G[Update Progress] + G --> H[Return to Skill] +``` + +### Example: brainstorming Integration + +**Step 1: Before Design** +```markdown +## Generate Design Options + +FIRST: Run `$DOCS_CLI search "project architecture"` to understand existing context. +``` + +**Step 2: After Design** +```markdown +## Capture Decisions + +IF design includes important technical choices: + Run `$DOCS_CLI create decision "Design decision title"` with rationale +``` + +### Example: writing-plans Integration + +**Step 1: Create Plan Document** +```markdown +## Create Implementation Task + +ALWAYS run: +```bash +$DOCS_CLI create task "Implement: [feature-name]" +``` + +This creates a timestamped task document that tracks: +- Implementation steps from this plan +- Progress updates during execution +- Completion status +``` + +**Step 2: Update During Execution** +```markdown +## Track Progress + +After each checkpoint: +```bash +$DOCS_CLI update "$TASK_DOC" "status:进行中" "progress:[checkpoint-description]" +``` + +## Configuration + +Create `.superpowers-config.yaml` in your project root: + +```yaml +# Superpowers Configuration +documentation: + enabled: true # Set to false to disable document integration + + # Path to document-driven-ai-workflow CLI + cli_path: "node /path/to/document-driven-ai-workflow/cli.js" + + # Document categories to create at each workflow point + workflows: + brainstorming: + create: + - type: decision + when: "technical_decisions_made" + - type: context + when: "new_context_needed" + + writing-plans: + create: + - type: task + always: true + + test-driven-development: + create: + - type: bug + when: "test_fails" + update: + - type: bug + when: "bug_fixed" + + finishing-a-development-branch: + actions: + - type: status + always: true + - type: archive + when: "merging_to_main" + + # Auto-archiving settings + archive: + enabled: true + after_days: 30 # Archive completed docs after 30 days + keep_active: + - type: task + status: ["进行中", "已阻塞"] +``` + +## Error Handling + +**If CLI not found:** +```bash +# Warn but continue +echo "⚠️ document-driven-ai-workflow CLI not found. Skipping documentation." +echo " Install from: https://github.com/LouisHors/document-driven-ai-workflow" +``` + +**If .docs not initialized:** +```bash +# Auto-initialize +$DOCS_CLI init +``` + +**If configuration missing:** +```bash +# Use defaults +echo "ℹ️ No .superpowers-config.yaml found. Using default documentation settings." +``` + +## Best Practices + +1. **Search Before Create**: Always run `docs:search` before creating new documents +2. **Update Frequently**: Keep documents current as work progresses +3. **Archive When Done**: Move completed documents to archive during finishing +4. **Context First**: Create context documents early in project lifecycle +5. **Decisions Matter**: Record all significant technical decisions + +## Troubleshooting + +**Problem**: Commands fail with "command not found" +**Solution**: Update `cli_path` in `.superpowers-config.yaml` to use full path + +**Problem**: Documents not being created +**Solution**: Check that `documentation.enabled: true` in config + +**Problem**: Can't find documents later +**Solution**: Use `docs:status` to see all active documents and their locations + +## See Also + +- **superpowers:brainstorming** - Design decisions captured here +- **superpowers:writing-plans** - Implementation tasks created here +- **superpowers:test-driven-development** - Bug tracking integrated here +- **superpowers:finishing-a-development-branch** - Final status check here From 6e1d4ed808a3c0ea82bd37fcece8f9cda11f1769 Mon Sep 17 00:00:00 2001 From: liuhao Date: Thu, 15 Jan 2026 16:47:35 +0800 Subject: [PATCH 10/99] =?UTF-8?q?feat(i18n):=20=E6=B7=BB=E5=8A=A0=E5=AE=8C?= =?UTF-8?q?=E6=95=B4=E7=9A=84=E4=B8=AD=E6=96=87=E6=94=AF=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 所有 14 个技能 description 支持中文触发场景 - 核心技能交互部分中文化（启动声明、用户选项） - README 添加中文介绍部分 - 创建任务规划文档（docs/tasks/） 修改的技能： - brainstorming, writing-plans, test-driven-development - systematic-debugging, finishing-a-development-branch - executing-plans, subagent-driven-development - using-git-worktrees, requesting-code-review - receiving-code-review, using-superpowers - dispatching-parallel-agents, verification-before-completion - writing-skills, document-driven-bridge Co-Authored-By: Claude --- README.md | 46 + ...21\345\270\203\346\224\271\351\200\240.md" | 297 ++++++ ...55\346\226\207\351\200\202\351\205\215.md" | 380 +++++++ ...5\267\245\344\275\234\346\265\201Skill.md" | 523 ++++++++++ ...76\350\256\241\346\226\207\346\241\243.md" | 950 ++++++++++++++++++ skills/brainstorming/SKILL.md | 4 +- skills/dispatching-parallel-agents/SKILL.md | 2 +- skills/document-driven-bridge/SKILL.md | 2 +- skills/executing-plans/SKILL.md | 4 +- .../finishing-a-development-branch/SKILL.md | 4 +- skills/receiving-code-review/SKILL.md | 2 +- skills/requesting-code-review/SKILL.md | 2 +- skills/subagent-driven-development/SKILL.md | 4 +- skills/systematic-debugging/SKILL.md | 4 +- skills/test-driven-development/SKILL.md | 4 +- skills/using-git-worktrees/SKILL.md | 2 +- skills/using-superpowers/SKILL.md | 2 +- .../verification-before-completion/SKILL.md | 2 +- skills/writing-plans/SKILL.md | 12 +- skills/writing-skills/SKILL.md | 2 +- 20 files changed, 2226 insertions(+), 22 deletions(-) create mode 100644 "docs/tasks/01-\351\241\271\347\233\256\345\217\221\345\270\203\346\224\271\351\200\240.md" create mode 100644 "docs/tasks/02-\345\205\250\351\235\242\344\270\255\346\226\207\351\200\202\351\205\215.md" create mode 100644 "docs/tasks/03-\350\207\252\345\212\250\345\214\226\345\274\200\345\217\221\345\267\245\344\275\234\346\265\201Skill.md" create mode 100644 "docs/\350\207\252\345\212\250\345\214\226\345\274\200\345\217\221\345\267\245\344\275\234\346\265\201\350\256\276\350\256\241\346\226\207\346\241\243.md" diff --git a/README.md b/README.md index cdb1d5ffb..5548c44f0 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,51 @@ # HorsPowers! +> **中文支持** | 本项目提供完整的中文支持，所有技能均支持中文触发。 + +--- + +## 🇨🇳 中文介绍 + +**HorsPowers** 是基于 [Superpowers](https://github.com/obra/superpowers) 的自定义版本，专为个人开发者优化。 + +### 主要特点 + +- ✅ **完整的中文支持** - 所有技能支持中文触发，在中文语境下正常工作 +- ✅ **个人/团队模式** - 可选择轻量化的个人开发模式或完整的团队协作模式 +- ✅ **文档驱动集成** - 集成 document-driven-ai-workflow，自动维护项目上下文 + +### 个人模式 vs 团队模式 + +| 特性 | 个人模式 | 团队模式 | +|------|---------|---------| +| 分支策略 | 普通分支 | Git Worktree | +| 测试策略 | 先写代码后测试 | 严格 TDD | +| 完成策略 | 本地合并 | 创建 PR | +| 适用场景 | 单人快速开发 | 多人协作项目 | + +在 `.superpowers-config.yaml` 中配置： + +```yaml +development_mode: personal # 或 team +branch_strategy: simple # 或 worktree +testing_strategy: test-after # 或 tdd +completion_strategy: merge # 或 pr +``` + +### 中文触发示例 + +所有技能都支持中文触发，例如： +- "帮我想想这个功能的实现方案" → 触发 `brainstorming` +- "帮我写个实施计划" → 触发 `writing-plans` +- "开始写这个功能" → 触发 `test-driven-development` +- "这里有个bug" → 触发 `systematic-debugging` + +更多示例请查看各技能的 description。 + +--- + +## 🇺🇸 English + Just kidding :p A custom version based on Superpowers, just a rookie stand on the shoulders of giants. diff --git "a/docs/tasks/01-\351\241\271\347\233\256\345\217\221\345\270\203\346\224\271\351\200\240.md" "b/docs/tasks/01-\351\241\271\347\233\256\345\217\221\345\270\203\346\224\271\351\200\240.md" new file mode 100644 index 000000000..79c46bbd3 --- /dev/null +++ "b/docs/tasks/01-\351\241\271\347\233\256\345\217\221\345\270\203\346\224\271\351\200\240.md" @@ -0,0 +1,297 @@ +# 任务1: 项目插件发布改造 (superpowers → horspower) + +> **创建日期**: 2026-01-15 +> **状态**: 规划中 +> **优先级**: 高 + +--- + +## 📋 任务概述 + +将项目从上游 `obra/superpowers` 的 fork 改造为独立项目 `horspower`，为发布到 Claude Code Marketplace 做准备。 + +### 改造范围 + +| 类别 | 需要替换的内容 | +|------|----------------| +| **项目名称** | `superpowers` → `horspower` | +| **配置文件** | `plugin.json`, `package.json` | +| **文档引用** | README, CLAUDE.md, 技能文档 | +| **内部引用** | 代码中的命名空间、引用 | +| **品牌标识** | 图标、描述、元数据 | + +--- + +## 🎯 详细检查清单 + +### 1. 配置文件改造 + +#### 1.1 `plugin.json` +```json +{ + "name": "horspower", + "displayName": "Horspower - 中文增强的开发技能库", + "description": "基于 Claude Code 的可组合开发工作流，专为中文用户优化", + "author": "horsliu", + "version": "4.1.0" +} +``` + +**需要检查的字段**： +- [ ] `name` - 插件唯一标识 +- [ ] `displayName` - 显示名称 +- [ ] `description` - 描述信息 +- [ ] `author` - 作者信息 +- [ ] `repository` - 仓库地址 +- [ ] `homepage` - 主页地址 + +#### 1.2 `package.json` +```json +{ + "name": "horspower", + "description": "中文增强的开发技能库", + "repository": { + "type": "git", + "url": "https://github.com/LouisHors/horspowers" + }, + "keywords": ["claude-code", "horspower", "中文", "workflow"] +} +``` + +#### 1.3 NPM 配置 +- [ ] 检查是否需要重命名 NPM package（如果发布到 NPM） +- [ ] 更新 `bugs.url` +- [ ] 更新 `homepage` + +--- + +### 2. 文档改造 + +#### 2.1 根目录文档 +- [ ] `README.md` - 主 README + - [ ] 项目名称和描述 + - [ ] 仓库链接 + - [ ] 徽章 (badges) + - [ ] 安装指令中的包名 + - [ ] 示例命令中的命名空间 + +- [ ] `CLAUDE.md` - Claude 指导文件 + - [ ] 项目名称引用 + - [ ] 技能命名空间说明 (`superpowers:` → `horspower:`) + +#### 2.2 技能文档 +所有 `skills/*/SKILL.md` 文件中的： +- [ ] `superpowers:` 命名空间引用 +- [ ] 项目名称提及 +- [ ] 示例代码中的引用 + +**受影响的技能**： +``` +skills/ +├── brainstorming/SKILL.md +├── using-superpowers/SKILL.md ← 特别注意 +├── writing-plans/SKILL.md +├── test-driven-development/SKILL.md +├── subagent-driven-development/SKILL.md +└── ... +``` + +#### 2.3 其他文档 +- [ ] `docs/README.codex.md` +- [ ] `docs/README.opencode.md` +- [ ] `docs/testing.md` +- [ ] `RELEASE-NOTES.md` + +--- + +### 3. 代码改造 + +#### 3.1 技能引用系统 +检查代码中是否有硬编码的 `superpowers` 引用： + +**需要搜索的模式**： +```bash +# 搜索这些模式 +grep -r "superpowers:" skills/ +grep -r "obra/superpowers" . +grep -r "superpowers" lib/ +``` + +**需要保留的引用**： +- MIT License 中的原始项目归属 +- 代码注释中对上游的致谢 + +#### 3.2 Hook 脚本 +- [ ] `hooks/session-start.sh` - 检查技能注入逻辑 +- [ ] `hooks/hooks.json` - 检查配置 + +#### 3.3 JavaScript/TypeScript 代码 +```bash +# 检查 lib/ 目录 +lib/skills-core.js # Codex/OpenCode 支持 +``` + +--- + +### 4. 品牌标识 + +#### 4.1 图标和资源 +- [ ] 检查是否有图标资源需要替换 +- [ ] 检查 Marketplace 展示图（如果有） + +#### 4.2 元数据描述 +更新所有面向用户的描述： +- [ ] Marketplace 描述 +- [ ] README 中的功能介绍 +- [ ] 技能触发条件描述 + +--- + +### 5. 许可证合规 + +#### 5.1 MIT License 要求 +✅ **必须保留**： +- 原始 MIT License 文件 +- 原项目版权声明 +- NOTICE 文件（如果需要） + +**建议添加**： +``` +NOTICE + +此项目基于 obra/superpowers (https://github.com/obra/superpowers) +Original Copyright (c) 2024 obra +Modifications Copyright (c) 2026 horsliu + +本项目在 MIT License 下发布 +``` + +#### 5.2 Package.json 许可证 +- [ ] 确认 `license` 字段为 `"MIT"` + +--- + +## 📝 执行步骤 + +### Phase 1: 准备阶段 +1. 创建发布分支 `git checkout -b prep/release-horspower` +2. 备份关键文件 +3. 创建检查清单追踪文档 + +### Phase 2: 配置文件改造 +1. 更新 `plugin.json` +2. 更新 `package.json` +3. 更新 NPM 相关配置 + +### Phase 3: 文档改造 +1. 更新 README.md +2. 更新 CLAUDE.md +3. 批量更新技能文档中的命名空间引用 +4. 更新其他文档 + +### Phase 4: 代码审查 +1. 搜索所有 `superpowers` 引用 +2. 分类处理：保留/修改/删除 +3. 测试技能系统是否正常工作 + +### Phase 5: 品牌更新 +1. 更新项目描述和元数据 +2. 准备 Marketplace 展示材料 +3. 添加 NOTICE 文件 + +### Phase 6: 验证测试 +1. 运行所有技能测试 +2. 验证插件加载 +3. 测试技能调用 +4. 检查文档链接 + +### Phase 7: 发布准备 +1. 更新版本号 +2. 编写 Release Notes +3. 准备 Marketplace 提交 + +--- + +## 🔍 搜索和替换策略 + +### 批量替换脚本 +```bash +#!/bin/bash +# ⚠️ 使用前请仔细检查！ + +# 1. 查找所有需要检查的文件 +grep -r "superpowers" \ + --exclude-dir=node_modules \ + --exclude-dir=.git \ + --exclude="*.log" \ + . > /tmp/superpowers-references.txt + +# 2. 人工审查后再替换 +# 查看结果： +cat /tmp/superpowers-references.txt + +# 3. 安全替换（示例 - 需要仔细验证） +find . -type f \( -name "*.md" -o -name "*.json" \) \ + -not -path "./node_modules/*" \ + -not -path "./.git/*" \ + -exec sed -i '' 's/superpowers:skill-name:/horspower:skill-name:/g' {} + +``` + +### 需要特别小心的地方 +1. **License 文件** - 不要修改 +2. **Git 历史** - 不要重写历史 +3. **外部引用链接** - 某些可能需要保留 +4. **代码示例** - 确保示例仍然有效 + +--- + +## ✅ 验证清单 + +完成改造后，验证以下内容： + +### 基础功能 +- [ ] 插件可以在 Claude Code 中加载 +- [ ] 技能列表正常显示 +- [ ] 技能可以正常调用 +- [ ] 所有测试通过 + +### 文档一致性 +- [ ] 所有文档链接有效 +- [ ] 命名空间引用统一 +- [ ] 示例代码可运行 + +### 发布就绪 +- [ ] 版本号已更新 +- [ ] Release Notes 已准备 +- [ ] Marketplace 描述完整 +- [ ] 许可证信息正确 + +--- + +## 📌 注意事项 + +1. **License 合规性**：MIT License 允许修改和再发布，但需要： + - 保留原始 License + - 保留版权声明 + - 声明修改内容 + +2. **向后兼容**：考虑是否需要保留 `superpowers:` 别名支持 + +3. **测试覆盖**：改造后必须运行完整测试套件 + +4. **渐进式替换**：建议分阶段进行，每次提交后验证 + +5. **文档同步**：确保 README 和 CLAUDE.md 中的引用同步更新 + +--- + +## 📚 参考资料 + +- [Claude Code Plugin Documentation](https://github.com/anthropics/claude-code) +- [MIT License Text](https://opensource.org/licenses/MIT) +- [Upstream Repository](https://github.com/obra/superpowers) + +--- + +**创建日期**: 2026-01-15 +**预计完成**: TBD diff --git "a/docs/tasks/02-\345\205\250\351\235\242\344\270\255\346\226\207\351\200\202\351\205\215.md" "b/docs/tasks/02-\345\205\250\351\235\242\344\270\255\346\226\207\351\200\202\351\205\215.md" new file mode 100644 index 000000000..08d4b0501 --- /dev/null +++ "b/docs/tasks/02-\345\205\250\351\235\242\344\270\255\346\226\207\351\200\202\351\205\215.md" @@ -0,0 +1,380 @@ +# 任务2: 全面中文适配 + +> **创建日期**: 2026-01-15 +> **状态**: 规划中 +> **优先级**: 高 + +--- + +## 📋 任务概述 + +将整个项目适配为中文优先的用户体验，确保在中文语境下能够正常、流畅地使用。 + +### 适配范围 + +| 类别 | 需要适配的内容 | +|------|----------------| +| **用户界面** | 技能描述、提示信息、错误消息 | +| **文档** | README、技能文档、指南 | +| **技能触发** | 自然语言触发条件 | +| **示例代码** | 代码注释、变量命名示例 | +| **交互流程** | 用户询问、确认提示 | + +--- + +## 🎯 详细检查清单 + +### 1. 核心技能文档适配 + +#### 1.1 技能元数据（YAML Frontmatter） +每个技能的 `description` 字段需要支持中文触发： + +**示例改造**： +```yaml +--- +name: brainstorming +# 原: Use when you need to refine ideas through questions +description: 当你需要通过提问来完善想法时使用此技能 +--- + +# 头脑风暴 + +## Overview +... +``` + +**需要适配的技能**： +- [ ] `brainstorming` - 头脑风暴 +- [ ] `using-superpowers` → `using-horspower` - 使用指南 +- [ ] `writing-plans` - 编写计划 +- [ ] `test-driven-development` - 测试驱动开发 +- [ ] `executing-plans` - 执行计划 +- [ ] `subagent-driven-development` - 子代理驱动开发 +- [ ] `systematic-debugging` - 系统化调试 +- [ ] `finishing-a-development-branch` - 完成开发分支 +- [ ] `using-git-worktrees` - 使用 Git Worktrees +- [ ] `receiving-code-review` - 接收代码审查 +- [ ] `requesting-code-review` - 请求代码审查 +- [ ] `writing-skills` - 编写技能 + +#### 1.2 技能内容本地化 +每个技能的主体内容需要： +- [ ] 章节标题双语化或中文化 +- [ ] 流程说明使用中文 +- [ ] 示例对话使用中文场景 +- [ ] 保留关键术语的英文原文（如 TDD、Git、rebase） + +--- + +### 2. 文档系统适配 + +#### 2.1 README.md +**需要添加的内容**： +```markdown +## 简体中文 + +本项目提供完整的中文支持： + +- ✅ 所有技能支持中文触发 +- ✅ 中文文档和示例 +- ✅ 中文友好的交互流程 + +[中文文档](docs/zh/) | [English](#english) +``` + +**适配要求**： +- [ ] 添加中文介绍段落 +- [ ] 中文安装指南 +- [ ] 中文快速开始示例 +- [ ] 常见问题中文版 + +#### 2.2 CLAUDE.md +**关键适配**： +```markdown +## Personal Rule +Always respond in *Simplified Chinese/中文* +``` + +**需要检查**： +- [ ] 项目概述是否准确反映中文功能 +- [ ] 技能列表是否有中文名称 +- [ ] 示例命令是否包含中文场景 + +#### 2.3 技能参考卡片 +为每个技能创建中文参考卡片： + +```markdown +## 技能速查表 + +| 技能 | 中文名称 | 触发条件 | +|------|---------|---------| +| brainstorming | 头脑风暴 | 当你需要完善想法时 | +| writing-plans | 编写计划 | 当需要详细实施计划时 | +| tdd | 测试驱动开发 | 当需要先写测试时 | +... +``` + +--- + +### 3. 技能触发条件优化 + +#### 3.1 中文触发词 +为每个技能添加中文触发场景： + +**brainstorming 示例**： +```yaml +--- +description: | + 当你需要通过提问来完善想法时使用此技能 + + 中文触发场景： + - "帮我想想这个功能的实现方案" + - "这个需求我该怎么设计？" + - "帮我理清思路" + - "我想做个XXX，有什么建议？" + + English triggers: + - "I need to refine my idea" + - "Help me think through this" +--- +``` + +#### 3.2 自然语言模式 +识别中文开发中的常见表达： + +| 开发场景 | 中文表达 | 应触发技能 | +|---------|---------|-----------| +| 需求讨论 | "帮我设计一下..." | brainstorming | +| 开始实现 | "怎么实现这个功能？" | writing-plans | +| 遇到 bug | "这里有个问题..." | systematic-debugging | +| 完成功能 | "功能做完了" | finishing-a-development-branch | +| 需要测试 | "怎么测试这个？" | test-driven-development | + +--- + +### 4. 交互流程适配 + +#### 4.1 AskUserQuestion 中文化 +确保所有用户交互使用中文： + +```javascript +// 不好的示例 +AskUserQuestion({ + questions: [{ + question: "Which approach do you prefer?", + header: "Approach", + options: [...] + }] +}) + +// 好的示例 +AskUserQuestion({ + questions: [{ + question: "你更倾向于哪种实现方案？", + header: "实现方案", + options: [...] + }] +}) +``` + +#### 4.2 错误提示中文化 +技能中的错误处理需要中文提示： + +```markdown +## 错误处理 + +### 测试失败 +❌ 测试失败，发现 3 个错误 + +请选择： +1. 查看详细错误信息 +2. 尝试自动修复 +3. 暂时跳过测试 +``` + +--- + +### 5. 代码示例适配 + +#### 5.1 注释中文化 +技能文档中的代码示例： + +```typescript +// 创建配置项 +const config = { + name: "我的项目", + version: "1.0.0" +} + +// 添加中文注释说明关键逻辑 +// 1. 首先检查缓存 +// 2. 如果没有缓存，则从 API 获取 +// 3. 最后将结果存入缓存 +``` + +#### 5.2 变量命名 +在示例中展示中文友好的命名风格： + +```typescript +// 推荐的命名示例（业务逻辑） +interface 用户配置 { + 用户名: string + 偏好设置: Preferences +} + +// 但技术术语保持英文 +interface UserConfig { + username: string + preferences: Preferences + webhookUrl: string // 技术术语 +} +``` + +--- + +### 6. 特殊中文场景适配 + +#### 6.1 Git Commit Message +支持中文 commit message： + +```bash +# 有效的中文 commit +feat(用户系统): 添加微信登录功能 + +- 新增微信 OAuth 集成 +- 添加用户绑定逻辑 +- 更新 API 文档 +``` + +#### 6.2 代码审查 +中文代码审查场景： + +```markdown +## 代码审查反馈 + +### 问题 +1. `getUserInfo` 函数的类型定义不够严格 +2. 建议将 `data: any` 改为 `data: unknown` + +### 建议 +考虑使用 Zod 或类似库进行运行时验证 +``` + +#### 6.3 调试和日志 +中文友好的调试信息： + +```typescript +logger.debug("开始处理用户请求", { userId }) +logger.info("数据库连接成功") +logger.error("API 调用失败", { url, error }) +``` + +--- + +## 📝 执行步骤 + +### Phase 1: 核心技能适配（优先级高） +1. `brainstorming` - 中文触发和描述 +2. `writing-plans` - 中文计划模板 +3. `test-driven-development` - 中文测试流程 +4. `systematic-debugging` - 中文调试步骤 + +### Phase 2: 文档系统适配 +1. README.md 添加中文部分 +2. 创建中文技能速查表 +3. 翻译核心概念说明 + +### Phase 3: 交互流程优化 +1. 统一错误提示为中文 +2. 优化 AskUserQuestion 的中文表达 +3. 添加中文使用示例 + +### Phase 4: 测试和验证 +1. 测试中文技能触发 +2. 验证中文交互流程 +3. 收集用户反馈 + +### Phase 5: 持续改进 +1. 根据使用反馈优化 +2. 添加更多中文示例 +3. 完善中文术语表 + +--- + +## 📊 中文适配优先级 + +| 优先级 | 内容 | 预计工作量 | 价值 | +|--------|------|-----------|------| +| P0 | 技能描述 YAML frontmatter | 2-3 小时 | ⭐⭐⭐⭐⭐ | +| P0 | CLAUDE.md 中文规则确认 | 30 分钟 | ⭐⭐⭐⭐⭐ | +| P1 | 核心技能内容中文化 | 4-6 小时 | ⭐⭐⭐⭐ | +| P1 | README 中文部分 | 2 小时 | ⭐⭐⭐⭐ | +| P2 | 代码示例中文化 | 2-3 小时 | ⭐⭐⭐ | +| P2 | 交互提示优化 | 2 小时 | ⭐⭐⭐ | +| P3 | 完整中文文档翻译 | 8-10 小时 | ⭐⭐ | + +--- + +## ✅ 验证清单 + +### 基础验证 +- [ ] 所有技能 description 包含中文触发条件 +- [ ] CLAUDE.md 包含中文响应规则 +- [ ] README 有中文介绍 + +### 功能验证 +- [ ] 中文指令能正确触发技能 +- [ ] 技能执行过程中使用中文交互 +- [ ] 错误提示使用中文 +- [ ] 示例代码包含中文注释 + +### 质量验证 +- [ ] 中文表达自然流畅 +- [ ] 技术术语使用准确 +- [ ] 保留必要的英文原文 + +--- + +## 🎨 中文风格指南 + +### 语气和风格 +- **友好自然**：避免生硬的机器翻译 +- **专业准确**：技术术语保持英文 +- **简洁明了**：避免冗长的描述 + +### 术语处理原则 +| 类型 | 处理方式 | 示例 | +|------|---------|------| +| 技术术语 | 保留英文 | Git, rebase, commit | +| 命令/代码 | 保留原文 | `git status` | +| UI 文本 | 中文化 | "提交更改" | +| 概念解释 | 中文 + 英文原文 | "分支 (Branch)" | + +### 标点符号 +- 代码和命令：使用英文标点 +- 中文说明：使用中文标点 +- 混合场景：遵循中文排版规范 + +--- + +## 📚 附录：中文术语对照表 + +| 英文 | 中文 | 说明 | +|------|------|------| +| Skill | 技能 | 基本功能单元 | +| Workflow | 工作流 | 一系列操作流程 | +| Branch | 分支 | Git 分支 | +| Commit | 提交 | Git 提交 | +| Merge | 合并 | 合并代码 | +| Rebase | 变基 | Git rebase | +| PR/MR | 拉取请求 | Pull/Merge Request | +| Lint | 代码检查 | 代码静态分析 | +| Type Check | 类型检查 | TypeScript 类型检查 | +| Test | 测试 | 单元测试等 | +| Debug | 调试 | 问题排查 | +| Deploy | 部署 | 发布上线 | + +--- + +**创建日期**: 2026-01-15 +**预计完成**: TBD diff --git "a/docs/tasks/03-\350\207\252\345\212\250\345\214\226\345\274\200\345\217\221\345\267\245\344\275\234\346\265\201Skill.md" "b/docs/tasks/03-\350\207\252\345\212\250\345\214\226\345\274\200\345\217\221\345\267\245\344\275\234\346\265\201Skill.md" new file mode 100644 index 000000000..8ea656e8e --- /dev/null +++ "b/docs/tasks/03-\350\207\252\345\212\250\345\214\226\345\274\200\345\217\221\345\267\245\344\275\234\346\265\201Skill.md" @@ -0,0 +1,523 @@ +# 任务3: 自动化开发工作流 Skill + +> **创建日期**: 2026-01-15 +> **状态**: 规划中 +> **优先级**: 中 + +--- + +## 📋 任务概述 + +将 [自动化开发工作流设计文档.md](../自动化开发工作流设计文档.md) 转换为可执行的 Claude Skill，作为 `using-git-worktrees` 的替代方案。 + +### 设计目标 + +1. **互补关系**：当用户不使用 worktree 时，使用此工作流 +2. **自动化优先**：减少手动操作，自动执行常见流程 +3. **中文友好**：全中文交互和提示 +4. **灵活配置**：支持 `.workflow-config.json` 自定义 + +--- + +## 🎯 Skill 结构设计 + +### 技能元数据 +```yaml +--- +name: automated-development-workflow +description: | + 当你在日常开发中需要自动化代码提交流程时使用此技能 + + 中文触发场景： + - "下班了" + - "完成今天的工作，帮我提交代码" + - "今天的代码可以提交了吗？" + - "帮我执行每日工作流" + - "提交并推送代码" + + 也适用于： + - 快速提交代码（跳过检查） + - 合并到 develop 分支 + - 解决 Git 冲突 + - 同步分支代码 +--- + +# 自动化开发工作流 + +## Overview +这个技能帮助你自动化日常开发中的 Git 操作，包括代码检查、提交、推送和合并。 + +## The Process +... +``` + +### 技能命名 +- **文件名**: `automated-development-workflow/SKILL.md` +- **简称**: `auto-dev-workflow` 或 `daily-workflow` +- **命令**: `/daily-workflow`, `/quick-commit`, `/merge-develop` + +--- + +## 📋 功能模块分解 + +### 模块 1: 每日工作流（核心功能） + +#### 触发条件 +用户说以下内容时启动： +- "下班了" +- "提交代码" +- "今天的代码可以提交了吗？" +- "执行每日工作流" + +#### 执行流程 +``` +1. 显示当前状态 + ├─ 当前分支 + ├─ 未提交更改（文件列表） + └─ 最近提交历史 + +2. 代码质量检查 + ├─ 类型检查（可配置） + ├─ Lint 检查（可配置） + └─ 测试（可选） + +3. 自动生成 Commit Message + ├─ 分析更改类型（feat/fix/docs/chore） + ├─ 分析更改范围（types/config/logger 等） + ├─ 生成主题行 + └─ 生成详细说明（可选） + +4. 用户确认 + └─ 显示生成的 commit message + └─ 询问是否使用 / 编辑 / 重新生成 + +5. 提交和推送 + ├─ git add -A + ├─ git commit + └─ git push + +6. 询问下一步 + ├─ 合并到 develop + ├─ 创建 Pull Request + ├─ 结束工作流 + └─ 取消（已提交） +``` + +#### 输出模板 +``` +🌅 下班时间到！开始执行每日工作流... + +📊 当前状态： +分支：feat/config-system-optimization +未提交更改：3 个文件 + + frontend/src/types/config-system.ts (新增 50 行) + + frontend/src/utils/configItemSort.ts (新增 70 行) + + CLAUDE.md (修改) + +🔍 步骤 1：代码质量检查 +✓ 类型检查通过（2.3s） +✓ Lint 通过（1.1s） + +📝 步骤 2：生成 Commit Message +分析更改内容... + - 新增类型定义 + - 新增工具函数 + - 更新文档 + +自动生成的 commit message： +feat(config): 添加配置项排序功能 + +- 新增 ModuleConfigItems 类型定义 +- 新增 configItemSort 工具函数 +- 更新 CLAUDE.md 文档 + +是否使用此 commit message？(y/n/edit) +``` + +--- + +### 模块 2: 快速提交 + +#### 触发条件 +- `/quick-commit` +- "快速提交" +- "跳过检查直接提交" + +#### 流程 +``` +1. 跳过所有质量检查 +2. 快速生成 commit message（或使用用户提供的） +3. 提交并推送 +``` + +--- + +### 模块 3: 合并到 Develop + +#### 触发条件 +- `/merge-develop` +- "合并到 develop" +- "把这个功能合并到 develop" + +#### 流程 +``` +1. 检查当前分支状态 +2. 切换到 develop +3. 拉取最新代码 +4. 合并当前分支 +5. 处理冲突（如果有） + ├─ 自动解决已知类型冲突 + └─ 手动解决复杂冲突 +6. 推送 develop +7. 可选：删除功能分支 +``` + +#### 冲突解决规则 +```typescript +interface ConflictResolution { + // 配置文件：合并 + packageJson: "merge" + + // 代码文件：基础设施优先 + codeFiles: "infra-priority" + + // 文档：保留当前分支 + docs: "ours" + + // 测试文件：保留传入版本 + testFiles: "theirs" +} +``` + +--- + +### 模块 4: 分支同步 + +#### 触发条件 +- `/sync-branch` +- "同步分支" +- "更新分支代码" + +#### 流程 +``` +1. 保存当前更改（使用 stash） +2. 切换到 develop/main +3. 拉取最新代码 +4. 返回原分支 +5. 执行 rebase +6. 恢复保存的更改 +7. 处理冲突（如果有） +``` + +--- + +### 模块 5: 冲突解决 + +#### 触发条件 +- `/resolve-conflicts` +- 检测到冲突时自动触发 + +#### 流程 +``` +1. 列出所有冲突文件 +2. 对每个文件分类： + ├─ package.json → 合并策略 + ├─ *.ts/*.tsx → infra-priority + ├─ *.md → ours + └─ 其他 → 询问用户 +3. 应用解决策略 +4. 验证解决结果 +5. 完成合并 +``` + +--- + +### 模块 6: 分支管理 + +#### 创建分支 +- `/create-branch ` +- "创建一个新的 feature 分支" + +```bash +git checkout develop +git pull origin develop +git checkout -b / +git push -u origin / +``` + +#### 清理分支 +- `/cleanup-branches` +- "清理已合并的分支" + +```bash +# 删除本地已合并分支 +git branch --merged | grep -v "develop\|main" | xargs git branch -d + +# 清理远程已合并分支 +git remote prune origin +``` + +--- + +### 模块 7: 配置管理 + +#### 读取配置 +```typescript +function loadConfig(): WorkflowConfig { + const defaultConfig = { + developBranch: "main", + checks: { + typeCheck: { enabled: true, command: "npm run type-check" }, + lint: { enabled: true, command: "npm run lint" }, + test: { enabled: false } + }, + autoMerge: { + enabled: false, + targetBranch: "develop" + } + } + + // 尝试读取 .workflow-config.json + try { + const userConfig = JSON.parse(readFile('.workflow-config.json')) + return { ...defaultConfig, ...userConfig } + } catch { + return defaultConfig + } +} +``` + +#### 配置文件模板 +```json +{ + "developBranch": "main", + "featureBranchPrefix": "feat/", + "checks": { + "typeCheck": { + "enabled": true, + "command": "npm run type-check", + "autoFix": true + }, + "lint": { + "enabled": true, + "command": "npm run lint", + "autoFix": true + }, + "test": { + "enabled": false, + "command": "npm test" + } + }, + "autoMerge": { + "enabled": false, + "targetBranch": "develop" + }, + "conflictResolution": { + "packageJson": "merge", + "codeFiles": "infra-priority", + "docs": "ours" + } +} +``` + +--- + +## 📝 Commit Message 生成逻辑 + +### 分析算法 +```typescript +interface CommitAnalysis { + type: 'feat' | 'fix' | 'docs' | 'refactor' | 'chore' | 'style' | 'perf' | 'test' + scope?: string + subject: string + body?: string +} + +function analyzeCommit(diff: string, files: string[]): CommitAnalysis { + // 1. 确定类型 + let type = 'chore' + if (diff.includes('export') || diff.includes('function') || diff.includes('class')) { + type = 'feat' + } else if (diff.includes('fix') || diff.includes('bug')) { + type = 'fix' + } else if (files.some(f => f.endsWith('.md'))) { + type = 'docs' + } else if (diff.includes('refactor') || diff.includes('优化')) { + type = 'refactor' + } + + // 2. 确定范围 + let scope = '' + if (files.some(f => f.includes('type'))) scope = 'types' + else if (files.some(f => f.includes('config'))) scope = 'config' + else if (files.some(f => f.includes('logger'))) scope = 'logger' + else if (files.some(f => f.includes('test'))) scope = 'test' + + // 3. 生成主题 + const subject = extractSubjectFromDiff(diff) + + // 4. 生成详细说明 + const body = generateBody(files) + + return { type, scope, subject, body } +} +``` + +### 示例 +**输入**： +- 修改了 `src/types/config.ts`（添加新类型） +- 修改了 `src/components/ConfigEditor.tsx`（使用新类型） +- 修改了 `README.md`（更新文档） + +**输出**： +``` +feat(types): 添加 ModuleConfigItems 类型定义 + +- 新增 ModuleConfigItems 接口 +- ConfigEditor 使用新的类型系统 +- 更新文档说明 +``` + +--- + +## 🎨 交互设计 + +### 场景 1: 正常工作流 +``` +User: "下班了" + +Claude: +🌅 下班时间到！开始执行每日工作流... + +📊 当前状态： +分支：feat/user-auth +未提交更改：2 个文件 + +🔍 步骤 1：代码质量检查 +✓ 类型检查通过 +✓ Lint 通过 + +📝 步骤 2：生成 Commit Message +feat(auth): 添加用户登录功能 + +- 实现用户名密码登录 +- 添加 JWT token 管理 +- 更新登录页面 UI + +是否使用此 commit message？(y/n/edit) +``` + +### 场景 2: 检查失败 +``` +Claude: +❌ 类型检查失败（3 个错误） + +src/auth.ts:10:5 + error TS2322: Type 'unknown' is not assignable to type 'string' + +💡 建议操作： +1. 尝试自动修复类型错误 +2. 手动修复后重试 +3. 暂时跳过检查（不推荐） + +选择操作（输入数字）： +``` + +### 场景 3: 解决冲突 +``` +User: "/merge-develop" + +Claude: +🔄 正在合并到 develop... + +⚠️ 检测到冲突！ + +冲突文件（2）： +1. package.json + └─ npm scripts 冲突 + +2. src/utils/logger.ts + └─ console.log vs logger.debug + +🔍 分析并解决冲突： +✓ package.json - 已自动合并（合并双方 scripts） +✓ logger.ts - 已自动解决（采用 logger 版本） + +是否继续合并？(y/n) +``` + +--- + +## 📋 实施步骤 + +### Step 1: 创建技能文件 +``` +skills/ +└── automated-development-workflow/ + ├── SKILL.md # 主技能文件 + ├── templates/ # 模板文件 + │ └── commit-message.txt + └── scripts/ # 辅助脚本 + └── merge-package-json.js +``` + +### Step 2: 实现 Commit Message 生成 +- [ ] 编写分析逻辑 +- [ ] 创建模板系统 +- [ ] 添加中文支持 + +### Step 3: 实现冲突解决 +- [ ] package.json 合并脚本 +- [ ] 文件分类逻辑 +- [ ] 自动解决规则 + +### Step 4: 实现配置系统 +- [ ] 配置文件读取 +- [ ] 默认配置定义 +- [ ] 配置验证 + +### Step 5: 测试和验证 +- [ ] 单元测试 +- [ ] 集成测试 +- [ ] 用户测试 + +--- + +## ✅ 验证清单 + +### 功能验证 +- [ ] 每日工作流完整执行 +- [ ] 快速提交正常工作 +- [ ] 分支合并无问题 +- [ ] 冲突解决正确 + +### 配置验证 +- [ ] 默认配置可用 +- [ ] 自定义配置加载 +- [ ] 配置验证正常 + +### 交互验证 +- [ ] 中文提示友好 +- [ ] 错误处理完善 +- [ ] 用户选择清晰 + +--- + +## 📚 与 using-git-worktrees 的关系 + +| 特性 | using-git-worktrees | automated-development-workflow | +|------|---------------------|-------------------------------| +| **使用场景** | 并行开发多个功能 | 单一分支顺序开发 | +| **隔离性** | 完全隔离的工作目录 | 同一工作目录 | +| **复杂性** | 较复杂 | 简单直接 | +| **适用项目** | 大型项目、长期分支 | 小型项目、快速迭代 | +| **切换成本** | 低（已有 worktree） | 低（无需设置） | + +**推荐使用场景**： +- 使用 `using-git-worktrees`：当你需要同时开发多个不相关的功能时 +- 使用 `automated-development-workflow`：当你专注于一个功能的快速迭代时 + +--- + +**创建日期**: 2026-01-15 +**预计完成**: TBD diff --git "a/docs/\350\207\252\345\212\250\345\214\226\345\274\200\345\217\221\345\267\245\344\275\234\346\265\201\350\256\276\350\256\241\346\226\207\346\241\243.md" "b/docs/\350\207\252\345\212\250\345\214\226\345\274\200\345\217\221\345\267\245\344\275\234\346\265\201\350\256\276\350\256\241\346\226\207\346\241\243.md" new file mode 100644 index 000000000..41b953eb7 --- /dev/null +++ "b/docs/\350\207\252\345\212\250\345\214\226\345\274\200\345\217\221\345\267\245\344\275\234\346\265\201\350\256\276\350\256\241\346\226\207\346\241\243.md" @@ -0,0 +1,950 @@ +# 自动化开发工作流设计文档 + +> **创建日期**: 2026-01-15 +> **版本**: 1.0.0 +> **状态**: 设计阶段 + +--- + +## 📋 目录 + +1. [背景与目标](#背景与目标) +2. [核心概念](#核心概念) +3. [工作流设计](#工作流设计) +4. [冲突解决策略](#冲突解决策略) +5. [Claude Skill 创建 Prompt](#claude-skill-创建-prompt) +6. [实施指南](#实施指南) +7. [最佳实践](#最佳实践) + +--- + +## 背景与目标 + +### 问题场景 + +在个人开发项目中，特别是使用 Claude Code 进行 AI 辅助开发时，面临以下挑战： + +1. **日常开发流程繁琐** + - 类型检查、Lint、测试需要手动执行 + - 代码提交、合并操作重复 + - 分支管理容易混乱 + +2. **分支合并冲突频繁** + - 多个 feature 分支并行开发 + - 基础设施改动（logger、type-check）与功能改动冲突 + - 缺乏统一的冲突解决策略 + +3. **基础设施升级困难** + - logger 优化、类型检查增强等全局改动难以协调 + - 需要在多个分支间同步相同改动 + - 容易出现不一致或遗漏 + +### 设计目标 + +1. **自动化日常流程**：一键完成代码检查、提交、推送、合并 +2. **智能冲突解决**：根据规则自动解决常见冲突 +3. **灵活可配置**：适应不同项目和个人习惯 +4. **保持项目独立**：不污染项目代码，作为外部工具使用 + +--- + +## 核心概念 + +### 并行开发工作流 + +``` +时间线：t0 ──────────────────────────────────────────────> tn + +开发阶段： +┌─────────────────────────────────────────────────────────┐ +│ Feature 分支（功能开发） │ +│ ├─ 每日提交代码 │ +│ ├─ 自动运行质量检查 │ +│ └─ 完成后合并到 develop │ +└─────────────────────────────────────────────────────────┘ + +同步阶段： +┌─────────────────────────────────────────────────────────┐ +│ Infrastructure 分支（基础设施） │ +│ ├─ 从 develop 同步最新代码 │ +│ ├─ 应用自动化转换规则 │ +│ │ └─ console.log → logger │ +│ │ └─ any → unknown │ +│ ├─ 解决冲突（如果有） │ +│ └─ 合并回 develop │ +└─────────────────────────────────────────────────────────┘ +``` + +### 关键原则 + +1. **Feature First**：功能开发优先完成，基础设施跟进 +2. **改动小者优先**：冲突在改动小的分支解决 +3. **基础设施优先**：logger、类型检查等基础改动优先保留 +4. **定期同步**：每天或每次提交前同步主分支代码 + +--- + +## 工作流设计 + +### 每日开发工作流 + +```bash +# === 早上 === +# 1. 同步最新代码 +git checkout develop +git pull origin develop + +# 2. 创建或切换到 feature 分支 +git checkout feat/my-feature +git rebase develop + +# === 开发中 === +# 使用 Claude Code 辅助开发 +# ...编写代码... + +# === 下班前 === +# 3. 运行自动化工作流（由 Claude Skill 执行） +# - 自动类型检查 +# - 自动 Lint +# - 自动测试 +# - 自动提交 +# - 自动推送 +# - 可选：自动合并到 develop +``` + +### 自动化流程步骤 + +#### 步骤 1：代码质量检查 + +```bash +# 类型检查 +npm run type-check:strict + +# Lint 检查 +npm run lint + +# 测试（如果有） +npm test +``` + +**智能处理**： +- ✅ 全部通过 → 继续 +- ❌ 有错误 → 尝试自动修复 + - 类型错误：尝试添加类型注解 + - Lint 错误：运行 `eslint --fix` + - 测试失败：询问是否跳过 + +#### 步骤 2：生成 Commit Message + +根据更改内容自动生成： + +```javascript +// 分析更改类型 +const changes = { + hasNewFeatures: diff.includes('feat('), + hasFixes: diff.includes('fix('), + hasDocs: files.some(f => f.endsWith('.md')), + hasTypes: files.some(f => f.match(/\.(ts|tsx)$/)), + hasTests: files.some(f => f.includes('.test.')), + hasConfig: files.some(f => f.includes('config')) +} + +// 生成类型 +let type = 'chore' +let scope = '' + +if (changes.hasNewFeatures) type = 'feat' +if (changes.hasFixes) type = 'fix' +if (changes.hasDocs) type = 'docs' +if (changes.hasTypes) scope = 'types' +if (changes.hasConfig) scope = 'config' + +// 生成 message +const message = `${type}(${scope}): ${subject}` +``` + +示例： +- `feat(config): 添加参数可见性控制` +- `fix(logger): 修复类型推断错误` +- `docs(readme): 更新安装指南` + +#### 步骤 3：提交和推送 + +```bash +# 添加所有更改 +git add -A + +# 提交 +git commit -m "$COMMIT_MESSAGE" + +# 推送 +git push origin $(git branch --show-current) +``` + +#### 步骤 4：询问下一步 + +``` +✅ 代码已提交并推送 + +下一步操作： +1. 合并到 develop 分支 +2. 创建 Pull Request +3. 触发基础设施自动化升级 +4. 结束工作流 + +选择操作（输入数字）： +``` + +--- + +## 冲突解决策略 + +### 冲突分类 + +#### 1. 配置文件冲突（package.json） + +**场景**：两个分支都添加了新的 npm scripts + +**解决方案**：合并所有 scripts 和 dependencies + +```javascript +// 合并逻辑 +const base = { scripts: { test: 'jest' } } +const ours = { scripts: { test: 'jest', lint: 'eslint' } } +const theirs = { scripts: { test: 'jest', typecheck: 'tsc' } } + +// 结果 +const merged = { + scripts: { + test: 'jest', + lint: 'eslint', + typecheck: 'tsc' + } +} +``` + +#### 2. 代码文件冲突（logger/console.log） + +**场景**： +- feat 分支使用 `console.log()` +- infra/logger 分支使用 `logger.debug()` + +**解决方案**：采用 logger 版本（基础设施优先） + +```bash +# 自动执行 +git checkout --theirs src/utils/logger.ts +``` + +#### 3. 类型冲突（any vs unknown） + +**场景**： +- feat 分支：`data: any` +- infra/type-check 分支：`data: unknown` + +**解决方案**：采用 unknown 版本 + +```bash +# 自动执行 +git checkout --theirs src/feature.ts +``` + +#### 4. 文档冲突（*.md） + +**场景**：两个分支都修改了 README.md + +**解决方案**：通常采用当前分支版本 + +```bash +git checkout --ours README.md +``` + +### 冲突解决流程 + +```bash +# 1. 检测冲突 +git diff --name-only --diff-filter=U + +# 2. 分类处理 +for file in conflicted_files; do + case "$file" in + package.json) + node scripts/merge-package-json + ;; + *.ts|*.tsx) + if grep -q "console.log\|logger\." "$file"; then + git checkout --theirs "$file" + fi + ;; + *.md) + git checkout --ours "$file" + ;; + esac +done + +# 3. 标记为已解决 +git add . + +# 4. 完成合并 +git commit --no-edit +``` + +--- + +## Claude Skill 创建 Prompt + +### 完整的 Skill 定义 Prompt + +复制以下内容，在目标项目中创建 Claude Skill： + +```markdown +# 自动开发工作流 Skill + +你是自动开发工作流助手，专门帮助开发者简化日常开发任务。 + +## 🎯 核心功能 + +1. **每日工作流自动化** + - 代码质量检查（类型、Lint、测试） + - 自动生成 commit message + - 提交和推送代码 + - 可选：合并到 develop + +2. **智能冲突解决** + - 自动分类冲突文件 + - 根据规则自动解决常见冲突 + - 无法自动解决时提供指导 + +3. **分支管理** + - 创建、切换、合并分支 + - 同步主分支代码 + - 清理已合并分支 + +## 🚀 触发方式 + +### 自动触发 +当用户说以下内容时，启动每日工作流： +- "下班了" +- "完成今天的工作" +- "提交代码" +- "今天的代码可以提交了吗？" + +### 手动命令 +- `/daily-workflow` - 执行完整的每日工作流 +- `/quick-commit` - 快速提交（跳过检查） +- `/merge-develop` - 合并当前分支到 develop +- `/resolve-conflicts` - 解决当前冲突 +- `/sync-branch` - 同步当前分支与 develop +- `/branch-status` - 显示分支状态 + +## 📋 每日工作流程 + +### 步骤 1：检查状态 +```bash +# 显示当前状态 +echo "当前分支: $(git branch --show-current)" +echo "未提交更改:" +git status --short +echo "最近提交:" +git log --oneline -5 +``` + +### 步骤 2：质量检查 +```bash +# 按顺序执行检查 +cd frontend && npm run type-check:strict +cd frontend && npm run lint +npm test +``` + +**处理错误**： +- 类型检查失败 → 尝试自动修复（添加类型注解） +- Lint 失败 → 运行 `eslint --fix` +- 测试失败 → 询问是否跳过 + +### 步骤 3：生成 Commit Message + +分析 Git diff 和修改的文件： + +```javascript +// 检查修改类型 +const hasNewFeatures = diff.includes('export') || diff.includes('function') +const hasFixes = diff.includes('fix') || diff.includes('bug') +const hasDocs = changedFiles.some(f => f.endsWith('.md')) +const hasTypes = changedFiles.some(f => f.match(/\.(ts|tsx)$/)) + +// 确定类型 +let type = 'chore' +let scope = '' + +if (hasNewFeatures) type = 'feat' +else if (hasFixes) type = 'fix' +else if (hasDocs) type = 'docs' +else if (hasTypes) scope = 'types' + +// 从 diff 中提取关键信息 +const subject = extractSubjectFromDiff(diff) + +// 生成 message +const message = `${type}(${scope}): ${subject}` +``` + +### 步骤 4：提交和推送 +```bash +git add -A +git commit -m "$COMMIT_MESSAGE" +git push origin $(git branch --show-current) +``` + +### 步骤 5：询问下一步 +``` +✅ 代码已提交并推送 + +下一步操作： +1. 合并到 develop 分支 +2. 创建 Pull Request +3. 触发基础设施自动化升级 +4. 结束工作流 + +选择操作（输入数字）： +``` + +## 🔧 冲突解决策略 + +### 自动解决规则 + +1. **package.json** + - 合并所有 `scripts`、`dependencies`、`devDependencies` + - 保留双方的键值对 + +2. **代码文件 (*.ts/*.tsx)** + - 如果冲突涉及 `console.log` vs `logger.*` → 采用 logger 版本 + - 如果冲突涉及 `any` vs `unknown` → 采用 unknown 版本 + - 如果冲突涉及类型注解 → 采用更严格的类型 + - 其他情况 → 询问用户 + +3. **配置文件 (*.json)** + - 尝试合并内容 + - 失败则询问用户 + +4. **文档文件 (*.md)** + - 采用当前分支版本（--ours） + +### 冲突解决流程 + +```bash +# 1. 列出冲突文件 +git diff --name-only --diff-filter=U + +# 2. 对每个冲突文件应用规则 +for file in conflicted_files: + determine_strategy(file) + apply_resolution(file) + +# 3. 验证解决 +git status + +# 4. 完成合并 +git commit --no-edit +``` + +## 💡 智能决策 + +### Commit Message 生成示例 + +输入： +- 修改了 `src/types/config.ts`（添加新类型） +- 修改了 `src/components/ConfigEditor.tsx`（使用新类型） +- 修改了 `README.md`（更新文档） + +输出： +``` +feat(types): 添加 ModuleConfigItems 类型定义 + +- 新增 ModuleConfigItems 接口 +- ConfigEditor 使用新的类型系统 +- 更新文档说明 +``` + +### 冲突解决示例 + +输入：`package.json` 冲突 +```json +// Base +{ + "scripts": { "test": "jest" } +} + +// Ours +{ + "scripts": { "test": "jest", "lint": "eslint" } +} + +// Theirs +{ + "scripts": { "test": "jest", "typecheck": "tsc" } +} +``` + +输出： +```json +{ + "scripts": { + "test": "jest", + "lint": "eslint", + "typecheck": "tsc" + } +} +``` + +## ⚙️ 配置 + +在项目根目录创建 `.workflow-config.json`： + +```json +{ + "mainBranch": "main", + "developBranch": "develop", + "featureBranchPrefix": "feat/", + "infraBranchPrefix": "infra/", + + "checks": { + "typeCheck": { + "enabled": true, + "command": "cd frontend && npm run type-check:strict", + "autoFix": true + }, + "lint": { + "enabled": true, + "command": "cd frontend && npm run lint", + "autoFix": true + }, + "test": { + "enabled": false, + "command": "npm test" + } + }, + + "autoMerge": { + "enabled": true, + "targetBranch": "develop", + "requireApproval": false + }, + + "conflictResolution": { + "packageJson": "merge", + "codeFiles": "infra-priority", + "docs": "ours", + "config": "merge" + } +} +``` + +## 🎨 交互示例 + +### 示例 1：每日工作流 + +**User**: "下班了" + +**Claude**: +``` +🌅 下班时间到！开始执行每日工作流... + +📊 当前状态： +分支：feat/config-system-optimization +未提交更改：3 个文件 + + frontend/src/types/config-system.ts (新增 50 行) + + frontend/src/utils/configItemSort.ts (新增 70 行) + + CLAUDE.md (修改) + +🔍 步骤 1：代码质量检查 +✓ 类型检查通过（2.3s） +✓ Lint 通过（1.1s） + +📝 步骤 2：提交更改 +分析更改内容... + - 新增类型定义 + - 新增工具函数 + - 更新文档 + +自动生成的 commit message： +feat(config): 添加配置项排序功能 + +- 新增 ModuleConfigItems 类型定义 +- 新增 configItemSort 工具函数 +- 更新 CLAUDE.md 文档 + +是否使用此 commit message？(y/n/edit) +``` + +**User**: "y" + +**Claude**: +``` +✓ 提交成功：abc1234 + +📤 步骤 3：推送到远程 +✓ 推送成功 + +🎯 步骤 4：下一步操作 +1. 合并到 develop 分支 +2. 创建 Pull Request +3. 触发基础设施自动化升级 +4. 结束工作流 + +选择操作（输入数字）： +``` + +### 示例 2：解决冲突 + +**User**: "/merge-develop" + +**Claude**: +``` +🔄 正在合并到 develop... + +⚠️ 检测到冲突！ + +冲突文件（2）： +1. frontend/package.json + └─ npm scripts 冲突 + +2. frontend/src/utils/logger.ts + └─ console.log vs logger.debug + +🔍 分析并解决冲突： + +1. frontend/package.json + 冲突类型：配置合并 + 解决策略：合并双方 scripts + ✓ 自动解决 + + 合并结果： + { + "scripts": { + "test": "jest", + "lint": "eslint", ← 来自 ours + "typecheck": "tsc" ← 来自 theirs + } + } + +2. frontend/src/utils/logger.ts + 冲突类型：代码替换 + 解决策略：采用 theirs (logger 版本) + ✓ 自动解决 + +✓ 所有冲突已自动解决 + +是否继续合并？(y/n) +``` + +## 📚 扩展命令 + +### `/create-branch ` +创建新分支 + +```bash +# 类型：feat, fix, docs, infra, refactor +git checkout develop +git pull origin develop +git checkout -b / +git push -u origin / +``` + +### `/cleanup-branches` +清理已合并的分支 + +```bash +# 删除本地已合并分支 +git branch --merged | grep -v "develop\|main" | xargs git branch -d + +# 清理远程已合并分支 +git remote prune origin +``` + +### `/show-workflow-status` +显示工作流状态 + +```bash +echo "=== 工作流状态 ===" +echo "当前分支: $(git branch --show-current)" +echo "与上游的差异:" +git log HEAD@{u}..HEAD --oneline || echo "无本地提交" +git log HEAD..HEAD@{u} --oneline || echo "无远程提交" +``` + +## ⚠️ 注意事项 + +1. **测试环境**：首次使用建议在测试分支验证 +2. **备份重要更改**：工作流会自动提交，确保重要更改已保存 +3. **网络连接**：推送操作需要网络连接 +4. **权限检查**：确保有推送到远程仓库的权限 +5. **冲突审查**：自动解决的冲突应在合并后检查 + +## 🐛 错误处理 + +### 类型检查失败 +``` +❌ 类型检查失败（3 个错误） + +frontend/src/utils/logger.ts:45:5 + error TS2322: Type 'unknown' is not assignable to type 'string' + +💡 建议操作： +1. 运行自动类型修复（/auto-fix-types） +2. 手动修复后重试 +3. 暂时跳过检查（不推荐） + +选择操作（输入数字）： +``` + +### 推送失败 +``` +❌ 推送失败 + +错误：remote rejected (fetch first） +原因：远程有新提交，需要拉取 + +💡 建议操作： +1. 拉取并 rebase：git pull --rebase +2. 查看差异：git fetch && git diff HEAD@{u} +3. 强制推送（危险）：git push --force + +选择操作（输入数字）： +``` + +## 🎯 使用建议 + +1. **每日使用**：开发完成后使用 `/daily-workflow` +2. **定期同步**：每天开始开发前使用 `/sync-branch` +3. **冲突不慌**：遇到冲突使用 `/resolve-conflicts` +4. **保持简洁**：commit message 应简洁明了 +5. **审查合并**：合并前检查待合并的提交 + +--- + +**版本**: 1.0.0 +**更新日期**: 2026-01-15 +**作者**: Claude & 项目开发者 +``` + +--- + +## 实施指南 + +### 步骤 1：创建 Skill 文件 + +在目标项目中创建： + +```bash +# 目录结构 +project/ +├── .skills/ +│ └── auto-dev-workflow/ +│ └── skill.md # 复制上面的 Prompt 内容 +├── .workflow-config.json # 可选：自定义配置 +└── ... +``` + +### 步骤 2：测试基础功能 + +```bash +# 测试 1：显示分支状态 +/branch-status + +# 测试 2：快速提交 +echo "# test" >> README.md +/quick-commit + +# 测试 3：解决冲突（如果有） +/resolve-conflicts +``` + +### 步骤 3：配置项目 + +创建 `.workflow-config.json`： + +```json +{ + "developBranch": "main", + "checks": { + "typeCheck": { + "enabled": true, + "command": "npm run type-check" + }, + "lint": { + "enabled": true, + "command": "npm run lint" + } + } +} +``` + +### 步骤 4：日常使用 + +```bash +# 早上：同步代码 +/sync-branch + +# 开发中... + +# 下班前：完成工作流 +/daily-workflow +``` + +--- + +## 最佳实践 + +### 1. 分支管理 + +```bash +# 功能分支命名 +feat/ # 新功能 +fix/ # bug 修复 +docs/ # 文档 +infra/ # 基础设施 +refactor/ # 重构 +``` + +### 2. Commit Message 规范 + +``` +(): + + + +