openone-workflow-kit 0.1.0

package/workflow/core/templates/business-stage-document.md

@@ -0,0 +1,49 @@
+# 商业化阶段文档模板
+
+## 结论
+
+- 待填写
+
+## 语言与展示
+
+- 默认使用简体中文展示；专有名词、产品名、品牌名、渠道名、代码标识符、命令、文件路径、API、SDK、框架、协议、标准和官方英文术语保留原文。
+- 对外材料（landing 文案、发布帖、邮件模板）按目标市场语言产出，并在文档中标注目标渠道和语言。
+
+## 输入来源
+
+| 来源 | 路径或证据 | 状态 |
+| --- | --- | --- |
+| team-profile | `workflow/team-profile.yaml` | 待核查 |
+| 前序商业化文档 | 工作区级 `business/{product}/` | 待核查 |
+| 产品现状 | 待填写 | 待核查 |
+| 市场与竞品资料 | 待填写 | 待核查 |
+| 用户反馈与数据 | 待填写 | 待核查 |
+
+## 事实与假设
+
+### 一手证据
+
+- 待填写（用户访谈、自有使用数据、自有渠道数据；注明时间范围与样本量）
+
+### 二手证据
+
+- 待填写（公开报告、竞品公开信息、社区讨论；注明来源与采集日期）
+
+### 推断与假设
+
+- 待填写（每条标注验证方式与判定标准）
+
+### 权限与证据边界
+
+- 本阶段只产出分析、文档和清单；对外动作——发布内容、投放广告、发送 cold email、联系 influencer 或合作伙伴、提交目录站——需要用户明确授权或由用户自行执行。
+- 不编造市场数据、用户评价、竞品价格或渠道基准；无法核实的信息进入待确认项。
+- 不在本文档存储凭证、API key、联系人名单或受众导出数据；此类数据放本地未跟踪文件，文档只记录路径。
+- 营销工程需求（landing page、SEO 页面、埋点、A/B 测试）通过 `/new-feature` 进入研发轨，不在商业化阶段直接修改代码。
+
+## 输出
+
+- 待填写
+
+## 待验证假设与证据缺口
+
+- 待填写

package/workflow/core/templates/completion-contract.md

