@anionzo/skill 1.1.0

package/skills/docs-writer/examples.md

@@ -0,0 +1,108 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Please refresh the README so setup instructions match the current app.
+```
+
+Expected result:
+
+- verify install, run, and test commands from source
+- update only the stale sections
+- note anything that still cannot be confirmed
+
+## Example 2
+
+User request:
+
+```text
+Write a short runbook for restarting the worker.
+```
+
+Expected result:
+
+- identify the real command path
+- write operator-focused steps
+- include safety notes if the restart has side effects
+
+### Completed output — Example 1
+
+```
+Target document: README.md
+
+Audience: New developers setting up the project locally.
+
+What changed:
+- Updated Node.js version requirement from 16 to 20 (verified in .nvmrc and package.json engines)
+- Replaced `npm run seed` with `npm run db:seed` (old command no longer exists in package.json)
+- Added the required REDIS_URL environment variable (added in config/default.ts 3 months ago but never documented)
+- Removed reference to deprecated /health endpoint (replaced by /api/status in src/routes/status.ts)
+
+Source of truth used:
+- package.json (engines, scripts)
+- .nvmrc
+- config/default.ts (env vars)
+- src/routes/status.ts (health check endpoint)
+
+Verification: Ran `npm install && npm run dev && curl localhost:3000/api/status` — confirmed the documented flow works end to end.
+
+Assumptions or follow-ups: The Docker setup section was not touched — it may also reference the old Node 16 base image. Worth a separate pass.
+```
+
+### Completed output — Example 2
+
+```
+Target document: docs/runbooks/restart-worker.md
+
+Audience: On-call operators who need to restart the background worker.
+
+What was written:
+- Step-by-step restart command: `kubectl rollout restart deployment/worker -n production`
+- Pre-check: verify no active jobs via `kubectl exec -it deploy/worker -- npm run jobs:status`
+- Post-check: confirm worker reconnects to RabbitMQ within 30s
+- Safety note: restarting mid-job will cause the active job to be requeued (idempotent by design)
+
+Source of truth used:
+- k8s/worker-deployment.yaml
+- src/workers/processor.ts (job idempotency contract)
+- ops/runbook-template.md (existing format reference)
+
+Verification: Ran the restart command in staging — worker reconnected in 12s, 3 in-flight jobs were requeued and completed successfully.
+
+Assumptions or follow-ups: The runbook assumes kubectl access. A CLI alias (`make restart-worker`) could be added for convenience.
+```
+
+## Example 3 — Sample completed output
+
+User request:
+
+```text
+Please refresh the README so setup instructions match the current app.
+```
+
+### Completed output
+
+```
+Target document: README.md
+
+Audience: New developers setting up the project locally.
+
+What changed:
+- Updated Node.js version requirement from 16 to 20 (verified in .nvmrc and package.json engines)
+- Replaced `npm run seed` with `npm run db:seed` (old command no longer exists in package.json)
+- Added the required REDIS_URL environment variable (added in config/default.ts 3 months ago but never documented)
+- Removed reference to deprecated /health endpoint (replaced by /api/status in src/routes/status.ts)
+
+Source of truth used:
+- package.json (engines, scripts)
+- .nvmrc
+- config/default.ts (env vars)
+- src/routes/status.ts (health check endpoint)
+
+Verification: Ran `npm install && npm run dev && curl localhost:3000/api/status` — confirmed the documented flow works end to end.
+
+Assumptions or follow-ups: The Docker setup section was not touched — it may also reference the old Node 16 base image. Worth a separate pass.
+```

package/skills/docs-writer/meta.yaml

@@ -0,0 +1,22 @@
+name: docs-writer
+version: 0.1.0
+category: documentation
+summary: Update documentation from verified source behavior so the docs stay useful and current.
+summary_vi: Cập nhật tài liệu từ hành vi nguồn đã xác minh để docs luôn hữu ích và cập nhật.
+triggers:
+  - update the README
+  - write onboarding docs
+  - refresh runbook or API notes
+inputs:
+  - current code or behavior
+  - existing documentation
+outputs:
+  - updated docs
+  - assumptions and verification notes
+constraints:
+  - prefer source-verified statements
+  - keep links repository-relative when possible
+related_skills:
+  - using-skills
+  - repo-onboarding
+  - code-review

package/skills/docs-writer/references/output-template.md

@@ -0,0 +1,17 @@
+## Target
+
+- Document:
+- Audience:
+
+## Update Summary
+
+- Sections changed:
+- Why they changed:
+
+## Verification
+
+- Source files or commands checked:
+
+## Follow-Up
+
+- Assumptions or remaining gaps

package/skills/feature-delivery/SKILL.md

@@ -0,0 +1,39 @@
+# Feature Delivery
+
+## Purpose
+
+Implement a feature with a minimal, repo-aligned change that is verified before handoff.
+
+## When To Use
+
+Load this skill when the user wants code changed to add or update behavior.
+
+## Workflow
+
+1. Restate the desired outcome in user-visible terms.
+2. Inspect the existing code paths and nearby patterns before designing the change.
+3. Choose the smallest approach that fits the current architecture.
+4. Make the change.
+5. Verify it with the most relevant checks available, such as tests, typecheck, or targeted runtime validation.
+6. Summarize what changed, why the approach was chosen, and what remains uncertain.
+
+## Output Format
+
+- goal and scope
+- chosen approach
+- files changed
+- verification performed
+- follow-up or risk note
+
+## Red Flags
+
+- introducing new abstractions before checking existing patterns
+- widening scope during implementation without calling it out
+- stopping after code edits without verification
+- describing code changes only in implementation terms instead of user impact
+
+## Done Criteria
+
+This skill is complete when the feature works as intended, the change is verified with the most relevant check available, and the outcome is summarized clearly.
+
+Before declaring done, run `verification-before-completion` to confirm the claim is backed by fresh evidence.

package/skills/feature-delivery/examples.md

@@ -0,0 +1,83 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Add an export CSV button to the orders page.
+```
+
+Expected result:
+
+- inspect the orders page and nearby action patterns
+- implement the smallest UI and backend change needed
+- verify export behavior and summarize any edge cases left open
+
+### Completed output — Example 1
+
+```
+Goal and scope: Add a "Export CSV" button to the orders list page that downloads the currently filtered orders as a CSV file.
+
+Chosen approach: Added a server-side endpoint (GET /api/orders/export?filters=...) that streams CSV rows using the existing OrderService query. The frontend button calls this endpoint and triggers a browser download via a hidden anchor element — same pattern used by the existing invoice export.
+
+Files changed:
+- src/routes/orders.ts          — new GET /api/orders/export route
+- src/services/OrderService.ts  — added toCsvStream() method
+- src/pages/OrdersPage.tsx      — added ExportButton component next to existing filter bar
+- tests/orders.export.test.ts   — new integration test for the export endpoint
+
+Verification performed: ran `npm test -- orders.export` — 3/3 tests passing (empty result, normal result, filtered result). Manual check: downloaded CSV opens correctly in LibreOffice.
+
+Follow-up: Large exports (>50k rows) may need streaming pagination. Not blocking for current usage but worth a ticket.
+
+Handoff: verification-before-completion
+```
+
+### Completed output — Example 2
+
+```
+Goal and scope: Add email-based filtering to the audit logs page without changing the existing query architecture.
+
+Chosen approach: Extended the existing audit log query builder to accept an `actor_email` filter parameter. Added a text input to the audit log filter bar. The query uses a LEFT JOIN to the users table to match email — no schema change needed.
+
+Files changed:
+- src/routes/audit.ts           — added actor_email query param handling
+- src/services/AuditService.ts  — extended listAuditLogs() to accept actorEmail filter
+- src/pages/AuditLogsPage.tsx   — added email filter input to filter bar
+- tests/audit.filter.test.ts    — new test for email filtering
+
+Verification performed: ran `npm test -- audit` — 5/5 tests passing. Manual check: filtering by "admin@example.com" returns correct subset.
+
+Follow-up: The email join could be slow on large tables without an index. Current dataset is <100k rows so not urgent.
+
+Handoff: verification-before-completion
+```
+
+## Example 3 — Sample completed output
+
+User request:
+
+```text
+Add an export CSV button to the orders page.
+```
+
+### Completed output
+
+```
+Goal and scope: Add a "Export CSV" button to the orders list page that downloads the currently filtered orders as a CSV file.
+
+Chosen approach: Added a server-side endpoint (GET /api/orders/export?filters=...) that streams CSV rows using the existing OrderService query. The frontend button calls this endpoint and triggers a browser download via a hidden anchor element — same pattern used by the existing invoice export.
+
+Files changed:
+- src/routes/orders.ts          — new GET /api/orders/export route
+- src/services/OrderService.ts  — added toCsvStream() method
+- src/pages/OrdersPage.tsx      — added ExportButton component next to existing filter bar
+- tests/orders.export.test.ts   — new integration test for the export endpoint
+
+Verification performed: ran `npm test -- orders.export` — 3/3 tests passing (empty result, normal result, filtered result). Manual check: downloaded CSV opens correctly in LibreOffice.
+
+Follow-up: Large exports (>50k rows) may need streaming pagination. Not blocking for current usage but worth a ticket.
+
+Handoff: verification-before-completion
+```

