@anionzo/skill 1.4.0 → 1.7.0

package/skills/research/SKILL.md

@@ -0,0 +1,130 @@
+# Research
+
+## Purpose
+
+Understand existing code, patterns, decisions, and repository structure before writing new code.
+
+This skill exists to prevent implementing from scratch what already exists, and to surface constraints that would otherwise be discovered mid-implementation.
+
+It also covers repo onboarding: mapping a repository quickly enough to act safely when the task starts from little context.
+
+## When To Use
+
+Load this skill when:
+
+- exploring a codebase before starting a task
+- entering a repo for the first time
+- looking for existing patterns, utilities, or conventions to follow
+- trying to understand how a feature or subsystem works
+- the implementation approach depends on what already exists
+- the user says "research this", "look into", or "what do we have for X"
+- the user asks "explain this repo" or "understand this codebase before we change it"
+
+Skip this skill when you already have clear context and the task is straightforward.
+
+## Workflow
+
+1. State what is being researched and why.
+2. Search in this order:
+   - project documentation (READMEs, docs/, wikis)
+   - existing code paths and implementations
+   - adjacent tests, validation, and configuration
+   - related issues, PRs, or commit history
+3. For each finding, note:
+   - what exists and where
+   - whether it is reusable, needs adaptation, or is irrelevant
+   - any conventions or constraints it reveals
+4. Identify gaps — what does NOT exist that the task needs.
+5. If this is repo onboarding, also identify:
+   - project purpose
+   - major components and responsibilities
+   - runtime model and key integrations
+   - important development commands
+   - notable conventions and open questions
+6. Summarize findings with concrete recommendations.
+
+## Repo Onboarding Mode
+
+When the user is entering an unfamiliar repo, use research in repo-map mode:
+
+1. Read the top-level operating docs first, especially `AGENTS.md` and `README.md` when present.
+2. Inspect the most informative files next:
+   - package manifests or build files
+   - app entrypoints and framework bootstraps
+   - core config files
+   - representative tests
+3. Summarize:
+   - project purpose
+   - architecture summary
+   - major components
+   - important commands
+   - notable conventions or constraints
+   - open questions
+4. Recommend the next files or directories to inspect for the user's likely goal.
+
+## Search Techniques
+
+Use the most efficient search method for the situation:
+
+```
+# Find files by name pattern
+find . -name "*<pattern>*" -type f | grep -v node_modules | head -20
+
+# Search code for patterns
+grep -r "<pattern>" --include="*.ts" -l | head -20
+
+# Check recent changes to a file
+git log --oneline -10 -- <file>
+
+# Find related tests
+find . -name "*<topic>*test*" -o -name "*test*<topic>*" | head -10
+```
+
+Read the actual files — do not guess from filenames alone.
+
+## Output Format
+
+Present findings using the Shared Output Contract:
+
+1. **Goal/Result** — what was researched and the key conclusion
+2. **Key Details:**
+   - concrete files or docs found
+   - what is reusable vs what is missing
+   - architecture or convention constraints discovered
+   - patterns that new code should follow
+3. **Next Action** — recommend a follow-up only when findings clearly lead somewhere:
+   - research for an active task → `planning`
+   - research revealed a gap → `brainstorming`
+   - research produced enough repo context → `planning`, `docs-writer`, or direct execution
+   - no clear handoff → stop after findings
+
+## Research Rules
+
+- Search before assuming nothing exists.
+- Read the actual code, not just the file tree.
+- State explicitly when no existing pattern is found rather than implying one exists.
+- If docs and code disagree, call out the mismatch.
+- If the research surface is too large, focus on the most relevant subset and note what was not covered.
+- Do not expand the original question into unrelated exploration.
+
+## Red Flags
+
+- skipping the search and going straight to implementation
+- reading filenames without opening the files
+- reporting vague findings like "there seems to be something related"
+- expanding research scope without noting the expansion
+- treating absence of evidence as evidence of absence
+
+## Checklist
+
+- [ ] Research topic stated
+- [ ] Documentation searched
+- [ ] Existing code patterns found (or explicitly noted as absent)
+- [ ] Related tests and config checked
+- [ ] Findings include concrete file paths
+- [ ] Reusable vs missing clearly separated
+- [ ] Recommendations are actionable
+
+## Done Criteria
+
+This skill is complete when the findings are concrete enough to inform the next step — whether that is planning, implementation, docs work, or a decision that more information is needed. Every finding should include a file path or explicit "not found" statement.

package/skills/research/examples.md

@@ -0,0 +1,79 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+How does our auth system work? I need to add a new OAuth provider.
+```
+
+Expected result:
+
+- search for auth-related files, patterns, and documentation
+- identify existing OAuth implementations and patterns
+- note what is reusable and what needs to be built
+
+Sample completed output:
+
+```
+Goal/Result: Researched the auth system to understand how to add a new OAuth provider.
+
+Key Details:
+- Existing implementations:
+  - src/auth/providers/google.ts — Google OAuth using passport-google-oauth20
+  - src/auth/providers/github.ts — GitHub OAuth using passport-github2
+  - src/auth/strategy.ts — Base strategy wrapper, all providers follow this pattern
+  - src/auth/callback.ts — Shared callback handler for all OAuth flows
+- Patterns found:
+  - Each provider is a separate file in src/auth/providers/
+  - All providers implement the AuthProvider interface from src/auth/types.ts
+  - Callback URL pattern: /auth/{provider}/callback
+  - Config loaded from environment variables: AUTH_{PROVIDER}_CLIENT_ID, AUTH_{PROVIDER}_SECRET
+- Gaps:
+  - No generic OAuth2 provider — each is implemented individually
+  - No tests for the OAuth callback flow
+- Constraints:
+  - Must use passport.js (project convention)
+  - Must register in src/auth/index.ts provider registry
+
+Next Action: planning — plan the new OAuth provider implementation following the existing pattern.
+```
+
+## Example 2
+
+User request:
+
+```text
+What caching do we use? I need to cache API responses.
+```
+
+Expected result:
+
+- search for caching patterns in the codebase
+- identify existing cache implementations
+- note configuration and conventions
+
+Sample completed output:
+
+```
+Goal/Result: Researched caching patterns. Found Redis-based caching in use for sessions but no API response caching.
+
+Key Details:
+- Existing implementations:
+  - src/cache/redis.ts — Redis client wrapper (ioredis)
+  - src/middleware/session.ts — Uses Redis for session storage
+  - No API response caching found anywhere
+- Patterns found:
+  - Redis connection config in src/config/redis.ts
+  - TTL conventions: sessions use 24h, no other TTL patterns
+  - Cache keys use prefix pattern: "app:{type}:{id}"
+- Gaps:
+  - No response caching middleware exists
+  - No cache invalidation strategy documented
+- Constraints:
+  - Redis is already a dependency — reuse existing connection
+  - Key prefix pattern must be followed
+
+Next Action: planning — design a response caching middleware using the existing Redis setup.
+```

package/skills/research/meta.yaml

@@ -0,0 +1,31 @@
+name: research
+version: 0.2.0
+category: discovery
+summary: Understand repository structure, existing code, patterns, and decisions before acting so new work follows what already exists.
+summary_vi: "Tìm hiểu cấu trúc repo, code, pattern, và quyết định hiện có trước khi hành động để công việc mới đi đúng theo cái đã có."
+triggers:
+  - research this codebase
+  - what do we already have for X
+  - look into how this works
+  - explore before implementing
+  - explain this repo
+  - onboard into a codebase
+  - understand architecture before changing code
+inputs:
+  - topic, feature, or repository area to research
+  - optional file paths or package names
+outputs:
+  - existing implementations found
+  - patterns and conventions discovered
+  - gaps identified
+  - actionable recommendations
+  - repo map and important commands when onboarding
+constraints:
+  - search before assuming nothing exists
+  - read actual code not just filenames
+related_skills:
+  - using-skills
+  - planning
+  - brainstorming
+  - extract
+  - docs-writer

package/skills/research/references/output-template.md

@@ -0,0 +1,23 @@
+## Goal/Result
+
+- What was researched:
+- Key conclusion:
+
+## Key Details
+
+### Existing Implementations
+- `path/to/file`: Does X
+
+### Patterns Found
+- Pattern 1: Used for...
+
+### Gaps Identified
+- What is missing:
+
+### Constraints Discovered
+- Convention 1:
+- Architecture constraint 1:
+
+## Next Action
+
+- Recommended follow-up:

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