@ai-content-space/loopx 0.1.9 → 0.2.0

package/skills/review/SKILL.md

@@ -1,139 +1,106 @@
 ---
 name: review
-description: "Reviews a loopx build execution record for acceptance, code risks, evidence quality, and architecture smells. Not for doing implementation work or replanning."
-when_to_use: "review, code review, acceptance, go no-go, execution-record, architecture smell, build complete, 审查, 验收"
+description: "Dispatches a loopx code reviewer subagent against a concrete git range and requirements. Not for implementation, planning, or unresolved review scope."
+when_to_use: "request code review, completed task review, major feature review, pre-merge review, subagent code quality check"
 metadata:
-  version: "0.1.9"
-argument-hint: "<execution-record path or workflow slug>"
+  version: "0.2.0"
 ---
 
-# loopx Review
+# Review
 
-## Purpose
+Dispatch a code reviewer subagent to catch issues before they cascade. The reviewer gets precisely crafted context for evaluation — never your session's history. This keeps the reviewer focused on the work product, not your thought process, and preserves your own context for continued work.
 
-Repo-local acceptance surface for loopx. Use it to evaluate the execution package from `build` and return an explicit go / no-go result.
+**Core principle:** Review early, review often.
 
-## Inputs
+## When to Request Review
 
-Preferred skill input:
+**Mandatory:**
+- After each task in subagent-exec
+- After completing major feature
+- Before merge to main
 
-- `.loopx/workflows/<slug>/execution-record.md`
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
 
-Compatible skill / CLI input:
+## How to Request
 
-- `<slug>`
-
-When invoked with an execution record path, derive `<slug>` from the workflow directory and evaluate the matching active run.
-
-When present, use `.loopx/config.json` as supporting context for project-native verification commands, existing AI rule files, and existing spec sources. Do not treat those external or pre-existing sources as replacements for the loopx execution record and review artifact.
-
-## Expected Outputs
-
-- a review artifact tied to the run being evaluated
-- verdict and rationale
-- code review findings for the implementation diff, including file / line references when issues are found
-- architecture-smell findings from the internal review lane, focused on module depth, test seams, domain vocabulary, duplicated rules, and plan architecture alignment
-- rollback/fix guidance when execution is incomplete, unstable, or needs another iteration
-- an explicit `Next:` block with the exact next skill command when more work remains
-
-## User Notification Language
-
-The final user-facing review result must be written in Chinese.
-
-Use stable machine values only where they are commands, file paths, JSON/state fields, or exact verdict identifiers. The human-readable summary, rationale, findings, residual risks, rollback guidance, and next-step instruction must be Chinese.
-
-## Decision Boundary
-
-- Use this only after build has produced execution and verification evidence for a specific run.
-- Stop here if review evidence is incomplete. `review` remains an independent gate and does not auto-complete the workflow.
-- Review must include code review of the build-owned implementation diff. Do not limit review to artifact/schema checks.
-- Review should compare verification evidence against project-native commands recorded in `.loopx/config.json` when available, while still accepting stronger task-specific verification from the approved plan.
-- Review must include the architecture-smell lane as part of review evidence. This is not a new workflow stage and must not create extra user steps.
-- Review must compare the execution scope against the approved workflow scope. If `execution-record.md` declares non-empty `remaining_scope`, `completion_claim` other than `full`, or a mismatch between `planned_scope` and `implemented_scope`, review must return no-go and route to build or plan. A partial slice may be accepted as useful work, but it must not be approved as full workflow completion.
-- Review must compare implementation evidence against the original source requirements and `.loopx/workflows/<slug>/requirement-traceability.md`, not only against the generated plan. If the traceability matrix is missing, partial, or contradicted by code/tests, route to `review -> plan` or `review -> clarify` depending on whether the plan or requirements are wrong.
-- Code review findings should focus on real bugs, regressions, missing tests, broken contracts, security/data-integrity risks, and user-visible behavior gaps.
-- If code review finds blocking high or medium severity issues, return a no-go verdict and rollback guidance instead of approving completion.
-- If architecture-smell findings are only advisory, record them as warnings without blocking. Block only when module seams, testability, domain boundaries, duplicated rules, or plan architecture assumptions are materially wrong.
-- Route request-changes by problem type:
-  - implementation bugs, missing tests, small contract fixes: `review -> build`
-  - wrong plan, wrong architecture, unresolved execution inputs: `review -> plan`
-  - unclear product requirements or decision boundaries: `review -> clarify`
-- Do not route implementation-only fixes back to plan unless the plan itself is wrong.
-
-## Next Step Format
-
-Every no-go review result must end with a concrete next command block.
-
-For implementation fixes:
-
-Default implementation-fix handoff:
-
-```text
-Next:
-$build --from-review .loopx/workflows/<slug>/review-report.md
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
 ```
 
