zero-workspace 0.0.2

package/plugin/skills/bootstrapping-workspace/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: bootstrapping-workspace
+description: Use when workspace is created and needs capability selection and info node setup. Guides ZeroWorkspace startup flow after workspace_init.
+---
+
+# Bootstrapping Workspace
+
+## Announcement (MANDATORY)
+
+Before executing this skill, you MUST announce to the user:
+
+「我将使用 **工作区启动** 技能来初始化工作区、选择能力、创建信息节点。」
+
+This creates a commitment checkpoint. Proceed only after announcing.
+
+## Core Flow
+
+```
+workspace_init(scenario=?)
+    ↓
+capability_list()  ← Get recommended capabilities
+    ↓
+capability_select(infoType=?, selected=[...])  ← Create info node + capability children
+    ↓
+Execute capability tasks
+```
+
+## SOP
+
+### 1. Tell User WebUI URL
+
+The `webUrl` from workspace_init is the visualization interface. **MUST tell user**.
+
+```
+webUrl: http://localhost:port/workspace/ws-xxx
+```
+
+### 2. Call capability_list
+
+Get recommended capabilities for the scenario:
+
+```typescript
+capability_list({ scenario: "feature" })  // Pass scenario type
+```
+
+**Returns**:
+- `basePack`: Required capabilities (**ALL must be selected**)
+- `optionalPack`: Optional capabilities (user chooses)
+
+### 3. Show User and Ask for Selection
+
+**MUST** show capability list to user in natural dialogue:
+
+**Template**:
+```
+当前任务是「{用户目标}」，属于 **{scenario}** 场景。
+
+我将执行以下能力：
+- **{能力名}**: {在此任务语境下的具体作用}
+- **{能力名}**: {在此任务语境下的具体作用}
+
+除此之外，还可以选择：
+  a. **{能力名}** - {语境下描述}
+  b. **{能力名}** - {语境下描述}
+  c. **{能力名}** - {语境下描述}
+
+💡 推荐：{基于具体任务的推荐理由}
+
+需要添加哪些？（输入序号如 a、ab，或回车跳过）
+```
+
+**Example** (optimize scenario):
+```
+当前任务是「优化派发模式」，属于 **optimize** 场景。
+
+我将执行以下能力：
+- **意图对齐**: 明确你想优化的具体方面和期望效果
+- **上下文探索**: 分析当前派发模式的实现和依赖
+- **度量分析**: 建立当前性能基准，量化优化效果
+
+除此之外，还可以选择：
+  a. **诊断分析** - 深入分析现有问题的根因
+  b. **方案设计** - 设计具体的优化方案
+  c. **验证策略** - 制定测试用例确保优化有效
+
+💡 推荐：b（方案设计），研究优化通常需要输出具体方案
+
+需要添加哪些？（输入序号如 a、ab，或回车跳过）
+```
+
+**Rules**:
+- basePack: 直接说"我将执行"，不问用户
+- optionalPack: 用 **abc 序号**，方便用户输入
+- 描述: **根据任务语境定制**，不用通用描述
+- 推荐: 基于具体任务给出理由
+- **MUST** wait for user response before capability_select
+
+### 4. Call capability_select
+
+Select capabilities and create info node:
+
+```typescript
+capability_select({
+  workspaceId: "ws-xxx",
+  infoType: "info_collection",  // or "info_summary"
+  selected: ["intent_alignment", "context_discovery"]
+})
+```
+
+**infoType Selection**:
+
+| Type | Use When | Action |
+|------|----------|--------|
+| `info_collection` | Need active research: scan project, read docs | Read, explore, collect |
+| `info_summary` | Have info to organize: extract from conversation | Summarize, extract |
+
+### 5. Execute Capability Tasks (CRITICAL)
+
+**capability_select 返回 `actionRequired`，MUST 遵循其指示调用 Skill。**
+
+```
+capability_select 返回
+    ↓
+actionRequired: { type: "invoke_skill", skills: [...] }
+    ↓
+Skill(aligning-intent)  ← 第一个能力
+    ↓
+node_transition(action="start")
+    ↓
+按 Skill SOP 执行
+    ↓
+node_transition(action="complete")
+    ↓
+Skill(discovering-context)  ← 下一个能力
+    ↓
+...重复...
+```
+
+**执行规则**：
+
+| 步骤 | 动作 | 说明 |
+|------|------|------|
+| 1 | `Skill(xxx)` | 调用对应 Skill 获取 SOP |
+| 2 | `node_transition(action="start")` | 启动节点 |
+| 3 | 按 SOP 执行 | 遵循 Skill 的 SOP 步骤 |
+| 4 | `node_transition(action="complete")` | 完成节点 |
+
+**⚠️ 禁止事项**：
+- **NEVER** 跳过 Skill 调用直接 node_transition start
+- **NEVER** 在信息收集/总结阶段修改任何代码
+- **NEVER** 在能力节点中执行 Write/Edit/Update 操作
+
+**信息收集/总结阶段的职责边界**：
+
+| 允许 | 禁止 |
+|------|------|
+| Read、Search、Grep、Glob | Write、Edit、Update |
+| 分析代码、理解结构 | 修改代码、创建文件 |
+| 记录发现到 conclusion | 直接实现功能 |
+| 提出方案建议 | 执行方案 |
+
+**为什么必须调用 Skill？**
+- Skill 包含该能力的 SOP（标准操作流程）
+- Skill 定义了正确的执行步骤和检查清单
+- 不读 Skill = 不知道该能力的正确做法
+
+### 6. Continue Tracking in Workspace (CRITICAL)
+
+**Workspace is for the ENTIRE task lifecycle, not just info collection.**
+
+After info collection completes:
+
+```
+Info collection done
+    ↓
+Create planning/execution nodes for implementation
+    ↓
+Use log_append to record progress
+    ↓
+Complete nodes when tasks finish
+```
+
+**Rules**:
+- **MUST** create execution nodes for implementation tasks
+- **MUST** use `log_append` for progress updates, NOT TodoWrite
+- **NEVER** treat "info collection done" as "workspace usage done"
+- Workspace nodes = visible progress + history + dispatchable
+
+**Why this matters**:
+- TodoWrite is local-only, invisible in WebUI
+- Workspace nodes preserve full execution history
+- User expects to see ALL progress in workspace
+
+## Scenario-Capability Mapping
+
+| scenario | basePack | optionalPack |
+|----------|----------|--------------|
+| feature | intent_alignment, context_discovery | tech_research, solution_design, verification_strategy |
+| debug | intent_alignment, context_discovery, diagnosis | solution_design, verification_strategy |
+| optimize | intent_alignment, context_discovery, measurement_analysis | diagnosis, solution_design, verification_strategy |
+| summary | intent_alignment, context_discovery | - |
+| misc | intent_alignment | context_discovery, tech_research, measurement_analysis, diagnosis, solution_design, verification_strategy |
+
+## Mandatory Rules
+
+1. **NEVER skip capability_list** - Must get capability list first
+2. **NEVER manually node_create info node** - Must use capability_select
+3. **MUST tell user webUrl** - Only entry for user to view progress
+4. **MUST choose correct infoType** - Based on task nature
+5. **MUST show capabilities to user** - Ask for confirmation, never decide alone
+6. **MUST include all basePack** - selected must contain all basePack capabilities
+7. **MUST call Skill before node_transition start** - 每个能力节点启动前必须先调用对应 Skill
+8. **NEVER modify code in info phase** - 信息收集/总结阶段禁止 Write/Edit/Update
+9. **MUST follow Skill SOP** - Skill 定义了正确的执行流程，必须遵循
+
+## Red Flags
+
+When these appear, you may be skipping proper bootstrapping:
+
+1. **Jump to task directly** - Start working without capability selection
+2. **Forget webUrl** - User has no way to view workspace progress
+3. **Skip user confirmation** - Decide capabilities without asking
+4. **Wrong infoType** - Always use info_collection when info_summary is appropriate
+5. **Partial basePack** - Missing required capabilities from basePack
+6. **Use TodoWrite after info collection** - Should create workspace nodes instead
+7. **No execution nodes for implementation** - Workspace abandoned after info phase
+8. **Skip Skill, direct node_transition** - 没调用 Skill 就直接启动节点 ⚠️ 严重错误
+9. **Write/Edit in info phase** - 在信息收集阶段修改代码 ⚠️ 严重错误
+10. **Ignore actionRequired** - capability_select 返回的 actionRequired 被忽略
+
+## Anti-Patterns
+
+| Wrong | Right |
+|-------|-------|
+| node_create after workspace_init | capability_list first, then capability_select |
+| Skip capabilities, start task | Follow capability SOP |
+| Forget to tell webUrl | Tell user immediately |
+| Always use info_collection | Choose collection/summary based on scenario |
+| Decide capabilities yourself | Show user and ask |
+| Only include partial basePack | Include ALL basePack |
+| TodoWrite for implementation tasks | Create execution nodes in workspace |
+| Abandon workspace after info collection | Continue with planning/execution nodes |
+| node_transition start without Skill | Skill(xxx) first, then node_transition |
+| Write/Edit in info_collection node | Only Read/Search, record to conclusion |
+| Ignore actionRequired from capability_select | Follow actionRequired instructions exactly |
+
+## Common Rationalizations
+
+| Excuse | Why Wrong | Correct Action |
+|--------|-----------|----------------|
+| "User knows what capabilities they need" | User may not know all options | MUST show capabilities and ask |
+| "webUrl is in the output, user will see" | Output may be long, user may miss it | Explicitly tell user the webUrl |
+| "info_collection is safer default" | Wrong type wastes effort | Match infoType to task nature |
+| "basePack is just a suggestion" | basePack is REQUIRED, not optional | Include ALL basePack capabilities |
+| "I'll skip capability selection to save time" | Skipping leads to incomplete setup | 30s setup saves confusion later |
+| "Info collection is done, now just coding" | Workspace tracks full lifecycle | Create execution nodes for implementation |
+| "TodoWrite is faster for tracking" | TodoWrite is invisible to user | Use workspace nodes + log_append |
+| "I know what to do, don't need Skill" | Skill 定义了正确流程，你可能遗漏关键步骤 | 必须先调用 Skill 获取 SOP |
+| "Just a quick fix while exploring" | 信息收集阶段禁止修改，会破坏职责边界 | 记录发现，创建执行节点后再修改 |
+| "The change is obvious, no need for execution node" | 所有修改必须在执行节点中进行，确保可追踪 | 创建执行节点，按流程执行 |