@@ -0,0 +1,114 @@
+# 完成合同：{feature}
+
+> 本合同是该需求「什么叫完成」的唯一判定依据：宣布完成 = 全部 blocking Oracle 为 PASS（或经用户书面确认 WAIVED）。
+> 冻结后，实现与验证只能翻转 Oracle 状态，不得静默修改任何标准；修改必须写入「修订记录」并经用户确认。
+> 复杂度 S 档只需填写标 ★ 的节；M/L 档全部填写。可用 `openone-workflow-check-contract <本文件>` 做结构校验。
+
+## 合同状态
+
+| 项 | 内容 |
+| --- | --- |
+| 需求名称 | 待填写 |
+| 复杂度档位 | S / M / L |
+| 状态 | 草稿 / 已冻结 / 修订中 |
+| 冻结时间 | - |
+| 冻结确认 | 待用户确认（记录用户原话或确认方式） |
+| Definition Lint | 未运行 / 通过 / 未通过 |
+| 交付模式 | 手动分阶段 / 交付至完成 |
+| 关联文档 | `01`-`07` 阶段文档、`specs/`、`workflow/constitution.md`、`workflow/standards/` |
+
+## ★ 目标与非目标
+
+### 目标（完成后必须为真的陈述，每条可被下方 Oracle 覆盖）
+
+- 待填写
+
+### 非目标（本次明确不做，防止范围漂移）
+
+- 待填写
+
+### 北极星挂钩
+
+- 本需求预期移动的指标：漏斗层 / 指标名 / 预期方向（有 `business/{product}/` 基线时必填，引用 B2/B5 条目；无基线记录缺口）
+
+## ★ 术语表（歧义消融）
+
+| 术语 | 本合同内的精确定义 | 被替代的模糊说法 |
+| --- | --- | --- |
+| 待填写 | 例：「快」= 冷启动到可交互 ≤ 2s（P95，中端设备） | 快、流畅 |
+
+## 数据流与状态机
+
+- 数据从哪来、到哪去、谁是唯一真相源（source of truth）。
+- 关键实体状态机：状态、触发事件、转移、终态；非法转移如何被拒绝。
+- 不变量：任何时刻必须为真的约束（例：余额不为负；同一 slug 唯一）。
+
+## 失败路径闭环
+
+| 失败场景 | 触发条件 | 系统行为 | 用户看到什么 | 恢复路径 |
+| --- | --- | --- | --- | --- |
+| 待填写 | | | | |
+
+> 至少检视：弱网/超时（重试策略与幂等性）、并发冲突、进程/页面中途被杀、配额或成本耗尽、非法输入、依赖服务故障。不适用的场景显式写「不适用+理由」。
+
+## 质量预算
+
+| 维度 | 预算（硬数字） | 测量方法 |
+| --- | --- | --- |
+| 性能 | 例：关键接口 P95 ≤ 300ms | 待填写 |
+| 资源 | 例：包体 ≤ 500KB / 内存 ≤ 200MB | 待填写 |
+| 成本 | 例：单活跃用户月成本 ≤ $0.05 | 待填写 |
+| 依赖 | 例：新增运行时依赖 ≤ 2 个 | 待填写 |
+| 安全 | 例：无明文凭证；输入全部校验 | 待填写 |
+
+## 体验质量线（S 档可省）
+
+- 感知性能：首屏骨架/进度反馈/乐观更新的要求。
+- 三态完备：每个页面/组件的空态、错误态、加载态定义（引用 `02B` 体验预算）。
+- 微文案：语气基线与错误信息的可行动性要求。
+- 可访问性最低线：对比度、键盘可达、屏幕阅读器关键路径。
+- 人工体验验收：保留至少一条 manual Oracle 给"用起来对不对劲"的直觉判断。
+
+## 影响边界
+
+- 允许修改：待填写（目录/模块/接口）。
+- 禁止触碰：待填写（引用 `workflow/constitution.md` 与 `workflow/standards/` 适用条款）。
+- 受影响契约：API / 数据结构 / 事件（对照 `specs/` 当前行为，列出将变更的行为条目）。
+
+## ★ 验收 Oracle
+
+> 每条必须绑定可复现的验证方法。类型 auto = 命令/脚本/测试，manual = 带步骤和判定标准的人工检查。
+> 状态机：`NOT_RUN → PASS / FAIL`；PASS 后相关代码再变更 → 置 `STALE` 必须复验；`WAIVED` 仅可由用户书面确认。
+> 状态只能由 `/交付至完成` 或 `/07-测试执行` 翻转，且必须附证据。
+
+| ID | 验收标准（建议 EARS 或 Given/When/Then 句式） | 验证方法（可复现命令或步骤） | 类型 | blocking | 状态 | 证据 | 更新时间 |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| O-001 | 例：WHEN 用户提交空表单 THE SYSTEM SHALL 阻止提交并逐字段提示 | 例：`npm test -- form.spec` | auto | 是 | NOT_RUN | - | - |
+
+## Definition Lint 结果
+
+| # | 维度 | 结论 | 缺口与处理 |
+| --- | --- | --- | --- |
+| 1 | 数据流确定性 | 未检查 | |
+| 2 | 失败路径闭环 | 未检查 | |
+| 3 | 质量预算 | 未检查 | |
+| 4 | Oracle 可复现 | 未检查 | |
+| 5 | 歧义消融 | 未检查 | |
+| 6 | 体验质量线 | 未检查 | |
+| 7 | 北极星挂钩 | 未检查 | |
+| 8 | 影响边界 | 未检查 | |
+
+## ★ 待澄清项
+
+> 冻结前必须清零：逐条解决，或经用户确认后降级为「已记录假设」写入对应章节。
+
+- 待填写（格式：`[待澄清: 问题描述]`）
+
+## 已记录假设
+
+- 待填写（用户确认过的默认假设，附确认时间）
+
+## 修订记录
+
+| 时间 | 修订内容 | 原因 | 用户确认 |
+| --- | --- | --- | --- |

package/workflow/core/templates/constitution.template.md

