aigroup-workflow 2.1.1 → 2.2.0

package/skills/workflow/brainstorming/visual-companion.md

@@ -0,0 +1,287 @@
+# Visual Companion Guide
+
+Browser-based visual brainstorming companion for showing mockups, diagrams, and options.
+
+## When to Use
+
+Decide per-question, not per-session. The test: **would the user understand this better by seeing it than reading it?**
+
+**Use the browser** when the content itself is visual:
+
+- **UI mockups** — wireframes, layouts, navigation structures, component designs
+- **Architecture diagrams** — system components, data flow, relationship maps
+- **Side-by-side visual comparisons** — comparing two layouts, two color schemes, two design directions
+- **Design polish** — when the question is about look and feel, spacing, visual hierarchy
+- **Spatial relationships** — state machines, flowcharts, entity relationships rendered as diagrams
+
+**Use the terminal** when the content is text or tabular:
+
+- **Requirements and scope questions** — "what does X mean?", "which features are in scope?"
+- **Conceptual A/B/C choices** — picking between approaches described in words
+- **Tradeoff lists** — pros/cons, comparison tables
+- **Technical decisions** — API design, data modeling, architectural approach selection
+- **Clarifying questions** — anything where the answer is words, not a visual preference
+
+A question *about* a UI topic is not automatically a visual question. "What kind of wizard do you want?" is conceptual — use the terminal. "Which of these wizard layouts feels right?" is visual — use the browser.
+
+## How It Works
+
+The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
+
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, selection indicator, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+
+## Starting a Session
+
+```bash
+# Start server with persistence (mockups saved to project)
+scripts/start-server.sh --project-dir /path/to/project
+
+# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
+#           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
+#           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
+```
+
+Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
+
+**Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
+
+**Note:** Pass the project root as `--project-dir` so mockups persist in `.superpowers/brainstorm/` and survive server restarts. Without it, files go to `/tmp` and get cleaned up. Remind the user to add `.superpowers/` to `.gitignore` if it's not already there.
+
+**Launching the server by platform:**
+
+**Claude Code (macOS / Linux):**
+```bash
+# Default mode works — the script backgrounds the server itself
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Claude Code (Windows):**
+```bash
+# Windows auto-detects and uses foreground mode, which blocks the tool call.
+# Use run_in_background: true on the Bash tool call so the server survives
+# across conversation turns.
+scripts/start-server.sh --project-dir /path/to/project
+```
+When calling this via the Bash tool, set `run_in_background: true`. Then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
+
+**Codex:**
+```bash
+# Codex reaps background processes. The script auto-detects CODEX_CI and
+# switches to foreground mode. Run it normally — no extra flags needed.
+scripts/start-server.sh --project-dir /path/to/project
+```
+
+**Gemini CLI:**
+```bash
+# Use --foreground and set is_background: true on your shell tool call
+# so the process survives across turns
+scripts/start-server.sh --project-dir /path/to/project --foreground
+```
+
+**Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
+
+If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
+
+```bash
+scripts/start-server.sh \
+  --project-dir /path/to/project \
+  --host 0.0.0.0 \
+  --url-host localhost
+```
+
+Use `--url-host` to control what hostname is printed in the returned URL JSON.
+
+## The Loop
+
+1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
+   - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
+   - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
+   - **Never reuse filenames** — each screen gets a fresh file
+   - Use Write tool — **never use cat/heredoc** (dumps noise into terminal)
+   - Server automatically serves the newest file
+
+2. **Tell user what to expect and end your turn:**
+   - Remind them of the URL (every step, not just first)
+   - Give a brief text summary of what's on screen (e.g., "Showing 3 layout options for the homepage")
+   - Ask them to respond in the terminal: "Take a look and let me know what you think. Click to select an option if you'd like."
+
+3. **On your next turn** — after the user responds in the terminal:
+   - Read `$STATE_DIR/events` if it exists — this contains the user's browser interactions (clicks, selections) as JSON lines
+   - Merge with the user's terminal text to get the full picture
+   - The terminal message is the primary feedback; `state_dir/events` provides structured interaction data
+
+4. **Iterate or advance** — if feedback changes current screen, write a new file (e.g., `layout-v2.html`). Only move to the next question when the current step is validated.
+
+5. **Unload when returning to terminal** — when the next step doesn't need the browser (e.g., a clarifying question, a tradeoff discussion), push a waiting screen to clear the stale content:
+
+   ```html
+   <!-- filename: waiting.html (or waiting-2.html, etc.) -->
+   <div style="display:flex;align-items:center;justify-content:center;min-height:60vh">
+     <p class="subtitle">Continuing in terminal...</p>
+   </div>
+   ```
+
+   This prevents the user from staring at a resolved choice while the conversation has moved on. When the next visual question comes up, push a new content file as usual.
+
+6. Repeat until done.
+
+## Writing Content Fragments
+
+Write just the content that goes inside the page. The server wraps it in the frame template automatically (header, theme CSS, selection indicator, and all interactive infrastructure).
+
+**Minimal example:**
+
+```html
+<h2>Which layout works better?</h2>
+<p class="subtitle">Consider readability and visual hierarchy</p>
+
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Single Column</h3>
+      <p>Clean, focused reading experience</p>
+    </div>
+  </div>
+  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+    <div class="letter">B</div>
+    <div class="content">
+      <h3>Two Column</h3>
+      <p>Sidebar navigation with main content</p>
+    </div>
+  </div>
+</div>
+```
+
+That's it. No `<html>`, no CSS, no `<script>` tags needed. The server provides all of that.
+
+## CSS Classes Available
+
+The frame template provides these CSS classes for your content:
+
+### Options (A/B/C choices)
+
+```html
+<div class="options">
+  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+    <div class="letter">A</div>
+    <div class="content">
+      <h3>Title</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+**Multi-select:** Add `data-multiselect` to the container to let users select multiple options. Each click toggles the item. The indicator bar shows the count.
+
+```html
+<div class="options" data-multiselect>
+  <!-- same option markup — users can select/deselect multiple -->
+</div>
+```
+
+### Cards (visual designs)
+
+```html
+<div class="cards">
+  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+    <div class="card-image"><!-- mockup content --></div>
+    <div class="card-body">
+      <h3>Name</h3>
+      <p>Description</p>
+    </div>
+  </div>
+</div>
+```
+
+### Mockup container
+
+```html
+<div class="mockup">
+  <div class="mockup-header">Preview: Dashboard Layout</div>
+  <div class="mockup-body"><!-- your mockup HTML --></div>
+</div>
+```
+
+### Split view (side-by-side)
+
+```html
+<div class="split">
+  <div class="mockup"><!-- left --></div>
+  <div class="mockup"><!-- right --></div>
+</div>
+```
+
+### Pros/Cons
+
+```html
+<div class="pros-cons">
+  <div class="pros"><h4>Pros</h4><ul><li>Benefit</li></ul></div>
+  <div class="cons"><h4>Cons</h4><ul><li>Drawback</li></ul></div>
+</div>
+```
+
+### Mock elements (wireframe building blocks)
+
+```html
+<div class="mock-nav">Logo | Home | About | Contact</div>
+<div style="display: flex;">
+  <div class="mock-sidebar">Navigation</div>
+  <div class="mock-content">Main content area</div>
+</div>
+<button class="mock-button">Action Button</button>
+<input class="mock-input" placeholder="Input field">
+<div class="placeholder">Placeholder area</div>
+```
+
+### Typography and sections
+
+- `h2` — page title
+- `h3` — section heading
+- `.subtitle` — secondary text below title
+- `.section` — content block with bottom margin
+- `.label` — small uppercase label text
+
+## Browser Events Format
+
+When the user clicks options in the browser, their interactions are recorded to `$STATE_DIR/events` (one JSON object per line). The file is cleared automatically when you push a new screen.
+
+```jsonl
+{"type":"click","choice":"a","text":"Option A - Simple Layout","timestamp":1706000101}
+{"type":"click","choice":"c","text":"Option C - Complex Grid","timestamp":1706000108}
+{"type":"click","choice":"b","text":"Option B - Hybrid","timestamp":1706000115}
+```
+
+The full event stream shows the user's exploration path — they may click multiple options before settling. The last `choice` event is typically the final selection, but the pattern of clicks can reveal hesitation or preferences worth asking about.
+
+If `$STATE_DIR/events` doesn't exist, the user didn't interact with the browser — use only their terminal text.
+
+## Design Tips
+
+- **Scale fidelity to the question** — wireframes for layout, polish for polish questions
+- **Explain the question on each page** — "Which layout feels more professional?" not just "Pick one"
+- **Iterate before advancing** — if feedback changes current screen, write a new version
+- **2-4 options max** per screen
+- **Use real content when it matters** — for a photography portfolio, use actual images (Unsplash). Placeholder content obscures design issues.
+- **Keep mockups simple** — focus on layout and structure, not pixel-perfect design
+
+## File Naming
+
+- Use semantic names: `platform.html`, `visual-style.html`, `layout.html`
+- Never reuse filenames — each screen must be a new file
+- For iterations: append version suffix like `layout-v2.html`, `layout-v3.html`
+- Server serves newest file by modification time
+
+## Cleaning Up
+
+```bash
+scripts/stop-server.sh $SESSION_DIR
+```
+
+If the session used `--project-dir`, mockup files persist in `.superpowers/brainstorm/` for later reference. Only `/tmp` sessions get deleted on stop.
+
+## Reference
+
+- Frame template (CSS reference): `scripts/frame-template.html`
+- Helper script (client-side): `scripts/helper.js`

