@votruongdanh/ai-agent-skills 3.3.3 → 3.3.4

package/skills/create/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: create
+description: "Build new features, files, components, endpoints, pages, or scripts. Use when the user wants to create something new in the codebase. Triggers: create, build, add, new, scaffold, tạo, thêm mới, tạo trang, tạo API."
+agents: [backend-specialist, frontend-specialist, database-architect]
+related-skills: [plan, test, debug]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check tech stack, coding conventions, existing patterns, architecture decisions, and file structure notes.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: what was created, files touched, patterns used, decisions, and follow-ups.
+
+## Goal
+Create a new implementation cleanly and with minimal disruption.
+
+## Agent Routing
+- If creating API/backend → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+- If creating UI component/page → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If creating database schema/migration → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+- If creating tests → read `.kiro/skills/agents/agents/test-engineer.md` and apply its knowledge
+- If creating deployment config → read `.kiro/skills/agents/agents/devops-engineer.md` and apply its knowledge
+
+## Socratic Gate
+Before creating, verify:
+1. What exactly should be created? (component, page, API, script?)
+2. Does something similar already exist in the project?
+3. What is the expected behavior/output?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context, conventions, and patterns.
+2. Understand the requested artifact and the existing project structure.
+3. Identify the smallest complete implementation that satisfies the request.
+4. Create or update the necessary files only.
+5. Reuse existing patterns, naming, and architecture already present in the repo.
+6. Include basic validation and error handling.
+7. Add brief usage notes, edge cases, and follow-up improvements.
+8. **Update Memory** — Save what was created, patterns used, and follow-up notes to `.ai-memory.md`.
+
+## Checklist
+- [ ] Requirement clearly understood
+- [ ] Existing patterns/conventions checked
+- [ ] Minimal files created/modified
+- [ ] Validation and error handling included
+- [ ] Project conventions matched (naming, structure)
+- [ ] Tests added if test framework exists
+- [ ] Usage notes provided
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Prefer incremental changes over large rewrites.
+- Match the project's conventions.
+- Include basic validation and error handling.
+- If tests exist nearby, add or update them when appropriate.
+- Avoid changing unrelated files; if unsure about side effects, ASK before editing broadly.
+- Always read and update the memory file.
+
+## Quality Gate
+After completing, read `.kiro/skills/_scripts/checklist.md` for cross-cutting quality checks.
+
+## Related Skills
+- `/plan` → read `.kiro/skills/plan/SKILL.md` — Plan before creating complex features
+- `/test` → read `.kiro/skills/test/SKILL.md` — Write tests for new code
+- `/debug` → read `.kiro/skills/debug/SKILL.md` — Fix issues in newly created code

