thachvd-kit 1.0.14 → 1.0.16

package/.agent/skills/docker-patterns/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: docker-patterns
+description: Docker and Docker Compose patterns for local development and production. Use when containerizing apps, writing Dockerfiles, configuring docker-compose, managing volumes/networks, or hardening container security.
+allowed-tools: Read, Edit, Write, Bash
+---
+
+# Docker Patterns
+
+## Multi-Stage Dockerfile (Node.js / Adapt for other runtimes)
+
+```dockerfile
+# Stage: dependencies
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci
+
+# Stage: development (hot reload)
+FROM node:22-alpine AS dev
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+EXPOSE 3000
+CMD ["npm", "run", "dev"]
+
+# Stage: build
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build && npm prune --production
+
+# Stage: production (minimal, non-root)
+FROM node:22-alpine AS production
+WORKDIR /app
+RUN addgroup -g 1001 -S appgroup && adduser -S appuser -u 1001
+USER appuser
+COPY --from=build --chown=appuser:appgroup /app/dist ./dist
+COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
+COPY --from=build --chown=appuser:appgroup /app/package.json ./
+ENV NODE_ENV=production
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
+CMD ["node", "dist/server.js"]
+```
+
+## Docker Compose — Local Dev Stack
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    build:
+      context: .
+      target: dev
+    ports:
+      - "3000:3000"
+    volumes:
+      - .:/app                      # Bind mount for hot reload
+      - /app/node_modules           # Preserve container deps
+    environment:
+      - DATABASE_URL=postgres://postgres:postgres@db:5432/app_dev
+      - REDIS_URL=redis://redis:6379/0
+    depends_on:
+      db:
+        condition: service_healthy
+    command: npm run dev
+
+  db:
+    image: postgres:16-alpine
+    ports:
+      - "5432:5432"
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+      POSTGRES_DB: app_dev
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    volumes:
+      - redisdata:/data
+
+  mailpit:                          # Local email testing
+    image: axllent/mailpit
+    ports:
+      - "8025:8025"                 # Web UI
+      - "1025:1025"                 # SMTP
+
+volumes:
+  pgdata:
+  redisdata:
+```
+
+## Override Files
+
+```yaml
+# docker-compose.override.yml (auto-loaded for dev)
+services:
+  app:
+    environment:
+      - DEBUG=app:*
+      - LOG_LEVEL=debug
+    ports:
+      - "9229:9229"               # Debugger port
+
+# docker-compose.prod.yml (explicit for production)
+services:
+  app:
+    build:
+      target: production
+    restart: always
+    deploy:
+      resources:
+        limits:
+          cpus: "1.0"
+          memory: 512M
+```
+
+```bash
+# Dev (auto-loads override)
+docker compose up
+
+# Production
+docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
+```
+
+## Container Security
+
+```yaml
+# Compose security settings
+services:
+  app:
+    security_opt:
+      - no-new-privileges:true
+    read_only: true
+    tmpfs:
+      - /tmp
+      - /app/.cache
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE          # Only if binding to ports < 1024
+```
+
+## Secret Management
+
+```yaml
+# GOOD: Environment variables from .env (never commit .env)
+services:
+  app:
+    env_file:
+      - .env
+    environment:
+      - API_KEY                   # Inherits from host env
+
+# GOOD: Docker secrets (Swarm mode)
+secrets:
+  db_password:
+    file: ./secrets/db_password.txt
+
+# BAD: Hardcoded in Dockerfile
+# ENV API_KEY=sk-xxx             # NEVER DO THIS
+```
+
+## .dockerignore
+
+```
+node_modules
+.git
+.env
+.env.*
+dist
+*.log
+coverage
+.DS_Store
+```
+
+## Networking
+
+```yaml
+# Named networks for isolation
+networks:
+  frontend:
+  backend:
+
+services:
+  nginx:
+    networks: [frontend]
+  app:
+    networks: [frontend, backend]
+  db:
+    networks: [backend]           # DB NOT exposed to frontend
+```
+
+## Debugging
+
+```bash
+# Enter running container
+docker compose exec app sh
+
+# View logs
+docker compose logs -f app
+
+# Inspect network
+docker network inspect <network-name>
+
+# Check container health
+docker compose ps
+
+# Rebuild without cache
+docker compose build --no-cache app
+```
+
+## Anti-Patterns
+
+| ❌ Anti-Pattern | ✅ Fix |
+|----------------|-------|
+| `FROM node:latest` | Use specific tag: `node:22.12-alpine3.20` |
+| Running as root | Add non-root user in Dockerfile |
+| Secrets in image layers | Use env vars or Docker secrets |
+| Single-stage Dockerfile | Multi-stage for smaller prod images |
+| No healthcheck | Always add `HEALTHCHECK` for prod |
+| Bind-mounting entire project to prod | Only copy what's needed |

package/.agent/skills/documentation-templates/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: documentation-templates
+description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
+allowed-tools: Read, Glob, Grep
+---
+
+# Documentation Templates
+
+> Templates and structure guidelines for common documentation types.
+
+---
+
+## 1. README Structure
+
+### Essential Sections (Priority Order)
+
+| Section | Purpose |
+|---------|---------|
+| **Title + One-liner** | What is this? |
+| **Quick Start** | Running in <5 min |
+| **Features** | What can I do? |
+| **Configuration** | How to customize |
+| **API Reference** | Link to detailed docs |
+| **Contributing** | How to help |
+| **License** | Legal |
+
+### README Template
+
+```markdown
+# Project Name
+
+Brief one-line description.
+
+## Quick Start
+
+[Minimum steps to run]
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 3000 |
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Architecture](./docs/architecture.md)
+
+## License
+
+MIT
+```
+
+---
+
+## 2. API Documentation Structure
+
+### Per-Endpoint Template
+
+```markdown
+## GET /users/:id
+
+Get a user by ID.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | User ID |
+
+**Response:**
+- 200: User object
+- 404: User not found
+
+**Example:**
+[Request and response example]
+```
+
+---
+
+## 3. Code Comment Guidelines
+
+### JSDoc/TSDoc Template
+
+```typescript
+/**
+ * Brief description of what the function does.
+ * 
+ * @param paramName - Description of parameter
+ * @returns Description of return value
+ * @throws ErrorType - When this error occurs
+ * 
+ * @example
+ * const result = functionName(input);
+ */
+```
+
+### When to Comment
+
+| ✅ Comment | ❌ Don't Comment |
+|-----------|-----------------|
+| Why (business logic) | What (obvious) |
+| Complex algorithms | Every line |
+| Non-obvious behavior | Self-explanatory code |
+| API contracts | Implementation details |
+
+---
+
+## 4. Changelog Template (Keep a Changelog)
+
+```markdown
+# Changelog
+
+## [Unreleased]
+### Added
+- New feature
+
+## [1.0.0] - 2025-01-01
+### Added
+- Initial release
+### Changed
+- Updated dependency
+### Fixed
+- Bug fix
+```
+
+---
+
+## 5. Architecture Decision Record (ADR)
+
+```markdown
+# ADR-001: [Title]
+
+## Status
+Accepted / Deprecated / Superseded
+
+## Context
+Why are we making this decision?
+
+## Decision
+What did we decide?
+
+## Consequences
+What are the trade-offs?
+```
+
+---
+
+## 6. AI-Friendly Documentation (2025)
+
+### llms.txt Template
+
+For AI crawlers and agents:
+
+```markdown
+# Project Name
+> One-line objective.
+
+## Core Files
+- [src/index.ts]: Main entry
+- [src/api/]: API routes
+- [docs/]: Documentation
+
+## Key Concepts
+- Concept 1: Brief explanation
+- Concept 2: Brief explanation
+```
+
+### MCP-Ready Documentation
+
+For RAG indexing:
+- Clear H1-H3 hierarchy
+- JSON/YAML examples for data structures
+- Mermaid diagrams for flows
+- Self-contained sections
+
+---
+
+## 7. Structure Principles
+
+| Principle | Why |
+|-----------|-----|
+| **Scannable** | Headers, lists, tables |
+| **Examples first** | Show, don't just tell |
+| **Progressive detail** | Simple → Complex |
+| **Up to date** | Outdated = misleading |
+
+---
+
+> **Remember:** Templates are starting points. Adapt to your project's needs.

package/.agent/skills/executing-plans/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+allowed-tools: Read, Bash, Edit, Write
+---
+
+# Executing Plans
+
+## Overview
+
+Load plan, review critically, execute all tasks, report when complete.
+
+**Announce at start:** "I'm using the executing-plans skill to implement this plan."
+
+## The Process
+
+### Step 1: Load and Review Plan
+
+1. Read plan file
+2. Review critically — identify any questions or concerns
+3. If concerns: Raise them with user before starting
+4. If no concerns: Create task list and proceed
+
+### Step 2: Execute Tasks
+
+For each task:
+1. Mark as in_progress
+2. Follow each step exactly (plan has bite-sized steps)
+3. Run verifications as specified
+4. Mark as completed
+
+### Step 3: Complete Development
+
+After all tasks complete and verified:
+- Use `finishing-a-development-branch` skill
+- Verify tests, present 4 options, execute choice
+
+## When to Stop and Ask for Help
+
+**STOP executing immediately when:**
+- Hit a blocker (missing dependency, test fails, instruction unclear)
+- Plan has critical gaps preventing starting
+- You don't understand an instruction
+- Verification fails repeatedly
+
+**Ask for clarification rather than guessing.**
+
+## Rules
+
+- Review plan critically first
+- Follow plan steps exactly
+- Don't skip verifications
+- Stop when blocked, don't guess
+- Never start implementation on main/master branch without explicit user consent
+
+## Integration
+
+**Required workflow skills:**
+- `using-git-worktrees` — Set up isolated workspace before starting
+- `plan-writing` — Creates the plan this skill executes
+- `finishing-a-development-branch` — Complete development after all tasks

package/.agent/skills/finishing-a-development-branch/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: finishing-a-development-branch
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+allowed-tools: Bash, Read
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / php artisan test / go test ./...
+```
+
+**If tests fail:** Show failures. Stop. Cannot proceed until tests pass.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Determine Base Branch
+
+```bash
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+Or ask: "This branch split from main - is that correct?"
+
+### Step 3: Present Options
+
+Present exactly these 4 options:
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+### Step 4: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+<test command>   # Verify tests on merged result
+git branch -d <feature-branch>
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 2: Push and Create PR
+
+```bash
+git push -u origin <feature-branch>
+gh pr create --title "<title>" --body "## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>"
+```
+
+Then: Cleanup worktree (Step 5)
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm first:**
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <commit-list>
+- Worktree at <path>
+
+Type 'discard' to confirm.
+```
+
+Wait for exact confirmation before proceeding.
+
+### Step 5: Cleanup Worktree
+
+For Options 1, 2, 4:
+```bash
+git worktree list | grep $(git branch --show-current)
+git worktree remove <worktree-path>
+```
+
+For Option 3: Keep worktree.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | ✓ | - | - | ✓ |
+| 2. Create PR | - | ✓ | ✓ | - |
+| 3. Keep as-is | - | - | ✓ | - |
+| 4. Discard | - | - | - | ✓ (force) |
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+
+## Integration
+
+**Called by:**
+- `subagent-driven-development` — After all tasks complete
+- `executing-plans` — After all batches complete
+
+**Pairs with:**
+- `using-git-worktrees` — Cleans up worktree created by that skill