package/skills/feature-delivery/meta.yaml

@@ -0,0 +1,26 @@
+name: feature-delivery
+version: 0.1.0
+category: implementation
+summary: Deliver a small or medium feature by following existing patterns and making the smallest correct change.
+summary_vi: Triển khai feature nhỏ hoặc vừa bằng cách theo pattern có sẵn và thực hiện thay đổi đúng nhỏ nhất.
+triggers:
+  - implement this feature
+  - add this behavior
+  - wire this new capability in
+inputs:
+  - user request
+  - relevant repo context
+  - existing patterns in the codebase
+outputs:
+  - chosen approach
+  - files changed
+  - verification performed
+constraints:
+  - inspect existing patterns before inventing new structure
+  - ask only one blocking question when necessary
+related_skills:
+  - using-skills
+  - planning
+  - repo-onboarding
+  - verification-before-completion
+  - code-review

package/skills/feature-delivery/references/output-template.md

@@ -0,0 +1,26 @@
+## Goal
+
+- User-visible outcome:
+- Scope boundary:
+
+## Approach
+
+- Existing pattern followed:
+- Why this approach:
+
+## Files Changed
+
+- List of files modified or created:
+
+## Verification
+
+- Commands or checks run:
+- Result:
+
+## Follow-Up
+
+- Remaining risk or next step:
+
+## Handoff
+
+- Next skill to invoke (verification-before-completion, code-review, or done):