package/skills/workflow/documentation/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: documentation
+description: 在代码变更落地后更新受影响的文档，确保 docs/ 与代码一致。包含必更新清单、更新原则、文档传感器验证。
+---
+
+# 文档更新
+
+代码变更后的文档同步。**只更新受影响的文档**，不做无关改进。
+
+## 协调
+
+直接修改 `docs/` 下的文档；在 session `README.md`（或回报主会话）留变更笔记。完成后运行 `node scripts/hooks/dispatcher.cjs stop` 验证。
+
+## 必更新清单
+
+| 文档 | 触发条件 |
+|------|---------|
+| API 文档 | 接口变更（参数 / 返回值 / 错误码） |
+| README | 安装、使用方式变更 |
+| `docs/ARCHITECTURE.md` | 架构 / 模块边界 / 组件图变更 |
+| 模块 `CLAUDE.md` | 模块行为或入口变更 |
+
+## 按需更新
+
+| 文档 | 触发条件 |
+|------|---------|
+| 代码注释 | 复杂逻辑、关键算法、设计决策 |
+| 配置文档 | 配置项变更（新增 / 默认值 / 移除） |
+| 部署文档 | 部署流程或环境要求变更 |
+
+## 原则
+
+- 只改受影响的文档，不顺手做无关改进
+- 文档描述以代码实际行为为准
+- 删除已不存在功能的描述
+- 沿用现有文档的格式和语气
+
+## Red Flags
+
+| 信号 | 行动 |
+|------|------|
+| 测试未通过就更新文档 | 先完成测试 phase |
+| 文档与代码描述冲突 | 以代码为准修正文档 |
+| dispatcher stop 报错 | 先修 [FAIL] 再 ship |
+| 想跳过文档更新 | 检查是否真的零受影响文档 |

