@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-design/skills/workflow-ui-spec/assets/ui-spec-template.md

@@ -0,0 +1,244 @@
+# UI-SPEC 模板
+
+> 本模板由 `workflow-ui-spec` 技能填充。所有 `{占位符}` 由技能自动替换，请勿手动编辑。
+
+---
+
+# UI 设计规范 — {功能名}
+
+**设计来源**: {设计稿路径/截图说明}
+**解析日期**: {日期}
+**上游依赖**: `.planning/features/{功能名}/功能点梳理.md`
+
+---
+
+## 1. 设计来源
+
+| 项目 | 内容 |
+|------|------|
+| 设计稿来源 | {截图/Figma/蓝湖/手动描述} |
+| 提供人 | {用户/设计师} |
+| 设计版本 | {版本号或日期} |
+| 解析方式 | {AI 视觉分析 / 用户口述 / PRD 文字提取} |
+
+---
+
+## 2. 页面清单与布局
+
+<!-- 对每个页面/弹窗，输出布局结构 -->
+
+### 2.1 {页面1名称}
+
+- **路由路径**: `{路径}`
+- **页面类型**: {主页面 / 弹窗 / 抽屉 / 半屏}
+- **布局模式**: {单列 / 双列 / 卡片列表 / 表单 / 自定义}
+
+```
+{页面名称}
+├── 顶部导航区
+│   ├── 返回按钮: {是否显示}
+│   ├── 标题: "{标题文字}"
+│   └── 右侧操作: {操作按钮}
+├── 主内容区 (scroll)
+│   ├── 区域A: {名称}
+│   │   ├── {子元素1}
+│   │   └── {子元素2}
+│   ├── 区域B: {名称}
+│   │   └── ...
+│   └── ...
+├── 底部操作区 (fixed)
+│   └── {按钮/输入框等}
+└── 弹窗/浮层
+    └── {弹窗名称}: {触发条件}
+```
+
+### 2.2 {页面2名称}
+
+...
+
+---
+
+## 3. 组件树与复用分析
+
+### 3.1 新增组件
+
+| 组件名 | 层级 | 所属页面 | 类型 | 描述 |
+|--------|------|---------|------|------|
+| {ComponentName} | {父组件} | {页面} | {业务/基础} | {一句话描述} |
+
+**组件详细设计**：
+
+#### {ComponentName}
+```
+{ComponentName}
+├── Props:
+│   ├── {prop1}: {type} — {描述}
+│   └── {prop2}: {type} — {描述}
+├── Emits:
+│   ├── {event1}: {payload} — {触发时机}
+│   └── {event2}: {payload} — {触发时机}
+├── Slots:
+│   └── {slot1}: {用途}
+├── 状态:
+│   ├── default: {描述}
+│   ├── loading: {骨架屏/loading 动画}
+│   ├── empty: {空数据插图+文案}
+│   ├── error: {错误提示+重试按钮}
+│   └── disabled: {置灰样式}
+└── 依赖:
+    ├── 子组件: {组件列表}
+    └── API调用: {接口名称}
+```
+
+### 3.2 修改现有组件
+
+| 现有组件 | 路径 | 修改内容 | 影响范围 |
+|----------|------|---------|---------|
+| {组件名} | `{文件路径}` | {具体修改点} | {受影响的页面} |
+
+### 3.3 复用现有组件
+
+| 设计组件 | 复用代码组件 | 路径 | 匹配度 | 备注 |
+|---------|------------|------|--------|------|
+| {设计名} | {代码组件名} | `{路径}` | 完全/需扩展 | {差异说明} |
+
+---
+
+## 4. 设计 Token
+
+### 4.0 来源分层与优先级
+
+| 来源类型 | 来源文件/依据 | 是否可直接用于实现 | 说明 |
+|----------|---------------|--------------------|------|
+| 设计稿事实 | {截图/Figma/蓝湖/用户已确认设计描述} | 是 | {明确来自设计稿的颜色、字号、间距、圆角、阴影等} |
+| 现有项目规范 | {现有代码变量/组件库/.context/spec/design/tokens/project-tokens.md} | 是 | {与现有变量或组件规则对齐的 token} |
+| 推荐 - 待拍板 | {.context/spec/design/recommendations 或 ui-ux-pro-max 查询结果} | 否 | {仅作为候选方案，需写入待确认事项} |
+
+合并优先级：用户拍板/设计稿事实/需求基线 > 现有代码与项目 token > 项目级已确认 token > 推荐 - 待拍板。
+
+### 4.1 颜色
+
+| Token 名 | 色值 | 用途 | 来源类型 | 已有变量 | 新增 | 状态 |
+|----------|------|------|----------|---------|------|------|
+| `--color-primary` | `#XXX` | 主色调 | 设计稿事实/现有项目规范/推荐 - 待拍板 | `$primary-color` | 否 | 已确认/待确认 |
+| `--color-xxx` | `#XXX` | {描述} | {来源类型} | — | **是** | {状态} |
+
+### 4.2 字体与字号
+
+| Token 名 | 字号 | 字重 | 行高 | 用途 | 来源类型 | 已有变量 | 状态 |
+|----------|------|------|------|------|----------|---------|------|
+| `--font-title` | `18px` | `600` | `1.4` | 页面标题 | {来源类型} | `$font-size-lg` | {状态} |
+| `--font-body` | `14px` | `400` | `1.5` | 正文 | {来源类型} | `$font-size-base` | {状态} |
+
+### 4.3 间距
+
+| Token 名 | 值 | 用途 | 来源类型 | 已有变量 | 状态 |
+|----------|----|----|----------|---------|------|
+| `--spacing-xs` | `4px` | 极小间距 | {来源类型} | `$spacing-xs` | {状态} |
+| `--spacing-sm` | `8px` | 小间距 | {来源类型} | `$spacing-sm` | {状态} |
+| `--spacing-md` | `12px` | 中间距 | {来源类型} | `$spacing-md` | {状态} |
+| `--spacing-lg` | `16px` | 大间距 | {来源类型} | `$spacing-lg` | {状态} |
+
+### 4.4 圆角与阴影
+
+| Token 名 | 值 | 用途 | 来源类型 | 已有变量 | 状态 |
+|----------|----|----|----------|---------|------|
+| `--radius-sm` | `4px` | 小圆角 | {来源类型} | — | {状态} |
+| `--radius-md` | `8px` | 按钮/卡片 | {来源类型} | `$border-radius-base` | {状态} |
+| `--shadow-card` | `0 2px 8px rgba(...)` | 卡片投影 | {来源类型} | — | {状态} |
+
+### 4.5 动画/过渡
+
+| 场景 | 属性 | 时长 | 缓动函数 | 描述 |
+|------|------|------|---------|------|
+| 弹窗打开 | `opacity, transform` | `300ms` | `ease-out` | 从底部滑入 |
+| 按钮点击 | `transform: scale` | `150ms` | `ease` | 按压缩放反馈 |
+
+---
+
+## 5. 交互流程
+
+### 5.1 {流程1名称}
+
+```
+触发: {用户操作，如"点击'立即参与'按钮"}
+├── 步骤1: 按钮显示 loading 状态，防重复点击
+│   └── 状态: 按钮 disabled + spinner
+├── 步骤2: 调用 API: {接口名}（来自功能点梳理 FP-XXX）
+│   └── 状态: 全局 loading / 局部 loading
+├── 步骤3: 成功 → 跳转 {目标页面} / 弹窗 {弹窗名}
+│   └── 动画: {过渡动画描述}
+├── 步骤3: 失败 → 显示错误提示
+│   └── 状态: toast "{错误消息}" / 错误页面 + 重试按钮
+└── 终态: {最终 UI 状态}
+```
+
+### 5.2 {流程2名称}
+
+...
+
+---
+
+## 6. 状态覆盖矩阵
+
+| 页面/组件 | Loading | Empty | Error | Disabled | 权限限制 | 重复提交 | 网络异常 |
+|----------|---------|-------|-------|----------|---------|---------|---------|
+| {页面A} | 骨架屏 | "暂无数据"插图 | 错误页+重试 | — | 提示"无权限" | 按钮防抖 | 离线提示 |
+| {组件X} | spinner | — | toast | 置灰 | — | loading | — |
+
+说明：
+- `✓` / 具体方案 = 已覆盖
+- `—` = 不适用（该组件无此状态）
+
+---
+
+## 7. 多端差异
+
+<!-- 如果目标平台包含多端（小程序 + H5 + App），标注差异 -->
+
+| 差异点 | 小程序 | H5 | App | 说明 |
+|--------|--------|----|-----|------|
+| {差异项} | {表现} | {表现} | {表现} | {备注} |
+
+如果仅单端，写："本次仅涉及 {平台}，无多端差异。"
+
+---
+
+## 8. 待确认事项
+
+| 编号 | 事项 | 影响范围 | 优先级 | 阻塞 |
+|------|------|---------|--------|------|
+| UI-001 | {待确认内容} | {影响的页面/组件} | 高/中/低 | 是/否 |
+| UI-REC-001 | {来自推荐源的候选颜色/字体/布局/状态是否采纳} | {影响范围} | 高/中/低 | 是/否 |
+
+---
+
+## 9. 下游输入契约
+
+本 UI-SPEC 为以下文档提供 UI 层面的确定输入：
+
+| 下游文档 | 消费的章节 | 使用方法 |
+|---------|-----------|---------|
+| 前端技术方案 | 组件树、交互流程、设计 Token | 组件拆分、状态管理、样式方案 |
+| 变更清单 | 组件树、复用分析 | 前端代码变更任务 |
+| 测试指导书 | 交互流程、状态覆盖矩阵 | UI 测试用例 |
+
+---
+
+## 10. 审查结论
+
+- [ ] 所有页面/弹窗布局已从设计稿提取（无凭感觉推测）
+- [ ] 组件树嵌套 ≥3 层，每个组件标注了 Props/Emits/Slots/状态
+- [ ] 设计 Token 覆盖颜色/字号/间距/圆角/阴影不少于 5 类
+- [ ] 设计 Token 已按来源区分：设计稿事实 / 现有项目规范 / 推荐 - 待拍板
+- [ ] 所有推荐 - 待拍板的 token 或交互已写入待确认事项，未作为已确认实现依据
+- [ ] 关键交互流程覆盖完整链路（触发 → 反馈 → 状态变化 → 结果）
+- [ ] 状态覆盖矩阵覆盖 Loading/Empty/Error/Disabled/权限/重复提交/网络异常
+- [ ] 新增/修改组件已与现有代码做复用匹配
+- [ ] 设计 Token 已与现有变量做对齐检查
+- [ ] 功能点梳理中的所有功能点均有对应 UI 元素
+
+**审查结论**: {通过 / 不通过}
+
+**审查人**: AI (workflow-ui-spec)
+**审查日期**: {日期}

