@ai-content-space/loopx 0.2.1 → 0.2.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Skill-first workflow suite for agentic coding assistants",
   "repository": {
     "type": "git",

package/plugins/loopx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "loopx",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Skill-first workflow suite for agentic coding assistants",
   "skills": "./skills/",
   "interface": {

package/plugins/loopx/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Grills ambiguous loopx work until material questions are answered, then routes to spec or plan using a design gate. Not for clear implementation tasks, approved specs, or code changes."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # loopx Clarify

package/plugins/loopx/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Systematic Debugging

package/plugins/loopx/skills/exec/SKILL.md

@@ -3,7 +3,7 @@ name: exec
 description: "Executes a written loopx implementation plan sequentially with review checkpoints. Not for unclear plans, missing requirements, or subagent-first execution."
 when_to_use: "written implementation plan, inline execution, sequential plan execution, review checkpoints, no subagent lane"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Exec

package/plugins/loopx/skills/final-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: final-review
+description: "Performs whole-feature review after implementation and staged task review. Not for per-task review, unresolved scope, implementation, or pure documentation polish."
+when_to_use: "final-review, final code review, whole feature review, integration review, pre-finish review, after subagent-exec, runtime risk review, 最终评审"
+metadata:
+  version: "0.2.2"
+---
+
+# Final Review
+
+Run the final whole-feature review after implementation is complete and before `finish`.
+
+**Core principle:** Per-task review catches local issues. Final review hunts integration and runtime risk across the complete feature.
+
+**Announce at start:** "I'm using the final-review skill to review the completed feature."
+
+## When to Use
+
+Use this after:
+- `subagent-exec` completed all planned tasks and per-task reviews
+- `exec` completed a full plan with verification checkpoints
+- ad-hoc implementation is complete and ready for final risk review
+
+Do not use this for:
+- reviewing one task or one small checkpoint (`review` is for that)
+- fixing review feedback (`fix-review` is for that)
+- polishing documentation wording
+- incomplete implementation or failing verification
+
+## Required Inputs
+
+Before dispatching the reviewer, collect:
+- Full feature git range: base SHA before implementation, head SHA now
+- Source requirements: spec, plan, issue, PRD, or accepted task brief
+- Implementation summary: what changed and why
+- Verification evidence: commands run and results
+- Per-task review artifacts, if available
+
+If the git range or requirements are unclear, stop and ask. A final review without a concrete scope is not useful.
+
+## Review Priority
+
+The reviewer must prioritize findings in this order:
+
+1. Runtime bugs, data loss, broken CLI behavior, state corruption
+2. Cross-task integration bugs
+3. Missing edge cases not covered by tests
+4. Test quality problems
+5. Architecture and maintainability issues
+6. Documentation defects that can mislead users or maintainers, omit required operational facts, or contradict actual behavior
+
+Do not report pure documentation polish, style preferences, or wording tweaks. Do report documentation problems that create wrong usage, wrong maintenance decisions, missing required commands, missing migration notes, or false claims.
+
+## Dispatch
+
+Use the platform's native subagent mechanism when available and fill template at `final-reviewer.md`.
+
+**Placeholders:**
+- `{DESCRIPTION}` - concise summary of the completed feature
+- `{REQUIREMENTS}` - source requirements or plan/spec excerpts
+- `{VERIFICATION}` - test commands and results
+- `{PER_TASK_REVIEWS}` - review artifacts or "not available"
+- `{BASE_SHA}` - commit before implementation began
+- `{HEAD_SHA}` - current commit
+
+## Handle Feedback
+
+- Critical and Important findings must be handled before `finish`
+- Use `fix-review` for received feedback
+- Push back only with code, test, or requirement evidence
+- After fixes, run verification again and repeat final review if the fix changed integration behavior
+
+## Common Mistakes
+
+**Running normal review again**
+- Problem: reviewer repeats per-task or documentation comments
+- Fix: use `final-reviewer.md`, which focuses on whole-feature runtime risk
+
+**Letting docs hide real risk**
+- Problem: "docs only" findings are ignored even when users would be misled
+- Fix: distinguish pure polish from operationally incorrect or missing documentation
+
+**Reviewing without base/head SHAs**
+- Problem: reviewer sees an unclear or stale diff
+- Fix: provide an exact git range every time
+
+**Skipping verification evidence**
+- Problem: reviewer cannot judge whether tests prove real behavior
+- Fix: include exact commands and pass/fail output summary

package/plugins/loopx/skills/final-review/final-reviewer.md

@@ -0,0 +1,135 @@
+# Final Reviewer Prompt Template
+
+Use this template when dispatching a final-review subagent.
+
+**Purpose:** Review the complete feature for integration and runtime risk after task-level implementation and review are already done.
+
+```
+Native subagent:
+  description: "Final review completed feature"
+  prompt: |
+    You are a Senior Final Reviewer. Task-level implementation and review have
+    already happened. Your job is not to repeat per-task review. Your job is to
+    find whole-feature risks that can still break users, corrupt state, lose
+    data, or leave important behavior untested.
+
+    ## What Was Implemented
+
+    {DESCRIPTION}
+
+    ## Requirements / Plan / Spec
+
+    {REQUIREMENTS}
+
+    ## Verification Evidence
+
+    {VERIFICATION}
+
+    ## Per-Task Reviews
+
+    {PER_TASK_REVIEWS}
+
+    ## Full Feature Git Range
+
+    **Base:** {BASE_SHA}
+    **Head:** {HEAD_SHA}
+
+    ```bash
+    git diff --stat {BASE_SHA}..{HEAD_SHA}
+    git diff {BASE_SHA}..{HEAD_SHA}
+    ```
+
+    ## Review Priority
+
+    Review in this exact priority order:
+
+    1. Runtime bugs, data loss, broken CLI behavior, state corruption
+    2. Cross-task integration bugs
+    3. Missing edge cases not covered by tests
+    4. Test quality problems
+    5. Architecture and maintainability issues
+    6. Documentation defects that can mislead users or maintainers, omit
+       required operational facts, or contradict actual behavior
+
+    Do not report pure documentation polish, style preferences, or wording
+    tweaks. Do report documentation problems that create wrong usage, wrong
+    maintenance decisions, missing required commands, missing migration notes,
+    or false claims.
+
+    ## What to Check
+
+    **Runtime and state risk:**
+    - Can any command crash, hang, silently no-op, or report success incorrectly?
+    - Can repeated runs corrupt files, state, locks, indexes, caches, or config?
+    - Can user data, generated artifacts, branches, or worktrees be lost?
+    - Are filesystem, process, permission, platform, and concurrency errors handled?
+
+    **Integration risk:**
+    - Do task outputs match later task inputs?
+    - Do CLI flags, exported functions, filenames, state keys, and schemas align?
+    - Does the feature work as a complete workflow, not just as isolated pieces?
+    - Are old data, missing files, and partially completed states handled?
+
+    **Tests:**
+    - Do tests execute real behavior rather than only mocks or snapshots?
+    - Are failure paths, edge cases, repeat runs, and integration paths covered?
+    - Are the verification commands sufficient for the changed surface area?
+
+    **Architecture:**
+    - Is the implementation maintainable within existing module boundaries?
+    - Did the feature add avoidable coupling or hidden global state?
+    - Are abstractions justified by actual complexity?
+
+    **Documentation defects:**
+    - Does documentation contradict actual behavior?
+    - Are required user or maintainer steps missing?
+    - Would a future agent follow the docs and make the wrong change?
+
+    ## Output Format
+
+    ### Findings
+
+    #### Critical
+    [Must fix before finish: data loss, state corruption, broken workflow,
+    security issue, or reliable runtime failure]
+
+    #### Important
+    [Should fix before finish: integration bug, untested edge case, weak test
+    proving too little, misleading docs that affect usage or maintenance]
+
+    #### Minor
+    [Low-risk maintainability or clarity issues. No pure polish.]
+
+    For each finding:
+    - File:line reference
+    - What is wrong
+    - Why it matters
+    - How to fix or what evidence would resolve it
+
+    ### Coverage Notes
+    [Briefly state which runtime paths and tests you inspected.]
+
+    ### Assessment
+
+    **Ready for finish?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence risk-based assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Read the actual diff, not only reports
+    - Focus on complete workflow behavior
+    - Treat tests as evidence to audit, not proof to trust blindly
+    - Report documentation defects that can mislead or omit required facts
+    - Give file:line references
+
+    **DON'T:**
+    - Repeat task-level nits unless they create whole-feature risk
+    - Report pure documentation polish
+    - Assume per-task reviews caught integration bugs
+    - Give a vague "looks good"
+    - Avoid a clear verdict
+```
+
+**Reviewer returns:** Findings by severity, Coverage Notes, Assessment.

package/plugins/loopx/skills/finish/SKILL.md

@@ -3,7 +3,7 @@ name: finish
 description: "Finishes completed loopx development work after tests pass by presenting merge, PR, keep, or discard options. Not for unfinished work or failing verification."
 when_to_use: "implementation complete, tests pass, finish branch, create pull request, merge locally, keep branch, discard work"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Finish
@@ -78,6 +78,13 @@ Allowed inputs:
 - existing `.loopx/memory/MEMORY.md` and `.loopx/memory/index.jsonl`
 - existing `docs/loopx/specs/*.md`
 
+Learning extraction priority:
+1. Durable behavior, contracts, or constraints proven by the implementation
+2. State, file, CLI, API, install, migration, compatibility, or test invariants
+3. Explicit user decisions that constrain future work
+4. Review findings or fixes that reveal a reusable pitfall, pattern, or boundary
+5. Documentation changes when they define, correct, or preserve one of the above
+
 Do not infer durable rules from agent intuition alone. Do not promote unverified implementation details.
 
 #### Memory

package/plugins/loopx/skills/fix-review/SKILL.md

@@ -3,7 +3,7 @@ name: fix-review
 description: "Handles received code review feedback with verification, technical evaluation, pushback, and one-item-at-a-time fixes. Not for requesting a new review or implementing unrelated changes."
 when_to_use: "fix-review, received code review feedback, review comments, reviewer suggestions, requested changes, 处理评审意见"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Fix Review

package/plugins/loopx/skills/go-style/SKILL.md

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Go Style

package/plugins/loopx/skills/kratos/SKILL.md

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Kratos
@@ -56,6 +56,12 @@ Use only the reference file needed for the current task:
 - Use validation annotations when the project already uses `buf.validate` or `protovalidate`.
 - Regenerate code with the repository's existing command, such as `buf generate`, `make api`, or project scripts.
 
+## Database DDL
+
+- MySQL `CREATE TABLE` statements must include a table-level `COMMENT`.
+- MySQL column definitions in `CREATE TABLE` or `ALTER TABLE ... ADD COLUMN` statements must include column-level `COMMENT`.
+- When using Ent schema for MySQL tables, add `.Comment(...)` to fields that are persisted as columns.
+
 ## Integration With Other loopx Skills
 
 - Use `go-style` for handwritten `.go` edits.

package/plugins/loopx/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Creates bite-sized implementation plans from approved requirements, clarify output, or design specs with exact files, tests, commands, expected output, and execution handoff. Not for unresolved requirements, design decisions, PRD generation, or code changes."
 when_to_use: "plan, implementation plan, execution plan, task breakdown, approved requirements, approved design spec, docs/loopx/design, 实施计划, 执行计划, 任务拆分"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 argument-hint: "<design spec path or feature name>"
 ---
 

package/plugins/loopx/skills/refactor-plan/SKILL.md

@@ -3,7 +3,7 @@ name: refactor-plan
 description: "Creates a behavior-preserving refactor plan with user interview, repo evidence, tiny commits, scope boundaries, and testing decisions. Not for feature changes or immediate implementation."
 when_to_use: "refactor-plan, refactor request, refactoring RFC, tiny commits, behavior-preserving cleanup, architecture cleanup, 重构计划"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.

package/plugins/loopx/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 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.2.1"
+  version: "0.2.2"
 ---
 
 # Review

package/plugins/loopx/skills/spec/SKILL.md

@@ -3,7 +3,7 @@ name: spec
 description: "Writes software design specs from already-clarified requirements, including solution approach, architecture outline, detailed design, tradeoffs, verification design, and handoff context. Not for unresolved requirements, PRD generation, implementation task planning, or code changes."
 when_to_use: "spec, design spec, technical design, design proposal, detailed design, architecture design, 设计方案, 概要设计, 详细设计, 技术方案"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # loopx Spec

package/plugins/loopx/skills/subagent-exec/SKILL.md

@@ -3,7 +3,7 @@ name: subagent-exec
 description: "Executes approved loopx implementation plans with fresh subagents per independent task and staged review. Not for planning, unclear requirements, or tightly coupled edits."
 when_to_use: "approved implementation plan, independent tasks, subagent execution, staged spec review, code quality review, parallel-capable execution"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Subagent Exec
@@ -65,7 +65,7 @@ digraph process {
 
     "Read plan, extract all tasks with full text, note context, create update_plan" [shape=box];
     "More tasks remain?" [shape=diamond];
-    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
+    "Use loopx:final-review for entire implementation" [shape=box];
     "Use loopx:finish" [shape=box style=filled fillcolor=lightgreen];
 
     "Read plan, extract all tasks with full text, note context, create update_plan" -> "Dispatch implementer subagent (./implementer-prompt.md)";
@@ -84,8 +84,8 @@ digraph process {
     "Code quality reviewer subagent approves?" -> "Mark task complete in update_plan" [label="yes"];
     "Mark task complete in update_plan" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
-    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
-    "Dispatch final code reviewer subagent for entire implementation" -> "Use loopx:finish";
+    "More tasks remain?" -> "Use loopx:final-review for entire implementation" [label="no"];
+    "Use loopx:final-review for entire implementation" -> "Use loopx:finish";
 }
 ```
 
@@ -199,8 +199,8 @@ Code reviewer: ✅ Approved
 ...
 
 [After all tasks]
-[Dispatch final code-reviewer]
-Final reviewer: All requirements met, ready to merge
+[Use loopx:final-review]
+Final reviewer: No whole-feature runtime or integration risks found. Ready for finish.
 
 Done!
 ```
@@ -273,6 +273,7 @@ Done!
 
 - **loopx:plan** - Creates the plan this skill executes
 - **loopx:review** - Code review template for reviewer subagents
+- **loopx:final-review** - Final whole-feature runtime and integration risk review
 - **loopx:finish** - Complete development after all tasks
 
 **Subagents should use:**

package/plugins/loopx/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Test-Driven Development (TDD)

package/plugins/loopx/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Verification Before Completion

package/skills/RESOLVER.md

@@ -14,6 +14,7 @@ Read the selected skill file before acting. If multiple skills match, read every
 | Approved plan has independent tasks and should run with subagents plus staged review | `skills/subagent-exec/SKILL.md` |
 | Approved plan should run inline or without subagent-first execution | `skills/exec/SKILL.md` |
 | Completed task, major feature, or pre-merge work needs independent code review | `skills/review/SKILL.md` |
+| Completed full feature needs final integration, runtime-risk, and test-gap review before finish | `skills/final-review/SKILL.md` |
 | Existing code review feedback needs technical evaluation and implementation | `skills/fix-review/SKILL.md` |
 | Completed implementation with passing tests needs merge, PR, keep, or discard decision | `skills/finish/SKILL.md` |
 | Refactor request needs interview, tiny commits, behavior-preserving scope, and RFC/issue output | `skills/refactor-plan/SKILL.md` |
@@ -36,10 +37,12 @@ Read the selected skill file before acting. If multiple skills match, read every
 4. `plan` writes `docs/loopx/plans/*.md` and then offers `subagent-exec` or `exec`.
 5. Use `subagent-exec` when subagents are available and the plan has independent tasks.
 6. Use `exec` when the user chooses inline execution or subagents are unavailable.
-7. Use `review` to request code review of completed work. Use `fix-review` only after feedback exists.
-8. Use `finish` only after implementation and verification are complete.
-9. Use `refactor-plan` for behavior-preserving refactor planning. If the refactor changes external behavior or contracts, route to `clarify` or `spec`.
-10. Treat `tdd`, `debug`, `verify`, `go-style`, and `kratos` as support lenses unless the user explicitly invokes them directly.
+7. Use `review` to request code review of completed task or checkpoint work.
+8. Use `final-review` after the whole feature is implemented and before `finish`.
+9. Use `fix-review` only after feedback exists.
+10. Use `finish` only after implementation, final review, and verification are complete.
+11. Use `refactor-plan` for behavior-preserving refactor planning. If the refactor changes external behavior or contracts, route to `clarify` or `spec`.
+12. Treat `tdd`, `debug`, `verify`, `go-style`, and `kratos` as support lenses unless the user explicitly invokes them directly.
 
 ## Deterministic Guard
 

package/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Grills ambiguous loopx work until material questions are answered, then routes to spec or plan using a design gate. Not for clear implementation tasks, approved specs, or code changes."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # loopx Clarify

package/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Systematic Debugging

package/skills/exec/SKILL.md

@@ -3,7 +3,7 @@ name: exec
 description: "Executes a written loopx implementation plan sequentially with review checkpoints. Not for unclear plans, missing requirements, or subagent-first execution."
 when_to_use: "written implementation plan, inline execution, sequential plan execution, review checkpoints, no subagent lane"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Exec

package/skills/final-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: final-review
+description: "Performs whole-feature review after implementation and staged task review. Not for per-task review, unresolved scope, implementation, or pure documentation polish."
+when_to_use: "final-review, final code review, whole feature review, integration review, pre-finish review, after subagent-exec, runtime risk review, 最终评审"
+metadata:
+  version: "0.2.2"
+---
+
+# Final Review
+
+Run the final whole-feature review after implementation is complete and before `finish`.
+
+**Core principle:** Per-task review catches local issues. Final review hunts integration and runtime risk across the complete feature.
+
+**Announce at start:** "I'm using the final-review skill to review the completed feature."
+
+## When to Use
+
+Use this after:
+- `subagent-exec` completed all planned tasks and per-task reviews
+- `exec` completed a full plan with verification checkpoints
+- ad-hoc implementation is complete and ready for final risk review
+
+Do not use this for:
+- reviewing one task or one small checkpoint (`review` is for that)
+- fixing review feedback (`fix-review` is for that)
+- polishing documentation wording
+- incomplete implementation or failing verification
+
+## Required Inputs
+
+Before dispatching the reviewer, collect:
+- Full feature git range: base SHA before implementation, head SHA now
+- Source requirements: spec, plan, issue, PRD, or accepted task brief
+- Implementation summary: what changed and why
+- Verification evidence: commands run and results
+- Per-task review artifacts, if available
+
+If the git range or requirements are unclear, stop and ask. A final review without a concrete scope is not useful.
+
+## Review Priority
+
+The reviewer must prioritize findings in this order:
+
+1. Runtime bugs, data loss, broken CLI behavior, state corruption
+2. Cross-task integration bugs
+3. Missing edge cases not covered by tests
+4. Test quality problems
+5. Architecture and maintainability issues
+6. Documentation defects that can mislead users or maintainers, omit required operational facts, or contradict actual behavior
+
+Do not report pure documentation polish, style preferences, or wording tweaks. Do report documentation problems that create wrong usage, wrong maintenance decisions, missing required commands, missing migration notes, or false claims.
+
+## Dispatch
+
+Use the platform's native subagent mechanism when available and fill template at `final-reviewer.md`.
+
+**Placeholders:**
+- `{DESCRIPTION}` - concise summary of the completed feature
+- `{REQUIREMENTS}` - source requirements or plan/spec excerpts
+- `{VERIFICATION}` - test commands and results
+- `{PER_TASK_REVIEWS}` - review artifacts or "not available"
+- `{BASE_SHA}` - commit before implementation began
+- `{HEAD_SHA}` - current commit
+
+## Handle Feedback
+
+- Critical and Important findings must be handled before `finish`
+- Use `fix-review` for received feedback
+- Push back only with code, test, or requirement evidence
+- After fixes, run verification again and repeat final review if the fix changed integration behavior
+
+## Common Mistakes
+
+**Running normal review again**
+- Problem: reviewer repeats per-task or documentation comments
+- Fix: use `final-reviewer.md`, which focuses on whole-feature runtime risk
+
+**Letting docs hide real risk**
+- Problem: "docs only" findings are ignored even when users would be misled
+- Fix: distinguish pure polish from operationally incorrect or missing documentation
+
+**Reviewing without base/head SHAs**
+- Problem: reviewer sees an unclear or stale diff
+- Fix: provide an exact git range every time
+
+**Skipping verification evidence**
+- Problem: reviewer cannot judge whether tests prove real behavior
+- Fix: include exact commands and pass/fail output summary

package/skills/final-review/final-reviewer.md

@@ -0,0 +1,135 @@
+# Final Reviewer Prompt Template
+
+Use this template when dispatching a final-review subagent.
+
+**Purpose:** Review the complete feature for integration and runtime risk after task-level implementation and review are already done.
+
+```
+Native subagent:
+  description: "Final review completed feature"
+  prompt: |
+    You are a Senior Final Reviewer. Task-level implementation and review have
+    already happened. Your job is not to repeat per-task review. Your job is to
+    find whole-feature risks that can still break users, corrupt state, lose
+    data, or leave important behavior untested.
+
+    ## What Was Implemented
+
+    {DESCRIPTION}
+
+    ## Requirements / Plan / Spec
+
+    {REQUIREMENTS}
+
+    ## Verification Evidence
+
+    {VERIFICATION}
+
+    ## Per-Task Reviews
+
+    {PER_TASK_REVIEWS}
+
+    ## Full Feature Git Range
+
+    **Base:** {BASE_SHA}
+    **Head:** {HEAD_SHA}
+
+    ```bash
+    git diff --stat {BASE_SHA}..{HEAD_SHA}
+    git diff {BASE_SHA}..{HEAD_SHA}
+    ```
+
+    ## Review Priority
+
+    Review in this exact priority order:
+
+    1. Runtime bugs, data loss, broken CLI behavior, state corruption
+    2. Cross-task integration bugs
+    3. Missing edge cases not covered by tests
+    4. Test quality problems
+    5. Architecture and maintainability issues
+    6. Documentation defects that can mislead users or maintainers, omit
+       required operational facts, or contradict actual behavior
+
+    Do not report pure documentation polish, style preferences, or wording
+    tweaks. Do report documentation problems that create wrong usage, wrong
+    maintenance decisions, missing required commands, missing migration notes,
+    or false claims.
+
+    ## What to Check
+
+    **Runtime and state risk:**
+    - Can any command crash, hang, silently no-op, or report success incorrectly?
+    - Can repeated runs corrupt files, state, locks, indexes, caches, or config?
+    - Can user data, generated artifacts, branches, or worktrees be lost?
+    - Are filesystem, process, permission, platform, and concurrency errors handled?
+
+    **Integration risk:**
+    - Do task outputs match later task inputs?
+    - Do CLI flags, exported functions, filenames, state keys, and schemas align?
+    - Does the feature work as a complete workflow, not just as isolated pieces?
+    - Are old data, missing files, and partially completed states handled?
+
+    **Tests:**
+    - Do tests execute real behavior rather than only mocks or snapshots?
+    - Are failure paths, edge cases, repeat runs, and integration paths covered?
+    - Are the verification commands sufficient for the changed surface area?
+
+    **Architecture:**
+    - Is the implementation maintainable within existing module boundaries?
+    - Did the feature add avoidable coupling or hidden global state?
+    - Are abstractions justified by actual complexity?
+
+    **Documentation defects:**
+    - Does documentation contradict actual behavior?
+    - Are required user or maintainer steps missing?
+    - Would a future agent follow the docs and make the wrong change?
+
+    ## Output Format
+
+    ### Findings
+
+    #### Critical
+    [Must fix before finish: data loss, state corruption, broken workflow,
+    security issue, or reliable runtime failure]
+
+    #### Important
+    [Should fix before finish: integration bug, untested edge case, weak test
+    proving too little, misleading docs that affect usage or maintenance]
+
+    #### Minor
+    [Low-risk maintainability or clarity issues. No pure polish.]
+
+    For each finding:
+    - File:line reference
+    - What is wrong
+    - Why it matters
+    - How to fix or what evidence would resolve it
+
+    ### Coverage Notes
+    [Briefly state which runtime paths and tests you inspected.]
+
+    ### Assessment
+
+    **Ready for finish?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence risk-based assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Read the actual diff, not only reports
+    - Focus on complete workflow behavior
+    - Treat tests as evidence to audit, not proof to trust blindly
+    - Report documentation defects that can mislead or omit required facts
+    - Give file:line references
+
+    **DON'T:**
+    - Repeat task-level nits unless they create whole-feature risk
+    - Report pure documentation polish
+    - Assume per-task reviews caught integration bugs
+    - Give a vague "looks good"
+    - Avoid a clear verdict
+```
+
+**Reviewer returns:** Findings by severity, Coverage Notes, Assessment.

package/skills/finish/SKILL.md

@@ -3,7 +3,7 @@ name: finish
 description: "Finishes completed loopx development work after tests pass by presenting merge, PR, keep, or discard options. Not for unfinished work or failing verification."
 when_to_use: "implementation complete, tests pass, finish branch, create pull request, merge locally, keep branch, discard work"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Finish
@@ -78,6 +78,13 @@ Allowed inputs:
 - existing `.loopx/memory/MEMORY.md` and `.loopx/memory/index.jsonl`
 - existing `docs/loopx/specs/*.md`
 
+Learning extraction priority:
+1. Durable behavior, contracts, or constraints proven by the implementation
+2. State, file, CLI, API, install, migration, compatibility, or test invariants
+3. Explicit user decisions that constrain future work
+4. Review findings or fixes that reveal a reusable pitfall, pattern, or boundary
+5. Documentation changes when they define, correct, or preserve one of the above
+
 Do not infer durable rules from agent intuition alone. Do not promote unverified implementation details.
 
 #### Memory

package/skills/fix-review/SKILL.md

@@ -3,7 +3,7 @@ name: fix-review
 description: "Handles received code review feedback with verification, technical evaluation, pushback, and one-item-at-a-time fixes. Not for requesting a new review or implementing unrelated changes."
 when_to_use: "fix-review, received code review feedback, review comments, reviewer suggestions, requested changes, 处理评审意见"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Fix Review

package/skills/go-style/SKILL.md

@@ -3,7 +3,7 @@ name: go-style
 description: "Applies loopx Go coding style for .go edits, tests, errors, context, naming, and interface boundaries. Not for non-Go code or Kratos-specific architecture by itself."
 when_to_use: "go-style, Go, golang, .go files, go tests, gofmt, idiomatic Go, Go style, Go 代码"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Go Style

package/skills/kratos/SKILL.md

@@ -3,7 +3,7 @@ name: kratos
 description: "Supports Go-Kratos microservices, proto/buf APIs, service/biz/data layers, middleware, auth, config, and troubleshooting. Not for generic Go style alone."
 when_to_use: "kratos, Go-Kratos, proto, buf, service layer, biz layer, data layer, middleware, auth, config, Kratos 微服务"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Kratos
@@ -56,6 +56,12 @@ Use only the reference file needed for the current task:
 - Use validation annotations when the project already uses `buf.validate` or `protovalidate`.
 - Regenerate code with the repository's existing command, such as `buf generate`, `make api`, or project scripts.
 
+## Database DDL
+
+- MySQL `CREATE TABLE` statements must include a table-level `COMMENT`.
+- MySQL column definitions in `CREATE TABLE` or `ALTER TABLE ... ADD COLUMN` statements must include column-level `COMMENT`.
+- When using Ent schema for MySQL tables, add `.Comment(...)` to fields that are persisted as columns.
+
 ## Integration With Other loopx Skills
 
 - Use `go-style` for handwritten `.go` edits.

package/skills/plan/SKILL.md

@@ -3,7 +3,7 @@ name: plan
 description: "Creates bite-sized implementation plans from approved requirements, clarify output, or design specs with exact files, tests, commands, expected output, and execution handoff. Not for unresolved requirements, design decisions, PRD generation, or code changes."
 when_to_use: "plan, implementation plan, execution plan, task breakdown, approved requirements, approved design spec, docs/loopx/design, 实施计划, 执行计划, 任务拆分"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 argument-hint: "<design spec path or feature name>"
 ---
 

package/skills/refactor-plan/SKILL.md

@@ -3,7 +3,7 @@ name: refactor-plan
 description: "Creates a behavior-preserving refactor plan with user interview, repo evidence, tiny commits, scope boundaries, and testing decisions. Not for feature changes or immediate implementation."
 when_to_use: "refactor-plan, refactor request, refactoring RFC, tiny commits, behavior-preserving cleanup, architecture cleanup, 重构计划"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.

package/skills/review/SKILL.md

@@ -3,7 +3,7 @@ name: review
 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.2.1"
+  version: "0.2.2"
 ---
 
 # Review

package/skills/spec/SKILL.md

@@ -3,7 +3,7 @@ name: spec
 description: "Writes software design specs from already-clarified requirements, including solution approach, architecture outline, detailed design, tradeoffs, verification design, and handoff context. Not for unresolved requirements, PRD generation, implementation task planning, or code changes."
 when_to_use: "spec, design spec, technical design, design proposal, detailed design, architecture design, 设计方案, 概要设计, 详细设计, 技术方案"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # loopx Spec

package/skills/subagent-exec/SKILL.md

@@ -3,7 +3,7 @@ name: subagent-exec
 description: "Executes approved loopx implementation plans with fresh subagents per independent task and staged review. Not for planning, unclear requirements, or tightly coupled edits."
 when_to_use: "approved implementation plan, independent tasks, subagent execution, staged spec review, code quality review, parallel-capable execution"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Subagent Exec
@@ -65,7 +65,7 @@ digraph process {
 
     "Read plan, extract all tasks with full text, note context, create update_plan" [shape=box];
     "More tasks remain?" [shape=diamond];
-    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
+    "Use loopx:final-review for entire implementation" [shape=box];
     "Use loopx:finish" [shape=box style=filled fillcolor=lightgreen];
 
     "Read plan, extract all tasks with full text, note context, create update_plan" -> "Dispatch implementer subagent (./implementer-prompt.md)";
@@ -84,8 +84,8 @@ digraph process {
     "Code quality reviewer subagent approves?" -> "Mark task complete in update_plan" [label="yes"];
     "Mark task complete in update_plan" -> "More tasks remain?";
     "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
-    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
-    "Dispatch final code reviewer subagent for entire implementation" -> "Use loopx:finish";
+    "More tasks remain?" -> "Use loopx:final-review for entire implementation" [label="no"];
+    "Use loopx:final-review for entire implementation" -> "Use loopx:finish";
 }
 ```
 
@@ -199,8 +199,8 @@ Code reviewer: ✅ Approved
 ...
 
 [After all tasks]
-[Dispatch final code-reviewer]
-Final reviewer: All requirements met, ready to merge
+[Use loopx:final-review]
+Final reviewer: No whole-feature runtime or integration risks found. Ready for finish.
 
 Done!
 ```
@@ -273,6 +273,7 @@ Done!
 
 - **loopx:plan** - Creates the plan this skill executes
 - **loopx:review** - Code review template for reviewer subagents
+- **loopx:final-review** - Final whole-feature runtime and integration risk review
 - **loopx:finish** - Complete development after all tasks
 
 **Subagents should use:**

package/skills/tdd/SKILL.md

@@ -3,7 +3,7 @@ name: tdd
 description: "Guides feature and bugfix implementation through a failing test before production code and red-green-refactor discipline. Not for generated files or throwaway prototypes."
 when_to_use: "tdd, failing test first, feature implementation, bugfix, regression test, red green refactor, 测试先行"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Test-Driven Development (TDD)

package/skills/verify/SKILL.md

@@ -3,7 +3,7 @@ name: verify
 description: "Requires fresh verification evidence before claiming work is complete, fixed, passing, review-ready, or ready to commit. Not for speculative confidence or stale results."
 when_to_use: "verify, completion claim, fixed claim, tests pass, review-ready, commit, fresh evidence, 验证, 完成前检查"
 metadata:
-  version: "0.2.1"
+  version: "0.2.2"
 ---
 
 # Verification Before Completion

package/src/install-discovery.mjs

@@ -21,6 +21,7 @@ const LOOPX_SKILLS = [
   'subagent-exec',
   'exec',
   'review',
+  'final-review',
   'fix-review',
   'finish',
   'refactor-plan',