package/skills/debug/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: debug
+description: "Root-cause analysis for bugs, failing commands, broken behavior, and error logs. Use when the user encounters errors, crashes, or unexpected behavior. Triggers: debug, fix, bug, error, crash, lỗi, sửa lỗi, hỏng, fail."
+agents: [debugger, backend-specialist, frontend-specialist]
+related-skills: [test, enhance, status]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check for known bugs, past fixes, tech stack details, common error patterns, and architecture notes.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: bug, root cause, fix, files touched, lessons learned, and remaining risks.
+
+## Goal
+Find the real root cause, not just the first visible symptom.
+
+## Agent Routing
+- If bug is in API/server/backend → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+- If bug is in UI/rendering/CSS → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If bug is in database/queries → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+- If bug may be a security issue → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+- Default → read `.kiro/skills/agents/agents/debugger.md` and apply its systematic analysis
+
+## Socratic Gate
+Before debugging, verify:
+1. What is the expected behavior vs actual behavior?
+2. Is there a log, stacktrace, or error message?
+3. When did this start? (recent change, always broken, intermittent?)
+4. Have we tried this before?
+If any answer is missing, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context and past bug history.
+2. Summarize the bug, expected behavior, and actual behavior.
+3. Gather evidence from logs, stack traces, code paths, config, and recent changes.
+4. List the top hypotheses ranked by likelihood. **Eliminate previously failed hypotheses immediately.**
+5. Eliminate hypotheses using direct evidence.
+6. Identify the root cause and confirm with evidence before attempting any code changes.
+7. Propose an effective solution that addresses the root cause definitively. **Ensure clean code standards are met and fully update all related files.**
+8. Suggest how to verify the fix and prevent regressions.
+9. **Quality Gate** — Read `.kiro/skills/_scripts/checklist.md` and run cross-cutting quality checks.
+10. **Update Memory** — Save root cause, fix, and lessons to `.ai-memory.md`.
+
+## Output format
+- Symptom
+- Evidence collected
+- Failed Attempts (to avoid repetition)
+- Hypotheses (ranked by likelihood)
+- Root cause
+- Fix (Clean code & complete file updates)
+- Verification steps
+- Regression prevention
+
+## Checklist
+- [ ] Bug clearly described (expected vs actual)
+- [ ] Past failed attempts reviewed to prevent loop
+- [ ] Evidence gathered and root cause definitively confirmed
+- [ ] Hypotheses listed and ranked
+- [ ] Root cause confirmed with evidence
+- [ ] Fix is effective and addresses root cause directly
+- [ ] No side effects introduced
+- [ ] Verification steps provided
+- [ ] Regression prevention suggested
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Do not guess when evidence is missing; say what must be checked.
+- Prefer deterministic reproduction steps.
+- Mention any hidden risk or side effect of the fix.
+- Avoid changing unrelated files; if a fix seems wide-impact, ASK before proceeding.
+- Always read and update the memory file.
+
+## Related Skills
+- `/test` → read `.kiro/skills/test/SKILL.md` — Write tests to prevent regression
+- `/enhance` → read `.kiro/skills/enhance/SKILL.md` — Improve code quality after fixing
+- `/status` → read `.kiro/skills/status/SKILL.md` — Check project health after fix

package/skills/deploy/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: deploy
+description: "Deployment steps, release preparation, environment setup, CI/CD guidance, and production rollout. Use when the user wants to deploy, release, or set up infrastructure. Triggers: deploy, release, CI/CD, docker, production, triển khai, phát hành, đưa lên production."
+agents: [devops-engineer, security-auditor]
+related-skills: [test, status, plan]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check deployment history, target environments, known infrastructure, CI/CD setup, past deployment issues.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: target, steps, env details, issues, rollback notes, and infra decisions.
+
+## Goal
+Prepare a safe, repeatable deployment or release plan.
+
+## Agent Routing
+- For infrastructure/CI/CD → read `.kiro/skills/agents/agents/devops-engineer.md` and apply its knowledge
+- For security review before deploy → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+- For database migrations → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+- For performance validation → read `.kiro/skills/agents/agents/performance-optimizer.md` and apply its knowledge
+
+## Socratic Gate
+Before deploying, verify:
+1. What is the target environment? (staging, production, preview?)
+2. Are all tests passing?
+3. Are there database migrations or breaking changes?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for deployment history and environment details.
+2. Detect the app type, runtime, dependencies, and target environment.
+3. List prerequisites: secrets, env vars, build steps, infrastructure, database migrations, and health checks.
+4. Produce a deployment sequence from pre-checks to rollback.
+5. Call out risky steps explicitly.
+6. Include post-deploy verification and monitoring.
+7. **Quality Gate** — Read `.kiro/skills/_scripts/pre-deploy.md` for pre-deploy checklist, then `.kiro/skills/_scripts/checklist.md` for cross-cutting checks.
+8. **Update Memory** — Save deployment details and outcomes to `.ai-memory.md`.
+
+## Output format
+- Target environment
+- Preconditions
+- Deployment steps (numbered, with risk flags)
+- Verification (health checks, smoke tests)
+- Rollback plan
+
+## Checklist
+- [ ] Target environment confirmed
+- [ ] All tests passing
+- [ ] Secrets/env vars configured
+- [ ] Database migrations planned
+- [ ] Build artifacts ready
+- [ ] Rollback plan documented
+- [ ] Health checks defined
+- [ ] Post-deploy verification planned
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Prefer least-risk rollout patterns.
+- Never expose secrets.
+- Distinguish clearly between required and optional steps.
+- Avoid unrelated infra/app changes; if a deployment step requires broad refactors, ASK first.
+- Always read and update the memory file.
+
+## Related Skills
+- `/test` → read `.kiro/skills/test/SKILL.md` — Run tests before deployment
+- `/status` → read `.kiro/skills/status/SKILL.md` — Check project readiness
+- `/plan` → read `.kiro/skills/plan/SKILL.md` — Plan complex deployment sequences

