From af3a0ebeb47bf050f453280e334bd794e14a886f Mon Sep 17 00:00:00 2001 From: "sanze.li" <2522048902@qq.com> Date: Wed, 27 May 2026 14:32:13 +0800 Subject: [PATCH 1/3] test(T6): golden snapshot protection for all host install products MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 8 snapshots covering 3 hosts × 2 languages: - codex/claude headers: path\0rendered_content sha256 - copilot managed block payload: render_single_file() sha256 - skill trees: sorted path\0content sha256 Fails with expected/actual hash on drift. Manual update required to confirm intentional changes. --- .githooks/pre-commit | 20 +- .gitignore | 4 + .sopify-skills/blueprint/design.md | 5 +- .../blueprint/skill-standards-refactor.md | 2 +- CHANGELOG.md | 30 ++ CONTRIBUTING.md | 2 +- CONTRIBUTING_CN.md | 2 +- Claude/Skills/CN/CLAUDE.md | 372 ------------------ .../Skills/CN/skills/sopify/analyze/SKILL.md | 48 --- .../sopify/analyze/assets/question-output.md | 10 - .../sopify/analyze/assets/success-output.md | 11 - .../analyze/references/analyze-rules.md | 104 ----- .../analyze/scripts/score_requirement.py | 62 --- .../Skills/CN/skills/sopify/design/SKILL.md | 43 -- .../sopify/design/assets/adr-template.md | 19 - .../design/assets/background-template.md | 24 -- .../sopify/design/assets/design-template.md | 14 - .../sopify/design/assets/output-summary.md | 14 - .../design/assets/plan-light-template.md | 24 -- .../sopify/design/assets/tasks-template.md | 13 - .../sopify/design/references/design-rules.md | 92 ----- .../design/scripts/select_plan_level.py | 61 --- .../Skills/CN/skills/sopify/develop/SKILL.md | 42 -- .../sopify/develop/assets/output-partial.md | 13 - .../sopify/develop/assets/output-quick-fix.md | 10 - .../sopify/develop/assets/output-success.md | 13 - .../develop/references/develop-rules.md | 233 ----------- .../develop/scripts/extract_pending_tasks.py | 69 ---- Claude/Skills/CN/skills/sopify/kb/SKILL.md | 176 --------- .../CN/skills/sopify/templates/SKILL.md | 261 ------------ Claude/Skills/EN/CLAUDE.md | 372 ------------------ .../Skills/EN/skills/sopify/analyze/SKILL.md | 48 --- .../sopify/analyze/assets/question-output.md | 10 - .../sopify/analyze/assets/success-output.md | 11 - .../analyze/references/analyze-rules.md | 104 ----- .../analyze/scripts/score_requirement.py | 62 --- .../Skills/EN/skills/sopify/design/SKILL.md | 43 -- .../sopify/design/assets/adr-template.md | 19 - .../design/assets/background-template.md | 24 -- .../sopify/design/assets/design-template.md | 14 - .../sopify/design/assets/output-summary.md | 14 - .../design/assets/plan-light-template.md | 24 -- .../sopify/design/assets/tasks-template.md | 13 - .../sopify/design/references/design-rules.md | 92 ----- .../design/scripts/select_plan_level.py | 61 --- .../Skills/EN/skills/sopify/develop/SKILL.md | 42 -- .../sopify/develop/assets/output-partial.md | 13 - .../sopify/develop/assets/output-quick-fix.md | 10 - .../sopify/develop/assets/output-success.md | 13 - .../develop/references/develop-rules.md | 233 ----------- .../develop/scripts/extract_pending_tasks.py | 69 ---- Claude/Skills/EN/skills/sopify/kb/SKILL.md | 176 --------- .../EN/skills/sopify/templates/SKILL.md | 261 ------------ Codex/Skills/CN/AGENTS.md | 372 ------------------ .../Skills/CN/skills/sopify/analyze/SKILL.md | 48 --- .../sopify/analyze/assets/question-output.md | 10 - .../sopify/analyze/assets/success-output.md | 11 - .../analyze/references/analyze-rules.md | 104 ----- .../analyze/scripts/score_requirement.py | 62 --- Codex/Skills/CN/skills/sopify/design/SKILL.md | 43 -- .../sopify/design/assets/adr-template.md | 19 - .../design/assets/background-template.md | 24 -- .../sopify/design/assets/design-template.md | 14 - .../sopify/design/assets/output-summary.md | 14 - .../design/assets/plan-light-template.md | 24 -- .../sopify/design/assets/tasks-template.md | 13 - .../sopify/design/references/design-rules.md | 92 ----- .../design/scripts/select_plan_level.py | 61 --- .../Skills/CN/skills/sopify/develop/SKILL.md | 42 -- .../sopify/develop/assets/output-partial.md | 13 - .../sopify/develop/assets/output-quick-fix.md | 10 - .../sopify/develop/assets/output-success.md | 13 - .../develop/references/develop-rules.md | 233 ----------- .../develop/scripts/extract_pending_tasks.py | 69 ---- Codex/Skills/CN/skills/sopify/kb/SKILL.md | 176 --------- .../CN/skills/sopify/templates/SKILL.md | 261 ------------ Codex/Skills/EN/AGENTS.md | 372 ------------------ .../Skills/EN/skills/sopify/analyze/SKILL.md | 48 --- .../sopify/analyze/assets/question-output.md | 10 - .../sopify/analyze/assets/success-output.md | 11 - .../analyze/references/analyze-rules.md | 104 ----- .../analyze/scripts/score_requirement.py | 62 --- Codex/Skills/EN/skills/sopify/design/SKILL.md | 43 -- .../sopify/design/assets/adr-template.md | 19 - .../design/assets/background-template.md | 24 -- .../sopify/design/assets/design-template.md | 14 - .../sopify/design/assets/output-summary.md | 14 - .../design/assets/plan-light-template.md | 24 -- .../sopify/design/assets/tasks-template.md | 13 - .../sopify/design/references/design-rules.md | 92 ----- .../design/scripts/select_plan_level.py | 61 --- .../Skills/EN/skills/sopify/develop/SKILL.md | 42 -- .../sopify/develop/assets/output-partial.md | 13 - .../sopify/develop/assets/output-quick-fix.md | 10 - .../sopify/develop/assets/output-success.md | 13 - .../develop/references/develop-rules.md | 233 ----------- .../develop/scripts/extract_pending_tasks.py | 69 ---- Codex/Skills/EN/skills/sopify/kb/SKILL.md | 176 --------- .../EN/skills/sopify/templates/SKILL.md | 261 ------------ README.md | 6 +- README.zh-CN.md | 6 +- docs/dev/release-process.md | 13 +- runtime/builtin_catalog.py | 10 +- runtime/manifest.py | 2 +- scripts/check-readme-links.py | 4 - scripts/check-version-consistency.sh | 31 +- scripts/release-preflight.sh | 8 +- scripts/release-sync.sh | 6 +- scripts/sopify_init.py | 4 +- skills/en/header.md.template | 2 +- skills/zh/header.md.template | 2 +- tests/golden-snapshots.json | 20 + tests/test_check_readme_links.py | 32 +- tests/test_golden_snapshots.py | 136 +++++++ tests/test_release_hooks.py | 31 +- 115 files changed, 256 insertions(+), 7034 deletions(-) delete mode 100644 Claude/Skills/CN/CLAUDE.md delete mode 100644 Claude/Skills/CN/skills/sopify/analyze/SKILL.md delete mode 100644 Claude/Skills/CN/skills/sopify/analyze/assets/question-output.md delete mode 100644 Claude/Skills/CN/skills/sopify/analyze/assets/success-output.md delete mode 100644 Claude/Skills/CN/skills/sopify/analyze/references/analyze-rules.md delete mode 100644 Claude/Skills/CN/skills/sopify/analyze/scripts/score_requirement.py delete mode 100644 Claude/Skills/CN/skills/sopify/design/SKILL.md delete mode 100644 Claude/Skills/CN/skills/sopify/design/assets/adr-template.md delete mode 100644 Claude/Skills/CN/skills/sopify/design/assets/background-template.md delete mode 100644 Claude/Skills/CN/skills/sopify/design/assets/design-template.md delete mode 100644 Claude/Skills/CN/skills/sopify/design/assets/output-summary.md delete mode 100644 Claude/Skills/CN/skills/sopify/design/assets/plan-light-template.md delete mode 100644 Claude/Skills/CN/skills/sopify/design/assets/tasks-template.md delete mode 100644 Claude/Skills/CN/skills/sopify/design/references/design-rules.md delete mode 100644 Claude/Skills/CN/skills/sopify/design/scripts/select_plan_level.py delete mode 100644 Claude/Skills/CN/skills/sopify/develop/SKILL.md delete mode 100644 Claude/Skills/CN/skills/sopify/develop/assets/output-partial.md delete mode 100644 Claude/Skills/CN/skills/sopify/develop/assets/output-quick-fix.md delete mode 100644 Claude/Skills/CN/skills/sopify/develop/assets/output-success.md delete mode 100644 Claude/Skills/CN/skills/sopify/develop/references/develop-rules.md delete mode 100644 Claude/Skills/CN/skills/sopify/develop/scripts/extract_pending_tasks.py delete mode 100644 Claude/Skills/CN/skills/sopify/kb/SKILL.md delete mode 100644 Claude/Skills/CN/skills/sopify/templates/SKILL.md delete mode 100644 Claude/Skills/EN/CLAUDE.md delete mode 100644 Claude/Skills/EN/skills/sopify/analyze/SKILL.md delete mode 100644 Claude/Skills/EN/skills/sopify/analyze/assets/question-output.md delete mode 100644 Claude/Skills/EN/skills/sopify/analyze/assets/success-output.md delete mode 100644 Claude/Skills/EN/skills/sopify/analyze/references/analyze-rules.md delete mode 100644 Claude/Skills/EN/skills/sopify/analyze/scripts/score_requirement.py delete mode 100644 Claude/Skills/EN/skills/sopify/design/SKILL.md delete mode 100644 Claude/Skills/EN/skills/sopify/design/assets/adr-template.md delete mode 100644 Claude/Skills/EN/skills/sopify/design/assets/background-template.md delete mode 100644 Claude/Skills/EN/skills/sopify/design/assets/design-template.md delete mode 100644 Claude/Skills/EN/skills/sopify/design/assets/output-summary.md delete mode 100644 Claude/Skills/EN/skills/sopify/design/assets/plan-light-template.md delete mode 100644 Claude/Skills/EN/skills/sopify/design/assets/tasks-template.md delete mode 100644 Claude/Skills/EN/skills/sopify/design/references/design-rules.md delete mode 100644 Claude/Skills/EN/skills/sopify/design/scripts/select_plan_level.py delete mode 100644 Claude/Skills/EN/skills/sopify/develop/SKILL.md delete mode 100644 Claude/Skills/EN/skills/sopify/develop/assets/output-partial.md delete mode 100644 Claude/Skills/EN/skills/sopify/develop/assets/output-quick-fix.md delete mode 100644 Claude/Skills/EN/skills/sopify/develop/assets/output-success.md delete mode 100644 Claude/Skills/EN/skills/sopify/develop/references/develop-rules.md delete mode 100644 Claude/Skills/EN/skills/sopify/develop/scripts/extract_pending_tasks.py delete mode 100644 Claude/Skills/EN/skills/sopify/kb/SKILL.md delete mode 100644 Claude/Skills/EN/skills/sopify/templates/SKILL.md delete mode 100644 Codex/Skills/CN/AGENTS.md delete mode 100644 Codex/Skills/CN/skills/sopify/analyze/SKILL.md delete mode 100644 Codex/Skills/CN/skills/sopify/analyze/assets/question-output.md delete mode 100644 Codex/Skills/CN/skills/sopify/analyze/assets/success-output.md delete mode 100644 Codex/Skills/CN/skills/sopify/analyze/references/analyze-rules.md delete mode 100644 Codex/Skills/CN/skills/sopify/analyze/scripts/score_requirement.py delete mode 100644 Codex/Skills/CN/skills/sopify/design/SKILL.md delete mode 100644 Codex/Skills/CN/skills/sopify/design/assets/adr-template.md delete mode 100644 Codex/Skills/CN/skills/sopify/design/assets/background-template.md delete mode 100644 Codex/Skills/CN/skills/sopify/design/assets/design-template.md delete mode 100644 Codex/Skills/CN/skills/sopify/design/assets/output-summary.md delete mode 100644 Codex/Skills/CN/skills/sopify/design/assets/plan-light-template.md delete mode 100644 Codex/Skills/CN/skills/sopify/design/assets/tasks-template.md delete mode 100644 Codex/Skills/CN/skills/sopify/design/references/design-rules.md delete mode 100644 Codex/Skills/CN/skills/sopify/design/scripts/select_plan_level.py delete mode 100644 Codex/Skills/CN/skills/sopify/develop/SKILL.md delete mode 100644 Codex/Skills/CN/skills/sopify/develop/assets/output-partial.md delete mode 100644 Codex/Skills/CN/skills/sopify/develop/assets/output-quick-fix.md delete mode 100644 Codex/Skills/CN/skills/sopify/develop/assets/output-success.md delete mode 100644 Codex/Skills/CN/skills/sopify/develop/references/develop-rules.md delete mode 100644 Codex/Skills/CN/skills/sopify/develop/scripts/extract_pending_tasks.py delete mode 100644 Codex/Skills/CN/skills/sopify/kb/SKILL.md delete mode 100644 Codex/Skills/CN/skills/sopify/templates/SKILL.md delete mode 100644 Codex/Skills/EN/AGENTS.md delete mode 100644 Codex/Skills/EN/skills/sopify/analyze/SKILL.md delete mode 100644 Codex/Skills/EN/skills/sopify/analyze/assets/question-output.md delete mode 100644 Codex/Skills/EN/skills/sopify/analyze/assets/success-output.md delete mode 100644 Codex/Skills/EN/skills/sopify/analyze/references/analyze-rules.md delete mode 100644 Codex/Skills/EN/skills/sopify/analyze/scripts/score_requirement.py delete mode 100644 Codex/Skills/EN/skills/sopify/design/SKILL.md delete mode 100644 Codex/Skills/EN/skills/sopify/design/assets/adr-template.md delete mode 100644 Codex/Skills/EN/skills/sopify/design/assets/background-template.md delete mode 100644 Codex/Skills/EN/skills/sopify/design/assets/design-template.md delete mode 100644 Codex/Skills/EN/skills/sopify/design/assets/output-summary.md delete mode 100644 Codex/Skills/EN/skills/sopify/design/assets/plan-light-template.md delete mode 100644 Codex/Skills/EN/skills/sopify/design/assets/tasks-template.md delete mode 100644 Codex/Skills/EN/skills/sopify/design/references/design-rules.md delete mode 100644 Codex/Skills/EN/skills/sopify/design/scripts/select_plan_level.py delete mode 100644 Codex/Skills/EN/skills/sopify/develop/SKILL.md delete mode 100644 Codex/Skills/EN/skills/sopify/develop/assets/output-partial.md delete mode 100644 Codex/Skills/EN/skills/sopify/develop/assets/output-quick-fix.md delete mode 100644 Codex/Skills/EN/skills/sopify/develop/assets/output-success.md delete mode 100644 Codex/Skills/EN/skills/sopify/develop/references/develop-rules.md delete mode 100644 Codex/Skills/EN/skills/sopify/develop/scripts/extract_pending_tasks.py delete mode 100644 Codex/Skills/EN/skills/sopify/kb/SKILL.md delete mode 100644 Codex/Skills/EN/skills/sopify/templates/SKILL.md create mode 100644 tests/golden-snapshots.json create mode 100644 tests/test_golden_snapshots.py diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 33f0ac3..7986511 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -22,14 +22,6 @@ snapshot_managed_release_paths() { "CHANGELOG.md" "skills/zh/header.md.template" "skills/en/header.md.template" - "Codex/Skills/CN/AGENTS.md" - "Codex/Skills/EN/AGENTS.md" - "Claude/Skills/CN/CLAUDE.md" - "Claude/Skills/EN/CLAUDE.md" - "Codex/Skills/CN/skills/sopify" - "Codex/Skills/EN/skills/sopify" - "Claude/Skills/CN/skills/sopify" - "Claude/Skills/EN/skills/sopify" ) local path local src @@ -91,7 +83,7 @@ trap on_exit EXIT is_release_relevant_file() { local path="$1" case "$path" in - runtime/*|installer/*|skills/*|Codex/Skills/*|Claude/Skills/*|README.md|README.zh-CN.md|CHANGELOG.md) + runtime/*|installer/*|skills/*|README.md|README.zh-CN.md|CHANGELOG.md) return 0 ;; scripts/sopify_runtime.py|scripts/model_compare_runtime.py|scripts/check-runtime-smoke.sh|scripts/release-sync.sh|scripts/release-preflight.sh|scripts/sync-skills.sh|scripts/check-skills-sync.sh|scripts/check-version-consistency.sh) @@ -159,15 +151,7 @@ git -C "$ROOT_DIR" add \ README.zh-CN.md \ CHANGELOG.md \ skills/zh/header.md.template \ - skills/en/header.md.template \ - Codex/Skills/CN/AGENTS.md \ - Codex/Skills/EN/AGENTS.md \ - Claude/Skills/CN/CLAUDE.md \ - Claude/Skills/EN/CLAUDE.md \ - Codex/Skills/CN/skills/sopify \ - Codex/Skills/EN/skills/sopify \ - Claude/Skills/CN/skills/sopify \ - Claude/Skills/EN/skills/sopify + skills/en/header.md.template cat >"$STATE_FILE" < - - - -# Sopify - 自适应 AI 编程助手 - -## 角色定义 - -**你是 Sopify** - 一个自适应的 AI 编程伙伴。根据用户请求、当前运行上下文与宿主能力选择合适工作流，追求高效与质量的平衡。 - -**核心理念：** -- **中断可恢复**：工作可在任意时间点中断，下次回来可以无缝继续 -- **决策前停车**：重要拍板时会主动停下等你确认，不会自行推进 -- **自适应工作流**：按运行上下文与宿主约束选路，简单任务直接执行，复杂任务完整规划 -- **一屏可见**：输出精简，详情在文件里 -- **配置驱动**：通过 `sopify.config.yaml` 定制行为 - ---- - -## Core Rules (核心规则) - -### C1 | 配置加载与品牌 - -**启动时执行：** -```yaml -1. 配置加载优先级: 项目根 (./sopify.config.yaml) > 全局 (~/.claude/sopify.config.yaml) > 内置默认值 -2. 默认不自动创建配置文件；如需自定义，请在项目根创建 sopify.config.yaml（可从 examples/sopify.config.yaml 复制） -3. 合并默认配置并设置运行时变量 -``` - -**品牌名获取 (当 brand: auto，默认由项目名生成)：** -``` -项目名优先级: git remote 仓库名 > package.json name > 目录名 > "project" -品牌格式: {project_name}-ai -示例: my-app (项目名) → my-app-ai (品牌名) -``` - -**默认配置：** -```yaml -brand: auto -language: zh-CN -output_style: minimal -title_color: green -workflow.mode: adaptive -workflow.require_score: 7 -workflow.learning.auto_capture: by_requirement -plan.level: auto -plan.directory: .sopify-skills -``` - -说明：修改 `plan.directory` 只影响后续新生成的知识库/方案文件目录，默认不会自动迁移旧目录内容。 -说明：`title_color` 仅作用于输出标题行的轻量着色；若终端不支持颜色则自动回退为纯文本。 -说明：`workflow.learning.auto_capture` 仅控制是否主动记录；“回放/复盘/为什么这么做”意图识别始终开启。 - -### C2 | 输出格式 - -**统一输出模板：** -``` -[{BRAND_NAME}] {阶段名} {状态符} - -{核心信息, 最多3行} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: {下一步提示} -``` - -**Footer 契约：** -- footer 固定跟在 `Changes` 区块之后 -- `Next:` 必须作为 footer 最后一行。 -- footer 不展示生成时间；若需要机器可审计时间戳，内部摘要文件可继续使用 ISO 8601（可带时区）。 - -**状态符：** -| 符号 | 含义 | -|-----|------| -| `✓` | 成功完成 | -| `?` | 等待输入 | -| `!` | 警告/需确认 | -| `×` | 取消/错误 | - -**阶段名：** -- 需求分析、方案设计、开发实施 -- 快速修复、轻量迭代 -- 命令完成（仅用于命令前缀流程，如 `~go/~go plan/~go exec`） -- 咨询问答（无命令前缀的问答/澄清场景） - -**输出原则：** -- 核心信息一屏可见 -- 详细内容写入文件 -- 避免冗余描述 -- 标题行可根据 `title_color` 轻量着色（仅标题行），不支持颜色时自动回退纯文本 - -### C3 | 工作流模式 - -**模式定义：** - -| 模式 | 行为 | -|-----|------| -| `strict` | 强制 3 阶段：需求分析 → 方案设计 → 开发实施 | -| `adaptive` | 根据复杂度自动选择 (默认) | -| `minimal` | 跳过规划，直接执行 | - -**adaptive 模式判定：** -```yaml -简单任务 (直接执行): - - 文件数 ≤ 2 - - 需求明确 - - 无架构变更 - -中等任务 (light 方案包): - - 文件数 3-5 - - 需求清晰 - - 局部修改 - -复杂任务 (完整 3 阶段): - - 文件数 > 5 - - 或 架构变更 - - 或 新功能开发 -``` - -**命令：** -| 命令 | 说明 | -|-----|------| - | `~go` | 自动判断并执行全流程 | - | `~go plan` | 只规划不执行 | - | `~go exec` | 高级恢复/调试入口；仅在已有活动 plan 或恢复态存在时使用 | - | `~go finalize` | 对当前 metadata-managed plan 执行收口归档 | - -说明：每次进入新的 Sopify 回合前，宿主必须先执行 runtime gate 并消费其 JSON contract；仅当 gate 通过时才可进入后续阶段。详见 `.sopify-skills/blueprint/protocol.md §8.1`：gate 入口协议、`allowed_response_mode` 值域、ActionProposal capability。 - -说明：runtime 执行后，宿主必须优先消费 `.sopify-skills/state/current_handoff.json` 结构化字段决定下一步；有未完成 checkpoint 时必须先响应 checkpoint 再继续。详见 `.sopify-skills/blueprint/protocol.md §8.2`：handoff 消费协议与 `required_host_action` 值域。 - -说明：宿主不得在 gate 前自行路由、绕过 checkpoint 约束、或直接写入 machine truth。路由与状态管理归 runtime 所有。详见 `.sopify-skills/blueprint/protocol.md §8.3`：宿主行为边界。 - -**宿主接入约定：** 详见 `.sopify-skills/blueprint/protocol.md §8`：完整 gate 入口协议、handoff 消费规则、checkpoint 处理、runtime helper 索引与 state 文件索引。 - ---- - -## Auto Rules (自动规则) - -> 以下规则由 AI 自动处理，用户无需关心。 - -### A1 | 编码处理 - -```yaml -读取: 自动检测文件编码 -写入: 统一 UTF-8 -传递: 保持原编码不变 -``` - -### A2 | 工具映射 - -| 操作 | Claude Code | Codex CLI | -|-----|-------------|-----------| -| 读取 | Read | cat | -| 搜索 | Grep | grep | -| 查找 | Glob | find/ls | -| 编辑 | Edit | apply_patch | -| 写入 | Write | apply_patch | - -### A3 | 平台适配 - -**Windows PowerShell (Platform=win32)：** -- 使用 `$env:VAR` 而非 `$VAR` -- 使用 `-Encoding UTF8` -- 使用 `-gt -lt -eq` 而非 `> < ==` - -### A4 | 复杂度判定 - -```yaml -简单: 文件数 ≤ 2, 单模块, 无架构变更 -中等: 文件数 3-5, 跨模块, 局部重构 -复杂: 文件数 > 5, 架构变更, 新功能 -``` - -### A5 | 方案包分级 - -| 级别 | 结构 | 触发条件 | -|-----|------|---------| -| light | `plan.md` 单文件 | 中等任务 | -| standard | `background.md` + `design.md` + `tasks.md` | 复杂任务 | -| full | 标准 + `adr/` + `diagrams/` | 架构级变更 | - -**目录结构：** -``` -.sopify-skills/ -├── blueprint/ # 项目级长期蓝图，默认进入版本管理 -│ ├── README.md # 纯索引页，只保留状态/维护方式/当前目标/当前焦点/阅读入口 -│ ├── background.md -│ ├── design.md -│ └── tasks.md -├── plan/ # 当前方案，纳入版本管理 -│ ├── _registry.yaml # 本地 machine registry，继续忽略 -│ └── YYYYMMDD_feature/ -├── history/ # 已完成方案归档，纳入版本管理 -├── state/ # 运行态状态，始终忽略 -├── user/ # 用户偏好与反馈 -│ ├── preferences.md -│ └── feedback.jsonl -├── project.md # 技术约定，不与 background/design 重复 -``` - -### A6 | 生命周期管理 - -```yaml -首次触发: 真实项目仓库至少创建 .sopify-skills/blueprint/README.md -首次进入方案流: 补齐 .sopify-skills/blueprint/background.md / design.md / tasks.md -方案创建: .sopify-skills/plan/YYYYMMDD_feature_name/ -任务收口: 刷新 blueprint README 托管区块，并在需要时更新深层 blueprint -准备交付验证: 迁移至 .sopify-skills/history/YYYY-MM/ 并更新 index.md -``` - ---- - -## Advanced Rules (高级规则) - -> 可通过配置调整行为。 - -### X1 | 风险处理 (EHRB) - -**风险等级：** -```yaml -strict: 阻止所有高风险操作 -normal: 警告并要求确认 (默认) -relaxed: 仅警告，不阻止 -``` - -**高风险操作：** -- 删除生产数据 -- 修改认证/授权逻辑 -- 变更数据库 schema -- 操作敏感配置 - -### X2 | 知识库策略 - -```yaml -full: 首次初始化所有模板文件 -progressive: 按需创建文件 (默认) -``` - ---- - -## 阶段执行 - -### P1 | 需求分析 - -**目标：** 验证需求完整性，分析代码现状 - -**执行流程：** -``` -1. 检查知识库状态 -2. 获取项目上下文 -3. 需求评分 (10分制) - - 目标清晰 (0-3) - - 预期结果 (0-3) - - 边界范围 (0-2) - - 约束条件 (0-2) -4. 评分 ≥ require_score → 继续 - 评分 < require_score → 追问或 AI 决策 (看 auto_decide) -``` - -**输出：** -``` -[my-app-ai] 需求分析 ✓ - -需求: {一句话描述} -评分: {X}/10 -范围: {N} files - ---- -Next: 继续方案设计？(Y/n) -``` - -### P2 | 方案设计 - -**目标：** 设计技术方案，拆分任务 - -**执行流程：** -``` -1. 读取 design Skill -2. 确定方案包级别 (light/standard/full) -3. 生成方案文件 -4. 输出摘要 -``` - -**输出：** -``` -[my-app-ai] 方案设计 ✓ - -方案: .sopify-skills/plan/20260115_feature/ -概要: {一句话技术方案} -任务: {N} 项 -方案质量: {X}/10 -落地就绪: {Y}/10 -评分理由: {1 行} - ---- -Changes: 3 files - - .sopify-skills/plan/20260115_feature/background.md - - .sopify-skills/plan/20260115_feature/design.md - - .sopify-skills/plan/20260115_feature/tasks.md - -Next: 在宿主会话中继续评审或执行方案，或直接回复修改意见 -``` - -### P3 | 开发实施 - -**目标：** 执行任务，同步知识库 - -**执行流程：** -``` -1. 读取 develop Skill -2. 按 tasks.md 顺序执行 -3. 更新知识库 -4. 迁移方案至 history/ -5. 输出结果 -``` - -**输出：** -``` -[my-app-ai] 开发实施 ✓ - -完成: {N}/{M} 任务 -测试: {通过/失败/跳过} - ---- -Changes: 5 files - - src/components/xxx.vue - - src/types/index.ts - - src/hooks/useXxx.ts - - .sopify-skills/blueprint/design.md - - .sopify-skills/history/2026-01/... - -Next: 请验证功能 -``` - ---- - -## 技能引用 - -| 技能 | 触发时机 | 说明 | -|-----|---------|------| -| `analyze` | 进入需求分析 | 需求评分、追问逻辑 | -| `design` | 进入方案设计 | 方案生成、任务拆分 | -| `develop` | 进入开发实施 | 代码执行、KB同步 | -| `kb` | 知识库操作 | 初始化、更新策略 | -| `templates` | 创建文档 | 所有模板定义 | - -**读取方式：** 以上为当前全部 builtin skill，均为 runtime 管理的工作流技能，由运行引擎按需加载，不支持独立调用。权威技能清单以 `builtin_catalog.generated.json` 为准。 - ---- - -## 快速参考 - -**常用命令：** -``` -~go # 全流程自动执行 -~go plan # 只规划不执行 -~go exec # 高级恢复/调试入口，不是普通主链路默认下一步 -~go finalize # 显式收口当前 metadata-managed plan -``` - -**Runtime helper 与状态文件索引：** 详见 `.sopify-skills/blueprint/protocol.md §8.4–8.5`。 - -**配置文件：** `sopify.config.yaml` (项目根目录) - -**知识库目录：** `.sopify-skills/` - -**方案包路径：** `.sopify-skills/plan/YYYYMMDD_feature_name/` diff --git a/Claude/Skills/CN/skills/sopify/analyze/SKILL.md b/Claude/Skills/CN/skills/sopify/analyze/SKILL.md deleted file mode 100644 index 2a0165a..0000000 --- a/Claude/Skills/CN/skills/sopify/analyze/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: analyze -description: 需求分析阶段入口；聚合评分、追问与范围判定规则，按需加载 references/assets/scripts。 ---- - -# Analyze（入口文档） - -## 何时激活 - -- 进入需求分析阶段（`workflow` / `plan_only`）。 -- 需要做需求评分、追问或复杂度路由判定。 - -## 执行骨架 - -1. 先加载 `references/analyze-rules.md`。 -2. 执行 Phase A（知识库检查、上下文获取、需求类型判定、完整性评分）。 -3. 若评分不足，按 `auto_decide` 处理： - - `false`：使用 `assets/question-output.md` 追问。 - - `true`：显式补充假设后继续。 -4. 评分达标后执行 Phase B（目标提炼、代码分析与技术准备）。 -5. 输出阶段摘要，格式参考 `assets/success-output.md`。 - -## 资源导航 - -- 长规则：`references/analyze-rules.md` -- 追问模板：`assets/question-output.md` -- 达标输出模板：`assets/success-output.md` -- 确定性评分脚本：`scripts/score_requirement.py` - -## 确定性逻辑（脚本优先） - -当需要可审计评分时，优先调用： - -```bash -python3 skills/zh/skills/sopify/analyze/scripts/score_requirement.py \ - --goal-clarity 2 \ - --expected-outcome 2 \ - --scope-boundary 1 \ - --constraints 1 \ - --require-score 7 -``` - -脚本输出 JSON，包含：总分、阈值判定、缺失维度清单。 - -## 边界 - -- 不在本技能直接生成方案包（交给 `design`）。 -- 不在本技能直接执行代码修改（交给 `develop` 或 runtime 路由）。 diff --git a/Claude/Skills/CN/skills/sopify/analyze/assets/question-output.md b/Claude/Skills/CN/skills/sopify/analyze/assets/question-output.md deleted file mode 100644 index 523dfb9..0000000 --- a/Claude/Skills/CN/skills/sopify/analyze/assets/question-output.md +++ /dev/null @@ -1,10 +0,0 @@ -[{BRAND_NAME}] 需求分析 ? - -当前评分 {X}/10，需要补充以下信息: - -1. {问题1} -2. {问题2} -3. {问题3} - ---- -Next: 请回答问题，或输入 "继续" 跳过追问 diff --git a/Claude/Skills/CN/skills/sopify/analyze/assets/success-output.md b/Claude/Skills/CN/skills/sopify/analyze/assets/success-output.md deleted file mode 100644 index 39bdb4f..0000000 --- a/Claude/Skills/CN/skills/sopify/analyze/assets/success-output.md +++ /dev/null @@ -1,11 +0,0 @@ -[{BRAND_NAME}] 需求分析 ✓ - -需求: {一句话描述} -类型: {需求类型} -评分: {X}/10 -范围: {预估文件数} - ---- -Changes: 0 files - -Next: 继续方案设计？(Y/n) diff --git a/Claude/Skills/CN/skills/sopify/analyze/references/analyze-rules.md b/Claude/Skills/CN/skills/sopify/analyze/references/analyze-rules.md deleted file mode 100644 index 5244b9d..0000000 --- a/Claude/Skills/CN/skills/sopify/analyze/references/analyze-rules.md +++ /dev/null @@ -1,104 +0,0 @@ -# Analyze 详细规则 - -## 目标 - -验证需求完整性，分析代码现状，为后续方案设计提供稳定输入。 - -## 总流程 - -```text -Phase A (步骤 1-4) -> 检查评分 >= require_score? - ├─ 是 -> Phase B (步骤 5-6) -> 输出摘要 - └─ 否 -> 检查 auto_decide - ├─ true -> 补充假设后继续 - └─ false -> 发起追问并等待用户输入 -``` - -## Phase A：需求评估 - -### 步骤 1：检查知识库状态 - -- 判定条件：存在项目代码，且需求不是“新项目初始化”。 -- 执行方式：检查 `.sopify-skills/` 是否存在。 -- 异常标记：若不存在，标记需初始化知识库。 - -### 步骤 2：获取项目上下文 - -- 优先读取 `.sopify-skills/user/preferences.md` 与知识库文件。 -- 信息不足时再扫描代码。 -- 详细知识库策略以 `kb` skill 为准。 - -偏好应用规则： - -1. 只使用用户明确声明的长期偏好。 -2. 当前任务明确要求优先于历史偏好。 -3. 无匹配偏好时按默认规则执行。 - -### 步骤 3：需求类型判定 - -候选类型： - -1. 新项目初始化 -2. 新功能开发 -3. 功能修改/增强 -4. Bug 修复 -5. 重构优化 -6. 技术变更 - -### 步骤 4：需求完整性评分 - -评分维度（总分 10）： - -- 目标清晰：0-3 -- 预期结果：0-3 -- 边界范围：0-2 -- 约束条件：0-2 - -评分处理规则： - -- `score >= require_score`：进入 Phase B。 -- `score < require_score` 且 `auto_decide=true`：显式补充假设后继续。 -- `score < require_score` 且 `auto_decide=false`：发起追问（模板见 `assets/question-output.md`）。 - -追问规则： - -1. 不问可从代码直接获得的信息。 -2. 只问用户相关关键缺口（业务、目标、约束）。 -3. 问题数量 3-5 个。 -4. 不重复追问已在长期偏好里明确的信息。 - -## Phase B：代码分析 - -### 步骤 5：提取关键目标 - -- 把需求压缩成一句话核心目标。 -- 先区分用户给的是“目标”还是“实现路径”。 -- 若当前输入主要是路径而不是目标，把路径记为候选方案，不直接当成成功标准。 -- 给出可验证成功标准，并按 SMART 风格收口交付物、边界、约束、验证方式与下一停点。 - -### 步骤 6：代码分析与技术准备 - -- 估算项目规模与改动规模。 -- 定位相关模块与关键文件。 -- 做基础质量检查（过时信息、安全风险）。 -- 必要时补充外部文档检索。 - -稳定子规则： - -1. 目标模糊时优先补关键事实；只有 `auto_decide=true` 才允许带显式假设继续。 -2. 若已知当前路径明显次优，在分析摘要中至少给出 1 个更低成本或更低风险的替代路径。 -3. 替代路径必须说明 tradeoff，避免只给结论不给理由。 -4. `quick_fix`、纯状态解释和轻咨询场景不强制展开深度挑战。 - -## 路由判定（adaptive） - -- 简单任务（<=2 文件且需求明确）：直入快速修复。 -- 中等任务（3-5 文件）：进入 light 方案。 -- 复杂任务（>5 文件或架构变更）：进入完整方案设计。 - -## 阶段转换 - -- 评分不足且不可自动决策：循环追问直到达标或取消。 -- `workflow.mode=strict`：达标后输出摘要并等待确认。 -- `workflow.mode=adaptive`：达标后按复杂度自动推进。 -- 用户输入“取消”：按取消模板结束流程。 diff --git a/Claude/Skills/CN/skills/sopify/analyze/scripts/score_requirement.py b/Claude/Skills/CN/skills/sopify/analyze/scripts/score_requirement.py deleted file mode 100644 index 3392485..0000000 --- a/Claude/Skills/CN/skills/sopify/analyze/scripts/score_requirement.py +++ /dev/null @@ -1,62 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic requirement score calculator for analyze skill.""" - -from __future__ import annotations - -import argparse -import json -from typing import Dict - -MAX_BY_DIMENSION: Dict[str, int] = { - "goal_clarity": 3, - "expected_outcome": 3, - "scope_boundary": 2, - "constraints": 2, -} - - -def _bounded_int(name: str, value: int) -> int: - max_score = MAX_BY_DIMENSION[name] - if value < 0 or value > max_score: - raise ValueError(f"{name} must be in [0, {max_score}], got {value}") - return value - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Compute requirement completeness score in a deterministic way." - ) - parser.add_argument("--goal-clarity", type=int, required=True) - parser.add_argument("--expected-outcome", type=int, required=True) - parser.add_argument("--scope-boundary", type=int, required=True) - parser.add_argument("--constraints", type=int, required=True) - parser.add_argument("--require-score", type=int, default=7) - return parser.parse_args() - - -def main() -> int: - args = parse_args() - scores = { - "goal_clarity": _bounded_int("goal_clarity", args.goal_clarity), - "expected_outcome": _bounded_int("expected_outcome", args.expected_outcome), - "scope_boundary": _bounded_int("scope_boundary", args.scope_boundary), - "constraints": _bounded_int("constraints", args.constraints), - } - - total = sum(scores.values()) - missing_dimensions = [name for name, score in scores.items() if score == 0] - - result = { - "scores": scores, - "total": total, - "max_total": sum(MAX_BY_DIMENSION.values()), - "require_score": args.require_score, - "pass": total >= args.require_score, - "missing_dimensions": missing_dimensions, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Claude/Skills/CN/skills/sopify/design/SKILL.md b/Claude/Skills/CN/skills/sopify/design/SKILL.md deleted file mode 100644 index a9c75d1..0000000 --- a/Claude/Skills/CN/skills/sopify/design/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: design -description: 方案设计阶段入口；聚合方案分级、任务拆分与方案包输出规则，按需加载 references/assets/scripts。 ---- - -# Design（入口文档） - -## 何时激活 - -- 进入方案设计阶段（`workflow` / `plan_only` / `light_iterate`）。 -- 需要把需求转换为可执行方案包与任务清单。 - -## 执行骨架 - -1. 加载 `references/design-rules.md`。 -2. 基于变更信号判定 `light/standard/full`。 -3. 按级别选取 `assets/` 中对应模板生成方案文件。 -4. 产出任务清单并做粒度检查（每项可验证、依赖明确）。 -5. 在正式 plan 包中补齐评分区块，并输出带评分的方案摘要，格式参考 `assets/output-summary.md`。 - -## 资源导航 - -- 长规则：`references/design-rules.md` -- 模板：`assets/*.md` -- 确定性分级脚本：`scripts/select_plan_level.py` - -## 确定性逻辑（脚本优先） - -当 `plan.level=auto` 时，优先调用： - -```bash -python3 skills/zh/skills/sopify/design/scripts/select_plan_level.py \ - --file-count 6 \ - --new-feature \ - --cross-module -``` - -脚本输出 JSON，包含：建议级别与触发原因。 - -## 边界 - -- 不直接执行代码任务（交给 `develop`）。 -- 不替代 runtime 的路由决策，仅提供方案结构与任务拆分契约。 diff --git a/Claude/Skills/CN/skills/sopify/design/assets/adr-template.md b/Claude/Skills/CN/skills/sopify/design/assets/adr-template.md deleted file mode 100644 index 20f3377..0000000 --- a/Claude/Skills/CN/skills/sopify/design/assets/adr-template.md +++ /dev/null @@ -1,19 +0,0 @@ -# ADR-001: {决策标题} - -## 状态 -已采纳 | 待定 | 已废弃 - -## 上下文 -{背景和问题} - -## 决策 -{核心决策} - -## 理由 -{原因} - -## 替代方案 -- {方案A}: 拒绝原因 - {原因} - -## 影响 -{后果与风险} diff --git a/Claude/Skills/CN/skills/sopify/design/assets/background-template.md b/Claude/Skills/CN/skills/sopify/design/assets/background-template.md deleted file mode 100644 index 1df45ee..0000000 --- a/Claude/Skills/CN/skills/sopify/design/assets/background-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# 变更提案: {功能名称} - -## 需求背景 -{描述现状、痛点及变更驱动因素} - -评分: -- 方案质量: {X}/10 -- 落地就绪: {Y}/10 - -评分理由: -- 优点: {1 行} -- 扣分: {1 行} - -## 变更内容 -1. {变更点1} -2. {变更点2} - -## 影响范围 -- 模块: {列表} -- 文件: {列表} - -## 风险评估 -- 风险: {描述} -- 缓解: {措施} diff --git a/Claude/Skills/CN/skills/sopify/design/assets/design-template.md b/Claude/Skills/CN/skills/sopify/design/assets/design-template.md deleted file mode 100644 index 90dcb27..0000000 --- a/Claude/Skills/CN/skills/sopify/design/assets/design-template.md +++ /dev/null @@ -1,14 +0,0 @@ -# 技术设计: {功能名称} - -## 技术方案 -- 核心技术: {语言/框架/库} -- 实现要点: - - {要点1} - - {要点2} - -## 架构设计 -{如有变更，包含 mermaid 图} - -## 安全与性能 -- 安全: {措施} -- 性能: {优化} diff --git a/Claude/Skills/CN/skills/sopify/design/assets/output-summary.md b/Claude/Skills/CN/skills/sopify/design/assets/output-summary.md deleted file mode 100644 index 7c56c91..0000000 --- a/Claude/Skills/CN/skills/sopify/design/assets/output-summary.md +++ /dev/null @@ -1,14 +0,0 @@ -[{BRAND_NAME}] 方案设计 ✓ - -方案: .sopify-skills/plan/{YYYYMMDD}_{feature}/ -概要: {一句话技术方案} -任务: {N} 项 -方案质量: {X}/10 -落地就绪: {Y}/10 -评分理由: {1 行} - ---- -Changes: {N} files - - .sopify-skills/plan/... - -Next: 在宿主会话中继续评审或执行方案，或直接回复修改意见 diff --git a/Claude/Skills/CN/skills/sopify/design/assets/plan-light-template.md b/Claude/Skills/CN/skills/sopify/design/assets/plan-light-template.md deleted file mode 100644 index 285640f..0000000 --- a/Claude/Skills/CN/skills/sopify/design/assets/plan-light-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# {功能名称} - -## 背景 -{1-2 句话描述需求背景} - -评分: -- 方案质量: {X}/10 -- 落地就绪: {Y}/10 - -评分理由: -- 优点: {1 行} -- 扣分: {1 行} - -## 方案 -{技术方案要点，列表形式} - -## 任务 -- [ ] {任务1} -- [ ] {任务2} -- [ ] {任务3} - -## 变更文件 -- {file1} -- {file2} diff --git a/Claude/Skills/CN/skills/sopify/design/assets/tasks-template.md b/Claude/Skills/CN/skills/sopify/design/assets/tasks-template.md deleted file mode 100644 index 4be5031..0000000 --- a/Claude/Skills/CN/skills/sopify/design/assets/tasks-template.md +++ /dev/null @@ -1,13 +0,0 @@ -# 任务清单: {功能名称} - -目录: `.sopify-skills/plan/YYYYMMDD_{feature}/` - -## 1. {模块名称} -- [ ] 1.1 在 `{文件路径}` 中实现 {功能} -- [ ] 1.2 在 `{文件路径}` 中实现 {功能} - -## 2. 测试 -- [ ] 2.1 {测试任务} - -## 3. 文档更新 -- [ ] 3.1 更新 `project.md / blueprint/background.md / blueprint/design.md / blueprint/tasks.md` diff --git a/Claude/Skills/CN/skills/sopify/design/references/design-rules.md b/Claude/Skills/CN/skills/sopify/design/references/design-rules.md deleted file mode 100644 index d4e785d..0000000 --- a/Claude/Skills/CN/skills/sopify/design/references/design-rules.md +++ /dev/null @@ -1,92 +0,0 @@ -# Design 详细规则 - -## 目标 - -设计技术方案，拆分可执行任务，生成可回放的方案包。 - -## 总流程 - -1. 判定方案包级别（`light/standard/full`）。 -2. 生成方案文件骨架。 -3. 拆分任务并标注验证标准。 -4. 输出摘要并等待宿主后续动作。 - -## 步骤 1：方案包级别判定 - -自动判定规则（`plan.level=auto`）： - -- `light`：文件数 3-5，且无架构级变更，修改范围明确。 -- `standard`：文件数 >5，或新功能开发，或跨模块改动。 -- `full`：架构级变更、重大重构、新系统设计。 - -## 步骤 2：生成方案文件 - -- `light`：生成 `plan.md`。 -- `standard`：生成 `background.md + design.md + tasks.md`。 -- `full`：在 standard 基础上补 `adr/` 与 `diagrams/`。 -- 正式 plan 包默认带评分区块： - - `light`：写入 `plan.md` - - `standard/full`：写入 `background.md` -- 方案摘要也必须显式输出： - - `方案质量` - - `落地就绪` - - `评分理由` - -模板来源统一使用 `assets/` 目录： - -1. `assets/plan-light-template.md` -2. `assets/background-template.md` -3. `assets/design-template.md` -4. `assets/tasks-template.md` -5. `assets/adr-template.md` - -## 步骤 3：任务拆分 - -任务约束： - -1. 每项建议 30 分钟内可完成。 -2. 每项需具备可验证完成标准。 -3. 依赖关系清晰，避免隐藏前置条件。 - -任务分类建议： - -1. 核心功能实现 -2. 辅助功能 -3. 安全检查 -4. 测试 -5. 文档更新（`project.md / blueprint/*`） - -任务状态符号： - -- `[ ]` 待执行 -- `[x]` 已完成 -- `[-]` 已跳过 -- `[!]` 阻塞中 - -## 阶段转换 - -- `workflow.mode=strict`：输出方案摘要后等待确认。 -- `workflow.mode=adaptive`： - - `~go` 触发：进入执行前确认或后续宿主链路。 - - `~go plan` 触发：只输出方案摘要并停止。 -- 用户反馈修改意见：留在本阶段，更新文件后再次输出摘要。 - -## runtime helper 边界 - -当仓库存在 `scripts/sopify_runtime.py` 且输入为原始请求时： - -1. 优先交给默认 runtime 入口，不手工强制改写为 `~go plan`。 -2. 明确是 `~go plan` 路径时，优先调用 `scripts/go_plan_runtime.py`。 -3. `go_plan_runtime.py` 仅用于 plan-only slice。 - -入口缺失时，才按本技能模板手工生成方案文件。 - -## 命名规则 - -方案目录格式：`YYYYMMDD_feature_name` - -示例： - -- `20260115_user_auth` -- `20260115_fix_login_bug` -- `20260115_refactor_api` diff --git a/Claude/Skills/CN/skills/sopify/design/scripts/select_plan_level.py b/Claude/Skills/CN/skills/sopify/design/scripts/select_plan_level.py deleted file mode 100644 index 0c4f663..0000000 --- a/Claude/Skills/CN/skills/sopify/design/scripts/select_plan_level.py +++ /dev/null @@ -1,61 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic plan-level selector for design skill.""" - -from __future__ import annotations - -import argparse -import json -from typing import List - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Select plan level based on explicit change signals." - ) - parser.add_argument("--file-count", type=int, required=True) - parser.add_argument("--architecture-change", action="store_true") - parser.add_argument("--major-refactor", action="store_true") - parser.add_argument("--new-system", action="store_true") - parser.add_argument("--new-feature", action="store_true") - parser.add_argument("--cross-module", action="store_true") - return parser.parse_args() - - -def main() -> int: - args = parse_args() - reasons: List[str] = [] - - if args.architecture_change or args.major_refactor or args.new_system: - level = "full" - if args.architecture_change: - reasons.append("architecture_change") - if args.major_refactor: - reasons.append("major_refactor") - if args.new_system: - reasons.append("new_system") - elif args.file_count > 5 or args.new_feature or args.cross_module: - level = "standard" - if args.file_count > 5: - reasons.append("file_count_gt_5") - if args.new_feature: - reasons.append("new_feature") - if args.cross_module: - reasons.append("cross_module") - elif 3 <= args.file_count <= 5: - level = "light" - reasons.append("file_count_between_3_and_5") - else: - level = "light" - reasons.append("default_light_for_small_scope") - - result = { - "plan_level": level, - "file_count": args.file_count, - "reasons": reasons, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Claude/Skills/CN/skills/sopify/develop/SKILL.md b/Claude/Skills/CN/skills/sopify/develop/SKILL.md deleted file mode 100644 index 45e68f2..0000000 --- a/Claude/Skills/CN/skills/sopify/develop/SKILL.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: develop -description: 开发实施阶段入口；聚合任务执行、状态更新、知识库同步与收尾迁移规则，按需加载 references/assets/scripts。 ---- - -# Develop（入口文档） - -## 何时激活 - -- 进入开发实施阶段（`workflow` / `light_iterate` / `quick_fix` / `exec_plan`）。 -- 需要执行任务清单、更新状态并收敛交付结果。 - -## 执行骨架 - -1. 读取活动方案任务（`tasks.md` 或 light 的 `plan.md`）。 -2. 提取待执行任务并按编号顺序执行。 -3. 每完成一步更新任务状态（`[ ] -> [x] / [-] / [!]`）。 -4. 同步知识库与偏好/反馈（保守写入）。 -5. 方案完成后迁移到 `history/` 并更新索引。 -6. 按结果输出成功/部分成功/快速修复摘要。 - -## 资源导航 - -- 长规则：`references/develop-rules.md` -- 输出模板：`assets/*.md` -- 任务提取脚本：`scripts/extract_pending_tasks.py` - -## 确定性逻辑（脚本优先） - -当需要可审计地提取任务状态时，优先调用： - -```bash -python3 skills/zh/skills/sopify/develop/scripts/extract_pending_tasks.py \ - --tasks-file .sopify-skills/plan//tasks.md -``` - -脚本输出 JSON，包含：待执行任务、状态统计与执行顺序。 - -## 边界 - -- 本技能负责执行与收尾，不负责重新定义方案结构（交给 `design`）。 -- 回滚属于显式用户动作，必须保留可追溯记录。 diff --git a/Claude/Skills/CN/skills/sopify/develop/assets/output-partial.md b/Claude/Skills/CN/skills/sopify/develop/assets/output-partial.md deleted file mode 100644 index 46ffd5c..0000000 --- a/Claude/Skills/CN/skills/sopify/develop/assets/output-partial.md +++ /dev/null @@ -1,13 +0,0 @@ -[{BRAND_NAME}] 开发实施 ! - -完成: {M}/{N} 任务 -阻塞: {K} 项 - -阻塞任务: - - [!] 2.3 {任务描述} - {阻塞原因} - ---- -Changes: {N} files - - ... - -Next: 解决阻塞后在宿主会话中继续恢复当前流程 diff --git a/Claude/Skills/CN/skills/sopify/develop/assets/output-quick-fix.md b/Claude/Skills/CN/skills/sopify/develop/assets/output-quick-fix.md deleted file mode 100644 index 61334a9..0000000 --- a/Claude/Skills/CN/skills/sopify/develop/assets/output-quick-fix.md +++ /dev/null @@ -1,10 +0,0 @@ -[{BRAND_NAME}] 快速修复 ✓ - -修复: {一句话描述} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: 请验证修复 diff --git a/Claude/Skills/CN/skills/sopify/develop/assets/output-success.md b/Claude/Skills/CN/skills/sopify/develop/assets/output-success.md deleted file mode 100644 index 97572ad..0000000 --- a/Claude/Skills/CN/skills/sopify/develop/assets/output-success.md +++ /dev/null @@ -1,13 +0,0 @@ -[{BRAND_NAME}] 开发实施 ✓ - -完成: {N}/{N} 任务 -测试: 通过 - ---- -Changes: {N} files - - src/xxx.vue - - src/xxx.ts - - .sopify-skills/blueprint/design.md - - .sopify-skills/history/... - -Next: 请验证功能 diff --git a/Claude/Skills/CN/skills/sopify/develop/references/develop-rules.md b/Claude/Skills/CN/skills/sopify/develop/references/develop-rules.md deleted file mode 100644 index ee69802..0000000 --- a/Claude/Skills/CN/skills/sopify/develop/references/develop-rules.md +++ /dev/null @@ -1,233 +0,0 @@ -# Develop 详细规则 - -## 目标 - -按任务清单实施开发，维护任务状态，按 `knowledge_sync` 同步 V2 长期知识，并通过 task-level 质量循环确保“有验证证据才算完成”。 - -## 总流程 - -1. 读取任务清单。 -2. 对每个任务按固定质量循环执行：实现修改 -> 发现验证 -> 执行验证 -> 必要时一次重试 -> 两阶段复审。仅在质量结果满足最小 contract 后更新任务状态。 -3. 若工作区存在 `post_develop` advisory skill 且前置条件满足，执行一次 post-develop advisory review。 -4. 按 `knowledge_sync` 同步知识库与偏好信息。 -5. 迁移方案包到 `history/`。 -6. 输出执行结果摘要。 - -## 步骤 1：读取任务清单 - -来源： - -- `.sopify-skills/plan/{current_plan}/tasks.md` -- `.sopify-skills/plan/{current_plan}/plan.md`（light） - -处理规则： - -1. 提取 `[ ]` 待执行任务。 -2. 按任务编号顺序执行。 -3. 先检查显式依赖再执行。 - -## 步骤 2：执行任务 - -### 2.1 任务级质量循环 - -每个任务按以下顺序执行： - -1. 定位目标文件。 -2. 理解当前实现。 -3. 实施修改。 -4. 发现验证命令。 -5. 执行验证。 -6. 首次失败时允许带失败上下文自动重试一次。 -7. 对失败收口做结构化根因分类。 -8. 执行两阶段复审：`spec_compliance` -> `code_quality`。 -9. 只有质量结果满足最小 contract 后才更新状态。 - -硬性约束： - -- 没有验证证据，不算完成。 -- `overbuild`、`underbuild`、`应该没问题` 这类主观判断不能替代验证或复审结果。 -- 不允许静默跳过验证，也不允许无限重试。 - -### 2.2 最小 verify contract - -develop 阶段统一使用以下字段名，不再混用 `discovery_source`、`status`、`configured`、`discovered` 等别名： - -1. `verification_source` - - 只表达验证来源，允许值固定为： - - `project_contract` - - `project_native` - - `not_configured` -2. `command` - - 记录本次尝试执行的验证命令。 - - 若没有稳定命令，允许为空，但必须补 `reason_code`，不能伪装为已验证。 -3. `scope` - - 记录验证覆盖的任务、文件或模块范围。 -4. `result` - - 固定使用： - - `passed` - - `retried` - - `failed` - - `skipped` - - `replan_required` -5. `reason_code` - - 当无法执行、显式降级、跳过或回退 plan review 时必须存在。 -6. `retry_count` - - v1 只允许 `0` 或 `1`。 -7. `root_cause` - - 失败收口或重试路径上必须存在。 -8. `review_result` - - 必须至少包含 `spec_compliance` 与 `code_quality` 两阶段结论。 - -补充说明： - -- `.sopify-skills/project.md` 的 `verify` 约定是后续长期落点；当它已存在时，作为最高优先级来源，但不是当前 v1 落地前提。 -- `verification_source` 只表示来源，不复用为结果态；“是否跳过/为何降级”统一通过 `result + reason_code` 表达。 - -### 2.3 验证发现顺序 - -固定优先级： - -1. `project_contract` - - 即 `.sopify-skills/project.md` 中已显式定义的 `verify` 约定。 -2. `project_native` - - 项目原生脚本或配置，例如 `package.json`、`pyproject.toml`、`Makefile`、`justfile` 中稳定的验证入口。 -3. `not_configured` - - 当仓库没有稳定命令时，必须可见降级，并写明 `reason_code`；不能把“没有找到命令”视为默认通过。 - -### 2.4 失败处理与根因分类 - -失败处理口径： - -1. 第一次验证失败后，允许自动重试一次。 -2. 第二次仍失败时，必须停止自动重试。 -3. 第二次失败或显式放弃重试时，必须写入 `root_cause`。 - -`root_cause` 允许值固定为： - -- `logic_regression` -- `environment_or_dependency` -- `missing_test_infra` -- `scope_or_design_mismatch` - -分流约束： - -- `logic_regression`：允许继续 develop，但必须带失败上下文修复。 -- `environment_or_dependency`：可见标记环境无法证明通过，不把任务伪装为已验证完成。 -- `missing_test_infra`：允许保留任务未验证完成，并显式写出补测要求。 -- `scope_or_design_mismatch`：不得继续盲修，应优先回到 plan review、decision checkpoint 或其他宿主确认链路。 - -### 2.5 两阶段复审 - -Stage A `spec_compliance` 至少检查： - -1. 是否满足当前任务目标与边界。 -2. 是否存在明显 `overbuild` 或 `underbuild`。 -3. 是否引入新的范围变化或需要用户拍板的分叉。 - -Stage B `code_quality` 至少检查： - -1. 是否与现有代码风格一致。 -2. 是否存在明显安全性、稳定性或可维护性回退。 -3. 修改面、注释、测试与知识同步是否达到当前任务最低标准。 - -状态迁移： - -- 成功：只有当 `verification_source / result / review_result` 满足最小 contract 时，才允许 `[ ] -> [x]` -- 跳过：`[ ] -> [-]` -- 阻塞：`[ ] -> [!]` - -安全底线： - -- 不引入常见漏洞（XSS / SQL 注入等）。 -- 不破坏既有功能。 -- 保持项目代码风格一致。 - -## 步骤 3：Post-develop advisory review - -开发任务完成、验证与两阶段复审通过后，若工作区 `.agents/skills/` 下存在 triggers 包含 `post_develop` 且 mode 为 `advisory` 的技能，可按其 SKILL.md 执行一次 post-develop advisory review。当前仅 CrossReview Phase 4a 纳入此路径。 - -触发条件： - -1. 所有任务已通过质量循环（Step 2 完成）。 -2. 工作区存在未评审的代码变更（已提交的 review range `git diff ..HEAD` 非空，或存在未提交变更须按 advisory skill Step 0 确认处理）。 -3. 对应 advisory skill 的前置条件满足（如 CLI 已安装，且 host-integrated 审查所需的隔离执行上下文可用）。 - -执行约束： - -- 执行失败或结果 `inconclusive` 不阻断主流程。 -- `concerns` / `needs_human_triage` 只展示并等待用户决定，不自动写 checkpoint、不自动改代码。 -- 若前置条件不满足（如 CLI 未安装），跳过并记录原因，不阻断。 -- 注释：Phase 4a 仅采用 Convention 模式；这里不引入 `bridge.py`、`pipeline_hooks` 或 runtime lifecycle hook。 - -## 步骤 4：知识库同步 - -同步时机： - -1. 每完成一个模块任务后。 -2. 阶段收尾时做统一复核。 - -同步目标： - -- `project.md` -- `blueprint/background.md` -- `blueprint/design.md` -- `blueprint/tasks.md` -- `user/preferences.md`（仅长期偏好） -- `user/feedback.jsonl` - -正式判断口径： - -- `knowledge_sync.skip`：本轮不要求同步。 -- `knowledge_sync.review`：finalize 前至少复核。 -- `knowledge_sync.required`：未更新则 finalize 阻断。 - -偏好写入（保守策略）： - -允许写入： - -- 用户明确表达长期偏好（如“以后默认...”）。 - -禁止写入： - -- 一次性指令。 -- 上下文不完整的猜测。 -- 与任务无关的泛化结论。 - -## 步骤 5：方案迁移 - -迁移路径： - -```text -.sopify-skills/plan/YYYYMMDD_feature/ - -> .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/ -``` - -索引更新：在首次显式 finalize 时按需创建并更新 `.sopify-skills/history/index.md`。 - -## 输出模板 - -按结果类型选择 `assets/`： - -1. `assets/output-success.md` -2. `assets/output-partial.md` -3. `assets/output-quick-fix.md` - -## 特殊情况 - -执行中断： - -1. 已完成任务标记 `[x]`。 -2. 当前任务保持 `[ ]`。 -3. 输出中断摘要，等待宿主恢复。 - -任务失败： - -1. 标记 `[!]` 并注明原因。 -2. 若存在失败收口，必须补 `reason_code`，并在需要时补 `root_cause` 与 `review_result`。 -3. 仅继续不受阻塞的独立任务。 - -回滚请求： - -1. 使用 git 回滚（仅在用户明确要求时）。 -2. 保留方案包在 `plan/`，不迁移。 -3. 输出回滚确认。 diff --git a/Claude/Skills/CN/skills/sopify/develop/scripts/extract_pending_tasks.py b/Claude/Skills/CN/skills/sopify/develop/scripts/extract_pending_tasks.py deleted file mode 100644 index 812d5e2..0000000 --- a/Claude/Skills/CN/skills/sopify/develop/scripts/extract_pending_tasks.py +++ /dev/null @@ -1,69 +0,0 @@ -#!/usr/bin/env python3 -"""Extract deterministic task status summary from a plan markdown file.""" - -from __future__ import annotations - -import argparse -import json -import re -from pathlib import Path -from typing import Dict, List - -TASK_PATTERN = re.compile(r"^\s*-\s*\[(?P[ x!\-])\]\s*(?P.+?)\s*$") - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Extract pending/completed/blocked/skipped tasks from markdown." - ) - parser.add_argument("--tasks-file", required=True, help="Path to tasks.md or plan.md") - return parser.parse_args() - - -def classify_status(raw: str) -> str: - if raw == " ": - return "pending" - if raw == "x": - return "completed" - if raw == "!": - return "blocked" - if raw == "-": - return "skipped" - return "unknown" - - -def main() -> int: - args = parse_args() - path = Path(args.tasks_file) - lines = path.read_text(encoding="utf-8").splitlines() - - tasks: List[Dict[str, str]] = [] - counts: Dict[str, int] = { - "pending": 0, - "completed": 0, - "blocked": 0, - "skipped": 0, - } - - for idx, line in enumerate(lines, start=1): - match = TASK_PATTERN.match(line) - if not match: - continue - status_key = classify_status(match.group("status")) - text = match.group("text") - tasks.append({"line": idx, "status": status_key, "text": text}) - if status_key in counts: - counts[status_key] += 1 - - result = { - "tasks_file": str(path), - "counts": counts, - "pending_tasks": [task for task in tasks if task["status"] == "pending"], - "all_tasks": tasks, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Claude/Skills/CN/skills/sopify/kb/SKILL.md b/Claude/Skills/CN/skills/sopify/kb/SKILL.md deleted file mode 100644 index 4e26de0..0000000 --- a/Claude/Skills/CN/skills/sopify/kb/SKILL.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -name: kb -description: 知识库管理技能；知识库操作时读取；包含初始化、更新、同步策略 ---- - -# 知识库管理 - V2 规则 - -**目标：** 管理 `.sopify-skills/` 的 V2 分层知识，保持长期知识、活动方案与归档层职责清晰。 - -## 知识库结构 - -```text -.sopify-skills/ -├── blueprint/ -│ ├── README.md # 纯索引页，只保留索引必需区块 -│ ├── background.md # 长期目标、范围、非目标 -│ ├── design.md # 模块/宿主/目录/消费契约 -│ └── tasks.md # 未完成长期项与明确延后项 -├── project.md # 项目技术约定 -├── user/ -│ ├── preferences.md # 用户长期偏好 -│ └── feedback.jsonl # 原始反馈事件 -├── plan/ -│ └── YYYYMMDD_feature/ # 当前活动方案 -├── history/ -│ ├── index.md # 归档索引 -│ └── YYYY-MM/ -└── state/ # runtime machine truth -``` - -## 初始化策略 - -### Full 模式 (`kb_init: full`) - -首次 bootstrap 直接创建： - -```yaml -创建文件: - - .sopify-skills/project.md - - .sopify-skills/user/preferences.md - - .sopify-skills/user/feedback.jsonl - - .sopify-skills/blueprint/README.md - - .sopify-skills/blueprint/background.md - - .sopify-skills/blueprint/design.md - - .sopify-skills/blueprint/tasks.md -``` - -注意： - -- 不预建 `plan/` 正文。 -- 不预建 `history/index.md` 或任何 archive。 - -### Progressive 模式 (`kb_init: progressive`) [默认] - -按生命周期创建： - -```yaml -首次真实项目触发: - - .sopify-skills/project.md - - .sopify-skills/user/preferences.md - - .sopify-skills/blueprint/README.md - -首次进入 plan 生命周期: - - .sopify-skills/blueprint/background.md - - .sopify-skills/blueprint/design.md - - .sopify-skills/blueprint/tasks.md - - .sopify-skills/plan/YYYYMMDD_feature/ - -首次显式 ~go finalize: - - .sopify-skills/history/index.md - - .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/ - -首次出现明确长期偏好: - - .sopify-skills/user/feedback.jsonl -``` - -## 上下文读取顺序 - -1. `project.md` -2. `user/preferences.md` -3. `blueprint/README.md` -4. `blueprint/background.md` -5. `blueprint/design.md` -6. `blueprint/tasks.md` -7. `active_plan = current_plan.path + current_plan.files` - -读取规则： - -- 咨询/澄清优先消费 `L0/L1`，不强制要求 deep blueprint。 -- planning / develop 才进入 `L2 active plan`。 -- `history/` 不是默认长期上下文，只在 finalize 后查询或人工追溯时读取。 - -## 更新规则 - -### L0 索引约束 - -- `blueprint/README.md` 只保留 `状态 / 维护方式 / 当前目标 / 当前焦点 / 深入阅读入口`。 -- 不把绝对工作目录、架构正文、正式契约正文写进 `blueprint/README.md`。 -- 若 `blueprint/` 根层存在额外长期专题文档，必须在 `blueprint/README.md` 显式列出入口。 - -### `blueprint/tasks.md` 边界 - -- 只保留未完成长期项与明确延后项。 -- `[x]` 已完成项不应继续保留在 `blueprint/tasks.md`。 - -### 必须更新 - -- `project.md`：跨任务可复用的技术约定变化。 -- `blueprint/background.md`：长期目标、范围、非目标变化。 -- `blueprint/design.md`：模块/宿主/目录/消费契约变化。 -- `blueprint/tasks.md`：长期未完成项或明确延后项变化。 -- `user/preferences.md`：用户明确声明长期偏好。 - -### 不应写入长期知识 - -- 一次性实现细节。 -- 当前 plan 的短期拆解。 -- 仅属于本轮任务的临时取舍。 -- 已完成任务清单继续滞留在 `blueprint/tasks.md`。 -- history 正文回灌到 blueprint。 - -## `knowledge_sync` 同步契约 - -```yaml -knowledge_sync: - project: skip|review|required - background: skip|review|required - design: skip|review|required - tasks: skip|review|required -``` - -执行要求： - -- `skip`：本轮不要求同步。 -- `review`：finalize 前至少复核。 -- `required`：未更新则 finalize 阻断。 - -## 冲突处理 - -- 代码与文档冲突：以代码现状为准，文档随后修正。 -- 当前任务与长期偏好冲突：当前任务明确要求 > `user/preferences.md` > 默认规则。 - -## 输出格式 - -**初始化完成：** - -```text -[{BRAND_NAME}] 知识库初始化 ✓ - -创建: {N} 文件 -策略: {full/progressive} - ---- -Changes: {N} files - - .sopify-skills/project.md - - .sopify-skills/blueprint/README.md - - ... - -Next: 知识库已就绪 -``` - -**同步完成：** - -```text -[{BRAND_NAME}] 知识库同步 ✓ - -更新: {N} 文件 - ---- -Changes: {N} files - - .sopify-skills/project.md - - .sopify-skills/blueprint/design.md - - ... - -Next: 文档已更新 -``` diff --git a/Claude/Skills/CN/skills/sopify/templates/SKILL.md b/Claude/Skills/CN/skills/sopify/templates/SKILL.md deleted file mode 100644 index 4a14094..0000000 --- a/Claude/Skills/CN/skills/sopify/templates/SKILL.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -name: templates -description: 文档模板集合；创建文档时读取；包含所有知识库模板和方案文件模板 ---- - -# 文档模板集合 - -**模板使用说明：** -1. 将 `{...}` 内容替换为实际内容。 -2. 正式 plan 包默认带评分区块。 -3. `blueprint/README.md` 只保留轻量入口索引。 -4. 若 `blueprint/` 根层存在额外长期专题文档，必须在 `blueprint/README.md` 里显式列入口。 -5. `blueprint/tasks.md` 只保留未完成长期项与明确延后项；已完成项不继续保留在该文件。 - -## A1 | 知识库文档模板 - -### project.md - -```markdown -# 项目技术约定 - -## 技术栈 -- 核心: {语言版本} / {框架版本} -- 构建: {构建工具} -- 测试: {测试框架} - -## 使用约定 -- 这里只沉淀可复用的长期技术约定。 -- 一次性实现细节不默认写入本文件。 - -## 文档边界 -- `project.md`: 可复用技术约定 -- `blueprint/background.md`: 长期目标、范围、非目标 -- `blueprint/design.md`: 模块/宿主/目录/消费契约 -- `blueprint/tasks.md`: 未完成长期项与明确延后项 -``` - -### blueprint/README.md - -```markdown -# 项目蓝图索引 - -状态: {当前状态} -维护方式: 仅保留状态、当前目标、当前焦点与阅读入口；长说明进入其他 blueprint 文件 - -## 当前目标 -- 项目：`{项目名}` -- 长期目标与范围进入 `./background.md` - -## 当前焦点 -- 当前活动 plan：{有/无} -- history 归档：{状态} - -## 深入阅读入口 -- [项目技术约定](../project.md) -- [蓝图背景](./background.md) -- [蓝图设计](./design.md) -- [蓝图任务](./tasks.md) -- [长期专题蓝图](./{extra_blueprint_doc}.md) # 如存在额外长期专题文档，则逐项列出 -- [变更历史](../history/index.md) -``` - -### blueprint/background.md - -```markdown -# 蓝图背景 - -## 长期目标 -- {目标1} -- {目标2} - -## 范围 -- 范围内: {内容} -- 范围外: {内容} - -## 非目标 -- {内容} -``` - -### blueprint/design.md - -```markdown -# 蓝图设计 - -## 正式契约 -- `knowledge_sync` 是唯一正式同步契约。 -- `active_plan = current_plan.path + current_plan.files`。 - -## 消费契约 - -| Context Profile | Reads | Fail-open Rule | Notes | -|-----|------|------|------| -| `consult` | `project.md`, `preferences.md`, `blueprint/README.md` | 缺 deep blueprint 不报错 | 不强制物化 plan | -| `plan` | `L1` + `active_plan` | 缺 deep blueprint 时按生命周期补齐 | history 不是默认上下文 | -| `finalize` | `active_plan`, `knowledge_sync`, `blueprint/*`, `history/index.md` | 缺 `history/index.md` 时现场创建 | `required` 未满足则阻断 | -``` - -### blueprint/tasks.md - -```markdown -# 蓝图任务 - -状态: 只保留未完成长期项与明确延后项；已完成项不继续留在本文件。 - -## 未完成长期项 -- [ ] {长期项} - -## 明确延后项 -- [-] {延后项} -``` - -### history/index.md - -```markdown -# 变更历史索引 - -| 时间戳 | 功能名称 | 状态 | 方案包 | -|--------|----------|------|--------| -| {YYYYMMDD} | {功能} | ✓ | [链接](YYYY-MM/...) | -``` - -### user/preferences.md - -```markdown -# 用户长期偏好 - -> 仅记录用户明确声明的长期偏好；一次性指令不入库。 - -当前暂无已确认的长期偏好。 -``` - -### user/feedback.jsonl - -```json -{"timestamp":"2026-01-15T10:30:00Z","source":"chat","message":"以后默认先给最小改动清单","scope":"planning","promote_to_preference":true,"preference_id":"pref-002"} -{"timestamp":"2026-01-15T11:10:00Z","source":"chat","message":"这次把输出写详细点","scope":"current_task","promote_to_preference":false} -``` - -## A2 | 方案文件模板 - -### Light 级别 - plan.md - -```markdown -# {功能名称} - -## 背景 -{1-2 句话描述需求背景} - -评分: -- 方案质量: {X}/10 -- 落地就绪: {Y}/10 - -评分理由: -- 优点: {1 行} -- 扣分: {1 行} - -## 方案 -- {技术方案要点1} -- {技术方案要点2} - -## 任务 -- [ ] {任务1} -- [ ] {任务2} - -## 变更文件 -- {file1} -- {file2} -``` - -### Standard 级别 - background.md - -```markdown -# 变更提案: {功能名称} - -## 需求背景 -{描述现状、痛点及变更驱动因素} - -评分: -- 方案质量: {X}/10 -- 落地就绪: {Y}/10 - -评分理由: -- 优点: {1 行} -- 扣分: {1 行} - -## 变更内容 -1. {变更点1} -2. {变更点2} - -## 影响范围 -- 模块: {列表} -- 文件: {列表} - -## 风险评估 -- 风险: {描述} -- 缓解: {措施} -``` - -### Standard 级别 - design.md - -```markdown -# 技术设计: {功能名称} - -## 技术方案 -- 核心技术: {语言/框架/库} -- 实现要点: - - {要点1} - - {要点2} - -## 架构设计 -{如有架构变更} - -## 安全与性能 -- 安全: {措施} -- 性能: {优化} -``` - -### Standard 级别 - tasks.md - -```markdown -# 任务清单: {功能名称} - -目录: `.sopify-skills/plan/{YYYYMMDD}_{feature}/` - -## 1. {模块名称} -- [ ] 1.1 在 `{文件路径}` 中实现 {功能} -- [ ] 1.2 在 `{文件路径}` 中实现 {功能} - -## 2. 测试 -- [ ] 2.1 {测试任务} - -## 3. 文档更新 -- [ ] 3.1 更新 `project.md / blueprint/background.md / blueprint/design.md / blueprint/tasks.md` -``` - -### Full 级别 - adr/{NNN}-{title}.md - -```markdown -# ADR-{NNN}: {决策标题} - -## 状态 -已采纳 | 待定 | 已废弃 - -## 日期 -{YYYY-MM-DD} - -## 上下文 -{背景和问题描述} - -## 决策 -{核心决策内容} -``` - -## A3 | 任务状态符号 - -| 符号 | 含义 | -|-----|------| -| `[ ]` | 待执行 | -| `[x]` | 已完成 | -| `[-]` | 已跳过 | -| `[!]` | 阻塞中 | diff --git a/Claude/Skills/EN/CLAUDE.md b/Claude/Skills/EN/CLAUDE.md deleted file mode 100644 index b6db56b..0000000 --- a/Claude/Skills/EN/CLAUDE.md +++ /dev/null @@ -1,372 +0,0 @@ - - - - -# Sopify - Adaptive AI Programming Assistant - -## Role Definition - -**You are Sopify** - An adaptive AI programming partner. Selects the appropriate workflow based on user request, current runtime context, and host capabilities, balancing efficiency and quality. - -**Core Philosophy:** -- **Resumable**: Work can be interrupted at any point and seamlessly resumed next time -- **Pauses for Decisions**: Pauses and waits for your confirmation on important decisions — never pushes forward on its own -- **Adaptive Workflow**: Routes by runtime context and host constraints; execute simple tasks directly, plan complex ones thoroughly -- **One Screen Visible**: Concise output, details in files -- **Configuration Driven**: Customize behavior via `sopify.config.yaml` - ---- - -## Core Rules - -### C1 | Configuration Loading & Branding - -**On Startup:** -```yaml -1. Config priority: project root (./sopify.config.yaml) > global (~/.claude/sopify.config.yaml) > built-in defaults -2. By default, do not create config files automatically; for customization, create sopify.config.yaml in your project root (you can copy from examples/sopify.config.yaml) -3. Merge defaults and set runtime variables -``` - -**Brand Name Resolution (when brand: auto, derived from project name by default):** -``` -Project-name priority: git remote repo name > package.json name > directory name > "project" -Brand format: {project_name}-ai -Example: my-app (project name) → my-app-ai (brand) -``` - -**Default Configuration:** -```yaml -brand: auto -language: en-US -output_style: minimal -title_color: green -workflow.mode: adaptive -workflow.require_score: 7 -workflow.learning.auto_capture: by_requirement -plan.level: auto -plan.directory: .sopify-skills -``` - -Note: Changing `plan.directory` only affects newly generated knowledge base/plan files. Existing data in the old directory will not be migrated automatically. -Note: `title_color` applies only to lightweight styling of the output title line. If color is unsupported, automatically fallback to plain text. -Note: `workflow.learning.auto_capture` controls proactive logging only. Replay/review/why intent recognition remains always enabled. - -### C2 | Output Format - -**Unified Output Template:** -``` -[{BRAND_NAME}] {Phase} {Status} - -{Core info, max 3 lines} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: {Next step hint} -``` - -**Footer Contract:** -- the footer always follows the `Changes` block -- `Next:` must be the final line in the footer. -- the footer does not display generated time; if a machine-auditable timestamp is needed, internal summary files may keep ISO 8601 timestamps with timezone data. - -**Status Symbols:** -| Symbol | Meaning | -|--------|---------| -| `✓` | Success | -| `?` | Awaiting input | -| `!` | Warning/Confirmation needed | -| `×` | Cancelled/Error | - -**Phase Names:** -- Requirements Analysis, Solution Design, Development -- Quick Fix, Light Iteration -- Command Complete (command-prefixed flows only, e.g., `~go/~go plan/~go exec`) -- Q&A (non-command questions/clarifications) - -**Output Principles:** -- Core info visible in one screen -- Detailed content in files -- Avoid redundant descriptions -- The title line can be lightly colored via `title_color` (title line only); fallback to plain text when color is unsupported - -### C3 | Workflow Modes - -**Mode Definitions:** - -| Mode | Behavior | -|------|----------| -| `strict` | Enforce 3 phases: Analysis → Design → Development | -| `adaptive` | Auto-select based on complexity (default) | -| `minimal` | Skip planning, execute directly | - -**Adaptive Mode Logic:** -```yaml -Simple Task (direct execution): - - Files ≤ 2 - - Clear requirements - - No architectural changes - -Medium Task (light plan package): - - Files 3-5 - - Clear requirements - - Local modifications - -Complex Task (full 3 phases): - - Files > 5 - - Or architectural changes - - Or new feature development -``` - -**Commands:** -| Command | Description | -|---------|-------------| -| `~go` | Auto-detect and execute full workflow | -| `~go plan` | Plan only, no execution | -| `~go exec` | Advanced recovery/debug entry; use only when an active plan or recovery state already exists | -| `~go finalize` | Close out the current metadata-managed plan | - -Note: Before every Sopify turn, the host must execute the runtime gate and validate its JSON contract. Continue into normal stages only when the gate passes. See `.sopify-skills/blueprint/protocol.md §8.1` for the full gate entry protocol, `allowed_response_mode` values, and ActionProposal capability. - -Note: After runtime execution, the host must consume `.sopify-skills/state/current_handoff.json` structured fields to decide the next step. Respect any pending checkpoint before continuing. See `.sopify-skills/blueprint/protocol.md §8.2` for the full handoff protocol and `required_host_action` values. - -Note: The host must not self-route before the gate, bypass checkpoint constraints, or write machine truth directly. Routing and state management are owned by the runtime. See `.sopify-skills/blueprint/protocol.md §8.3` for boundaries. - -**Host Integration Contract:** See `.sopify-skills/blueprint/protocol.md §8` for the full host runtime integration protocol, including gate entry, handoff consumption, checkpoint handling, runtime helper index, and state file index. - ---- - -## Auto Rules - -> These rules are handled automatically by AI. Users don't need to manage them. - -### A1 | Encoding Handling - -```yaml -Read: Auto-detect file encoding -Write: Use UTF-8 uniformly -Pass: Preserve original encoding -``` - -### A2 | Tool Mapping - -| Operation | Claude Code | Codex CLI | -|-----------|-------------|-----------| -| Read | Read | cat | -| Search | Grep | grep | -| Find | Glob | find/ls | -| Edit | Edit | apply_patch | -| Write | Write | apply_patch | - -### A3 | Platform Adaptation - -**Windows PowerShell (Platform=win32):** -- Use `$env:VAR` instead of `$VAR` -- Use `-Encoding UTF8` -- Use `-gt -lt -eq` instead of `> < ==` - -### A4 | Complexity Assessment - -```yaml -Simple: Files ≤ 2, single module, no architectural changes -Medium: Files 3-5, cross-module, local refactoring -Complex: Files > 5, architectural changes, new features -``` - -### A5 | Plan Package Levels - -| Level | Structure | Trigger | -|-------|-----------|---------| -| light | Single `plan.md` | Medium tasks | -| standard | `background.md` + `design.md` + `tasks.md` | Complex tasks | -| full | Standard + `adr/` + `diagrams/` | Architectural changes | - -**Directory Structure:** -``` -.sopify-skills/ -├── blueprint/ # Project-level long-lived blueprint, tracked by default -│ ├── README.md # Pure index page with status/maintenance/current-goal/current-focus/read-next only -│ ├── background.md -│ ├── design.md -│ └── tasks.md -├── plan/ # Current plans, tracked in git -│ ├── _registry.yaml # Local machine registry, still ignored -│ └── YYYYMMDD_feature/ -├── history/ # Completed plan archives, tracked in git -├── state/ # Runtime state, always ignored -├── user/ # User preferences and feedback -│ ├── preferences.md -│ └── feedback.jsonl -├── project.md # Technical conventions, not a duplicate of background/design -``` - -### A6 | Lifecycle Management - -```yaml -First Trigger: real project repositories should at least create .sopify-skills/blueprint/README.md -First Plan Lifecycle: populate .sopify-skills/blueprint/background.md / design.md / tasks.md -Plan Creation: .sopify-skills/plan/YYYYMMDD_feature_name/ -Task Close-Out: refresh blueprint README managed sections and update deeper blueprint docs when required -Ready for Verification: migrate to .sopify-skills/history/YYYY-MM/ and update index.md -``` - ---- - -## Advanced Rules - -> Behavior can be adjusted via configuration. - -### X1 | Risk Handling (EHRB) - -**Risk Levels:** -```yaml -strict: Block all high-risk operations -normal: Warn and require confirmation (default) -relaxed: Warn only, don't block -``` - -**High-Risk Operations:** -- Deleting production data -- Modifying auth/authorization logic -- Changing database schema -- Operating sensitive configurations - -### X2 | Knowledge Base Strategy - -```yaml -full: Initialize all template files at once -progressive: Create files as needed (default) -``` - ---- - -## Phase Execution - -### P1 | Requirements Analysis - -**Goal:** Verify requirement completeness, analyze code status - -**Execution Flow:** -``` -1. Check knowledge base status -2. Acquire project context -3. Requirement scoring (10-point scale) - - Goal clarity (0-3) - - Expected results (0-3) - - Scope boundaries (0-2) - - Constraints (0-2) -4. Score ≥ require_score → Continue - Score < require_score → Follow-up or AI decision (based on auto_decide) -``` - -**Output:** -``` -[my-app-ai] Requirements Analysis ✓ - -Requirement: {one-line description} -Score: {X}/10 -Scope: {N} files - ---- -Next: Continue to solution design? (Y/n) -``` - -### P2 | Solution Design - -**Goal:** Design technical solution, break down tasks - -**Execution Flow:** -``` -1. Read design Skill -2. Determine plan package level (light/standard/full) -3. Generate plan files -4. Output summary -``` - -**Output:** -``` -[my-app-ai] Solution Design ✓ - -Plan: .sopify-skills/plan/20260115_feature/ -Summary: {one-line technical solution} -Tasks: {N} items -Solution quality: {X}/10 -Implementation readiness: {Y}/10 -Scoring rationale: {1 line} - ---- -Changes: 3 files - - .sopify-skills/plan/20260115_feature/background.md - - .sopify-skills/plan/20260115_feature/design.md - - .sopify-skills/plan/20260115_feature/tasks.md - -Next: Continue plan review or execution in the host session, or reply with feedback -``` - -### P3 | Development - -**Goal:** Execute tasks, sync knowledge base - -**Execution Flow:** -``` -1. Read develop Skill -2. Execute in tasks.md order -3. Update knowledge base -4. Migrate plan to history/ -5. Output results -``` - -**Output:** -``` -[my-app-ai] Development ✓ - -Completed: {N}/{M} tasks -Tests: {passed/failed/skipped} - ---- -Changes: 5 files - - src/components/xxx.vue - - src/types/index.ts - - src/hooks/useXxx.ts - - .sopify-skills/blueprint/design.md - - .sopify-skills/history/2026-01/... - -Next: Please verify the functionality -``` - ---- - -## Skill Reference - -| Skill | Trigger | Description | -|-------|---------|-------------| -| `analyze` | Enter requirements analysis | Scoring, follow-up logic | -| `design` | Enter solution design | Plan generation, task breakdown | -| `develop` | Enter development | Code execution, KB sync | -| `kb` | Knowledge base operations | Init, update strategies | -| `templates` | Create documents | All template definitions | - -**Loading:** The above are all current builtin skills — runtime-managed workflow skills loaded on-demand by the runtime engine. Standalone invocation is not supported. The authoritative skill catalog is `builtin_catalog.generated.json`. - ---- - -## Quick Reference - -**Common Commands:** -``` -~go # Full workflow auto-execution -~go plan # Plan only, no execution -~go exec # Advanced recovery/debug entry, not the default next step in the main flow -~go finalize # Explicitly close out the current metadata-managed plan -``` - -**Runtime helpers and state files:** See `.sopify-skills/blueprint/protocol.md §8.4–8.5` for the full runtime helper index and state file index. - -**Configuration File:** `sopify.config.yaml` (project root) - -**Knowledge Base Directory:** `.sopify-skills/` - -**Plan Package Path:** `.sopify-skills/plan/YYYYMMDD_feature_name/` diff --git a/Claude/Skills/EN/skills/sopify/analyze/SKILL.md b/Claude/Skills/EN/skills/sopify/analyze/SKILL.md deleted file mode 100644 index e87fc64..0000000 --- a/Claude/Skills/EN/skills/sopify/analyze/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: analyze -description: Analyze phase entry; routes scoring, follow-up, and scope checks through references/assets/scripts. ---- - -# Analyze (Entry) - -## When to activate - -- Entering the analysis phase (`workflow` / `plan_only`). -- Need requirement scoring, clarification, or complexity routing. - -## Execution skeleton - -1. Load `references/analyze-rules.md` first. -2. Run Phase A (KB check, context acquisition, requirement typing, completeness scoring). -3. If the score is below threshold, follow `auto_decide`: - - `false`: ask follow-up questions with `assets/question-output.md`. - - `true`: state explicit assumptions, then continue. -4. After the score passes, run Phase B (objective extraction, code analysis, technical prep). -5. Render the phase summary with `assets/success-output.md`. - -## Resource navigation - -- Long rules: `references/analyze-rules.md` -- Follow-up template: `assets/question-output.md` -- Success template: `assets/success-output.md` -- Deterministic scoring script: `scripts/score_requirement.py` - -## Deterministic logic first - -Use the script when the score must be auditable: - -```bash -python3 skills/en/skills/sopify/analyze/scripts/score_requirement.py \ - --goal-clarity 2 \ - --expected-outcome 2 \ - --scope-boundary 1 \ - --constraints 1 \ - --require-score 7 -``` - -The script returns JSON with total score, threshold result, and missing dimensions. - -## Boundaries - -- This skill does not generate a plan package directly; hand off to `design`. -- This skill does not execute code changes directly; hand off to `develop` or runtime routing. diff --git a/Claude/Skills/EN/skills/sopify/analyze/assets/question-output.md b/Claude/Skills/EN/skills/sopify/analyze/assets/question-output.md deleted file mode 100644 index 02acedb..0000000 --- a/Claude/Skills/EN/skills/sopify/analyze/assets/question-output.md +++ /dev/null @@ -1,10 +0,0 @@ -[{BRAND_NAME}] Requirements Analysis ? - -Current score: {X}/10. Please clarify the following: - -1. {question1} -2. {question2} -3. {question3} - ---- -Next: Reply with the answers, or type "continue" to skip clarification diff --git a/Claude/Skills/EN/skills/sopify/analyze/assets/success-output.md b/Claude/Skills/EN/skills/sopify/analyze/assets/success-output.md deleted file mode 100644 index 345882b..0000000 --- a/Claude/Skills/EN/skills/sopify/analyze/assets/success-output.md +++ /dev/null @@ -1,11 +0,0 @@ -[{BRAND_NAME}] Requirements Analysis ✓ - -Requirement: {one-line description} -Type: {requirement type} -Score: {X}/10 -Scope: {estimated file count} - ---- -Changes: 0 files - -Next: Continue to solution design? (Y/n) diff --git a/Claude/Skills/EN/skills/sopify/analyze/references/analyze-rules.md b/Claude/Skills/EN/skills/sopify/analyze/references/analyze-rules.md deleted file mode 100644 index eef2a9e..0000000 --- a/Claude/Skills/EN/skills/sopify/analyze/references/analyze-rules.md +++ /dev/null @@ -1,104 +0,0 @@ -# Analyze Detailed Rules - -## Goal - -Verify requirement completeness, analyze the current codebase, and provide stable input for downstream design. - -## Overall flow - -```text -Phase A (steps 1-4) -> check score >= require_score? - ├─ yes -> Phase B (steps 5-6) -> render summary - └─ no -> check auto_decide - ├─ true -> continue with explicit assumptions - └─ false -> ask follow-up questions and wait for user input -``` - -## Phase A: Requirement assessment - -### Step 1: Check knowledge-base status - -- Condition: project code exists and the task is not "new project bootstrap". -- Action: check whether `.sopify-skills/` exists. -- Mark the KB as missing when the directory does not exist. - -### Step 2: Acquire project context - -- Read `.sopify-skills/user/preferences.md` and KB files first. -- Scan the codebase only when KB context is insufficient. -- Follow the `kb` skill for KB-specific rules. - -Preference rules: - -1. Use only explicit long-term user preferences. -2. Current-task instructions override historical preferences. -3. Fall back to defaults when no preference matches. - -### Step 3: Determine requirement type - -Candidate types: - -1. New project bootstrap -2. New feature development -3. Feature modification / enhancement -4. Bug fix -5. Refactor / optimization -6. Technical change - -### Step 4: Score requirement completeness - -Scoring dimensions (10 total): - -- Goal clarity: 0-3 -- Expected outcome: 0-3 -- Scope boundary: 0-2 -- Constraints: 0-2 - -Scoring rules: - -- `score >= require_score`: continue to Phase B. -- `score < require_score` and `auto_decide=true`: continue with explicit assumptions. -- `score < require_score` and `auto_decide=false`: ask follow-up questions with `assets/question-output.md`. - -Follow-up rules: - -1. Do not ask for information that code can already provide. -2. Ask only for user-facing gaps: business logic, target behavior, constraints. -3. Ask 3-5 questions. -4. Do not re-ask preferences that are already captured as long-term preferences. - -## Phase B: Code analysis - -### Step 5: Extract key objectives - -- Compress the request into one core objective sentence. -- Distinguish whether the user provided a real goal or only an implementation path. -- When the input is mostly a path, treat that path as a candidate approach rather than the success criterion itself. -- Define verifiable success criteria, and close them in a SMART-style form: deliverable, boundary, constraints, verification, and next stop-point. - -### Step 6: Code analysis and technical preparation - -- Estimate project and change scale. -- Locate related modules and key files. -- Run baseline quality checks (stale information, security risks). -- Pull external documentation only when necessary. - -Stable subset rules: - -1. When the goal is still fuzzy, clarify key facts first; only continue with explicit assumptions when `auto_decide=true`. -2. When the current path is clearly suboptimal, include at least one lower-cost or lower-risk alternative in the analysis summary. -3. Every alternative path should state the tradeoff instead of giving a bare conclusion. -4. Do not force deep challenge mode for `quick_fix`, pure state explanation, or lightweight consult flows. - -## Adaptive routing - -- Simple task (`<=2` files and clear scope): go straight to quick fix. -- Medium task (`3-5` files): enter the light plan path. -- Complex task (`>5` files or architectural change): enter full design. - -## Phase transitions - -- Score below threshold and no auto-decide: keep asking until the score passes or the user cancels. -- `workflow.mode=strict`: render summary and wait for confirmation. -- `workflow.mode=adaptive`: continue automatically according to complexity. -- User says `cancel`: terminate with the cancellation path. diff --git a/Claude/Skills/EN/skills/sopify/analyze/scripts/score_requirement.py b/Claude/Skills/EN/skills/sopify/analyze/scripts/score_requirement.py deleted file mode 100644 index 3392485..0000000 --- a/Claude/Skills/EN/skills/sopify/analyze/scripts/score_requirement.py +++ /dev/null @@ -1,62 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic requirement score calculator for analyze skill.""" - -from __future__ import annotations - -import argparse -import json -from typing import Dict - -MAX_BY_DIMENSION: Dict[str, int] = { - "goal_clarity": 3, - "expected_outcome": 3, - "scope_boundary": 2, - "constraints": 2, -} - - -def _bounded_int(name: str, value: int) -> int: - max_score = MAX_BY_DIMENSION[name] - if value < 0 or value > max_score: - raise ValueError(f"{name} must be in [0, {max_score}], got {value}") - return value - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Compute requirement completeness score in a deterministic way." - ) - parser.add_argument("--goal-clarity", type=int, required=True) - parser.add_argument("--expected-outcome", type=int, required=True) - parser.add_argument("--scope-boundary", type=int, required=True) - parser.add_argument("--constraints", type=int, required=True) - parser.add_argument("--require-score", type=int, default=7) - return parser.parse_args() - - -def main() -> int: - args = parse_args() - scores = { - "goal_clarity": _bounded_int("goal_clarity", args.goal_clarity), - "expected_outcome": _bounded_int("expected_outcome", args.expected_outcome), - "scope_boundary": _bounded_int("scope_boundary", args.scope_boundary), - "constraints": _bounded_int("constraints", args.constraints), - } - - total = sum(scores.values()) - missing_dimensions = [name for name, score in scores.items() if score == 0] - - result = { - "scores": scores, - "total": total, - "max_total": sum(MAX_BY_DIMENSION.values()), - "require_score": args.require_score, - "pass": total >= args.require_score, - "missing_dimensions": missing_dimensions, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Claude/Skills/EN/skills/sopify/design/SKILL.md b/Claude/Skills/EN/skills/sopify/design/SKILL.md deleted file mode 100644 index af25c86..0000000 --- a/Claude/Skills/EN/skills/sopify/design/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: design -description: Design phase entry; routes plan grading, task breakdown, and plan package output through references/assets/scripts. ---- - -# Design (Entry) - -## When to activate - -- Entering the design phase (`workflow` / `plan_only` / `light_iterate`). -- Need to convert validated requirements into a plan package and task list. - -## Execution skeleton - -1. Load `references/design-rules.md`. -2. Decide `light/standard/full` from explicit change signals. -3. Generate the plan files from the matching templates in `assets/`. -4. Produce the task list and validate task granularity. -5. Add the scoring block to the formal plan package and render the scored summary with `assets/output-summary.md`. - -## Resource navigation - -- Long rules: `references/design-rules.md` -- Templates: `assets/*.md` -- Deterministic level selector: `scripts/select_plan_level.py` - -## Deterministic logic first - -Use the selector when `plan.level=auto` must be auditable: - -```bash -python3 skills/en/skills/sopify/design/scripts/select_plan_level.py \ - --file-count 6 \ - --new-feature \ - --cross-module -``` - -The script returns JSON with the suggested level and explicit reasons. - -## Boundaries - -- This skill does not execute code changes directly; hand off to `develop`. -- This skill does not replace runtime routing; it defines the plan structure and task contract only. diff --git a/Claude/Skills/EN/skills/sopify/design/assets/adr-template.md b/Claude/Skills/EN/skills/sopify/design/assets/adr-template.md deleted file mode 100644 index 2e911f2..0000000 --- a/Claude/Skills/EN/skills/sopify/design/assets/adr-template.md +++ /dev/null @@ -1,19 +0,0 @@ -# ADR-001: {Decision Title} - -## Status -Accepted | Proposed | Deprecated - -## Context -{Background and problem} - -## Decision -{Core decision} - -## Rationale -{Reasons} - -## Alternatives -- {Option A}: rejected because - {reason} - -## Consequences -{Impacts and risks} diff --git a/Claude/Skills/EN/skills/sopify/design/assets/background-template.md b/Claude/Skills/EN/skills/sopify/design/assets/background-template.md deleted file mode 100644 index 27546de..0000000 --- a/Claude/Skills/EN/skills/sopify/design/assets/background-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# Change Proposal: {Feature Name} - -## Requirement Background -{Describe the current state, pain points, and change drivers} - -Scoring: -- Solution quality: {X}/10 -- Implementation readiness: {Y}/10 - -Scoring rationale: -- Strengths: {1 line} -- Deductions: {1 line} - -## Change Content -1. {change point 1} -2. {change point 2} - -## Impact Scope -- Modules: {list} -- Files: {list} - -## Risk Assessment -- Risk: {description} -- Mitigation: {measures} diff --git a/Claude/Skills/EN/skills/sopify/design/assets/design-template.md b/Claude/Skills/EN/skills/sopify/design/assets/design-template.md deleted file mode 100644 index f31c60f..0000000 --- a/Claude/Skills/EN/skills/sopify/design/assets/design-template.md +++ /dev/null @@ -1,14 +0,0 @@ -# Technical Design: {Feature Name} - -## Technical Solution -- Core technology: {language/framework/library} -- Implementation points: - - {point1} - - {point2} - -## Architecture Design -{Include a mermaid diagram when the architecture changes} - -## Security and Performance -- Security: {measures} -- Performance: {optimizations} diff --git a/Claude/Skills/EN/skills/sopify/design/assets/output-summary.md b/Claude/Skills/EN/skills/sopify/design/assets/output-summary.md deleted file mode 100644 index 1300570..0000000 --- a/Claude/Skills/EN/skills/sopify/design/assets/output-summary.md +++ /dev/null @@ -1,14 +0,0 @@ -[{BRAND_NAME}] Solution Design ✓ - -Plan: .sopify-skills/plan/{YYYYMMDD}_{feature}/ -Summary: {one-line technical solution} -Tasks: {N} items -Solution quality: {X}/10 -Implementation readiness: {Y}/10 -Scoring rationale: {1 line} - ---- -Changes: {N} files - - .sopify-skills/plan/... - -Next: Continue the review or execution flow in the host session, or reply with feedback diff --git a/Claude/Skills/EN/skills/sopify/design/assets/plan-light-template.md b/Claude/Skills/EN/skills/sopify/design/assets/plan-light-template.md deleted file mode 100644 index fa810a3..0000000 --- a/Claude/Skills/EN/skills/sopify/design/assets/plan-light-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# {Feature Name} - -## Background -{1-2 sentences describing the requirement background} - -Scoring: -- Solution quality: {X}/10 -- Implementation readiness: {Y}/10 - -Scoring rationale: -- Strengths: {1 line} -- Deductions: {1 line} - -## Solution -{Technical solution points as a list} - -## Tasks -- [ ] {task1} -- [ ] {task2} -- [ ] {task3} - -## Changed Files -- {file1} -- {file2} diff --git a/Claude/Skills/EN/skills/sopify/design/assets/tasks-template.md b/Claude/Skills/EN/skills/sopify/design/assets/tasks-template.md deleted file mode 100644 index c74ef01..0000000 --- a/Claude/Skills/EN/skills/sopify/design/assets/tasks-template.md +++ /dev/null @@ -1,13 +0,0 @@ -# Task List: {Feature Name} - -Directory: `.sopify-skills/plan/YYYYMMDD_{feature}/` - -## 1. {Module Name} -- [ ] 1.1 Implement {feature} in `{file path}` -- [ ] 1.2 Implement {feature} in `{file path}` - -## 2. Testing -- [ ] 2.1 {test task} - -## 3. Documentation Update -- [ ] 3.1 Update `project.md / blueprint/background.md / blueprint/design.md / blueprint/tasks.md` diff --git a/Claude/Skills/EN/skills/sopify/design/references/design-rules.md b/Claude/Skills/EN/skills/sopify/design/references/design-rules.md deleted file mode 100644 index 439e087..0000000 --- a/Claude/Skills/EN/skills/sopify/design/references/design-rules.md +++ /dev/null @@ -1,92 +0,0 @@ -# Design Detailed Rules - -## Goal - -Design the technical solution, break work into executable tasks, and generate a replayable plan package. - -## Overall flow - -1. Decide the plan level (`light/standard/full`). -2. Generate the plan file scaffold. -3. Break down tasks and mark verification criteria. -4. Render the summary and wait for the next host action. - -## Step 1: Decide the plan level - -Auto-detection rules (`plan.level=auto`): - -- `light`: 3-5 files, no architectural change, scope is explicit. -- `standard`: more than 5 files, or a new feature, or a cross-module change. -- `full`: architectural change, major refactor, or new system design. - -## Step 2: Generate plan files - -- `light`: generate `plan.md`. -- `standard`: generate `background.md + design.md + tasks.md`. -- `full`: extend standard with `adr/` and `diagrams/`. -- formal plan packages include the scoring block by default: - - `light`: write it into `plan.md` - - `standard/full`: write it into `background.md` -- the plan summary must also surface: - - `Solution quality` - - `Implementation readiness` - - `Scoring rationale` - -Template sources live in `assets/`: - -1. `assets/plan-light-template.md` -2. `assets/background-template.md` -3. `assets/design-template.md` -4. `assets/tasks-template.md` -5. `assets/adr-template.md` - -## Step 3: Break down tasks - -Task constraints: - -1. Each task should fit within about 30 minutes. -2. Each task must have a verifiable completion criterion. -3. Dependencies must be explicit. - -Suggested categories: - -1. Core feature work -2. Supporting work -3. Security checks -4. Testing -5. Documentation updates (`project.md / blueprint/*`) - -Task markers: - -- `[ ]` pending -- `[x]` completed -- `[-]` skipped -- `[!]` blocked - -## Phase transitions - -- `workflow.mode=strict`: render the summary and wait for confirmation. -- `workflow.mode=adaptive`: - - `~go`: continue into execution confirmation or the downstream host flow. - - `~go plan`: stop after rendering the plan summary. -- If the user gives plan feedback, stay in this phase, update the files, and render again. - -## Runtime helper boundaries - -When the repo contains `scripts/sopify_runtime.py` and the input is the raw request: - -1. Prefer the default runtime entry; do not rewrite it manually into `~go plan`. -2. When the intent is explicitly `~go plan`, prefer `scripts/go_plan_runtime.py`. -3. `go_plan_runtime.py` is plan-only and not a generic default entry. - -Generate plan files manually only when the runtime helpers are absent. - -## Naming rules - -Plan directory format: `YYYYMMDD_feature_name` - -Examples: - -- `20260115_user_auth` -- `20260115_fix_login_bug` -- `20260115_refactor_api` diff --git a/Claude/Skills/EN/skills/sopify/design/scripts/select_plan_level.py b/Claude/Skills/EN/skills/sopify/design/scripts/select_plan_level.py deleted file mode 100644 index 0c4f663..0000000 --- a/Claude/Skills/EN/skills/sopify/design/scripts/select_plan_level.py +++ /dev/null @@ -1,61 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic plan-level selector for design skill.""" - -from __future__ import annotations - -import argparse -import json -from typing import List - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Select plan level based on explicit change signals." - ) - parser.add_argument("--file-count", type=int, required=True) - parser.add_argument("--architecture-change", action="store_true") - parser.add_argument("--major-refactor", action="store_true") - parser.add_argument("--new-system", action="store_true") - parser.add_argument("--new-feature", action="store_true") - parser.add_argument("--cross-module", action="store_true") - return parser.parse_args() - - -def main() -> int: - args = parse_args() - reasons: List[str] = [] - - if args.architecture_change or args.major_refactor or args.new_system: - level = "full" - if args.architecture_change: - reasons.append("architecture_change") - if args.major_refactor: - reasons.append("major_refactor") - if args.new_system: - reasons.append("new_system") - elif args.file_count > 5 or args.new_feature or args.cross_module: - level = "standard" - if args.file_count > 5: - reasons.append("file_count_gt_5") - if args.new_feature: - reasons.append("new_feature") - if args.cross_module: - reasons.append("cross_module") - elif 3 <= args.file_count <= 5: - level = "light" - reasons.append("file_count_between_3_and_5") - else: - level = "light" - reasons.append("default_light_for_small_scope") - - result = { - "plan_level": level, - "file_count": args.file_count, - "reasons": reasons, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Claude/Skills/EN/skills/sopify/develop/SKILL.md b/Claude/Skills/EN/skills/sopify/develop/SKILL.md deleted file mode 100644 index 4ba1495..0000000 --- a/Claude/Skills/EN/skills/sopify/develop/SKILL.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: develop -description: Develop phase entry; routes task execution, state updates, KB sync, and plan close-out through references/assets/scripts. ---- - -# Develop (Entry) - -## When to activate - -- Entering the implementation phase (`workflow` / `light_iterate` / `quick_fix` / `exec_plan`). -- Need to execute the task list, update state, and converge the delivery result. - -## Execution skeleton - -1. Read the active plan tasks (`tasks.md` or light `plan.md`). -2. Extract pending tasks and execute them in numbered order. -3. Update task markers after each step (`[ ] -> [x] / [-] / [!]`). -4. Sync KB files and conservative preference / feedback records. -5. Move completed plans into `history/` and update the index. -6. Render the matching result template. - -## Resource navigation - -- Long rules: `references/develop-rules.md` -- Output templates: `assets/*.md` -- Task extraction script: `scripts/extract_pending_tasks.py` - -## Deterministic logic first - -Use the script when task extraction must be auditable: - -```bash -python3 skills/en/skills/sopify/develop/scripts/extract_pending_tasks.py \ - --tasks-file .sopify-skills/plan//tasks.md -``` - -The script returns JSON with pending tasks, status counts, and execution order. - -## Boundaries - -- This skill executes and closes out work; it does not redefine the plan structure. -- Rollback remains an explicit user action and must keep a traceable record. diff --git a/Claude/Skills/EN/skills/sopify/develop/assets/output-partial.md b/Claude/Skills/EN/skills/sopify/develop/assets/output-partial.md deleted file mode 100644 index e9752d7..0000000 --- a/Claude/Skills/EN/skills/sopify/develop/assets/output-partial.md +++ /dev/null @@ -1,13 +0,0 @@ -[{BRAND_NAME}] Development ! - -Completed: {M}/{N} tasks -Blocked: {K} items - -Blocked tasks: - - [!] 2.3 {task description} - {block reason} - ---- -Changes: {N} files - - ... - -Next: Resume the current host flow after resolving the blockers diff --git a/Claude/Skills/EN/skills/sopify/develop/assets/output-quick-fix.md b/Claude/Skills/EN/skills/sopify/develop/assets/output-quick-fix.md deleted file mode 100644 index a280077..0000000 --- a/Claude/Skills/EN/skills/sopify/develop/assets/output-quick-fix.md +++ /dev/null @@ -1,10 +0,0 @@ -[{BRAND_NAME}] Quick Fix ✓ - -Fix: {one-line description} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: Please verify the fix diff --git a/Claude/Skills/EN/skills/sopify/develop/assets/output-success.md b/Claude/Skills/EN/skills/sopify/develop/assets/output-success.md deleted file mode 100644 index c267699..0000000 --- a/Claude/Skills/EN/skills/sopify/develop/assets/output-success.md +++ /dev/null @@ -1,13 +0,0 @@ -[{BRAND_NAME}] Development ✓ - -Completed: {N}/{N} tasks -Tests: passed - ---- -Changes: {N} files - - src/xxx.vue - - src/xxx.ts - - .sopify-skills/blueprint/design.md - - .sopify-skills/history/... - -Next: Please verify the functionality diff --git a/Claude/Skills/EN/skills/sopify/develop/references/develop-rules.md b/Claude/Skills/EN/skills/sopify/develop/references/develop-rules.md deleted file mode 100644 index 1992ccc..0000000 --- a/Claude/Skills/EN/skills/sopify/develop/references/develop-rules.md +++ /dev/null @@ -1,233 +0,0 @@ -# Develop Detailed Rules - -## Goal - -Implement the task list, maintain task state, sync V2 long-lived knowledge through `knowledge_sync`, and enforce a task-level quality loop so work is not treated as complete without verification evidence. - -## Overall flow - -1. Read the task list. -2. Execute each task through the fixed quality loop: implement change -> discover verification -> run verification -> retry once when needed -> perform two-stage review. Update task markers only after the minimum quality contract is satisfied. -3. If the workspace contains a `post_develop` advisory skill and its prerequisites are met, execute a single post-develop advisory review. -4. Sync KB and preference data through `knowledge_sync`. -5. Move the completed plan into `history/`. -6. Render the execution summary. - -## Step 1: Read the task list - -Sources: - -- `.sopify-skills/plan/{current_plan}/tasks.md` -- `.sopify-skills/plan/{current_plan}/plan.md` (light) - -Handling rules: - -1. Extract `[ ]` pending tasks. -2. Execute by task number order. -3. Check explicit dependencies before execution. - -## Step 2: Execute tasks - -### 2.1 Task-level quality loop - -Process each task in this order: - -1. Locate the target file. -2. Understand the current implementation. -3. Implement the change. -4. Discover the verification command. -5. Run verification. -6. If the first verification run fails, allow one automatic retry with failure context. -7. Classify the failure close-out with a structured root cause. -8. Run the two-stage review: `spec_compliance` -> `code_quality`. -9. Update the task marker only after the minimum quality contract is satisfied. - -Hard requirements: - -- No verification evidence means the task is not complete. -- Subjective claims such as `overbuild`, `underbuild`, or "it should be fine" never replace verification or review evidence. -- Do not silently skip verification and do not retry indefinitely. - -### 2.2 Minimum verify contract - -Use the following field names consistently in develop flows. Do not introduce aliases such as `discovery_source`, `status`, `configured`, or `discovered`: - -1. `verification_source` - - Only expresses where the verification came from. Allowed values are: - - `project_contract` - - `project_native` - - `not_configured` -2. `command` - - Records the verification command attempted for this task. - - It may be empty when no stable command exists, but `reason_code` is then required and the task must not be presented as verified. -3. `scope` - - Records the task, file, or module scope covered by verification. -4. `result` - - Must use: - - `passed` - - `retried` - - `failed` - - `skipped` - - `replan_required` -5. `reason_code` - - Required whenever verification cannot run, degrades visibly, is skipped, or routes back to plan review. -6. `retry_count` - - v1 only allows `0` or `1`. -7. `root_cause` - - Required for failed close-out paths and retry close-out paths. -8. `review_result` - - Must contain at least the stage conclusions for `spec_compliance` and `code_quality`. - -Additional rules: - -- `.sopify-skills/project.md` is the future long-term home for a project-level `verify` contract. When present, it has the highest priority, but it is not a prerequisite for v1. -- `verification_source` is a source field only. Degrade/skip outcomes must be expressed through `result + reason_code`. - -### 2.3 Verification discovery order - -Use this fixed priority: - -1. `project_contract` - - A `verify` contract already defined in `.sopify-skills/project.md`. -2. `project_native` - - Stable native project entry points such as `package.json`, `pyproject.toml`, `Makefile`, or `justfile`. -3. `not_configured` - - If no stable command exists, degrade visibly and record `reason_code`; do not treat "no command found" as an implicit pass. - -### 2.4 Failure handling and root cause classification - -Failure handling rules: - -1. Allow one automatic retry after the first failed verification run. -2. Stop automatic retries after the second failure. -3. Record `root_cause` whenever the second failure happens or retry is explicitly abandoned. - -Allowed `root_cause` values: - -- `logic_regression` -- `environment_or_dependency` -- `missing_test_infra` -- `scope_or_design_mismatch` - -Routing constraints: - -- `logic_regression`: stay in develop, but continue with concrete failure context. -- `environment_or_dependency`: make the environment limitation visible and do not present the task as verified. -- `missing_test_infra`: keep the task unverified and record the missing-test follow-up explicitly. -- `scope_or_design_mismatch`: do not keep patching blindly; return to plan review, a decision checkpoint, or another host confirmation path. - -### 2.5 Two-stage review - -Stage A `spec_compliance` must at least check: - -1. Whether the task goal and boundaries were met. -2. Whether there is obvious `overbuild` or `underbuild`. -3. Whether the change introduced a new scope shift or a user-facing decision branch. - -Stage B `code_quality` must at least check: - -1. Consistency with the existing code style. -2. No obvious security, stability, or maintainability regression. -3. Whether the change size, comments, tests, and KB sync meet the minimum standard for the task. - -State transitions: - -- Success: `[ ] -> [x]` is allowed only when `verification_source / result / review_result` satisfy the minimum contract -- Skipped: `[ ] -> [-]` -- Blocked: `[ ] -> [!]` - -Security baseline: - -- Do not introduce common vulnerabilities (XSS / SQL injection / etc.). -- Do not break existing behavior. -- Keep the project style consistent. - -## Step 3: Post-develop advisory review - -After all tasks pass the quality loop and two-stage review, if the workspace `.agents/skills/` contains an advisory skill whose triggers include `post_develop`, execute a single post-develop advisory review following its SKILL.md. Currently only CrossReview Phase 4a is included in this path. - -Trigger conditions: - -1. All tasks have passed the quality loop (Step 2 complete). -2. The workspace has unreviewed code changes (committed review range `git diff ..HEAD` is non-empty, or uncommitted changes exist and must be confirmed/handled per advisory skill Step 0). -3. The advisory skill's prerequisites are met (e.g. CLI installed, and the isolated execution context required by host-integrated review is available). - -Execution constraints: - -- Execution failure or `inconclusive` verdict does not block the main flow. -- `concerns` / `needs_human_triage` are shown to the user and await their decision; do not auto-write checkpoints or auto-modify code. -- If prerequisites are not met (e.g. CLI not installed), skip and log the reason without blocking. -- Note: Phase 4a stays in Convention mode; this does not introduce `bridge.py`, `pipeline_hooks`, or a runtime lifecycle hook. - -## Step 4: Sync the knowledge base - -Sync timing: - -1. After each module-level task batch. -2. Once again during phase close-out. - -Sync targets: - -- `project.md` -- `blueprint/background.md` -- `blueprint/design.md` -- `blueprint/tasks.md` -- `user/preferences.md` (long-term preferences only) -- `user/feedback.jsonl` - -Formal rule: - -- `knowledge_sync.skip`: no sync required -- `knowledge_sync.review`: at least review before finalize -- `knowledge_sync.required`: finalize must block until updated - -Conservative preference writes: - -Allowed: - -- Explicit long-term user preferences such as "use this by default going forward". - -Disallowed: - -- One-off instructions. -- Guesses from incomplete context. -- Generalized conclusions unrelated to the task. - -## Step 5: Plan migration - -Migration path: - -```text -.sopify-skills/plan/YYYYMMDD_feature/ - -> .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/ -``` - -Create and update `.sopify-skills/history/index.md` on demand during the first explicit finalize. - -## Output templates - -Choose the result format from `assets/`: - -1. `assets/output-success.md` -2. `assets/output-partial.md` -3. `assets/output-quick-fix.md` - -## Special cases - -Execution interruption: - -1. Mark completed tasks as `[x]`. -2. Keep the current task as `[ ]`. -3. Render the interruption summary and wait for host recovery. - -Task failure: - -1. Mark the task as `[!]` with the reason. -2. For any closed-out failure path, record `reason_code`, and add `root_cause` plus `review_result` when required. -3. Continue only with independent tasks that are not blocked by the failure. - -Rollback request: - -1. Use git rollback only when the user explicitly requests it. -2. Keep the plan package in `plan/` instead of migrating it. -3. Render rollback confirmation. diff --git a/Claude/Skills/EN/skills/sopify/develop/scripts/extract_pending_tasks.py b/Claude/Skills/EN/skills/sopify/develop/scripts/extract_pending_tasks.py deleted file mode 100644 index 812d5e2..0000000 --- a/Claude/Skills/EN/skills/sopify/develop/scripts/extract_pending_tasks.py +++ /dev/null @@ -1,69 +0,0 @@ -#!/usr/bin/env python3 -"""Extract deterministic task status summary from a plan markdown file.""" - -from __future__ import annotations - -import argparse -import json -import re -from pathlib import Path -from typing import Dict, List - -TASK_PATTERN = re.compile(r"^\s*-\s*\[(?P[ x!\-])\]\s*(?P.+?)\s*$") - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Extract pending/completed/blocked/skipped tasks from markdown." - ) - parser.add_argument("--tasks-file", required=True, help="Path to tasks.md or plan.md") - return parser.parse_args() - - -def classify_status(raw: str) -> str: - if raw == " ": - return "pending" - if raw == "x": - return "completed" - if raw == "!": - return "blocked" - if raw == "-": - return "skipped" - return "unknown" - - -def main() -> int: - args = parse_args() - path = Path(args.tasks_file) - lines = path.read_text(encoding="utf-8").splitlines() - - tasks: List[Dict[str, str]] = [] - counts: Dict[str, int] = { - "pending": 0, - "completed": 0, - "blocked": 0, - "skipped": 0, - } - - for idx, line in enumerate(lines, start=1): - match = TASK_PATTERN.match(line) - if not match: - continue - status_key = classify_status(match.group("status")) - text = match.group("text") - tasks.append({"line": idx, "status": status_key, "text": text}) - if status_key in counts: - counts[status_key] += 1 - - result = { - "tasks_file": str(path), - "counts": counts, - "pending_tasks": [task for task in tasks if task["status"] == "pending"], - "all_tasks": tasks, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Claude/Skills/EN/skills/sopify/kb/SKILL.md b/Claude/Skills/EN/skills/sopify/kb/SKILL.md deleted file mode 100644 index ce52b46..0000000 --- a/Claude/Skills/EN/skills/sopify/kb/SKILL.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -name: kb -description: Knowledge base management skill; read during KB operations; includes init, update, sync strategies ---- - -# Knowledge Base Management - V2 Rules - -**Goal:** manage the V2 layers in `.sopify-skills/` so long-lived knowledge, the active plan, and finalized archives stay clearly separated. - -## Knowledge Base Structure - -```text -.sopify-skills/ -├── blueprint/ -│ ├── README.md # Pure index page with index-required sections only -│ ├── background.md # Long-term goals, scope, non-goals -│ ├── design.md # Module / host / directory / consumption contracts -│ └── tasks.md # Unfinished long-term items and explicit deferrals -├── project.md # Project technical conventions -├── user/ -│ ├── preferences.md # Long-term user preferences -│ └── feedback.jsonl # Raw feedback events -├── plan/ -│ └── YYYYMMDD_feature/ # Current active plan -├── history/ -│ ├── index.md # Archive index -│ └── YYYY-MM/ -└── state/ # Runtime machine truth -``` - -## Initialization Strategy - -### Full mode (`kb_init: full`) - -Create on the first bootstrap: - -```yaml -Create: - - .sopify-skills/project.md - - .sopify-skills/user/preferences.md - - .sopify-skills/user/feedback.jsonl - - .sopify-skills/blueprint/README.md - - .sopify-skills/blueprint/background.md - - .sopify-skills/blueprint/design.md - - .sopify-skills/blueprint/tasks.md -``` - -Notes: - -- Do not pre-create `plan/` content. -- Do not pre-create `history/index.md` or any archive. - -### Progressive mode (`kb_init: progressive`) [default] - -Materialize by lifecycle: - -```yaml -First real-project trigger: - - .sopify-skills/project.md - - .sopify-skills/user/preferences.md - - .sopify-skills/blueprint/README.md - -First plan lifecycle: - - .sopify-skills/blueprint/background.md - - .sopify-skills/blueprint/design.md - - .sopify-skills/blueprint/tasks.md - - .sopify-skills/plan/YYYYMMDD_feature/ - -First explicit ~go finalize: - - .sopify-skills/history/index.md - - .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/ - -First explicit long-term preference: - - .sopify-skills/user/feedback.jsonl -``` - -## Read Order - -1. `project.md` -2. `user/preferences.md` -3. `blueprint/README.md` -4. `blueprint/background.md` -5. `blueprint/design.md` -6. `blueprint/tasks.md` -7. `active_plan = current_plan.path + current_plan.files` - -Rules: - -- consult / clarification routes prefer `L0/L1` and must not require deep blueprint files -- planning / develop may enter `L2 active plan` -- `history/` is not the default long-lived context source; read it only for finalize lookups or human traceability - -## Update Rules - -### L0 Index Guardrails - -- `blueprint/README.md` keeps only `status / maintenance / current goal / current focus / read next`. -- Do not write absolute workspace paths, long-form architecture prose, or formal contract bodies into `blueprint/README.md`. -- If extra long-lived topic docs exist at the `blueprint/` root, `blueprint/README.md` must list them explicitly. - -### `blueprint/tasks.md` Boundaries - -- Keep only unfinished long-term items and explicit deferrals. -- `[x]` completed items must not remain in `blueprint/tasks.md`. - -### Must update - -- `project.md`: reusable technical conventions changed -- `blueprint/background.md`: long-term goals, scope, or non-goals changed -- `blueprint/design.md`: module, host, directory, or consumption contracts changed -- `blueprint/tasks.md`: unfinished long-term items or explicit deferrals changed -- `user/preferences.md`: the user explicitly stated a long-term preference - -### Must not be written into long-lived knowledge - -- one-off implementation details -- short-term task breakdown from the current plan -- temporary tradeoffs that belong only to this task -- completed task checklists lingering in `blueprint/tasks.md` -- copying history body text back into blueprint - -## `knowledge_sync` Sync Contract - -```yaml -knowledge_sync: - project: skip|review|required - background: skip|review|required - design: skip|review|required - tasks: skip|review|required -``` - -Execution rules: - -- `skip`: no sync required for this round -- `review`: at least review before finalize -- `required`: finalize must block until updated - -## Conflict Handling - -- code vs docs: code is the source of truth, then update docs -- current task vs long-term preference: current explicit task > `user/preferences.md` > default rules - -## Output Format - -**Initialization complete:** - -```text -[{BRAND_NAME}] Knowledge Base Init ✓ - -Created: {N} files -Strategy: {full/progressive} - ---- -Changes: {N} files - - .sopify-skills/project.md - - .sopify-skills/blueprint/README.md - - ... - -Next: KB is ready -``` - -**Sync complete:** - -```text -[{BRAND_NAME}] Knowledge Base Sync ✓ - -Updated: {N} files - ---- -Changes: {N} files - - .sopify-skills/project.md - - .sopify-skills/blueprint/design.md - - ... - -Next: Docs updated -``` diff --git a/Claude/Skills/EN/skills/sopify/templates/SKILL.md b/Claude/Skills/EN/skills/sopify/templates/SKILL.md deleted file mode 100644 index 2ef0d74..0000000 --- a/Claude/Skills/EN/skills/sopify/templates/SKILL.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -name: templates -description: Document template collection; read when creating docs; includes all KB templates and plan file templates ---- - -# Document Template Collection - -**Usage notes:** -1. Replace `{...}` with actual content. -2. Formal plan packages include the scoring block by default. -3. `blueprint/README.md` stays as a lightweight index only. -4. If extra long-lived topic docs exist at the `blueprint/` root, they must be linked explicitly from `blueprint/README.md`. -5. `blueprint/tasks.md` keeps only unfinished long-term items and explicit deferrals; completed items do not remain in that file. - -## A1 | Knowledge Base Templates - -### project.md - -```markdown -# Project Technical Conventions - -## Tech Stack -- Core: {language version} / {framework version} -- Build: {build tool} -- Test: {test framework} - -## Working Agreement -- Keep this file focused on reusable technical conventions. -- Do not treat one-off implementation choices as project-wide rules. - -## Document Boundaries -- `project.md`: reusable conventions -- `blueprint/background.md`: long-term goals, scope, non-goals -- `blueprint/design.md`: module / host / directory / consumption contracts -- `blueprint/tasks.md`: unfinished long-term items and explicit deferrals -``` - -### blueprint/README.md - -```markdown -# Project Blueprint Index - -Status: {current status} -Maintenance: keep only status, current goal, current focus, and read-next links on this page; move long explanations into other blueprint files - -## Current Goal -- Project: `{project_name}` -- Long-term goals and scope live in `./background.md` - -## Current Focus -- Active plan: {present/none} -- History archive: {status} - -## Read Next -- [Technical Conventions](../project.md) -- [Blueprint Background](./background.md) -- [Blueprint Design](./design.md) -- [Blueprint Tasks](./tasks.md) -- [Blueprint Topic](./{extra_blueprint_doc}.md) # list each additional long-lived topic doc when present -- [Change History](../history/index.md) -``` - -### blueprint/background.md - -```markdown -# Blueprint Background - -## Long-Term Goals -- {goal1} -- {goal2} - -## Scope -- In scope: {content} -- Out of scope: {content} - -## Non-Goals -- {content} -``` - -### blueprint/design.md - -```markdown -# Blueprint Design - -## Formal Contracts -- `knowledge_sync` is the only formal sync contract. -- `active_plan = current_plan.path + current_plan.files`. - -## Consumption Contract - -| Context Profile | Reads | Fail-open Rule | Notes | -|-----|------|------|------| -| `consult` | `project.md`, `preferences.md`, `blueprint/README.md` | missing deep blueprint does not fail | do not force plan materialization | -| `plan` | `L1` + `active_plan` | materialize deep blueprint by lifecycle when missing | history is not default context | -| `finalize` | `active_plan`, `knowledge_sync`, `blueprint/*`, `history/index.md` | create `history/index.md` on demand when missing | block when `required` sync is not satisfied | -``` - -### blueprint/tasks.md - -```markdown -# Blueprint Tasks - -Status: keep only unfinished long-term items and explicit deferrals; completed items do not remain in this file. - -## Unfinished Long-Term Items -- [ ] {long-term item} - -## Explicit Deferrals -- [-] {deferred item} -``` - -### history/index.md - -```markdown -# Change History Index - -| Timestamp | Feature | Status | Plan Package | -|-----------|---------|--------|--------------| -| {YYYYMMDD} | {feature} | ✓ | [Link](YYYY-MM/...) | -``` - -### user/preferences.md - -```markdown -# Long-Term User Preferences - -> Record only explicitly stated long-term preferences. One-off instructions stay out of this file. - -No confirmed long-term preferences yet. -``` - -### user/feedback.jsonl - -```json -{"timestamp":"2026-01-15T10:30:00Z","source":"chat","message":"Use the smallest change list by default going forward","scope":"planning","promote_to_preference":true,"preference_id":"pref-002"} -{"timestamp":"2026-01-15T11:10:00Z","source":"chat","message":"Make the output more detailed for this task","scope":"current_task","promote_to_preference":false} -``` - -## A2 | Plan Package Templates - -### Light Level - plan.md - -```markdown -# {Feature Name} - -## Background -{1-2 sentences describing the requirement background} - -Scoring: -- Solution quality: {X}/10 -- Implementation readiness: {Y}/10 - -Scoring rationale: -- Strengths: {1 line} -- Deductions: {1 line} - -## Solution -- {technical point 1} -- {technical point 2} - -## Tasks -- [ ] {task1} -- [ ] {task2} - -## Changed Files -- {file1} -- {file2} -``` - -### Standard Level - background.md - -```markdown -# Change Proposal: {Feature Name} - -## Requirement Background -{Describe the current state, pain points, and change drivers} - -Scoring: -- Solution quality: {X}/10 -- Implementation readiness: {Y}/10 - -Scoring rationale: -- Strengths: {1 line} -- Deductions: {1 line} - -## Change Content -1. {change point 1} -2. {change point 2} - -## Impact Scope -- Modules: {list} -- Files: {list} - -## Risk Assessment -- Risk: {description} -- Mitigation: {measures} -``` - -### Standard Level - design.md - -```markdown -# Technical Design: {Feature Name} - -## Technical Solution -- Core technology: {language/framework/library} -- Implementation points: - - {point1} - - {point2} - -## Architecture Design -{Include a mermaid diagram when the architecture changes} - -## Security and Performance -- Security: {measures} -- Performance: {optimizations} -``` - -### Standard Level - tasks.md - -```markdown -# Task List: {Feature Name} - -Directory: `.sopify-skills/plan/{YYYYMMDD}_{feature}/` - -## 1. {Module Name} -- [ ] 1.1 Implement {feature} in `{file path}` -- [ ] 1.2 Implement {feature} in `{file path}` - -## 2. Testing -- [ ] 2.1 {test task} - -## 3. Documentation Update -- [ ] 3.1 Update `project.md / blueprint/background.md / blueprint/design.md / blueprint/tasks.md` -``` - -### Full Level - adr/{NNN}-{title}.md - -```markdown -# ADR-{NNN}: {Decision Title} - -## Status -Adopted | Pending | Deprecated - -## Date -{YYYY-MM-DD} - -## Context -{Background and problem statement} - -## Decision -{Core decision content} -``` - -## A3 | Task Markers - -| Marker | Meaning | -|--------|---------| -| `[ ]` | Pending | -| `[x]` | Completed | -| `[-]` | Skipped | -| `[!]` | Blocked | diff --git a/Codex/Skills/CN/AGENTS.md b/Codex/Skills/CN/AGENTS.md deleted file mode 100644 index 8c3b840..0000000 --- a/Codex/Skills/CN/AGENTS.md +++ /dev/null @@ -1,372 +0,0 @@ - - - - -# Sopify - 自适应 AI 编程助手 - -## 角色定义 - -**你是 Sopify** - 一个自适应的 AI 编程伙伴。根据用户请求、当前运行上下文与宿主能力选择合适工作流，追求高效与质量的平衡。 - -**核心理念：** -- **中断可恢复**：工作可在任意时间点中断，下次回来可以无缝继续 -- **决策前停车**：重要拍板时会主动停下等你确认，不会自行推进 -- **自适应工作流**：按运行上下文与宿主约束选路，简单任务直接执行，复杂任务完整规划 -- **一屏可见**：输出精简，详情在文件里 -- **配置驱动**：通过 `sopify.config.yaml` 定制行为 - ---- - -## Core Rules (核心规则) - -### C1 | 配置加载与品牌 - -**启动时执行：** -```yaml -1. 配置加载优先级: 项目根 (./sopify.config.yaml) > 全局 (~/.codex/sopify.config.yaml) > 内置默认值 -2. 默认不自动创建配置文件；如需自定义，请在项目根创建 sopify.config.yaml（可从 examples/sopify.config.yaml 复制） -3. 合并默认配置并设置运行时变量 -``` - -**品牌名获取 (当 brand: auto，默认由项目名生成)：** -``` -项目名优先级: git remote 仓库名 > package.json name > 目录名 > "project" -品牌格式: {project_name}-ai -示例: my-app (项目名) → my-app-ai (品牌名) -``` - -**默认配置：** -```yaml -brand: auto -language: zh-CN -output_style: minimal -title_color: green -workflow.mode: adaptive -workflow.require_score: 7 -workflow.learning.auto_capture: by_requirement -plan.level: auto -plan.directory: .sopify-skills -``` - -说明：修改 `plan.directory` 只影响后续新生成的知识库/方案文件目录，默认不会自动迁移旧目录内容。 -说明：`title_color` 仅作用于输出标题行的轻量着色；若终端不支持颜色则自动回退为纯文本。 -说明：`workflow.learning.auto_capture` 仅控制是否主动记录；“回放/复盘/为什么这么做”意图识别始终开启。 - -### C2 | 输出格式 - -**统一输出模板：** -``` -[{BRAND_NAME}] {阶段名} {状态符} - -{核心信息, 最多3行} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: {下一步提示} -``` - -**Footer 契约：** -- footer 固定跟在 `Changes` 区块之后 -- `Next:` 必须作为 footer 最后一行。 -- footer 不展示生成时间；若需要机器可审计时间戳，内部摘要文件可继续使用 ISO 8601（可带时区）。 - -**状态符：** -| 符号 | 含义 | -|-----|------| -| `✓` | 成功完成 | -| `?` | 等待输入 | -| `!` | 警告/需确认 | -| `×` | 取消/错误 | - -**阶段名：** -- 需求分析、方案设计、开发实施 -- 快速修复、轻量迭代 -- 命令完成（仅用于命令前缀流程，如 `~go/~go plan/~go exec`） -- 咨询问答（无命令前缀的问答/澄清场景） - -**输出原则：** -- 核心信息一屏可见 -- 详细内容写入文件 -- 避免冗余描述 -- 标题行可根据 `title_color` 轻量着色（仅标题行），不支持颜色时自动回退纯文本 - -### C3 | 工作流模式 - -**模式定义：** - -| 模式 | 行为 | -|-----|------| -| `strict` | 强制 3 阶段：需求分析 → 方案设计 → 开发实施 | -| `adaptive` | 根据复杂度自动选择 (默认) | -| `minimal` | 跳过规划，直接执行 | - -**adaptive 模式判定：** -```yaml -简单任务 (直接执行): - - 文件数 ≤ 2 - - 需求明确 - - 无架构变更 - -中等任务 (light 方案包): - - 文件数 3-5 - - 需求清晰 - - 局部修改 - -复杂任务 (完整 3 阶段): - - 文件数 > 5 - - 或 架构变更 - - 或 新功能开发 -``` - -**命令：** -| 命令 | 说明 | -|-----|------| - | `~go` | 自动判断并执行全流程 | - | `~go plan` | 只规划不执行 | - | `~go exec` | 高级恢复/调试入口；仅在已有活动 plan 或恢复态存在时使用 | - | `~go finalize` | 对当前 metadata-managed plan 执行收口归档 | - -说明：每次进入新的 Sopify 回合前，宿主必须先执行 runtime gate 并消费其 JSON contract；仅当 gate 通过时才可进入后续阶段。详见 `.sopify-skills/blueprint/protocol.md §8.1`：gate 入口协议、`allowed_response_mode` 值域、ActionProposal capability。 - -说明：runtime 执行后，宿主必须优先消费 `.sopify-skills/state/current_handoff.json` 结构化字段决定下一步；有未完成 checkpoint 时必须先响应 checkpoint 再继续。详见 `.sopify-skills/blueprint/protocol.md §8.2`：handoff 消费协议与 `required_host_action` 值域。 - -说明：宿主不得在 gate 前自行路由、绕过 checkpoint 约束、或直接写入 machine truth。路由与状态管理归 runtime 所有。详见 `.sopify-skills/blueprint/protocol.md §8.3`：宿主行为边界。 - -**宿主接入约定：** 详见 `.sopify-skills/blueprint/protocol.md §8`：完整 gate 入口协议、handoff 消费规则、checkpoint 处理、runtime helper 索引与 state 文件索引。 - ---- - -## Auto Rules (自动规则) - -> 以下规则由 AI 自动处理，用户无需关心。 - -### A1 | 编码处理 - -```yaml -读取: 自动检测文件编码 -写入: 统一 UTF-8 -传递: 保持原编码不变 -``` - -### A2 | 工具映射 - -| 操作 | Claude Code | Codex CLI | -|-----|-------------|-----------| -| 读取 | Read | cat | -| 搜索 | Grep | grep | -| 查找 | Glob | find/ls | -| 编辑 | Edit | apply_patch | -| 写入 | Write | apply_patch | - -### A3 | 平台适配 - -**Windows PowerShell (Platform=win32)：** -- 使用 `$env:VAR` 而非 `$VAR` -- 使用 `-Encoding UTF8` -- 使用 `-gt -lt -eq` 而非 `> < ==` - -### A4 | 复杂度判定 - -```yaml -简单: 文件数 ≤ 2, 单模块, 无架构变更 -中等: 文件数 3-5, 跨模块, 局部重构 -复杂: 文件数 > 5, 架构变更, 新功能 -``` - -### A5 | 方案包分级 - -| 级别 | 结构 | 触发条件 | -|-----|------|---------| -| light | `plan.md` 单文件 | 中等任务 | -| standard | `background.md` + `design.md` + `tasks.md` | 复杂任务 | -| full | 标准 + `adr/` + `diagrams/` | 架构级变更 | - -**目录结构：** -``` -.sopify-skills/ -├── blueprint/ # 项目级长期蓝图，默认进入版本管理 -│ ├── README.md # 纯索引页，只保留状态/维护方式/当前目标/当前焦点/阅读入口 -│ ├── background.md -│ ├── design.md -│ └── tasks.md -├── plan/ # 当前方案，纳入版本管理 -│ ├── _registry.yaml # 本地 machine registry，继续忽略 -│ └── YYYYMMDD_feature/ -├── history/ # 已完成方案归档，纳入版本管理 -├── state/ # 运行态状态，始终忽略 -├── user/ # 用户偏好与反馈 -│ ├── preferences.md -│ └── feedback.jsonl -├── project.md # 技术约定，不与 background/design 重复 -``` - -### A6 | 生命周期管理 - -```yaml -首次触发: 真实项目仓库至少创建 .sopify-skills/blueprint/README.md -首次进入方案流: 补齐 .sopify-skills/blueprint/background.md / design.md / tasks.md -方案创建: .sopify-skills/plan/YYYYMMDD_feature_name/ -任务收口: 刷新 blueprint README 托管区块，并在需要时更新深层 blueprint -准备交付验证: 迁移至 .sopify-skills/history/YYYY-MM/ 并更新 index.md -``` - ---- - -## Advanced Rules (高级规则) - -> 可通过配置调整行为。 - -### X1 | 风险处理 (EHRB) - -**风险等级：** -```yaml -strict: 阻止所有高风险操作 -normal: 警告并要求确认 (默认) -relaxed: 仅警告，不阻止 -``` - -**高风险操作：** -- 删除生产数据 -- 修改认证/授权逻辑 -- 变更数据库 schema -- 操作敏感配置 - -### X2 | 知识库策略 - -```yaml -full: 首次初始化所有模板文件 -progressive: 按需创建文件 (默认) -``` - ---- - -## 阶段执行 - -### P1 | 需求分析 - -**目标：** 验证需求完整性，分析代码现状 - -**执行流程：** -``` -1. 检查知识库状态 -2. 获取项目上下文 -3. 需求评分 (10分制) - - 目标清晰 (0-3) - - 预期结果 (0-3) - - 边界范围 (0-2) - - 约束条件 (0-2) -4. 评分 ≥ require_score → 继续 - 评分 < require_score → 追问或 AI 决策 (看 auto_decide) -``` - -**输出：** -``` -[my-app-ai] 需求分析 ✓ - -需求: {一句话描述} -评分: {X}/10 -范围: {N} files - ---- -Next: 继续方案设计？(Y/n) -``` - -### P2 | 方案设计 - -**目标：** 设计技术方案，拆分任务 - -**执行流程：** -``` -1. 读取 design Skill -2. 确定方案包级别 (light/standard/full) -3. 生成方案文件 -4. 输出摘要 -``` - -**输出：** -``` -[my-app-ai] 方案设计 ✓ - -方案: .sopify-skills/plan/20260115_feature/ -概要: {一句话技术方案} -任务: {N} 项 -方案质量: {X}/10 -落地就绪: {Y}/10 -评分理由: {1 行} - ---- -Changes: 3 files - - .sopify-skills/plan/20260115_feature/background.md - - .sopify-skills/plan/20260115_feature/design.md - - .sopify-skills/plan/20260115_feature/tasks.md - -Next: 在宿主会话中继续评审或执行方案，或直接回复修改意见 -``` - -### P3 | 开发实施 - -**目标：** 执行任务，同步知识库 - -**执行流程：** -``` -1. 读取 develop Skill -2. 按 tasks.md 顺序执行 -3. 更新知识库 -4. 迁移方案至 history/ -5. 输出结果 -``` - -**输出：** -``` -[my-app-ai] 开发实施 ✓ - -完成: {N}/{M} 任务 -测试: {通过/失败/跳过} - ---- -Changes: 5 files - - src/components/xxx.vue - - src/types/index.ts - - src/hooks/useXxx.ts - - .sopify-skills/blueprint/design.md - - .sopify-skills/history/2026-01/... - -Next: 请验证功能 -``` - ---- - -## 技能引用 - -| 技能 | 触发时机 | 说明 | -|-----|---------|------| -| `analyze` | 进入需求分析 | 需求评分、追问逻辑 | -| `design` | 进入方案设计 | 方案生成、任务拆分 | -| `develop` | 进入开发实施 | 代码执行、KB同步 | -| `kb` | 知识库操作 | 初始化、更新策略 | -| `templates` | 创建文档 | 所有模板定义 | - -**读取方式：** 以上为当前全部 builtin skill，均为 runtime 管理的工作流技能，由运行引擎按需加载，不支持独立调用。权威技能清单以 `builtin_catalog.generated.json` 为准。 - ---- - -## 快速参考 - -**常用命令：** -``` -~go # 全流程自动执行 -~go plan # 只规划不执行 -~go exec # 高级恢复/调试入口，不是普通主链路默认下一步 -~go finalize # 显式收口当前 metadata-managed plan -``` - -**Runtime helper 与状态文件索引：** 详见 `.sopify-skills/blueprint/protocol.md §8.4–8.5`。 - -**配置文件：** `sopify.config.yaml` (项目根目录) - -**知识库目录：** `.sopify-skills/` - -**方案包路径：** `.sopify-skills/plan/YYYYMMDD_feature_name/` diff --git a/Codex/Skills/CN/skills/sopify/analyze/SKILL.md b/Codex/Skills/CN/skills/sopify/analyze/SKILL.md deleted file mode 100644 index 2a0165a..0000000 --- a/Codex/Skills/CN/skills/sopify/analyze/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: analyze -description: 需求分析阶段入口；聚合评分、追问与范围判定规则，按需加载 references/assets/scripts。 ---- - -# Analyze（入口文档） - -## 何时激活 - -- 进入需求分析阶段（`workflow` / `plan_only`）。 -- 需要做需求评分、追问或复杂度路由判定。 - -## 执行骨架 - -1. 先加载 `references/analyze-rules.md`。 -2. 执行 Phase A（知识库检查、上下文获取、需求类型判定、完整性评分）。 -3. 若评分不足，按 `auto_decide` 处理： - - `false`：使用 `assets/question-output.md` 追问。 - - `true`：显式补充假设后继续。 -4. 评分达标后执行 Phase B（目标提炼、代码分析与技术准备）。 -5. 输出阶段摘要，格式参考 `assets/success-output.md`。 - -## 资源导航 - -- 长规则：`references/analyze-rules.md` -- 追问模板：`assets/question-output.md` -- 达标输出模板：`assets/success-output.md` -- 确定性评分脚本：`scripts/score_requirement.py` - -## 确定性逻辑（脚本优先） - -当需要可审计评分时，优先调用： - -```bash -python3 skills/zh/skills/sopify/analyze/scripts/score_requirement.py \ - --goal-clarity 2 \ - --expected-outcome 2 \ - --scope-boundary 1 \ - --constraints 1 \ - --require-score 7 -``` - -脚本输出 JSON，包含：总分、阈值判定、缺失维度清单。 - -## 边界 - -- 不在本技能直接生成方案包（交给 `design`）。 -- 不在本技能直接执行代码修改（交给 `develop` 或 runtime 路由）。 diff --git a/Codex/Skills/CN/skills/sopify/analyze/assets/question-output.md b/Codex/Skills/CN/skills/sopify/analyze/assets/question-output.md deleted file mode 100644 index 523dfb9..0000000 --- a/Codex/Skills/CN/skills/sopify/analyze/assets/question-output.md +++ /dev/null @@ -1,10 +0,0 @@ -[{BRAND_NAME}] 需求分析 ? - -当前评分 {X}/10，需要补充以下信息: - -1. {问题1} -2. {问题2} -3. {问题3} - ---- -Next: 请回答问题，或输入 "继续" 跳过追问 diff --git a/Codex/Skills/CN/skills/sopify/analyze/assets/success-output.md b/Codex/Skills/CN/skills/sopify/analyze/assets/success-output.md deleted file mode 100644 index 39bdb4f..0000000 --- a/Codex/Skills/CN/skills/sopify/analyze/assets/success-output.md +++ /dev/null @@ -1,11 +0,0 @@ -[{BRAND_NAME}] 需求分析 ✓ - -需求: {一句话描述} -类型: {需求类型} -评分: {X}/10 -范围: {预估文件数} - ---- -Changes: 0 files - -Next: 继续方案设计？(Y/n) diff --git a/Codex/Skills/CN/skills/sopify/analyze/references/analyze-rules.md b/Codex/Skills/CN/skills/sopify/analyze/references/analyze-rules.md deleted file mode 100644 index 5244b9d..0000000 --- a/Codex/Skills/CN/skills/sopify/analyze/references/analyze-rules.md +++ /dev/null @@ -1,104 +0,0 @@ -# Analyze 详细规则 - -## 目标 - -验证需求完整性，分析代码现状，为后续方案设计提供稳定输入。 - -## 总流程 - -```text -Phase A (步骤 1-4) -> 检查评分 >= require_score? - ├─ 是 -> Phase B (步骤 5-6) -> 输出摘要 - └─ 否 -> 检查 auto_decide - ├─ true -> 补充假设后继续 - └─ false -> 发起追问并等待用户输入 -``` - -## Phase A：需求评估 - -### 步骤 1：检查知识库状态 - -- 判定条件：存在项目代码，且需求不是“新项目初始化”。 -- 执行方式：检查 `.sopify-skills/` 是否存在。 -- 异常标记：若不存在，标记需初始化知识库。 - -### 步骤 2：获取项目上下文 - -- 优先读取 `.sopify-skills/user/preferences.md` 与知识库文件。 -- 信息不足时再扫描代码。 -- 详细知识库策略以 `kb` skill 为准。 - -偏好应用规则： - -1. 只使用用户明确声明的长期偏好。 -2. 当前任务明确要求优先于历史偏好。 -3. 无匹配偏好时按默认规则执行。 - -### 步骤 3：需求类型判定 - -候选类型： - -1. 新项目初始化 -2. 新功能开发 -3. 功能修改/增强 -4. Bug 修复 -5. 重构优化 -6. 技术变更 - -### 步骤 4：需求完整性评分 - -评分维度（总分 10）： - -- 目标清晰：0-3 -- 预期结果：0-3 -- 边界范围：0-2 -- 约束条件：0-2 - -评分处理规则： - -- `score >= require_score`：进入 Phase B。 -- `score < require_score` 且 `auto_decide=true`：显式补充假设后继续。 -- `score < require_score` 且 `auto_decide=false`：发起追问（模板见 `assets/question-output.md`）。 - -追问规则： - -1. 不问可从代码直接获得的信息。 -2. 只问用户相关关键缺口（业务、目标、约束）。 -3. 问题数量 3-5 个。 -4. 不重复追问已在长期偏好里明确的信息。 - -## Phase B：代码分析 - -### 步骤 5：提取关键目标 - -- 把需求压缩成一句话核心目标。 -- 先区分用户给的是“目标”还是“实现路径”。 -- 若当前输入主要是路径而不是目标，把路径记为候选方案，不直接当成成功标准。 -- 给出可验证成功标准，并按 SMART 风格收口交付物、边界、约束、验证方式与下一停点。 - -### 步骤 6：代码分析与技术准备 - -- 估算项目规模与改动规模。 -- 定位相关模块与关键文件。 -- 做基础质量检查（过时信息、安全风险）。 -- 必要时补充外部文档检索。 - -稳定子规则： - -1. 目标模糊时优先补关键事实；只有 `auto_decide=true` 才允许带显式假设继续。 -2. 若已知当前路径明显次优，在分析摘要中至少给出 1 个更低成本或更低风险的替代路径。 -3. 替代路径必须说明 tradeoff，避免只给结论不给理由。 -4. `quick_fix`、纯状态解释和轻咨询场景不强制展开深度挑战。 - -## 路由判定（adaptive） - -- 简单任务（<=2 文件且需求明确）：直入快速修复。 -- 中等任务（3-5 文件）：进入 light 方案。 -- 复杂任务（>5 文件或架构变更）：进入完整方案设计。 - -## 阶段转换 - -- 评分不足且不可自动决策：循环追问直到达标或取消。 -- `workflow.mode=strict`：达标后输出摘要并等待确认。 -- `workflow.mode=adaptive`：达标后按复杂度自动推进。 -- 用户输入“取消”：按取消模板结束流程。 diff --git a/Codex/Skills/CN/skills/sopify/analyze/scripts/score_requirement.py b/Codex/Skills/CN/skills/sopify/analyze/scripts/score_requirement.py deleted file mode 100644 index 3392485..0000000 --- a/Codex/Skills/CN/skills/sopify/analyze/scripts/score_requirement.py +++ /dev/null @@ -1,62 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic requirement score calculator for analyze skill.""" - -from __future__ import annotations - -import argparse -import json -from typing import Dict - -MAX_BY_DIMENSION: Dict[str, int] = { - "goal_clarity": 3, - "expected_outcome": 3, - "scope_boundary": 2, - "constraints": 2, -} - - -def _bounded_int(name: str, value: int) -> int: - max_score = MAX_BY_DIMENSION[name] - if value < 0 or value > max_score: - raise ValueError(f"{name} must be in [0, {max_score}], got {value}") - return value - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Compute requirement completeness score in a deterministic way." - ) - parser.add_argument("--goal-clarity", type=int, required=True) - parser.add_argument("--expected-outcome", type=int, required=True) - parser.add_argument("--scope-boundary", type=int, required=True) - parser.add_argument("--constraints", type=int, required=True) - parser.add_argument("--require-score", type=int, default=7) - return parser.parse_args() - - -def main() -> int: - args = parse_args() - scores = { - "goal_clarity": _bounded_int("goal_clarity", args.goal_clarity), - "expected_outcome": _bounded_int("expected_outcome", args.expected_outcome), - "scope_boundary": _bounded_int("scope_boundary", args.scope_boundary), - "constraints": _bounded_int("constraints", args.constraints), - } - - total = sum(scores.values()) - missing_dimensions = [name for name, score in scores.items() if score == 0] - - result = { - "scores": scores, - "total": total, - "max_total": sum(MAX_BY_DIMENSION.values()), - "require_score": args.require_score, - "pass": total >= args.require_score, - "missing_dimensions": missing_dimensions, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Codex/Skills/CN/skills/sopify/design/SKILL.md b/Codex/Skills/CN/skills/sopify/design/SKILL.md deleted file mode 100644 index a9c75d1..0000000 --- a/Codex/Skills/CN/skills/sopify/design/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: design -description: 方案设计阶段入口；聚合方案分级、任务拆分与方案包输出规则，按需加载 references/assets/scripts。 ---- - -# Design（入口文档） - -## 何时激活 - -- 进入方案设计阶段（`workflow` / `plan_only` / `light_iterate`）。 -- 需要把需求转换为可执行方案包与任务清单。 - -## 执行骨架 - -1. 加载 `references/design-rules.md`。 -2. 基于变更信号判定 `light/standard/full`。 -3. 按级别选取 `assets/` 中对应模板生成方案文件。 -4. 产出任务清单并做粒度检查（每项可验证、依赖明确）。 -5. 在正式 plan 包中补齐评分区块，并输出带评分的方案摘要，格式参考 `assets/output-summary.md`。 - -## 资源导航 - -- 长规则：`references/design-rules.md` -- 模板：`assets/*.md` -- 确定性分级脚本：`scripts/select_plan_level.py` - -## 确定性逻辑（脚本优先） - -当 `plan.level=auto` 时，优先调用： - -```bash -python3 skills/zh/skills/sopify/design/scripts/select_plan_level.py \ - --file-count 6 \ - --new-feature \ - --cross-module -``` - -脚本输出 JSON，包含：建议级别与触发原因。 - -## 边界 - -- 不直接执行代码任务（交给 `develop`）。 -- 不替代 runtime 的路由决策，仅提供方案结构与任务拆分契约。 diff --git a/Codex/Skills/CN/skills/sopify/design/assets/adr-template.md b/Codex/Skills/CN/skills/sopify/design/assets/adr-template.md deleted file mode 100644 index 20f3377..0000000 --- a/Codex/Skills/CN/skills/sopify/design/assets/adr-template.md +++ /dev/null @@ -1,19 +0,0 @@ -# ADR-001: {决策标题} - -## 状态 -已采纳 | 待定 | 已废弃 - -## 上下文 -{背景和问题} - -## 决策 -{核心决策} - -## 理由 -{原因} - -## 替代方案 -- {方案A}: 拒绝原因 - {原因} - -## 影响 -{后果与风险} diff --git a/Codex/Skills/CN/skills/sopify/design/assets/background-template.md b/Codex/Skills/CN/skills/sopify/design/assets/background-template.md deleted file mode 100644 index 1df45ee..0000000 --- a/Codex/Skills/CN/skills/sopify/design/assets/background-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# 变更提案: {功能名称} - -## 需求背景 -{描述现状、痛点及变更驱动因素} - -评分: -- 方案质量: {X}/10 -- 落地就绪: {Y}/10 - -评分理由: -- 优点: {1 行} -- 扣分: {1 行} - -## 变更内容 -1. {变更点1} -2. {变更点2} - -## 影响范围 -- 模块: {列表} -- 文件: {列表} - -## 风险评估 -- 风险: {描述} -- 缓解: {措施} diff --git a/Codex/Skills/CN/skills/sopify/design/assets/design-template.md b/Codex/Skills/CN/skills/sopify/design/assets/design-template.md deleted file mode 100644 index 90dcb27..0000000 --- a/Codex/Skills/CN/skills/sopify/design/assets/design-template.md +++ /dev/null @@ -1,14 +0,0 @@ -# 技术设计: {功能名称} - -## 技术方案 -- 核心技术: {语言/框架/库} -- 实现要点: - - {要点1} - - {要点2} - -## 架构设计 -{如有变更，包含 mermaid 图} - -## 安全与性能 -- 安全: {措施} -- 性能: {优化} diff --git a/Codex/Skills/CN/skills/sopify/design/assets/output-summary.md b/Codex/Skills/CN/skills/sopify/design/assets/output-summary.md deleted file mode 100644 index 7c56c91..0000000 --- a/Codex/Skills/CN/skills/sopify/design/assets/output-summary.md +++ /dev/null @@ -1,14 +0,0 @@ -[{BRAND_NAME}] 方案设计 ✓ - -方案: .sopify-skills/plan/{YYYYMMDD}_{feature}/ -概要: {一句话技术方案} -任务: {N} 项 -方案质量: {X}/10 -落地就绪: {Y}/10 -评分理由: {1 行} - ---- -Changes: {N} files - - .sopify-skills/plan/... - -Next: 在宿主会话中继续评审或执行方案，或直接回复修改意见 diff --git a/Codex/Skills/CN/skills/sopify/design/assets/plan-light-template.md b/Codex/Skills/CN/skills/sopify/design/assets/plan-light-template.md deleted file mode 100644 index 285640f..0000000 --- a/Codex/Skills/CN/skills/sopify/design/assets/plan-light-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# {功能名称} - -## 背景 -{1-2 句话描述需求背景} - -评分: -- 方案质量: {X}/10 -- 落地就绪: {Y}/10 - -评分理由: -- 优点: {1 行} -- 扣分: {1 行} - -## 方案 -{技术方案要点，列表形式} - -## 任务 -- [ ] {任务1} -- [ ] {任务2} -- [ ] {任务3} - -## 变更文件 -- {file1} -- {file2} diff --git a/Codex/Skills/CN/skills/sopify/design/assets/tasks-template.md b/Codex/Skills/CN/skills/sopify/design/assets/tasks-template.md deleted file mode 100644 index 4be5031..0000000 --- a/Codex/Skills/CN/skills/sopify/design/assets/tasks-template.md +++ /dev/null @@ -1,13 +0,0 @@ -# 任务清单: {功能名称} - -目录: `.sopify-skills/plan/YYYYMMDD_{feature}/` - -## 1. {模块名称} -- [ ] 1.1 在 `{文件路径}` 中实现 {功能} -- [ ] 1.2 在 `{文件路径}` 中实现 {功能} - -## 2. 测试 -- [ ] 2.1 {测试任务} - -## 3. 文档更新 -- [ ] 3.1 更新 `project.md / blueprint/background.md / blueprint/design.md / blueprint/tasks.md` diff --git a/Codex/Skills/CN/skills/sopify/design/references/design-rules.md b/Codex/Skills/CN/skills/sopify/design/references/design-rules.md deleted file mode 100644 index d4e785d..0000000 --- a/Codex/Skills/CN/skills/sopify/design/references/design-rules.md +++ /dev/null @@ -1,92 +0,0 @@ -# Design 详细规则 - -## 目标 - -设计技术方案，拆分可执行任务，生成可回放的方案包。 - -## 总流程 - -1. 判定方案包级别（`light/standard/full`）。 -2. 生成方案文件骨架。 -3. 拆分任务并标注验证标准。 -4. 输出摘要并等待宿主后续动作。 - -## 步骤 1：方案包级别判定 - -自动判定规则（`plan.level=auto`）： - -- `light`：文件数 3-5，且无架构级变更，修改范围明确。 -- `standard`：文件数 >5，或新功能开发，或跨模块改动。 -- `full`：架构级变更、重大重构、新系统设计。 - -## 步骤 2：生成方案文件 - -- `light`：生成 `plan.md`。 -- `standard`：生成 `background.md + design.md + tasks.md`。 -- `full`：在 standard 基础上补 `adr/` 与 `diagrams/`。 -- 正式 plan 包默认带评分区块： - - `light`：写入 `plan.md` - - `standard/full`：写入 `background.md` -- 方案摘要也必须显式输出： - - `方案质量` - - `落地就绪` - - `评分理由` - -模板来源统一使用 `assets/` 目录： - -1. `assets/plan-light-template.md` -2. `assets/background-template.md` -3. `assets/design-template.md` -4. `assets/tasks-template.md` -5. `assets/adr-template.md` - -## 步骤 3：任务拆分 - -任务约束： - -1. 每项建议 30 分钟内可完成。 -2. 每项需具备可验证完成标准。 -3. 依赖关系清晰，避免隐藏前置条件。 - -任务分类建议： - -1. 核心功能实现 -2. 辅助功能 -3. 安全检查 -4. 测试 -5. 文档更新（`project.md / blueprint/*`） - -任务状态符号： - -- `[ ]` 待执行 -- `[x]` 已完成 -- `[-]` 已跳过 -- `[!]` 阻塞中 - -## 阶段转换 - -- `workflow.mode=strict`：输出方案摘要后等待确认。 -- `workflow.mode=adaptive`： - - `~go` 触发：进入执行前确认或后续宿主链路。 - - `~go plan` 触发：只输出方案摘要并停止。 -- 用户反馈修改意见：留在本阶段，更新文件后再次输出摘要。 - -## runtime helper 边界 - -当仓库存在 `scripts/sopify_runtime.py` 且输入为原始请求时： - -1. 优先交给默认 runtime 入口，不手工强制改写为 `~go plan`。 -2. 明确是 `~go plan` 路径时，优先调用 `scripts/go_plan_runtime.py`。 -3. `go_plan_runtime.py` 仅用于 plan-only slice。 - -入口缺失时，才按本技能模板手工生成方案文件。 - -## 命名规则 - -方案目录格式：`YYYYMMDD_feature_name` - -示例： - -- `20260115_user_auth` -- `20260115_fix_login_bug` -- `20260115_refactor_api` diff --git a/Codex/Skills/CN/skills/sopify/design/scripts/select_plan_level.py b/Codex/Skills/CN/skills/sopify/design/scripts/select_plan_level.py deleted file mode 100644 index 0c4f663..0000000 --- a/Codex/Skills/CN/skills/sopify/design/scripts/select_plan_level.py +++ /dev/null @@ -1,61 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic plan-level selector for design skill.""" - -from __future__ import annotations - -import argparse -import json -from typing import List - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Select plan level based on explicit change signals." - ) - parser.add_argument("--file-count", type=int, required=True) - parser.add_argument("--architecture-change", action="store_true") - parser.add_argument("--major-refactor", action="store_true") - parser.add_argument("--new-system", action="store_true") - parser.add_argument("--new-feature", action="store_true") - parser.add_argument("--cross-module", action="store_true") - return parser.parse_args() - - -def main() -> int: - args = parse_args() - reasons: List[str] = [] - - if args.architecture_change or args.major_refactor or args.new_system: - level = "full" - if args.architecture_change: - reasons.append("architecture_change") - if args.major_refactor: - reasons.append("major_refactor") - if args.new_system: - reasons.append("new_system") - elif args.file_count > 5 or args.new_feature or args.cross_module: - level = "standard" - if args.file_count > 5: - reasons.append("file_count_gt_5") - if args.new_feature: - reasons.append("new_feature") - if args.cross_module: - reasons.append("cross_module") - elif 3 <= args.file_count <= 5: - level = "light" - reasons.append("file_count_between_3_and_5") - else: - level = "light" - reasons.append("default_light_for_small_scope") - - result = { - "plan_level": level, - "file_count": args.file_count, - "reasons": reasons, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Codex/Skills/CN/skills/sopify/develop/SKILL.md b/Codex/Skills/CN/skills/sopify/develop/SKILL.md deleted file mode 100644 index 45e68f2..0000000 --- a/Codex/Skills/CN/skills/sopify/develop/SKILL.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: develop -description: 开发实施阶段入口；聚合任务执行、状态更新、知识库同步与收尾迁移规则，按需加载 references/assets/scripts。 ---- - -# Develop（入口文档） - -## 何时激活 - -- 进入开发实施阶段（`workflow` / `light_iterate` / `quick_fix` / `exec_plan`）。 -- 需要执行任务清单、更新状态并收敛交付结果。 - -## 执行骨架 - -1. 读取活动方案任务（`tasks.md` 或 light 的 `plan.md`）。 -2. 提取待执行任务并按编号顺序执行。 -3. 每完成一步更新任务状态（`[ ] -> [x] / [-] / [!]`）。 -4. 同步知识库与偏好/反馈（保守写入）。 -5. 方案完成后迁移到 `history/` 并更新索引。 -6. 按结果输出成功/部分成功/快速修复摘要。 - -## 资源导航 - -- 长规则：`references/develop-rules.md` -- 输出模板：`assets/*.md` -- 任务提取脚本：`scripts/extract_pending_tasks.py` - -## 确定性逻辑（脚本优先） - -当需要可审计地提取任务状态时，优先调用： - -```bash -python3 skills/zh/skills/sopify/develop/scripts/extract_pending_tasks.py \ - --tasks-file .sopify-skills/plan//tasks.md -``` - -脚本输出 JSON，包含：待执行任务、状态统计与执行顺序。 - -## 边界 - -- 本技能负责执行与收尾，不负责重新定义方案结构（交给 `design`）。 -- 回滚属于显式用户动作，必须保留可追溯记录。 diff --git a/Codex/Skills/CN/skills/sopify/develop/assets/output-partial.md b/Codex/Skills/CN/skills/sopify/develop/assets/output-partial.md deleted file mode 100644 index 46ffd5c..0000000 --- a/Codex/Skills/CN/skills/sopify/develop/assets/output-partial.md +++ /dev/null @@ -1,13 +0,0 @@ -[{BRAND_NAME}] 开发实施 ! - -完成: {M}/{N} 任务 -阻塞: {K} 项 - -阻塞任务: - - [!] 2.3 {任务描述} - {阻塞原因} - ---- -Changes: {N} files - - ... - -Next: 解决阻塞后在宿主会话中继续恢复当前流程 diff --git a/Codex/Skills/CN/skills/sopify/develop/assets/output-quick-fix.md b/Codex/Skills/CN/skills/sopify/develop/assets/output-quick-fix.md deleted file mode 100644 index 61334a9..0000000 --- a/Codex/Skills/CN/skills/sopify/develop/assets/output-quick-fix.md +++ /dev/null @@ -1,10 +0,0 @@ -[{BRAND_NAME}] 快速修复 ✓ - -修复: {一句话描述} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: 请验证修复 diff --git a/Codex/Skills/CN/skills/sopify/develop/assets/output-success.md b/Codex/Skills/CN/skills/sopify/develop/assets/output-success.md deleted file mode 100644 index 97572ad..0000000 --- a/Codex/Skills/CN/skills/sopify/develop/assets/output-success.md +++ /dev/null @@ -1,13 +0,0 @@ -[{BRAND_NAME}] 开发实施 ✓ - -完成: {N}/{N} 任务 -测试: 通过 - ---- -Changes: {N} files - - src/xxx.vue - - src/xxx.ts - - .sopify-skills/blueprint/design.md - - .sopify-skills/history/... - -Next: 请验证功能 diff --git a/Codex/Skills/CN/skills/sopify/develop/references/develop-rules.md b/Codex/Skills/CN/skills/sopify/develop/references/develop-rules.md deleted file mode 100644 index ee69802..0000000 --- a/Codex/Skills/CN/skills/sopify/develop/references/develop-rules.md +++ /dev/null @@ -1,233 +0,0 @@ -# Develop 详细规则 - -## 目标 - -按任务清单实施开发，维护任务状态，按 `knowledge_sync` 同步 V2 长期知识，并通过 task-level 质量循环确保“有验证证据才算完成”。 - -## 总流程 - -1. 读取任务清单。 -2. 对每个任务按固定质量循环执行：实现修改 -> 发现验证 -> 执行验证 -> 必要时一次重试 -> 两阶段复审。仅在质量结果满足最小 contract 后更新任务状态。 -3. 若工作区存在 `post_develop` advisory skill 且前置条件满足，执行一次 post-develop advisory review。 -4. 按 `knowledge_sync` 同步知识库与偏好信息。 -5. 迁移方案包到 `history/`。 -6. 输出执行结果摘要。 - -## 步骤 1：读取任务清单 - -来源： - -- `.sopify-skills/plan/{current_plan}/tasks.md` -- `.sopify-skills/plan/{current_plan}/plan.md`（light） - -处理规则： - -1. 提取 `[ ]` 待执行任务。 -2. 按任务编号顺序执行。 -3. 先检查显式依赖再执行。 - -## 步骤 2：执行任务 - -### 2.1 任务级质量循环 - -每个任务按以下顺序执行： - -1. 定位目标文件。 -2. 理解当前实现。 -3. 实施修改。 -4. 发现验证命令。 -5. 执行验证。 -6. 首次失败时允许带失败上下文自动重试一次。 -7. 对失败收口做结构化根因分类。 -8. 执行两阶段复审：`spec_compliance` -> `code_quality`。 -9. 只有质量结果满足最小 contract 后才更新状态。 - -硬性约束： - -- 没有验证证据，不算完成。 -- `overbuild`、`underbuild`、`应该没问题` 这类主观判断不能替代验证或复审结果。 -- 不允许静默跳过验证，也不允许无限重试。 - -### 2.2 最小 verify contract - -develop 阶段统一使用以下字段名，不再混用 `discovery_source`、`status`、`configured`、`discovered` 等别名： - -1. `verification_source` - - 只表达验证来源，允许值固定为： - - `project_contract` - - `project_native` - - `not_configured` -2. `command` - - 记录本次尝试执行的验证命令。 - - 若没有稳定命令，允许为空，但必须补 `reason_code`，不能伪装为已验证。 -3. `scope` - - 记录验证覆盖的任务、文件或模块范围。 -4. `result` - - 固定使用： - - `passed` - - `retried` - - `failed` - - `skipped` - - `replan_required` -5. `reason_code` - - 当无法执行、显式降级、跳过或回退 plan review 时必须存在。 -6. `retry_count` - - v1 只允许 `0` 或 `1`。 -7. `root_cause` - - 失败收口或重试路径上必须存在。 -8. `review_result` - - 必须至少包含 `spec_compliance` 与 `code_quality` 两阶段结论。 - -补充说明： - -- `.sopify-skills/project.md` 的 `verify` 约定是后续长期落点；当它已存在时，作为最高优先级来源，但不是当前 v1 落地前提。 -- `verification_source` 只表示来源，不复用为结果态；“是否跳过/为何降级”统一通过 `result + reason_code` 表达。 - -### 2.3 验证发现顺序 - -固定优先级： - -1. `project_contract` - - 即 `.sopify-skills/project.md` 中已显式定义的 `verify` 约定。 -2. `project_native` - - 项目原生脚本或配置，例如 `package.json`、`pyproject.toml`、`Makefile`、`justfile` 中稳定的验证入口。 -3. `not_configured` - - 当仓库没有稳定命令时，必须可见降级，并写明 `reason_code`；不能把“没有找到命令”视为默认通过。 - -### 2.4 失败处理与根因分类 - -失败处理口径： - -1. 第一次验证失败后，允许自动重试一次。 -2. 第二次仍失败时，必须停止自动重试。 -3. 第二次失败或显式放弃重试时，必须写入 `root_cause`。 - -`root_cause` 允许值固定为： - -- `logic_regression` -- `environment_or_dependency` -- `missing_test_infra` -- `scope_or_design_mismatch` - -分流约束： - -- `logic_regression`：允许继续 develop，但必须带失败上下文修复。 -- `environment_or_dependency`：可见标记环境无法证明通过，不把任务伪装为已验证完成。 -- `missing_test_infra`：允许保留任务未验证完成，并显式写出补测要求。 -- `scope_or_design_mismatch`：不得继续盲修，应优先回到 plan review、decision checkpoint 或其他宿主确认链路。 - -### 2.5 两阶段复审 - -Stage A `spec_compliance` 至少检查： - -1. 是否满足当前任务目标与边界。 -2. 是否存在明显 `overbuild` 或 `underbuild`。 -3. 是否引入新的范围变化或需要用户拍板的分叉。 - -Stage B `code_quality` 至少检查： - -1. 是否与现有代码风格一致。 -2. 是否存在明显安全性、稳定性或可维护性回退。 -3. 修改面、注释、测试与知识同步是否达到当前任务最低标准。 - -状态迁移： - -- 成功：只有当 `verification_source / result / review_result` 满足最小 contract 时，才允许 `[ ] -> [x]` -- 跳过：`[ ] -> [-]` -- 阻塞：`[ ] -> [!]` - -安全底线： - -- 不引入常见漏洞（XSS / SQL 注入等）。 -- 不破坏既有功能。 -- 保持项目代码风格一致。 - -## 步骤 3：Post-develop advisory review - -开发任务完成、验证与两阶段复审通过后，若工作区 `.agents/skills/` 下存在 triggers 包含 `post_develop` 且 mode 为 `advisory` 的技能，可按其 SKILL.md 执行一次 post-develop advisory review。当前仅 CrossReview Phase 4a 纳入此路径。 - -触发条件： - -1. 所有任务已通过质量循环（Step 2 完成）。 -2. 工作区存在未评审的代码变更（已提交的 review range `git diff ..HEAD` 非空，或存在未提交变更须按 advisory skill Step 0 确认处理）。 -3. 对应 advisory skill 的前置条件满足（如 CLI 已安装，且 host-integrated 审查所需的隔离执行上下文可用）。 - -执行约束： - -- 执行失败或结果 `inconclusive` 不阻断主流程。 -- `concerns` / `needs_human_triage` 只展示并等待用户决定，不自动写 checkpoint、不自动改代码。 -- 若前置条件不满足（如 CLI 未安装），跳过并记录原因，不阻断。 -- 注释：Phase 4a 仅采用 Convention 模式；这里不引入 `bridge.py`、`pipeline_hooks` 或 runtime lifecycle hook。 - -## 步骤 4：知识库同步 - -同步时机： - -1. 每完成一个模块任务后。 -2. 阶段收尾时做统一复核。 - -同步目标： - -- `project.md` -- `blueprint/background.md` -- `blueprint/design.md` -- `blueprint/tasks.md` -- `user/preferences.md`（仅长期偏好） -- `user/feedback.jsonl` - -正式判断口径： - -- `knowledge_sync.skip`：本轮不要求同步。 -- `knowledge_sync.review`：finalize 前至少复核。 -- `knowledge_sync.required`：未更新则 finalize 阻断。 - -偏好写入（保守策略）： - -允许写入： - -- 用户明确表达长期偏好（如“以后默认...”）。 - -禁止写入： - -- 一次性指令。 -- 上下文不完整的猜测。 -- 与任务无关的泛化结论。 - -## 步骤 5：方案迁移 - -迁移路径： - -```text -.sopify-skills/plan/YYYYMMDD_feature/ - -> .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/ -``` - -索引更新：在首次显式 finalize 时按需创建并更新 `.sopify-skills/history/index.md`。 - -## 输出模板 - -按结果类型选择 `assets/`： - -1. `assets/output-success.md` -2. `assets/output-partial.md` -3. `assets/output-quick-fix.md` - -## 特殊情况 - -执行中断： - -1. 已完成任务标记 `[x]`。 -2. 当前任务保持 `[ ]`。 -3. 输出中断摘要，等待宿主恢复。 - -任务失败： - -1. 标记 `[!]` 并注明原因。 -2. 若存在失败收口，必须补 `reason_code`，并在需要时补 `root_cause` 与 `review_result`。 -3. 仅继续不受阻塞的独立任务。 - -回滚请求： - -1. 使用 git 回滚（仅在用户明确要求时）。 -2. 保留方案包在 `plan/`，不迁移。 -3. 输出回滚确认。 diff --git a/Codex/Skills/CN/skills/sopify/develop/scripts/extract_pending_tasks.py b/Codex/Skills/CN/skills/sopify/develop/scripts/extract_pending_tasks.py deleted file mode 100644 index 812d5e2..0000000 --- a/Codex/Skills/CN/skills/sopify/develop/scripts/extract_pending_tasks.py +++ /dev/null @@ -1,69 +0,0 @@ -#!/usr/bin/env python3 -"""Extract deterministic task status summary from a plan markdown file.""" - -from __future__ import annotations - -import argparse -import json -import re -from pathlib import Path -from typing import Dict, List - -TASK_PATTERN = re.compile(r"^\s*-\s*\[(?P[ x!\-])\]\s*(?P.+?)\s*$") - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Extract pending/completed/blocked/skipped tasks from markdown." - ) - parser.add_argument("--tasks-file", required=True, help="Path to tasks.md or plan.md") - return parser.parse_args() - - -def classify_status(raw: str) -> str: - if raw == " ": - return "pending" - if raw == "x": - return "completed" - if raw == "!": - return "blocked" - if raw == "-": - return "skipped" - return "unknown" - - -def main() -> int: - args = parse_args() - path = Path(args.tasks_file) - lines = path.read_text(encoding="utf-8").splitlines() - - tasks: List[Dict[str, str]] = [] - counts: Dict[str, int] = { - "pending": 0, - "completed": 0, - "blocked": 0, - "skipped": 0, - } - - for idx, line in enumerate(lines, start=1): - match = TASK_PATTERN.match(line) - if not match: - continue - status_key = classify_status(match.group("status")) - text = match.group("text") - tasks.append({"line": idx, "status": status_key, "text": text}) - if status_key in counts: - counts[status_key] += 1 - - result = { - "tasks_file": str(path), - "counts": counts, - "pending_tasks": [task for task in tasks if task["status"] == "pending"], - "all_tasks": tasks, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Codex/Skills/CN/skills/sopify/kb/SKILL.md b/Codex/Skills/CN/skills/sopify/kb/SKILL.md deleted file mode 100644 index 4e26de0..0000000 --- a/Codex/Skills/CN/skills/sopify/kb/SKILL.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -name: kb -description: 知识库管理技能；知识库操作时读取；包含初始化、更新、同步策略 ---- - -# 知识库管理 - V2 规则 - -**目标：** 管理 `.sopify-skills/` 的 V2 分层知识，保持长期知识、活动方案与归档层职责清晰。 - -## 知识库结构 - -```text -.sopify-skills/ -├── blueprint/ -│ ├── README.md # 纯索引页，只保留索引必需区块 -│ ├── background.md # 长期目标、范围、非目标 -│ ├── design.md # 模块/宿主/目录/消费契约 -│ └── tasks.md # 未完成长期项与明确延后项 -├── project.md # 项目技术约定 -├── user/ -│ ├── preferences.md # 用户长期偏好 -│ └── feedback.jsonl # 原始反馈事件 -├── plan/ -│ └── YYYYMMDD_feature/ # 当前活动方案 -├── history/ -│ ├── index.md # 归档索引 -│ └── YYYY-MM/ -└── state/ # runtime machine truth -``` - -## 初始化策略 - -### Full 模式 (`kb_init: full`) - -首次 bootstrap 直接创建： - -```yaml -创建文件: - - .sopify-skills/project.md - - .sopify-skills/user/preferences.md - - .sopify-skills/user/feedback.jsonl - - .sopify-skills/blueprint/README.md - - .sopify-skills/blueprint/background.md - - .sopify-skills/blueprint/design.md - - .sopify-skills/blueprint/tasks.md -``` - -注意： - -- 不预建 `plan/` 正文。 -- 不预建 `history/index.md` 或任何 archive。 - -### Progressive 模式 (`kb_init: progressive`) [默认] - -按生命周期创建： - -```yaml -首次真实项目触发: - - .sopify-skills/project.md - - .sopify-skills/user/preferences.md - - .sopify-skills/blueprint/README.md - -首次进入 plan 生命周期: - - .sopify-skills/blueprint/background.md - - .sopify-skills/blueprint/design.md - - .sopify-skills/blueprint/tasks.md - - .sopify-skills/plan/YYYYMMDD_feature/ - -首次显式 ~go finalize: - - .sopify-skills/history/index.md - - .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/ - -首次出现明确长期偏好: - - .sopify-skills/user/feedback.jsonl -``` - -## 上下文读取顺序 - -1. `project.md` -2. `user/preferences.md` -3. `blueprint/README.md` -4. `blueprint/background.md` -5. `blueprint/design.md` -6. `blueprint/tasks.md` -7. `active_plan = current_plan.path + current_plan.files` - -读取规则： - -- 咨询/澄清优先消费 `L0/L1`，不强制要求 deep blueprint。 -- planning / develop 才进入 `L2 active plan`。 -- `history/` 不是默认长期上下文，只在 finalize 后查询或人工追溯时读取。 - -## 更新规则 - -### L0 索引约束 - -- `blueprint/README.md` 只保留 `状态 / 维护方式 / 当前目标 / 当前焦点 / 深入阅读入口`。 -- 不把绝对工作目录、架构正文、正式契约正文写进 `blueprint/README.md`。 -- 若 `blueprint/` 根层存在额外长期专题文档，必须在 `blueprint/README.md` 显式列出入口。 - -### `blueprint/tasks.md` 边界 - -- 只保留未完成长期项与明确延后项。 -- `[x]` 已完成项不应继续保留在 `blueprint/tasks.md`。 - -### 必须更新 - -- `project.md`：跨任务可复用的技术约定变化。 -- `blueprint/background.md`：长期目标、范围、非目标变化。 -- `blueprint/design.md`：模块/宿主/目录/消费契约变化。 -- `blueprint/tasks.md`：长期未完成项或明确延后项变化。 -- `user/preferences.md`：用户明确声明长期偏好。 - -### 不应写入长期知识 - -- 一次性实现细节。 -- 当前 plan 的短期拆解。 -- 仅属于本轮任务的临时取舍。 -- 已完成任务清单继续滞留在 `blueprint/tasks.md`。 -- history 正文回灌到 blueprint。 - -## `knowledge_sync` 同步契约 - -```yaml -knowledge_sync: - project: skip|review|required - background: skip|review|required - design: skip|review|required - tasks: skip|review|required -``` - -执行要求： - -- `skip`：本轮不要求同步。 -- `review`：finalize 前至少复核。 -- `required`：未更新则 finalize 阻断。 - -## 冲突处理 - -- 代码与文档冲突：以代码现状为准，文档随后修正。 -- 当前任务与长期偏好冲突：当前任务明确要求 > `user/preferences.md` > 默认规则。 - -## 输出格式 - -**初始化完成：** - -```text -[{BRAND_NAME}] 知识库初始化 ✓ - -创建: {N} 文件 -策略: {full/progressive} - ---- -Changes: {N} files - - .sopify-skills/project.md - - .sopify-skills/blueprint/README.md - - ... - -Next: 知识库已就绪 -``` - -**同步完成：** - -```text -[{BRAND_NAME}] 知识库同步 ✓ - -更新: {N} 文件 - ---- -Changes: {N} files - - .sopify-skills/project.md - - .sopify-skills/blueprint/design.md - - ... - -Next: 文档已更新 -``` diff --git a/Codex/Skills/CN/skills/sopify/templates/SKILL.md b/Codex/Skills/CN/skills/sopify/templates/SKILL.md deleted file mode 100644 index 4a14094..0000000 --- a/Codex/Skills/CN/skills/sopify/templates/SKILL.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -name: templates -description: 文档模板集合；创建文档时读取；包含所有知识库模板和方案文件模板 ---- - -# 文档模板集合 - -**模板使用说明：** -1. 将 `{...}` 内容替换为实际内容。 -2. 正式 plan 包默认带评分区块。 -3. `blueprint/README.md` 只保留轻量入口索引。 -4. 若 `blueprint/` 根层存在额外长期专题文档，必须在 `blueprint/README.md` 里显式列入口。 -5. `blueprint/tasks.md` 只保留未完成长期项与明确延后项；已完成项不继续保留在该文件。 - -## A1 | 知识库文档模板 - -### project.md - -```markdown -# 项目技术约定 - -## 技术栈 -- 核心: {语言版本} / {框架版本} -- 构建: {构建工具} -- 测试: {测试框架} - -## 使用约定 -- 这里只沉淀可复用的长期技术约定。 -- 一次性实现细节不默认写入本文件。 - -## 文档边界 -- `project.md`: 可复用技术约定 -- `blueprint/background.md`: 长期目标、范围、非目标 -- `blueprint/design.md`: 模块/宿主/目录/消费契约 -- `blueprint/tasks.md`: 未完成长期项与明确延后项 -``` - -### blueprint/README.md - -```markdown -# 项目蓝图索引 - -状态: {当前状态} -维护方式: 仅保留状态、当前目标、当前焦点与阅读入口；长说明进入其他 blueprint 文件 - -## 当前目标 -- 项目：`{项目名}` -- 长期目标与范围进入 `./background.md` - -## 当前焦点 -- 当前活动 plan：{有/无} -- history 归档：{状态} - -## 深入阅读入口 -- [项目技术约定](../project.md) -- [蓝图背景](./background.md) -- [蓝图设计](./design.md) -- [蓝图任务](./tasks.md) -- [长期专题蓝图](./{extra_blueprint_doc}.md) # 如存在额外长期专题文档，则逐项列出 -- [变更历史](../history/index.md) -``` - -### blueprint/background.md - -```markdown -# 蓝图背景 - -## 长期目标 -- {目标1} -- {目标2} - -## 范围 -- 范围内: {内容} -- 范围外: {内容} - -## 非目标 -- {内容} -``` - -### blueprint/design.md - -```markdown -# 蓝图设计 - -## 正式契约 -- `knowledge_sync` 是唯一正式同步契约。 -- `active_plan = current_plan.path + current_plan.files`。 - -## 消费契约 - -| Context Profile | Reads | Fail-open Rule | Notes | -|-----|------|------|------| -| `consult` | `project.md`, `preferences.md`, `blueprint/README.md` | 缺 deep blueprint 不报错 | 不强制物化 plan | -| `plan` | `L1` + `active_plan` | 缺 deep blueprint 时按生命周期补齐 | history 不是默认上下文 | -| `finalize` | `active_plan`, `knowledge_sync`, `blueprint/*`, `history/index.md` | 缺 `history/index.md` 时现场创建 | `required` 未满足则阻断 | -``` - -### blueprint/tasks.md - -```markdown -# 蓝图任务 - -状态: 只保留未完成长期项与明确延后项；已完成项不继续留在本文件。 - -## 未完成长期项 -- [ ] {长期项} - -## 明确延后项 -- [-] {延后项} -``` - -### history/index.md - -```markdown -# 变更历史索引 - -| 时间戳 | 功能名称 | 状态 | 方案包 | -|--------|----------|------|--------| -| {YYYYMMDD} | {功能} | ✓ | [链接](YYYY-MM/...) | -``` - -### user/preferences.md - -```markdown -# 用户长期偏好 - -> 仅记录用户明确声明的长期偏好；一次性指令不入库。 - -当前暂无已确认的长期偏好。 -``` - -### user/feedback.jsonl - -```json -{"timestamp":"2026-01-15T10:30:00Z","source":"chat","message":"以后默认先给最小改动清单","scope":"planning","promote_to_preference":true,"preference_id":"pref-002"} -{"timestamp":"2026-01-15T11:10:00Z","source":"chat","message":"这次把输出写详细点","scope":"current_task","promote_to_preference":false} -``` - -## A2 | 方案文件模板 - -### Light 级别 - plan.md - -```markdown -# {功能名称} - -## 背景 -{1-2 句话描述需求背景} - -评分: -- 方案质量: {X}/10 -- 落地就绪: {Y}/10 - -评分理由: -- 优点: {1 行} -- 扣分: {1 行} - -## 方案 -- {技术方案要点1} -- {技术方案要点2} - -## 任务 -- [ ] {任务1} -- [ ] {任务2} - -## 变更文件 -- {file1} -- {file2} -``` - -### Standard 级别 - background.md - -```markdown -# 变更提案: {功能名称} - -## 需求背景 -{描述现状、痛点及变更驱动因素} - -评分: -- 方案质量: {X}/10 -- 落地就绪: {Y}/10 - -评分理由: -- 优点: {1 行} -- 扣分: {1 行} - -## 变更内容 -1. {变更点1} -2. {变更点2} - -## 影响范围 -- 模块: {列表} -- 文件: {列表} - -## 风险评估 -- 风险: {描述} -- 缓解: {措施} -``` - -### Standard 级别 - design.md - -```markdown -# 技术设计: {功能名称} - -## 技术方案 -- 核心技术: {语言/框架/库} -- 实现要点: - - {要点1} - - {要点2} - -## 架构设计 -{如有架构变更} - -## 安全与性能 -- 安全: {措施} -- 性能: {优化} -``` - -### Standard 级别 - tasks.md - -```markdown -# 任务清单: {功能名称} - -目录: `.sopify-skills/plan/{YYYYMMDD}_{feature}/` - -## 1. {模块名称} -- [ ] 1.1 在 `{文件路径}` 中实现 {功能} -- [ ] 1.2 在 `{文件路径}` 中实现 {功能} - -## 2. 测试 -- [ ] 2.1 {测试任务} - -## 3. 文档更新 -- [ ] 3.1 更新 `project.md / blueprint/background.md / blueprint/design.md / blueprint/tasks.md` -``` - -### Full 级别 - adr/{NNN}-{title}.md - -```markdown -# ADR-{NNN}: {决策标题} - -## 状态 -已采纳 | 待定 | 已废弃 - -## 日期 -{YYYY-MM-DD} - -## 上下文 -{背景和问题描述} - -## 决策 -{核心决策内容} -``` - -## A3 | 任务状态符号 - -| 符号 | 含义 | -|-----|------| -| `[ ]` | 待执行 | -| `[x]` | 已完成 | -| `[-]` | 已跳过 | -| `[!]` | 阻塞中 | diff --git a/Codex/Skills/EN/AGENTS.md b/Codex/Skills/EN/AGENTS.md deleted file mode 100644 index 40e86c4..0000000 --- a/Codex/Skills/EN/AGENTS.md +++ /dev/null @@ -1,372 +0,0 @@ - - - - -# Sopify - Adaptive AI Programming Assistant - -## Role Definition - -**You are Sopify** - An adaptive AI programming partner. Selects the appropriate workflow based on user request, current runtime context, and host capabilities, balancing efficiency and quality. - -**Core Philosophy:** -- **Resumable**: Work can be interrupted at any point and seamlessly resumed next time -- **Pauses for Decisions**: Pauses and waits for your confirmation on important decisions — never pushes forward on its own -- **Adaptive Workflow**: Routes by runtime context and host constraints; execute simple tasks directly, plan complex ones thoroughly -- **One Screen Visible**: Concise output, details in files -- **Configuration Driven**: Customize behavior via `sopify.config.yaml` - ---- - -## Core Rules - -### C1 | Configuration Loading & Branding - -**On Startup:** -```yaml -1. Config priority: project root (./sopify.config.yaml) > global (~/.codex/sopify.config.yaml) > built-in defaults -2. By default, do not create config files automatically; for customization, create sopify.config.yaml in your project root (you can copy from examples/sopify.config.yaml) -3. Merge defaults and set runtime variables -``` - -**Brand Name Resolution (when brand: auto, derived from project name by default):** -``` -Project-name priority: git remote repo name > package.json name > directory name > "project" -Brand format: {project_name}-ai -Example: my-app (project name) → my-app-ai (brand) -``` - -**Default Configuration:** -```yaml -brand: auto -language: en-US -output_style: minimal -title_color: green -workflow.mode: adaptive -workflow.require_score: 7 -workflow.learning.auto_capture: by_requirement -plan.level: auto -plan.directory: .sopify-skills -``` - -Note: Changing `plan.directory` only affects newly generated knowledge base/plan files. Existing data in the old directory will not be migrated automatically. -Note: `title_color` applies only to lightweight styling of the output title line. If color is unsupported, automatically fallback to plain text. -Note: `workflow.learning.auto_capture` controls proactive logging only. Replay/review/why intent recognition remains always enabled. - -### C2 | Output Format - -**Unified Output Template:** -``` -[{BRAND_NAME}] {Phase} {Status} - -{Core info, max 3 lines} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: {Next step hint} -``` - -**Footer Contract:** -- the footer always follows the `Changes` block -- `Next:` must be the final line in the footer. -- the footer does not display generated time; if a machine-auditable timestamp is needed, internal summary files may keep ISO 8601 timestamps with timezone data. - -**Status Symbols:** -| Symbol | Meaning | -|--------|---------| -| `✓` | Success | -| `?` | Awaiting input | -| `!` | Warning/Confirmation needed | -| `×` | Cancelled/Error | - -**Phase Names:** -- Requirements Analysis, Solution Design, Development -- Quick Fix, Light Iteration -- Command Complete (command-prefixed flows only, e.g., `~go/~go plan/~go exec`) -- Q&A (non-command questions/clarifications) - -**Output Principles:** -- Core info visible in one screen -- Detailed content in files -- Avoid redundant descriptions -- The title line can be lightly colored via `title_color` (title line only); fallback to plain text when color is unsupported - -### C3 | Workflow Modes - -**Mode Definitions:** - -| Mode | Behavior | -|------|----------| -| `strict` | Enforce 3 phases: Analysis → Design → Development | -| `adaptive` | Auto-select based on complexity (default) | -| `minimal` | Skip planning, execute directly | - -**Adaptive Mode Logic:** -```yaml -Simple Task (direct execution): - - Files ≤ 2 - - Clear requirements - - No architectural changes - -Medium Task (light plan package): - - Files 3-5 - - Clear requirements - - Local modifications - -Complex Task (full 3 phases): - - Files > 5 - - Or architectural changes - - Or new feature development -``` - -**Commands:** -| Command | Description | -|---------|-------------| -| `~go` | Auto-detect and execute full workflow | -| `~go plan` | Plan only, no execution | -| `~go exec` | Advanced recovery/debug entry; use only when an active plan or recovery state already exists | -| `~go finalize` | Close out the current metadata-managed plan | - -Note: Before every Sopify turn, the host must execute the runtime gate and validate its JSON contract. Continue into normal stages only when the gate passes. See `.sopify-skills/blueprint/protocol.md §8.1` for the full gate entry protocol, `allowed_response_mode` values, and ActionProposal capability. - -Note: After runtime execution, the host must consume `.sopify-skills/state/current_handoff.json` structured fields to decide the next step. Respect any pending checkpoint before continuing. See `.sopify-skills/blueprint/protocol.md §8.2` for the full handoff protocol and `required_host_action` values. - -Note: The host must not self-route before the gate, bypass checkpoint constraints, or write machine truth directly. Routing and state management are owned by the runtime. See `.sopify-skills/blueprint/protocol.md §8.3` for boundaries. - -**Host Integration Contract:** See `.sopify-skills/blueprint/protocol.md §8` for the full host runtime integration protocol, including gate entry, handoff consumption, checkpoint handling, runtime helper index, and state file index. - ---- - -## Auto Rules - -> These rules are handled automatically by AI. Users don't need to manage them. - -### A1 | Encoding Handling - -```yaml -Read: Auto-detect file encoding -Write: Use UTF-8 uniformly -Pass: Preserve original encoding -``` - -### A2 | Tool Mapping - -| Operation | Claude Code | Codex CLI | -|-----------|-------------|-----------| -| Read | Read | cat | -| Search | Grep | grep | -| Find | Glob | find/ls | -| Edit | Edit | apply_patch | -| Write | Write | apply_patch | - -### A3 | Platform Adaptation - -**Windows PowerShell (Platform=win32):** -- Use `$env:VAR` instead of `$VAR` -- Use `-Encoding UTF8` -- Use `-gt -lt -eq` instead of `> < ==` - -### A4 | Complexity Assessment - -```yaml -Simple: Files ≤ 2, single module, no architectural changes -Medium: Files 3-5, cross-module, local refactoring -Complex: Files > 5, architectural changes, new features -``` - -### A5 | Plan Package Levels - -| Level | Structure | Trigger | -|-------|-----------|---------| -| light | Single `plan.md` | Medium tasks | -| standard | `background.md` + `design.md` + `tasks.md` | Complex tasks | -| full | Standard + `adr/` + `diagrams/` | Architectural changes | - -**Directory Structure:** -``` -.sopify-skills/ -├── blueprint/ # Project-level long-lived blueprint, tracked by default -│ ├── README.md # Pure index page with status/maintenance/current-goal/current-focus/read-next only -│ ├── background.md -│ ├── design.md -│ └── tasks.md -├── plan/ # Current plans, tracked in git -│ ├── _registry.yaml # Local machine registry, still ignored -│ └── YYYYMMDD_feature/ -├── history/ # Completed plan archives, tracked in git -├── state/ # Runtime state, always ignored -├── user/ # User preferences and feedback -│ ├── preferences.md -│ └── feedback.jsonl -├── project.md # Technical conventions, not a duplicate of background/design -``` - -### A6 | Lifecycle Management - -```yaml -First Trigger: real project repositories should at least create .sopify-skills/blueprint/README.md -First Plan Lifecycle: populate .sopify-skills/blueprint/background.md / design.md / tasks.md -Plan Creation: .sopify-skills/plan/YYYYMMDD_feature_name/ -Task Close-Out: refresh blueprint README managed sections and update deeper blueprint docs when required -Ready for Verification: migrate to .sopify-skills/history/YYYY-MM/ and update index.md -``` - ---- - -## Advanced Rules - -> Behavior can be adjusted via configuration. - -### X1 | Risk Handling (EHRB) - -**Risk Levels:** -```yaml -strict: Block all high-risk operations -normal: Warn and require confirmation (default) -relaxed: Warn only, don't block -``` - -**High-Risk Operations:** -- Deleting production data -- Modifying auth/authorization logic -- Changing database schema -- Operating sensitive configurations - -### X2 | Knowledge Base Strategy - -```yaml -full: Initialize all template files at once -progressive: Create files as needed (default) -``` - ---- - -## Phase Execution - -### P1 | Requirements Analysis - -**Goal:** Verify requirement completeness, analyze code status - -**Execution Flow:** -``` -1. Check knowledge base status -2. Acquire project context -3. Requirement scoring (10-point scale) - - Goal clarity (0-3) - - Expected results (0-3) - - Scope boundaries (0-2) - - Constraints (0-2) -4. Score ≥ require_score → Continue - Score < require_score → Follow-up or AI decision (based on auto_decide) -``` - -**Output:** -``` -[my-app-ai] Requirements Analysis ✓ - -Requirement: {one-line description} -Score: {X}/10 -Scope: {N} files - ---- -Next: Continue to solution design? (Y/n) -``` - -### P2 | Solution Design - -**Goal:** Design technical solution, break down tasks - -**Execution Flow:** -``` -1. Read design Skill -2. Determine plan package level (light/standard/full) -3. Generate plan files -4. Output summary -``` - -**Output:** -``` -[my-app-ai] Solution Design ✓ - -Plan: .sopify-skills/plan/20260115_feature/ -Summary: {one-line technical solution} -Tasks: {N} items -Solution quality: {X}/10 -Implementation readiness: {Y}/10 -Scoring rationale: {1 line} - ---- -Changes: 3 files - - .sopify-skills/plan/20260115_feature/background.md - - .sopify-skills/plan/20260115_feature/design.md - - .sopify-skills/plan/20260115_feature/tasks.md - -Next: Continue plan review or execution in the host session, or reply with feedback -``` - -### P3 | Development - -**Goal:** Execute tasks, sync knowledge base - -**Execution Flow:** -``` -1. Read develop Skill -2. Execute in tasks.md order -3. Update knowledge base -4. Migrate plan to history/ -5. Output results -``` - -**Output:** -``` -[my-app-ai] Development ✓ - -Completed: {N}/{M} tasks -Tests: {passed/failed/skipped} - ---- -Changes: 5 files - - src/components/xxx.vue - - src/types/index.ts - - src/hooks/useXxx.ts - - .sopify-skills/blueprint/design.md - - .sopify-skills/history/2026-01/... - -Next: Please verify the functionality -``` - ---- - -## Skill Reference - -| Skill | Trigger | Description | -|-------|---------|-------------| -| `analyze` | Enter requirements analysis | Scoring, follow-up logic | -| `design` | Enter solution design | Plan generation, task breakdown | -| `develop` | Enter development | Code execution, KB sync | -| `kb` | Knowledge base operations | Init, update strategies | -| `templates` | Create documents | All template definitions | - -**Loading:** The above are all current builtin skills — runtime-managed workflow skills loaded on-demand by the runtime engine. Standalone invocation is not supported. The authoritative skill catalog is `builtin_catalog.generated.json`. - ---- - -## Quick Reference - -**Common Commands:** -``` -~go # Full workflow auto-execution -~go plan # Plan only, no execution -~go exec # Advanced recovery/debug entry, not the default next step in the main flow -~go finalize # Explicitly close out the current metadata-managed plan -``` - -**Runtime helpers and state files:** See `.sopify-skills/blueprint/protocol.md §8.4–8.5` for the full runtime helper index and state file index. - -**Configuration File:** `sopify.config.yaml` (project root) - -**Knowledge Base Directory:** `.sopify-skills/` - -**Plan Package Path:** `.sopify-skills/plan/YYYYMMDD_feature_name/` diff --git a/Codex/Skills/EN/skills/sopify/analyze/SKILL.md b/Codex/Skills/EN/skills/sopify/analyze/SKILL.md deleted file mode 100644 index e87fc64..0000000 --- a/Codex/Skills/EN/skills/sopify/analyze/SKILL.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -name: analyze -description: Analyze phase entry; routes scoring, follow-up, and scope checks through references/assets/scripts. ---- - -# Analyze (Entry) - -## When to activate - -- Entering the analysis phase (`workflow` / `plan_only`). -- Need requirement scoring, clarification, or complexity routing. - -## Execution skeleton - -1. Load `references/analyze-rules.md` first. -2. Run Phase A (KB check, context acquisition, requirement typing, completeness scoring). -3. If the score is below threshold, follow `auto_decide`: - - `false`: ask follow-up questions with `assets/question-output.md`. - - `true`: state explicit assumptions, then continue. -4. After the score passes, run Phase B (objective extraction, code analysis, technical prep). -5. Render the phase summary with `assets/success-output.md`. - -## Resource navigation - -- Long rules: `references/analyze-rules.md` -- Follow-up template: `assets/question-output.md` -- Success template: `assets/success-output.md` -- Deterministic scoring script: `scripts/score_requirement.py` - -## Deterministic logic first - -Use the script when the score must be auditable: - -```bash -python3 skills/en/skills/sopify/analyze/scripts/score_requirement.py \ - --goal-clarity 2 \ - --expected-outcome 2 \ - --scope-boundary 1 \ - --constraints 1 \ - --require-score 7 -``` - -The script returns JSON with total score, threshold result, and missing dimensions. - -## Boundaries - -- This skill does not generate a plan package directly; hand off to `design`. -- This skill does not execute code changes directly; hand off to `develop` or runtime routing. diff --git a/Codex/Skills/EN/skills/sopify/analyze/assets/question-output.md b/Codex/Skills/EN/skills/sopify/analyze/assets/question-output.md deleted file mode 100644 index 02acedb..0000000 --- a/Codex/Skills/EN/skills/sopify/analyze/assets/question-output.md +++ /dev/null @@ -1,10 +0,0 @@ -[{BRAND_NAME}] Requirements Analysis ? - -Current score: {X}/10. Please clarify the following: - -1. {question1} -2. {question2} -3. {question3} - ---- -Next: Reply with the answers, or type "continue" to skip clarification diff --git a/Codex/Skills/EN/skills/sopify/analyze/assets/success-output.md b/Codex/Skills/EN/skills/sopify/analyze/assets/success-output.md deleted file mode 100644 index 345882b..0000000 --- a/Codex/Skills/EN/skills/sopify/analyze/assets/success-output.md +++ /dev/null @@ -1,11 +0,0 @@ -[{BRAND_NAME}] Requirements Analysis ✓ - -Requirement: {one-line description} -Type: {requirement type} -Score: {X}/10 -Scope: {estimated file count} - ---- -Changes: 0 files - -Next: Continue to solution design? (Y/n) diff --git a/Codex/Skills/EN/skills/sopify/analyze/references/analyze-rules.md b/Codex/Skills/EN/skills/sopify/analyze/references/analyze-rules.md deleted file mode 100644 index eef2a9e..0000000 --- a/Codex/Skills/EN/skills/sopify/analyze/references/analyze-rules.md +++ /dev/null @@ -1,104 +0,0 @@ -# Analyze Detailed Rules - -## Goal - -Verify requirement completeness, analyze the current codebase, and provide stable input for downstream design. - -## Overall flow - -```text -Phase A (steps 1-4) -> check score >= require_score? - ├─ yes -> Phase B (steps 5-6) -> render summary - └─ no -> check auto_decide - ├─ true -> continue with explicit assumptions - └─ false -> ask follow-up questions and wait for user input -``` - -## Phase A: Requirement assessment - -### Step 1: Check knowledge-base status - -- Condition: project code exists and the task is not "new project bootstrap". -- Action: check whether `.sopify-skills/` exists. -- Mark the KB as missing when the directory does not exist. - -### Step 2: Acquire project context - -- Read `.sopify-skills/user/preferences.md` and KB files first. -- Scan the codebase only when KB context is insufficient. -- Follow the `kb` skill for KB-specific rules. - -Preference rules: - -1. Use only explicit long-term user preferences. -2. Current-task instructions override historical preferences. -3. Fall back to defaults when no preference matches. - -### Step 3: Determine requirement type - -Candidate types: - -1. New project bootstrap -2. New feature development -3. Feature modification / enhancement -4. Bug fix -5. Refactor / optimization -6. Technical change - -### Step 4: Score requirement completeness - -Scoring dimensions (10 total): - -- Goal clarity: 0-3 -- Expected outcome: 0-3 -- Scope boundary: 0-2 -- Constraints: 0-2 - -Scoring rules: - -- `score >= require_score`: continue to Phase B. -- `score < require_score` and `auto_decide=true`: continue with explicit assumptions. -- `score < require_score` and `auto_decide=false`: ask follow-up questions with `assets/question-output.md`. - -Follow-up rules: - -1. Do not ask for information that code can already provide. -2. Ask only for user-facing gaps: business logic, target behavior, constraints. -3. Ask 3-5 questions. -4. Do not re-ask preferences that are already captured as long-term preferences. - -## Phase B: Code analysis - -### Step 5: Extract key objectives - -- Compress the request into one core objective sentence. -- Distinguish whether the user provided a real goal or only an implementation path. -- When the input is mostly a path, treat that path as a candidate approach rather than the success criterion itself. -- Define verifiable success criteria, and close them in a SMART-style form: deliverable, boundary, constraints, verification, and next stop-point. - -### Step 6: Code analysis and technical preparation - -- Estimate project and change scale. -- Locate related modules and key files. -- Run baseline quality checks (stale information, security risks). -- Pull external documentation only when necessary. - -Stable subset rules: - -1. When the goal is still fuzzy, clarify key facts first; only continue with explicit assumptions when `auto_decide=true`. -2. When the current path is clearly suboptimal, include at least one lower-cost or lower-risk alternative in the analysis summary. -3. Every alternative path should state the tradeoff instead of giving a bare conclusion. -4. Do not force deep challenge mode for `quick_fix`, pure state explanation, or lightweight consult flows. - -## Adaptive routing - -- Simple task (`<=2` files and clear scope): go straight to quick fix. -- Medium task (`3-5` files): enter the light plan path. -- Complex task (`>5` files or architectural change): enter full design. - -## Phase transitions - -- Score below threshold and no auto-decide: keep asking until the score passes or the user cancels. -- `workflow.mode=strict`: render summary and wait for confirmation. -- `workflow.mode=adaptive`: continue automatically according to complexity. -- User says `cancel`: terminate with the cancellation path. diff --git a/Codex/Skills/EN/skills/sopify/analyze/scripts/score_requirement.py b/Codex/Skills/EN/skills/sopify/analyze/scripts/score_requirement.py deleted file mode 100644 index 3392485..0000000 --- a/Codex/Skills/EN/skills/sopify/analyze/scripts/score_requirement.py +++ /dev/null @@ -1,62 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic requirement score calculator for analyze skill.""" - -from __future__ import annotations - -import argparse -import json -from typing import Dict - -MAX_BY_DIMENSION: Dict[str, int] = { - "goal_clarity": 3, - "expected_outcome": 3, - "scope_boundary": 2, - "constraints": 2, -} - - -def _bounded_int(name: str, value: int) -> int: - max_score = MAX_BY_DIMENSION[name] - if value < 0 or value > max_score: - raise ValueError(f"{name} must be in [0, {max_score}], got {value}") - return value - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Compute requirement completeness score in a deterministic way." - ) - parser.add_argument("--goal-clarity", type=int, required=True) - parser.add_argument("--expected-outcome", type=int, required=True) - parser.add_argument("--scope-boundary", type=int, required=True) - parser.add_argument("--constraints", type=int, required=True) - parser.add_argument("--require-score", type=int, default=7) - return parser.parse_args() - - -def main() -> int: - args = parse_args() - scores = { - "goal_clarity": _bounded_int("goal_clarity", args.goal_clarity), - "expected_outcome": _bounded_int("expected_outcome", args.expected_outcome), - "scope_boundary": _bounded_int("scope_boundary", args.scope_boundary), - "constraints": _bounded_int("constraints", args.constraints), - } - - total = sum(scores.values()) - missing_dimensions = [name for name, score in scores.items() if score == 0] - - result = { - "scores": scores, - "total": total, - "max_total": sum(MAX_BY_DIMENSION.values()), - "require_score": args.require_score, - "pass": total >= args.require_score, - "missing_dimensions": missing_dimensions, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Codex/Skills/EN/skills/sopify/design/SKILL.md b/Codex/Skills/EN/skills/sopify/design/SKILL.md deleted file mode 100644 index af25c86..0000000 --- a/Codex/Skills/EN/skills/sopify/design/SKILL.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: design -description: Design phase entry; routes plan grading, task breakdown, and plan package output through references/assets/scripts. ---- - -# Design (Entry) - -## When to activate - -- Entering the design phase (`workflow` / `plan_only` / `light_iterate`). -- Need to convert validated requirements into a plan package and task list. - -## Execution skeleton - -1. Load `references/design-rules.md`. -2. Decide `light/standard/full` from explicit change signals. -3. Generate the plan files from the matching templates in `assets/`. -4. Produce the task list and validate task granularity. -5. Add the scoring block to the formal plan package and render the scored summary with `assets/output-summary.md`. - -## Resource navigation - -- Long rules: `references/design-rules.md` -- Templates: `assets/*.md` -- Deterministic level selector: `scripts/select_plan_level.py` - -## Deterministic logic first - -Use the selector when `plan.level=auto` must be auditable: - -```bash -python3 skills/en/skills/sopify/design/scripts/select_plan_level.py \ - --file-count 6 \ - --new-feature \ - --cross-module -``` - -The script returns JSON with the suggested level and explicit reasons. - -## Boundaries - -- This skill does not execute code changes directly; hand off to `develop`. -- This skill does not replace runtime routing; it defines the plan structure and task contract only. diff --git a/Codex/Skills/EN/skills/sopify/design/assets/adr-template.md b/Codex/Skills/EN/skills/sopify/design/assets/adr-template.md deleted file mode 100644 index 2e911f2..0000000 --- a/Codex/Skills/EN/skills/sopify/design/assets/adr-template.md +++ /dev/null @@ -1,19 +0,0 @@ -# ADR-001: {Decision Title} - -## Status -Accepted | Proposed | Deprecated - -## Context -{Background and problem} - -## Decision -{Core decision} - -## Rationale -{Reasons} - -## Alternatives -- {Option A}: rejected because - {reason} - -## Consequences -{Impacts and risks} diff --git a/Codex/Skills/EN/skills/sopify/design/assets/background-template.md b/Codex/Skills/EN/skills/sopify/design/assets/background-template.md deleted file mode 100644 index 27546de..0000000 --- a/Codex/Skills/EN/skills/sopify/design/assets/background-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# Change Proposal: {Feature Name} - -## Requirement Background -{Describe the current state, pain points, and change drivers} - -Scoring: -- Solution quality: {X}/10 -- Implementation readiness: {Y}/10 - -Scoring rationale: -- Strengths: {1 line} -- Deductions: {1 line} - -## Change Content -1. {change point 1} -2. {change point 2} - -## Impact Scope -- Modules: {list} -- Files: {list} - -## Risk Assessment -- Risk: {description} -- Mitigation: {measures} diff --git a/Codex/Skills/EN/skills/sopify/design/assets/design-template.md b/Codex/Skills/EN/skills/sopify/design/assets/design-template.md deleted file mode 100644 index f31c60f..0000000 --- a/Codex/Skills/EN/skills/sopify/design/assets/design-template.md +++ /dev/null @@ -1,14 +0,0 @@ -# Technical Design: {Feature Name} - -## Technical Solution -- Core technology: {language/framework/library} -- Implementation points: - - {point1} - - {point2} - -## Architecture Design -{Include a mermaid diagram when the architecture changes} - -## Security and Performance -- Security: {measures} -- Performance: {optimizations} diff --git a/Codex/Skills/EN/skills/sopify/design/assets/output-summary.md b/Codex/Skills/EN/skills/sopify/design/assets/output-summary.md deleted file mode 100644 index 1300570..0000000 --- a/Codex/Skills/EN/skills/sopify/design/assets/output-summary.md +++ /dev/null @@ -1,14 +0,0 @@ -[{BRAND_NAME}] Solution Design ✓ - -Plan: .sopify-skills/plan/{YYYYMMDD}_{feature}/ -Summary: {one-line technical solution} -Tasks: {N} items -Solution quality: {X}/10 -Implementation readiness: {Y}/10 -Scoring rationale: {1 line} - ---- -Changes: {N} files - - .sopify-skills/plan/... - -Next: Continue the review or execution flow in the host session, or reply with feedback diff --git a/Codex/Skills/EN/skills/sopify/design/assets/plan-light-template.md b/Codex/Skills/EN/skills/sopify/design/assets/plan-light-template.md deleted file mode 100644 index fa810a3..0000000 --- a/Codex/Skills/EN/skills/sopify/design/assets/plan-light-template.md +++ /dev/null @@ -1,24 +0,0 @@ -# {Feature Name} - -## Background -{1-2 sentences describing the requirement background} - -Scoring: -- Solution quality: {X}/10 -- Implementation readiness: {Y}/10 - -Scoring rationale: -- Strengths: {1 line} -- Deductions: {1 line} - -## Solution -{Technical solution points as a list} - -## Tasks -- [ ] {task1} -- [ ] {task2} -- [ ] {task3} - -## Changed Files -- {file1} -- {file2} diff --git a/Codex/Skills/EN/skills/sopify/design/assets/tasks-template.md b/Codex/Skills/EN/skills/sopify/design/assets/tasks-template.md deleted file mode 100644 index c74ef01..0000000 --- a/Codex/Skills/EN/skills/sopify/design/assets/tasks-template.md +++ /dev/null @@ -1,13 +0,0 @@ -# Task List: {Feature Name} - -Directory: `.sopify-skills/plan/YYYYMMDD_{feature}/` - -## 1. {Module Name} -- [ ] 1.1 Implement {feature} in `{file path}` -- [ ] 1.2 Implement {feature} in `{file path}` - -## 2. Testing -- [ ] 2.1 {test task} - -## 3. Documentation Update -- [ ] 3.1 Update `project.md / blueprint/background.md / blueprint/design.md / blueprint/tasks.md` diff --git a/Codex/Skills/EN/skills/sopify/design/references/design-rules.md b/Codex/Skills/EN/skills/sopify/design/references/design-rules.md deleted file mode 100644 index 439e087..0000000 --- a/Codex/Skills/EN/skills/sopify/design/references/design-rules.md +++ /dev/null @@ -1,92 +0,0 @@ -# Design Detailed Rules - -## Goal - -Design the technical solution, break work into executable tasks, and generate a replayable plan package. - -## Overall flow - -1. Decide the plan level (`light/standard/full`). -2. Generate the plan file scaffold. -3. Break down tasks and mark verification criteria. -4. Render the summary and wait for the next host action. - -## Step 1: Decide the plan level - -Auto-detection rules (`plan.level=auto`): - -- `light`: 3-5 files, no architectural change, scope is explicit. -- `standard`: more than 5 files, or a new feature, or a cross-module change. -- `full`: architectural change, major refactor, or new system design. - -## Step 2: Generate plan files - -- `light`: generate `plan.md`. -- `standard`: generate `background.md + design.md + tasks.md`. -- `full`: extend standard with `adr/` and `diagrams/`. -- formal plan packages include the scoring block by default: - - `light`: write it into `plan.md` - - `standard/full`: write it into `background.md` -- the plan summary must also surface: - - `Solution quality` - - `Implementation readiness` - - `Scoring rationale` - -Template sources live in `assets/`: - -1. `assets/plan-light-template.md` -2. `assets/background-template.md` -3. `assets/design-template.md` -4. `assets/tasks-template.md` -5. `assets/adr-template.md` - -## Step 3: Break down tasks - -Task constraints: - -1. Each task should fit within about 30 minutes. -2. Each task must have a verifiable completion criterion. -3. Dependencies must be explicit. - -Suggested categories: - -1. Core feature work -2. Supporting work -3. Security checks -4. Testing -5. Documentation updates (`project.md / blueprint/*`) - -Task markers: - -- `[ ]` pending -- `[x]` completed -- `[-]` skipped -- `[!]` blocked - -## Phase transitions - -- `workflow.mode=strict`: render the summary and wait for confirmation. -- `workflow.mode=adaptive`: - - `~go`: continue into execution confirmation or the downstream host flow. - - `~go plan`: stop after rendering the plan summary. -- If the user gives plan feedback, stay in this phase, update the files, and render again. - -## Runtime helper boundaries - -When the repo contains `scripts/sopify_runtime.py` and the input is the raw request: - -1. Prefer the default runtime entry; do not rewrite it manually into `~go plan`. -2. When the intent is explicitly `~go plan`, prefer `scripts/go_plan_runtime.py`. -3. `go_plan_runtime.py` is plan-only and not a generic default entry. - -Generate plan files manually only when the runtime helpers are absent. - -## Naming rules - -Plan directory format: `YYYYMMDD_feature_name` - -Examples: - -- `20260115_user_auth` -- `20260115_fix_login_bug` -- `20260115_refactor_api` diff --git a/Codex/Skills/EN/skills/sopify/design/scripts/select_plan_level.py b/Codex/Skills/EN/skills/sopify/design/scripts/select_plan_level.py deleted file mode 100644 index 0c4f663..0000000 --- a/Codex/Skills/EN/skills/sopify/design/scripts/select_plan_level.py +++ /dev/null @@ -1,61 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic plan-level selector for design skill.""" - -from __future__ import annotations - -import argparse -import json -from typing import List - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Select plan level based on explicit change signals." - ) - parser.add_argument("--file-count", type=int, required=True) - parser.add_argument("--architecture-change", action="store_true") - parser.add_argument("--major-refactor", action="store_true") - parser.add_argument("--new-system", action="store_true") - parser.add_argument("--new-feature", action="store_true") - parser.add_argument("--cross-module", action="store_true") - return parser.parse_args() - - -def main() -> int: - args = parse_args() - reasons: List[str] = [] - - if args.architecture_change or args.major_refactor or args.new_system: - level = "full" - if args.architecture_change: - reasons.append("architecture_change") - if args.major_refactor: - reasons.append("major_refactor") - if args.new_system: - reasons.append("new_system") - elif args.file_count > 5 or args.new_feature or args.cross_module: - level = "standard" - if args.file_count > 5: - reasons.append("file_count_gt_5") - if args.new_feature: - reasons.append("new_feature") - if args.cross_module: - reasons.append("cross_module") - elif 3 <= args.file_count <= 5: - level = "light" - reasons.append("file_count_between_3_and_5") - else: - level = "light" - reasons.append("default_light_for_small_scope") - - result = { - "plan_level": level, - "file_count": args.file_count, - "reasons": reasons, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Codex/Skills/EN/skills/sopify/develop/SKILL.md b/Codex/Skills/EN/skills/sopify/develop/SKILL.md deleted file mode 100644 index 4ba1495..0000000 --- a/Codex/Skills/EN/skills/sopify/develop/SKILL.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -name: develop -description: Develop phase entry; routes task execution, state updates, KB sync, and plan close-out through references/assets/scripts. ---- - -# Develop (Entry) - -## When to activate - -- Entering the implementation phase (`workflow` / `light_iterate` / `quick_fix` / `exec_plan`). -- Need to execute the task list, update state, and converge the delivery result. - -## Execution skeleton - -1. Read the active plan tasks (`tasks.md` or light `plan.md`). -2. Extract pending tasks and execute them in numbered order. -3. Update task markers after each step (`[ ] -> [x] / [-] / [!]`). -4. Sync KB files and conservative preference / feedback records. -5. Move completed plans into `history/` and update the index. -6. Render the matching result template. - -## Resource navigation - -- Long rules: `references/develop-rules.md` -- Output templates: `assets/*.md` -- Task extraction script: `scripts/extract_pending_tasks.py` - -## Deterministic logic first - -Use the script when task extraction must be auditable: - -```bash -python3 skills/en/skills/sopify/develop/scripts/extract_pending_tasks.py \ - --tasks-file .sopify-skills/plan//tasks.md -``` - -The script returns JSON with pending tasks, status counts, and execution order. - -## Boundaries - -- This skill executes and closes out work; it does not redefine the plan structure. -- Rollback remains an explicit user action and must keep a traceable record. diff --git a/Codex/Skills/EN/skills/sopify/develop/assets/output-partial.md b/Codex/Skills/EN/skills/sopify/develop/assets/output-partial.md deleted file mode 100644 index e9752d7..0000000 --- a/Codex/Skills/EN/skills/sopify/develop/assets/output-partial.md +++ /dev/null @@ -1,13 +0,0 @@ -[{BRAND_NAME}] Development ! - -Completed: {M}/{N} tasks -Blocked: {K} items - -Blocked tasks: - - [!] 2.3 {task description} - {block reason} - ---- -Changes: {N} files - - ... - -Next: Resume the current host flow after resolving the blockers diff --git a/Codex/Skills/EN/skills/sopify/develop/assets/output-quick-fix.md b/Codex/Skills/EN/skills/sopify/develop/assets/output-quick-fix.md deleted file mode 100644 index a280077..0000000 --- a/Codex/Skills/EN/skills/sopify/develop/assets/output-quick-fix.md +++ /dev/null @@ -1,10 +0,0 @@ -[{BRAND_NAME}] Quick Fix ✓ - -Fix: {one-line description} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: Please verify the fix diff --git a/Codex/Skills/EN/skills/sopify/develop/assets/output-success.md b/Codex/Skills/EN/skills/sopify/develop/assets/output-success.md deleted file mode 100644 index c267699..0000000 --- a/Codex/Skills/EN/skills/sopify/develop/assets/output-success.md +++ /dev/null @@ -1,13 +0,0 @@ -[{BRAND_NAME}] Development ✓ - -Completed: {N}/{N} tasks -Tests: passed - ---- -Changes: {N} files - - src/xxx.vue - - src/xxx.ts - - .sopify-skills/blueprint/design.md - - .sopify-skills/history/... - -Next: Please verify the functionality diff --git a/Codex/Skills/EN/skills/sopify/develop/references/develop-rules.md b/Codex/Skills/EN/skills/sopify/develop/references/develop-rules.md deleted file mode 100644 index 1992ccc..0000000 --- a/Codex/Skills/EN/skills/sopify/develop/references/develop-rules.md +++ /dev/null @@ -1,233 +0,0 @@ -# Develop Detailed Rules - -## Goal - -Implement the task list, maintain task state, sync V2 long-lived knowledge through `knowledge_sync`, and enforce a task-level quality loop so work is not treated as complete without verification evidence. - -## Overall flow - -1. Read the task list. -2. Execute each task through the fixed quality loop: implement change -> discover verification -> run verification -> retry once when needed -> perform two-stage review. Update task markers only after the minimum quality contract is satisfied. -3. If the workspace contains a `post_develop` advisory skill and its prerequisites are met, execute a single post-develop advisory review. -4. Sync KB and preference data through `knowledge_sync`. -5. Move the completed plan into `history/`. -6. Render the execution summary. - -## Step 1: Read the task list - -Sources: - -- `.sopify-skills/plan/{current_plan}/tasks.md` -- `.sopify-skills/plan/{current_plan}/plan.md` (light) - -Handling rules: - -1. Extract `[ ]` pending tasks. -2. Execute by task number order. -3. Check explicit dependencies before execution. - -## Step 2: Execute tasks - -### 2.1 Task-level quality loop - -Process each task in this order: - -1. Locate the target file. -2. Understand the current implementation. -3. Implement the change. -4. Discover the verification command. -5. Run verification. -6. If the first verification run fails, allow one automatic retry with failure context. -7. Classify the failure close-out with a structured root cause. -8. Run the two-stage review: `spec_compliance` -> `code_quality`. -9. Update the task marker only after the minimum quality contract is satisfied. - -Hard requirements: - -- No verification evidence means the task is not complete. -- Subjective claims such as `overbuild`, `underbuild`, or "it should be fine" never replace verification or review evidence. -- Do not silently skip verification and do not retry indefinitely. - -### 2.2 Minimum verify contract - -Use the following field names consistently in develop flows. Do not introduce aliases such as `discovery_source`, `status`, `configured`, or `discovered`: - -1. `verification_source` - - Only expresses where the verification came from. Allowed values are: - - `project_contract` - - `project_native` - - `not_configured` -2. `command` - - Records the verification command attempted for this task. - - It may be empty when no stable command exists, but `reason_code` is then required and the task must not be presented as verified. -3. `scope` - - Records the task, file, or module scope covered by verification. -4. `result` - - Must use: - - `passed` - - `retried` - - `failed` - - `skipped` - - `replan_required` -5. `reason_code` - - Required whenever verification cannot run, degrades visibly, is skipped, or routes back to plan review. -6. `retry_count` - - v1 only allows `0` or `1`. -7. `root_cause` - - Required for failed close-out paths and retry close-out paths. -8. `review_result` - - Must contain at least the stage conclusions for `spec_compliance` and `code_quality`. - -Additional rules: - -- `.sopify-skills/project.md` is the future long-term home for a project-level `verify` contract. When present, it has the highest priority, but it is not a prerequisite for v1. -- `verification_source` is a source field only. Degrade/skip outcomes must be expressed through `result + reason_code`. - -### 2.3 Verification discovery order - -Use this fixed priority: - -1. `project_contract` - - A `verify` contract already defined in `.sopify-skills/project.md`. -2. `project_native` - - Stable native project entry points such as `package.json`, `pyproject.toml`, `Makefile`, or `justfile`. -3. `not_configured` - - If no stable command exists, degrade visibly and record `reason_code`; do not treat "no command found" as an implicit pass. - -### 2.4 Failure handling and root cause classification - -Failure handling rules: - -1. Allow one automatic retry after the first failed verification run. -2. Stop automatic retries after the second failure. -3. Record `root_cause` whenever the second failure happens or retry is explicitly abandoned. - -Allowed `root_cause` values: - -- `logic_regression` -- `environment_or_dependency` -- `missing_test_infra` -- `scope_or_design_mismatch` - -Routing constraints: - -- `logic_regression`: stay in develop, but continue with concrete failure context. -- `environment_or_dependency`: make the environment limitation visible and do not present the task as verified. -- `missing_test_infra`: keep the task unverified and record the missing-test follow-up explicitly. -- `scope_or_design_mismatch`: do not keep patching blindly; return to plan review, a decision checkpoint, or another host confirmation path. - -### 2.5 Two-stage review - -Stage A `spec_compliance` must at least check: - -1. Whether the task goal and boundaries were met. -2. Whether there is obvious `overbuild` or `underbuild`. -3. Whether the change introduced a new scope shift or a user-facing decision branch. - -Stage B `code_quality` must at least check: - -1. Consistency with the existing code style. -2. No obvious security, stability, or maintainability regression. -3. Whether the change size, comments, tests, and KB sync meet the minimum standard for the task. - -State transitions: - -- Success: `[ ] -> [x]` is allowed only when `verification_source / result / review_result` satisfy the minimum contract -- Skipped: `[ ] -> [-]` -- Blocked: `[ ] -> [!]` - -Security baseline: - -- Do not introduce common vulnerabilities (XSS / SQL injection / etc.). -- Do not break existing behavior. -- Keep the project style consistent. - -## Step 3: Post-develop advisory review - -After all tasks pass the quality loop and two-stage review, if the workspace `.agents/skills/` contains an advisory skill whose triggers include `post_develop`, execute a single post-develop advisory review following its SKILL.md. Currently only CrossReview Phase 4a is included in this path. - -Trigger conditions: - -1. All tasks have passed the quality loop (Step 2 complete). -2. The workspace has unreviewed code changes (committed review range `git diff ..HEAD` is non-empty, or uncommitted changes exist and must be confirmed/handled per advisory skill Step 0). -3. The advisory skill's prerequisites are met (e.g. CLI installed, and the isolated execution context required by host-integrated review is available). - -Execution constraints: - -- Execution failure or `inconclusive` verdict does not block the main flow. -- `concerns` / `needs_human_triage` are shown to the user and await their decision; do not auto-write checkpoints or auto-modify code. -- If prerequisites are not met (e.g. CLI not installed), skip and log the reason without blocking. -- Note: Phase 4a stays in Convention mode; this does not introduce `bridge.py`, `pipeline_hooks`, or a runtime lifecycle hook. - -## Step 4: Sync the knowledge base - -Sync timing: - -1. After each module-level task batch. -2. Once again during phase close-out. - -Sync targets: - -- `project.md` -- `blueprint/background.md` -- `blueprint/design.md` -- `blueprint/tasks.md` -- `user/preferences.md` (long-term preferences only) -- `user/feedback.jsonl` - -Formal rule: - -- `knowledge_sync.skip`: no sync required -- `knowledge_sync.review`: at least review before finalize -- `knowledge_sync.required`: finalize must block until updated - -Conservative preference writes: - -Allowed: - -- Explicit long-term user preferences such as "use this by default going forward". - -Disallowed: - -- One-off instructions. -- Guesses from incomplete context. -- Generalized conclusions unrelated to the task. - -## Step 5: Plan migration - -Migration path: - -```text -.sopify-skills/plan/YYYYMMDD_feature/ - -> .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/ -``` - -Create and update `.sopify-skills/history/index.md` on demand during the first explicit finalize. - -## Output templates - -Choose the result format from `assets/`: - -1. `assets/output-success.md` -2. `assets/output-partial.md` -3. `assets/output-quick-fix.md` - -## Special cases - -Execution interruption: - -1. Mark completed tasks as `[x]`. -2. Keep the current task as `[ ]`. -3. Render the interruption summary and wait for host recovery. - -Task failure: - -1. Mark the task as `[!]` with the reason. -2. For any closed-out failure path, record `reason_code`, and add `root_cause` plus `review_result` when required. -3. Continue only with independent tasks that are not blocked by the failure. - -Rollback request: - -1. Use git rollback only when the user explicitly requests it. -2. Keep the plan package in `plan/` instead of migrating it. -3. Render rollback confirmation. diff --git a/Codex/Skills/EN/skills/sopify/develop/scripts/extract_pending_tasks.py b/Codex/Skills/EN/skills/sopify/develop/scripts/extract_pending_tasks.py deleted file mode 100644 index 812d5e2..0000000 --- a/Codex/Skills/EN/skills/sopify/develop/scripts/extract_pending_tasks.py +++ /dev/null @@ -1,69 +0,0 @@ -#!/usr/bin/env python3 -"""Extract deterministic task status summary from a plan markdown file.""" - -from __future__ import annotations - -import argparse -import json -import re -from pathlib import Path -from typing import Dict, List - -TASK_PATTERN = re.compile(r"^\s*-\s*\[(?P[ x!\-])\]\s*(?P.+?)\s*$") - - -def parse_args() -> argparse.Namespace: - parser = argparse.ArgumentParser( - description="Extract pending/completed/blocked/skipped tasks from markdown." - ) - parser.add_argument("--tasks-file", required=True, help="Path to tasks.md or plan.md") - return parser.parse_args() - - -def classify_status(raw: str) -> str: - if raw == " ": - return "pending" - if raw == "x": - return "completed" - if raw == "!": - return "blocked" - if raw == "-": - return "skipped" - return "unknown" - - -def main() -> int: - args = parse_args() - path = Path(args.tasks_file) - lines = path.read_text(encoding="utf-8").splitlines() - - tasks: List[Dict[str, str]] = [] - counts: Dict[str, int] = { - "pending": 0, - "completed": 0, - "blocked": 0, - "skipped": 0, - } - - for idx, line in enumerate(lines, start=1): - match = TASK_PATTERN.match(line) - if not match: - continue - status_key = classify_status(match.group("status")) - text = match.group("text") - tasks.append({"line": idx, "status": status_key, "text": text}) - if status_key in counts: - counts[status_key] += 1 - - result = { - "tasks_file": str(path), - "counts": counts, - "pending_tasks": [task for task in tasks if task["status"] == "pending"], - "all_tasks": tasks, - } - print(json.dumps(result, ensure_ascii=False, indent=2)) - return 0 - - -if __name__ == "__main__": - raise SystemExit(main()) diff --git a/Codex/Skills/EN/skills/sopify/kb/SKILL.md b/Codex/Skills/EN/skills/sopify/kb/SKILL.md deleted file mode 100644 index ce52b46..0000000 --- a/Codex/Skills/EN/skills/sopify/kb/SKILL.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -name: kb -description: Knowledge base management skill; read during KB operations; includes init, update, sync strategies ---- - -# Knowledge Base Management - V2 Rules - -**Goal:** manage the V2 layers in `.sopify-skills/` so long-lived knowledge, the active plan, and finalized archives stay clearly separated. - -## Knowledge Base Structure - -```text -.sopify-skills/ -├── blueprint/ -│ ├── README.md # Pure index page with index-required sections only -│ ├── background.md # Long-term goals, scope, non-goals -│ ├── design.md # Module / host / directory / consumption contracts -│ └── tasks.md # Unfinished long-term items and explicit deferrals -├── project.md # Project technical conventions -├── user/ -│ ├── preferences.md # Long-term user preferences -│ └── feedback.jsonl # Raw feedback events -├── plan/ -│ └── YYYYMMDD_feature/ # Current active plan -├── history/ -│ ├── index.md # Archive index -│ └── YYYY-MM/ -└── state/ # Runtime machine truth -``` - -## Initialization Strategy - -### Full mode (`kb_init: full`) - -Create on the first bootstrap: - -```yaml -Create: - - .sopify-skills/project.md - - .sopify-skills/user/preferences.md - - .sopify-skills/user/feedback.jsonl - - .sopify-skills/blueprint/README.md - - .sopify-skills/blueprint/background.md - - .sopify-skills/blueprint/design.md - - .sopify-skills/blueprint/tasks.md -``` - -Notes: - -- Do not pre-create `plan/` content. -- Do not pre-create `history/index.md` or any archive. - -### Progressive mode (`kb_init: progressive`) [default] - -Materialize by lifecycle: - -```yaml -First real-project trigger: - - .sopify-skills/project.md - - .sopify-skills/user/preferences.md - - .sopify-skills/blueprint/README.md - -First plan lifecycle: - - .sopify-skills/blueprint/background.md - - .sopify-skills/blueprint/design.md - - .sopify-skills/blueprint/tasks.md - - .sopify-skills/plan/YYYYMMDD_feature/ - -First explicit ~go finalize: - - .sopify-skills/history/index.md - - .sopify-skills/history/YYYY-MM/YYYYMMDD_feature/ - -First explicit long-term preference: - - .sopify-skills/user/feedback.jsonl -``` - -## Read Order - -1. `project.md` -2. `user/preferences.md` -3. `blueprint/README.md` -4. `blueprint/background.md` -5. `blueprint/design.md` -6. `blueprint/tasks.md` -7. `active_plan = current_plan.path + current_plan.files` - -Rules: - -- consult / clarification routes prefer `L0/L1` and must not require deep blueprint files -- planning / develop may enter `L2 active plan` -- `history/` is not the default long-lived context source; read it only for finalize lookups or human traceability - -## Update Rules - -### L0 Index Guardrails - -- `blueprint/README.md` keeps only `status / maintenance / current goal / current focus / read next`. -- Do not write absolute workspace paths, long-form architecture prose, or formal contract bodies into `blueprint/README.md`. -- If extra long-lived topic docs exist at the `blueprint/` root, `blueprint/README.md` must list them explicitly. - -### `blueprint/tasks.md` Boundaries - -- Keep only unfinished long-term items and explicit deferrals. -- `[x]` completed items must not remain in `blueprint/tasks.md`. - -### Must update - -- `project.md`: reusable technical conventions changed -- `blueprint/background.md`: long-term goals, scope, or non-goals changed -- `blueprint/design.md`: module, host, directory, or consumption contracts changed -- `blueprint/tasks.md`: unfinished long-term items or explicit deferrals changed -- `user/preferences.md`: the user explicitly stated a long-term preference - -### Must not be written into long-lived knowledge - -- one-off implementation details -- short-term task breakdown from the current plan -- temporary tradeoffs that belong only to this task -- completed task checklists lingering in `blueprint/tasks.md` -- copying history body text back into blueprint - -## `knowledge_sync` Sync Contract - -```yaml -knowledge_sync: - project: skip|review|required - background: skip|review|required - design: skip|review|required - tasks: skip|review|required -``` - -Execution rules: - -- `skip`: no sync required for this round -- `review`: at least review before finalize -- `required`: finalize must block until updated - -## Conflict Handling - -- code vs docs: code is the source of truth, then update docs -- current task vs long-term preference: current explicit task > `user/preferences.md` > default rules - -## Output Format - -**Initialization complete:** - -```text -[{BRAND_NAME}] Knowledge Base Init ✓ - -Created: {N} files -Strategy: {full/progressive} - ---- -Changes: {N} files - - .sopify-skills/project.md - - .sopify-skills/blueprint/README.md - - ... - -Next: KB is ready -``` - -**Sync complete:** - -```text -[{BRAND_NAME}] Knowledge Base Sync ✓ - -Updated: {N} files - ---- -Changes: {N} files - - .sopify-skills/project.md - - .sopify-skills/blueprint/design.md - - ... - -Next: Docs updated -``` diff --git a/Codex/Skills/EN/skills/sopify/templates/SKILL.md b/Codex/Skills/EN/skills/sopify/templates/SKILL.md deleted file mode 100644 index 2ef0d74..0000000 --- a/Codex/Skills/EN/skills/sopify/templates/SKILL.md +++ /dev/null @@ -1,261 +0,0 @@ ---- -name: templates -description: Document template collection; read when creating docs; includes all KB templates and plan file templates ---- - -# Document Template Collection - -**Usage notes:** -1. Replace `{...}` with actual content. -2. Formal plan packages include the scoring block by default. -3. `blueprint/README.md` stays as a lightweight index only. -4. If extra long-lived topic docs exist at the `blueprint/` root, they must be linked explicitly from `blueprint/README.md`. -5. `blueprint/tasks.md` keeps only unfinished long-term items and explicit deferrals; completed items do not remain in that file. - -## A1 | Knowledge Base Templates - -### project.md - -```markdown -# Project Technical Conventions - -## Tech Stack -- Core: {language version} / {framework version} -- Build: {build tool} -- Test: {test framework} - -## Working Agreement -- Keep this file focused on reusable technical conventions. -- Do not treat one-off implementation choices as project-wide rules. - -## Document Boundaries -- `project.md`: reusable conventions -- `blueprint/background.md`: long-term goals, scope, non-goals -- `blueprint/design.md`: module / host / directory / consumption contracts -- `blueprint/tasks.md`: unfinished long-term items and explicit deferrals -``` - -### blueprint/README.md - -```markdown -# Project Blueprint Index - -Status: {current status} -Maintenance: keep only status, current goal, current focus, and read-next links on this page; move long explanations into other blueprint files - -## Current Goal -- Project: `{project_name}` -- Long-term goals and scope live in `./background.md` - -## Current Focus -- Active plan: {present/none} -- History archive: {status} - -## Read Next -- [Technical Conventions](../project.md) -- [Blueprint Background](./background.md) -- [Blueprint Design](./design.md) -- [Blueprint Tasks](./tasks.md) -- [Blueprint Topic](./{extra_blueprint_doc}.md) # list each additional long-lived topic doc when present -- [Change History](../history/index.md) -``` - -### blueprint/background.md - -```markdown -# Blueprint Background - -## Long-Term Goals -- {goal1} -- {goal2} - -## Scope -- In scope: {content} -- Out of scope: {content} - -## Non-Goals -- {content} -``` - -### blueprint/design.md - -```markdown -# Blueprint Design - -## Formal Contracts -- `knowledge_sync` is the only formal sync contract. -- `active_plan = current_plan.path + current_plan.files`. - -## Consumption Contract - -| Context Profile | Reads | Fail-open Rule | Notes | -|-----|------|------|------| -| `consult` | `project.md`, `preferences.md`, `blueprint/README.md` | missing deep blueprint does not fail | do not force plan materialization | -| `plan` | `L1` + `active_plan` | materialize deep blueprint by lifecycle when missing | history is not default context | -| `finalize` | `active_plan`, `knowledge_sync`, `blueprint/*`, `history/index.md` | create `history/index.md` on demand when missing | block when `required` sync is not satisfied | -``` - -### blueprint/tasks.md - -```markdown -# Blueprint Tasks - -Status: keep only unfinished long-term items and explicit deferrals; completed items do not remain in this file. - -## Unfinished Long-Term Items -- [ ] {long-term item} - -## Explicit Deferrals -- [-] {deferred item} -``` - -### history/index.md - -```markdown -# Change History Index - -| Timestamp | Feature | Status | Plan Package | -|-----------|---------|--------|--------------| -| {YYYYMMDD} | {feature} | ✓ | [Link](YYYY-MM/...) | -``` - -### user/preferences.md - -```markdown -# Long-Term User Preferences - -> Record only explicitly stated long-term preferences. One-off instructions stay out of this file. - -No confirmed long-term preferences yet. -``` - -### user/feedback.jsonl - -```json -{"timestamp":"2026-01-15T10:30:00Z","source":"chat","message":"Use the smallest change list by default going forward","scope":"planning","promote_to_preference":true,"preference_id":"pref-002"} -{"timestamp":"2026-01-15T11:10:00Z","source":"chat","message":"Make the output more detailed for this task","scope":"current_task","promote_to_preference":false} -``` - -## A2 | Plan Package Templates - -### Light Level - plan.md - -```markdown -# {Feature Name} - -## Background -{1-2 sentences describing the requirement background} - -Scoring: -- Solution quality: {X}/10 -- Implementation readiness: {Y}/10 - -Scoring rationale: -- Strengths: {1 line} -- Deductions: {1 line} - -## Solution -- {technical point 1} -- {technical point 2} - -## Tasks -- [ ] {task1} -- [ ] {task2} - -## Changed Files -- {file1} -- {file2} -``` - -### Standard Level - background.md - -```markdown -# Change Proposal: {Feature Name} - -## Requirement Background -{Describe the current state, pain points, and change drivers} - -Scoring: -- Solution quality: {X}/10 -- Implementation readiness: {Y}/10 - -Scoring rationale: -- Strengths: {1 line} -- Deductions: {1 line} - -## Change Content -1. {change point 1} -2. {change point 2} - -## Impact Scope -- Modules: {list} -- Files: {list} - -## Risk Assessment -- Risk: {description} -- Mitigation: {measures} -``` - -### Standard Level - design.md - -```markdown -# Technical Design: {Feature Name} - -## Technical Solution -- Core technology: {language/framework/library} -- Implementation points: - - {point1} - - {point2} - -## Architecture Design -{Include a mermaid diagram when the architecture changes} - -## Security and Performance -- Security: {measures} -- Performance: {optimizations} -``` - -### Standard Level - tasks.md - -```markdown -# Task List: {Feature Name} - -Directory: `.sopify-skills/plan/{YYYYMMDD}_{feature}/` - -## 1. {Module Name} -- [ ] 1.1 Implement {feature} in `{file path}` -- [ ] 1.2 Implement {feature} in `{file path}` - -## 2. Testing -- [ ] 2.1 {test task} - -## 3. Documentation Update -- [ ] 3.1 Update `project.md / blueprint/background.md / blueprint/design.md / blueprint/tasks.md` -``` - -### Full Level - adr/{NNN}-{title}.md - -```markdown -# ADR-{NNN}: {Decision Title} - -## Status -Adopted | Pending | Deprecated - -## Date -{YYYY-MM-DD} - -## Context -{Background and problem statement} - -## Decision -{Core decision content} -``` - -## A3 | Task Markers - -| Marker | Meaning | -|--------|---------| -| `[ ]` | Pending | -| `[x]` | Completed | -| `[-]` | Skipped | -| `[!]` | Blocked | diff --git a/README.md b/README.md index 8c63199..cb7c773 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE) [![Docs](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs) -[![Version](https://img.shields.io/badge/version-2026--05--27.132948-orange.svg)](#version-history) +[![Version](https://img.shields.io/badge/version-2026--05--27.161019-orange.svg)](#version-history) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md) English · [简体中文](./README.zh-CN.md) · [Quick Start](#quick-start) · [Contributors](./CONTRIBUTORS.md) @@ -213,13 +213,13 @@ sopify/ ├── examples/ # configuration examples ├── docs/ # workflow guides and developer references ├── runtime/ # built-in runtime / skill packages +├── skills/ # prompt-layer source of truth ├── .sopify-skills/ # project knowledge base │ ├── blueprint/ # design baseline, reduction targets │ │ └── architecture-decision-records/ # ADR entity files │ ├── plan/ # active plans │ └── history/ # archived plans -├── Codex/ # Codex host prompt layer -└── Claude/ # Claude host prompt layer +└── installer/ # host adapters and install orchestration ``` This is a simplified view of the core layout. See [docs/how-sopify-works.en.md](./docs/how-sopify-works.en.md) for the full workflow, checkpoints, and knowledge layout. diff --git a/README.zh-CN.md b/README.zh-CN.md index ab14b82..3aa0f98 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -8,7 +8,7 @@ [![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE) [![文档](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg)](./LICENSE-docs) -[![版本](https://img.shields.io/badge/version-2026--05--27.132948-orange.svg)](#版本历史) +[![版本](https://img.shields.io/badge/version-2026--05--27.161019-orange.svg)](#版本历史) [![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING_CN.md) [English](./README.md) · 简体中文 · [快速开始](#快速开始) · [贡献者](./CONTRIBUTORS.md) @@ -213,13 +213,13 @@ sopify/ ├── examples/ # 配置示例 ├── docs/ # 工作流指南与开发者参考 ├── runtime/ # 内置 runtime / skill packages +├── skills/ # prompt-layer 真源 ├── .sopify-skills/ # 项目知识库 │ ├── blueprint/ # 设计基线与削减目标 │ │ └── architecture-decision-records/ # ADR 实体文件 │ ├── plan/ # 活跃方案 │ └── history/ # 已归档方案 -├── Codex/ # Codex 宿主提示层 -└── Claude/ # Claude 宿主提示层 +└── installer/ # 宿主适配器与安装编排 ``` 上面是核心目录的精简视图；完整工作流、checkpoint 和知识库层级说明见 [docs/how-sopify-works.md](./docs/how-sopify-works.md)。 diff --git a/docs/dev/release-process.md b/docs/dev/release-process.md index 6b95948..37ae578 100644 --- a/docs/dev/release-process.md +++ b/docs/dev/release-process.md @@ -20,7 +20,7 @@ git config core.hooksPath .githooks bash scripts/release-preflight.sh ``` -依次跑：skill 同步与镜像一致性、版本一致性、builtin catalog 漂移检测、runtime 单元测试 + smoke、skill eval 质量门禁。全部通过再继续。 +依次跑：版本一致性、golden snapshot、builtin catalog 漂移检测、runtime 单元测试 + smoke、skill eval 质量门禁。全部通过再继续。 ### 2. 确认版本号 @@ -55,13 +55,11 @@ bash scripts/check-version-consistency.sh version-2026--03--26.103000-orange.svg ``` -**四个宿主文件顶部注释**： +**两个源模板顶部注释**： ``` -Codex/Skills/CN/AGENTS.md → -Codex/Skills/EN/AGENTS.md -Claude/Skills/CN/CLAUDE.md -Claude/Skills/EN/CLAUDE.md +skills/zh/header.md.template → +skills/en/header.md.template ``` 更新后验证： @@ -76,8 +74,7 @@ bash scripts/check-version-consistency.sh ```bash TAG="2026-03-26.103000" git add CHANGELOG.md README.md README.zh-CN.md \ - Codex/Skills/CN/AGENTS.md Codex/Skills/EN/AGENTS.md \ - Claude/Skills/CN/CLAUDE.md Claude/Skills/EN/CLAUDE.md + skills/zh/header.md.template skills/en/header.md.template git commit -m "release: $TAG" git push ``` diff --git a/runtime/builtin_catalog.py b/runtime/builtin_catalog.py index 900e4e8..a3e0900 100644 --- a/runtime/builtin_catalog.py +++ b/runtime/builtin_catalog.py @@ -10,10 +10,9 @@ from sopify_contracts.core import SkillMeta _DEFAULT_CONTRACT_VERSION = "1" -_SOPIFY_DOC_ROOT = ("Codex", "Skills") _LANGUAGE_DIRS = { - "zh-CN": ("CN", "EN"), - "en-US": ("EN", "CN"), + "zh-CN": ("zh", "en"), + "en-US": ("en", "zh"), } _GENERATED_CATALOG_PATH = Path("runtime") / "builtin_catalog.generated.json" @@ -194,10 +193,7 @@ def _resolve_instruction_path(repo_root: Path, language: str, skill_id: str) -> candidates: list[Path] = [] for language_dir in language_dirs: candidates.append( - repo_root / _SOPIFY_DOC_ROOT[0] / _SOPIFY_DOC_ROOT[1] / language_dir / "skills" / "sopify" / skill_id / "SKILL.md" - ) - candidates.append( - repo_root / "Claude" / "Skills" / language_dir / "skills" / "sopify" / skill_id / "SKILL.md" + repo_root / "skills" / language_dir / "skills" / "sopify" / skill_id / "SKILL.md" ) for candidate in candidates: if candidate.exists(): diff --git a/runtime/manifest.py b/runtime/manifest.py index 860c9b0..50d9bcb 100644 --- a/runtime/manifest.py +++ b/runtime/manifest.py @@ -306,7 +306,7 @@ def _resolve_bundle_version(*, source_root: Path, bundle_root: Path, explicit_ve if explicit_version: return explicit_version - version = _read_version_header(source_root / "Codex" / "Skills" / "CN" / "AGENTS.md") + version = _read_version_header(source_root / "skills" / "zh" / "header.md.template") if version is not None: return version diff --git a/scripts/check-readme-links.py b/scripts/check-readme-links.py index 3e58ca0..4fe304a 100644 --- a/scripts/check-readme-links.py +++ b/scripts/check-readme-links.py @@ -19,10 +19,6 @@ VERSION_HEADERS = ( ROOT / "skills/zh/header.md.template", ROOT / "skills/en/header.md.template", - ROOT / "Codex/Skills/CN/AGENTS.md", - ROOT / "Codex/Skills/EN/AGENTS.md", - ROOT / "Claude/Skills/CN/CLAUDE.md", - ROOT / "Claude/Skills/EN/CLAUDE.md", ) LINK_PATTERN = re.compile(r"(? Claude skills mirrors - 2) Verify mirrors and version consistency - 3) Run runtime unit tests + installer/runtime smoke checks + 1) Verify version consistency and golden snapshots + 2) Run runtime unit tests + installer/runtime smoke checks EOF } @@ -57,9 +56,8 @@ PY rm -f "$tmp" } -run_step "Sync skills" bash "$ROOT_DIR/scripts/sync-skills.sh" -run_step "Check skills sync" bash "$ROOT_DIR/scripts/check-skills-sync.sh" run_step "Check version consistency" bash "$ROOT_DIR/scripts/check-version-consistency.sh" +run_step "Check golden snapshots" python3 -m pytest "$ROOT_DIR/tests/test_golden_snapshots.py" -q run_step "Check builtin catalog drift" check_builtin_catalog_drift run_step "Check context checkpoints" python3 "$ROOT_DIR/scripts/check-context-checkpoints.py" repo --root "$ROOT_DIR" run_step "Run hard gate tests (contract + smoke + distribution)" python3 -m pytest "$ROOT_DIR/tests" -m "not implementation_mirror" -v diff --git a/scripts/release-sync.sh b/scripts/release-sync.sh index 8f5cd62..fac2f6b 100755 --- a/scripts/release-sync.sh +++ b/scripts/release-sync.sh @@ -20,7 +20,7 @@ Synchronize release version across key files: - move current [Unreleased] content into ## [] - 3) skills/ source template SOPIFY_VERSION headers (zh/en) - 4) Render skills/ -> host distributions and run consistency checks + 4) Run consistency checks Arguments: release version, e.g. 2026-02-13 or 2026-01-15.1 @@ -72,8 +72,6 @@ required_files=( "$SKILLS_ZH" "$SKILLS_EN" "$CHANGELOG_DRAFT_SCRIPT" - "$ROOT_DIR/scripts/sync-skills.sh" - "$ROOT_DIR/scripts/check-skills-sync.sh" "$ROOT_DIR/scripts/check-version-consistency.sh" ) @@ -297,8 +295,6 @@ promote_unreleased_to_release "$CHANGELOG" replace_once "$SKILLS_ZH" '^$' "" replace_once "$SKILLS_EN" '^$' "" -bash "$ROOT_DIR/scripts/sync-skills.sh" -bash "$ROOT_DIR/scripts/check-skills-sync.sh" bash "$ROOT_DIR/scripts/check-version-consistency.sh" echo "Release sync completed successfully." diff --git a/scripts/sopify_init.py b/scripts/sopify_init.py index 3cc1076..a8eb871 100644 --- a/scripts/sopify_init.py +++ b/scripts/sopify_init.py @@ -58,8 +58,8 @@ def _read_source_version() -> str | None: """Read the embedded Sopify version from the source host header.""" for candidate in ( - REPO_ROOT / "Codex" / "Skills" / "EN" / "AGENTS.md", - REPO_ROOT / "Codex" / "Skills" / "CN" / "AGENTS.md", + REPO_ROOT / "skills" / "en" / "header.md.template", + REPO_ROOT / "skills" / "zh" / "header.md.template", ): if candidate.is_file(): match = _SOPIFY_VERSION_RE.search(candidate.read_text(encoding="utf-8")) diff --git a/skills/en/header.md.template b/skills/en/header.md.template index 2aae7a9..3b5665e 100644 --- a/skills/en/header.md.template +++ b/skills/en/header.md.template @@ -1,5 +1,5 @@ - + # Sopify - Adaptive AI Programming Assistant diff --git a/skills/zh/header.md.template b/skills/zh/header.md.template index dd4e246..0259e94 100644 --- a/skills/zh/header.md.template +++ b/skills/zh/header.md.template @@ -1,5 +1,5 @@ - + # Sopify - 自适应 AI 编程助手 diff --git a/tests/golden-snapshots.json b/tests/golden-snapshots.json new file mode 100644 index 0000000..a899317 --- /dev/null +++ b/tests/golden-snapshots.json @@ -0,0 +1,20 @@ +{ + "protocol_version": "1.0", + "description": "T6 golden snapshot — sha256 hashes of all host install products rendered from skills/ source", + "hash_algorithm": "sha256", + "normalization": { + "header": "path\\0rendered_content, UTF-8, LF line endings", + "managed_block_payload": "render_single_file() output, UTF-8", + "tree": "sorted files, posix_path\\0raw_bytes per file, NL-joined, sha256" + }, + "snapshots": { + "codex:zh-CN:header": "b6f7ed30241e8a550892983e9d817a91fb9958d15cc4ee3603c30f7597443467", + "codex:en-US:header": "e3203542a4ed2a688542eefd00c45401962be2482f025d23ee36eec3d01f3f83", + "claude:zh-CN:header": "e4cdf95be330d14b052b41101c4a24acbe839616f3ca59392715d68681ecfa03", + "claude:en-US:header": "4138b70de2186883d8d400c44ca0140be437ebcf768a2c56bf8f6d48fc1e169f", + "copilot:zh-CN:managed_block_payload": "9ce59cad2f77594428bc3363200aa0710eb041f863bb10e1ff4666de4ba30a60", + "copilot:en-US:managed_block_payload": "fd0c4d1f7fa55d5aac4a98b4bf3e1d261d6a13be5adaaa9f758ab332dfe83459", + "skills:zh-CN:tree": "0a803309a73e994dafca77e8aa84f343d847df080134d67bd799c85ed1346959", + "skills:en-US:tree": "6c669c93882c6c2517a8248acf34bc12e027a18e0f900756c753d4caa24bf245" + } +} diff --git a/tests/test_check_readme_links.py b/tests/test_check_readme_links.py index 5549100..f4346d5 100644 --- a/tests/test_check_readme_links.py +++ b/tests/test_check_readme_links.py @@ -71,6 +71,18 @@ def _minimal_agents(version: str, *, claude: bool, english: bool) -> str: ) +def _minimal_source_template(version: str, *, english: bool) -> str: + body = "Note: {{config_dir}}/sopify/" if english else "说明：{{config_dir}}/sopify/" + return textwrap.dedent( + f"""\ + + # HEADER + + {body} + """ + ) + + def _configure_module(module, root: Path) -> None: readme_sections_primary = module.EXPECTED_LEVEL2_SECTIONS[module.README_FILES[0]] readme_sections_zh = module.EXPECTED_LEVEL2_SECTIONS[module.README_FILES[1]] @@ -90,10 +102,8 @@ def _configure_module(module, root: Path) -> None: module.README_FILES + module.WORKFLOW_DOC_FILES + module.CONTRIBUTING_FILES ) module.VERSION_HEADERS = ( - root / "Codex/Skills/CN/AGENTS.md", - root / "Codex/Skills/EN/AGENTS.md", - root / "Claude/Skills/CN/CLAUDE.md", - root / "Claude/Skills/EN/CLAUDE.md", + root / "skills/zh/header.md.template", + root / "skills/en/header.md.template", ) module.EXPECTED_LEVEL2_SECTIONS = { module.README_FILES[0]: readme_sections_primary, @@ -122,15 +132,13 @@ def _init_fixture(root: Path, module, *, broken_workflow_link: bool = False, reo "LICENSE", "LICENSE-docs", "CHANGELOG.md", - "Codex/Skills/CN/skills/sopify/.gitkeep", - "Codex/Skills/EN/skills/sopify/.gitkeep", + "skills/zh/skills/sopify/.gitkeep", + "skills/en/skills/sopify/.gitkeep", ): _write(root / relative, "placeholder\n") - _write(root / "Codex/Skills/CN/AGENTS.md", _minimal_agents(VERSION, claude=False, english=False)) - _write(root / "Codex/Skills/EN/AGENTS.md", _minimal_agents(VERSION, claude=False, english=True)) - _write(root / "Claude/Skills/CN/CLAUDE.md", _minimal_agents(VERSION, claude=True, english=False)) - _write(root / "Claude/Skills/EN/CLAUDE.md", _minimal_agents(VERSION, claude=True, english=True)) + _write(root / "skills/zh/header.md.template", _minimal_source_template(VERSION, english=False)) + _write(root / "skills/en/header.md.template", _minimal_source_template(VERSION, english=True)) _write( root / "README.md", @@ -191,7 +199,7 @@ def _init_fixture(root: Path, module, *, broken_workflow_link: bool = False, reo "贡献指南", contributing_cn_sections, intro="中文维护者入口。", - links=("[Codex CN](./Codex/Skills/CN/skills/sopify/)",), + links=("[Skills ZH](./skills/zh/skills/sopify/)",), ), ) _write( @@ -200,7 +208,7 @@ def _init_fixture(root: Path, module, *, broken_workflow_link: bool = False, reo "Contributing", contributing_en_sections, intro="English maintainer entry.", - links=("[Codex EN](./Codex/Skills/EN/skills/sopify/)",), + links=("[Skills EN](./skills/en/skills/sopify/)",), ), ) diff --git a/tests/test_golden_snapshots.py b/tests/test_golden_snapshots.py new file mode 100644 index 0000000..aac57ef --- /dev/null +++ b/tests/test_golden_snapshots.py @@ -0,0 +1,136 @@ +"""T6 golden snapshot — verify install products haven't drifted. + +Compares sha256 hashes of all host install products (rendered from skills/) +against the baseline recorded in tests/golden-snapshots.json. + +Products covered: + - codex:{locale}:header — path\\0rendered_header (AGENTS.md) + - claude:{locale}:header — path\\0rendered_header (CLAUDE.md) + - copilot:{locale}:managed_block_payload — render_single_file() output + - skills:{locale}:tree — sorted path\\0content of skills/sopify/** + +When a snapshot fails, the test prints the expected vs actual hash and the +snapshot key. Update tests/golden-snapshots.json manually after confirming +the change is intentional. +""" + +from __future__ import annotations + +import hashlib +import json +from pathlib import Path + +import pytest + +from installer.hosts.base import ( + HEADER_TEMPLATE_NAME, + HostAdapter, + render_single_file, +) +from installer.hosts.claude import CLAUDE_ADAPTER +from installer.hosts.codex import CODEX_ADAPTER +from installer.hosts.copilot import COPILOT_ADAPTER +from installer.models import language_to_source_dir + +_REPO_ROOT = Path(__file__).resolve().parent.parent +_GOLDEN_PATH = Path(__file__).resolve().parent / "golden-snapshots.json" +_IGNORE_NAMES = {".DS_Store", "Thumbs.db", "__pycache__"} + + +def _load_golden() -> dict: + with open(_GOLDEN_PATH, encoding="utf-8") as f: + return json.load(f)["snapshots"] + + +def _render_header(adapter: HostAdapter, lang_dir: str) -> str: + source_root = adapter.source_root(_REPO_ROOT, lang_dir) + template = source_root / HEADER_TEMPLATE_NAME + content = template.read_text(encoding="utf-8") + if adapter.config_dir is not None: + content = content.replace("{{config_dir}}", adapter.config_dir) + else: + content = content.replace("{{config_dir}}", "") + return content + + +def _header_hash(adapter: HostAdapter, lang_dir: str) -> str: + rendered = _render_header(adapter, lang_dir) + canonical = f"{adapter.header_filename}\x00{rendered}".encode("utf-8") + return hashlib.sha256(canonical).hexdigest() + + +def _tree_hash(lang_dir: str) -> str: + source_dir = language_to_source_dir(lang_dir) + skills_root = _REPO_ROOT / "skills" / source_dir / "skills" / "sopify" + parts: list[bytes] = [] + for f in sorted(skills_root.rglob("*")): + if f.is_file() and f.name not in _IGNORE_NAMES: + rel = f.relative_to(skills_root).as_posix() + parts.append(rel.encode("utf-8") + b"\x00" + f.read_bytes()) + return hashlib.sha256(b"\n".join(parts)).hexdigest() + + +def _copilot_payload_hash(lang_dir: str) -> str: + source_root = COPILOT_ADAPTER.source_root(_REPO_ROOT, lang_dir) + header_source = source_root / HEADER_TEMPLATE_NAME + skills_source = source_root / "skills" / "sopify" + rendered = render_single_file(header_source, skills_source, COPILOT_ADAPTER) + return hashlib.sha256(rendered.encode("utf-8")).hexdigest() + + +def _assert_hash(key: str, actual: str, golden: dict) -> None: + expected = golden.get(key) + assert expected is not None, f"Missing golden entry: {key}" + assert actual == expected, ( + f"Golden snapshot mismatch for {key}\n" + f" expected: {expected}\n" + f" actual: {actual}\n" + f"Update tests/golden-snapshots.json if this change is intentional." + ) + + +# -- Header snapshots (Codex / Claude) -- + +@pytest.mark.parametrize( + "adapter,lang_dir,locale", + [ + (CODEX_ADAPTER, "CN", "zh-CN"), + (CODEX_ADAPTER, "EN", "en-US"), + (CLAUDE_ADAPTER, "CN", "zh-CN"), + (CLAUDE_ADAPTER, "EN", "en-US"), + ], + ids=["codex:zh-CN", "codex:en-US", "claude:zh-CN", "claude:en-US"], +) +def test_header_snapshot(adapter: HostAdapter, lang_dir: str, locale: str) -> None: + golden = _load_golden() + key = f"{adapter.host_name}:{locale}:header" + actual = _header_hash(adapter, lang_dir) + _assert_hash(key, actual, golden) + + +# -- Copilot managed block payload snapshots -- + +@pytest.mark.parametrize( + "lang_dir,locale", + [("CN", "zh-CN"), ("EN", "en-US")], + ids=["copilot:zh-CN", "copilot:en-US"], +) +def test_copilot_payload_snapshot(lang_dir: str, locale: str) -> None: + golden = _load_golden() + key = f"copilot:{locale}:managed_block_payload" + actual = _copilot_payload_hash(lang_dir) + _assert_hash(key, actual, golden) + + +# -- Skill tree snapshots -- + +@pytest.mark.parametrize( + "lang_dir,locale", + [("CN", "zh-CN"), ("EN", "en-US")], + ids=["skills:zh-CN", "skills:en-US"], +) +def test_skill_tree_snapshot(lang_dir: str, locale: str) -> None: + golden = _load_golden() + key = f"skills:{locale}:tree" + actual = _tree_hash(lang_dir) + _assert_hash(key, actual, golden) diff --git a/tests/test_release_hooks.py b/tests/test_release_hooks.py index 5ddedb9..7787f1b 100644 --- a/tests/test_release_hooks.py +++ b/tests/test_release_hooks.py @@ -145,11 +145,14 @@ def _init_release_hook_fixture(root: Path, *, inject_sync_failure: bool = False) ): _copy_script(relative, root) - # Copy skills/hosts.yaml (needed by sync-skills.sh -> render-host-skills.py). - # Skip when inject_sync_failure to make sync-skills.sh fail after - # release-sync has already modified README/CHANGELOG, testing rollback. - if not inject_sync_failure: - _copy_script("skills/hosts.yaml", root) + # Inject a post-update check failure to verify pre-commit rollback after + # release-sync has already modified README/CHANGELOG and source templates. + _copy_script("skills/hosts.yaml", root) + if inject_sync_failure: + _write( + root / "scripts/check-version-consistency.sh", + "#!/usr/bin/env bash\nexit 1\n", + ) old_version = "2026-03-20.183348" old_date = "2026-03-20" @@ -163,16 +166,6 @@ def _init_release_hook_fixture(root: Path, *, inject_sync_failure: bool = False) _write(root / "skills/zh/skills/sopify/SKILL.md", "# skill\n") _write(root / "skills/en/skills/sopify/SKILL.md", "# skill\n") - _write(root / "Codex/Skills/CN/AGENTS.md", _minimal_agents(old_version, claude=False, english=False)) - _write(root / "Codex/Skills/EN/AGENTS.md", _minimal_agents(old_version, claude=False, english=True)) - _write(root / "Codex/Skills/CN/skills/sopify/SKILL.md", "# skill\n") - _write(root / "Codex/Skills/EN/skills/sopify/SKILL.md", "# skill\n") - - _write(root / "Claude/Skills/CN/CLAUDE.md", _minimal_agents(old_version, claude=True, english=False)) - _write(root / "Claude/Skills/EN/CLAUDE.md", _minimal_agents(old_version, claude=True, english=True)) - _write(root / "Claude/Skills/CN/skills/sopify/SKILL.md", "# skill\n") - _write(root / "Claude/Skills/EN/skills/sopify/SKILL.md", "# skill\n") - _write(root / "runtime/gate.py", "print('baseline')\n") _write(root / "tests/test_runtime_gate.py", "print('baseline test')\n") @@ -355,8 +348,8 @@ def test_release_sync_auto_drafts_unreleased_before_version_bump(self) -> None: self.assertIn("**Tests**", release_body) self.assertNotIn("
", release_body) self.assertIn("badge/version-2026--03--21.010203-orange.svg", (root / "README.md").read_text(encoding="utf-8")) - self.assertIn("", (root / "Codex/Skills/CN/AGENTS.md").read_text(encoding="utf-8")) - self.assertIn("", (root / "Claude/Skills/CN/CLAUDE.md").read_text(encoding="utf-8")) + self.assertIn("", (root / "skills/zh/header.md.template").read_text(encoding="utf-8")) + self.assertIn("", (root / "skills/en/header.md.template").read_text(encoding="utf-8")) def test_release_draft_only_renders_non_empty_sections(self) -> None: with tempfile.TemporaryDirectory() as temp_dir: @@ -462,7 +455,7 @@ def test_pre_commit_restores_release_managed_files_when_release_sync_fails(self) original_readme = (root / "README.md").read_text(encoding="utf-8") original_changelog = (root / "CHANGELOG.md").read_text(encoding="utf-8") - original_agents = (root / "Codex/Skills/CN/AGENTS.md").read_text(encoding="utf-8") + original_template = (root / "skills/zh/header.md.template").read_text(encoding="utf-8") completed = subprocess.run( ["bash", str(root / ".githooks" / "pre-commit")], @@ -476,7 +469,7 @@ def test_pre_commit_restores_release_managed_files_when_release_sync_fails(self) self.assertNotEqual(completed.returncode, 0) self.assertEqual((root / "README.md").read_text(encoding="utf-8"), original_readme) self.assertEqual((root / "CHANGELOG.md").read_text(encoding="utf-8"), original_changelog) - self.assertEqual((root / "Codex/Skills/CN/AGENTS.md").read_text(encoding="utf-8"), original_agents) + self.assertEqual((root / "skills/zh/header.md.template").read_text(encoding="utf-8"), original_template) self.assertFalse((root / ".git" / ".sopify-release-sync-state").exists()) From f66f962345fc7d4f6e9292909cd19e0a9fa076d4 Mon Sep 17 00:00:00 2001 From: "sanze.li" <2522048902@qq.com> Date: Wed, 27 May 2026 16:14:50 +0800 Subject: [PATCH 2/3] refactor(T5): remove check-skills-sync.sh and clarify local-only script roles - Delete scripts/check-skills-sync.sh (superseded by golden snapshot tests) - CI: remove sync/diff/check-skills-sync steps from sync-and-version-guard - pre-commit: remove check-skills-sync from is_release_relevant - sync-skills.sh, render-host-skills.py: add 'local maintainer helper' notice - CONTRIBUTING: clarify Codex/Claude dirs are gitignored, manual-only - test fixture: remove check-skills-sync.sh reference --- .githooks/pre-commit | 2 +- .github/workflows/ci.yml | 9 --- CONTRIBUTING.md | 4 +- CONTRIBUTING_CN.md | 4 +- scripts/check-skills-sync.sh | 100 ---------------------------------- scripts/render-host-skills.py | 6 +- scripts/sync-skills.sh | 6 +- tests/test_release_hooks.py | 1 - 8 files changed, 13 insertions(+), 119 deletions(-) delete mode 100755 scripts/check-skills-sync.sh diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 7986511..71b8fcb 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -86,7 +86,7 @@ is_release_relevant_file() { runtime/*|installer/*|skills/*|README.md|README.zh-CN.md|CHANGELOG.md) return 0 ;; - scripts/sopify_runtime.py|scripts/model_compare_runtime.py|scripts/check-runtime-smoke.sh|scripts/release-sync.sh|scripts/release-preflight.sh|scripts/sync-skills.sh|scripts/check-skills-sync.sh|scripts/check-version-consistency.sh) + scripts/sopify_runtime.py|scripts/model_compare_runtime.py|scripts/check-runtime-smoke.sh|scripts/release-sync.sh|scripts/release-preflight.sh|scripts/sync-skills.sh|scripts/check-version-consistency.sh) return 0 ;; *) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 027ae24..a7c94be 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -13,15 +13,6 @@ jobs: with: fetch-depth: 0 - - name: Sync skills - run: bash scripts/sync-skills.sh - - - name: Ensure sync produced no changes - run: git diff --exit-code - - - name: Check skills sync - run: bash scripts/check-skills-sync.sh - - name: Check version consistency run: bash scripts/check-version-consistency.sh diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70fd1d5..aa2e813 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,7 +12,7 @@ Thanks for your interest in contributing to Sopify. ## Prompt-layer and Skill Authoring - `skills/{zh,en}` is the prompt-layer source of truth. Each language directory contains `header.md.template` (host-agnostic template) and `skills/sopify/` (skill packages). -- `Codex/Skills/{CN,EN}` and `Claude/Skills/{CN,EN}` are local generated caches rendered from `skills/` via `scripts/sync-skills.sh`; they are ignored by git. +- `Codex/Skills/{CN,EN}` and `Claude/Skills/{CN,EN}` are gitignored. They can be generated locally via `bash scripts/sync-skills.sh` for debugging or inspecting the traditional host layout, but are not part of release, CI, or pre-commit. - `runtime/builtin_skill_packages/*/skill.yaml` is the source of truth for builtin machine metadata. - For skill package changes, follow the `SKILL.md` files under [skills/zh/skills/sopify/](./skills/zh/skills/sopify/) / [skills/en/skills/sopify/](./skills/en/skills/sopify/). @@ -100,8 +100,6 @@ Run the minimum checks that match your change scope. Prompt-layer and metadata sync: ```bash -bash scripts/sync-skills.sh -bash scripts/check-skills-sync.sh bash scripts/check-version-consistency.sh python3 scripts/generate-builtin-catalog.py python3 -m pytest tests -v diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md index 7cd8e03..f7f3cab 100644 --- a/CONTRIBUTING_CN.md +++ b/CONTRIBUTING_CN.md @@ -12,7 +12,7 @@ ## Prompt 层与 Skill Authoring - `skills/{zh,en}` 是 prompt-layer 真源。每个语言目录包含 `header.md.template`（宿主无关模板）和 `skills/sopify/`（skill 包）。 -- `Codex/Skills/{CN,EN}` 和 `Claude/Skills/{CN,EN}` 是由 `scripts/sync-skills.sh` 从 `skills/` 渲染出的本地缓存，已被 git 忽略。 +- `Codex/Skills/{CN,EN}` 和 `Claude/Skills/{CN,EN}` 已被 git 忽略。可通过 `bash scripts/sync-skills.sh` 本地生成，用于调试或查看传统宿主目录结构，但不参与发版、CI 或 pre-commit。 - `runtime/builtin_skill_packages/*/skill.yaml` 是 builtin machine metadata 真源。 - Skill package 变更时，参考 [skills/zh/skills/sopify/](./skills/zh/skills/sopify/) / [skills/en/skills/sopify/](./skills/en/skills/sopify/) 下各自的 `SKILL.md`。 @@ -106,8 +106,6 @@ python3 scripts/render-release-installers.py --release-tag "$TAG" --output-dir " Prompt 层与 metadata 同步： ```bash -bash scripts/sync-skills.sh -bash scripts/check-skills-sync.sh bash scripts/check-version-consistency.sh python3 scripts/generate-builtin-catalog.py python3 -m pytest tests -v diff --git a/scripts/check-skills-sync.sh b/scripts/check-skills-sync.sh deleted file mode 100755 index a880f78..0000000 --- a/scripts/check-skills-sync.sh +++ /dev/null @@ -1,100 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -TMP_DIR="$(mktemp -d "${TMPDIR:-/tmp}/sopify-sync-check.XXXXXX")" -trap 'rm -rf "$TMP_DIR"' EXIT - -usage() { - cat <<'EOF' -Usage: scripts/check-skills-sync.sh - -Check whether host distribution files (Codex/*, Claude/*) match the -rendered output from skills/ source of truth. -On mismatch, run: - bash scripts/sync-skills.sh -EOF -} - -if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then - usage - exit 0 -fi - -RENDER_SCRIPT="$ROOT_DIR/scripts/render-host-skills.py" -HOSTS_FILE="$ROOT_DIR/skills/hosts.yaml" -status=0 - -dist_lang_dir() { - case "$1" in - zh) echo "CN" ;; en) echo "EN" ;; - *) echo "Unknown source lang: $1" >&2; exit 1 ;; - esac -} -host_top_dir() { - case "$1" in - codex) echo "Codex" ;; claude) echo "Claude" ;; - *) echo "Unknown host: $1" >&2; exit 1 ;; - esac -} -host_header_file() { - case "$1" in - codex) echo "AGENTS.md" ;; claude) echo "CLAUDE.md" ;; - *) echo "Unknown host: $1" >&2; exit 1 ;; - esac -} - -check_host_lang() { - local host_id="$1" - local src_lang="$2" - local dist_lang - local host_dir - local header_file - local skills_source - local dist_dir - local label - local diff_file - local expected_header - - dist_lang="$(dist_lang_dir "$src_lang")" - host_dir="$(host_top_dir "$host_id")" - header_file="$(host_header_file "$host_id")" - skills_source="$ROOT_DIR/skills/$src_lang/skills/sopify" - dist_dir="$ROOT_DIR/$host_dir/Skills/$dist_lang" - label="$host_id:$src_lang ($dist_lang)" - diff_file="$TMP_DIR/${host_id}_${src_lang}.diff" - expected_header="$TMP_DIR/${host_id}_${src_lang}.expected.md" - - python3 "$RENDER_SCRIPT" \ - --hosts-file "$HOSTS_FILE" \ - --skills-root "$ROOT_DIR/skills" \ - --lang "$src_lang" \ - --host "$host_id" \ - --output "$expected_header" - - if ! diff -u "$expected_header" "$dist_dir/$header_file" >"$diff_file" 2>&1; then - echo "[$label] Header mismatch: $host_dir/Skills/$dist_lang/$header_file" - head -n 40 "$diff_file" - status=1 - fi - - if ! diff -ru -x .DS_Store -x Thumbs.db "$skills_source" "$dist_dir/skills/sopify" >"$diff_file" 2>&1; then - echo "[$label] Skill directory mismatch" - head -n 60 "$diff_file" - status=1 - fi -} - -for host_id in codex claude; do - for src_lang in zh en; do - check_host_lang "$host_id" "$src_lang" - done -done - -if [[ "$status" -ne 0 ]]; then - echo - echo "Sync check failed. Run: bash scripts/sync-skills.sh" - exit 1 -fi - -echo "Sync check passed: all distribution files match skills/ source." diff --git a/scripts/render-host-skills.py b/scripts/render-host-skills.py index 46a5f37..56bb459 100644 --- a/scripts/render-host-skills.py +++ b/scripts/render-host-skills.py @@ -1,6 +1,10 @@ #!/usr/bin/env python3 """Render host-specific headers from header.md.template + hosts.yaml. +Local maintainer helper — NOT part of release / CI / pre-commit pipeline. +Used by sync-skills.sh to generate gitignored Codex/Skills/ and Claude/Skills/ +local cache directories. + Usage: python3 scripts/render-host-skills.py --hosts-file skills/hosts.yaml --lang en --host claude python3 scripts/render-host-skills.py --hosts-file skills/hosts.yaml --lang en --host claude --output /tmp/CLAUDE.md @@ -11,7 +15,7 @@ --verify-all renders all host:lang header combos and prints their sha256. Note: this only covers header rendering, not full install-product hashes. -Full install-product verification is in T6 (golden snapshot comparison). +Full install-product verification is in tests/test_golden_snapshots.py. No external dependencies — stdlib only. """ diff --git a/scripts/sync-skills.sh b/scripts/sync-skills.sh index 1a1295b..92081cd 100755 --- a/scripts/sync-skills.sh +++ b/scripts/sync-skills.sh @@ -7,7 +7,11 @@ usage() { cat <<'EOF' Usage: scripts/sync-skills.sh -Render host distribution files from skills/ source of truth: +Local maintainer cache helper — NOT part of release / CI / pre-commit pipeline. +Generates Codex/Skills/ and Claude/Skills/ directories (gitignored) from the +skills/ source of truth so maintainers can inspect the traditional host layout. + +Rendered output: - skills/zh/header.md.template -> Codex/Skills/CN/AGENTS.md (with codex vars) - skills/zh/header.md.template -> Claude/Skills/CN/CLAUDE.md (with claude vars) - skills/en/header.md.template -> Codex/Skills/EN/AGENTS.md (with codex vars) diff --git a/tests/test_release_hooks.py b/tests/test_release_hooks.py index 7787f1b..3218d0a 100644 --- a/tests/test_release_hooks.py +++ b/tests/test_release_hooks.py @@ -137,7 +137,6 @@ def _init_release_hook_fixture(root: Path, *, inject_sync_failure: bool = False) "scripts/release-preflight.sh", "scripts/check-context-checkpoints.py", "scripts/sync-skills.sh", - "scripts/check-skills-sync.sh", "scripts/check-version-consistency.sh", "scripts/render-host-skills.py", ".githooks/pre-commit", From bd045004edc389d11b8a6c85321c55deac973f9b Mon Sep 17 00:00:00 2001 From: "sanze.li" <2522048902@qq.com> Date: Wed, 27 May 2026 16:24:45 +0800 Subject: [PATCH 3/3] chore(T7): remove last tracked Copilot distribution file - git rm Copilot/Skills/CN/COPILOT.md - .gitignore: add Copilot/Skills/ --- .gitignore | 1 + Copilot/Skills/CN/COPILOT.md | 251 ----------------------------------- 2 files changed, 1 insertion(+), 251 deletions(-) delete mode 100644 Copilot/Skills/CN/COPILOT.md diff --git a/.gitignore b/.gitignore index a22c74c..0a80ba3 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,4 @@ evals/skill_eval_report.json # Generated host prompt distributions. Source of truth is skills/{zh,en}. Codex/Skills/ Claude/Skills/ +Copilot/Skills/ diff --git a/Copilot/Skills/CN/COPILOT.md b/Copilot/Skills/CN/COPILOT.md deleted file mode 100644 index 1fbc471..0000000 --- a/Copilot/Skills/CN/COPILOT.md +++ /dev/null @@ -1,251 +0,0 @@ - - - - -# Sopify - 自适应 AI 编程助手 (Copilot 接入) - -## 角色定义 - -**你是 Sopify** - 一个自适应的 AI 编程伙伴。根据用户请求、当前项目状态选择合适工作流，追求高效与质量的平衡。 - -**核心理念：** -- **中断可恢复**：工作可在任意时间点中断，下次回来可以无缝继续 -- **决策前停车**：重要拍板时会主动停下等你确认，不会自行推进 -- **自适应工作流**：按项目上下文选路，简单任务直接执行，复杂任务完整规划 -- **一屏可见**：输出精简，详情在文件里 - -**宿主定位**：Copilot CLI 是 `payload_capable + CONTINUATION` 宿主，不运行 Sopify runtime。通过读取冻结 contract 文件理解上下文并接续工作。 - ---- - -## Core Rules (核心规则) - -### C1 | 配置加载与品牌 - -**启动时执行：** -```yaml -1. 配置加载优先级: 项目根 (./sopify.config.yaml) > 内置默认值 -2. 默认不自动创建配置文件 -3. 合并默认配置并设置运行时变量 -``` - -**品牌名获取 (当 brand: auto，默认由项目名生成)：** -``` -项目名优先级: git remote 仓库名 > package.json name > 目录名 > "project" -品牌格式: {project_name}-ai -示例: my-app (项目名) → my-app-ai (品牌名) -``` - -**默认配置：** -```yaml -brand: auto -language: zh-CN -output_style: minimal -workflow.mode: adaptive -plan.directory: .sopify-skills -``` - -### C2 | 输出格式 - -**统一输出模板：** -``` -[{BRAND_NAME}] {阶段名} {状态符} - -{核心信息, 最多3行} - ---- -Changes: {N} files - - {file1} - - {file2} - -Next: {下一步提示} -``` - -**状态符：** -| 符号 | 含义 | -|-----|------| -| `✓` | 成功完成 | -| `?` | 等待输入 | -| `!` | 警告/需确认 | -| `×` | 取消/错误 | - -**阶段名：** -- 需求分析、方案设计、开发实施 -- 快速修复、轻量迭代 -- 咨询问答 - -**输出原则：** -- 核心信息一屏可见 -- 详细内容写入文件 -- 避免冗余描述 - -### C3 | 接续增强 (CONTINUATION) - -**每次会话开始时，检查接续状态：** - -1. 读取 `.sopify-skills/state/current_handoff.json` -2. 若 handoff 存在且非空： - - 消费 `required_host_action` 判定下一步行为 - - 消费 `artifacts` 获取上次产出 - - 结合 `.sopify-skills/plan/` 目录了解活跃方案 - - 向用户展示接续摘要 - -**`required_host_action` 值域与行为：** - -| 值 | 行为 | -|---|------| -| `answer_questions` | 读 `current_clarification.json`，展示 `missing_facts` / `questions`，等待用户补充 | -| `confirm_decision` | 读 `current_handoff.json.artifacts.decision_checkpoint`，展示 `question` / `options` / `recommended_option_id`，等待用户确认 | -| `continue_host_develop` | 接续代码修改，按活跃 plan 继续下一步任务 | -| `continue_host_consult` | 继续问答 | - -**入口语义（三种使用场景）：** - -| 场景 | 条件 | 行为 | -|------|------|------| -| 查看进度 (Inspect) | 有活跃 handoff，用户未明确说"继续" | 展示当前状态摘要，不执行 | -| 接续工作 (Continue) | 有活跃 handoff，用户要求继续 | 按 `required_host_action` 接续 | -| 开新任务 (Start New) | 用户说"开新任务" | 若有活跃 handoff → 提示"当前有进行中的工作，确认要开新任务吗？"；否则正常开始 | - -**禁止消费的面：** -- ❌ 不读 `state/last_route.json`（forbidden surface） -- ❌ 不依赖 route_name 语义做路由决策 -- ❌ 不把 `current_gate_receipt.json` 当作当前轮次的授权依据（仅可作为上一轮的审计历史查看） - -### C4 | 工作流模式 - -**模式定义：** - -| 模式 | 行为 | -|-----|------| -| `adaptive` | 根据复杂度自动选择 (默认) | -| `minimal` | 跳过规划，直接执行 | - -**adaptive 模式判定：** -```yaml -简单任务 (直接执行): - - 文件数 ≤ 2 - - 需求明确 - - 无架构变更 - -中等任务 (light 方案包): - - 文件数 3-5 - - 需求清晰 - - 局部修改 - -复杂任务 (完整 3 阶段): - - 文件数 > 5 - - 或 架构变更 - - 或 新功能开发 -``` - ---- - -## Auto Rules (自动规则) - -> 以下规则由 AI 自动处理，用户无需关心。 - -### A1 | 编码处理 - -```yaml -读取: 自动检测文件编码 -写入: 统一 UTF-8 -传递: 保持原编码不变 -``` - -### A2 | 复杂度判定 - -```yaml -简单: 文件数 ≤ 2, 单模块, 无架构变更 -中等: 文件数 3-5, 跨模块, 局部重构 -复杂: 文件数 > 5, 架构变更, 新功能 -``` - -### A3 | 方案包分级 - -| 级别 | 结构 | 触发条件 | -|-----|------|---------| -| light | `plan.md` 单文件 | 中等任务 | -| standard | `background.md` + `design.md` + `tasks.md` | 复杂任务 | -| full | 标准 + `adr/` + `diagrams/` | 架构级变更 | - -**目录结构：** -``` -.sopify-skills/ -├── blueprint/ # 项目级长期蓝图 -│ ├── README.md -│ ├── background.md -│ ├── design.md -│ └── tasks.md -├── plan/ # 当前方案 -│ └── YYYYMMDD_feature/ -├── history/ # 已完成方案归档 -├── state/ # 运行态状态（读取用，不写入） -│ ├── current_handoff.json -│ ├── current_gate_receipt.json -│ ├── current_clarification.json -│ └── current_decision.json -├── user/ # 用户偏好与反馈 -│ ├── preferences.md -│ └── feedback.jsonl -├── project.md # 技术约定 -``` - -### A4 | 生命周期管理 - -```yaml -首次触发: 至少创建 .sopify-skills/blueprint/README.md -方案创建: .sopify-skills/plan/YYYYMMDD_feature_name/ -任务收口: 刷新 blueprint, 归档到 history/ -``` - ---- - -## 阶段执行 - -### P1 | 需求分析 - -**目标：** 验证需求完整性，分析代码现状 - -**执行流程：** -``` -1. 检查接续状态（是否有 handoff） -2. 获取项目上下文（读 blueprint） -3. 需求评分 (10分制) -4. 评分 ≥ 7 → 继续；否则追问 -``` - -### P2 | 方案设计 - -**目标：** 设计技术方案，拆分任务 - -**执行流程：** -``` -1. 确定方案包级别 (light/standard/full) -2. 生成方案文件 -3. 输出摘要 -``` - -### P3 | 开发实施 - -**目标：** 执行任务，同步知识库 - -**执行流程：** -``` -1. 按 tasks.md 顺序执行 -2. 更新知识库 -3. 归档方案至 history/ -4. 输出结果 -``` - ---- - -## 快速参考 - -**配置文件：** `sopify.config.yaml` (项目根目录) - -**知识库目录：** `.sopify-skills/` - -**方案包路径：** `.sopify-skills/plan/YYYYMMDD_feature_name/` - -**接续入口：** 每次会话自动检查 `current_handoff.json`，按 `required_host_action` 判定行为。