@@ -0,0 +1,50 @@
+# 工作区宪法（constitution）
+
+> 本文件存放**跨需求不可协商的原则**——每个需求不再重复讨论的既定决策。事实与路径配置放 `workflow/team-profile.yaml`，可复用代码规范放 `workflow/standards/`；本文件只放原则。
+> 效力：`/定义完成`、`/一致性检查`、`/04-代码实现`、`/05-代码审查`、`/交付至完成` 都以本文件为不可协商基准；与本文件冲突的需求必须先修订宪法（经用户确认并记录），不得静默绕过。
+> 每条原则写三段：原则 / 为什么 / 例外条件（没有例外就写"无"）。
+
+## 技术栈与依赖
+
+- 原则：待填写（例：默认 TypeScript + 最小依赖；新增运行时依赖每需求 ≤2 个）
+- 为什么：待填写
+- 例外条件：待填写
+
+## 安全与隐私底线
+
+- 原则：待填写（例：凭证只放本地未跟踪文件；不收集非必需个人数据；输入一律校验）
+- 为什么：待填写
+- 例外条件：无
+
+## 质量与测试底线
+
+- 原则：待填写（例：blocking Oracle 未全绿不发布；核心路径必须有 auto Oracle）
+- 为什么：待填写
+- 例外条件：待填写
+
+## UX 底线
+
+- 原则：待填写（例：每个页面必须定义空/错/载三态；错误信息必须可行动）
+- 为什么：待填写
+- 例外条件：待填写（例：内部工具可豁免动效规范）
+
+## 成本上限
+
+- 原则：待填写（例：单项目月固定成本 ≤ $X；引入付费服务需用户确认）
+- 为什么：待填写
+- 例外条件：待填写
+
+## 发布纪律
+
+- 原则：待填写（例：`prod` 只接受来自 `main` 的提升；发布必须有回滚点）
+- 为什么：待填写
+- 例外条件：待填写
+
+## 永不做清单
+
+- 待填写（例：不做需要收集通讯录的功能；不接入需要独占锁定的平台）
+
+## 修订记录
+
+| 时间 | 修订内容 | 原因 | 用户确认 |
+| --- | --- | --- | --- |

package/workflow/core/templates/living-spec.md

@@ -0,0 +1,35 @@
+# 行为规格：{领域或模块名}
+
+> living spec：本文件描述**当前已实现并已发布**的行为真相，是 brownfield 需求的定义起点。
+> 与 `features/` 的关系：features 是变更流水（做过什么），specs 是当前状态（现在是什么）。新需求先读本文件再定义变更；`/10-复盘总结` 在发布后把行为增量合并回本文件。
+> 只记录已验证行为；未发布的计划不进本文件。
+
+## 概览
+
+- 该领域/模块解决什么问题、服务哪些场景（一段话）。
+- 关联仓库与关键入口：待填写。
+
+## 行为清单
+
+> 用 EARS 句式（WHEN/WHILE/IF…THEN/WHERE + SHALL）逐条描述，稳定编号，不复用已删除编号。
+
+| 编号 | 行为（EARS 句式） | 来源 | 生效版本 |
+| --- | --- | --- | --- |
+| S-001 | 例：WHEN 用户提交空表单 THE SYSTEM SHALL 阻止提交并逐字段提示 | features/xxx | v0.1.0 |
+
+## 数据模型
+
+- 关键实体、字段口径、唯一真相源、保留策略：待填写。
+
+## 对外契约
+
+- API / 事件 / 文件格式 / 快捷键等对外承诺，及其兼容性口径：待填写。
+
+## 边界与已知限制
+
+- 明确不支持的场景、已知缺陷及其 workaround：待填写。
+
+## 变更历史
+
+| 时间 | 变更 | 来源 feature | 影响的行为编号 |
+| --- | --- | --- | --- |

package/workflow/core/templates/stage-document.md

@@ -0,0 +1,42 @@
+# 阶段文档模板
+
+## 结论
+
+- 待填写
+
+## 语言与展示
+
+- 默认使用简体中文展示；专有名词、产品名、品牌名、代码标识符、命令、文件路径、分支名、API、SDK、框架、协议、标准、错误信息和官方英文术语保留原文。
+- 不做无意义的中英双语重复；只有对外材料、多语言产品文案、合同/合规引用、用户明确要求翻译或目标市场需要时，才输出对应语言版本。
+
+## 输入来源
+
+| 来源 | 路径或证据 | 状态 |
+| --- | --- | --- |
+| team-profile | `workflow/team-profile.yaml` | 待核查 |
+| 前序文档 | 工作区级 `features/{feature}/` | 待核查 |
+| 本地代码 | 待填写 | 待核查 |
+| 设计 / 规范 / 测试资料 | 待填写 | 待核查 |
+
+## 事实与假设
+
+### 已确认事实
+
+- 待填写
+
+### 待确认项
+
+- 待填写
+
+### 权限边界
+
+- 个人项目中，agent 可以在范围明确且工作树已检查后执行本地分支命名、创建、commit、tag 和本地 merge。
+- 未经用户明确授权，不执行远程 Git 刷新、推送、GitHub release、商店提交、部署、数据库写入或生产配置写入。
+- 未通过实现准入，不修改业务代码、配置、脚本、迁移或部署文件。
+- 不将内部工作流阶段产物、PRD、调研、法务、隐私、合规、复盘或内部决策材料写入目标代码仓库；公开 README、CHANGELOG、release notes、商店文案和隐私政策可以在发布阶段明确记录为代码侧材料。
+- 不在 `main` 或 `prod` 上直接开发；实现默认在从 `prod` 创建的开发分支上进行，完成后合并到 `main` 测试，再由 `main` 提升到 `prod`；个人项目不创建 `test` 分支。
+- 首个线上版本前不启用自动生产部署；CI/CD 变更必须记录触发分支、必跑检查、密钥存放、部署审批、回滚路径和证据。
+
+## 输出
+
+- 待填写

package/workflow/core/templates/team-profile.template.yaml

@@ -0,0 +1,104 @@
+schema_version: "1.0"
+generated_at: "<ISO timestamp>"
+generated_by: "agent-workflow-init"
+
+team:
+  name: "<TODO>"
+  business_definition: "<TODO>"
+  target_users: []
+
+workspace_context:
+  operating_defaults:
+    planning_language: "zh-CN"
+    display_language: "zh-CN-first"
+    language_policy: "Use Simplified Chinese by default for workflow communication, stage deliverables, status summaries, reviews, tests, release records, and retrospectives; preserve official names and technical terms in their original form."
+    terminology_policy: "Keep product names, brand names, code identifiers, commands, file paths, branch names, APIs, SDKs, frameworks, protocols, standards, error messages, and official English terms unchanged unless the user asks for localization."
+
+enabled_tools: []
+detected_tools: []
+
+source_materials:
+  business_intro:
+    label: "业务介绍"
+    status: "missing"
+    paths: []
+  project_docs:
+    label: "项目资料"
+    status: "missing"
+    paths: []
+  ui_specs:
+    label: "UI 设计文件"
+    status: "missing"
+    paths: []
+  frontend_rules:
+    label: "前端开发规范"
+    status: "missing"
+    paths: []
+  backend_rules:
+    label: "后端开发规范"
+    status: "missing"
+    paths: []
+  testing_rules:
+    label: "测试规范"
+    status: "missing"
+    paths: []
+  market_research:
+    label: "市场与竞品资料"
+    status: "missing"
+    paths: []
+
+repos: []
+
+branch_model:
+  type: "prod-main-development"
+  production_branch: "prod"
+  integration_branch: "main"
+  development_branch_base: "prod"
+  testing_branch: "main"
+  test_branch_policy: "Do not create a separate test branch for personal projects; main is the testing/integration branch."
+  release_flow: "Create development branches from current prod, develop locally on the development branch, merge completed work into main for testing, then promote main to prod for release."
+  feature_branch_rule: "Use feature/<short-name>, fix/<short-name>, or dev/<short-name> development branches created from prod; agent may create local branches, local commits, local tags, and local merges after scope and working tree checks."
+  worktree_dir: "_worktrees"
+
+risk_policy:
+  local_git_operations: "agent-allowed-after-scope-check"
+  branch_creation: "agent-allowed-for-personal-repos"
+  commit_tag_local_merge: "agent-allowed-after-verification"
+  remote_git_operations: "explicit-user-authorization-required"
+  push_and_release: "explicit-user-authorization-required"
+  outbound_marketing_actions: "explicit-user-authorization-required"
+  paid_ad_spend: "manual-only"
+  ci_workflow_changes: "manual-review-required"
+  cd_workflow_changes: "manual-review-required"
+  auto_deploy_before_first_prod_release: "blocked"
+  production_deployments: "manual-approval-required-until-guarded-auto-approved"
+  database_writes: "manual-only"
+  config_writes: "manual-only"
+  high_risk_files:
+    - "ci/**"
+    - "cd/**"
+    - "deploy/**"
+    - "*.env*"
+    - "application*.yml"
+    - "application*.yaml"
+    - "bootstrap*.yml"
+    - "bootstrap*.yaml"
+    - "pom.xml"
+    - "package.json"
+    - "lockfiles"
+
+workflow:
+  features_dir: "features"
+  business_dir: "business"
+  specs_dir: "specs"
+  standards_dir: "workflow/standards"
+  constitution: "workflow/constitution.md"
+  core_dir: "workflow/core"
+  adapters_dir: "workflow/adapters"
+  require_stage_gate_for_code: true
+  require_feature_branch_for_code: true
+  complexity_tiers: "S/M/L"
+  definition_gate: "frozen-contract-with-lint-required-for-m-l; starred-mini-contract-for-s"
+  done_verdict: "all-blocking-oracles-pass-or-user-waived"
+  same_repo_parallel_policy: "worktree-required-after-implementation-stage"
+  business_review_cadence: "weekly-metrics, monthly-strategy, quarterly-positioning"