package/skills/enhance/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: enhance
+description: "Improve existing code — refactor, optimize performance, tighten security, or enhance UX. Use when the user wants to make code better without changing its purpose. Triggers: enhance, improve, refactor, optimize, review, cải thiện, tối ưu, nhanh hơn, code dài quá."
+agents: [performance-optimizer, security-auditor, frontend-specialist]
+related-skills: [debug, test, plan]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check past enhancements, known pain points, tech debt notes, performance baselines, and architecture decisions.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: what changed, impact, tradeoffs, and remaining tech debt.
+
+## Goal
+Improve an existing implementation without breaking working behavior.
+
+## Agent Routing
+- If enhancing performance → read `.kiro/skills/agents/agents/performance-optimizer.md` and apply its knowledge
+- If tightening security → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+- If improving UI/UX → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If refactoring backend/API → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+- If improving database queries → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+
+## Socratic Gate
+Before enhancing, verify:
+1. What specific aspect needs improvement? (performance, security, UX, maintainability?)
+2. What is the current pain point or metric?
+3. Are there existing tests that must continue to pass?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context and past enhancement history.
+2. Understand the current state and pain points.
+3. Identify high-impact improvements in quality, maintainability, performance, reliability, or UX.
+4. Prioritize improvements by value versus effort.
+5. Implement or recommend the top changes.
+6. Explain tradeoffs and validation steps.
+7. **Quality Gate** — Read `.kiro/skills/_scripts/checklist.md` and verify enhancements don't break existing behavior.
+8. **Update Memory** — Save enhancement details and outcomes to `.ai-memory.md`.
+
+## Checklist
+- [ ] Current state documented
+- [ ] Pain points identified
+- [ ] Improvements prioritized by value/effort
+- [ ] Existing behavior preserved
+- [ ] Tradeoffs explained
+- [ ] Tests still passing
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Preserve behavior unless the user asked for a behavior change.
+- Prefer small, meaningful upgrades over broad rewrites.
+- If performance is discussed, explain where the gain comes from.
+- Avoid changing unrelated files; if improvement requires broad refactor, ASK before doing it.
+- Always read and update the memory file.
+
+## Related Skills
+- `/debug` → read `.kiro/skills/debug/SKILL.md` — Fix issues found during enhancement
+- `/test` → read `.kiro/skills/test/SKILL.md` — Verify enhancements don't break things
+- `/plan` → read `.kiro/skills/plan/SKILL.md` — Plan large-scale refactoring

