claude-toolkit 0.1.9

package/core/commands/ct/pr-review.md

@@ -0,0 +1,104 @@
+---
+description: "Review a pull request using project standards"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# Pull Request Review
+
+Perform a checklist-based code review on the current PR or a specified PR number. Evaluate against project standards and common quality criteria.
+
+## Workflow
+
+1. **Get PR context.** If a PR number is provided, fetch it with `gh pr view {number} --json title,body,files,commits`. Otherwise, diff the current branch against the base branch (`main` or `master`).
+
+2. **Read all changed files** in full to understand the complete context of the change. Do not review diffs in isolation — understand what the surrounding code does.
+
+3. **Run the review checklist** against every changed file.
+
+4. **Compile findings** into a structured review.
+
+## Review Checklist
+
+### Logic Correctness
+- Are conditionals and branches correct? Any off-by-one errors?
+- Are edge cases handled (empty inputs, null values, boundary conditions)?
+- Does the control flow match the intended behavior?
+- Are there any unreachable code paths?
+
+### Type Safety
+- Are types precise (no `any`, no unsafe casts, no overly broad unions)?
+- Is type narrowing used correctly before accessing properties?
+- Are generic constraints appropriate?
+- Are return types explicit where they should be?
+
+### Error Handling
+- Are errors caught and handled meaningfully (not swallowed)?
+- Do error messages provide enough context for debugging?
+- Are error boundaries or fallbacks in place where needed?
+- Is cleanup logic (finally blocks, defer, etc.) correct?
+
+### Test Coverage
+- Are new behaviors covered by tests?
+- Do tests focus on behavior, not implementation details?
+- Are edge cases and error paths tested?
+- Are test descriptions clear and descriptive?
+
+### Performance
+- Any unnecessary re-renders, recomputations, or allocations?
+- Any N+1 query patterns or missing pagination?
+- Any missing memoization for expensive operations?
+- Any potential memory leaks (unclosed resources, dangling listeners)?
+
+### Security
+- Any injection vulnerabilities (SQL, XSS, command injection)?
+- Are user inputs validated and sanitized?
+- Are auth checks present on protected operations?
+- Are secrets or sensitive data properly handled (not logged, not exposed)?
+
+### Code Style
+- Does naming follow project conventions?
+- Is the code readable without excessive comments?
+- Are abstractions at the right level (not over- or under-engineered)?
+- Is there unnecessary duplication?
+
+## Output Format
+
+```markdown
+## PR Review: {title}
+
+**Branch:** {branch} -> {base}
+**Files changed:** {count}
+**Verdict:** {APPROVE | REQUEST_CHANGES | COMMENT}
+
+### Critical Issues
+> Must be fixed before merge.
+
+- **[CRITICAL]** {file}:{line} - {description}
+
+### Warnings
+> Should be addressed, but not blocking.
+
+- **[WARNING]** {file}:{line} - {description}
+
+### Suggestions
+> Nice-to-have improvements.
+
+- **[SUGGESTION]** {file}:{line} - {description}
+
+### Positive Notes
+- {things done well}
+
+### Summary
+{1-3 sentence overall assessment}
+```
+
+## Notes
+
+- Be specific. Reference file names and line numbers.
+- Distinguish between opinion and objective issues.
+- Acknowledge good patterns, not just problems.
+- If the PR is too large to review effectively, say so and suggest splitting it.

package/core/commands/ct/pr-summary.md

@@ -0,0 +1,59 @@
+---
+description: "Generate a PR summary from the current branch"
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# PR Summary Generator
+
+Generate a structured pull request summary by analyzing the diff and commit history of the current branch against its base.
+
+## Workflow
+
+1. **Identify the base branch.** Check for `main` or `master`. Use `git merge-base` to find the common ancestor.
+
+2. **Gather the diff.** Run `git diff {base}...HEAD --stat` for an overview and `git diff {base}...HEAD` for full changes.
+
+3. **Gather commit history.** Run `git log {base}...HEAD --oneline --no-merges` to understand the progression of changes.
+
+4. **Analyze changes** by reading modified files to understand the "why" behind each change. Group related changes together.
+
+5. **Generate the summary.**
+
+## Output Format
+
+```markdown
+## Summary
+
+{1-3 bullet points describing the high-level purpose of this PR}
+
+## What Changed
+
+### {Category 1} (e.g., "Authentication", "Database", "UI")
+- `{file}` - {what changed and why}
+- `{file}` - {what changed and why}
+
+### {Category 2}
+- ...
+
+## Impact Assessment
+
+- **Risk level:** {low | medium | high}
+- **Affected areas:** {list of features or systems impacted}
+- **Breaking changes:** {none, or describe}
+- **Migration needed:** {none, or describe}
+
+## Testing Notes
+
+- {How to test this change}
+- {Key scenarios to verify}
+- {Any manual testing required}
+```
+
+## Notes
+
+- Infer the "why" from commit messages, code comments, and the nature of changes. Do not just list file names.
+- Group related file changes under meaningful categories, not one-file-per-bullet.
+- Be honest about risk level. If you see potential issues, flag them in Testing Notes.
+- Keep it concise. The summary should be scannable in under 60 seconds.

