super-engineer-workflow 0.1.0

package/super-engineer-workflow/assets/config-schema.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "super-engineer workspace.yml",
+  "type": "object",
+  "required": ["version", "mode", "workflow_source", "todo_file", "reference_files", "code_path", "output_dir"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "type": "integer",
+      "const": 1
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["manual", "auto"]
+    },
+    "workflow_source": {
+      "type": "string",
+      "enum": ["todo", "openspec"],
+      "default": "todo"
+    },
+    "vars": {
+      "type": "object",
+      "additionalProperties": {
+        "type": ["string", "number", "boolean"]
+      }
+    },
+    "demand_file": {
+      "type": "string"
+    },
+    "todo_file": {
+      "type": "string",
+      "minLength": 1
+    },
+    "reference_files": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "default": []
+    },
+    "code_path": {
+      "type": "string",
+      "minLength": 1
+    },
+    "output_dir": {
+      "type": "string",
+      "minLength": 1
+    },
+    "verify_commands": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      ]
+    },
+    "openspec": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "changes_dir": {
+          "type": "string",
+          "minLength": 1
+        },
+        "change_dir": {
+          "type": "string",
+          "minLength": 1
+        },
+        "tasks_file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "proposal_file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "design_file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "specs_dir": {
+          "type": "string",
+          "minLength": 1
+        },
+        "writeback_dir": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    }
+  }
+}

package/super-engineer-workflow/assets/config.example.yml

@@ -0,0 +1,12 @@
+version: 1
+notification:
+  pushplus:
+    token: ""
+    ordinary:
+      enabled: false
+      channel: wechat
+      template: markdown
+  feishu:
+    enabled: false
+    webhook_url: "https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook"
+    secret: ""

package/super-engineer-workflow/assets/plan-schema.json

@@ -0,0 +1,362 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "super-engineer plan",
+  "type": "object",
+  "required": [
+    "session_id",
+    "constraints",
+    "todo_progress",
+    "task_modules",
+    "task_breakdown",
+    "requirement_summary",
+    "assumptions",
+    "workspace",
+    "configured_code_path",
+    "resolved_code_path",
+    "resolved_code_paths",
+    "service_hints",
+    "service_resolution",
+    "target_codebases",
+    "reference_files_used",
+    "detected_project",
+    "impacted_modules",
+    "impacted_files",
+    "change_steps",
+    "confidence",
+    "evidence",
+    "bridge_context",
+    "acceptance_criteria",
+    "implementation_slices",
+    "test_plan",
+    "risks",
+    "unknowns"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "session_id": { "type": "string" },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "todo_progress": {
+      "type": "object",
+      "required": ["pending_task_count", "completed_task_count", "total_task_count"],
+      "additionalProperties": false,
+      "properties": {
+        "pending_task_count": { "type": "integer", "minimum": 0 },
+        "completed_task_count": { "type": "integer", "minimum": 0 },
+        "total_task_count": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "task_modules": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "tasks"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "tasks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["id", "title", "details"],
+              "additionalProperties": false,
+              "properties": {
+                "id": { "type": "string" },
+                "title": { "type": "string" },
+                "details": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "task_breakdown": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "details"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "details": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "requirement_summary": { "type": "string" },
+    "assumptions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "workspace": { "type": "string" },
+    "configured_code_path": { "type": "string" },
+    "resolved_code_path": { "type": "string" },
+    "resolved_code_paths": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "service_hints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "service_resolution": {
+      "type": "object",
+      "required": [
+        "configured_code_path",
+        "resolved_code_paths",
+        "service_hints",
+        "selection_reason",
+        "candidate_codebases"
+      ],
+      "additionalProperties": true,
+      "properties": {
+        "configured_code_path": { "type": "string" },
+        "resolved_code_path": { "type": "string" },
+        "resolved_code_paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "service_hints": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "matched_service_hint": { "type": "string" },
+        "matched_services": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["service_hint", "resolved_code_path"],
+            "additionalProperties": false,
+            "properties": {
+              "service_hint": { "type": "string" },
+              "resolved_code_path": { "type": "string" }
+            }
+          }
+        },
+        "selection_reason": { "type": "string" },
+        "candidate_codebases": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "target_codebases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "path", "detected_project", "impacted_modules", "impacted_files"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "path": { "type": "string" },
+          "detected_project": {
+            "type": "object",
+            "required": ["language", "build_tool", "test_command", "start_command", "verify_command"],
+            "additionalProperties": false,
+            "properties": {
+              "language": { "type": "string" },
+              "build_tool": { "type": "string" },
+              "test_command": { "type": "string" },
+              "start_command": { "type": "string" },
+              "verify_command": { "type": "string" }
+            }
+          },
+          "impacted_modules": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "impacted_files": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "reference_files_used": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "detected_project": {
+      "type": "object",
+      "required": ["language", "build_tool", "test_command", "start_command", "verify_command"],
+      "additionalProperties": false,
+      "properties": {
+        "language": { "type": "string" },
+        "build_tool": { "type": "string" },
+        "test_command": { "type": "string" },
+        "start_command": { "type": "string" },
+        "verify_command": { "type": "string" }
+      }
+    },
+    "impacted_modules": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "impacted_files": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "change_steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "details", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "details": { "type": "string" },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "in_progress", "done", "blocked"]
+          }
+        }
+      }
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"]
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["codebase", "keyword", "file", "line", "snippet"],
+        "additionalProperties": false,
+        "properties": {
+          "codebase": { "type": "string" },
+          "keyword": { "type": "string" },
+          "file": { "type": "string" },
+          "line": { "type": "integer" },
+          "snippet": { "type": "string" }
+        }
+      }
+    },
+    "bridge_context": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "workflow_source",
+        "change_name",
+        "change_dir",
+        "tasks_file",
+        "proposal_file",
+        "design_file",
+        "spec_reference_files",
+        "proposal_headings",
+        "design_headings",
+        "business_constraints",
+        "acceptance_criteria",
+        "compatibility_notes",
+        "spec_merge_targets",
+        "updated_at"
+      ],
+      "properties": {
+        "workflow_source": { "type": "string" },
+        "change_name": { "type": "string" },
+        "change_dir": { "type": "string" },
+        "tasks_file": { "type": "string" },
+        "proposal_file": { "type": "string" },
+        "design_file": { "type": "string" },
+        "spec_reference_files": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "proposal_headings": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "design_headings": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "business_constraints": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "acceptance_criteria": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "compatibility_notes": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "spec_merge_targets": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["delta_source", "target", "relative_path", "target_exists", "target_sha256"],
+            "additionalProperties": false,
+            "properties": {
+              "delta_source": { "type": "string" },
+              "target": { "type": "string" },
+              "relative_path": { "type": "string" },
+              "target_exists": { "type": "boolean" },
+              "target_sha256": { "type": "string" }
+            }
+          }
+        },
+        "updated_at": { "type": "string" }
+      }
+    },
+    "acceptance_criteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["task_id", "task_title", "checks"],
+        "additionalProperties": false,
+        "properties": {
+          "task_id": { "type": "string" },
+          "task_title": { "type": "string" },
+          "checks": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "implementation_slices": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "title", "goal", "candidate_files", "status"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string" },
+          "title": { "type": "string" },
+          "goal": { "type": "string" },
+          "candidate_files": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "status": {
+            "type": "string",
+            "enum": ["pending", "in_progress", "done", "blocked"]
+          }
+        }
+      }
+    },
+    "test_plan": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "risks": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "unknowns": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

package/super-engineer-workflow/assets/status-schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "super-engineer status",
+  "type": "object",
+  "required": [
+    "mode",
+    "session_id",
+    "data_dir",
+    "report_dir",
+    "phase",
+    "current_task",
+    "progress",
+    "awaiting_confirmation",
+    "pending_confirmation_for",
+    "next_action",
+    "completed_tasks",
+    "blocked_tasks",
+    "started_at",
+    "finished_at",
+    "duration_seconds",
+    "notification_status",
+    "notification_message",
+    "updated_at"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": ["manual", "auto"]
+    },
+    "session_id": { "type": "string" },
+    "data_dir": { "type": "string" },
+    "report_dir": { "type": "string" },
+    "phase": {
+      "type": "string",
+      "enum": [
+        "context",
+        "discover",
+        "plan",
+        "wait_confirm_plan",
+        "implement",
+        "self_check",
+        "wait_confirm_implement",
+        "review",
+        "fix_review",
+        "wait_confirm_review",
+        "verify",
+        "fix_verify",
+        "done",
+        "blocked"
+      ]
+    },
+    "current_task": { "type": "string" },
+    "progress": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 100
+    },
+    "awaiting_confirmation": { "type": "boolean" },
+    "pending_confirmation_for": {
+      "type": "string",
+      "enum": ["", "implement", "review", "verify"]
+    },
+    "next_action": { "type": "string" },
+    "completed_tasks": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "blocked_tasks": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "started_at": { "type": "string" },
+    "finished_at": { "type": "string" },
+    "duration_seconds": {
+      "type": "number",
+      "minimum": 0
+    },
+    "notification_status": { "type": "string" },
+    "notification_message": { "type": "string" },
+    "updated_at": { "type": "string" }
+  }
+}

