@anionzo/skill 1.1.0

package/skills/refactor-safe/examples.md

@@ -0,0 +1,96 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Clean up the payment module — it's gotten too big.
+```
+
+Expected result:
+
+- define what "clean up" means exactly (split file? rename? extract utilities?)
+- fix scope to specific files before touching anything
+- check which tests cover payment logic before starting
+- make structural changes and verify no behavioral drift
+
+### Completed output — Example 1
+
+```
+Goal and scope boundary: Split src/services/PaymentService.ts (680 lines) into focused modules without changing any payment behavior.
+- In scope: PaymentService.ts, its direct imports, and related tests
+- Not in scope: API routes, database schema, external payment provider integration
+
+Behavior contract: All 14 existing tests in tests/payment.test.ts must continue to pass with identical assertions. No changes to the public API of PaymentService (same method signatures, same return types).
+
+Coverage check before: 14 tests covering charge(), refund(), listTransactions(), and webhookHandler(). No test for the internal retry logic — noted but not blocking the refactor.
+
+Steps taken:
+1. Extracted retry logic into src/services/payment/retryWithBackoff.ts
+2. Extracted webhook handling into src/services/payment/webhookHandler.ts
+3. Kept PaymentService.ts as the public facade re-exporting the split modules
+4. Updated internal imports; no changes to external callers
+
+Coverage result after: All 14 tests pass. Added 2 unit tests for retryWithBackoff to cover the newly isolated module.
+
+Behavioral drift check: Compared charge() and refund() outputs for 3 fixture inputs before and after — identical results. Webhook handler returns the same status codes for test payloads.
+
+Handoff: verification-before-completion
+```
+
+### Completed output — Example 2
+
+```
+Goal and scope boundary: Migrate all HTTP client calls from axios to native fetch across the service layer without changing any request behavior.
+- In scope: All files importing axios in src/services/
+- Not in scope: External API contracts, retry policies, test mocks
+
+Behavior contract: Every existing API call must produce identical request headers, body shape, timeout behavior, and error responses.
+
+Coverage check before: 22 integration tests covering all service-layer HTTP calls. All passing with axios.
+
+Steps taken:
+1. Audited all 8 call sites for axios-specific features (interceptors, transformRequest, custom agents)
+2. Created src/utils/http.ts with fetch-based wrapper matching axios behavior (auto JSON parse, timeout via AbortController, error normalization)
+3. Migrated one service at a time, running its tests after each migration
+4. Removed axios from package.json after all call sites migrated
+
+Coverage result after: All 22 integration tests pass. No behavioral differences detected.
+
+Behavioral drift check: Compared request headers and response bodies for all 8 call sites — identical. Timeout behavior confirmed at 10s threshold.
+
+Handoff: verification-before-completion
+```
+
+## Example 3 — Sample completed output
+
+User request:
+
+```text
+Clean up the payment module — it's gotten too big.
+```
+
+### Completed output
+
+```
+Goal and scope boundary: Split src/services/PaymentService.ts (680 lines) into focused modules without changing any payment behavior.
+- In scope: PaymentService.ts, its direct imports, and related tests
+- Not in scope: API routes, database schema, external payment provider integration
+
+Behavior contract: All 14 existing tests in tests/payment.test.ts must continue to pass with identical assertions. No changes to the public API of PaymentService (same method signatures, same return types).
+
+Coverage check before: 14 tests covering charge(), refund(), listTransactions(), and webhookHandler(). No test for the internal retry logic — noted but not blocking the refactor.
+
+Steps taken:
+1. Extracted retry logic into src/services/payment/retryWithBackoff.ts
+2. Extracted webhook handling into src/services/payment/webhookHandler.ts
+3. Kept PaymentService.ts as the public facade re-exporting the split modules
+4. Updated internal imports; no changes to external callers
+
+Coverage result after: All 14 tests pass. Added 2 unit tests for retryWithBackoff to cover the newly isolated module.
+
+Behavioral drift check: Compared charge() and refund() outputs for 3 fixture inputs before and after — identical results. Webhook handler returns the same status codes for test payloads.
+
+Handoff: verification-before-completion
+```

package/skills/refactor-safe/meta.yaml

@@ -0,0 +1,28 @@
+name: refactor-safe
+version: 0.1.0
+category: implementation
+summary: Restructure code safely by preserving behavior, maintaining regression coverage, and bounding scope before touching any file.
+summary_vi: Tái cấu trúc code an toàn bằng cách giữ nguyên hành vi, duy trì regression coverage, và giới hạn phạm vi trước khi chạm file nào.
+triggers:
+  - refactor this module
+  - extract this into a shared utility
+  - clean up this file without changing behavior
+  - migrate from X to Y
+inputs:
+  - code to refactor
+  - existing test coverage
+  - stated goal and scope boundary
+outputs:
+  - scope boundary
+  - behavior contract
+  - refactor steps
+  - regression verification
+constraints:
+  - behavior must not change unless explicitly agreed
+  - scope must be fixed before starting
+  - regression coverage must be checked before and after
+related_skills:
+  - using-skills
+  - planning
+  - verification-before-completion
+  - code-review

package/skills/refactor-safe/references/output-template.md

@@ -0,0 +1,37 @@
+## Goal
+
+- Refactor goal (one sentence, no behavior change):
+
+## Scope Boundary
+
+- In scope:
+- Out of scope:
+
+## Behavior Contract
+
+- Public surface being preserved:
+- Inputs and expected outputs:
+
+## Coverage Before
+
+- Tests covering the refactored area:
+- Gaps:
+
+## Steps Taken
+
+1.
+2.
+3.
+
+## Coverage After
+
+- Test command run:
+- Result:
+
+## Behavioral Drift Check
+
+- Confirmed no change in observable behavior:
+
+## Handoff
+
+- Next skill: verification-before-completion, then code-review

package/skills/repo-onboarding/SKILL.md

@@ -0,0 +1,52 @@
+# 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).

package/skills/repo-onboarding/examples.md

@@ -0,0 +1,115 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Can you explain how this service is structured before we add a queue worker?
+```
+
+Expected result:
+
+- read top-level docs first
+- inspect runtime entrypoints and worker-related modules
+- summarize current architecture and likely integration points
+
+### Completed output — Example 1
+
+```
+Project purpose: Order processing microservice — receives orders via REST API, persists to PostgreSQL, publishes events to RabbitMQ.
+
+Architecture summary: Express.js app using a layered structure (routes → controllers → services → repositories). Bull is already listed in package.json but no active queue consumer exists.
+
+Major components:
+- src/routes/       — REST endpoint definitions
+- src/controllers/  — request handling and validation
+- src/services/     — business logic (OrderService, PaymentService)
+- src/repositories/ — Knex-based database access
+- src/events/       — RabbitMQ publisher (no consumer yet)
+
+Important commands:
+- npm run dev       — start with hot reload
+- npm test          — jest unit + integration tests
+- npm run migrate   — run Knex migrations
+
+Notable conventions:
+- All services are instantiated via a simple DI container in src/container.ts
+- Tests use a shared test database seeded per suite
+
+Open questions:
+- Is Bull the intended queue driver, or should the new worker use the existing RabbitMQ publisher?
+- Are there any existing retry/dead-letter conventions?
+
+Recommended next reads: src/events/publisher.ts, src/container.ts, config/queue.ts (if present)
+```
+
+### Completed output — Example 2
+
+```
+Project purpose: Internal dashboard for managing feature flags and A/B test configurations.
+
+First things to read:
+1. README.md — setup instructions and architecture overview (up to date, last edited 2 weeks ago)
+2. package.json scripts — `npm run dev`, `npm test`, `npm run build`, `npm run seed`
+3. src/config/ — environment variable definitions and feature flag schema
+4. prisma/schema.prisma — data model (3 main tables: Flag, Variant, Assignment)
+
+Important commands:
+- npm run dev       — Next.js dev server on port 3000
+- npm test          — Vitest test suite (47 tests, all passing)
+- npm run seed      — seed local database with sample flags
+- npx prisma studio — open database GUI
+
+Directory overview:
+- src/app/          — Next.js App Router pages and layouts
+- src/lib/          — shared utilities (flag evaluation engine, auth helpers)
+- src/components/   — React UI components
+- prisma/           — database schema and migrations
+- e2e/              — Playwright end-to-end tests
+
+Notable conventions:
+- Server components by default; client components marked with "use client"
+- Flag evaluation happens server-side via src/lib/evaluate.ts
+- Auth is handled via NextAuth with GitHub OAuth only
+
+Recommended next step: Run `npm run dev && npm run seed` to get a local instance with sample data, then explore the flag management UI at /flags.
+```
+
+## Example 3 — Sample completed output
+
+User request:
+
+```text
+Can you explain how this service is structured before we add a queue worker?
+```
+
+### Completed output
+
+```
+Project purpose: Order processing microservice — receives orders via REST API, persists to PostgreSQL, publishes events to RabbitMQ.
+
+Architecture summary: Express.js app using a layered structure (routes → controllers → services → repositories). Bull is already listed in package.json but no active queue consumer exists.
+
+Major components:
+- src/routes/       — REST endpoint definitions
+- src/controllers/  — request handling and validation
+- src/services/     — business logic (OrderService, PaymentService)
+- src/repositories/ — Knex-based database access
+- src/events/       — RabbitMQ publisher (no consumer yet)
+
+Important commands:
+- npm run dev       — start with hot reload
+- npm test          — jest unit + integration tests
+- npm run migrate   — run Knex migrations
+
+Notable conventions:
+- All services are instantiated via a simple DI container in src/container.ts
+- Tests use a shared test database seeded per suite
+
+Open questions:
+- Is Bull the intended queue driver, or should the new worker use the existing RabbitMQ publisher?
+- Are there any existing retry/dead-letter conventions?
+
+Recommended next reads: src/events/publisher.ts, src/container.ts, config/queue.ts (if present)
+```