package/plugin/skills/designing-solutions/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: designing-solutions
+description: Use when planning implementation approach for features or changes. Builds technical solutions, defines interfaces, data structures, and implementation paths.
+---
+
+# Designing Solutions
+
+## Announcement (MANDATORY)
+
+Before executing this skill, you MUST announce to the user:
+
+「我将使用 **方案设计** 技能来构建技术方案、定义接口和数据结构、规划实现路径。」
+
+This creates a commitment checkpoint. Proceed only after announcing.
+
+## Core Thinking
+
+**Architect** - Design before build. Good architecture enables good implementation.
+
+**YAGNI Ruthlessly** - You Aren't Gonna Need It. Remove unnecessary features from all designs. Simpler is better.
+
+**Incremental Validation** - Present design in sections, validate each before proceeding. Early correction beats late rework.
+
+**Recording**: Conversation output is invisible to users. You MUST record to workspace node. Standard: "If context is wiped now, can you recall discussion details from conclusion alone?"
+
+**Progressive Recording**: For complex designs, checkpoint after each major decision. `log_append` interface decisions before moving to data structures.
+
+## Typical Actions
+
+- Define interfaces
+- Design data structures
+- Plan implementation steps
+
+## SOP
+
+### 1. Define Boundaries
+
+**Goal**: Determine change scope and impact.
+
+- **Change scope**: Which modules/files to modify?
+- **Impact assessment**: Which callers affected?
+- **Unchanged parts**: What explicitly won't change?
+- **System boundary**: What system does/doesn't handle?
+
+**Output**: Change scope list (files, modules)
+
+**⏸️ User Validation**: Present boundaries to user. Ask: "这个变更范围对吗？有遗漏或需要排除的吗？" Wait for confirmation before proceeding.
+
+### 2. Interface Design
+
+**Goal**: Define input/output contracts.
+
+- **Public interfaces**:
+  - Function signatures (params, returns, exceptions)
+  - API endpoints (if any)
+  - Clear semantics, complete params
+- **Module interfaces**:
+  - Internal module collaboration
+  - Call relationships, data passing
+- **Backward compatibility**:
+  - Need to maintain compatibility?
+  - How to handle deprecated interfaces?
+
+**Output**: Interface definitions (TypeScript/code examples)
+
+**⚠️ Checkpoint**: After interface design, `log_append` the interface definitions before proceeding to data structures.
+
+**⏸️ User Validation**: Present interfaces to user. Ask: "接口设计合理吗？参数和返回值符合预期吗？" Wait for confirmation before proceeding.
+
+### 3. Data Structure Design
+
+**Goal**: Design core data models.
+
+- **Core types**:
+  - Main interfaces/types/classes
+  - Field meanings and constraints
+- **State management**:
+  - Where to store state?
+  - How to update state?
+- **Data validation**:
+  - Required vs optional fields
+  - Value range validation
+
+**Output**: Type definitions with comments
+
+**⏸️ User Validation**: Present data structures to user. Ask: "数据结构设计可以吗？字段是否完整？" Wait for confirmation before proceeding.
+
+### 4. Implementation Plan
+
+**Goal**: Define execution steps.
+
+- **YAGNI check** (FIRST):
+  - What can be removed without breaking core functionality?
+  - Is this feature truly needed NOW, or "might be useful later"?
+  - Can we simplify without losing value?
+- **Task breakdown**:
+  - Break into testable units
+  - Each step independently verifiable
+- **Execution order**:
+  - Dependencies between steps
+  - Recommended execution sequence
+- **Risk points**:
+  - Which steps are risky?
+  - What could go wrong?
+
+**Output**: Numbered implementation steps (after YAGNI pruning)
+
+**⏸️ User Validation**: Present implementation plan to user. Ask: "实现步骤清晰吗？顺序和风险点有问题吗？" Wait for confirmation before proceeding.
+
+### 4.5. Test & Observability Design (MANDATORY)
+
+**Goal**: Define verification strategy and logging requirements BEFORE implementation.
+
+#### Verification Strategy
+
+For each implementation step, define HOW to verify it:
+
+| Step | Verification | Format |
+|------|--------------|--------|
+| 核心功能 | 可运行的命令 | `[cmd] pytest tests/xxx.py` |
+| UI 变更 | 手动验证步骤 | `[manual] 打开页面 → 检查显示` |
+| 代码规范 | 代码检查 | `[check] 无 TODO/FIXME` |
+
+**Critical questions**:
+- **哪些功能必须有测试覆盖？** 核心业务逻辑、边界条件
+- **测试放在哪里？** 现有测试目录结构
+- **无测试框架时怎么办？** `[manual]` 或 `[check]` 替代
+
+#### Logging Requirements
+
+定义实现中需要的日志点：
+
+| 场景 | 日志需求 |
+|------|----------|
+| **关键流程** | 入口、出口、状态变更 |
+| **错误场景** | 错误类型、上下文、恢复动作 |
+| **调试信息** | 中间状态、参数值 |
+
+**Critical questions**:
+- **哪些操作需要日志？** 用户操作、系统事件、异常
+- **日志级别？** debug/info/warn/error 分别用在哪里
+- **日志内容？** 需要记录哪些上下文信息
+
+**Output**: Verification table + Logging requirements
+
+**⚠️ Iron Law**: NO IMPLEMENTATION STEP WITHOUT VERIFICATION METHOD
+
+**⏸️ User Validation**: Present test & observability design. Ask: "验证方式和日志需求合理吗？" Wait for confirmation before proceeding.
+
+### 5. Record to Workspace (MANDATORY)
+
+After design, MUST record to workspace node:
+
+**Recording locations**:
+| Content | Location | Tool |
+|---------|----------|------|
+| Key conclusions (brief) | conclusion | node_update |
+| Scope, interfaces, steps | notes | node_update |
+| Full design doc (>200 lines) | MEMO | memo_create + node_reference |
+
+**NEVER hardcode MEMO IDs** in text like "见 MEMO#xxx". Use `node_reference` to link.
+
+**Reference rules** (design tasks SHOULD include):
+- Affected files/modules in scope
+- Dependencies being relied upon
+- Existing patterns being followed
+- Core principle: references help reviewers understand context
+
+**Conclusion template** (brief):
+```
+[问题] + [方案概述] + [影响范围] + [步骤数]
+```
+
+**Notes template** (detailed):
+```
+**Problem**: [what to solve]
+**Approach**: [high-level]
+**Scope**: [files/modules]
+**Key Interfaces**:
+- function(param): Return
+**Key Types**:
+- TypeName { field: type }
+**Implementation Steps**:
+1. Step 1 - [verification]
+2. Step 2 - [verification]
+**Risks**: [identified risks]
+```
+
+**Output**: node_update called with conclusion + notes
+
+### 6. Present to User (MANDATORY)
+
+After recording, MUST present design to user:
+
+1. **Output summary**: Show design using Output Template
+2. **Wait for confirmation**: Ask user if design approach is acceptable
+3. **NEVER proceed directly**: Do NOT start implementation without user approval
+
+**Output**: Design presented, user confirmation received
+
+## Checklist
+
+### Boundaries
+- [ ] Change scope identified
+- [ ] Impact assessed
+- [ ] Unchanged parts documented
+- [ ] System boundaries clear
+
+### Interfaces
+- [ ] Public interfaces defined
+- [ ] Module interfaces defined
+- [ ] Compatibility considered
+
+### Data Structures
+- [ ] Core types designed
+- [ ] State management planned
+- [ ] Validation rules defined
+
+### Implementation
+- [ ] **YAGNI applied**: Unnecessary features removed
+- [ ] Tasks broken down
+- [ ] Order determined
+- [ ] Risks identified
+
+### Test & Observability (MANDATORY)
+- [ ] **Verification defined**: Each step has `[cmd]`, `[manual]`, or `[check]`
+- [ ] **Critical tests identified**: Core logic has test coverage plan
+- [ ] **Logging planned**: Key flows have logging requirements
+- [ ] **Error logging**: Error scenarios have context capture
+
+### Incremental Validation (MANDATORY)
+- [ ] **Boundaries confirmed**: User validated change scope
+- [ ] **Interfaces confirmed**: User validated interface design
+- [ ] **Data structures confirmed**: User validated type definitions
+- [ ] **Plan confirmed**: User validated implementation steps
+- [ ] **Test & observability confirmed**: User validated verification strategy and logging
+
+### Recording (MANDATORY)
+- [ ] **Conclusion written**: Brief summary in node conclusion
+- [ ] **Notes written**: Scope, interfaces, steps in node notes
+- [ ] **MEMO linked**: Long content in MEMO, linked via node_reference (not hardcoded ID)
+- [ ] **Wipe test**: If context wiped now, can recall details from recorded content?
+
+### Long Content Protection
+- [ ] **Checkpoint hit**: Logged interface design before data structures
+- [ ] **Scope referenced**: Affected files/modules listed
+- [ ] **Dependencies noted**: Key dependencies documented
+
+## Output Template
+
+```markdown
+### Solution Overview
+**Problem**: [What to solve]
+**Approach**: [High-level approach]
+
+### Boundaries
+**Change scope**:
+- [File 1]: [Change description]
+- [File 2]: [Change description]
+
+**Impact**: [Affected modules/callers]
+**Not changing**: [Explicit exclusions]
+
+### Interfaces
+
+#### Public Interface
+```typescript
+function example(param: Type): ReturnType
+```
+
+#### Module Interface
+[Internal contracts]
+
+### Data Structures
+
+```typescript
+interface CoreType {
+  field1: string;  // [description]
+  field2: number;  // [description]
+}
+```
+
+### Implementation Plan
+
+1. **Step 1**: [Description]
+   - Files: [list]
+   - Verification: [how to verify]
+
+2. **Step 2**: [Description]
+   - Files: [list]
+   - Verification: [how to verify]
+
+### Test & Observability
+
+#### Verification Strategy
+| Step | Verification | Method |
+|------|--------------|--------|
+| Step 1 | [what to verify] | `[cmd] xxx` |
+| Step 2 | [what to verify] | `[manual] xxx` |
+
+#### Logging Requirements
+| Flow | Log Points | Level |
+|------|------------|-------|
+| [operation] | entry, exit, error | info/error |
+
+### Risks
+- **Risk 1**: [Description] - Mitigation: [approach]
+```
+
+## Red Flags
+
+1. **No boundaries** - Start coding without scoping
+2. **Interface changes mid-way** - Design interfaces after implementation
+3. **Missing states** - Forget state management design
+4. **No breakdown** - Giant task without steps
+5. **Silent execution** - Complete design, then immediately start implementing without showing user
+6. **Skip checkpoint** - Complete complex design without intermediate logging
+7. **Skip incremental validation** - Output entire design without pausing for user feedback at each step
+8. **Batch presentation** - Present all sections at once instead of section by section
+9. **YAGNI violation** - Adding "might be useful" features, over-engineering for hypothetical future needs
+10. **No verification plan** - Implementation steps without `[cmd]`/`[manual]`/`[check]` methods
+11. **No logging design** - Code changes without considering observability needs
+
+## Mandatory Rules
+
+1. **MUST define boundaries first** - NEVER start coding without knowing change scope
+2. **MUST design interfaces before implementation** - Changing interfaces mid-way causes rework
+3. **MUST check existing patterns** - Design must fit existing codebase, not fight it
+4. **MUST break down into steps** - No giant tasks without clear milestones
+5. **NEVER create hidden dependencies** - All coupling must be explicit and documented
+6. **MUST present before proceed** - After design, NEVER start implementation directly. Present design, wait for user approval
+7. **MUST validate incrementally** - Present each section, get user confirmation before next section. Early correction beats late rework
+8. **MUST apply YAGNI** - Before finalizing design, ask "What can we remove?" Simpler designs are better designs
+9. **MUST define verification for each step** - Every implementation step needs `[cmd]`, `[manual]`, or `[check]`
+10. **MUST plan logging** - Key operations, errors, and state changes need log points
+
+## Anti-Patterns
+
+| Pattern | Wrong | Right |
+|---------|-------|-------|
+| **Code first** | Jump into coding | Design interfaces first |
+| **Over-design** | Perfect design for simple task | Match design effort to complexity |
+| **Ignore existing** | Design without checking existing code | Understand existing patterns first |
+| **Hidden coupling** | Create implicit dependencies | Make dependencies explicit |
+| **Batch dump** | Output entire design then ask "OK?" | Present section by section, validate each |
+| **Test afterthought** | "We'll figure out testing later" | Define verification in design phase |
+| **Silent code** | No logs, debug by guessing | Plan log points for key operations |
+
+## Common Rationalizations
+
+| Excuse | Why Wrong | Correct Action |
+|--------|-----------|----------------|
+| "This is simple, no design needed" | Simple tasks still need scope definition | Define boundaries, even briefly |
+| "I'll refine the interface as I go" | Interface changes cascade to all callers | Design interface upfront |
+| "I know the codebase well enough" | Memory is unreliable, patterns may have changed | Check existing code before designing |
+| "One big task is faster than splitting" | Big tasks fail more, are harder to verify | Break into testable units |
+| "Design takes too long" | No design = more rework later | 30 min design saves 3 hour fixes |
+| "Asking after each section is slow" | Late correction costs 10x early correction | Validate incrementally, save rework |
+| "User will see the full picture better" | User drowns in details, misses problems | Small sections are easier to review |
+| "We might need this later" | 90% of "later" never comes | Build what's needed NOW, extend later |
+| "It's easy to add while we're here" | Easy to add = easy to add later | YAGNI - don't add until needed |
+| "Testing is the executor's job" | Executor can't test what wasn't designed | Define verification in design phase |
+| "Logs clutter the code" | Silent code = blind debugging | Strategic logs save hours of debugging |