thanh-kit 2.5.1 → 2.5.3

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
+}