package/core/commands/ct/proto-check.md

@@ -0,0 +1,74 @@
+---
+description: "Validate protobuf definitions and check for breaking changes"
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# Protobuf Validation
+
+Validate protobuf definitions for correctness, lint compliance, and backward compatibility. Regenerate types and verify the generated code compiles.
+
+## Workflow
+
+1. **Find proto files.** Locate all `.proto` files in the project. Identify the buf configuration (`buf.yaml`, `buf.gen.yaml`) or other protobuf tooling in use.
+
+2. **Run lint checks.** Execute `buf lint` (or the project-configured linter) against proto definitions. Report any style or correctness violations.
+
+3. **Check for breaking changes.** Run `buf breaking --against .git#branch=main` (or equivalent) to detect backward-incompatible changes. Common breaking changes include:
+   - Removing or renaming fields
+   - Changing field numbers
+   - Changing field types
+   - Removing services or RPCs
+   - Changing RPC signatures
+
+4. **Regenerate types.** Run `buf generate` (or the project-configured generation command) to regenerate code from proto definitions.
+
+5. **Verify generated code compiles.** Run the project's typecheck or build command to ensure the regenerated code is valid and integrates correctly with the rest of the codebase.
+
+6. **Report results.**
+
+## Output Format
+
+```markdown
+## Protobuf Validation Report
+
+**Proto files found:** {count}
+**Buf config:** {path or "not found"}
+
+### Lint Results
+- **Status:** {pass | fail}
+- **Issues:** {count}
+
+| File | Line | Rule | Message |
+|------|------|------|---------|
+| ...  | ...  | ...  | ...     |
+
+### Breaking Change Check
+- **Status:** {pass | fail}
+- **Against:** {branch or reference}
+- **Breaking changes found:** {count}
+
+| File | Change | Description |
+|------|--------|-------------|
+| ...  | ...    | ...         |
+
+### Code Generation
+- **Status:** {success | failure}
+- **Files generated:** {count}
+
+### Compilation Check
+- **Status:** {pass | fail}
+- **Errors:** {if any}
+
+### Summary
+{Overall status and recommended actions}
+```
+
+## Notes
+
+- If `buf` is not installed, check for alternative protobuf tooling (`protoc`, `grpc_tools`, etc.) before reporting failure.
+- If no proto files are found, report that clearly rather than failing silently.
+- Breaking changes are not always wrong — they just need to be intentional. Flag them for human review rather than treating them as errors.

package/core/commands/ct/ticket.md