package/skills/repo-onboarding/meta.yaml

@@ -0,0 +1,23 @@
+name: repo-onboarding
+version: 0.1.0
+category: discovery
+summary: Build a practical map of an unfamiliar repository before making claims or edits.
+summary_vi: Xây dựng bản đồ thực tế của repo lạ trước khi đưa ra nhận định hoặc sửa code.
+triggers:
+  - explain this repo
+  - onboard into a codebase
+  - understand architecture before changing code
+inputs:
+  - repository files
+  - README and operating docs when present
+outputs:
+  - architecture summary
+  - important commands
+  - open questions and next reads
+constraints:
+  - prefer source-grounded observations
+  - do not infer architecture from names alone
+related_skills:
+  - using-skills
+  - planning
+  - docs-writer

package/skills/repo-onboarding/references/output-template.md

@@ -0,0 +1,24 @@
+## Project Purpose
+
+- What the project is for
+
+## Architecture Summary
+
+- Runtime or framework:
+- Major subsystems:
+- External integrations:
+
+## Important Commands
+
+- install:
+- test:
+- build:
+- run:
+
+## Open Questions
+
+- Unknowns that still need deeper inspection
+
+## Recommended Next Reads
+
+- Files or directories to inspect next

package/skills/using-skills/SKILL.md

