thanh-kit 2.5.0 → 2.5.2

package/templates/{workflows → rules}/development-rules.md

@@ -4,38 +4,30 @@
 **IMPORTANT:** You ALWAYS follow these principles: **YAGNI (You Aren't Gonna Need It) - KISS (Keep It Simple, Stupid) - DRY (Don't Repeat Yourself)**
 
 ## General
-
 - **File Naming**: Use kebab-case for file names with a meaningful name that describes the purpose of the file, doesn't matter if the file name is long, just make sure when LLMs read the file names while using Grep or other tools, they can understand the purpose of the file right away without reading the file content.
-- **File Size Management**: Keep individual code files under 300 lines for optimal context management
+- **File Size Management**: Keep individual code files under 200 lines for optimal context management
   - Split large files into smaller, focused components/modules
   - Use composition over inheritance for complex widgets
   - Extract utility functions into separate modules
   - Create dedicated service classes for business logic
-- Use `docs-seeker` skill for exploring latest docs of plugins/packages if needed
+- When looking for docs, activate `docs-seeker` skill (`context7` reference) for exploring latest docs.
 - Use `gh` bash command to interact with Github features if needed
 - Use `psql` bash command to query Postgres database for debugging if needed
 - Use `ai-multimodal` skill for describing details of images, videos, documents, etc. if needed
 - Use `ai-multimodal` skill and `imagemagick` skill for generating and editing images, videos, documents, etc. if needed
-- Use `sequential-thinking` skill and `debugging` skills for sequential thinking, analyzing code, debugging, etc. if needed
+- Use `sequential-thinking` and `debug` skills for sequential thinking, analyzing code, debugging, etc. if needed
 - **[IMPORTANT]** Follow the codebase structure and code standards in `./docs` during implementation.
 - **[IMPORTANT]** Do not just simulate the implementation or mocking them, always implement the real code.
 
 ## Code Quality Guidelines
-
 - Read and follow codebase structure and code standards in `./docs`
 - Don't be too harsh on code linting, but **make sure there are no syntax errors and code are compilable**
 - Prioritize functionality and readability over strict style enforcement and code formatting
 - Use reasonable code quality standards that enhance developer productivity
 - Use try catch error handling & cover security standards
 - Use `code-reviewer` agent to review code after every implementation
-- **[CRITICAL] Class Responsibility Rule:**
-  - Logic belongs in LOWEST layer: Entity/Model > Service > Component/Handler
-  - Backend: Entity mapping → Command.UpdateEntity() or DTO.MapToEntity(), NOT in Handler
-  - Frontend: Constants, column arrays, role lists → static properties in Model class, NOT in Component
-  - Frontend: Display logic (CSS class, status text) → instance getter in Model, NOT switch in Component
 
 ## Pre-commit/Push Rules
-
 - Run linting before commit
 - Run tests before push (DO NOT ignore failed tests just to pass the build or github actions)
 - Keep commits focused on the actual code changes
@@ -43,51 +35,18 @@
 - Create clean, professional commit messages without AI references. Use conventional commit format.
 
 ## Code Implementation
-
 - Write clean, readable, and maintainable code
 - Follow established architectural patterns
 - Implement features according to specifications
 - Handle edge cases and error scenarios
 - **DO NOT** create new enhanced files, update to the existing files directly.
 
-## Mandatory Post-Task Two-Pass Review Protocol
-
-**CRITICAL:** After ANY code changes (bug fix or feature), execute this protocol BEFORE task completion.
-
-### Pass 1: Initial Review
-
-1. Run `git diff` to examine unstaged changes
-2. Verify changes correctly implement the task requirements
-3. Check compliance with project conventions and best practices:
-   - Backend: repository patterns, validation fluent API, DTOs, event handlers
-   - Frontend: base classes, stores, BEM classes, untilDestroyed()
-4. Identify security vulnerabilities and edge cases
-5. Fix any issues found → mark `MADE_CHANGES = true`
-
-### Pass 2: Re-Review (Conditional)
-
-**ONLY IF Pass 1 made changes:**
-
-1. Run `git diff` again to verify all current changes
-2. Re-execute full review checklist on updated code
-3. Ensure corrections didn't introduce new issues
-4. Apply minimal, targeted fixes if needed
-
-### Quick Reference
-
-```bash
-# Execute review
-/review:post-task
-
-# Or use code-reviewer subagent for complex reviews
-Task tool → code-reviewer subagent
-```
-
-### Review Checklist Quick Reference
-
-- [ ] Task objective achieved correctly
-- [ ] No unrelated/unnecessary modifications
-- [ ] Follows project code conventions
-- [ ] No security vulnerabilities
-- [ ] Edge cases handled
-- [ ] Ready for commit
+## Visual Aids
+- Use `/preview --explain` when explaining unfamiliar code patterns or complex logic
+- Use `/preview --diagram` for architecture diagrams and data flow visualization
+- Use `/preview --slides` for step-by-step walkthroughs and presentations
+- Use `/preview --ascii` for terminal-friendly diagrams (no browser needed to understand)
+- **Plan context:** Active plan determined from `## Plan Context` in hook injection; visuals save to `{plan_dir}/visuals/`
+- If no active plan, fallback to `plans/visuals/` directory
+- For Mermaid diagrams, use `/mermaidjs-v11` skill for v11 syntax rules
+- See `primary-workflow.md` → Step 6 for workflow integration

