@anionzo/skill 1.4.0 → 1.6.0

package/CONTRIBUTING.md

@@ -79,7 +79,7 @@ cp -r templates/ skills/<your-skill-name>/
 |---|---|---|
 | `name` | ✅ | Skill identifier (kebab-case) |
 | `version` | ✅ | Semantic version (`1.0.0`) |
-| `category` | ✅ | One of: `routing`, `discovery`, `planning`, `implementation`, `debugging`, `review`, `documentation`, `verification` |
+| `category` | ✅ | One of: `routing`, `discovery`, `planning`, `implementation`, `troubleshooting`, `review`, `documentation`, `quality`, `knowledge`, `workflow` |
 | `summary` | ✅ | One-line English description |
 | `summary_vi` | 🟡 | One-line Vietnamese description |
 | `triggers` | 🟡 | When to activate this skill |
@@ -161,6 +161,7 @@ Knowledge files live in `knowledge/global/`. They contain principles, heuristics
 | 🔍 `review-heuristics.md` | Code review rules |
 | 🐛 `debugging-patterns.md` | Systematic debugging approaches |
 | 🧠 `skill-triggering-rules.md` | When to load which skill |
+| 📋 `evidence-before-claims.md` | Evidence requirements before completion claims |
 
 When adding or editing knowledge:
 

package/README.md

@@ -4,7 +4,7 @@
 
 **A vendor-neutral, multi-agent skill library for AI-powered software engineering**
 