package/skills/workflow/entropy-management/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: entropy-management
+description: 定期维护代码库健康度。扫描架构漂移、过期文档、低质量代码，防止技术债积累。应在完成若干任务后或怀疑代码库退化时触发。
+---
+
+# 熵管理（Garbage Collection）
+
+## 概述
+
+AI Agent 会复制仓库中已有的模式——包括不好的模式。随着时间推移，这不可避免地导致漂移。
+手动清理不可持续。熵管理将清理系统化，定期执行，像垃圾回收一样防止技术债积累。
+
+**核心原则**：技术债是高利贷——持续小额偿还远优于积累后大规模清理。
+
+## 铁律
+
+```
+发现的问题不能只修一次——必须同时编码为约束，防止再次发生。
+每次熵管理运行结束后，必须更新质量评分和技术债追踪。
+```
+
+## 触发条件
+
+- 完成 5 个以上任务后（定期维护）
+- `code-reviewer` 审查中反复出现同类问题（模式漂移信号）
+- 用户主动要求代码库健康检查
+- 怀疑文档与代码不一致
+- 新成员加入前（确保仓库状态良好）
+
+## 执行流程
+
+### 第一阶段：自动化传感器扫描
+
+运行 Harness 传感器套件收集机器可检测的问题：
+
+```bash
+node scripts/hooks/dispatcher.cjs stop
+```
+
+记录所有 `[FAIL]` 和 `[WARN]` 项。
+
+### 第二阶段：推理型扫描
+
+自动化传感器无法覆盖的维度，需要人工/Agent 推理检查：
+
+#### 2.1 文档-代码一致性
+
+| 检查项 | 方法 |
+|--------|------|
+| CLAUDE.md 引用路径是否有效 | 逐条验证文件/目录存在 |
+| docs/ 文档描述是否匹配实际行为 | 抽样对比 |
+| SKILL.md 中的流程是否被实际遵循 | 回顾近期任务记录 |
+| 模板是否与当前实践一致 | 对比模板与近期产出 |
+
+#### 2.2 架构漂移检测
+
+| 检查项 | 方法 |
+|--------|------|
+| 是否有文件放在错误目录 | 检查目录约定是否被遵守 |
+| 是否有重复/冗余文件 | 搜索相似文件名和内容 |
+| 技能包结构是否一致 | 抽样检查 SKILL.md 格式 |
+| 协作产物是否在正确位置 | 检查 .orchestration/<session>/ 结构 |
+
+#### 2.3 质量回归检测
+
+| 检查项 | 方法 |
+|--------|------|
+| 近期审查中的高频问题 | 分析 .orchestration/<session>/code-reviewer/ |
+| 是否有被跳过的工作流阶段 | 检查产物完整性 |
+| 是否有"沉默的传感器"（从不报错） | 评估传感器有效性 |
+
+### 第三阶段：修复与编码
+
+对发现的问题分类处理：
+
+| 问题类型 | 处理方式 |
+|---------|---------|
+| 可快速修复的具体问题 | 立即修复（文档更新、文件移动等） |
+| 需要编码为约束的重复模式 | 在 `scripts/hooks/checks/` 加 check，让违规自动触发 [FAIL] |
+| 需要架构讨论的系统性问题 | 与用户讨论；动手前先达成共识 |
+
+### 第四阶段：沉淀与追踪
+
+把本次发现和处理沉淀到下列位置（按相关性挑，不必每次都全做）：
+
+- 反复出现的违规模式 → 在 `scripts/hooks/checks/` 加自动化 check
+- 团队级架构决策 / 新约束 → 写进 `docs/PROJECT_CONTEXT.md` 或 `docs/ARCHITECTURE.md`
+- 跨会话需要记得的代码模式 → 写进 `docs/rules/<topic>.md` 或 `docs/red-flags.md`
+- 用户当前活跃状态 / 个人偏好 → 让 Claude 写进原生 memory（`~/.claude/projects/<slug>/memory/`，自动加载）
+- 新增的危险信号 → 加入 `docs/red-flags.md`
+- 新增的强制规则 → 加入 `docs/rules/<topic>.md`
+
+## 产出清单
+
+每次熵管理运行后，应产出：
+
+```
+✅ dispatcher 扫描结果（node scripts/hooks/dispatcher.cjs stop）
+✅ 推理型扫描发现清单
+✅ 修复的问题列表
+✅ 新增的约束 / check / 规则文档（如有）
+```
+
+## Red Flags — 停下来
+
+| 信号 | 行动 |
+|------|------|
+| 传感器全部通过但直觉上代码库有问题 | 传感器覆盖不足，加新 check |
+| 修复一个漂移又发现三个 | 可能是架构问题，先与用户讨论再动 |
+| 反复出现同类问题但没有沉淀为约束 | 必须在 `scripts/hooks/checks/` 加自动检测 |
+
+## 关联技能
+
+- **verification-before-completion** — 修复后验证
+- **systematic-debugging** — 深入调查发现的问题

package/skills/workflow/executing-plans/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute all tasks, report when complete.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+**Note:** When subagents are available (Claude Code / Codex), prefer dispatching per `docs/rules/agents.md` over inline execution — fresh context per task and two-stage review yield higher-quality output. Use this skill when subagent dispatch is unavailable or batched checkpoint execution is preferred.
+
+## The Process
+
+### Step 1: Load and Review Plan
+1. Read plan file
+2. Review critically - identify any questions or concerns about the plan
+3. If concerns: Raise them with your human partner before starting
+4. If no concerns: Create TodoWrite and proceed
+
+### Step 2: Execute Tasks
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Complete Development
+
+After all tasks complete and verified:
+- Announce: "I'm using the finishing-a-development-branch skill to complete this work."
+- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
+- Follow that skill to verify tests, present options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## When to Revisit Earlier Steps
+
+**Return to Review (Step 1) when:**
+- Partner updates the plan based on your feedback
+- Fundamental approach needs rethinking
+
+**Don't force through blockers** - stop and ask.
+
+## Remember
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Reference skills when plan says to
+- Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks