@anionzo/skill 1.3.0 → 1.6.0

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,194 @@
+# Test-Driven Development
+
+## Purpose
+
+Enforce the discipline of writing a failing test before writing production code. This skill exists because tests written after implementation pass immediately, proving nothing — they verify what you built, not what was required.
+
+## When To Use
+
+Load this skill when:
+
+- implementing any new feature or behavior
+- fixing a bug (write a test that reproduces the bug first)
+- refactoring code that lacks test coverage
+- the user says "use TDD", "test first", or "red-green-refactor"
+
+Exceptions (confirm with the user first):
+
+- throwaway prototypes or spikes
+- generated code (codegen, scaffolding)
+- pure configuration files
+
+## The Iron Law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Wrote code before the test? Delete it. Start over. Implement fresh from the test.
+
+- Do not keep it as "reference"
+- Do not "adapt" it while writing tests
+- Do not look at it while writing the test
+- Delete means delete
+
+## Workflow: Red-Green-Refactor
+
+### 1. RED — Write a Failing Test
+
+Write one minimal test that describes the behavior you want.
+
+Requirements:
+
+- Tests one behavior (if the test name contains "and", split it)
+- Clear name that describes expected behavior
+- Uses real code, not mocks (unless external dependency makes this impossible)
+- Asserts observable outcomes, not implementation details
+
+### 2. Verify RED — Watch It Fail
+
+Run the test. This step is mandatory — never skip it.
+
+```bash
+<test-command> <path-to-test-file>
+```
+
+Confirm:
+
+- The test fails (not errors due to syntax or import issues)
+- The failure message matches what you expect
+- It fails because the feature is missing, not because of a typo
+
+If the test passes immediately, you are testing existing behavior. Rewrite the test.
+
+If the test errors instead of failing, fix the error first, then re-run until it fails correctly.
+
+### 3. GREEN — Write Minimal Code to Pass
+
+Write the simplest code that makes the test pass. Nothing more.
+
+- Do not add features the test does not require
+- Do not refactor other code
+- Do not "improve" beyond what the test demands
+- YAGNI — You Aren't Gonna Need It
+
+### 4. Verify GREEN — Watch It Pass
+
+Run the test again. This step is mandatory.
+
+```bash
+<test-command> <path-to-test-file>
+```
+
+Confirm:
+
+- The new test passes
+- All other tests still pass
+- No warnings or errors in the output
+
+If the test still fails, fix the code — not the test.
+
+If other tests broke, fix them now before moving on.
+
+### 5. REFACTOR — Clean Up (Tests Must Stay Green)
+
+After green only:
+
+- Remove duplication
+- Improve names
+- Extract helpers or shared utilities
+
+Run tests after every refactor change. If any test fails, undo the refactor and try again.
+
+Do not add new behavior during refactor. Refactor changes structure, not behavior.
+
+### 6. Repeat
+
+Next failing test for the next behavior. One cycle at a time.
+
+## Test Quality Checklist
+
+| Quality | Good | Bad |
+|---------|------|-----|
+| **Minimal** | Tests one thing | "validates email and domain and whitespace" |
+| **Clear name** | Describes expected behavior | "test1", "it works" |
+| **Shows intent** | Demonstrates desired API usage | Tests internal implementation details |
+| **Real code** | Calls actual functions | Mocks everything, tests mock behavior |
+| **Observable** | Asserts return values or side effects | Asserts internal state or call counts |
+
+## When Tests Are Hard to Write
+
+| Problem | What It Means | Action |
+|---------|---------------|--------|
+| Cannot figure out how to test | Design is unclear | Write the API you wish existed first, then assert on it |
+| Test is too complicated | Code design is too complicated | Simplify the interface |
+| Must mock everything | Code is too tightly coupled | Use dependency injection, reduce coupling |
+| Test setup is enormous | Too many dependencies | Extract helpers — if still complex, simplify the design |
+
+Hard-to-test code is hard-to-use code. Listen to what the test is telling you about the design.
+
+## Bug Fix Protocol
+
+Every bug fix follows TDD:
+
+1. **RED** — write a test that reproduces the bug
+2. **Verify RED** — confirm the test fails with the bug present
+3. **GREEN** — implement the fix
+4. **Verify GREEN** — confirm the test passes and the bug is gone
+
+Never fix a bug without a test. The test proves the fix works and prevents regression.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. The test takes 30 seconds. |
+| "I'll write tests after" | Tests written after pass immediately and prove nothing. |
+| "Tests after achieve the same goals" | Tests-after verify "what does this do?" Tests-first define "what should this do?" |
+| "Already manually tested" | Manual testing is ad-hoc: no record, cannot re-run, easy to miss cases. |
+| "Deleting X hours of work is wasteful" | Sunk cost fallacy. Keeping unverified code is technical debt. |
+| "Keep as reference, write tests first" | You will adapt it instead of writing fresh. That is testing after. |
+| "Need to explore first" | Fine. Throw away the exploration. Start fresh with TDD. |
+| "TDD will slow me down" | TDD is faster than debugging after the fact. |
+| "This is different because..." | It is not. Delete the code. Start over with TDD. |
+
+## Output Format
+
+Present results using the Shared Output Contract:
+
+1. **Goal/Result** — what was implemented using TDD and the current cycle state
+2. **Key Details:**
+   - tests written (names and what they verify)
+   - RED/GREEN/REFACTOR status for each cycle
+   - any test that could not be written and why
+   - verification output (pass/fail counts)
+3. **Next Action** — continue with next RED cycle, or hand off:
+   - all tests green and feature complete → `verification-before-completion`
+   - needs broader review → `code-review`
+   - complex feature needs planning first → `planning`
+
+## Red Flags
+
+- writing production code before a failing test exists
+- test passes immediately on first run (testing existing behavior, not new behavior)
+- cannot explain why the test failed (do not proceed to GREEN)
+- adding features the test does not require during GREEN
+- adding behavior during REFACTOR
+- rationalizing "just this once" to skip the failing test step
+- mocking so heavily that the test verifies mock behavior, not real behavior
+- keeping pre-TDD code as "reference" instead of deleting it
+
+## Checklist
+
+- [ ] Every new function/method has a test that was written first
+- [ ] Watched each test fail before writing implementation
+- [ ] Each test failed for the expected reason (feature missing, not typo)
+- [ ] Wrote minimal code to pass each test (YAGNI)
+- [ ] All tests pass after each GREEN step
+- [ ] Refactoring did not break any tests
+- [ ] Tests use real code (mocks only when unavoidable)
+- [ ] Edge cases and error paths are covered
+
+## Done Criteria
+
+This skill is complete when all required behaviors have passing tests that were written before the implementation, the full test suite is green, and no production code exists without a corresponding test that was seen to fail first. If any rationalization was used to skip TDD, the skill is not complete — delete the code and start over.

package/skills/test-driven-development/examples.md

@@ -0,0 +1,77 @@
+# Test-Driven Development — Examples
+
+## Example 1
+
+**User:** "Add email validation to the signup form"
+
+Expected routing:
+
+- task type: new feature with TDD
+- chosen skill: `test-driven-development`
+- planning required: yes, if multi-file
+- next step: write a failing test for email validation before any implementation
+
+## Example 2
+
+**User:** "Fix bug: empty email accepted by the form"
+
+Expected routing:
+
+- task type: bug fix with TDD
+- chosen skill: `test-driven-development` (via `debug`)
+- next step: write a test that reproduces the bug (empty email accepted), confirm it fails, then fix
+
+## Example 3
+
+**User:** "Refactor the auth module — add tests first since it has none"
+
+Expected routing:
+
+- task type: refactor with TDD safety net
+- chosen skill: `test-driven-development` + `refactor-safe`
+- next step: write characterization tests for existing behavior before refactoring
+
+## Red-Green-Refactor Cycle Example
+
+**Feature:** retry failed HTTP requests 3 times
+
+### RED
+
+```typescript
+test('retries failed operations 3 times', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const result = await retryOperation(operation);
+
+  expect(result).toBe('success');
+  expect(attempts).toBe(3);
+});
+```
+
+Run test → FAIL: `retryOperation is not defined`
+
+### GREEN
+
+```typescript
+async function retryOperation<T>(fn: () => T | Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === 2) throw e;
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+
+Run test → PASS
+
+### REFACTOR
+
+Extract magic number 3 into a constant if needed. Run tests → still PASS.

package/skills/test-driven-development/meta.yaml

@@ -0,0 +1,31 @@
+name: test-driven-development
+version: 0.1.0
+category: quality
+summary: Enforce test-first discipline with red-green-refactor cycles, preventing production code without a failing test.
+summary_vi: "Thực thi kỷ luật test-first với chu trình red-green-refactor, không cho phép code production khi chưa có test fail."
+triggers:
+  - implement with TDD
+  - test first
+  - red-green-refactor
+  - write a failing test first
+  - use TDD
+inputs:
+  - feature or behavior to implement
+  - existing test framework and conventions
+outputs:
+  - failing tests written first
+  - minimal implementation passing tests
+  - refactored code with green tests
+  - verification output
+constraints:
+  - no production code without a failing test
+  - delete code written before its test
+  - one behavior per test
+  - YAGNI during GREEN phase
+related_skills:
+  - using-skills
+  - planning
+  - feature-delivery
+  - debug
+  - verification-before-completion
+  - code-review

package/skills/test-driven-development/references/output-template.md

@@ -0,0 +1,31 @@
+# TDD Cycle Output Template
+
+Use this template when reporting TDD progress so each cycle is explicit and verifiable.
+
+```markdown
+## Goal/Result
+
+[What behavior was implemented or fixed using TDD]
+
+## Key Details
+
+- Test name: `[exact test name]`
+- RED status: PASS / FAIL
+- RED evidence: `[command and failure reason]`
+- GREEN status: PASS / FAIL
+- GREEN evidence: `[command and pass/fail result]`
+- Refactor performed: yes / no
+- Notes: `[edge cases, blockers, or why a test could not be written]`
+
+## Next Action
+
+- Continue with next RED cycle
+- Or hand off to `verification-before-completion`
+```
+
+Checklist:
+
+- The test was written before production code
+- The RED failure was observed for the expected reason
+- The GREEN pass was observed with fresh output
+- Refactor did not add new behavior

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,31 @@ 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:brainstorming` — explore ideas, lock decisions, optionally write a spec
 - `an:repo-onboarding` — understand an unfamiliar codebase
-- `an:planning` — create an execution-ready plan
+- `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
+- `an:go-pipeline` — execute a full spec-to-commit pipeline in one run
 
 ## 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.
@@ -64,12 +70,19 @@ 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`
+- need to understand existing code before implementing -> `research`
+- complex feature needing requirements definition -> `brainstorming` (includes spec writing)
 - 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
+- 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`
 - 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 -> `extract`
+- execute an approved spec end-to-end -> `go-pipeline`
 
 ## Planning Rule
 
@@ -84,15 +97,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 +119,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
 

package/skills/using-skills/meta.yaml

@@ -1,8 +1,8 @@
 name: using-skills
-version: 0.1.0
+version: 0.3.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
@@ -20,10 +20,15 @@ constraints:
 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
+  - go-pipeline

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.