package/templates/rules/orchestration-protocol.md

@@ -0,0 +1,43 @@
+# Orchestration Protocol
+
+## Delegation Context (MANDATORY)
+
+When spawning subagents via Task tool, **ALWAYS** include in prompt:
+
+1. **Work Context Path**: The git root of the PRIMARY files being worked on
+2. **Reports Path**: `{work_context}/plans/reports/` for that project
+3. **Plans Path**: `{work_context}/plans/` for that project
+
+**Example:**
+```
+Task prompt: "Fix parser bug.
+Work context: /path/to/project-b
+Reports: /path/to/project-b/plans/reports/
+Plans: /path/to/project-b/plans/"
+```
+
+**Rule:** If CWD differs from work context (editing files in different project), use the **work context paths**, not CWD paths.
+
+---
+
+#### Sequential Chaining
+Chain subagents when tasks have dependencies or require outputs from previous steps:
+- **Planning → Implementation → Simplification → Testing → Review**: Use for feature development (tests verify simplified code)
+- **Research → Design → Code → Documentation**: Use for new system components
+- Each agent completes fully before the next begins
+- Pass context and outputs between agents in the chain
+
+#### Parallel Execution
+Spawn multiple subagents simultaneously for independent tasks:
+- **Code + Tests + Docs**: When implementing separate, non-conflicting components
+- **Multiple Feature Branches**: Different agents working on isolated features
+- **Cross-platform Development**: iOS and Android specific implementations
+- **Careful Coordination**: Ensure no file conflicts or shared resource contention
+- **Merge Strategy**: Plan integration points before parallel execution begins
+
+---
+
+## Agent Teams (Optional)
+
+For multi-session parallel collaboration, activate the `/team` skill.
+Not part of the default orchestration workflow. See `.claude/skills/team/SKILL.md` for templates, decision criteria, and spawn instructions.

package/templates/{workflows → rules}/primary-workflow.md

@@ -14,17 +14,18 @@
 - **[IMPORTANT]** After creating or modifying code file, run compile command/script to check for any compile errors.
 
 #### 2. Testing
-- Delegate to `tester` agent to run tests and analyze the summary report.
+- Delegate to `tester` agent to run tests on the **simplified code**
   - Write comprehensive unit tests
   - Ensure high code coverage
   - Test error scenarios
   - Validate performance requirements
-- Tests are critical for ensuring code quality and reliability, **DO NOT** ignore failing tests just to pass the build.
+- Tests verify the FINAL code that will be reviewed and merged
+- **DO NOT** ignore failing tests just to pass the build.
 - **IMPORTANT:** make sure you don't use fake data, mocks, cheats, tricks, temporary solutions, just to pass the build or github actions.
 - **IMPORTANT:** Always fix failing tests follow the recommendations and delegate to `tester` agent to run tests again, only finish your session when all tests pass.
 
 #### 3. Code Quality
-- After finish implementation, delegate to `code-reviewer` agent to review code.
+- After testing passes, delegate to `code-reviewer` agent to review clean, tested code.
 - Follow coding standards and conventions
 - Write self-documenting code
 - Add meaningful comments for complex logic
@@ -42,4 +43,15 @@
 - When a user report bugs or issues on the server or a CI/CD pipeline, delegate to `debugger` agent to run tests and analyze the summary report.
 - Read the summary report from `debugger` agent and implement the fix.
 - Delegate to `tester` agent to run tests and analyze the summary report.