@@ -0,0 +1,71 @@
+---
+description: "Work end-to-end on a ticket or issue"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+---
+
+# Ticket Workflow
+
+Work on a ticket or issue end-to-end: understand it, explore the codebase, plan the implementation, build it, test it, and prepare a PR.
+
+## Workflow
+
+### Phase 1: Understand
+
+1. **Read the ticket.** If a GitHub issue number is provided, fetch it with `gh issue view {number}`. Otherwise, use the description provided by the user.
+
+2. **Clarify requirements.** Identify acceptance criteria, edge cases, and constraints. If anything is ambiguous, ask before proceeding.
+
+3. **Identify scope.** What needs to change? What should NOT change? Are there related tickets or dependencies?
+
+### Phase 2: Explore
+
+4. **Find relevant code.** Search for files, functions, and patterns related to the ticket. Read them fully to understand the current behavior.
+
+5. **Understand the test landscape.** Find existing tests for the affected area. Note the testing framework, patterns, and coverage.
+
+6. **Check for related changes.** Look at recent commits or PRs in the affected area for context.
+
+### Phase 3: Plan
+
+7. **Draft an implementation plan.** List the specific changes needed, in order:
+   - Files to create or modify
+   - Functions to add or change
+   - Tests to write
+   - Migrations or config changes needed
+
+8. **Share the plan with the user** and get confirmation before proceeding. If the change is small and obvious, proceed directly.
+
+### Phase 4: Implement
+
+9. **Create a feature branch** following project conventions (e.g., `feat/description`, `fix/description`).
+
+10. **Write tests first** when applicable (TDD). Write failing tests that describe the desired behavior, then implement to make them pass.
+
+11. **Implement the changes.** Follow project conventions for code style, error handling, and naming. Make focused, atomic changes.
+
+12. **Run quality checks.** Run lint, typecheck, and tests. Fix any issues introduced by the changes.
+
+### Phase 5: Deliver
+
+13. **Commit with conventional commit messages.** Group related changes into logical commits.
+
+14. **Create a PR** with a clear title and description. Include:
+    - Summary of what changed and why
+    - How to test
+    - Any follow-up work needed
+
+15. **Report back** with the PR link and a summary of what was done.
+
+## Notes
+
+- Always ask before making architectural decisions (new tables, new services, changing frameworks).
+- Do not gold-plate. Implement what the ticket asks for, nothing more.
+- If the ticket is too large for a single PR, propose splitting it and implement the first piece.
+- If you discover bugs or issues outside the ticket scope, note them but do not fix them unless they block the ticket.
+- Prefer small, reviewable PRs over large monolithic ones.

package/core/hooks/skill-eval.js

