@uocnv1998/agent-kit 1.0.0

package/templates/.agent/dev/backend/skills/mysql/references/replication-lag.md

@@ -0,0 +1,46 @@
+---
+title: Replication Lag Awareness
+description: Read-replica consistency pitfalls and mitigations
+tags: mysql, replication, lag, read-replicas, consistency, gtid
+---
+
+# Replication Lag
+
+MySQL replication is asynchronous by default. Reads from a replica may return stale data.
+
+## The Core Problem
+1. App writes to primary: `INSERT INTO orders ...`
+2. App immediately reads from replica: `SELECT * FROM orders WHERE id = ?`
+3. Replica hasn't applied the write yet — returns empty or stale data.
+
+## Detecting Lag
+```sql
+-- On the replica
+SHOW REPLICA STATUS\G
+-- Key field: Seconds_Behind_Source (0 = caught up, NULL = not replicating)
+```
+**Warning**: `Seconds_Behind_Source` measures relay-log lag, not true wall-clock staleness. It can underreport during long-running transactions because it only updates when transactions commit.
+
+**GTID-based lag**: for more accurate tracking, compare `@@global.gtid_executed` (replica) to primary GTID position, or use `WAIT_FOR_EXECUTED_GTID_SET()` to wait for a specific transaction.
+
+**Note**: parallel replication with `replica_parallel_type=LOGICAL_CLOCK` requires `binlog_format=ROW`. Statement-based replication (`binlog_format=STATEMENT`) is more limited for parallel apply.
+
+## Mitigation Strategies
+
+| Strategy | How | Trade-off |
+|---|---|---|
+| **Read from primary** | Route critical reads to primary after writes | Increases primary load |
+| **Sticky sessions** | Pin user to primary for N seconds after a write | Adds session affinity complexity |
+| **GTID wait** | `SELECT WAIT_FOR_EXECUTED_GTID_SET('gtid', timeout)` on replica | Adds latency equal to lag |
+| **Semi-sync replication** | Primary waits for >=1 replica ACK before committing | Higher write latency |
+
+## Common Pitfalls
+- **Large transactions cause lag spikes**: A single `INSERT ... SELECT` of 1M rows replays as one big transaction on the replica. Break into batches.
+- **DDL blocks replication**: `ALTER TABLE` with `ALGORITHM=COPY` on primary replays on replica, blocking other relay-log events during execution. `INSTANT` and `INPLACE` DDL are less blocking but still require brief metadata locks.
+- **Long queries on replica**: A slow `SELECT` on the replica can block relay-log application. Use `replica_parallel_workers` (8.0+) with `replica_parallel_type=LOGICAL_CLOCK` for parallel apply. Note: LOGICAL_CLOCK requires `binlog_format=ROW` and `slave_preserve_commit_order=ON` (or `replica_preserve_commit_order=ON`) to preserve commit order.
+- **IO thread bottlenecks**: Network latency, disk I/O, or `relay_log_space_limit` exhaustion can cause lag even when the SQL apply thread isn't saturated. Monitor `Relay_Log_Space` and connectivity.
+
+## Guidelines
+- Assume replicas are always slightly behind. Design reads accordingly.
+- Use GTID-based replication for reliable failover and lag tracking.
+- Monitor `Seconds_Behind_Source` with alerting (>5s warrants investigation).

package/templates/.agent/dev/backend/skills/mysql/references/row-locking-gotchas.md