package/plugins/devflow-design/skills/workflow-ui-spec/references/affected-module-exploration.md

@@ -0,0 +1,55 @@
+# 被影响方探索指引（UI 规范）
+
+在生成 UI-SPEC 前，必须对需求基线中"关联历史功能/模块"表格列出的每个受影响前端页面、组件或交互区域进行探索。探索产出直接填入 UI-SPEC 的组件树、复用分析、设计 Token 对齐和交互流程章节。
+
+## 核心原则
+
+- **先读现有界面，再写 UI 契约**：不知道现有页面布局、组件层级和状态流，就不能可靠判断复用、扩展或新增。
+- **被影响页面和新增页面同等重要**：既要分析新设计稿，也要确认旧页面、共享组件、路由、状态管理和样式变量的影响。
+- **探索产出必须来自代码或设计事实**：组件树、Token、交互状态和复用决策必须来自实际源码、已有 UI 或设计稿，不得只靠文件名推断。
+
+## 探索清单
+
+对每个受影响页面/组件，按以下步骤执行。
+
+### 步骤1：定位关键文件
+
+| 层级 | 定位方式 | 最少读取 |
+|------|----------|----------|
+| 页面入口 | 前端路由表、`src/pages/`、`src/views/` 或同类目录 | 页面布局、入口状态、主要事件 |
+| 业务组件 | `src/components/`、页面局部组件目录 | props、事件、状态、插槽、可见区域 |
+| API 调用 | `src/api/`、service、store action | 请求方法、参数、响应字段、错误处理 |
+| 路由配置 | router、menu、权限配置 | 路径、参数、meta、菜单入口 |
+| 状态管理 | store、hooks、context、zustand/redux 等 | 共享状态、派生状态、加载/错误状态 |
+| 样式系统 | CSS/LESS/SCSS 变量、主题配置、Ant Design token | 颜色、字号、间距、圆角、阴影 |
+
+**底线**：每个被影响页面/组件至少读取 3 类文件：页面/组件源码、数据/API 来源、样式或主题来源。
+
+### 步骤2：回答四个问题
+
+| 问题 | 产出 | 填入 UI-SPEC |
+|------|------|-------------|
+| 现有页面长什么样？ | 页面区域、组件层级、关键字段/按钮/表格列 | 页面清单与布局、组件树 |
+| 现有状态有哪些？ | loading、empty、error、disabled、权限限制、重复提交 | 状态覆盖矩阵 |
+| 现有交互怎么触发？ | 点击、筛选、提交、弹窗、跳转、接口调用链 | 交互流程 |
+| 现有样式如何约束？ | 主题 Token、组件库规则、自定义样式变量 | 设计 Token |
+
+### 步骤3：判断复用/调整/新增边界
+
+| 决策类型 | 说明 |
+|----------|------|
+| 复用不改 | 现有组件、Token、交互满足 UI-SPEC |
+| 复用并扩展 | 保留现有组件结构，新增状态、字段、样式或事件 |
+| 抽离重构 | 现有页面承担过多职责，需要拆出业务组件或共享组件 |
+| 新增组件 | 现有组件无法覆盖新 UI 或新交互 |
+| 替换方案 | 现有实现与需求/设计冲突，需要明确迁移策略和兼容影响 |
+
+## 探索产出检查
+
+- [ ] 是否覆盖 baseline 第8.2节列出的每个受影响前端页面/组件？
+- [ ] 是否实际读取页面/组件源码、数据来源和样式/主题来源？
+- [ ] 是否列出现有布局、组件层级、状态、交互和 Token 约束？
+- [ ] 是否明确每个受影响组件的复用、扩展、抽离、新增或替换决策？
+- [ ] 是否把探索结论写入 UI-SPEC 的影响范围、组件树、Token 和交互章节？
+
+**此检查不通过，不得生成最终 UI-SPEC。**