-[![Skills](https://img.shields.io/badge/skills-10-blue?style=flat-square&logo=bookstack)](skills/)
+[![Skills](https://img.shields.io/badge/skills-15-blue?style=flat-square&logo=bookstack)](skills/)
 [![Knowledge](https://img.shields.io/badge/knowledge-5_files-green?style=flat-square&logo=readme)](knowledge/)
 [![Platforms](https://img.shields.io/badge/platforms-5_agents-purple?style=flat-square&logo=robot-framework)](adapters/)
 [![License](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
@@ -51,15 +51,20 @@ This repo is intentionally lighter than a full workflow product. It borrows the
 | | Skill | Purpose |
 |---|---|---|
 | 🧭 | `using-skills` | Route a request to the right skill and working mode |
-| 💡 | `brainstorming` | Refine rough ideas into a concrete direction before planning |
+| 💡 | `brainstorming` | Explore ideas, lock decisions, optionally write a spec |
 | 🗺️ | `repo-onboarding` | Understand an unfamiliar codebase before acting |
-| 📐 | `planning` | Turn a request into an execution-ready plan |
+| 🔎 | `research` | Explore existing code and patterns before implementing |
+| 📐 | `planning` | Execution-ready plans with bite-sized steps and no placeholders |
 | 🚀 | `feature-delivery` | Implement a feature with minimal, repo-aligned change |
-| 🐛 | `bug-triage` | Investigate errors, regressions, and unclear failures |
+| 🧪 | `test-driven-development` | Enforce test-first discipline with red-green-refactor |
+| 🐛 | `debug` | 4-phase systematic debugging with root cause investigation |
 | ♻️ | `refactor-safe` | Restructure code without changing behavior |
-| ✅ | `verification-before-completion` | Require fresh evidence before claiming done |
-| 🔍 | `code-review` | Review diffs — bugs, regressions, test gaps first |
-| 📝 | `docs-writer` | Update docs from verified source behavior |
+| ✅ | `verification-before-completion` | Iron law: no completion claims without fresh evidence |
+| 🔍 | `code-review` | Give and receive code reviews with severity triage |
+| 📝 | `commit` | Create conventional commits with staged change review |
+| 📖 | `docs-writer` | Update docs from verified source behavior |
+| 🧬 | `extract` | Extract patterns, decisions, and learnings from work |
+| ⚡ | `go-pipeline` | Execute a full spec-to-commit pipeline in one run |
 
 ### 🔄 Default Workflow
 
@@ -77,10 +82,13 @@ This repo is intentionally lighter than a full workflow product. It borrows the
               ┌────────────┼────────────┐
               ▼            ▼            ▼
      ┌────────────┐ ┌───────────┐ ┌──────────────┐
-     │  feature-  │ │ bug-triage│ │ refactor-safe│
+     │  feature-  │ │   debug   │ │ refactor-safe│
      │  delivery  │ │           │ │              │
      └─────┬──────┘ └─────┬─────┘ └──────┬───────┘
            │              │              │
+           │       ┌──────┴──────┐       │
+           │       │     TDD     │       │
+           │       └──────┬──────┘       │
            ▼              ▼              ▼
      ┌─────────────────────────────────────────┐
      │      verification-before-completion     │
@@ -88,7 +96,11 @@ This repo is intentionally lighter than a full workflow product. It borrows the
                           ▼
                    ┌─────────────┐
                    │ code-review │
-                   └─────────────┘
+                   └──────┬──────┘
+                          ▼
+                    ┌──────────┐
+                    │  commit  │
+                    └──────────┘
 ```
 
 ### 📖 Research Highlights

package/docs/design-brief.md

@@ -73,19 +73,25 @@ A personal operating library with three layers:
 5. ⚙️ The first version uses simple shell scripts instead of introducing a build system
 6. ✅ Planning and verification are explicit phases for code-changing work
 
-### 🎯 Initial Scope
-
-The first version focuses on the work patterns most likely to pay off immediately:
-
-- 🧭 Routing requests
-- 💡 Refining rough requests into a workable direction
-- 🗺️ Onboarding into repos
-- 🐛 Triaging bugs
-- 📐 Planning implementation work before code edits
-- 🚀 Delivering features
-- ✅ Verifying outcomes before claiming completion
-- 🔍 Reviewing code
-- 📝 Updating docs
+### 🎯 Current Scope
+
+The library has expanded beyond the original v1 scope. The current skill set covers 15 repeatable work patterns:
+
+- 🧭 Routing requests with `using-skills`
+- 💡 Refining ideas and writing specs with `brainstorming`
+- 🗺️ Onboarding into unfamiliar repos with `repo-onboarding`
+- 🔎 Researching existing code and patterns with `research`
+- 📐 Planning implementation work before code edits with `planning`
+- 🚀 Delivering features with `feature-delivery`
+- 🧪 Implementing with test-first discipline through `test-driven-development`
+- 🐛 Systematically debugging failures with `debug`
+- ♻️ Refactoring safely with `refactor-safe`
+- ✅ Verifying outcomes before claiming completion with `verification-before-completion`
+- 🔍 Giving and receiving code reviews with `code-review`
+- 📝 Creating intentional commits with `commit`
+- 📖 Updating docs with `docs-writer`
+- 🧬 Extracting reusable learnings with `extract`
+- ⚡ Running an approved spec-to-commit flow with `go-pipeline`
 
 ### 🔮 Next Steps
 

package/i18n/CONTRIBUTING.vi.md

@@ -79,7 +79,7 @@ cp -r templates/ skills/<ten-skill>/
 |---|---|---|
 | `name` | ✅ | Định danh skill (kebab-case) |
 | `version` | ✅ | Phiên bản semantic (`1.0.0`) |
-| `category` | ✅ | Một trong: `routing`, `discovery`, `planning`, `implementation`, `debugging`, `review`, `documentation`, `verification` |
+| `category` | ✅ | Một trong: `routing`, `discovery`, `planning`, `implementation`, `troubleshooting`, `review`, `documentation`, `quality`, `knowledge`, `workflow` |
 | `summary` | ✅ | Mô tả một dòng bằng tiếng Anh |
 | `summary_vi` | 🟡 | Mô tả một dòng bằng tiếng Việt |
 | `triggers` | 🟡 | Khi nào kích hoạt skill |
@@ -161,6 +161,7 @@ File knowledge nằm trong `knowledge/global/`. Chúng chứa nguyên tắc, heu
 | 🔍 `review-heuristics.md` | Quy tắc code review |
 | 🐛 `debugging-patterns.md` | Phương pháp debug có hệ thống |
 | 🧠 `skill-triggering-rules.md` | Khi nào load skill nào |
+| 📋 `evidence-before-claims.md` | Yêu cầu bằng chứng trước tuyên bố hoàn thành |
 
 Khi thêm hoặc sửa knowledge:
 

package/i18n/README.vi.md

@@ -4,7 +4,7 @@
 
 **Thư viện skill đa agent, vendor-neutral cho kỹ thuật phần mềm hỗ trợ AI**
 
-[![Skills](https://img.shields.io/badge/skills-10-blue?style=flat-square&logo=bookstack)](../skills/)
+[![Skills](https://img.shields.io/badge/skills-15-blue?style=flat-square&logo=bookstack)](../skills/)
 [![Knowledge](https://img.shields.io/badge/knowledge-5_files-green?style=flat-square&logo=readme)](../knowledge/)
 [![Platforms](https://img.shields.io/badge/platforms-5_agents-purple?style=flat-square&logo=robot-framework)](../adapters/)
 [![License](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](../LICENSE)
@@ -51,15 +51,20 @@ Repo này nhẹ hơn một sản phẩm workflow đầy đủ. Nó lấy tư duy
 | | Skill | Mục đích |
 |---|---|---|
 | 🧭 | `using-skills` | Phân loại request và chọn đúng skill |
-| 💡 | `brainstorming` | Làm rõ ý tưởng mơ hồ trước khi lập plan |
+| 💡 | `brainstorming` | Khám phá ý tưởng, khóa quyết định, viết spec nếu cần |
 | 🗺️ | `repo-onboarding` | Hiểu codebase lạ trước khi hành động |
-| 📐 | `planning` | Biến request thành plan thực thi trước khi code |
+| 🔎 | `research` | Tìm hiểu code và pattern có sẵn trước khi implement |
+| 📐 | `planning` | Plan thực thi với bước nhỏ gọn, không placeholder |
 | 🚀 | `feature-delivery` | Triển khai feature với thay đổi tối thiểu, phù hợp repo |
-| 🐛 | `bug-triage` | Điều tra lỗi, regression, failure chưa rõ nguyên nhân |
+| 🧪 | `test-driven-development` | Kỷ luật test-first với chu trình red-green-refactor |
+| 🐛 | `debug` | Gỡ lỗi hệ thống 4 giai đoạn với điều tra nguyên nhân gốc |
 | ♻️ | `refactor-safe` | Tái cấu trúc code mà không thay đổi hành vi |
-| ✅ | `verification-before-completion` | Yêu cầu bằng chứng trước khi tuyên bố xong |
-| 🔍 | `code-review` | Review diff ưu tiên bug, regression, test gap |
-| 📝 | `docs-writer` | Cập nhật docs từ hành vi thực tế đã xác minh |
+| ✅ | `verification-before-completion` | Luật sắt: không tuyên bố xong mà không có bằng chứng mới |
+| 🔍 | `code-review` | Cho và nhận code review với phân loại mức độ |
+| 📝 | `commit` | Tạo commit conventional với review thay đổi staged |
+| 📖 | `docs-writer` | Cập nhật docs từ hành vi thực tế đã xác minh |
+| 🧬 | `extract` | Trích xuất pattern, quyết định, bài học từ công việc |
+| ⚡ | `go-pipeline` | Thực thi pipeline spec-to-commit trong một lượt |
 
 ### 🔄 Workflow Mặc Định
 
@@ -77,10 +82,13 @@ Repo này nhẹ hơn một sản phẩm workflow đầy đủ. Nó lấy tư duy
               ┌────────────┼────────────┐
               ▼            ▼            ▼
      ┌────────────┐ ┌───────────┐ ┌──────────────┐
-     │  feature-  │ │ bug-triage│ │ refactor-safe│
+     │  feature-  │ │   debug   │ │ refactor-safe│
      │  delivery  │ │           │ │              │
      └─────┬──────┘ └─────┬─────┘ └──────┬───────┘
            │              │              │
+           │       ┌──────┴──────┐       │
+           │       │     TDD     │       │
+           │       └──────┬──────┘       │
            ▼              ▼              ▼
      ┌─────────────────────────────────────────┐
      │      verification-before-completion     │
@@ -88,7 +96,11 @@ Repo này nhẹ hơn một sản phẩm workflow đầy đủ. Nó lấy tư duy
                           ▼
                    ┌─────────────┐
                    │ code-review │
-                   └─────────────┘
+                   └──────┬──────┘
+                          ▼
+                    ┌──────────┐
+                    │  commit  │
+                    └──────────┘
 ```
 
 ### 📖 Nghiên Cứu Tham Khảo

package/i18n/design-brief.vi.md

@@ -73,19 +73,25 @@ Thư viện vận hành cá nhân với ba lớp:
 5. ⚙️ Phiên bản đầu dùng shell script đơn giản thay vì build system
 6. ✅ Planning và verification là các pha rõ ràng cho công việc thay đổi code
 
-### 🎯 Phạm Vi Ban Đầu
-
-Phiên bản đầu tập trung vào các pattern có giá trị ngay:
-
-- 🧭 Phân loại request
-- 💡 Làm rõ request mơ hồ thành hướng đi cụ thể
-- 🗺️ Onboard vào repo
-- 🐛 Triage bug
-- 📐 Lập plan trước khi code
-- 🚀 Triển khai feature
-- ✅ Xác minh kết quả trước khi tuyên bố hoàn thành
-- 🔍 Review code
-- 📝 Cập nhật docs
+### 🎯 Phạm Vi Hiện Tại
+
+Thư viện đã mở rộng vượt quá phạm vi v1 ban đầu. Bộ skill hiện tại bao phủ 15 pattern công việc lặp lại:
+
+- 🧭 Phân loại request với `using-skills`
+- 💡 Làm rõ ý tưởng và viết spec với `brainstorming`
+- 🗺️ Onboard vào repo lạ với `repo-onboarding`
+- 🔎 Nghiên cứu code và pattern có sẵn với `research`
+- 📐 Lập plan trước khi code với `planning`
+- 🚀 Triển khai feature với `feature-delivery`
+- 🧪 Implement theo test-first với `test-driven-development`
+- 🐛 Gỡ lỗi có hệ thống với `debug`
+- ♻️ Refactor an toàn với `refactor-safe`
+- ✅ Xác minh kết quả trước khi tuyên bố hoàn thành với `verification-before-completion`
+- 🔍 Cho và nhận code review với `code-review`
+- 📝 Tạo commit có chủ đích với `commit`
+- 📖 Cập nhật tài liệu với `docs-writer`
+- 🧬 Trích xuất bài học tái sử dụng với `extract`
+- ⚡ Chạy luồng spec-to-commit đã được duyệt với `go-pipeline`
 
 ### 🔮 Bước Tiếp Theo
 

package/knowledge/global/skill-triggering-rules.md

@@ -10,7 +10,8 @@ These notes keep the library behavior consistent across agents and sessions.
 - Use `brainstorming` when the request is still fuzzy and the user is really asking for a clarified direction.
 - Use `planning` before code changes for multi-file, ambiguous, or higher-risk work.
 - Use `feature-delivery` only after the implementation path is concrete enough to execute.
-- Use `bug-triage` before fixing an issue whose cause is not yet grounded.
+- Use `debug` before fixing an issue whose cause is not yet grounded.
+- Use `test-driven-development` when implementing with TDD discipline (red-green-refactor).
 - Use `verification-before-completion` before any strong success claim.
 - Use `code-review` for review requests and post-implementation risk checks.
 - Use `repo-onboarding` when entering an unfamiliar codebase before productive work can begin.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anionzo/skill",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Personal AI Skill Library — vendor-neutral, multi-agent skill library for AI-powered software engineering",
   "bin": {
     "anionzo-skill": "scripts/install-opencode-skills"

package/skills/brainstorming/SKILL.md

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-Refine a fuzzy request into a concrete direction that is clear enough to plan.
+Refine a fuzzy request into a concrete direction, and when needed, lock decisions into a specification before implementation begins.
+
+This skill combines idea exploration with spec-driven development: first clarify what to build, then optionally formalize it into a spec with locked decisions and acceptance criteria.
 
 ## When To Use
 
@@ -11,35 +13,196 @@ Load this skill when:
 - the user has an idea but not a settled approach
 - the scope or success criteria are still unclear
 - multiple reasonable options exist and the tradeoff matters
-- starting implementation immediately would force too many assumptions
+- the user says "spec this", "define requirements", or "what should we build"
+- planning a non-trivial feature that has ambiguous requirements
+- multiple stakeholders need to agree on behavior before code is written
 
 Skip this skill and go directly to `planning` when the request is already specific: a named feature with clear scope, a known code path, or an explicit task with acceptance criteria.
 
-## Workflow
+## Workflow Overview
+
+**Phase 0: Explore** — clarify the idea, surface tradeoffs, extract decisions
+**Phase 1: Lock Direction** — lock the recommended direction and scope boundary
+**Phase 2: Write Spec** (optional) — formalize into a spec document with ACs
+**Phase 3: Review** — get user approval before handoff
+
+For simple clarifications, Phase 0 + Phase 1 is sufficient. For non-trivial features, continue through Phase 2 + Phase 3.
+
+## Phase 0: Explore
+
+### 0.1 Scope Assessment
+
+Assess the request complexity:
+
+- **Quick** — bounded, low ambiguity (rename a flag, tweak a label). Clarify and hand off to `planning`.
+- **Standard** — normal feature with decisions to extract. Run full exploration.
+- **Deep** — cross-cutting, strategic, or highly ambiguous. Run exploration with extra depth, then write a spec.
+
+### 0.2 Restate and Question
 
 1. Restate the request in plain language.
 2. Ask focused questions that reduce ambiguity quickly.
 3. Surface the most important tradeoffs, not every possible one.
-4. Propose one or two viable directions with clear consequences.
-5. Lock the current best direction, scope boundary, and open questions.
-6. End with a handoff into `planning` when the request is concrete enough.
+
+**HARD RULE: Ask ONE question at a time. Wait for the user's response before asking the next.**
+
+Rules:
+
+- One question per message — never bundled
+- Single-select multiple choice preferred over open-ended
+- Start broad (what/why/for whom) then narrow (constraints, edge cases)
+- 3-4 questions per topic area, then checkpoint:
+  > "More questions about [area], or move on? (Remaining: [unvisited areas])"
+
+### 0.3 Gray Area Identification
+
+Generate 2-4 gray areas — decisions that affect implementation but were not stated in the request. A gray area is a decision that would force the planner to make an assumption without it.
+
+Quick codebase scout (grep, not deep analysis):
+
+- check what already exists that is related
+- annotate options with what the codebase already has
+
+Filter OUT:
+
+- technical implementation details (architecture, library choices) — that is `planning`'s job
+- performance concerns
+- scope expansion (new capabilities not requested)
+
+### 0.4 Decision Locking
+
+After each gray area is resolved, lock the decision:
+
+> "Lock decision D[N]: [summary]. Confirmed?"
+
+Assign stable IDs: D1, D2, D3... These IDs carry forward into the spec.
+
+**Scope creep response** — when the user suggests something outside scope:
+
+> "[Feature X] is a new capability — noted as a separate work item. Back to [current area]: [question]"
+
+## Phase 1: Lock Direction
+
+Summarize the exploration output. All three of the following must be written down explicitly:
+
+1. **Recommended direction** — the approach to take
+2. **At least one key constraint** — what limits or shapes the solution
+3. **Scope boundary** — what is in and what is out
+
+Present viable options with consequences if multiple exist, but recommend one.
+
+**For quick scope:** This is the final output. Hand off to `planning`.
+
+**For standard/deep scope:** Continue to Phase 2.
+
+## Phase 2: Write Spec (For Standard/Deep Scope)
+
+### Spec Document Structure
+
+```markdown
+## Overview
+
+Brief description of the feature and its purpose.
+
+## Locked Decisions
+
+- D1: [Decision summary]
+- D2: [Decision summary]
+
+## Requirements
+
+### Functional Requirements
+- FR-1: [Requirement description]
+- FR-2: [Requirement description]
+
+### Non-Functional Requirements
+- NFR-1: [Performance, security, etc.]
+
+## Acceptance Criteria
+
+- [ ] AC-1: [Testable criterion]
+- [ ] AC-2: [Testable criterion]
+
+## Scenarios
+
+### Scenario 1: [Happy Path]
+**Given** [context]
+**When** [action]
+**Then** [expected result]
+
+### Scenario 2: [Edge Case]
+**Given** [context]
+**When** [action]
+**Then** [expected result]
+
+## Open Questions
+
+- [ ] Question 1?
+```
+
+### Spec Quality Rules
+
+- Requirements must be testable.
+- Acceptance criteria must be observable outcomes, not vague goals.
+- Scenarios should cover the happy path plus important edge cases.
+- Open questions must stay explicit, not buried in prose.
+- Keep the spec focused on WHAT, not HOW (implementation is `planning`'s job).
+
+## Phase 3: Review
+
+Present the spec (or the locked direction for quick scope) and ask:
+
+> Please review:
+> - **Approve** if complete
+> - **Edit** if you want to modify something
+> - **Add more** if requirements are missing
+
+Handle the response:
+
+- **Approved** → hand off to next skill
+- **Edit requested** → update, return to review
+- **Add more** → gather additional requirements, update, return to review
 
 ## Output Format
 
-- clarified goal
-- constraints and assumptions
-- viable options considered
-- recommended direction
-- unresolved questions
-- next skill to invoke
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — the clarified direction, spec (if written), and approval status
+2. **Key Details:**
+   - locked decisions (D1, D2...)
+   - scope boundary (in/out)
+   - viable options considered with tradeoffs
+   - acceptance criteria (if spec written)
+   - open questions
+3. **Next Action** — after approval:
+   - to review each step: `planning` (with spec reference)
+   - to execute everything at once: `go-pipeline` (with spec reference)
+   - if requirements still unclear: state what decision is still needed
 
 ## Red Flags
 
 - diving into file-level implementation too early
 - asking many questions that do not change the decision
+- batching multiple questions in one message (HARD RULE violation)
 - presenting vague options with no tradeoff explanation
 - pretending the problem is settled when key constraints are still unknown
+- creating a spec without user input
+- answering your own questions during exploration
+- skipping the review step
+- writing implementation notes instead of requirements
+- leaving ambiguous acceptance criteria that cannot be verified
+
+## Checklist
+
+- [ ] Scope assessed (quick/standard/deep)
+- [ ] Request restated in plain language
+- [ ] Gray areas identified and explored (one question at a time)
+- [ ] Decisions locked with stable IDs (D1, D2...)
+- [ ] Direction, constraint, and scope boundary documented
+- [ ] Spec written (if standard/deep scope): overview, decisions, requirements, ACs, scenarios
+- [ ] User reviewed and approved
+- [ ] Next step communicated
 
 ## Done Criteria
 
-This skill is complete when all three of the following are written down explicitly: the recommended direction, at least one key constraint, and the scope boundary. At that point, `planning` can proceed without inventing missing requirements.
+This skill is complete when the recommended direction, at least one key constraint, and the scope boundary are all written down explicitly. For standard/deep scope, the spec must be approved with acceptance criteria defined. If the spec is not approved, the skill is complete when the user has the information needed to make a decision.

package/skills/brainstorming/meta.yaml

@@ -1,23 +1,32 @@
 name: brainstorming
-version: 0.1.0
+version: 0.2.0
 category: discovery
-summary: Turn a rough idea or underspecified request into a concrete, reviewable direction before planning begins.
-summary_vi: Biến ý tưởng thô hoặc request chưa rõ thành hướng đi cụ thể, có thể review, trước khi bắt đầu lập plan.
+summary: Turn a rough idea into a concrete direction with locked decisions, optionally formalized into a spec with acceptance criteria.
+summary_vi: "Biến ý tưởng thô thành hướng đi cụ thể với quyết định đã khóa, có thể formalize thành spec với acceptance criteria."
 triggers:
   - help me think this through
   - explore the approach first
   - the request is vague or underspecified
+  - spec this feature
+  - define requirements
+  - what should we build
+  - create a specification
 inputs:
-  - rough idea
+  - rough idea or feature description
   - user goals and constraints
 outputs:
-  - clarified goal
-  - key decisions
-  - open questions
-  - handoff into planning
+  - clarified goal and direction
+  - locked decisions (D1, D2...)
+  - scope boundary
+  - optional spec with requirements and ACs
+  - approval status
 constraints:
-  - avoid jumping into code or low-level implementation too early
-  - keep the discussion concrete and decision-oriented
+  - ask one question at a time during exploration
+  - do not skip the review step
+  - keep focused on WHAT not HOW
 related_skills:
   - using-skills
   - planning
+  - research
+  - go-pipeline
+  - feature-delivery