@@ -0,0 +1,63 @@
+---
+title: InnoDB Row Locking Gotchas
+description: Gap locks, next-key locks, and surprise escalation
+tags: mysql, innodb, locking, gap-locks, next-key-locks, concurrency
+---
+
+# Row Locking Gotchas
+
+InnoDB uses row-level locking, but the actual locked range is often wider than expected.
+
+## Next-Key Locks (REPEATABLE READ)
+InnoDB's default isolation level uses next-key locks for **locking reads** (`SELECT ... FOR UPDATE`, `SELECT ... FOR SHARE`, `UPDATE`, `DELETE`) to prevent phantom reads. A range scan locks every gap in that range. Plain `SELECT` statements use consistent reads (MVCC) and don't acquire locks.
+
+**Exception**: a unique index search with a unique search condition (e.g., `WHERE id = 5` on a unique `id`) locks only the index record, not the gap. Gap/next-key locks still apply for range scans and non-unique searches.
+
+```sql
+-- Locks rows with id 5..10 AND the gaps between them and after the range
+SELECT * FROM orders WHERE id BETWEEN 5 AND 10 FOR UPDATE;
+-- Another session inserting id=7 blocks until the lock is released.
+```
+
+## Gap Locks on Non-Existent Rows
+`SELECT ... FOR UPDATE` on a row that doesn't exist still places a gap lock:
+```sql
+-- No row with id=999 exists, but this locks the gap around where 999 would be
+SELECT * FROM orders WHERE id = 999 FOR UPDATE;
+-- Concurrent INSERTs into that gap are blocked.
+```
+
+## Index-Less UPDATE/DELETE = Full Scan and Broad Locking
+If the WHERE column has no index, InnoDB must scan all rows and locks every row examined (often effectively all rows in the table). This is not table-level locking—InnoDB doesn't escalate locks—but rather row-level locks on all rows:
+```sql
+-- No index on status → locks all rows (not a table lock, but all row locks)
+UPDATE orders SET processed = 1 WHERE status = 'pending';
+-- Fix: CREATE INDEX idx_status ON orders (status);
+```
+
+## SELECT ... FOR SHARE (Shared Locks)
+`SELECT ... FOR SHARE` acquires shared (S) locks instead of exclusive (X) locks. Multiple sessions can hold shared locks simultaneously, but exclusive locks are blocked:
+
+```sql
+-- Session 1: shared lock
+SELECT * FROM orders WHERE id = 5 FOR SHARE;
+
+-- Session 2: also allowed (shared lock)
+SELECT * FROM orders WHERE id = 5 FOR SHARE;
+
+-- Session 3: blocked until shared locks are released
+UPDATE orders SET status = 'processed' WHERE id = 5;
+```
+
+Gap/next-key locks can still apply in REPEATABLE READ, so inserts into locked gaps may be blocked even with shared locks.
+
+## INSERT ... ON DUPLICATE KEY UPDATE
+Takes an exclusive next-key lock on the index entry. If multiple sessions do this concurrently on nearby key values, gap-lock deadlocks are common.
+
+## Lock Escalation Misconception
+InnoDB does **not** automatically escalate row locks to table locks. When a missing index causes "table-wide" locking, it's because InnoDB scans and locks all rows individually—not because locks were escalated.
+
+## Mitigation Strategies
+- **Use READ COMMITTED** when gap locks cause excessive blocking (gap locks disabled in RC except for FK/duplicate-key checks).
+- **Keep transactions short** — hold locks for milliseconds, not seconds.
+- **Ensure WHERE columns are indexed** to avoid full-table lock scans.

package/templates/.agent/dev/common/rules/GIT_COMMIT.md

@@ -0,0 +1,9 @@
+---
+trigger: model_decision
+description: Apply this rule hen you generate a commit message
+---
+
+- Always generate commit messages in English.
+- Use the Conventional Commits format: <type>(<scope>): <description>
+- Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
+- Keep the subject line under 50 characters.

package/templates/.agent/dev/common/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: tdd-workflow
+description: Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# TDD Workflow
+
+> Write tests first, code second.
+
+---
+
+## 1. The TDD Cycle
+
+```
+🔴 RED → Write failing test
+    ↓
+🟢 GREEN → Write minimal code to pass
+    ↓
+🔵 REFACTOR → Improve code quality
+    ↓
+   Repeat...
+```
+
+---
+
+## 2. The Three Laws of TDD
+
+1. Write production code only to make a failing test pass
+2. Write only enough test to demonstrate failure
+3. Write only enough code to make the test pass
+
+---
+
+## 3. RED Phase Principles
+
+### What to Write
+
+| Focus | Example |
+|-------|---------|
+| Behavior | "should add two numbers" |
+| Edge cases | "should handle empty input" |
+| Error states | "should throw for invalid data" |
+
+### RED Phase Rules
+
+- Test must fail first
+- Test name describes expected behavior
+- One assertion per test (ideally)
+
+---
+
+## 4. GREEN Phase Principles
+
+### Minimum Code
+
+| Principle | Meaning |
+|-----------|---------|
+| **YAGNI** | You Aren't Gonna Need It |
+| **Simplest thing** | Write the minimum to pass |
+| **No optimization** | Just make it work |
+
+### GREEN Phase Rules
+
+- Don't write unneeded code
+- Don't optimize yet
+- Pass the test, nothing more
+
+---
+
+## 5. REFACTOR Phase Principles
+
+### What to Improve
+
+| Area | Action |
+|------|--------|
+| Duplication | Extract common code |
+| Naming | Make intent clear |
+| Structure | Improve organization |
+| Complexity | Simplify logic |
+
+### REFACTOR Rules
+
+- All tests must stay green
+- Small incremental changes
+- Commit after each refactor
+
+---
+
+## 6. AAA Pattern
+
+Every test follows:
+
+| Step | Purpose |
+|------|---------|
+| **Arrange** | Set up test data |
+| **Act** | Execute code under test |
+| **Assert** | Verify expected outcome |
+
+---
+
+## 7. When to Use TDD
+
+| Scenario | TDD Value |
+|----------|-----------|
+| New feature | High |
+| Bug fix | High (write test first) |
+| Complex logic | High |
+| Exploratory | Low (spike, then TDD) |
+| UI layout | Low |
+
+---
+
+## 8. Test Prioritization
+
+| Priority | Test Type |
+|----------|-----------|
+| 1 | Happy path |
+| 2 | Error cases |
+| 3 | Edge cases |
+| 4 | Performance |
+
+---
+
+## 9. Anti-Patterns
+
+| ❌ Don't | ✅ Do |
+|----------|-------|
+| Skip the RED phase | Watch test fail first |
+| Write tests after | Write tests before |
+| Over-engineer initial | Keep it simple |
+| Multiple asserts | One behavior per test |
+| Test implementation | Test behavior |
+
+---
+
+## 10. AI-Augmented TDD
+
+### Multi-Agent Pattern
+
+| Agent | Role |
+|-------|------|
+| Agent A | Write failing tests (RED) |
+| Agent B | Implement to pass (GREEN) |
+| Agent C | Optimize (REFACTOR) |
+
+---
+
+> **Remember:** The test is the specification. If you can't write a test, you don't understand the requirement.