@@ -0,0 +1,108 @@
+# Using Skills
+
+## Purpose
+
+Use this skill first when the task shape is unclear or when a session is starting from little context.
+
+Its job is to classify the request, pick one primary skill, and define the next move.
+
+For code-changing work, prefer an explicit planning step before implementation unless the change is trivially local and already unambiguous.
+
+If the request itself is still fuzzy, use a brainstorming step before planning.
+
+## When To Use
+
+Load this skill when:
+
+- starting work in a new session
+- the user request mixes multiple intents
+- you are unsure whether the task is implementation, debugging, review, or docs
+
+## Direct Skill Trigger
+
+> `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.
+
+**Rules:**
+
+- `an:` prefix means the user already knows what they want — do not second-guess
+- if the named skill does not exist, say so and list available skills
+- still apply the planning and verification rules if relevant
+- after the triggered skill completes, return to normal workflow
+
+**Available skills:**
+
+- `an:brainstorming` — refine vague ideas before planning
+- `an:repo-onboarding` — understand an unfamiliar codebase
+- `an:planning` — create an execution-ready plan
+- `an:feature-delivery` — implement a feature
+- `an:bug-triage` — investigate errors or regressions
+- `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:docs-writer` — update documentation
+
+## 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
+   - repo understanding
+   - bug or regression investigation
+   - planning and implementation
+   - code review
+   - documentation work
+   - answer-only guidance
+3. Decide whether the task first needs brainstorming or can go straight to planning.
+4. Pick one primary skill.
+5. State the chosen skill and the immediate next step.
+6. Ask a short blocking question only if the task cannot proceed safely without it.
+
+## Routing Guide
+
+- `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
+- implement or change behavior -> `planning`, then `feature-delivery`
+- refactor, restructure, extract, or migrate without behavior change -> `planning`, then `refactor-safe`
+- review diff, PR, or changed files -> `code-review`
+- update README, runbook, onboarding docs, API notes in a known repo -> `docs-writer`
+
+## Planning Rule
+
+Use `planning` before code changes when any of these are true:
+
+- more than one file will likely change
+- the request is ambiguous or under-specified
+- the implementation touches state, data flow, API shape, or architecture boundaries
+- the user explicitly asks for a plan
+
+You may skip a separate planning step only when the change is clearly local, low-risk, and already unambiguous.
+
+## Verification Rule
+
+Use `verification-before-completion` before any strong claim that work is done, fixed, passing, or ready.
+
+## Output Format
+
+- task type
+- chosen primary skill
+- planning required
+- key assumption or missing decision, if any
+- immediate next step
+
+## Red Flags
+
+- starting code changes before understanding the request shape
+- treating a fuzzy idea as implementation-ready
+- starting multi-file code changes without an explicit plan
+- 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
+
+## Done Criteria
+
+This skill is complete when the chosen skill and the first concrete action are both stated explicitly.