package/plugins/devflow-implementation/agents/implementation-worker.md

@@ -0,0 +1,20 @@
+---
+name: implementation-worker
+description: Isolated implementation worker for an approved, bounded change plan; writes code and tests but never mutates Devflow control-plane state.
+tools:
+  - read
+  - grep
+  - find
+  - lsp
+  - bash
+  - edit
+  - write
+model: "@task"
+thinkingLevel: high
+autoloadSkills:
+  - workflow-execute-phase
+---
+
+Implement only the assigned plan slice. Read the relevant project rules, source, tests, and approved design artifacts before editing. Preserve unrelated work and report deviations instead of silently expanding scope.
+
+Run focused validation and return changed files, commands, results, residual risks, and any blocked dependency. Never edit `.planning/STATE.md`, `.planning/artifacts/index.yaml`, workflow definitions, or checkpoint decisions; the parent session owns those through Devflow tools.

package/plugins/devflow-implementation/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@devflow/omp-implementation",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module"
+}

package/plugins/devflow-implementation/skills/workflow-bug-fix/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: workflow-bug-fix
+description: "Use when a bug must be traced through workflow artifacts, root-caused, fixed, verified, and captured as a lesson when needed."
+---
+
+## Legacy Command Metadata
+
+```yaml
+argument-hint: <bug描述 | @bug-report.md>
+user-invocable: true
+pattern: debugger+reviewer
+allowed-tools: [Read, Write, Edit, Bash, Glob, Grep]
+```
+
+# Workflow: Bug Fix
+
+## Objective
+
+Trace a reported bug from workflow artifacts to implementation, identify the **first broken layer**, make the smallest correct repair, verify it, and preserve a reusable lesson when appropriate.
+
+Do not stop at “the code now works.” Every completed diagnosis must explain why the bug was possible: an undefined requirement, missed breakdown, incomplete specification, missing change-list task, incorrect implementation, or regression.
+
+## Input, Outputs, and References
+
+Input: `$ARGUMENTS` — a bug description or `@bug-report.md`.
+
+Required outputs:
+
+- Root-cause diagnosis containing the fields in `references/root-cause-ladder.md`.
+- Code and/or workflow-artifact repair consistent with that diagnosis.
+- Verification evidence and a context-sync result.
+- A lesson under `.context/lessons/` when the finding is reusable; if the directory or index is absent, record that limitation and do not fail solely for its absence.
+
+Read references only at their designated phase. [references/INDEX.md](references/INDEX.md) is the routing contract; it is not optional.
+
+## Non-Negotiable Rules
+
+1. Find the first broken layer and stop root-cause traversal there. Do not call a downstream symptom the root cause.
+2. Before classifying the cause, read `references/first-principles.md` and `references/adversarial-review.md`.
+3. Any source-level claim based on `.planning/code-index/` requires source readback at its evidence path and line. Navigation or index summaries alone are insufficient.
+4. `requirement-gap`, `breakdown-gap`, `spec-gap`, and `change-list-gap` require documentation repair before code repair. `implementation-bug` and `regression` do not require speculative document rewrites.
+5. Keep the repair scoped to the violated invariant. Do not slip in unrelated refactors or new feature scope.
+6. Complete verification and `workflow-context-sync --after-bugfix` before declaring success, unless the user explicitly approves an exception and its residual risk is recorded.
+
+## Context Loading Order
+
+Load only what exists and is relevant, in this order:
+
+1. `.planning/STATE.md` for the active feature and phase.
+2. `.planning/requirements/baseline.md`.
+3. `.planning/features/{功能名}/功能点梳理.md`.
+4. `.planning/features/{功能名}/前端技术方案.md` and `后端技术方案.md`.
+5. `.planning/features/{功能名}/*变更清单.md`.
+6. `.planning/code-index/` and then evidence source files, when source tracing is needed.
+
+If an upstream artifact is absent, record it as evidence for the corresponding gap rather than silently skipping it.
+
+## Phase 1 — Understand and Frame the Bug
+
+1. Extract abnormal behavior, expected behavior, actual behavior, reproduction, and impact.
+2. Read `STATE.md` to identify the active feature and phase.
+3. Ask only the minimum targeted question when a fact essential to reproduction or impact is unknown; do not turn a bug report into a full requirement interview.
+4. Read `references/first-principles.md` and record the function’s purpose, violated invariant, and failed assumption.
+5. Read `references/adversarial-review.md` and record the likely attack perspective, full path, and comparable unexposed paths.
+
+Gate: a bug frame must distinguish observed symptoms from the intended invariant before Phase 2 starts.
+
+## Phase 2 — Locate the First Broken Layer
+
+Read `references/root-cause-ladder.md` and inspect the layers in this exact order:
+
+1. Requirement baseline → `requirement-gap`
+2. Feature breakdown → `breakdown-gap`
+3. Technical specification → `spec-gap`
+4. Change list → `change-list-gap`
+5. Implementation → `implementation-bug`
+6. Relevant history → `regression`
+
+At the first layer that does not support the intended invariant, record the exact artifact section or source location, classify the root cause, and stop traversal. The reference defines the evidence tests and repair route for every classification.
+
+Gate: the diagnosis names one root-cause type, one first broken location, and the proof that all earlier applicable layers were sufficient.
+
+## Phase 3 — Diagnose and Plan
+
+Write the diagnosis using the required template in `references/root-cause-ladder.md`. It must include:
+
+- bug, root-cause type, first broken location, and why it happened;
+- function purpose, violated invariant, and failed assumption;
+- attack perspective, full attack path, and comparable risks;
+- code repair, invariant hardening, entry defense, and documentation writeback.
+
+Use the repair route from Phase 2. Scope the plan to the root cause and all directly necessary defenses.
+
+## Phase 4 — Repair and Verify
+
+1. Repair upstream artifacts first when the type requires it.
+2. Make the code repair.
+3. Run the applicable targeted tests and project toolchain checks.
+4. Confirm the implementation now matches the repaired change list and baseline when those artifacts changed.
+5. When the cause could be a boundary mistake, read `references/seam-analysis.md`; record only a substantiated seam finding.
+
+Gate: verification demonstrates the original reproduction is fixed and the identified invariant is protected against the relevant comparable path.
+
+## Phase 5 — Preserve Knowledge and Synchronize Context
+
+1. Read `references/lesson-format.md`. Write a lesson when the finding is reusable beyond this single line fix; otherwise record why no lesson is needed.
+2. If `.context/lessons/README.md` exists, append the lesson to its index. If it does not exist, retain the lesson file and report that no index was available.
+3. Run `workflow-context-sync --after-bugfix`.
+   - Ordinary implementation repairs refresh code-index and run validate/audit.
+   - Changes to routes, API clients, handlers, jobs, service boundaries, toolchain, or manifests may require a Medium sync with navigation/spec/toolchain updates.
+   - If a Full sync needs user authorization, explain why and wait; record the resulting residual risk.
+
+## Completion Report and Success Criteria
+
+Report: root cause; invariant/assumption; attack perspective and path; changed files; document writeback; lesson outcome; context-sync result; and whether any workflow step should be rerun.
+
+Success requires all of the following:
+
+- A specific first broken artifact or source location, not a generic label.
+- Minimal scoped repair with verification evidence.
+- Required workflow artifacts updated for documentation-originated causes.
+- Lesson outcome recorded and indexed when the index exists.
+- Context-sync completed, or an explicit user-approved exception and residual risk recorded.
+- `STATE.md` updated when phase state changed.

