thachvd-kit 1.0.19 → 1.0.21

package/.agent/docs/architecture.md

@@ -12,9 +12,10 @@
 
 `thachvd-kit init` creates thin root entry files and puts project-specific knowledge in `.agent/docs/`:
 
-- `AGENTS.md`: shared instructions for Codex, Antigravity, and Claude Code.
+- `AGENTS.md`: shared instructions for Codex, Antigravity, Claude Code, and Cursor.
 - `CLAUDE.md`: imports `AGENTS.md` for Claude Code.
-- `GEMINI.md`: Antigravity entry that points to `AGENTS.md`.
+- `GEMINI.md`: points to `AGENTS.md` for Antigravity.
+- `.cursorrules`: points to `AGENTS.md` for Cursor.
 - `.agent/docs/*.md`: stack, architecture, conventions, and workflow.
 
 ## Maintenance Rule

package/.agent/docs/conventions.md

@@ -9,7 +9,7 @@
 
 ## Docs And Rules
 
-- Root `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` should stay concise.
+- Root `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `.cursorrules` should stay concise.
 - Put scan-specific or project-specific detail in `.agent/docs/`.
 - Keep `.agent/rules/GEMINI.md` and `rules/GEMINI.md` aligned.
 - Keep mirrored source folders and `.agent/` content aligned when changing kit assets.

package/.agent/docs/tooling.md

@@ -23,6 +23,12 @@ args = ["-y", "@upstash/context7-mcp"]
 startup_timeout_sec = 20
 tool_timeout_sec = 120
 
+[mcp_servers.filesystem]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-filesystem", "<projectPath>"]
+startup_timeout_sec = 20
+tool_timeout_sec = 120
+
 [mcp_servers.playwright]
 command = "npx"
 args = ["-y", "@playwright/mcp"]
@@ -67,6 +73,10 @@ Gemini CLI / Antigravity `mcp_config.json` example:
       "command": "npx",
       "args": ["-y", "@upstash/context7-mcp"]
     },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+    },
     "playwright": {
       "command": "npx",
       "args": ["-y", "@playwright/mcp"]
@@ -91,6 +101,16 @@ Claude Code user config example:
       "command": "codegraph",
       "args": ["serve", "--mcp"]
     },
+    "context7": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"]
+    },
+    "filesystem": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/project"]
+    },
     "playwright": {
       "type": "stdio",
       "command": "npx",
@@ -102,18 +122,15 @@ Claude Code user config example:
 
 Common local path:
 
-- Claude Code: `~/.claude.json`
-
-## Native Skill Folders
+- Claude Code: `~/.claude.json` or `~/.claude/settings.json`
 
-The shared kit skills live in `.agent/skills/`. Antigravity can use that folder directly, but Codex expects repo skills under `.agents/skills/` or user skills under `~/.agents/skills/`. Claude Code may require its own native skill location depending on the installed client.
+The shared kit skills live in `.agent/skills/`. Antigravity reads that folder directly. Codex shows skills from `~/.codex/skills/` in the `$` menu. Claude Code reads project skills from `.claude/skills/`.
 
-- Codex repo skills: `.agents/skills/`
-- Codex user skills: `~/.agents/skills/`
-- Codex may also keep installed/system skills under `$CODEX_HOME/skills` such as `~/.codex/skills`; treat that as local Codex state, not a repo folder to generate or commit.
-- Claude Code project skills commonly live under `.claude/skills/`.
-- `thachvd-kit` copies selected native skills to `.agents/skills/` and `.claude/skills/` based on the detected stack.
+- Codex global skills: `~/.codex/skills/` — installed by `thachvd-kit init`, visible in Codex `$` menu
+- Claude Code project skills: `.claude/skills/`
+- Antigravity: reads `.agent/skills/` directly (no copy needed)
 - Keep `.agent/skills/` as the full shared source of truth committed with the repo.
+- Do not commit `~/.codex/skills/`; it is local user state.
 
 Recommended candidates to copy first:
 

package/.agent/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/.agent/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/.agent/skills/writing-skills/SKILL.md

@@ -1,110 +1,170 @@
----
-name: writing-skills
-description: Use when creating a new skill or improving an existing one — follows best practices for SKILL.md structure, Claude Search Optimization, token efficiency, and skill testing methodology
-allowed-tools: Read, Write, Edit
----
-
-# Writing Skills
-
-## What is a Skill?
-
-A skill is a reusable instruction set that activates when Claude detects a relevant context. It lives in a folder with a `SKILL.md` file.
-
-## Skill Types
-
-| Type | Purpose | Example |
-|------|---------|---------|
-| **Technique** | How-to guide | `tdd-workflow` |
-| **Pattern** | Mental model | `clean-code` |
-| **Reference** | Documentation | `api-patterns` |
-| **Discipline** | Rules/enforcement | `verification-before-completion` |
-
-## Directory Structure
-
-```
-skill-name/
-├── SKILL.md          # Required: metadata + instructions
-├── scripts/          # Optional: runnable scripts
-└── references/       # Optional: templates, docs
-```
-
-## SKILL.md Structure
-
-```markdown
----
-name: skill-name
-description: [Trigger description — when to use this skill]
-allowed-tools: [Bash, Read, Edit, Write, ...]
----
-
-# Skill Title
-
-## Overview
-Brief summary + core principle
-
-## [Main Content]
-...
-```
-
-## Claude Search Optimization (CSO)
-
-The `description` field is how Claude decides whether to load your skill. Make it trigger correctly:
-
-### 1. Rich Description
-
-```yaml
-# ❌ Vague
-description: For code review
-
-# ✅ Specific with triggers
-description: Use when completing tasks, implementing major features, or before merging — pre-review checklist, evidence-before-claims workflow
-```
-
-### 2. Keyword Coverage
-
-Include synonyms, trigger phrases, and common user requests in description.
-
-### 3. Token Efficiency (Critical)
-
-- Use tables instead of prose for comparisons
-- Use code blocks for commands
-- Use flowcharts/diagrams for processes
-- Avoid narrative explanations — use structured data
-
-### 4. Cross-Referencing
-
-Use `Pairs with:` and `Integration:` sections to link related skills.
-
-## Anti-Patterns to Avoid
-
-| ❌ Anti-Pattern | ✅ Fix |
-|----------------|-------|
-| Narrative prose everywhere | Tables, bullet lists, code blocks |
-| Same content in multiple languages | Pick one, note variants |
-| Code examples in flowchart labels | Flowcharts for flow, code blocks for code |
-| Generic labels ("Step 1", "Step 2") | Descriptive labels ("Verify baseline", "Create worktree") |
-| Vague description | Specific triggers and use cases |
-
-## Skill Creation Checklist
-
-- [ ] Description field triggers correctly (test with: "would Claude load this for X?")
-- [ ] Core principle stated in Overview
-- [ ] Content uses tables/code blocks, not prose paragraphs
-- [ ] Token-efficient (no redundant explanations)
-- [ ] Red Flags / Anti-Patterns section included for discipline skills
-- [ ] Integration section lists related skills
-- [ ] Tested: create a scenario where this skill should fire, verify it does
-
-## Testing Skills
-
-For **discipline skills** (rules): Create scenario where rule should fire, verify AI follows it.
-For **technique skills** (how-to): Apply skill to a real task, verify output quality.
-For **reference skills** (docs): Query for specific info, verify correct answer.
-
-## The Bottom Line
-
-A skill is good when:
-1. It fires when it should (good description/CSO)
-2. It improves output quality noticeably
-3. It's token-efficient (doesn't waste context)
-4. It has no ambiguous loopholes
+---
+name: writing-skills
+description: Use when creating a new skill or improving an existing one — follows best practices for SKILL.md structure, Claude Search Optimization, token efficiency, anti-rationalization tables, and skill testing methodology
+allowed-tools: Read, Write, Edit
+---
+
+# Writing Skills
+
+## What is a Skill?
+
+A skill is a reusable instruction set that activates when an AI detects a relevant context. It lives in a folder with a `SKILL.md` file and works across Codex, Antigravity, Claude, and Cursor.
+
+## Skill Types
+
+| Type | Purpose | Example | Anti-Rationalization Required? |
+|------|---------|---------|----|
+| **Technique** | How-to guide | `tdd-workflow` | Optional |
+| **Pattern** | Mental model | `clean-code` | Optional |
+| **Reference** | Documentation | `api-patterns` | No |
+| **Discipline** | Rules/enforcement | `verification-before-completion` | **Mandatory** |
+
+## Directory Structure
+
+```
+skill-name/
+├── SKILL.md          # Required: metadata + instructions
+├── scripts/          # Optional: runnable scripts
+└── references/       # Optional: templates, docs
+```
+
+## SKILL.md Structure
+
+```markdown
+---
+name: skill-name
+description: [Trigger description — when to use this skill]
+allowed-tools: [Bash, Read, Edit, Write, ...]
+---
+
+# Skill Title
+
+## Overview
+Brief summary + core principle
+
+## When to Use
+- Specific trigger scenarios
+
+## [Main Content]
+...
+
+## Anti-Rationalization  ← REQUIRED for Discipline/Technique skills
+| Excuse | Correct Response |
+|--------|-----------------|
+| "Just this once" | No exceptions. Apply the rule. |
+
+## Exit Criteria  ← REQUIRED for Technique/Discipline skills
+- [ ] Specific, verifiable condition 1
+- [ ] Specific, verifiable condition 2
+```
+
+## Claude Search Optimization (CSO)
+
+The `description` field is how the AI decides whether to load your skill. Make it trigger correctly:
+
+### 1. Rich Description
+
+```yaml
+# ❌ Vague
+description: For code review
+
+# ✅ Specific with triggers
+description: Use when completing tasks, implementing major features, or before merging — pre-review checklist, evidence-before-claims workflow
+```
+
+### 2. Keyword Coverage
+
+Include synonyms, trigger phrases, and common user requests in description.
+
+### 3. Token Efficiency (Critical)
+
+- Use tables instead of prose for comparisons
+- Use code blocks for commands
+- Use flowcharts/diagrams for processes
+- Avoid narrative explanations — use structured data
+
+### 4. Cross-Referencing
+
+Use `Pairs with:` and `Integration:` sections to link related skills.
+
+## Anti-Rationalization Tables (Key Concept)
+
+The most powerful feature of a discipline skill. A table that blocks the AI's most common excuses for skipping a rule.
+
+### Why They Matter
+
+AI agents (like humans) tend to rationalize shortcuts under pressure. An Anti-Rationalization table names each excuse explicitly and provides the correct response, making it impossible to skip without consciously overriding the rule.
+
+### Format
+
+```markdown
+## Anti-Rationalization
+
+| Excuse | Reality / Correct Response |
+|--------|---------------------------|
+| "It's a small change" | Size doesn't reduce the need. Apply the rule. |
+| "I'm confident it works" | Confidence ≠ evidence. Run verification. |
+| "Just this once" | No exceptions — "just this once" is how standards die. |
+| "The last run passed" | Stale results. Run fresh verification now. |
+```
+
+### What Makes a Good Entry
+
+- **Excuse column**: Real phrases AI uses to justify skipping. Be specific.
+- **Reality column**: The direct counter. Short, imperative, no hedging.
+- Cover at least 4–6 common excuses for discipline skills.
+
+## Exit Criteria
+
+Every Technique or Discipline skill must end with a verifiable checklist the AI can check off before declaring the task done.
+
+```markdown
+## Exit Criteria
+
+Before claiming this task is complete:
+- [ ] [Verifiable condition 1]
+- [ ] [Verifiable condition 2]
+- [ ] [Verifiable condition 3]
+```
+
+**Rules for Exit Criteria:**
+- Each item must be binary (done or not done) — no vague "looks good" items
+- Must be something that can be checked programmatically or by inspection
+- Failing any item = task is NOT complete
+
+## Anti-Patterns to Avoid
+
+| ❌ Anti-Pattern | ✅ Fix |
+|----------------|-------|
+| Narrative prose everywhere | Tables, bullet lists, code blocks |
+| Discipline skill with no Anti-Rationalization | Add the table — it's mandatory |
+| Technique skill with no Exit Criteria | Add verifiable checklist |
+| Vague description | Specific triggers and use cases |
+| Generic labels ("Step 1", "Step 2") | Descriptive labels ("Verify baseline", "Run tests") |
+| Code examples in flowchart labels | Flowcharts for flow, code blocks for code |
+
+## Skill Creation Checklist
+
+- [ ] Description field triggers correctly (test: "would AI load this for X?")
+- [ ] Core principle stated in Overview
+- [ ] Content uses tables/code blocks, not prose paragraphs
+- [ ] Token-efficient (no redundant explanations)
+- [ ] **Anti-Rationalization section included** (Discipline/Technique skills — mandatory)
+- [ ] **Exit Criteria section included** (Discipline/Technique skills — mandatory)
+- [ ] Integration section lists related skills
+- [ ] Tested: create a scenario where this skill should fire, verify it does
+
+## Testing Skills
+
+For **discipline skills** (rules): Create scenario where rule should fire, verify AI follows it AND rejects the rationalizations in the Anti-Rationalization table.
+For **technique skills** (how-to): Apply skill to a real task, verify output quality and that Exit Criteria are met.
+For **reference skills** (docs): Query for specific info, verify correct answer.
+
+## The Bottom Line
+
+A skill is good when:
+1. It fires when it should (good description/CSO)
+2. It improves output quality noticeably
+3. It's token-efficient (doesn't waste context)
+4. It has no ambiguous loopholes (Anti-Rationalization table closes them)
+5. It's verifiable (Exit Criteria defines "done")

package/.agent/workflows/review.md

@@ -0,0 +1,125 @@
+# /review — Pre-Merge Code Review
+
+Structured multi-axis review before any change enters the main branch.
+
+> **Rule:** Every change gets reviewed before merge — no exceptions, no shortcuts.
+
+---
+
+## When to Use
+
+- Before merging any PR or change
+- After completing a feature implementation
+- When another agent or model produced code you need to evaluate
+- When refactoring existing code
+- After any bug fix (review both fix and regression test)
+
+---
+
+## Step 1: Understand the Context
+
+Before looking at code, understand the intent:
+
+```
+- What is this change trying to accomplish?
+- What spec or task does it map to?
+- What could go wrong if this change is wrong?
+```
+
+---
+
+## Step 2: Five-Axis Review
+
+Work through each axis in order. Flag issues with 🔴 BLOCKING / 🟡 SUGGESTION / 🟢 NIT.
+
+### Axis 1 — Correctness
+- [ ] Matches spec/task requirements
+- [ ] Edge cases handled (null, empty, boundary values)
+- [ ] Error paths covered
+- [ ] Tests pass and test the right things
+
+### Axis 2 — Readability & Simplicity
+- [ ] Names descriptive and consistent
+- [ ] Could this be done in fewer lines?
+- [ ] No clever tricks that should be simplified
+- [ ] No dead code (no-op variables, `// removed` comments)
+
+### Axis 3 — Architecture
+- [ ] Follows existing patterns (or new pattern justified)
+- [ ] Clean module boundaries
+- [ ] No unnecessary code duplication
+- [ ] No circular dependencies
+
+### Axis 4 — Security
+- [ ] Input validated and sanitized
+- [ ] No secrets in code, logs, or version control
+- [ ] Auth/authz checked where needed
+- [ ] SQL queries parameterized
+- [ ] External data treated as untrusted
+
+### Axis 5 — Performance
+- [ ] No N+1 queries
+- [ ] No unbounded loops or unconstrained fetching
+- [ ] Missing pagination on list endpoints
+- [ ] No unnecessary re-renders in UI
+
+---
+
+## Step 3: Change Size Sanity Check
+
+```
+~100 lines changed   → Good
+~300 lines changed   → Acceptable (single logical change)
+~1000+ lines changed → Too large — request a split
+```
+
+If too large, request it be split before reviewing further.
+
+---
+
+## Step 4: Write Review Output
+
+Use comment conventions:
+
+```
+🔴 BLOCKING: [Specific issue that must be fixed before merge]
+🟡 SUGGESTION: [Improvement worth considering but not blocking]
+🟢 NIT: [Minor style/preference item]
+❓ QUESTION: [Clarification needed]
+```
+
+---
+
+## Approval Standard
+
+Approve when the change **definitely improves overall code health**, even if imperfect.
+
+Do not block because it isn't exactly how you would have written it. If it improves the codebase and follows project conventions, approve it.
+
+---
+
+## Anti-Rationalization
+
+| Excuse | Correct Response |
+|--------|-----------------|
+| "It's a small PR, not worth five axes" | Small PRs still introduce bugs. Run all five. |
+| "I wrote this code, I know it's correct" | Author bias is real. Treat it as a stranger's code. |
+| "Tests pass so it's fine" | Tests prove what you tested, not what you didn't. |
+| "No time for a thorough review" | A partial review is a false sense of security. Flag as skipped. |
+| "The security axis doesn't apply here" | Apply it and confirm explicitly — don't silently skip. |
+| "Just reviewing, not approving" | Still run the full checklist. Review = accountability. |
+
+---
+
+## Exit Criteria
+
+Before approving or merging:
+
+- [ ] All five axes reviewed (not skimmed)
+- [ ] Change size is appropriate (< ~300 lines for one logical change)
+- [ ] All 🔴 BLOCKING issues resolved or explicitly accepted with rationale
+- [ ] Tests present and passing for changed behavior
+- [ ] No secrets, magic numbers, or hardcoded values
+- [ ] Review decision posted with explicit rationale
+
+**Pairs with:** `code-review-checklist`, `verification-before-completion`, `requesting-code-review`