-The review artifact is the direct rework contract for implementation fixes. `$build --from-review ...` must load the review findings first, while still using the approved PRD, test spec, previous `execution-record.md`, and workflow-local plan package as supporting context. Do not make the normal Codex-facing handoff require a separate bash `loopx approve ... --from review --to build` step.
+**2. Dispatch code reviewer subagent:**
 
-For CLI/runtime debugging only, the equivalent state transition is:
+Use the platform's native subagent mechanism when available and fill template at `code-reviewer.md`.
 
-```bash
-loopx build --from-review .loopx/workflows/<slug>/review-report.md
-```
+**Placeholders:**
+- `{DESCRIPTION}` - Brief summary of what you built
+- `{PLAN_OR_REQUIREMENTS}` - What it should do
+- `{BASE_SHA}` - Starting commit
+- `{HEAD_SHA}` - Ending commit
 
-For plan fixes:
+**3. Act on feedback:**
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
 
-```text
-Next:
-loopx approve <slug> --from review --to plan
-$plan <slug>
-```
-
-For clarify fixes:
+## Example
 
-```text
-Next:
-loopx approve <slug> --from review --to clarify
-$clarify <slug>
 ```
+[Just completed Task 2: Add verification function]
 
-For approval:
+You: Let me request code review before proceeding.
 
-```text
-Next:
-$archive <slug>
-```
+BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}')
+HEAD_SHA=$(git rev-parse HEAD)
 
-`$archive` consumes the pending `review -> done` completion transition before syncing specs. Do not ask the user to run a separate `loopx approve <slug> --from review --to done` command in the normal Codex-facing flow.
+[Dispatch code reviewer subagent]
+  DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types
+  PLAN_OR_REQUIREMENTS: Task 2 from docs/loopx/plans/deployment-plan.md
+  BASE_SHA: a7981ec
+  HEAD_SHA: 3df7661
 
-For CLI/runtime debugging only, the equivalent explicit sequence is:
+[Subagent returns]:
+  Strengths: Clean architecture, real tests
+  Issues:
+    Important: Missing progress indicators
+    Minor: Magic number (100) for reporting interval
+  Assessment: Ready to proceed
 
-```bash
-loopx approve <slug> --from review --to done
-loopx archive <slug>
+You: [Fix progress indicators]
+[Continue to Task 3]
 ```
 
-This syncs the approved `.loopx/changes/active/<change-id>/spec-delta.md` into long-lived `.loopx/specs/` files and moves the change folder under `.loopx/changes/archive/<change-id>/`.
-
-## Support Skill Review Lenses
+## Integration with Workflows
 
-Use loopx support skills as review lenses, not as implementation instructions:
+**Subagent Exec:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
 