package/plugins/devflow-implementation/skills/workflow-bug-fix/references/INDEX.md

@@ -0,0 +1,13 @@
+# Bug-Fix Reference Routing
+
+This index defines the only authoritative routing for stable bug-fix details. The main `SKILL.md` owns workflow state, mandatory gates, outputs, and failure routing. References provide procedures and templates; they must not introduce a new mandatory phase.
+
+| Reference | Read when | Authority |
+|---|---|---|
+| `first-principles.md` | Phase 1, before root-cause classification | Function purpose, invariants, assumptions |
+| `adversarial-review.md` | Phase 1 and implementation/history analysis | Attack perspectives and full-path review |
+| `root-cause-ladder.md` | Phase 2 and Phase 3 | Evidence tests, classifications, repair routes, diagnosis template |
+| `seam-analysis.md` | Phase 4 only when a module boundary may be causal | Seam retrospective and recording format |
+| `lesson-format.md` | Phase 5 when deciding or writing a reusable lesson | Lesson decision rule, template, and indexing behavior |
+
+Do not load every reference eagerly. Read the one mapped to the active phase.

package/plugins/devflow-implementation/skills/workflow-bug-fix/references/adversarial-review.md

@@ -0,0 +1,35 @@
+# Adversarial Review
+
+Functional tests prove a normal path. This review asks how abnormal input, timing, state, or dependencies can violate the same invariant.
+
+## Attack Perspectives
+
+| Perspective | Probe |
+|---|---|
+| Oversized input | Does size, batch count, or concurrency exhaust memory, queues, or connections? |
+| Time anomalies | Are future, stale, timezone-shifted, or invalid timestamps ordered and validated safely? |
+| Encoding and special characters | Can null bytes, emoji, RTL markers, or malformed text bypass validation or break serialization? |
+| Concurrency | Can duplicate actions create double writes, payments, or conflicting state? |
+| Dependency failure | Are timeout, empty, malformed, or non-JSON responses bounded and handled? |
+| State interruption | Can restart, retry, partial persistence, or idempotency leave an unrecoverable state? |
+| Type and boundary confusion | Are null, strings-for-numbers, empty collections, zero, negative, and maximum values validated? |
+| Re-entry and loops | Can events or callbacks recursively re-trigger the operation? |
+
+## Full-Path Procedure
+
+Pick the perspective most related to the report, then trace:
+
+`entry → middleware/validation → business logic → data access → external calls → response/observability`
+
+At every boundary, state whether the abnormal condition is rejected, contained, retried with a bound, recovered, or silently propagated. Trace at least one comparable path when the issue reaches production-facing behavior.
+
+## Required Findings
+
+The diagnosis must state:
+
+- the attack perspective that first exposes the defect;
+- the complete path from entry to symptom;
+- comparable unexposed paths; and
+- the boundary where the invariant will be enforced.
+
+Do not “fix” only the triggering input when the same class can enter through another boundary. Use bounded validation, idempotency, transaction/locking, timeout/circuit-breaking, recovery, or observability as appropriate to the actual invariant.