package/skills/planning/SKILL.md

@@ -0,0 +1,61 @@
+# Planning
+
+## Purpose
+
+Produce an execution-ready plan before code changes begin.
+
+This skill exists to make planning explicit, especially for multi-file or non-trivial work.
+
+## When To Use
+
+Load this skill when:
+
+- the task will likely change more than one file
+- the request is still ambiguous after initial reading
+- the change touches APIs, data flow, persistence, or architecture boundaries
+- the user explicitly asks for a plan
+- implementation risk is high enough that code should not start immediately
+
+## Workflow
+
+1. Restate the goal in user-visible terms.
+2. Define the scope boundary:
+   - what is in scope
+   - what is out of scope
+3. Inspect the existing code paths and patterns that the work should follow.
+4. Choose the smallest viable approach that fits the repo.
+5. Break the work into ordered steps.
+6. Call out risks, assumptions, and missing decisions.
+7. Define how the work will be verified.
+8. End with the next implementation skill to invoke.
+
+## Output Format
+
+- goal
+- scope
+- existing patterns or files to follow
+- proposed approach
+- ordered implementation steps
+- risks and assumptions
+- verification plan
+- next skill to invoke
+
+## Planning Rules
+
+- Keep the plan concrete enough that another engineer could execute it.
+- Prefer a small number of meaningful steps over a long task dump.
+- Name the files, modules, or surfaces likely to change when possible.
+- Make uncertainty explicit instead of hiding it in vague language.
+- Do not start coding inside the plan.
+
+## Red Flags
+
+- jumping from request to code without checking current patterns
+- writing a plan so abstract that it does not guide implementation
+- turning the plan into a full design doc for a small change
+- leaving verification unspecified
+- mixing code edits into the planning phase
+
+## Done Criteria
+
+This skill is complete when the implementation path, risks, and verification steps are clear enough to hand off to `feature-delivery`, `refactor-safe`, or to a bounded bug fix.