-- `verify`: Evidence lens. Reject completion, passing, or review-ready claims that lack fresh command output and exit status.
-- `scope`: Completion lens. Reject full-completion claims when the execution record still declares remaining workflow scope or only a partial slice was implemented.
-- `tdd`: Behavior-change lens. Feature work and bug fixes should include failing-test or regression-test evidence unless the execution record explicitly explains why tests are not applicable.
-- `debug`: Failure-analysis lens. Fixes for bugs, test failures, build failures, and unexpected behavior should document root cause, not only symptoms or attempted patches.
-- `go-style`: Go diff lens. For `.go` changes, review happy-path structure, error handling, context usage, interface boundaries, naming, table tests, and `gofmt`/Go verification evidence.
-- `kratos`: Kratos diff lens. For Kratos/proto/service/biz/data/middleware/auth/config changes, review layer boundaries, generated-code flow, proto/package contracts, middleware/auth ordering, config compatibility, and project-native verification.
+**Exec:**
+- Review after each task or at natural checkpoints
+- Get feedback, apply, continue
 
-These lenses can produce review findings when the execution package violates them. Do not run new build work from `review`; request rollback or changes instead.
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
 
-## Must Not Decide Automatically
+## Red Flags
 
-- final completion without an explicit approval step
-- re-running build work inside the review surface
-- editing code or rerunning build from inside review
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
 
-## Notes
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification
 
-- Review consumes structured outputs from the active loopx run. It should reject thin or placeholder-only evidence.
+See template at: review/code-reviewer.md

package/skills/review/code-reviewer.md