package/skills/explain/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: explain
+description: "Explain code, walk through logic, and help understand architecture or behavior. Use when the user asks what code does, how something works, or wants a walkthrough. Triggers: explain, what does this do, how does this work, giải thích, giải thích code, code này làm gì."
+agents: [documentation-writer, backend-specialist, frontend-specialist]
+related-skills: [debug, enhance, status]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Check tech stack, architecture notes, past explanations, and domain context.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: what was explained, key insights, misconceptions clarified, and follow-ups.
+
+## Goal
+Help the user deeply understand code, logic, architecture, or behavior — at the level of detail they need.
+
+## Agent Routing
+- If explaining backend/API logic → read `.kiro/skills/agents/agents/backend-specialist.md` and apply its knowledge
+- If explaining UI/component behavior → read `.kiro/skills/agents/agents/frontend-specialist.md` and apply its knowledge
+- If explaining database schema/queries → read `.kiro/skills/agents/agents/database-architect.md` and apply its knowledge
+- If explaining security mechanisms → read `.kiro/skills/agents/agents/security-auditor.md` and apply its knowledge
+- Default → read `.kiro/skills/agents/agents/documentation-writer.md` for clear, structured explanation
+
+## Socratic Gate
+Before explaining, verify:
+1. Which file, function, or code block should be explained?
+2. What level of detail? (high-level overview vs line-by-line walkthrough)
+3. What is the user's familiarity level with this area?
+If any answer is unclear, ASK before proceeding.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for project context, tech stack, and architecture.
+2. Read the target code thoroughly — understand intent, not just syntax.
+3. Identify the explanation scope: single function, module, data flow, or architecture.
+4. Explain at the requested level:
+   - **High-level**: Purpose, inputs/outputs, how it fits in the system.
+   - **Detailed**: Step-by-step logic, control flow, edge cases, design decisions.
+   - **Line-by-line**: What each line does and why.
+5. Highlight non-obvious logic, hidden side effects, and design trade-offs.
+6. Use analogies or diagrams if the concept is complex.
+7. Suggest follow-up topics if relevant (e.g., "you may also want to understand X").
+8. **Quality Gate** — Read `.kiro/skills/_scripts/checklist.md` for cross-cutting checks.
+9. **Update Memory** — Save explanation context and insights to `.ai-memory.md`.
+
+## Output format
+- **What it does**: One-sentence summary
+- **How it works**: Step-by-step explanation at the requested level
+- **Key design decisions**: Why it was built this way
+- **Non-obvious details**: Edge cases, side effects, gotchas
+- **Related context**: Connected files/modules worth understanding
+
+## Checklist
+- [ ] Target code identified and read
+- [ ] Explanation level matches user need
+- [ ] Logic explained clearly, not just syntax described
+- [ ] Non-obvious details highlighted
+- [ ] Design decisions explained
+- [ ] Follow-up suggestions provided
+- [ ] Memory file updated
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules
+- Explain the WHY, not just the WHAT — developers can read syntax themselves.
+- Match explanation depth to the user's familiarity level.
+- If the code is unclear or has issues, mention them without derailing the explanation.
+- Avoid proposing wide changes mid-explanation; if improvement requires broader edits, ASK before switching to implementation.
+- Always read and update the memory file.
+
+## Related Skills
+- `/debug` → read `.kiro/skills/debug/SKILL.md` — If explanation reveals bugs
+- `/enhance` → read `.kiro/skills/enhance/SKILL.md` — If explanation reveals improvement opportunities
+- `/status` → read `.kiro/skills/status/SKILL.md` — For project-wide understanding

package/skills/instructions.md