-- If the `tester` agent reports failed tests, fix them follow the recommendations and repeat from the **Step 2**.
+- If the `tester` agent reports failed tests, fix them follow the recommendations and repeat from the **Step 3**.
+
+#### 6. Visual Explanations
+When explaining complex code, protocols, or architecture:
+- **When to use:** User asks "explain", "how does X work", "visualize", or topic has 3+ interacting components
+- Use `/preview --explain <topic>` to generate visual explanation with ASCII + Mermaid
+- Use `/preview --diagram <topic>` for architecture and data flow diagrams
+- Use `/preview --slides <topic>` for step-by-step walkthroughs
+- Use `/preview --ascii <topic>` for terminal-friendly output only
+- **Plan context:** Visuals save to plan folder from `## Plan Context` hook injection; if none, uses `plans/visuals/`
+- Auto-opens in browser via markdown-novel-viewer with Mermaid rendering
+- See `development-rules.md` → "Visual Aids" section for additional guidance

package/templates/rules/team-coordination-rules.md

@@ -0,0 +1,90 @@
+# Team Coordination Rules
+
+> These rules only apply when operating as a teammate within an Agent Team.
+> They have no effect on standard sessions or subagent workflows.
+
+Rules for agents operating as teammates within an Agent Team.
+
+## File Ownership (CRITICAL)
+
+- Each teammate MUST own distinct files — no overlapping edits
+- Define ownership via glob patterns in task descriptions: `File ownership: src/api/*, src/models/*`
+- Lead resolves ownership conflicts by restructuring tasks or handling shared files directly
+- Tester owns test files only; reads implementation files but never edits them
+- If ownership violation detected: STOP and report to lead immediately
+
+## Git Safety
+
+- Prefer git worktrees for implementation teams — each dev in own worktree eliminates conflicts
+- Never force-push from a teammate session
+- Commit frequently with descriptive messages
+- Pull before push to catch merge conflicts early
+- If working in a git worktree, commit/push to the worktree branch — not main or dev
+
+## Communication Protocol
+
+- Use `SendMessage(type: "message")` for peer DMs — always specify recipient by name
+- Use `SendMessage(type: "broadcast")` ONLY for critical blocking issues affecting entire team
+- Mark tasks completed via `TaskUpdate` BEFORE sending completion message to lead
+- Include actionable findings in messages, not just "I'm done"
+- Never send structured JSON status messages — use plain text
+
+## CK Stack Conventions
+
+### Report Output
+- Save reports to `{CK_REPORTS_PATH}` (injected via hook, fallback: `plans/reports/`)
+- Naming: `{type}-{date}-{slug}.md` where type = your role (researcher, reviewer, debugger)
+- Sacrifice grammar for concision. List unresolved questions at end.
+
+### Commit Messages
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- No AI references in commit messages
+- Keep commits focused on actual code changes
+
+### Docs Sync (Implementation Teams Only)
+- After completing implementation tasks, lead MUST evaluate docs impact
+- State explicitly: `Docs impact: [none|minor|major]`
+- If impact: update `docs/` directory or note in completion message
+
+## Task Claiming
+
+- Claim lowest-ID unblocked task first (earlier tasks set up context for later ones)
+- Check `TaskList` after completing each task for newly unblocked work
+- Set task to `in_progress` before starting work
+- If all tasks blocked, notify lead and offer to help unblock
+
+## Plan Approval Flow
+
+When `plan_mode_required` is set:
+1. Research and plan your approach (read-only — no file edits)
+2. Send plan via `ExitPlanMode` — this triggers approval request to lead
+3. Wait for lead's `plan_approval_response`
+4. If rejected: revise based on feedback, resubmit
+5. If approved: proceed with implementation
+
+## Conflict Resolution
+
+- If two teammates need the same file: escalate to lead immediately
+- If a teammate's plan is rejected twice: lead takes over that task
+- If findings conflict between reviewers: lead synthesizes and documents disagreement
+- If blocked by another teammate's incomplete work: message them directly first, escalate to lead if unresponsive
+
+## Shutdown Protocol
+
+- Approve shutdown requests unless mid-critical-operation
+- Always mark current task as completed before approving shutdown
+- If rejecting shutdown, explain why concisely
+- Extract `requestId` from shutdown request JSON and pass to `shutdown_response`
+
+## Idle State (Normal Behavior)
+
+- Going idle after sending a message is NORMAL — not an error
+- Idle means waiting for input, not disconnected
+- Sending a message to an idle teammate wakes them up
+- Do not treat idle notifications as completion signals — check task status instead
+
+## Discovery
+
+- Read team config at `~/.claude/teams/{team-name}/config.json` to discover teammates
+- Always refer to teammates by NAME (not agent ID)
+- Names are used for: `recipient` in SendMessage, task `owner` in TaskUpdate

