@torus-engineering/tas-kit 1.5.1 → 1.6.0

package/.claude/rules/common/agents.md

@@ -0,0 +1,65 @@
+# Agent Orchestration
+
+## Parallel Execution Pattern (TAS Commands)
+
+TAS commands launch agents **đồng thời** — không chờ nhau. Chờ **TẤT CẢ** xong mới tổng hợp.
+
+### Parallel Agent Sets theo Command
+
+| Command | Agents chạy song song | Điều kiện |
+|---------|----------------------|-----------|
+| `/tas-plan` (Bước 2) | code-explorer + [architect] | architect khi ảnh hưởng architecture |
+| `/tas-dev` (Bước 3) | [build-resolver] | Chỉ khi tests vẫn fail sau 1 lần tự fix |
+| `/tas-dev` (Bước 4) | code-reviewer + security-reviewer + [lang-reviewer] | lang theo stack |
+| `/tas-bug` (fix step) | [build-resolver] | Chỉ khi build fail hoặc test lỗi compile |
+| `/tas-verify` (Bước 4.5) | e2e-runner | Khi Feature có E2E test cases |
+| `/tas-review` | code-reviewer + security-reviewer + [lang-reviewer] + [aws-reviewer] | lang theo stack; aws nếu có AWS |
+| `/tas-security` | security-reviewer + [database-reviewer] + [aws-reviewer] | db nếu SQL; aws nếu AWS |
+| `tas-implementation-complete` | code-reviewer + security-reviewer + [lang-reviewer] | Auto-invoke khi user nói "done/xong" |
+
+### Cách viết agent prompt trong commands
+
+Mỗi agent trong parallel set cần prompt đủ 4 yếu tố:
+
+```
+**Agent N — `<agent-name>`** (<điều kiện chạy>):
+> [1] Scope — review/analyze cái gì (file path, git diff, directory)
+> [2] Read — rule files nào phải đọc trước khi phân tích
+> [3] Focus — tập trung vào những gì cụ thể
+> [4] Format — Critical / High / Medium / Low với file:line
+```
+
+**Ví dụ chuẩn:**
+```
+**Agent 1 — `security-reviewer`** (luôn chạy):
+> Security audit [scope]. Đọc `.claude/rules/common/security.md`.
+> Tập trung: OWASP Top 10, injection, hardcoded secrets, auth/authz.
+> Format: Critical / High / Medium / Low với file:line và remediation.
+```
+
+### Gate Rule sau khi tổng hợp
+
+```
+Có Critical/High → Block, list findings, yêu cầu fix trước khi tiếp tục
+Chỉ có Medium/Low → List gợi ý, hỏi user có muốn fix không, sau đó tiếp tục
+```
+
+## Rule Files — Khi Nào Agent Cần Đọc
+
+Agents **không tự động nhận** rule files. Commands và skills phải **chủ động** chỉ định trong agent prompt.
+
+| Rule File | Agent nên đọc | Ngữ cảnh |
+|-----------|---------------|----------|
+| `common/security.md` | `security-reviewer` | Mọi security audit |
+| `common/code-review.md` | `code-reviewer` | Mọi code review |
+| `common/testing.md` | `tdd-guide`, lang-reviewers | Review test coverage |
+| `common/patterns.md` | `architect` | Đánh giá architectural choice |
+| `common/development-workflow.md` | `architect`, `planner` | Plan/design phase |
+| `[stack]/coding-style.md` | lang-reviewer | Language-specific review |
+| `[stack]/patterns.md` | lang-reviewer | Language-specific patterns |
+| `[stack]/security.md` | `security-reviewer` | Stack-specific security risks |
+| `[stack]/testing.md` | lang-reviewer | Stack-specific test patterns |
+| `web/design-quality.md` | Frontend reviewer | Review UI code |
+| `web/performance.md` | Frontend reviewer | Review performance |
+
+> Danh sách đầy đủ tất cả agents: xem `.claude/agents/README.md`