@@ -0,0 +1,95 @@
+## AI Agent Skills — System Bootstrap
+
+This project uses an **AI Skills system** with 16 skills, 11 specialist agents, and a memory protocol.
+
+### On EVERY request, follow this flow:
+
+0. **Validate input**:
+   - If the message is empty or contains no meaningful content → Respond with a friendly greeting, list the available skills below with one-line descriptions, and ask what the user would like to work on. Do NOT proceed to classification.
+   - If the message is a greeting ("hi", "hello", "hey", "xin chào", "chào") → Respond warmly, briefly list what you can help with (the skills below), and ask how you can help. Do NOT proceed to classification.
+
+1. **Read memory**:
+   - If `.ai-memory.md` exists in project root, read it first for context.
+   - If Codex memory directories exist (`memories/`, `memories/session/`, `memories/repo/`), read relevant notes from `memories/repo/`.
+   - If `.ai-memory.md` doesn't exist, create it after completing the first task using the template at the end of this file.
+
+2. **Classify the request** — Match to one of these skills:
+
+   | Command | Skill file to read | When to use |
+   |---------|-------------------|-------------|
+   | `/brainstorm` | `.kiro/skills/brainstorm/SKILL.md` | Explore options, ideate solutions |
+   | `/plan` | `.kiro/skills/plan/SKILL.md` | Create implementation plan with milestones |
+   | `/create` | `.kiro/skills/create/SKILL.md` | Build new feature/file/component |
+   | `/debug` | `.kiro/skills/debug/SKILL.md` | Fix bugs, analyze errors |
+   | `/test` | `.kiro/skills/test/SKILL.md` | Write tests, improve coverage |
+   | `/enhance` | `.kiro/skills/enhance/SKILL.md` | Improve existing code without breaking it |
+   | `/deploy` | `.kiro/skills/deploy/SKILL.md` | Deployment and release guidance |
+   | `/clean` | `.kiro/skills/clean/SKILL.md` | Remove junk files, clean up |
+   | `/status` | `.kiro/skills/status/SKILL.md` | Project status summary |
+   | `/preview` | `.kiro/skills/preview/SKILL.md` | Preview output/UX before implementing |
+   | `/orchestrate` | `.kiro/skills/orchestrate/SKILL.md` | Coordinate multi-step workflows |
+   | `/ui-ux-pro-max` | `.kiro/skills/ui-ux-pro-max/SKILL.md` | Advanced UI/UX improvements |
+   | `/motion-ui` | `.kiro/skills/motion-ui/SKILL.md` | Motion UI with Framer Motion micro-interactions |
+   | `/explain` | `.kiro/skills/explain/SKILL.md` | Explain code, walk through logic, understand architecture |
+   | `/integrate` | `.kiro/skills/integrate/SKILL.md` | Integrate provided sample code with minimal impact |
+
+3. **If the request is vague/general** (no clear skill match):
+   - "Help me with this project" → Read `.kiro/skills/status/SKILL.md` first, then suggest next steps
+   - "Review my code" → Read `.kiro/skills/enhance/SKILL.md` with all agents (not just performance)
+   - "I'm stuck" / "What should I do?" → Read `.kiro/skills/status/SKILL.md` then `.kiro/skills/plan/SKILL.md`
+   - "Make this better" → Read `.kiro/skills/enhance/SKILL.md`
+   - "Explain this code" / "What does this do?" / "giải thích code" → Read `.kiro/skills/explain/SKILL.md`
+   - Complaints about code quality ("too long", "messy", "sao dài quá", "rối quá") → Read `.kiro/skills/enhance/SKILL.md` or `.kiro/skills/clean/SKILL.md`
+   - Any multi-step or complex request → Read `.kiro/skills/orchestrate/SKILL.md`
+   - If still unclear → Read `.kiro/skills/agents/SKILL.md` and use @orchestrator to triage
+
+4. **Load the agent**: Each skill specifies agents. To load an agent persona, read its file:
+
+   | Agent handle | File to read |
+   |-------------|-------------|
+   | `@debugger` | `.kiro/skills/agents/agents/debugger.md` |
+   | `@backend-specialist` | `.kiro/skills/agents/agents/backend-specialist.md` |
+   | `@frontend-specialist` | `.kiro/skills/agents/agents/frontend-specialist.md` |
+   | `@database-architect` | `.kiro/skills/agents/agents/database-architect.md` |
+   | `@security-auditor` | `.kiro/skills/agents/agents/security-auditor.md` |
+   | `@devops-engineer` | `.kiro/skills/agents/agents/devops-engineer.md` |
+   | `@test-engineer` | `.kiro/skills/agents/agents/test-engineer.md` |
+   | `@performance-optimizer` | `.kiro/skills/agents/agents/performance-optimizer.md` |
+   | `@documentation-writer` | `.kiro/skills/agents/agents/documentation-writer.md` |
+   | `@orchestrator` | `.kiro/skills/agents/agents/orchestrator.md` |
+   | `@project-planner` | `.kiro/skills/agents/agents/project-planner.md` |
+
+5. **Execute the skill workflow** — Follow the steps in the SKILL.md file.
+
+6. **Run quality checks**: Read `.kiro/skills/_scripts/checklist.md` for cross-cutting checks.
+
+7. **Update memory**:
+   - Save findings to `.ai-memory.md` using the **Memory Compaction Rules** in `.ai-memory.md` (short bullets, dedupe, enforce section limits).
+   - If `memories/repo/` exists (Codex layout), mirror the most important 1-3 bullets into a repo memory note.
+   - If you notice duplicates, apply `.kiro/skills/_scripts/memory-dedupe.md` and merge bullets instead of appending.
+   - If `.ai-memory.md` exceeds 500 lines or sections exceed limits, apply `.kiro/skills/_scripts/memory-compact.md` to compact it.
+
+### .ai-memory.md Template (create if not exists)
+
+```markdown
+# Project Memory
+
+## Tech Stack
+- Language: (detected)
+- Framework: (detected)
+- Database: (if any)
+- Package manager: (detected)
+
+## Architecture
+- Pattern: (detected)
+- Key directories: (discovered)
+
+## Decisions
+- (date) Decision and rationale
+
+## Known Issues
+- (none yet)
+
+## Recent Work
+- (none yet)
+```