package/templates/schemas/ck-config.schema.json

@@ -0,0 +1,381 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema#",
+  "$id": "https://claudekit.cc/schemas/ck-config.schema.json",
+  "title": "ClaudeKit Configuration",
+  "description": "Configuration schema for ClaudeKit Engineer .ck.json files",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "JSON Schema reference for editor autocompletion"
+    },
+    "codingLevel": {
+      "type": "integer",
+      "minimum": -1,
+      "maximum": 3,
+      "default": -1,
+      "description": "User coding experience level: -1=auto, 0=beginner, 1=intermediate, 2=advanced, 3=expert"
+    },
+    "privacyBlock": {
+      "type": "boolean",
+      "default": true,
+      "description": "Enable privacy block hook to protect sensitive files (.env, credentials, etc.)"
+    },
+    "docs": {
+      "type": "object",
+      "description": "Documentation settings",
+      "properties": {
+        "maxLoc": {
+          "type": "integer",
+          "minimum": 100,
+          "maximum": 5000,
+          "default": 800,
+          "description": "Maximum lines of code per documentation file"
+        }
+      },
+      "additionalProperties": false
+    },
+    "plan": {
+      "type": "object",
+      "description": "Plan naming and validation settings",
+      "properties": {
+        "namingFormat": {
+          "type": "string",
+          "default": "{date}-{issue}-{slug}",
+          "description": "Format for plan directory names. Variables: {date}, {issue}, {slug}"
+        },
+        "dateFormat": {
+          "type": "string",
+          "default": "YYMMDD-HHmm",
+          "description": "Date format for plan names (moment.js format)"
+        },
+        "issuePrefix": {
+          "type": "string",
+          "default": "GH-",
+          "description": "Prefix for issue references (e.g., GH-, JIRA-)"
+        },
+        "reportsDir": {
+          "type": "string",
+          "default": "reports",
+          "description": "Subdirectory name for reports within plans"
+        },
+        "resolution": {
+          "type": "object",
+          "description": "Plan resolution settings",
+          "properties": {
+            "order": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "session",
+                  "branch",
+                  "directory"
+                ]
+              },
+              "default": [
+                "session",
+                "branch"
+              ],
+              "description": "Order of resolution strategies for plan context"
+            },
+            "branchPattern": {
+              "type": "string",
+              "default": "(?:feat|fix|chore|refactor|docs)/(?:[^/]+/)?(.+)",
+              "description": "Regex pattern to extract plan slug from branch name"
+            }
+          },
+          "additionalProperties": false
+        },
+        "validation": {
+          "type": "object",
+          "description": "Plan validation settings",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "prompt",
+                "auto",
+                "strict",
+                "none"
+              ],
+              "default": "prompt",
+              "description": "Validation mode: prompt=ask questions, auto=auto-validate, strict=require all, none=skip"
+            },
+            "minQuestions": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 20,
+              "default": 3,
+              "description": "Minimum validation questions to ask"
+            },
+            "maxQuestions": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 20,
+              "default": 8,
+              "description": "Maximum validation questions to ask"
+            },
+            "focusAreas": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "assumptions",
+                  "risks",
+                  "tradeoffs",
+                  "architecture",
+                  "security",
+                  "performance",
+                  "testing",
+                  "dependencies"
+                ]
+              },
+              "default": [
+                "assumptions",
+                "risks",
+                "tradeoffs",
+                "architecture"
+              ],
+              "description": "Focus areas for validation questions"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "paths": {
+      "type": "object",
+      "description": "Directory paths configuration",
+      "properties": {
+        "docs": {
+          "type": "string",
+          "default": "docs",
+          "description": "Path to documentation directory"
+        },
+        "plans": {
+          "type": "string",
+          "default": "plans",
+          "description": "Path to plans directory"
+        }
+      },
+      "additionalProperties": false
+    },
+    "locale": {
+      "type": "object",
+      "description": "Language and locale settings",
+      "properties": {
+        "thinkingLanguage": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Language for Claude's thinking (null=English)"
+        },
+        "responseLanguage": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Language for Claude's responses (null=match user)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "trust": {
+      "type": "object",
+      "description": "Trust mode settings for auto-approval",
+      "properties": {
+        "passphrase": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Passphrase to enable trust mode (null=disabled)"
+        },
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether trust mode is currently enabled"
+        }
+      },
+      "additionalProperties": false
+    },
+    "project": {
+      "type": "object",
+      "description": "Project type detection settings",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "library",
+            "application",
+            "monorepo",
+            "cli",
+            "api",
+            "web",
+            "mobile"
+          ],
+          "default": "auto",
+          "description": "Project type (auto=detect from package.json)"
+        },
+        "packageManager": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "npm",
+            "yarn",
+            "pnpm",
+            "bun"
+          ],
+          "default": "auto",
+          "description": "Package manager (auto=detect from lockfile)"
+        },
+        "framework": {
+          "type": "string",
+          "enum": [
+            "auto",
+            "react",
+            "vue",
+            "angular",
+            "svelte",
+            "nextjs",
+            "nuxt",
+            "express",
+            "nestjs",
+            "fastify",
+            "none"
+          ],
+          "default": "auto",
+          "description": "Framework (auto=detect from dependencies)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "gemini": {
+      "type": "object",
+      "description": "Gemini CLI configuration",
+      "properties": {
+        "model": {
+          "type": "string",
+          "enum": [
+            "gemini-2.5-flash",
+            "gemini-2.5-pro",
+            "gemini-3-pro-preview",
+            "gemini-3-flash-preview"
+          ],
+          "default": "gemini-3-flash-preview",
+          "description": "Gemini model to use for CLI commands"
+        }
+      },
+      "additionalProperties": false
+    },
+    "skills": {
+      "type": "object",
+      "description": "Per-skill configuration",
+      "properties": {
+        "research": {
+          "type": "object",
+          "properties": {
+            "useGemini": {
+              "type": "boolean",
+              "default": true,
+              "description": "Use Gemini CLI for research (false=use WebSearch)"
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": {
+        "type": "object",
+        "description": "Custom skill configuration"
+      }
+    },
+    "assertions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "pattern": {
+            "type": "string",
+            "description": "Glob pattern or regex for files to match"
+          },
+          "rule": {
+            "type": "string",
+            "description": "Assertion rule to enforce"
+          },
+          "message": {
+            "type": "string",
+            "description": "Error message when assertion fails"
+          }
+        }
+      },
+      "default": [],
+      "description": "Code assertions and rules to enforce"
+    },
+    "statusline": {
+      "type": "string",
+      "enum": ["full", "compact", "minimal", "none"],
+      "default": "full",
+      "description": "Statusline display mode: full=all features, compact=2-3 lines, minimal=single text line, none=disabled"
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Toggle individual hooks on/off. Default: all enabled. Set a hook to `false` to disable; only explicit `false` disables (undefined/null/missing keys default to enabled).",
+      "properties": {
+        "session-init": {
+          "type": "boolean",
+          "default": true,
+          "description": "SessionStart hook - project detection and env setup"
+        },
+        "subagent-init": {
+          "type": "boolean",
+          "default": true,
+          "description": "SubagentStart hook - injects context to subagents"
+        },
+        "descriptive-name": {
+          "type": "boolean",
+          "default": true,
+          "description": "PreToolUse hook - descriptive name for scripts"
+        },
+        "dev-rules-reminder": {
+          "type": "boolean",
+          "default": true,
+          "description": "UserPromptSubmit hook - injects dev rules context"
+        },
+        "usage-context-awareness": {
+          "type": "boolean",
+          "default": true,
+          "description": "UserPromptSubmit/PostToolUse hook - usage limits fetching and injection"
+        },
+        "context-tracking": {
+          "type": "boolean",
+          "default": true,
+          "description": "Context window tracking injection (% used, token counts) in dev-rules-reminder"
+        },
+        "scout-block": {
+          "type": "boolean",
+          "default": true,
+          "description": "PreToolUse hook - blocks heavy directories"
+        },
+        "privacy-block": {
+          "type": "boolean",
+          "default": true,
+          "description": "PreToolUse hook - blocks sensitive files"
+        },
+        "post-edit-simplify-reminder": {
+          "type": "boolean",
+          "default": true,
+          "description": "PostToolUse hook - simplify reminder after edits"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true
+}