package/plugins/devflow-implementation/skills/workflow-bug-fix/references/first-principles.md

@@ -0,0 +1,26 @@
+# First-Principles Review
+
+Pipeline artifacts are evidence, not truth. Use this review before assigning a root-cause type.
+
+## Required Questions
+
+For every bug, record:
+
+1. **Function purpose** — What problem must this module solve if rebuilt from zero?
+2. **Invariant** — What must always remain true for data integrity, state consistency, authorization, or temporal causality?
+3. **Assumption** — Which caller, dependency, ordering, transaction, or data-shape assumption no longer holds?
+
+## Phase Prompts
+
+| Layer | Challenge |
+|---|---|
+| Baseline | Is the stated FP/BR/BC itself consistent with the function purpose and failure paths? |
+| Breakdown | Did the style/function/logic expansion omit an invariant or a negative path? |
+| Technical spec | Does the seam align with the module’s responsibility and protect the invariant? |
+| Change list | Does a task couple unrelated modules or merely patch a symptom? |
+| Implementation | Does data, state, or timing violate a basic constraint or leak an internal assumption? |
+| History | Did a recent change remove a prior guarantee? |
+
+## Decision Rule
+
+Do not accept “the reported expected behavior” as sufficient proof. If the expected behavior conflicts with the function purpose or invariant, classify the upstream artifact as incorrect and repair it before implementation. A repair is complete only when it makes the failed assumption explicit, removes it, or defends it at the correct boundary.