package/skills/using-skills/examples.md

@@ -0,0 +1,79 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Review these changes before I merge.
+```
+
+Expected routing:
+
+- task type: code review
+- chosen skill: `code-review`
+- planning required: no
+- next step: inspect the full diff before commenting
+
+## Example 2
+
+User request:
+
+```text
+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
+
+## Example 3
+
+User request:
+
+```text
+Help me understand this repo before we add a new API endpoint.
+```
+
+Expected routing:
+
+- task type: repo understanding
+- chosen skill: `repo-onboarding`
+- planning required: not yet
+- next step: read repo docs and inspect core entrypoints
+
+## Example 4
+
+User request:
+
+```text
+Add SSO support to the admin app.
+```
+
+Expected routing:
+
+- task type: planning and implementation
+- chosen skill: `brainstorming`
+- planning required: yes
+- next step: refine the exact SSO scope and constraints before writing the implementation plan
+
+## Example 5 — Sample completed output
+
+User request:
+
+```text
+We need to speed up the product search endpoint.
+```
+
+### Completed output
+
+```
+Task type: bug investigation / performance
+Chosen primary skill: planning
+Planning required: yes — the optimization could involve query changes, caching, or index tuning; scope is unclear
+Key assumption: the bottleneck has not been profiled yet
+Immediate next step: profile the current endpoint latency and identify the dominant cost before proposing a fix
+```

package/skills/using-skills/meta.yaml

@@ -0,0 +1,29 @@
+name: using-skills
+version: 0.1.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.
+triggers:
+  - start a new session
+  - decide which skill to load
+  - handle mixed or unclear requests
+inputs:
+  - user request
+  - repo context if available
+outputs:
+  - chosen skill
+  - working mode
+  - immediate next step
+constraints:
+  - ask only the shortest blocking question when necessary
+  - prefer one primary skill at a time
+related_skills:
+  - brainstorming
+  - repo-onboarding
+  - planning
+  - bug-triage
+  - feature-delivery
+  - refactor-safe
+  - code-review
+  - verification-before-completion
+  - docs-writer

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

@@ -0,0 +1,14 @@
+## Task Shape
+
+- Type:
+- Chosen skill:
+- Planning required:
+- Why this skill:
+
+## Missing Decision
+
+- None, or the single shortest blocking question
+
+## Immediate Next Step
+
+- First concrete action to take

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

@@ -0,0 +1,46 @@
+# Verification Before Completion
+
+## Purpose
+
+Stop false completion claims by requiring fresh evidence before saying work is done, fixed, or passing.
+
+## When To Use
+
+Load this skill when:
+
+- about to claim a fix works
+- about to say tests or builds pass
+- about to mark work complete
+- about to commit, open a PR, or hand off finished work
+
+## Workflow
+
+1. Identify the exact claim being made.
+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.
+
+## Output Format
+
+- claim being checked
+- evidence run
+- result
+- final status
+- remaining uncertainty, if any
+
+## Red Flags
+
+- 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
+
+## 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`.