package/.agent/workflows/spec.md

@@ -0,0 +1,140 @@
+# /spec — Spec-Driven Development
+
+Write a structured specification before writing any code.
+
+> **Rule:** Code without a spec is guessing. The spec is the shared source of truth.
+
+---
+
+## When to Use
+
+Use `/spec` when:
+- Starting a new project or feature
+- Requirements are ambiguous or incomplete
+- The change touches multiple files or modules
+- You're about to make an architectural decision
+- The task would take more than 30 minutes to implement
+
+**Skip when:** Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
+
+---
+
+## The Gated Workflow
+
+Do not advance to the next phase without human validation.
+
+```
+SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
+   │          │        │          │
+   ▼          ▼        ▼          ▼
+ Human      Human    Human      Human
+ reviews    reviews  reviews    reviews
+```
+
+---
+
+## Phase 1: Surface Assumptions First
+
+Before writing any spec content, explicitly state what you're assuming:
+
+```
+ASSUMPTIONS I'M MAKING:
+1. [assumption about tech stack or framework]
+2. [assumption about architecture]
+3. [assumption about scope or boundaries]
+→ Correct me now or I'll proceed with these.
+```
+
+Do not silently fill in ambiguous requirements.
+
+---
+
+## Phase 2: Write the Spec
+
+Create a spec document in `docs/spec-[feature-name].md` covering six areas:
+
+### 1. Objective
+What are we building and why? Who is the user? What does success look like?
+
+### 2. Commands
+Full executable commands with flags:
+```
+Build: npm run build
+Test: npm test
+Lint: npm run lint
+Dev: npm run dev
+```
+
+### 3. Project Structure
+Where source code lives, where tests go, where docs belong:
+```
+src/           → Application source
+src/components → Components
+tests/         → Unit and integration tests
+```
+
+### 4. Code Style
+One real code snippet showing style beats three paragraphs describing it. Include naming conventions and examples.
+
+### 5. Testing Strategy
+Framework, where tests live, coverage expectations, which test levels for which concerns.
+
+### 6. Boundaries (Three-Tier)
+- **Always do:** Run tests before commits, follow naming conventions
+- **Ask first:** Database schema changes, adding dependencies, changing CI config
+- **Never do:** Commit secrets, remove failing tests without approval
+
+---
+
+## Spec Template
+
+```markdown
+# Spec: [Feature Name]
+
+## Objective
+[What we're building and why. User stories or acceptance criteria.]
+
+## Tech Stack
+[Framework, language, key dependencies with versions]
+
+## Commands
+[Build, test, lint, dev commands — exact flags]
+
+## Project Structure
+[Key directories and what goes where]
+
+## Code Style
+[One code example showing conventions]
+
+## Testing Strategy
+[Framework, location, coverage target, test levels]
+
+## Boundaries
+- Always: ...
+- Ask first: ...
+- Never: ...
+```
+
+---
+
+## Anti-Rationalization
+
+| Excuse | Correct Response |
+|--------|-----------------|
+| "Requirements are clear, no need for a spec" | Write a one-page spec to confirm. Misalignments appear during writing, not before. |
+| "We'll figure out details during implementation" | Ambiguities discovered during coding are more expensive. Resolve them now. |
+| "The spec will become outdated" | A living spec that's 80% right is better than no spec. Update it as you learn. |
+| "This is too small for a spec" | If it takes more than 30 minutes, it needs a spec. Estimate conservatively. |
+| "I already know what to build" | Write it down to confirm alignment, then proceed. |
+
+## Exit Criteria
+
+Before moving from spec to plan:
+
+- [ ] Assumptions explicitly listed and confirmed by human
+- [ ] Spec document covers all six areas (objective, commands, structure, style, testing, boundaries)
+- [ ] Human has reviewed and approved the spec
+- [ ] No ambiguous requirements remain open
+- [ ] Spec saved as `docs/spec-[feature-name].md` or equivalent location
+
+**Pairs with:** `plan-writing`, `tdd-workflow`, `verification-before-completion`