package/.claude/rules/common/code-review.md

@@ -0,0 +1,124 @@
+# Code Review Standards
+
+## Purpose
+
+Code review ensures quality, security, and maintainability before code is merged. This rule defines when and how to conduct code reviews.
+
+## When to Review
+
+**MANDATORY review triggers:**
+
+- After writing or modifying code
+- Before any commit to shared branches
+- When security-sensitive code is changed (auth, payments, user data)
+- When architectural changes are made
+- Before merging pull requests
+
+**Pre-Review Requirements:**
+
+Before requesting review, ensure:
+
+- All automated checks (CI/CD) are passing
+- Merge conflicts are resolved
+- Branch is up to date with target branch
+
+## Review Checklist
+
+Before marking code complete:
+
+- [ ] Code is readable and well-named
+- [ ] Functions are focused (<50 lines)
+- [ ] Files are cohesive (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Errors are handled explicitly
+- [ ] No hardcoded secrets or credentials
+- [ ] No console.log or debug statements
+- [ ] Tests exist for new functionality
+- [ ] Test coverage meets 80% minimum
+
+## Security Review Triggers
+
+**STOP and use security-reviewer agent when:**
+
+- Authentication or authorization code
+- User input handling
+- Database queries
+- File system operations
+- External API calls
+- Cryptographic operations
+- Payment or financial code
+
+## Review Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
+| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
+| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
+| LOW | Style or minor suggestion | **NOTE** - Optional |
+
+## Agent Usage
+
+Use these agents for code review:
+
+| Agent | Purpose |
+|-------|---------|
+| **code-reviewer** | General code quality, patterns, best practices |
+| **security-reviewer** | Security vulnerabilities, OWASP Top 10 |
+| **typescript-reviewer** | TypeScript/JavaScript specific issues |
+| **python-reviewer** | Python specific issues |
+| **go-reviewer** | Go specific issues |
+| **rust-reviewer** | Rust specific issues |
+
+## Review Workflow
+
+```
+1. Run git diff to understand changes
+2. Check security checklist first
+3. Review code quality checklist
+4. Run relevant tests
+5. Verify coverage >= 80%
+6. Use appropriate agent for detailed review
+```
+
+## Common Issues to Catch
+
+### Security
+
+- Hardcoded credentials (API keys, passwords, tokens)
+- SQL injection (string concatenation in queries)
+- XSS vulnerabilities (unescaped user input)
+- Path traversal (unsanitized file paths)
+- CSRF protection missing
+- Authentication bypasses
+
+### Code Quality
+
+- Large functions (>50 lines) - split into smaller
+- Large files (>800 lines) - extract modules
+- Deep nesting (>4 levels) - use early returns
+- Missing error handling - handle explicitly
+- Mutation patterns - prefer immutable operations
+- Missing tests - add test coverage
+
+### Performance
+
+- N+1 queries - use JOINs or batching
+- Missing pagination - add LIMIT to queries
+- Unbounded queries - add constraints
+- Missing caching - cache expensive operations
+
+## Approval Criteria
+
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: Only HIGH issues (merge with caution)
+- **Block**: CRITICAL issues found
+
+## Integration with Other Rules
+
+This rule works with:
+
+- [testing.md](testing.md) - Test coverage requirements
+- [security.md](security.md) - Security checklist
+- [git-workflow.md](git-workflow.md) - Commit standards
+- [agents.md](agents.md) - Agent delegation

package/.claude/rules/common/coding-style.md

@@ -0,0 +1,90 @@
+# Coding Style
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate existing ones:
+
+```
+// Pseudocode
+WRONG:  modify(original, field, value) → changes original in-place
+CORRECT: update(original, field, value) → returns new copy with change
+```
+
+Rationale: Immutable data prevents hidden side effects, makes debugging easier, and enables safe concurrency.
+
+## Core Principles
+
+### KISS (Keep It Simple)
+
+- Prefer the simplest solution that actually works
+- Avoid premature optimization
+- Optimize for clarity over cleverness
+
+### DRY (Don't Repeat Yourself)
+
+- Extract repeated logic into shared functions or utilities
+- Avoid copy-paste implementation drift
+- Introduce abstractions when repetition is real, not speculative
+
+### YAGNI (You Aren't Gonna Need It)
+
+- Do not build features or abstractions before they are needed
+- Avoid speculative generality
+- Start simple, then refactor when the pressure is real
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Extract utilities from large modules
+- Organize by feature/domain, not by type
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+- Handle errors explicitly at every level
+- Provide user-friendly error messages in UI-facing code
+- Log detailed error context on the server side
+- Never silently swallow errors
+
+## Input Validation
+
+ALWAYS validate at system boundaries:
+- Validate all user input before processing
+- Use schema-based validation where available
+- Fail fast with clear error messages
+- Never trust external data (API responses, user input, file content)
+
+## Naming Conventions
+
+- Variables and functions: `camelCase` with descriptive names
+- Booleans: prefer `is`, `has`, `should`, or `can` prefixes
+- Interfaces, types, and components: `PascalCase`
+- Constants: `UPPER_SNAKE_CASE`
+- Custom hooks: `camelCase` with a `use` prefix
+
+## Code Smells to Avoid
+
+### Deep Nesting
+
+Prefer early returns over nested conditionals once the logic starts stacking.
+
+### Magic Numbers
+
+Use named constants for meaningful thresholds, delays, and limits.
+
+### Long Functions
+
+Split large functions into focused pieces with clear responsibilities.
+
+## Code Quality Checklist
+
+Before marking work complete:
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No hardcoded values (use constants or config)
+- [ ] No mutation (immutable patterns used)

package/.claude/rules/common/development-workflow.md

@@ -0,0 +1,44 @@
+# Development Workflow
+
+> This file extends [common/git-workflow.md](./git-workflow.md) with the full feature development process that happens before git operations.
+
+The Feature Implementation Workflow describes the development pipeline: research, planning, TDD, code review, and then committing to git.
+
+## Feature Implementation Workflow
+
+0. **Research & Reuse** _(mandatory before any new implementation)_
+   - **GitHub code search first:** Run `gh search repos` and `gh search code` to find existing implementations, templates, and patterns before writing anything new.
+   - **Library docs second:** Use Context7 or primary vendor docs to confirm API behavior, package usage, and version-specific details before implementing.
+   - **Exa only when the first two are insufficient:** Use Exa for broader web research or discovery after GitHub search and primary docs.
+   - **Check package registries:** Search npm, PyPI, crates.io, and other registries before writing utility code. Prefer battle-tested libraries over hand-rolled solutions.
+   - **Search for adaptable implementations:** Look for open-source projects that solve 80%+ of the problem and can be forked, ported, or wrapped.
+   - Prefer adopting or porting a proven approach over writing net-new code when it meets the requirement.
+
+1. **Plan First**
+   - Use **planner** agent to create implementation plan
+   - Generate planning docs before coding: PRD, architecture, system_design, tech_doc, task_list
+   - Identify dependencies and risks
+   - Break down into phases
+
+2. **TDD Approach**
+   - Use **tdd-guide** agent
+   - Write tests first (RED)
+   - Implement to pass tests (GREEN)
+   - Refactor (IMPROVE)
+   - Verify 80%+ coverage
+
+3. **Code Review**
+   - Use **code-reviewer** agent immediately after writing code
+   - Address CRITICAL and HIGH issues
+   - Fix MEDIUM issues when possible
+
+4. **Commit & Push**
+   - Detailed commit messages
+   - Follow conventional commits format
+   - See [git-workflow.md](./git-workflow.md) for commit message format and PR process
+
+5. **Pre-Review Checks**
+   - Verify all automated checks (CI/CD) are passing
+   - Resolve any merge conflicts
+   - Ensure branch is up to date with target branch
+   - Only request review after these checks pass

package/.claude/rules/common/git-workflow.md

@@ -0,0 +1,24 @@
+# Git Workflow
+
+## Commit Message Format
+```
+<type>: <description>
+
+<optional body>
+```
+
+Types: feat, fix, refactor, docs, test, chore, perf, ci
+
+Note: Attribution disabled globally via ~/.claude/settings.json.
+
+## Pull Request Workflow
+
+When creating PRs:
+1. Analyze full commit history (not just latest commit)
+2. Use `git diff [base-branch]...HEAD` to see all changes
+3. Draft comprehensive PR summary
+4. Include test plan with TODOs
+5. Push with `-u` flag if new branch
+
+> For the full development process (planning, TDD, code review) before git operations,
+> see [development-workflow.md](./development-workflow.md).

package/.claude/rules/common/hooks.md

@@ -0,0 +1,30 @@
+# Hooks System
+
+## Hook Types
+
+- **PreToolUse**: Before tool execution (validation, parameter modification)
+- **PostToolUse**: After tool execution (auto-format, checks)
+- **Stop**: When session ends (final verification)
+
+## Auto-Accept Permissions
+
+Use with caution:
+- Enable for trusted, well-defined plans
+- Disable for exploratory work
+- Never use dangerously-skip-permissions flag
+- Configure `allowedTools` in `~/.claude.json` instead
+
+## TodoWrite Best Practices
+
+Use TodoWrite tool to:
+- Track progress on multi-step tasks
+- Verify understanding of instructions
+- Enable real-time steering
+- Show granular implementation steps
+
+Todo list reveals:
+- Out of order steps
+- Missing items
+- Extra unnecessary items
+- Wrong granularity
+- Misinterpreted requirements

package/.claude/rules/common/patterns.md

@@ -0,0 +1,31 @@
+# Common Patterns
+
+## Skeleton Projects
+
+When implementing new functionality:
+1. Search for battle-tested skeleton projects
+2. Use parallel agents to evaluate options:
+   - Security assessment
+   - Extensibility analysis
+   - Relevance scoring
+   - Implementation planning
+3. Clone best match as foundation
+4. Iterate within proven structure
+
+## Design Patterns
+
+### Repository Pattern
+
+Encapsulate data access behind a consistent interface:
+- Define standard operations: findAll, findById, create, update, delete
+- Concrete implementations handle storage details (database, API, file, etc.)
+- Business logic depends on the abstract interface, not the storage mechanism
+- Enables easy swapping of data sources and simplifies testing with mocks
+
+### API Response Format
+
+Use a consistent envelope for all API responses:
+- Include a success/status indicator
+- Include the data payload (nullable on error)
+- Include an error message field (nullable on success)
+- Include metadata for paginated responses (total, page, limit)

package/.claude/rules/common/performance.md

@@ -0,0 +1,55 @@
+# Performance Optimization
+
+## Model Selection Strategy
+
+**Haiku 4.5** (90% of Sonnet capability, 3x cost savings):
+- Lightweight agents with frequent invocation
+- Pair programming and code generation
+- Worker agents in multi-agent systems
+
+**Sonnet 4.6** (Best coding model):
+- Main development work
+- Orchestrating multi-agent workflows
+- Complex coding tasks
+
+**Opus 4.5** (Deepest reasoning):
+- Complex architectural decisions
+- Maximum reasoning requirements
+- Research and analysis tasks
+
+## Context Window Management
+
+Avoid last 20% of context window for:
+- Large-scale refactoring
+- Feature implementation spanning multiple files
+- Debugging complex interactions
+
+Lower context sensitivity tasks:
+- Single-file edits
+- Independent utility creation
+- Documentation updates
+- Simple bug fixes
+
+## Extended Thinking + Plan Mode
+
+Extended thinking is enabled by default, reserving up to 31,999 tokens for internal reasoning.
+
+Control extended thinking via:
+- **Toggle**: Option+T (macOS) / Alt+T (Windows/Linux)
+- **Config**: Set `alwaysThinkingEnabled` in `~/.claude/settings.json`
+- **Budget cap**: `export MAX_THINKING_TOKENS=10000`
+- **Verbose mode**: Ctrl+O to see thinking output
+
+For complex tasks requiring deep reasoning:
+1. Ensure extended thinking is enabled (on by default)
+2. Enable **Plan Mode** for structured approach
+3. Use multiple critique rounds for thorough analysis
+4. Use split role sub-agents for diverse perspectives
+
+## Build Troubleshooting
+
+If build fails:
+1. Use **build-error-resolver** agent
+2. Analyze error messages
+3. Fix incrementally
+4. Verify after each fix

package/.claude/rules/common/post-review-agent.md

@@ -0,0 +1,39 @@
+# Post-Implementation Review (Isolated Agent)
+
+Sau khi implement hoặc fix xong, chạy review qua **Agent độc lập** — không dùng session hiện tại để tránh reviewer bias từ quá trình implement.
+
+## Cách dùng
+
+Gọi `Agent` tool với prompt sau (thay thế các placeholder `{}`):
+
+```
+Bạn là code reviewer. Không có context từ session trước — hãy review hoàn toàn khách quan.
+
+Artifact: {path-to-artifact-file}
+Changed files: {danh sách files vừa thay đổi}
+Stack: {stack từ CLAUDE.md}
+
+Thực hiện:
+1. Hygiene scan: debug code còn sót (console.log, debugger, print), secrets hardcoded,
+   commented-out blocks lớn (>5 dòng).
+2. Chạy tests: detect test runner (package.json → npm test / *.csproj → dotnet test /
+   pytest.ini → python -m pytest), report kết quả.
+3. Parallel review — launch đồng thời:
+   - code-reviewer: đọc .tas/checklists/code-review.md + .claude/rules/common/code-review.md.
+     Tập trung: naming, architecture, error handling, DRY, function size, nesting depth.
+   - security-reviewer: đọc .claude/rules/common/security.md.
+     Tập trung: OWASP Top 10, injection, hardcoded secrets, auth/authz.
+   - {lang_agent}: đọc .claude/rules/[stack]/coding-style.md + .claude/rules/[stack]/patterns.md.
+     Tập trung: async/await, null handling, type safety, anti-patterns của stack.
+4. Tổng hợp findings: Critical / High / Medium / Low với file:line và fix cụ thể.
+
+Trả về Review Summary đầy đủ.
+```
+
+## Gate Rule
+
+| Kết quả | Hành động |
+|---|---|
+| Có **Critical** hoặc **High** | List findings, **DỪNG**, yêu cầu fix trước khi tiếp tục |
+| Chỉ có **Medium** / **Low** | List gợi ý, hỏi user có muốn fix không, sau đó tiếp tục |
+| Không có findings | Tiếp tục bình thường |

package/.claude/rules/common/project-status.md

@@ -0,0 +1,80 @@
+# project-status.yaml — Update Convention
+
+File `project-status.yaml` ở project root là index tổng hợp trạng thái dự án.
+Commands cập nhật file này sau mỗi thay đổi artifact hoặc status.
+
+## Luôn cập nhật
+
+```yaml
+last_updated: YYYY-MM-DD   # ngày hiện tại, mỗi lần có thay đổi
+```
+
+## Artifacts (docs đơn lẻ)
+
+Cập nhật khi tạo mới hoặc thay đổi version:
+
+```yaml
+artifacts:
+  prd:
+    file: docs/prd.md
+    status: Draft | Review | Approved
+    last_updated: YYYY-MM-DD
+    version: "1.0"           # tăng minor khi update nội dung, major khi thay đổi lớn
+    requirements_count: N    # chỉ dành cho PRD — đếm số FR-xxx
+
+  sad:
+    file: docs/sad.md
+    status: Draft | Review | Approved
+    last_updated: YYYY-MM-DD
+    version: "1.0"
+
+  design_spec:
+    file: docs/design-spec.md
+    status: Draft | Review | Approved
+    last_updated: YYYY-MM-DD
+    version: "1.0"
+
+  security_report:
+    file: docs/security-report.md
+    status: "Critical findings present" | "Clean"
+    last_updated: YYYY-MM-DD
+```
+
+## Epics / Features / Stories
+
+Cập nhật khi tạo mới hoặc status thay đổi:
+
+```yaml
+epics:
+  Epic-001:
+    path: docs/epics/{code}-Epic-001-{slug}/
+    status: Draft | Active | Done
+    title: "..."
+    effort: S | M | L | XL
+    features:
+      Feature-001:
+        status: New | In Progress | Ready To Verify | Verified | Done
+        title: "..."
+        stories:
+          Story-001:
+            status: New | Committed | In Progress | Deploy Test | Verify Test | Done
+            title: "..."
+            plan_status: pending | completed
+```
+
+## ADRs
+
+```yaml
+adrs:
+  ADR-001:
+    file: docs/adr/ADR-001-{slug}.md
+    status: Proposed | Accepted | Deprecated | Superseded
+    title: "..."
+```
+
+## Quy tắc
+
+- Chỉ cập nhật key liên quan đến thay đổi vừa xảy ra — không rewrite toàn bộ file
+- Nếu key chưa tồn tại: thêm mới
+- Nếu key đã tồn tại: cập nhật giá trị
+- Version: minor (+0.1) khi update nội dung; major (+1.0) khi thay đổi cấu trúc lớn

package/.claude/rules/common/security.md

@@ -0,0 +1,29 @@
+# Security Guidelines
+
+## Mandatory Security Checks
+
+Before ANY commit:
+- [ ] No hardcoded secrets (API keys, passwords, tokens)
+- [ ] All user inputs validated
+- [ ] SQL injection prevention (parameterized queries)
+- [ ] XSS prevention (sanitized HTML)
+- [ ] CSRF protection enabled
+- [ ] Authentication/authorization verified
+- [ ] Rate limiting on all endpoints
+- [ ] Error messages don't leak sensitive data
+
+## Secret Management
+
+- NEVER hardcode secrets in source code
+- ALWAYS use environment variables or a secret manager
+- Validate that required secrets are present at startup
+- Rotate any secrets that may have been exposed
+
+## Security Response Protocol
+
+If security issue found:
+1. STOP immediately
+2. Use **security-reviewer** agent
+3. Fix CRITICAL issues before continuing
+4. Rotate any exposed secrets
+5. Review entire codebase for similar issues

package/.claude/rules/common/stack-detection.md

@@ -0,0 +1,29 @@
+# Stack Detection
+
+Đọc `CLAUDE.md` tại root, tìm section `## Tech Stack`, xác định các biến sau để dùng trong agent prompts và rule file lookups.
+
+## lang_agent — Backend
+
+| Tech Stack chứa | lang_agent |
+|---|---|
+| `.NET` / `C#` | `csharp-reviewer` |
+| `Node.js` / `TypeScript` / `NestJS` / `Express` | `typescript-reviewer` |
+| `Python` / `FastAPI` / `Django` / `Flask` | `python-reviewer` |
+
+**Frontend bổ sung:** nếu Tech Stack chứa `React` → thêm `typescript-reviewer` vào lang_agent (nếu chưa có).
+
+## infra_agent và db_agent — Tùy chọn
+
+| Tech Stack chứa | Biến | Value |
+|---|---|---|
+| `AWS` (Infrastructure) | `infra_agent` | `aws-reviewer` |
+| `MySQL` / `PostgreSQL` / `MSSQL` / `SQL Server` / `SQLite` | `db_agent` | `database-reviewer` |
+
+## Rules directory theo stack
+
+| lang_agent | Rules directory |
+|---|---|
+| `csharp-reviewer` | `.claude/rules/csharp/` |
+| `typescript-reviewer` | `.claude/rules/typescript/` |
+| `python-reviewer` | `.claude/rules/python/` |
+| Frontend / React | `.claude/rules/web/` |