package/plugins/devflow-implementation/skills/workflow-bug-fix/references/lesson-format.md

@@ -0,0 +1,28 @@
+# Bug-Fix Lesson Format
+
+Write a lesson when the cause, invariant, boundary defense, or regression pattern is likely to prevent future work from repeating the failure. Do not create one for a self-evident isolated typo unless project rules require it.
+
+Write `.context/lessons/{YYYY-MM-DD}-{slug}.md`:
+
+```markdown
+# {Bug title}
+
+- **Date**: {YYYY-MM-DD}
+- **Root-cause type**: {type}
+- **First broken location**: {file:section}
+- **Scenario**: {when it occurs}
+- **Symptom**: {what happened}
+- **Cause**: {why it happened}
+- **Function purpose**: {purpose}
+- **Violated invariant**: {invariant}
+- **Failed assumption**: {assumption}
+- **Attack perspective**: {perspective}
+- **Attack path**: {entry → … → symptom}
+- **Comparable risks**: {unexposed paths}
+- **Repair**: {what changed}
+- **Invariant hardening**: {how recurrence is prevented}
+- **Entry defense**: {defensive boundary}
+- **Rule for future work**: {reusable guidance}
+```
+
+If `.context/lessons/README.md` exists, add a concise linked entry. If it does not exist, do not fail the bug fix; retain the lesson file and report that the index was unavailable.