package/super-engineer-workflow/assets/workspace.example.yml

@@ -0,0 +1,25 @@
+version: 1
+mode: manual
+workflow_source: todo
+todo_file: todo.md
+reference_files:
+  - docs/项目介绍.md
+  - docs/开发规范.md
+code_path: ../your-project
+output_dir: output
+# 可选：自动识别不准确时覆盖验证命令
+# verify_commands:
+#   default: pnpm test && pnpm build
+#   frontend-app: pnpm test && pnpm build
+#   user-service: go test ./...
+
+# 如果使用 OpenSpec 模式，改成：
+# workflow_source: openspec
+# vars:
+#   demand_name: 7-your-demand
+# demand_file: superengineer/${demand_name}/需求.md
+# demand_file 也可以配置为飞书/Lark 云文档 URL，需本机已安装并授权 lark-cli。
+# todo_file: superengineer/${demand_name}/todo.md
+# output_dir: superengineer/${demand_name}/output
+# openspec:
+#   changes_dir: openspec/changes

package/super-engineer-workflow/config.example.yml

@@ -0,0 +1,12 @@
+version: 1
+notification:
+  pushplus:
+    token: ""
+    ordinary:
+      enabled: false
+      channel: wechat
+      template: markdown
+  feishu:
+    enabled: false
+    webhook_url: "https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook"
+    secret: ""

package/super-engineer-workflow/references/contracts.md

@@ -0,0 +1,39 @@
+# 工作流契约
+
+## 输入来源
+
+- `workflow_source=todo`：直接读取 `todo_file`
+- `workflow_source=openspec`：从 OpenSpec `tasks.md` 生成桥接 `todo_file`，并写入 `openspec-bridge-context.json`
+
+## 关键产物
+
+- `discovery.json`：代码定位证据
+- `plan.json`：工程计划与验收基线
+- `review.json`：结构化审查结论
+- `verify.json`：结构化验证结论
+- `execution-summary.json`：写回 OpenSpec change 的执行摘要
+- `archive-input.json`：归档前检查输入
+- `archive-result.json`：归档执行结果
+
+## 可靠性边界
+
+- `plan.json` 是实现阶段的执行基线
+- `review.json` 和 `verify.json` 是是否允许归档的核心证据
+- `execution-summary.json` 是 OpenSpec change 的共享摘要，不是长期规格 source of truth
+- `openspec/specs/` 在 archive 完成后才成为新的长期规格基线
+- `archive-input.json.merge_mode` 只要不是 `safe_merge`，就不允许自动 archive
+
+## 归档顺序
+
+1. `writeback-openspec`
+2. `prepare-archive-openspec`
+3. `archive-openspec`
+
+## 归档前置条件
+
+- `review.result == passed`
+- `verify.result == 通过`
+- `status.phase == done`
+- `archive-input.json.archive_ready == true`
+- `archive-input.json.spec_conflicts` 为空
+- `archive-input.json.merge_mode == safe_merge`

package/super-engineer-workflow/references/execution-modes.md

@@ -0,0 +1,38 @@
+# 执行模式
+
+## manual
+
+`manual` 模式下，工作流必须在以下节点暂停：
+
+- 计划生成后
+- 代码实现后
+- 代码审查后
+
+暂停时需要：
+
+- 把 `awaiting_confirmation` 设为 `true`
+- 把 `pending_confirmation_for` 设为下一阶段
+- 在 `status.json` 中写清楚下一步动作
+
+## auto
+
+`auto` 模式下，工作流应自动继续，除非出现以下情况：
+
+- 无法读取 `workspace.yml` 或配置不合法
+- 无法找到 todo、代码目录或必要参考文件，且缺失已经阻断后续执行
+- `code_path` 是聚合目录，但无法从 todo 判断目标服务
+- Git、文件系统、权限、命令执行错误导致后续步骤无法继续
+- 验证失败，已经不适合继续自动推进
+
+阻塞时需要：
+
+- 把 `phase` 设为 `blocked`
+- 记录阻塞原因
+- 明确停止，并输出可执行的下一步建议
+
+`auto` 模式下的强约束：
+
+- 不要因为“计划还不够细”“还需要先定位代码”“还想先确认方案”而请求用户批准
+- 如果计划粒度不够，应直接进入代码定位、补充计划，然后继续实现
+- 如果 review 发现计划与现实不一致，应先更新计划，再继续 review 或 verify
+- 只有真正的硬阻塞才允许停下来询问用户