@@ -0,0 +1,168 @@
+# Code Reviewer Prompt Template
+
+Use this template when dispatching a code reviewer subagent.
+
+**Purpose:** Review completed work against requirements and code quality standards before it cascades into more work.
+
+```
+Native subagent:
+  description: "Review code changes"
+  prompt: |
+    You are a Senior Code Reviewer with expertise in software architecture,
+    design patterns, and best practices. Your job is to review completed work
+    against its plan or requirements and identify issues before they cascade.
+
+    ## What Was Implemented
+
+    {DESCRIPTION}
+
+    ## Requirements / Plan
+
+    {PLAN_OR_REQUIREMENTS}
+
+    ## Git Range to Review
+
+    **Base:** {BASE_SHA}
+    **Head:** {HEAD_SHA}
+
+    ```bash
+    git diff --stat {BASE_SHA}..{HEAD_SHA}
+    git diff {BASE_SHA}..{HEAD_SHA}
+    ```
+
+    ## What to Check
+
+    **Plan alignment:**
+    - Does the implementation match the plan / requirements?
+    - Are deviations justified improvements, or problematic departures?
+    - Is all planned functionality present?
+
+    **Code quality:**
+    - Clean separation of concerns?
+    - Proper error handling?
+    - Type safety where applicable?
+    - DRY without premature abstraction?
+    - Edge cases handled?
+
+    **Architecture:**
+    - Sound design decisions?
+    - Reasonable scalability and performance?
+    - Security concerns?
+    - Integrates cleanly with surrounding code?
+
+    **Testing:**
+    - Tests verify real behavior, not mocks?
+    - Edge cases covered?
+    - Integration tests where they matter?
+    - All tests passing?
+
+    **Production readiness:**
+    - Migration strategy if schema changed?
+    - Backward compatibility considered?
+    - Documentation complete?
+    - No obvious bugs?
+
+    ## Calibration
+
+    Categorize issues by actual severity. Not everything is Critical.
+    Acknowledge what was done well before listing issues — accurate praise
+    helps the implementer trust the rest of the feedback.
+
+    If you find significant deviations from the plan, flag them specifically
+    so the implementer can confirm whether the deviation was intentional.
+    If you find issues with the plan itself rather than the implementation,
+    say so.
+
+    ## Output Format
+
+    ### Strengths
+    [What's well done? Be specific.]
+
+    ### Issues
+
+    #### Critical (Must Fix)
+    [Bugs, security issues, data loss risks, broken functionality]
+
+    #### Important (Should Fix)
+    [Architecture problems, missing features, poor error handling, test gaps]
+
+    #### Minor (Nice to Have)
+    [Code style, optimization opportunities, documentation polish]
+
+    For each issue:
+    - File:line reference
+    - What's wrong
+    - Why it matters
+    - How to fix (if not obvious)
+
+    ### Recommendations
+    [Improvements for code quality, architecture, or process]
+
+    ### Assessment
+
+    **Ready to merge?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence technical assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Categorize by actual severity
+    - Be specific (file:line, not vague)
+    - Explain WHY each issue matters
+    - Acknowledge strengths
+    - Give a clear verdict
+
+    **DON'T:**
+    - Say "looks good" without checking
+    - Mark nitpicks as Critical
+    - Give feedback on code you didn't actually read
+    - Be vague ("improve error handling")
+    - Avoid giving a clear verdict
+```
+
+**Placeholders:**
+- `{DESCRIPTION}` — brief summary of what was built
+- `{PLAN_OR_REQUIREMENTS}` — what it should do (plan file path, task text, or requirements)
+- `{BASE_SHA}` — starting commit
+- `{HEAD_SHA}` — ending commit
+
+**Reviewer returns:** Strengths, Issues (Critical / Important / Minor), Recommendations, Assessment
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42)
+- Comprehensive test coverage (18 tests, all edge cases)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+1. **Missing help text in CLI wrapper**
+   - File: index-conversations:1-31
+   - Issue: No --help flag, users won't discover --concurrency
+   - Fix: Add --help case with usage examples
+
+2. **Date validation missing**
+   - File: search.ts:25-27
+   - Issue: Invalid dates silently return no results
+   - Fix: Validate ISO format, throw error with example
+
+#### Minor
+1. **Progress indicators**
+   - File: indexer.ts:130
+   - Issue: No "X of Y" counter for long operations
+   - Impact: Users don't know how long to wait
+
+### Recommendations
+- Add progress reporting for user experience
+- Consider config file for excluded projects (portability)
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. Important issues (help text, date validation) are easily fixed and don't affect core functionality.
+```

package/skills/spec/DESIGN_SPEC_TEMPLATE.md

@@ -0,0 +1,323 @@
+# <项目/功能>设计文档
+
+> 模板用途：用于需求已澄清后的软件设计方案、概要设计、详细设计和评审材料。保持章节顺序；不适用的章节写“无/不涉及”并说明原因。
+
+## 一、修订历史
+
+| 版本号 | 修订内容 | 修订时间 | 修订人 |
+|---|---|---|---|
+| V1.0.0 | 新建初稿 | YYYY-MM-DD | <姓名> |
+
+## 二、需求信息
+
+### 2.1 需求背景
+
+- 背景：
+- 需求目的：
+- 目标用户/使用方：
+- 需求链接：
+- 关联原始材料：
+
+### 2.2 需求范围
+
+- 本期范围：
+- 非目标：
+- 决策边界：
+- 依赖方：
+- 约束条件：
+
+### 2.3 可行性分析
+
+- 业务可行性：
+- 技术可行性：
+- 团队接受能力：
+- 时间成本：
+- 资源成本：
+- 替代方案：
+- 关键风险：
+
+## 三、概要设计
+
+### 3.1 方案总述
+
+- 设计目标：
+- 总体思路：
+- 核心模块：
+- 主要难点：
+- 技术指标：
+
+### 3.2 整体架构设计
+
+- 业务模式：
+- 系统边界：
+- 上下游系统：
+- 应用架构：
+- 技术架构：
+- 数据流转：
+
+### 3.3 核心流程设计
+
+按核心业务流程描述触发方、参与系统、关键状态、数据变化和异常分支。
+
+| 流程 | 触发条件 | 参与系统/模块 | 主流程 | 异常/补偿 | 输出 |
+|---|---|---|---|---|---|
+| <流程名> | <条件> | <模块> | <步骤> | <处理> | <结果> |
+
+### 3.4 功能模块
+
+| 模块 | 职责 | 关键功能 | 依赖 | 备注 |
+|---|---|---|---|---|
+| <模块名> | <职责> | <功能> | <依赖> | <备注> |
+
+### 3.5 新增/调整功能说明
+
+按端、系统或业务域拆分，例如 H5、后台、开放接口、清结算、资金资产、权限等。
+
+## 四、详细设计
+
+> 每个模块使用同一结构展开；复杂模块可继续拆到 4.x.x。
+
+### 4.x <模块/领域>详细设计
+
+#### 4.x.1 需求内容
+
+- 入口：
+- 操作人/调用方：
+- 前置条件：
+- 输出结果：
+
+#### 4.x.2 方案设计
+
+- 核心逻辑：
+- 状态流转：
+- 数据变更：
+- 计算公式：
+- 幂等设计：
+- 权限/越权控制：
+- 异常处理：
+- 补偿/重试：
+- 日志与审计：
+
+#### 4.x.3 流程步骤
+
+1. <步骤>
+2. <步骤>
+3. <步骤>
+
+#### 4.x.4 边界条件
+
+| 场景 | 处理方式 | 用户/调用方感知 | 监控/告警 |
+|---|---|---|---|
+| <场景> | <处理> | <感知> | <告警> |
+
+## 五、存储类设计
+
+### 5.1 库表设计
+
+#### 5.1.1 数据库模型图
+
+说明核心实体关系；如使用图，请附图或 Mermaid。
+
+#### 5.1.2 表结构
+
+| 表名 | 用途 | 主键 | 关键索引 | 数据量预估 | 备注 |
+|---|---|---|---|---|---|
+| <table> | <用途> | <pk> | <idx> | <规模> | <备注> |
+
+字段明细：
+
+| 字段 | 类型 | 是否必填 | 默认值 | 含义 | 来源/取值逻辑 | 备注 |
+|---|---|---|---|---|---|---|
+| <field> | <type> | 是/否 | <default> | <含义> | <逻辑> | <备注> |
+
+### 5.2 数据迁移/初始化
+
+- DDL：
+- DML：
+- 数据回填：
+- 老数据兼容：
+- 新老系统读写关系：
+
+### 5.3 缓存设计
+
+| 场景 | Key | Value | 数据结构 | 过期时长 | 容量预估 | 失效/刷新策略 |
+|---|---|---|---|---|---|---|
+| <场景> | <key> | <value> | <结构> | <TTL> | <容量> | <策略> |
+
+## 六、其他组件设计
+
+### 6.1 消息设计
+
+| 场景 | Group | Topic | 生产者 | 消费者 | 幂等键 | 失败补偿 |
+|---|---|---|---|---|---|---|
+| <场景> | <group> | <topic> | <producer> | <consumer> | <key> | <补偿> |
+
+### 6.2 配置设计
+
+| 配置项 | 环境 | 默认值 | 是否动态生效 | 说明 | 风险 |
+|---|---|---|---|---|---|
+| <config> | <env> | <value> | 是/否 | <说明> | <风险> |
+
+### 6.3 定时任务/批处理
+
+| 任务 | 触发时间 | 处理范围 | 幂等 | 失败重试 | 影响评估 |
+|---|---|---|---|---|---|
+| <job> | <cron> | <范围> | <方式> | <策略> | <影响> |
+
+### 6.4 技术组件
+
+- 分布式锁：
+- 唯一 ID：
+- 加解密/验签：
+- 字典转换：
+- Excel/文件处理：
+- 用户信息透传：
+- 限流/熔断：
+
+## 七、接口设计
+
+### 7.1 接口设计原则
+
+- 接口和字段注释必须完整，明确必填、非必填、默认值和枚举。
+- 非纯查询接口必须说明幂等策略。
+- 异常码、异常文案和抛出条件必须明确。
+- 重要接口必须说明日志、链路字段、性能、限流、熔断和数据流水。
+- 如接口文档在 YApi/OpenAPI/Apifox 等平台维护，必须给出链接。
+
+### 7.2 接口清单
+
+| 接口 | 调用方 | 服务方 | 权限/认证 | 幂等 | 文档地址 | 备注 |
+|---|---|---|---|---|---|---|
+| <接口名> | <caller> | <provider> | <auth> | <key> | <url> | <备注> |
+
+### 7.3 接口明细
+
+#### 7.3.x <接口名>
+
+- 路径/方法：
+- 请求头：
+- 请求参数：
+- 响应参数：
+- 错误码：
+- 业务校验：
+- 数据变更：
+- 日志字段：
+
+## 八、系统发布
+
+### 8.1 灰度方案
+
+- 灰度范围：
+- 灰度开关：
+- 验证指标：
+- 放量节奏：
+
+### 8.2 降级方案
+
+- 降级触发条件：
+- 降级行为：
+- 用户影响：
+- 恢复方式：
+
+### 8.3 关联系统/功能影响
+
+| 系统/功能 | 影响 | 依赖动作 | 负责人 | 验证方式 |
+|---|---|---|---|---|
+| <系统> | <影响> | <动作> | <负责人> | <验证> |
+
+### 8.4 回滚方案
+
+- 回滚条件：
+- 回滚步骤：
+- 数据回滚：
+- 配置回滚：
+- 风险：
+
+## 九、系统监控与维护
+
+### 9.1 监控与告警
+
+- 系统异常：
+- 业务异常：
+- 重试异常：
+- 超时：
+- 关键接口指标：
+- 告警渠道：
+
+### 9.2 性能与容量
+
+- TPS/吞吐：
+- CPU/内存/磁盘 IO/网络 IO：
+- 数据容量：
+- 缓存容量：
+- 跑批耗时：
+- 是否压测：
+
+### 9.3 可靠性与兜底
+
+- 幂等击穿：
+- 并发失效：
+- 冷热备：
+- 关键任务独立性：
+- 字段兜底：
+- 老新数据兼容：
+
+## 十、排期与规划
+
+### 10.1 任务拆分与工作量评估
+
+| 任务 | 范围 | 负责人 | 工作量 | 依赖 | 备注 |
+|---|---|---|---|---|---|
+| <任务> | <范围> | <负责人> | <人天> | <依赖> | <备注> |
+
+### 10.2 计划时间
+
+- 数据方案评审：
+- 开发开始/结束：
+- CR：
+- 联调完成/提测：
+- 测试用例评审：
+- 测试开始/结束：
+- 预发布：
+- 上线：
+- 线上验证：
+
+### 10.3 发布计划
+
+1. 需求纳入发布版本
+2. 测试环境申请与部署
+3. 代码 CR
+4. 发布评审 checklist
+5. 预发布/灰度/线上环境部署
+6. 稳定观察
+
+### 10.4 遗留问题与后续规划
+
+| 问题 | 影响 | 处理计划 | 负责人 | 截止时间 |
+|---|---|---|---|---|
+| <问题> | <影响> | <计划> | <负责人> | <时间> |
+
+### 10.5 Planning Handoff
+
+- `plan` 可以决定：
+- 必须返回 `spec` 的事项：
+- 必须返回 `clarify` 的事项：
+- 推荐下一步：
+
+```text
+$plan --direct docs/loopx/design/<需求名>需求设计文档.md
+```
+
+## 十一、QA
+
+### 11.1 评审记录
+
+| 评审时间 | 评审人 | 评审问题 | 处理进展 | 结论 |
+|---|---|---|---|---|
+| <时间> | <姓名> | <问题> | <进展> | <结论> |
+
+### 11.2 待确认问题
+
+| 问题 | 需要谁确认 | 阻塞阶段 | 推荐答案 | 状态 |
+|---|---|---|---|---|
+| <问题> | <角色> | clarify/spec/plan/build | <建议> | open/closed |