package/plugins/devflow-implementation/skills/workflow-bug-fix/references/root-cause-ladder.md

@@ -0,0 +1,51 @@
+# Root-Cause Ladder
+
+Inspect in order and stop at the first broken layer. Earlier applicable layers must be evidenced as sufficient before moving down.
+
+| Order | Evidence test | Type when broken | Repair route |
+|---:|---|---|---|
+| 1 | Baseline has a confirmed FP/BR/BC that defines the intended and failure behavior. | `requirement-gap` | Update baseline, then rerun downstream planning needed by the change. |
+| 2 | Feature breakdown expands the relevant behavior into page/component/field/validation or equivalent logic. | `breakdown-gap` | Complete the breakdown, then repair dependent plan/code. |
+| 3 | Technical spec covers the interface, field, component, seam, and boundary behavior. | `spec-gap` | Update the technical spec, then the change list and code. |
+| 4 | Change list has an executable task for every required change and dependency. | `change-list-gap` | Add the task, then implement it. |
+| 5 | Source faithfully implements the approved task and preserves boundaries. | `implementation-bug` | Repair code and tests; do not invent document changes. |
+| 6 | The behavior previously worked and a later relevant change removed the guarantee. | `regression` | Repair code, add regression coverage, and update documents only when they were also wrong. |
+
+## Evidence Details
+
+- Use `.planning/code-index/` to locate symbols, callers, imports, reads/writes, and tests when present; read the cited source evidence before asserting a fact.
+- If code-index is missing, stale, or has no result, use navigation and targeted source inspection, and say that machine relation facts were unavailable.
+- For implementation analysis, check completed change-list tasks, boundary/error handling, and obvious omissions such as type errors, logic reversal, or missed validation.
+- For regression analysis, run `git log --oneline -10 -- <relevant-file>` from the owning repository and inspect the relevant diff.
+
+## Diagnosis Template
+
+```markdown
+## Bug Root-Cause Diagnosis
+
+**Bug**: {one sentence}
+**Root-cause type**: `requirement-gap` | `breakdown-gap` | `spec-gap` | `change-list-gap` | `implementation-bug` | `regression`
+**First broken location**: {artifact section or file:line}
+**Why it happened**: {concise causal explanation}
+
+### First-Principles Analysis
+
+- **Function purpose**: {purpose}
+- **Violated invariant**: {always-true condition}
+- **Failed assumption**: {assumption}
+
+### Adversarial Analysis
+
+- **Attack perspective**: {perspective}
+- **Full path**: {entry → … → symptom}
+- **Comparable risks**: {other paths}
+
+### Repair Plan
+
+- **Artifact repair**: {required update or none}
+- **Code repair**: {files and intent}
+- **Invariant hardening**: {test/constraint/contract}
+- **Entry defense**: {where and how}
+```
+
+The diagnosis is invalid if it names a downstream type while an earlier applicable artifact is missing, pending, contradictory, or insufficient.

package/plugins/devflow-implementation/skills/workflow-bug-fix/references/seam-analysis.md

@@ -0,0 +1,30 @@
+# Seam Retrospective
+
+Use only after the repair when a module boundary, not merely a local mistake, may have enabled the bug.
+
+## When to Apply
+
+Review seams for `spec-gap`, `change-list-gap`, and `regression`; consider it for `breakdown-gap` or `implementation-bug`. It is normally not relevant to a pure `requirement-gap`.
+
+## Questions
+
+1. Where is the bug: module and method?
+2. What interface does that module expose, and who consumes it?
+3. Was an internal detail exposed, a dependency omitted, or a new module forced into an unrelated existing seam?
+4. Would a different boundary prevent this class of defect without broad refactoring?
+
+Record a finding only with evidence. “No seam issue” is valid for a local logic error.
+
+## Recording Format
+
+Append this to the lesson when a seam issue is substantiated:
+
+```markdown
+## Seam Analysis
+
+- **Bug location**: {module.method}
+- **Seam issue**: {yes/no and evidence}
+- **Recommendation**: {future boundary or module action}
+```
+
+This retrospective does not authorize unrelated refactoring in the current bug fix.