package/skills/planning/examples.md

@@ -0,0 +1,124 @@
+# Examples
+
+## Example 1
+
+User request:
+
+```text
+Add SSO login to the admin dashboard.
+```
+
+Expected result:
+
+- inspect the current auth flow and integration points
+- define what parts of the login system will change
+- produce a bounded implementation plan before any code changes begin
+
+Sample completed output:
+
+```
+Goal: Allow admin users to log in via SSO using SAML instead of local credentials.
+
+Scope:
+- In scope: SAML assertion parsing, session creation after SSO, admin login page update
+- Out of scope: User-facing login, MFA changes, password migration
+
+Current Pattern:
+- src/auth/local.ts handles current login flow
+- sessions are created in src/auth/session.ts
+
+Proposed Approach:
+- Add a SAML callback route that validates assertions and delegates to session.ts
+- Update the admin login page to show SSO button
+
+Steps:
+1. Add saml-passport library and wire callback route
+2. Extract session-creation logic into shared helper
+3. Update admin login UI
+4. Add integration test for SAML callback
+
+Risks: SAML IdP metadata must be confirmed before step 1
+Verification: run auth integration tests; manually test SSO callback with IdP
+Handoff: feature-delivery
+```
+
+## Example 2
+
+User request:
+
+```text
+Plan the work to support soft delete on customers.
+```
+
+Expected result:
+
+- identify data model, query, and UI surfaces affected
+- define scope and rollback or migration risks
+- specify verification before implementation starts
+
+### Completed output — Example 2
+
+```
+Goal: Add soft delete support for customers — records should be marked as deleted rather than removed from the database.
+
+Scope:
+- In scope: Customer model (add deletedAt column), all queries that read/update customers, admin UI to show/hide deleted records
+- Out of scope: Hard delete migration for existing data, cascade soft delete for related orders/transactions
+
+Current Pattern:
+- src/models/Customer.ts — Prisma model, no soft delete support
+- src/services/CustomerService.ts — CRUD operations using direct Prisma calls
+- src/routes/customers.ts — REST endpoints, no filtering for deleted records
+- Admin UI at /admin/customers — lists all customers with no deleted/active distinction
+
+Proposed Approach:
+- Add deletedAt DateTime? column to Customer model via Prisma migration
+- Update all CustomerService queries to filter `where: { deletedAt: null }` by default
+- Add restoreCustomer() method to CustomerService
+- Add a "Show deleted" toggle to the admin UI
+
+Steps:
+1. Prisma migration: add deletedAt column, backfill existing records as null
+2. Update CustomerService list/get/update to exclude soft-deleted records
+3. Add deleteCustomer() (sets deletedAt) and restoreCustomer() methods
+4. Update admin UI with deleted/active toggle
+5. Add integration tests for soft delete and restore flows
+
+Risks:
+- Related tables (orders, transactions) still reference soft-deleted customers — need to decide if they should be hidden too
+- Any external integrations that sync customer data may not handle soft-deleted records
+
+Verification: Run customer-related test suite (18 tests); manually verify admin UI shows/hides deleted records; confirm API returns 404 for deleted customer details endpoint.
+
+Handoff: feature-delivery
+```
+
+### Completed output — Example 3
+
+```
+Goal: Fix the API timeout issue that occurs under load (>100 concurrent requests).
+
+Summary after triage context:
+- Timeouts occur on GET /api/reports endpoint when >100 concurrent requests hit
+- Root cause identified: each request triggers a full table scan on the reports table (no index on the date range filter)
+- The reports table has 2M+ rows and the query filters by createdAt range without an index
+
+Proposed Approach:
+- Add a composite index on (createdAt, status) to speed up the date range filter
+- Add query result caching (5-minute TTL) for identical report requests
+- Set a query timeout of 10s to fail fast instead of hanging
+
+Steps:
+1. Add Prisma migration for the composite index
+2. Add Redis caching layer for report queries (cache key: hash of query params)
+3. Set query timeout in the database connection string
+4. Load test with k6 to confirm timeout is resolved at 200 concurrent requests
+
+Risks:
+- The index will take ~30s to build on production (2M rows) — should use CONCURRENTLY
+- Redis caching adds a new dependency — need to confirm Redis is available in production
+
+Verification: Run k6 load test at 200 concurrent requests — p99 latency should be <2s (currently >30s timeout).
+
+Handoff: feature-delivery
+```