@@ -0,0 +1,381 @@
+#!/usr/bin/env node
+/**
+ * Skill Evaluation Engine v2.0
+ *
+ * Intelligent skill activation based on:
+ * - Keywords and patterns in prompts
+ * - File paths mentioned or being edited
+ * - Directory mappings
+ * - Intent detection
+ * - Content pattern matching
+ *
+ * Outputs a structured reminder with matched skills and reasons.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+// Configuration
+const RULES_PATH = path.join(__dirname, "skill-rules.json");
+
+/**
+ * @typedef {Object} SkillMatch
+ * @property {string} name - Skill name
+ * @property {number} score - Confidence score
+ * @property {string[]} reasons - Why this skill was matched
+ * @property {number} priority - Skill priority
+ */
+
+/**
+ * Load skill rules from JSON file
+ * @returns {Object} Parsed skill rules
+ */
+function loadRules() {
+	try {
+		const content = fs.readFileSync(RULES_PATH, "utf-8");
+		return JSON.parse(content);
+	} catch (error) {
+		console.error(`Failed to load skill rules: ${error.message}`);
+		process.exit(0);
+	}
+}
+
+/**
+ * Extract file paths mentioned in the prompt
+ * @param {string} prompt - User's prompt text
+ * @returns {string[]} Array of detected file paths
+ */
+function extractFilePaths(prompt) {
+	const paths = new Set();
+
+	// Match explicit paths with extensions
+	const extensionPattern =
+		/(?:^|\s|["'`])([\w\-./]+\.(?:[tj]sx?|json|gql|ya?ml|md|sh|rs|proto|toml|css\.ts|wasm))\b/gi;
+	for (const match of prompt.matchAll(extensionPattern)) {
+		paths.add(match[1]);
+	}
+
+	// Match paths starting with common directories
+	const dirPattern =
+		/(?:^|\s|["'`])((?:src|app|components|worker|workers|proto|hooks|utils|services|styles|locales|tests|\.claude|\.github)\/[\w\-./]+)/gi;
+	for (const match of prompt.matchAll(dirPattern)) {
+		paths.add(match[1]);
+	}
+
+	// Match quoted paths
+	const quotedPattern = /["'`]([\w\-./]+\/[\w\-./]+)["'`]/g;
+	for (const match of prompt.matchAll(quotedPattern)) {
+		paths.add(match[1]);
+	}
+
+	return Array.from(paths);
+}
+
+/**
+ * Check if a pattern matches the text
+ * @param {string} text - Text to search in
+ * @param {string} pattern - Regex pattern
+ * @param {string} flags - Regex flags
+ * @returns {boolean}
+ */
+function matchesPattern(text, pattern, flags = "i") {
+	try {
+		const regex = new RegExp(pattern, flags);
+		return regex.test(text);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if a glob pattern matches a file path
+ * @param {string} filePath - File path to check
+ * @param {string} globPattern - Glob pattern (simplified)
+ * @returns {boolean}
+ */
+function matchesGlob(filePath, globPattern) {
+	const regexPattern = globPattern
+		.replace(/\./g, "\\.")
+		.replace(/\*\*\//g, "<<<DOUBLESTARSLASH>>>")
+		.replace(/\*\*/g, "<<<DOUBLESTAR>>>")
+		.replace(/\*/g, "[^/]*")
+		.replace(/<<<DOUBLESTARSLASH>>>/g, "(.*\\/)?")
+		.replace(/<<<DOUBLESTAR>>>/g, ".*")
+		.replace(/\?/g, ".");
+
+	try {
+		const regex = new RegExp(`^${regexPattern}$`, "i");
+		return regex.test(filePath);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Check if file path matches any directory mapping
+ * @param {string} filePath - File path to check
+ * @param {Object} mappings - Directory to skill mappings
+ * @returns {string|null} Matched skill name or null
+ */
+function matchDirectoryMapping(filePath, mappings) {
+	for (const [dir, skillName] of Object.entries(mappings)) {
+		if (filePath === dir || filePath.startsWith(`${dir}/`)) {
+			return skillName;
+		}
+	}
+	return null;
+}
+
+/**
+ * Evaluate a single skill against the prompt and context
+ */
+function evaluateSkill(
+	skillName,
+	skill,
+	prompt,
+	promptLower,
+	filePaths,
+	rules,
+) {
+	const { triggers = {}, excludePatterns = [], priority = 5 } = skill;
+	const scoring = rules.scoring;
+
+	let score = 0;
+	const reasons = [];
+
+	// Check exclude patterns first
+	for (const excludePattern of excludePatterns) {
+		if (matchesPattern(promptLower, excludePattern)) {
+			return null;
+		}
+	}
+
+	// 1. Check keywords
+	if (triggers.keywords) {
+		for (const keyword of triggers.keywords) {
+			if (promptLower.includes(keyword.toLowerCase())) {
+				score += scoring.keyword;
+				reasons.push(`keyword "${keyword}"`);
+			}
+		}
+	}
+
+	// 2. Check keyword patterns (regex)
+	if (triggers.keywordPatterns) {
+		for (const pattern of triggers.keywordPatterns) {
+			if (matchesPattern(promptLower, pattern)) {
+				score += scoring.keywordPattern;
+				reasons.push(`pattern /${pattern}/`);
+			}
+		}
+	}
+
+	// 3. Check intent patterns
+	if (triggers.intentPatterns) {
+		for (const pattern of triggers.intentPatterns) {
+			if (matchesPattern(promptLower, pattern)) {
+				score += scoring.intentPattern;
+				reasons.push(`intent detected`);
+				break;
+			}
+		}
+	}
+
+	// 4. Check context patterns
+	if (triggers.contextPatterns) {
+		for (const pattern of triggers.contextPatterns) {
+			if (promptLower.includes(pattern.toLowerCase())) {
+				score += scoring.contextPattern;
+				reasons.push(`context "${pattern}"`);
+			}
+		}
+	}
+
+	// 5. Check file paths against path patterns
+	if (triggers.pathPatterns && filePaths.length > 0) {
+		for (const filePath of filePaths) {
+			for (const pattern of triggers.pathPatterns) {
+				if (matchesGlob(filePath, pattern)) {
+					score += scoring.pathPattern;
+					reasons.push(`path "${filePath}"`);
+					break;
+				}
+			}
+		}
+	}
+
+	// 6. Check directory mappings
+	if (rules.directoryMappings && filePaths.length > 0) {
+		for (const filePath of filePaths) {
+			const mappedSkill = matchDirectoryMapping(
+				filePath,
+				rules.directoryMappings,
+			);
+			if (mappedSkill === skillName) {
+				score += scoring.directoryMatch;
+				reasons.push(`directory mapping`);
+				break;
+			}
+		}
+	}
+
+	// 7. Check content patterns in prompt (for code snippets)
+	if (triggers.contentPatterns) {
+		for (const pattern of triggers.contentPatterns) {
+			if (matchesPattern(prompt, pattern)) {
+				score += scoring.contentPattern;
+				reasons.push(`code pattern detected`);
+				break;
+			}
+		}
+	}
+
+	if (score > 0) {
+		return { name: skillName, score, reasons: [...new Set(reasons)], priority };
+	}
+
+	return null;
+}
+
+/**
+ * Get related skills that should also be suggested
+ */
+function getRelatedSkills(matches, skills) {
+	const matchedNames = new Set(matches.map((m) => m.name));
+	const related = new Set();
+
+	for (const match of matches) {
+		const skill = skills[match.name];
+		if (skill?.relatedSkills) {
+			for (const relatedName of skill.relatedSkills) {
+				if (!matchedNames.has(relatedName)) {
+					related.add(relatedName);
+				}
+			}
+		}
+	}
+
+	return Array.from(related);
+}
+
+/**
+ * Format confidence level based on score
+ */
+function formatConfidence(score, minScore) {
+	if (score >= minScore * 3) return "HIGH";
+	if (score >= minScore * 2) return "MEDIUM";
+	return "LOW";
+}
+
+/**
+ * Main evaluation function
+ */
+function evaluate(prompt) {
+	const rules = loadRules();
+	const { config, skills } = rules;
+
+	const promptLower = prompt.toLowerCase();
+	const filePaths = extractFilePaths(prompt);
+
+	const matches = [];
+	for (const [name, skill] of Object.entries(skills)) {
+		const match = evaluateSkill(
+			name,
+			skill,
+			prompt,
+			promptLower,
+			filePaths,
+			rules,
+		);
+		if (match && match.score >= config.minConfidenceScore) {
+			matches.push(match);
+		}
+	}
+
+	if (matches.length === 0) {
+		return "";
+	}
+
+	matches.sort((a, b) => {
+		if (b.score !== a.score) return b.score - a.score;
+		return b.priority - a.priority;
+	});
+
+	const topMatches = matches.slice(0, config.maxSkillsToShow);
+	const relatedSkills = getRelatedSkills(topMatches, skills);
+
+	let output = "<user-prompt-submit-hook>\n";
+	output += "SKILL ACTIVATION REQUIRED\n\n";
+
+	if (filePaths.length > 0) {
+		output += `Detected file paths: ${filePaths.join(", ")}\n\n`;
+	}
+
+	output += "Matched skills (ranked by relevance):\n";
+
+	for (let i = 0; i < topMatches.length; i++) {
+		const match = topMatches[i];
+		const confidence = formatConfidence(match.score, config.minConfidenceScore);
+		output += `${i + 1}. ${match.name} (${confidence} confidence)\n`;
+		if (config.showMatchReasons && match.reasons.length > 0) {
+			output += `   Matched: ${match.reasons.slice(0, 3).join(", ")}\n`;
+		}
+	}
+
+	if (relatedSkills.length > 0) {
+		output += `\nRelated skills to consider: ${relatedSkills.join(", ")}\n`;
+	}
+
+	output += "\nBefore implementing, you MUST:\n";
+	output += "1. EVALUATE: State YES/NO for each skill with brief reasoning\n";
+	output += "2. ACTIVATE: Invoke the Skill tool for each YES skill\n";
+	output += "3. IMPLEMENT: Only proceed after skill activation\n";
+	output += "\nExample evaluation:\n";
+	output += `- ${topMatches[0].name}: YES - [your reasoning]\n`;
+	if (topMatches.length > 1) {
+		output += `- ${topMatches[1].name}: NO - [your reasoning]\n`;
+	}
+	output += "\nDO NOT skip this step. Invoke relevant skills NOW.\n";
+	output += "</user-prompt-submit-hook>";
+
+	return output;
+}
+
+// Main execution
+function main() {
+	let input = "";
+
+	process.stdin.setEncoding("utf8");
+
+	process.stdin.on("data", (chunk) => {
+		input += chunk;
+	});
+
+	process.stdin.on("end", () => {
+		let prompt = "";
+
+		try {
+			const data = JSON.parse(input);
+			prompt = data.prompt || "";
+		} catch {
+			prompt = input;
+		}
+
+		if (!prompt.trim()) {
+			process.exit(0);
+		}
+
+		try {
+			const output = evaluate(prompt);
+			if (output) {
+				console.log(output);
+			}
+		} catch (error) {
+			console.error(`Skill evaluation failed: ${error.message}`);
+		}
+
+		process.exit(0);
+	});
+}
+
+main();