package/skills/integrate/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: integrate
+description: "Integrate provided sample code/snippets into the existing system with minimal changes and minimal risk. Use when the user gives a code mẫu and wants to merge it into current project. Triggers: integrate, merge snippet, gộp code mẫu, ghép code, áp code mẫu vào hệ thống."
+agents: [backend-specialist, frontend-specialist, debugger]
+related-skills: [plan, test, debug, enhance]
+---
+
+## Memory Protocol
+**START**: Read `.ai-memory.md` from project root. Focus on: entry points, key directories, conventions, and any integration decisions already logged.
+**END**: Update `.ai-memory.md` using **Memory Compaction Rules** with: integration points, files touched, behavior changes (if any), and verification notes.
+
+## Goal
+Merge the requested sample code into the current codebase **without broad refactors**, keeping behavior stable and avoiding changes to unrelated files.
+
+## Socratic Gate (ask if missing)
+Before editing, verify these inputs exist. If any is missing or ambiguous, ASK:
+1. The **sample code** to integrate (full snippet + expected behavior).
+2. The **target location** in this project (file/module/feature area).
+3. Constraints: must keep API stable? must keep UI stable? backward compatible?
+
+- [ ] Clean code chuẩn (Standard clean code applied)
+- [ ] Cập nhật đầy đủ tất cả các file liên quan (All related files fully updated)
+
+## Rules (Blast-radius control)
+- Touch the **smallest** possible set of files.
+- Do **not** reformat or restructure unrelated code.
+- Prefer **adapters/wrappers** over rewriting existing modules.
+- If the integration requires changing shared interfaces, introduce compatibility shims (or feature flag) instead of breaking changes.
+- If uncertain about side effects, **stop and ask** rather than guessing.
+
+## Workflow
+1. **Read Memory** — Load `.ai-memory.md` for architecture + conventions.
+2. **Locate Integration Point** — Identify the narrowest place to hook in (entry, router, service, component, util).
+3. **Diff the Concepts** — Map sample code concepts → existing abstractions (types, services, routes, state).
+4. **Design Minimal Bridge**:
+   - Prefer adding a thin adapter layer rather than changing existing call sites.
+   - Prefer dependency injection/config wiring over global edits.
+5. **Implement in Small Steps**:
+   - Add new file(s) when that reduces risk (e.g., `adapter/`, `integrations/`).
+   - Modify existing files only where the integration connects.
+6. **Verification**:
+   - Run/adjust existing tests if present; otherwise add a minimal smoke test when feasible.
+   - Ensure no unrelated behavior changes.
+7. **Quality Gate** — Read `.kiro/skills/_scripts/checklist.md`.
+8. **Update Memory** — Log only high-signal bullets (integration point, key decision, files touched, outcome).
+
+## Output Format
+- Integration target (what feature/module)
+- Files touched (added/modified)
+- Minimal change strategy (1–3 bullets)
+- Verification performed (commands/tests)
+- Risks / follow-ups (if any)
+