@anionzo/skill 1.4.0 → 1.7.0

package/skills/using-skills/SKILL.md

@@ -22,7 +22,7 @@ Load this skill when:
 
 > `an:` stands for "activate now" — a shorthand to immediately load a specific skill.
 
-If the user types `an:<skill-name>` (for example `an:planning` or `an:bug-triage`), skip classification and load that skill immediately.
+If the user types `an:<skill-name>` (for example `an:planning` or `an:debug`), skip classification and load that skill immediately.
 
 **Rules:**
 
@@ -33,25 +33,29 @@ If the user types `an:<skill-name>` (for example `an:planning` or `an:bug-triage
 
 **Available skills:**
 
-- `an:brainstorming` — refine vague ideas before planning
-- `an:repo-onboarding` — understand an unfamiliar codebase
-- `an:planning` — create an execution-ready plan
+- `an:brainstorming` — explore ideas, lock decisions, optionally write a spec
+- `an:research` — explore existing code and patterns before implementing
+- `an:planning` — create an execution-ready plan with bite-sized steps
 - `an:feature-delivery` — implement a feature
-- `an:bug-triage` — investigate errors or regressions
+- `an:test-driven-development` — implement with TDD (red-green-refactor)
+- `an:debug` — systematic 4-phase debugging: investigate, analyze, fix, learn
 - `an:refactor-safe` — restructure code without behavior change
 - `an:verification-before-completion` — verify before claiming done
-- `an:code-review` — review a diff or PR
+- `an:code-review` — review a diff/PR, or evaluate received feedback
+- `an:commit` — create a conventional commit with verification
 - `an:docs-writer` — update documentation
+- `an:extract` — extract patterns, decisions, and learnings from completed work
 
 ## Workflow
 
 1. Check for direct trigger: if the user typed `an:<skill-name>`, load that skill and skip to step 5.
 2. Classify the request into one of these modes:
-   - idea refinement or specification
+   - idea refinement, specification, or requirements definition
    - repo understanding
    - bug or regression investigation
    - planning and implementation
-   - code review
+   - test-driven implementation
+   - code review (giving or receiving)
    - documentation work
    - answer-only guidance
 3. Decide whether the task first needs brainstorming or can go straight to planning.
@@ -63,13 +67,20 @@ If the user types `an:<skill-name>` (for example `an:planning` or `an:bug-triage
 
 - `an:<skill-name>` (direct trigger) -> load the named skill immediately
 - vague feature idea, unclear goal, tradeoff exploration -> `brainstorming`, then `planning`
-- unfamiliar repo or missing context -> `repo-onboarding`
-- docs work in an unfamiliar repo -> `repo-onboarding` first, then `docs-writer`
-- bug report, error trace, failing test, regression -> `bug-triage`, then `planning` if the fix is not already obvious and bounded
+- unfamiliar repo or missing context -> `research`
+- need to understand existing code before implementing -> `research`
+- complex feature needing requirements definition -> `brainstorming` (includes spec writing)
+- docs work in an unfamiliar repo -> `research` first, then `docs-writer`
+- bug report, error trace, failing test, regression -> `debug`
 - implement or change behavior -> `planning`, then `feature-delivery`
+- implement with TDD approach -> `planning`, then `test-driven-development`
+- execute an approved spec or clear task end-to-end with minimal gates -> `planning` in go mode
 - refactor, restructure, extract, or migrate without behavior change -> `planning`, then `refactor-safe`
 - review diff, PR, or changed files -> `code-review`
+- respond to review feedback -> `code-review` (receiving mode)
+- ready to commit -> `commit`
 - update README, runbook, onboarding docs, API notes in a known repo -> `docs-writer`
+- extract learnings from completed work, or summarize active work for the next session -> `extract`
 
 ## Planning Rule
 
@@ -84,15 +95,19 @@ You may skip a separate planning step only when the change is clearly local, low
 
 ## Verification Rule
 
-Use `verification-before-completion` before any strong claim that work is done, fixed, passing, or ready.
+Use `verification-before-completion` before any strong claim that work is done, fixed, passing, or ready. No completion claims without fresh evidence.
 
 ## Output Format
 
-- task type
-- chosen primary skill
-- planning required
-- key assumption or missing decision, if any
-- immediate next step
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — the task classified and primary skill chosen
+2. **Key Details:**
+   - task type
+   - chosen primary skill
+   - whether planning is required
+   - key assumption or missing decision, if any
+3. **Next Action** — the immediate first step with the chosen skill
 
 ## Red Flags
 
@@ -102,6 +117,7 @@ Use `verification-before-completion` before any strong claim that work is done,
 - loading many skills at once without a clear reason
 - asking broad planning questions before checking if the task is already clear
 - forcing a feature workflow onto a review or docs task
+- skipping TDD when the user requested it
 
 ## Done Criteria
 

package/skills/using-skills/examples.md

@@ -26,9 +26,9 @@ This login flow started failing after yesterday's deploy.
 Expected routing:
 
 - task type: bug investigation
-- chosen skill: `bug-triage`
-- planning required: maybe, after triage if the fix is not obviously local
-- next step: restate the symptom and try to reproduce it
+- chosen skill: `debug`
+- planning required: maybe, after diagnosis if the fix is not obviously local
+- next step: classify the issue and try to reproduce it
 
 ## Example 3
 
@@ -41,7 +41,7 @@ Help me understand this repo before we add a new API endpoint.
 Expected routing:
 
 - task type: repo understanding
-- chosen skill: `repo-onboarding`
+- chosen skill: `research`
 - planning required: not yet
 - next step: read repo docs and inspect core entrypoints
 
@@ -60,7 +60,22 @@ Expected routing:
 - planning required: yes
 - next step: refine the exact SSO scope and constraints before writing the implementation plan
 
-## Example 5 — Sample completed output
+## Example 5
+
+User request:
+
+```text
+What did we do so far? Prepare the next session to continue this task.
+```
+
+Expected routing:
+
+- task type: extraction / handoff
+- chosen skill: `extract`
+- planning required: no
+- next step: summarize the active task, completed work, locked decisions, risks, and next action
+
+## Example 6 — Sample completed output
 
 User request:
 

package/skills/using-skills/meta.yaml

@@ -1,8 +1,8 @@
 name: using-skills
-version: 0.1.0
+version: 0.4.0
 category: routing
 summary: Route a user request to the right primary skill and working mode before deeper work begins.
-summary_vi: Phân loại request và chọn đúng skill chính trước khi bắt đầu công việc sâu hơn.
+summary_vi: "Phân loại request và chọn đúng skill chính trước khi bắt đầu công việc sâu hơn."
 triggers:
   - start a new session
   - decide which skill to load
@@ -19,11 +19,14 @@ constraints:
   - prefer one primary skill at a time
 related_skills:
   - brainstorming
-  - repo-onboarding
+  - research
   - planning
-  - bug-triage
+  - test-driven-development
+  - debug
   - feature-delivery
   - refactor-safe
   - code-review
+  - commit
   - verification-before-completion
   - docs-writer
+  - extract

package/skills/verification-before-completion/SKILL.md

@@ -2,7 +2,15 @@
 
 ## Purpose
 
-Stop false completion claims by requiring fresh evidence before saying work is done, fixed, or passing.
+Stop false completion claims by requiring fresh evidence before saying work is done, fixed, or passing. Evidence before claims, always.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you have not run the verification command in this response, you cannot claim it passes. No exceptions.
 
 ## When To Use
 
@@ -12,6 +20,37 @@ Load this skill when:
 - about to say tests or builds pass
 - about to mark work complete
 - about to commit, open a PR, or hand off finished work
+- verifying implementation against a spec's acceptance criteria
+- expressing satisfaction about work state ("done", "ready", "all good")
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Forbidden Words
+
+Do not use these words in completion claims unless backed by fresh evidence run in the same response:
+
+- "should work now"
+- "probably fixed"
+- "seems to pass"
+- "looks correct"
+- "I'm confident"
+- "Great!", "Perfect!", "Done!" (before verification)
+
+Replace with evidence: "Tests pass (42/42, 0 failures)" or "Build exits 0."
 
 ## Workflow
 
@@ -19,28 +58,103 @@ Load this skill when:
 2. Identify the command, test, or check that proves that claim.
 3. Run the most relevant verification available.
 4. Read the actual result, not just the expectation.
-5. Report one of three states:
-   - verified
-   - failed verification
-   - verification blocked
-6. If blocked, state what remains unproven.
+5. If spec-linked, verify acceptance criteria coverage.
+6. Check verification levels per deliverable.
+7. Report one of three states:
+   - **verified** — evidence confirms the claim
+   - **failed verification** — evidence contradicts the claim
+   - **verification blocked** — cannot verify, state what remains unproven
+
+## Verification Levels
+
+For each deliverable, verify at three levels:
+
+| Level | Check | Meaning |
+|-------|-------|---------|
+| **L1: EXISTS** | File/component/route exists | Created but unknown quality |
+| **L2: SUBSTANTIVE** | Not a stub (no `return null`, empty handlers, TODO-only) | Has real implementation |
+| **L3: WIRED** | Imported and used in the integration layer | Actually connected |
+
+Report status per deliverable:
+
+- L1+L2+L3: fully wired
+- L1+L2 only: created but not integrated (flag it)
+- L1 only (stub): exists but empty (blocks completion)
+- Missing: not found (blocks completion)
+
+## Spec Acceptance Criteria Coverage
+
+When work is linked to a spec, also verify:
+
+1. Map each acceptance criterion to its verification evidence.
+2. Report coverage:
+
+```
+AC Coverage
+===========
+- [x] AC-1: [description] — VERIFIED (test passes)
+- [x] AC-2: [description] — VERIFIED (manual check)
+- [ ] AC-3: [description] — NOT VERIFIED (no test exists)
+
+Coverage: 2/3 (67%)
+```
+
+3. Flag any AC that has no verification evidence.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification. |
+| "I'm confident" | Confidence is not evidence. |
+| "Just this once" | No exceptions. |
+| "Linter passed" | Linter is not compiler is not test suite. |
+| "Agent said success" | Verify independently. |
+| "Partial check is enough" | Partial proves nothing about the unchecked parts. |
+| "Different words so rule doesn't apply" | Spirit over letter. Any claim of success requires evidence. |
+| "I'm tired" | Exhaustion is not an excuse to ship broken code. |
 
 ## Output Format
 
-- claim being checked
-- evidence run
-- result
-- final status
-- remaining uncertainty, if any
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — what claim was checked and the verification status
+2. **Key Details:**
+   - claim being checked
+   - evidence run (exact command or check)
+   - result (pass/fail/blocked)
+   - verification level per deliverable (L1/L2/L3)
+   - AC coverage (if spec-linked)
+   - remaining uncertainty, if any
+3. **Next Action:**
+   - if verified → `code-review` or `commit`
+   - if failed → back to `feature-delivery` or `debug`
+   - if blocked → state what is needed
 
 ## Red Flags
 
-- saying `should work now`
+- using any forbidden word without fresh evidence
+- saying "should work now"
 - treating code edits as proof
 - using stale test output as fresh evidence
 - extrapolating from a partial check to a broader claim
 - declaring success while verification is still blocked
+- marking stubs (L1 only) as complete
+- skipping AC coverage check for spec-linked work
+- expressing satisfaction before running verification
+
+## Checklist
+
+- [ ] Claim identified
+- [ ] Verification command/check identified
+- [ ] Verification run (fresh, not stale)
+- [ ] Actual result read (not assumed)
+- [ ] No forbidden words used without evidence
+- [ ] Verification levels checked per deliverable (L1/L2/L3)
+- [ ] AC coverage verified (if spec-linked)
+- [ ] Status reported (verified / failed / blocked)
+- [ ] Remaining uncertainty stated
 
 ## Done Criteria
 
-This skill is complete when the claim is either backed by fresh evidence or explicitly marked as unverified with the blocker stated. If verification passes and a review is warranted, hand off to `code-review`.
+This skill is complete when the claim is either backed by fresh evidence or explicitly marked as unverified with the blocker stated. If verification passes and a review is warranted, hand off to `code-review`. If spec-linked, AC coverage must be reported.

package/skills/verification-before-completion/meta.yaml

@@ -1,26 +1,35 @@
 name: verification-before-completion
-version: 0.1.0
-category: verification
-summary: Require fresh evidence before claiming work is done, fixed, passing, or ready.
-summary_vi: Yêu cầu bằng chứng mới trước khi tuyên bố công việc đã xong, đã sửa, đã pass, hoặc sẵn sàng.
+version: 0.3.0
+category: quality
+summary: Iron law enforcement of fresh evidence before completion claims, with forbidden words, anti-rationalization, and AC coverage.
+summary_vi: "Thực thi nghiêm ngặt bằng chứng mới trước khi tuyên bố hoàn thành, với từ cấm, chống rationalization, và AC coverage."
 triggers:
+  - verify this works
+  - check before marking done
+  - confirm the fix
   - before saying a fix works
-  - before marking work complete
   - before commit, PR, or handoff
 inputs:
-  - work completed so far
-  - relevant verification commands or checks
+  - claim being made
+  - verification command or check
+  - optional spec reference for AC coverage
 outputs:
-  - verified claim
-  - blocked verification note
+  - verification status (verified/failed/blocked)
+  - verification levels per deliverable (L1/L2/L3)
+  - AC coverage report (if spec-linked)
   - remaining uncertainty
 constraints:
-  - no success claims without fresh evidence
-  - if verification is blocked, say so plainly
+  - no completion claims without fresh verification evidence
+  - forbidden words without evidence block completion
+  - must run fresh verification, not use stale output
+  - stubs (L1 only) block completion
 related_skills:
   - using-skills
+  - code-review
+  - commit
+  - docs-writer
   - feature-delivery
-  - bug-triage
-  - refactor-safe
+  - debug
   - planning
-  - code-review
+  - refactor-safe
+  - test-driven-development

package/templates/SKILL.md

@@ -17,7 +17,14 @@ State the job this skill performs.
 
 ## Output Format
 
-- Main sections the response or result should contain
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — what was accomplished or blocked
+2. **Key Details:**
+   - the most important supporting context
+   - concrete references (files, commands, evidence)
+   - assumptions or gaps
+3. **Next Action** — recommend a follow-up only when a natural handoff exists
 
 ## Red Flags
 

package/skills/bug-triage/SKILL.md

@@ -1,47 +0,0 @@
-# Bug Triage
-
-## Purpose
-
-Investigate failures methodically so the next fix is based on evidence instead of guesswork.
-
-## When To Use
-
-Load this skill when:
-
-- a user reports a bug or regression
-- a test starts failing without obvious cause
-- production behavior no longer matches the intended behavior
-
-## Workflow
-
-1. Restate the symptom in plain language.
-2. Attempt to reproduce the issue or explain why reproduction is blocked.
-3. Narrow the problem:
-   - identify the code path involved
-   - inspect recent behavior changes or assumptions
-   - check inputs, state, timing, or environment differences
-4. Form the smallest credible root-cause hypothesis.
-5. Define the minimal next change or experiment that would confirm the cause.
-6. Add or recommend regression coverage when the cause is clear.
-
-## Output Format
-
-- symptom summary
-- reproduction status
-- suspected root cause
-- impacted area
-- proposed next change
-- confidence level
-
-## Red Flags
-
-- proposing a rewrite before understanding the current failure
-- changing many files before narrowing the cause
-- ignoring whether the behavior is reproducible
-- treating logs or stack traces as proof without checking the code path
-
-## Done Criteria
-
-This skill is complete when the next fix or experiment is specific, minimal, and tied to a clearly stated hypothesis.
-
-If the fix is non-trivial or touches more than one area, hand off to `planning` before moving to `feature-delivery`.

package/skills/bug-triage/examples.md

@@ -1,68 +0,0 @@
-# Examples
-
-## Example 1
-
-User request:
-
-```text
-Users get logged out randomly after the deploy.
-```
-
-Expected result:
-
-- restate the symptom and affected surface area
-- inspect auth session code path and recent deploy changes
-- identify one or two likely causes before editing unrelated modules
-
-Sample completed output:
-
-```
-Symptom: Users with active sessions are being logged out unexpectedly after the v2.4.1 deploy.
-
-Reproduction: Confirmed on staging — session is invalidated ~10 minutes after login even without user action.
-
-Root-Cause Hypothesis:
-- Most likely: SESSION_TTL env var was changed from 3600 to 600 in the deploy config
-- Evidence: session.ts reads process.env.SESSION_TTL; config diff shows the change
-- Uncertainty: not yet confirmed whether all env changes were intentional
-
-Next Change: Restore SESSION_TTL to 3600 in production config and redeploy
-
-Confidence: high
-
-Handoff: feature-delivery (fix is already clear and local)
-```
-
-## Example 2
-
-User request:
-
-```text
-This integration test started failing with a timeout.
-```
-
-Expected result:
-
-- determine where the timeout occurs
-- distinguish between slow setup, deadlock, or missing response
-- propose the smallest confirming step
-
-### Completed output
-
-```
-Symptom: Integration test `test/integration/payment.test.ts` times out after 30s on the "processes valid refund" case.
-
-Reproduction: Confirmed locally — `npm test -- payment` hangs at step 3/5 of the refund flow test.
-
-Root-Cause Hypothesis:
-- Most likely: The mock payment gateway is not responding to the refund callback, causing the test to wait indefinitely
-- Evidence: The test uses a mock server on port 9999; logs show the request is sent but no response is received
-- Alternative: A database connection pool exhaustion from a previous test not cleaning up properly
-- Uncertainty: need to check if the mock server is started before the refund call
-
-Confirming Step: Add a 5s timeout to the mock refund endpoint and log whether it receives the request. If the mock receives it but doesn't respond, the mock handler is missing the refund route.
-
-Confidence: medium
-
-Handoff: planning (once root cause is confirmed, the fix is likely a one-line mock handler addition)
-```

package/skills/bug-triage/meta.yaml

@@ -1,25 +0,0 @@
-name: bug-triage
-version: 0.1.0
-category: debugging
-summary: Turn a bug report or failure symptom into a grounded root-cause hypothesis and a minimal next fix.
-summary_vi: Biến bug report hoặc triệu chứng lỗi thành giả thuyết nguyên nhân gốc có căn cứ và bước sửa tối thiểu tiếp theo.
-triggers:
-  - investigate this error
-  - debug this regression
-  - failing test or production issue
-inputs:
-  - bug report
-  - logs or stack traces when available
-  - code paths involved in the failure
-outputs:
-  - reproduction status
-  - root-cause hypothesis
-  - minimal next change
-constraints:
-  - prove or narrow the cause before broad refactors
-  - call out confidence and uncertainty explicitly
-related_skills:
-  - using-skills
-  - planning
-  - feature-delivery
-  - verification-before-completion

package/skills/bug-triage/references/output-template.md

@@ -1,26 +0,0 @@
-## Symptom
-
-- What is failing and how it shows up
-
-## Reproduction
-
-- reproduced: yes or no
-- notes:
-
-## Root-Cause Hypothesis
-
-- most likely cause:
-- evidence:
-- uncertainty:
-
-## Next Change
-
-- smallest fix or confirming experiment
-
-## Confidence
-
-- low, medium, or high
-
-## Handoff
-
-- Next skill: planning (if fix is non-trivial) or feature-delivery (if fix is already clear)

package/skills/repo-onboarding/SKILL.md

@@ -1,52 +0,0 @@
-# Repo Onboarding
-
-## Purpose
-
-Understand a repository quickly enough to act safely and explain what matters.
-
-## When To Use
-
-Load this skill when:
-
-- entering a repo for the first time
-- a task depends on understanding architecture or conventions
-- the user asks what the project does or how it is organized
-
-## Workflow
-
-1. Read the top-level operating docs first, especially `AGENTS.md` and `README.md` when present.
-2. Inspect the most informative source files next:
-   - package manifests or build files
-   - app entrypoints and framework bootstraps
-   - core config files
-   - representative tests
-3. Identify:
-   - project purpose
-   - major components
-   - runtime model and key integrations
-   - important development or verification commands
-4. Call out what is verified from source versus what is still uncertain.
-5. Recommend the next files or directories to inspect for the user's likely goal.
-
-## Output Format
-
-- project purpose
-- architecture summary
-- major components and responsibilities
-- important commands or workflows
-- notable conventions or constraints
-- open questions
-- recommended next reads
-
-## Red Flags
-
-- skipping repo docs and jumping straight into random source files
-- summarizing architecture from folder names alone
-- claiming a behavior without checking source or config
-- reading many low-value files while missing the actual entrypoints
-
-## Done Criteria
-
-This skill is complete when another engineer could start productive work from the summary without redoing the same orientation pass. Both the "Important Commands" and "Open Questions" fields must be populated.
-
-After this skill, the natural next step is `planning` (to plan a change) or `docs-writer` (if the goal is to update documentation).