package/templates/.agent/dev/common/workflows/dev-workflow.md

@@ -0,0 +1,46 @@
+---
+description: Spec-Driven Development (SDD) using the official OpenSpec tool.
+---
+
+# Developer Execution Workflow (OpenSpec Official Workflow)
+
+This project strictly utilizes the **Official OpenSpec framework** (`@fission-ai/openspec`) to manage the AI Spec-Driven Development (SDD) process. 
+
+**CRITICAL RULE FOR AI:** 
+Even if the user simply says "Thực hiện task TAP-1" or "Code chức năng Đăng nhập" without mentioning `/opsx`, **YOU MUST AUTOMATICALLY TRIGGER THE OPENSPEC WORKFLOW**. You are FORBIDDEN from writing source code immediately.
+
+## Workflow Phases
+
+### Phase 1: Establish the Spec (Thuyết minh & Thiết kế kỹ thuật)
+When receiving a task (via Jira Ticket or direct prompt), you must act as if the user typed `/opsx:propose [Task-Key]`.
+
+- You will automatically generate or update a folder at `openspec/changes/[Task-Key]/`.
+- You must draft the 4 required artifacts within that folder:
+  1. `proposal.md` - Why we're doing this, what's changing.
+  2. `specs/` - Requirements and scenarios.
+  3. `design.md` - Technical approach.
+  4. `tasks.md` - Implementation checklist.
+- After generating these files, STOP and ask the user to review them via `/opsx:apply`.
+
+### Phase 2: Implementation (Tiến hành Code)
+- **Command**: `/opsx:apply`
+- When you receive this command, you will start implementing the code strictly following the checklist in `tasks.md`.
+- As you complete portions of the work, mark off items in the `tasks.md` internal memory.
+- **MANDATORY**: Upon completing the backend implementation, you MUST document the new or updated APIs:
+    1. Create or update an API Specification page on **Confluence** (using `atlassian-mcp-server_createConfluencePage` or `updateConfluencePage`).
+    2. Add a comment to the corresponding **Jira ticket** (using `atlassian-mcp-server_addCommentToJiraIssue`) containing the direct link to the Confluence API Documentation page so the frontend team can implement their side.
+
+### Phase 3: Archive & Continuous Updates
+- **Command**: `/opsx:archive`
+- Move the feature to `openspec/changes/archive/[date]-[feature-name]/`.
+- Specs must be updated to ensure the AI's prompt rules (e.g., inside `.cursorrules` or `.clinerules` that OpenSpec generates) remain accurate. This ensures the Agent avoids hallucinations in future tasks.
+
+---
+
+## 🛠️ Setup Instructions (For User/Dev)
+If OpenSpec is not yet initialized in this project, run the following commands in the terminal:
+```bash
+npx @fission-ai/openspec@latest init
+openspec update
+```
+This forces the AI coding assistants (Cursor, Copilot, Cline, etc.) to load the OpenSpec workflow rules.

package/templates/.agent/dev/frontend/ARCHITECTURE.md

@@ -0,0 +1,47 @@
+# Antigravity Kit Architecture
+
+> System overview for the current single-agent development setup.
+
+---
+
+## 🏗️ Directory Structure
+
+```plaintext
+.agent/
+├── ARCHITECTURE.md          # This file (System Overview)
+├── agents/                  # Specialist AI Persona (1 active)
+├── rules/                   # Global Rules (GEMINI.md)
+├── skills/                  # Domain-specific knowledge modules
+└── workflows/               # Slash Command Procedures
+```
+
+---
+
+## 🤖 Active Agent
+
+| Agent                 | Focus                                  | Location                                |
+| --------------------- | -------------------------------------- | --------------------------------------- |
+| `frontend-specialist` | Web UI/UX, Performance, React, Next.js | `.agent/agents/frontend-specialist.md` |
+
+---
+
+## 🧩 Active Skills (4)
+
+Modular knowledge domains loaded by the `frontend-specialist`.
+
+| Skill                    | Description                                  |
+| ------------------------ | -------------------------------------------- |
+| `frontend-design`        | Design systems and UX patterns               |
+| `nextjs-react-expert`   | Next.js performance and patterns             |
+| `tailwind-patterns`      | Utility-first styling with Tailwind CSS      |
+| `web-design-guidelines` | Accessibility and design audit principles    |
+
+---
+
+## 🔄 Workflows (1)
+
+Slash command procedures. Invoke with `/command`.
+
+| Command       | Description                 | Location                            |
+| ------------- | --------------------------- | ----------------------------------- |
+| `/brainstorm` | Socratic discovery & design | `.agent/workflows/brainstorm.md`    |