package/skills/planning/meta.yaml

@@ -0,0 +1,29 @@
+name: planning
+version: 0.1.0
+category: planning
+summary: Turn a request into an execution-ready plan with scope, approach, risks, and verification before code changes begin.
+summary_vi: Biến request thành plan sẵn sàng thực thi với phạm vi, cách tiếp cận, rủi ro, và xác minh trước khi bắt đầu code.
+triggers:
+  - make a plan
+  - think through the implementation first
+  - prepare before coding
+inputs:
+  - user request
+  - relevant repo context
+  - existing patterns and constraints
+outputs:
+  - scope
+  - approach
+  - file plan
+  - verification plan
+constraints:
+  - keep the plan concrete and bounded
+  - separate planning from implementation
+related_skills:
+  - using-skills
+  - brainstorming
+  - repo-onboarding
+  - feature-delivery
+  - bug-triage
+  - refactor-safe
+  - verification-before-completion

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

@@ -0,0 +1,37 @@
+## Goal
+
+- User-visible outcome:
+
+## Scope
+
+- In scope:
+- Out of scope:
+
+## Current Pattern
+
+- Files or modules to follow:
+- Relevant existing behavior:
+
+## Proposed Approach
+
+- Chosen approach:
+- Why this approach:
+
+## Steps
+
+1. 
+2. 
+3. 
+
+## Risks And Assumptions
+
+- Risk:
+- Assumption:
+
+## Verification
+
+- Tests or checks:
+
+## Handoff
+
+- Next skill to invoke:

package/skills/refactor-safe/SKILL.md

@@ -0,0 +1,53 @@
+# Refactor Safe
+
+## Purpose
+
+Restructure code without changing behavior.
+
+## When To Use
+
+Load this skill when:
+
+- the user wants to move, rename, extract, or reorganize code without adding features
+- a module has grown too large and needs splitting
+- a pattern is being replaced across a bounded area
+- cleanup is needed before a new feature touches the same code
+
+Do not use this skill when the intent is also to change behavior. Separate the refactor from the feature change — do one at a time.
+
+## Workflow
+
+1. State the goal in one sentence and confirm it does not include behavior changes.
+2. Define the scope boundary explicitly:
+   - which files, functions, or modules are in scope
+   - what is not in scope
+3. Check the current regression coverage for the area:
+   - identify which tests cover the code being refactored
+   - note any gaps before starting
+4. Write or tighten regression tests if the coverage is insufficient to protect the refactor.
+5. Make the structural change.
+6. Run the full relevant test suite and confirm it passes.
+7. Check for behavioral drift: compare inputs and outputs of the refactored surface at the boundary.
+8. Run `verification-before-completion` before declaring the refactor done.
+
+## Output Format
+
+- goal and scope boundary
+- behavior contract
+- coverage check before
+- steps taken
+- coverage result after
+- behavioral drift check
+- handoff or follow-up
+
+## Red Flags
+
+- starting the refactor before checking current test coverage
+- changing behavior while "just refactoring"
+- expanding scope mid-refactor without calling it out
+- declaring done based on "looks right" without running tests
+- mixing a refactor commit with a feature change commit
+
+## Done Criteria
+
+This skill is complete when the test suite passes, no behavioral drift is detected at the refactored surface, and the verification field is populated with actual test output.