thachvd-kit 1.0.18 → 1.0.20

package/kit/README.md

@@ -1,12 +1,13 @@
 # thachvd-kit Kit
 
-This kit keeps AI coding behavior consistent across Codex, Antigravity, and Claude Code.
+This kit keeps AI coding behavior consistent across Codex, Antigravity, Claude Code, and Cursor.
 
 ## Entry Files
 
 - `AGENTS.md`: shared cross-agent instructions.
 - `CLAUDE.md`: Claude Code entry file that imports `AGENTS.md`.
 - `GEMINI.md`: Antigravity entry file that points to `AGENTS.md`.
+- `.cursorrules`: Cursor entry file that points to `AGENTS.md`.
 
 ## Shared Docs
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "thachvd-kit",
-    "version": "1.0.18",
+    "version": "1.0.20",
     "description": "Cross-agent project rules bootstrap kit for Codex, Antigravity, and Claude Code",
     "bin": {
         "thachvd-kit": "./bin/cli.js"

package/skills/code-review-checklist/SKILL.md

@@ -1,109 +1,142 @@
----
-name: code-review-checklist
-description: Code review guidelines covering code quality, security, and best practices.
-allowed-tools: Read, Glob, Grep
----
-
-# Code Review Checklist
-
-## Quick Review Checklist
-
-### Correctness
-- [ ] Code does what it's supposed to do
-- [ ] Edge cases handled
-- [ ] Error handling in place
-- [ ] No obvious bugs
-
-### Security
-- [ ] Input validated and sanitized
-- [ ] No SQL/NoSQL injection vulnerabilities
-- [ ] No XSS or CSRF vulnerabilities
-- [ ] No hardcoded secrets or sensitive credentials
-- [ ] **AI-Specific:** Protection against Prompt Injection (if applicable)
-- [ ] **AI-Specific:** Outputs are sanitized before being used in critical sinks
-
-### Performance
-- [ ] No N+1 queries
-- [ ] No unnecessary loops
-- [ ] Appropriate caching
-- [ ] Bundle size impact considered
-
-### Code Quality
-- [ ] Clear naming
-- [ ] DRY - no duplicate code
-- [ ] SOLID principles followed
-- [ ] Appropriate abstraction level
-
-### Testing
-- [ ] Unit tests for new code
-- [ ] Edge cases tested
-- [ ] Tests readable and maintainable
-
-### Documentation
-- [ ] Complex logic commented
-- [ ] Public APIs documented
-- [ ] README updated if needed
-
-## AI & LLM Review Patterns (2025)
-
-### Logic & Hallucinations
-- [ ] **Chain of Thought:** Does the logic follow a verifiable path?
-- [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
-- [ ] **External State:** Is the code making safe assumptions about file systems or networks?
-
-### Prompt Engineering Review
-```markdown
-// ❌ Vague prompt in code
-const response = await ai.generate(userInput);
-
-// ✅ Structured & Safe prompt
-const response = await ai.generate({
-  system: "You are a specialized parser...",
-  input: sanitize(userInput),
-  schema: ResponseSchema
-});
-```
-
-## Anti-Patterns to Flag
-
-```typescript
-// ❌ Magic numbers
-if (status === 3) { ... }
-
-// ✅ Named constants
-if (status === Status.ACTIVE) { ... }
-
-// ❌ Deep nesting
-if (a) { if (b) { if (c) { ... } } }
-
-// ✅ Early returns
-if (!a) return;
-if (!b) return;
-if (!c) return;
-// do work
-
-// ❌ Long functions (100+ lines)
-// ✅ Small, focused functions
-
-// ❌ any type
-const data: any = ...
-
-// ✅ Proper types
-const data: UserData = ...
-```
-
-## Review Comments Guide
-
-```
-// Blocking issues use 🔴
-🔴 BLOCKING: SQL injection vulnerability here
-
-// Important suggestions use 🟡
-🟡 SUGGESTION: Consider using useMemo for performance
-
-// Minor nits use 🟢
-🟢 NIT: Prefer const over let for immutable variable
-
-// Questions use ❓
-❓ QUESTION: What happens if user is null here?
-```
+---
+name: code-review-checklist
+description: Code review guidelines covering correctness, readability, architecture, security, and performance. Use before merging any PR, after completing a feature, or when reviewing AI-generated code.
+allowed-tools: Read, Glob, Grep
+---
+
+# Code Review Checklist
+
+## Overview
+
+Multi-dimensional code review with quality gates. Every change gets reviewed before merge — no exceptions.
+
+**The approval standard:** Approve when it definitely improves overall code health, even if imperfect. Don't block because it isn't exactly how you would have written it.
+
+## The Five-Axis Review
+
+### 1. Correctness
+- [ ] Code does what the spec/task requires
+- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] Error paths handled (not just the happy path)
+- [ ] Tests pass and are testing the right things
+- [ ] No off-by-one errors, race conditions, or state inconsistencies
+
+### 2. Readability & Simplicity
+- [ ] Names descriptive and consistent with project conventions (no `temp`, `data`, `result` without context)
+- [ ] Control flow straightforward (no nested ternaries, deep callbacks)
+- [ ] **Could this be done in fewer lines?** (1000 lines where 100 suffice is a failure)
+- [ ] **Are abstractions earning their complexity?** (Don't generalize before the third use case)
+- [ ] No dead code: no-op variables, backwards-compat shims, `// removed` comments
+
+### 3. Architecture
+- [ ] Follows existing patterns (or new pattern is justified)
+- [ ] Clean module boundaries maintained
+- [ ] No code duplication that should be shared
+- [ ] Dependencies flow in the right direction (no circular dependencies)
+
+### 4. Security
+- [ ] Input validated and sanitized
+- [ ] No SQL/NoSQL injection vulnerabilities
+- [ ] No XSS or CSRF vulnerabilities
+- [ ] No hardcoded secrets or sensitive credentials
+- [ ] **AI-Specific:** Protection against Prompt Injection (if applicable)
+- [ ] **AI-Specific:** Outputs sanitized before use in critical sinks
+
+### 5. Performance
+- [ ] No N+1 queries
+- [ ] No unbounded loops or unconstrained data fetching
+- [ ] Synchronous operations that should be async
+- [ ] No unnecessary re-renders in UI components
+- [ ] Missing pagination on list endpoints
+
+## Change Sizing
+
+```
+~100 lines changed   → Good. Reviewable in one sitting.
+~300 lines changed   → Acceptable if it's a single logical change.
+~1000 lines changed  → Too large. Split it.
+```
+
+**Splitting strategies:**
+
+| Strategy | How | When |
+|----------|-----|------|
+| **Stack** | Submit small change, next based on it | Sequential dependencies |
+| **By file group** | Separate changes needing different reviewers | Cross-cutting concerns |
+| **Vertical** | Break into smaller full-stack slices | Feature work |
+
+**Always separate refactoring from feature work.** Submit them independently.
+
+## AI & LLM Review Patterns (2025)
+
+### Logic & Hallucinations
+- [ ] **Chain of Thought:** Does the logic follow a verifiable path?
+- [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
+- [ ] **External State:** Is the code making safe assumptions about file systems or networks?
+
+### Prompt Engineering Review
+```markdown
+// ❌ Vague prompt in code
+const response = await ai.generate(userInput);
+
+// ✅ Structured & Safe prompt
+const response = await ai.generate({
+  system: "You are a specialized parser...",
+  input: sanitize(userInput),
+  schema: ResponseSchema
+});
+```
+
+## Code Anti-Patterns to Flag
+
+```typescript
+// ❌ Magic numbers
+if (status === 3) { ... }
+
+// ✅ Named constants
+if (status === Status.ACTIVE) { ... }
+
+// ❌ Deep nesting
+if (a) { if (b) { if (c) { ... } } }
+
+// ✅ Early returns
+if (!a) return;
+if (!b) return;
+
+// ❌ any type
+const data: any = ...
+
+// ✅ Proper types
+const data: UserData = ...
+```
+
+## Review Comment Conventions
+
+```
+🔴 BLOCKING: SQL injection vulnerability here
+🟡 SUGGESTION: Consider using useMemo for performance
+🟢 NIT: Prefer const over let for immutable variable
+❓ QUESTION: What happens if user is null here?
+```
+
+## Anti-Rationalization
+
+| Excuse | Correct Response |
+|--------|-----------------|
+| "It's a small PR, not worth full review" | Small PRs still introduce bugs. Run the five-axis check. |
+| "I wrote this code, I know it's correct" | Author bias is real. Treat your own code as a stranger's. |
+| "Tests pass, it's fine" | Tests prove what you tested, not what you didn't. Check all 5 axes. |
+| "No time for a thorough review" | A partial review is a false sense of security. Flag it as skipped. |
+| "The security checks don't apply here" | Apply them and explicitly confirm they don't apply — don't skip. |
+| "It's just refactoring, no new behavior" | Refactors introduce bugs. Correctness + test axes are non-negotiable. |
+
+## Exit Criteria
+
+Before approving or merging any change:
+
+- [ ] All five axes reviewed (correctness, readability, architecture, security, performance)
+- [ ] Change size is appropriate (< ~300 lines for a single logical change)
+- [ ] All 🔴 BLOCKING issues resolved
+- [ ] Tests present and passing for changed behavior
+- [ ] No secrets, magic numbers, or hardcoded values
+- [ ] Review comment posted or change approved with explicit rationale

package/skills/project-onboarding/SKILL.md

@@ -9,7 +9,7 @@ Use this skill when a project has just run `thachvd-kit init`, when `.agent/docs
 
 ## Goal
 
-Create or update the shared project docs used by Codex, Antigravity, and Claude Code:
+Create or update the shared project docs used by Codex, Antigravity, Claude Code, and Cursor:
 
 - `.agent/docs/project.md`
 - `.agent/docs/architecture.md`

package/skills/tdd-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd-workflow
-description: Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.
+description: Test-Driven Development workflow principles. Use when writing new features, fixing bugs, or implementing any logic — enforces RED-GREEN-REFACTOR cycle, prevents writing code before tests
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 
@@ -146,4 +146,28 @@ Every test follows:
 
 ---
 
+## Anti-Rationalization
+
+The most common reasons AI skips writing tests first — and why they're wrong:
+
+| Excuse | Correct Response |
+|--------|------------------|
+| "It's a simple change, tests aren't needed" | Simplicity is not an exemption. Simple code breaks too. Write the test. |
+| "I'll write tests after the implementation" | That's TAD (Test After Development), not TDD. Tests written after implementation don't drive design. |
+| "The feature is exploratory, tests would slow me down" | Write a spike without TDD, then delete and rewrite TDD. Don't skip the RED phase permanently. |
+| "The test would be too complex to write" | Complex test = unclear requirement. Stop and clarify the requirement first. |
+| "I already know what the code should do" | Knowing what it should do is exactly when you write the test — to prove it. |
+| "This is UI code, hard to test" | UI logic can be extracted and tested. Pure rendering tests have lower value — skip those, not the logic. |
+
+## Exit Criteria
+
+Before claiming a TDD cycle is complete:
+
+- [ ] Test was written BEFORE the implementation (RED phase confirmed — test failed first)
+- [ ] Test failure message was read and confirmed it failed for the right reason
+- [ ] Minimum code was written to make the test pass (GREEN)
+- [ ] Test suite runs green with the new test included
+- [ ] Code was refactored if needed while keeping tests green (REFACTOR)
+- [ ] No production code exists that isn't covered by a test written in this cycle
+
 > **Remember:** The test is the specification. If you can't write a test, you don't understand the requirement.

package/skills/using-git-worktrees/SKILL.md

@@ -27,11 +27,10 @@ ls -d worktrees 2>/dev/null      # Alternative
 
 **If found:** Use that directory. If both exist, `.worktrees` wins.
 
-### 2. Check CLAUDE.md / GEMINI.md
+### 2. Check CLAUDE.md / GEMINI.md / .cursorrules
 
 ```bash
-grep -i "worktree.*director" CLAUDE.md 2>/dev/null
-grep -i "worktree.*director" GEMINI.md 2>/dev/null
+grep -i "worktree.*director" CLAUDE.md GEMINI.md .cursorrules 2>/dev/null
 ```
 
 **If preference specified:** Use it without asking.

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

@@ -1,6 +1,6 @@
 ---
 name: verification-before-completion
-description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs, or before moving to next task — requires running verification commands and confirming output; evidence before assertions always
 allowed-tools: Bash, Read
 ---
 
@@ -57,16 +57,19 @@ Skip any step = lying, not verifying
 - Relying on partial verification
 - **ANY wording implying success without having run verification**
 
-## Rationalization Prevention
+## Anti-Rationalization
 
-| Excuse | Reality |
-|--------|---------|
-| "Should work now" | RUN the verification |
-| "I'm confident" | Confidence ≠ evidence |
-| "Just this once" | No exceptions |
-| "Linter passed" | Linter ≠ compiler |
-| "Agent said success" | Verify independently |
-| "Partial check is enough" | Partial proves nothing |
+| Excuse | Correct Response |
+|--------|------------------|
+| "Should work now" | Run the verification. "Should" is not evidence. |
+| "I'm confident" | Confidence ≠ evidence. Run it anyway. |
+| "Just this once" | No exceptions. "Just this once" is how standards die. |
+| "Linter passed" | Linter ≠ compiler ≠ tests. All three are separate gates. |
+| "Agent said success" | Verify independently. Agent reports are not evidence. |
+| "Partial check is enough" | Partial proves nothing. Run the full suite. |
+| "I already ran this earlier" | Stale results. Run fresh verification in this message. |
+| "The change is too small to matter" | Small changes cause prod incidents. Run the gate. |
+| "Tests take too long" | A broken deploy takes longer. Run the gate. |
 
 ## Key Patterns
 
@@ -96,4 +99,15 @@ Skip any step = lying, not verifying
 - Moving to next task
 - Delegating to agents
 
+## Exit Criteria
+
+Before claiming any task is done:
+
+- [ ] Verification command identified ("what command proves this claim?")
+- [ ] Verification command run fresh in this session (not relying on past results)
+- [ ] Full output read, not skimmed
+- [ ] Exit code or failure count checked explicitly
+- [ ] No "should", "probably", or "seems to" language used in the claim
+- [ ] Claim is accompanied by specific evidence from the output
+
 **The Bottom Line:** Run the command. Read the output. THEN claim the result.