@macpaw/cctk 1.0.0-beta.1

package/templates/claude/commands/skill/optimize.md

@@ -0,0 +1,34 @@
+---
+description: Optimize an existing agent skill
+argument-hint: [skill-name] [prompt]
+---
+
+Think harder.
+Use `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+
+## Arguments
+SKILL: $1 (default: `*`)
+PROMPT: $2 (default: empty)
+
+## Your mission
+Propose a plan to optimize an existing skill in `.claude/skills/${SKILL}` directory. 
+When you finish, ask user to review your plan:
+- If the user approve: Write down a plan follow "Output Requirements", then ask user if they want to start implementing.
+- If the user reject: Revise the plan or ask more questions to clarify more about the user's request (ask one question at the time), then repeat the review process.
+
+## Additional instructions
+<additional-instructions>$PROMPT</additional-instructions>
+
+## Output Requirements
+An output implementation plan must also follow the progressive disclosure structure:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- `SKILL.md` is always short and concise, straight to the point, treat it as a quick reference guide.
+- Create a directory using naming pattern from `## Naming` section.
+- Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
+- For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
+
+**IMPORTANT:**
+- Skills are not documentation, they are practical instructions for Claude Code to use the tools, packages, plugins or APIs to achieve the tasks.
+- Each skill teaches Claude how to perform a specific development task, not what a tool does.
+- Claude Code can activate multiple skills automatically to achieve the user's request.

package/templates/claude/commands/skill/plan.md

@@ -0,0 +1,45 @@
+---
+description: Plan to create a new agent skill
+argument-hint: [skill-name] [prompt]
+---
+
+Think harder.
+First: Activate `skill-creator` and `claude-code` skills.
+Use `docs-seeker` skills to search for documentation if needed.
+Employ `sequential-thinking` or `problem-solving` skills for complex problem-solving that requires structured analysis
+Finally, when creating a plan, activate `planning` skill.
+
+## Arguments
+SKILL: $1 (default: `*`)
+PROMPT: $2 (default: empty)
+
+## Your mission
+Propose a plan to create a new skill in `.claude/skills/${SKILL}` directory. 
+When you finish, ask user to review your plan:
+- If the user approve: Write down a plan follow "Output Requirements", then ask user if they want to start implementing.
+- If the user reject: Revise the plan or ask more questions to clarify more about the user's request (ask one question at the time), then repeat the review process.
+
+## Additional instructions
+<additional-instructions>$PROMPT</additional-instructions>
+
+## Your Approach
+1. **Question Everything**: Ask probing questions to fully understand the user's request, constraints, and true objectives. Don't assume - clarify until you're 100% certain.
+2. **Brutal Honesty**: Provide frank, unfiltered feedback about ideas. If something is unrealistic, over-engineered, or likely to cause problems, say so directly. Your job is to prevent costly mistakes.
+3. **Explore Alternatives**: Always consider multiple approaches. Present 2-3 viable solutions with clear pros/cons, explaining why one might be superior.
+4. **Challenge Assumptions**: Question the user's initial approach. Often the best solution is different from what was originally envisioned.
+5. **Consider All Stakeholders**: Evaluate impact on end users, developers, operations team, and business objectives.
+
+## Output Requirements
+An output implementation plan must also follow the progressive disclosure structure:
+- Always keep in mind that `SKILL.md` and reference files should be token consumption efficient, so that **progressive disclosure** can be leveraged at best.
+- `SKILL.md` is always short and concise, straight to the point, treat it as a quick reference guide.
+- Create a directory using naming pattern from `## Naming` section.
+- Save the overview access point at `plan.md`, keep it generic, under 80 lines, and list each phase with status/progress and links.
+- For each phase, add `phase-XX-phase-name.md` files containing sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
+
+**IMPORTANT:**
+- Analyze the given task and use `AskUserQuestion` tool to ask for more details if needed.
+- Ensure token consumption efficiency while maintaining high quality.
+- Skills are not documentation, they are practical instructions for Claude Code to use the tools, packages, plugins or APIs to achieve the tasks.
+- Each skill teaches Claude how to perform a specific development task, not what a tool does.
+- Claude Code can activate multiple skills automatically to achieve the user's request.

package/templates/claude/commands/test/ui.md

@@ -0,0 +1,91 @@
+---
+description: ⚡⚡ Run UI tests on a website & generate a detailed report.
+argument-hint: [url] [options]
+---
+
+Activate the chrome-devtools skill.
+
+## Purpose
+Run comprehensive UI tests on a website and generate a detailed report.
+
+## Arguments
+- $1: URL - The URL of the website to test
+- $2: OPTIONS - Optional test configuration (e.g., --headless, --mobile, --auth)
+
+## Testing Protected Routes (Authentication)
+
+For testing protected routes that require authentication, follow this workflow:
+
+### Step 1: User Manual Login
+Instruct the user to:
+1. Open the target site in their browser
+2. Log in manually with their credentials
+3. Open browser DevTools (F12) → Application tab → Cookies/Storage
+
+### Step 2: Extract Auth Credentials
+Ask the user to provide one of:
+- **Cookies**: Copy cookie values (name, value, domain)
+- **Access Token**: Copy JWT/Bearer token from localStorage or cookies
+- **Session Storage**: Copy relevant session keys
+
+### Step 3: Inject Authentication
+Use the `inject-auth.js` script to inject credentials before testing:
+
+```bash
+cd $SKILL_DIR  # .claude/skills/chrome-devtools/scripts
+
+# Option A: Inject cookies
+node inject-auth.js --url https://example.com --cookies '[{"name":"session","value":"abc123","domain":".example.com"}]'
+
+# Option B: Inject Bearer token
+node inject-auth.js --url https://example.com --token "Bearer eyJhbGciOi..." --header Authorization --token-key access_token
+
+# Option C: Inject localStorage
+node inject-auth.js --url https://example.com --local-storage '{"auth_token":"xyz","user_id":"123"}'
+
+# Combined (cookies + localStorage)
+node inject-auth.js --url https://example.com --cookies '[{"name":"session","value":"abc"}]' --local-storage '{"user":"data"}'
+```
+
+### Step 4: Run Tests
+After auth injection, the browser session persists. Run tests normally:
+
+```bash
+# Navigate and screenshot protected pages
+node navigate.js --url https://example.com/dashboard
+node screenshot.js --url https://example.com/profile --output profile.png
+
+# The auth session persists until --close true is used
+node screenshot.js --url https://example.com/settings --output settings.png --close true
+```
+
+### Auth Script Options
+- `--cookies '<json>'` - Inject cookies (JSON array)
+- `--token '<token>'` - Inject Bearer token
+- `--token-key '<key>'` - localStorage key for token (default: access_token)
+- `--header '<name>'` - Set HTTP header with token (e.g., Authorization)
+- `--local-storage '<json>'` - Inject localStorage items
+- `--session-storage '<json>'` - Inject sessionStorage items
+- `--reload true` - Reload page after injection
+- `--clear true` - Clear saved auth session
+
+## Workflow
+- Use `planning` skill to organize the test plan & report in the current project directory.
+- All the screenshots should be saved in the same report directory.
+- Browse $URL with the specified $OPTIONS, discover all pages, components, and endpoints.
+- Create a test plan based on the discovered structure
+- Use multiple `tester` subagents or tool calls in parallel to test all pages, forms, navigation, user flows, accessibility, functionalities, usability, responsive layouts, cross-browser compatibility, performance, security, seo, etc.
+- Generate a comprehensive report in Markdown format, embedding all screenshots directly in the report.
+- Finally respond to the user with a concise summary of findings and recommendations.
+- Use `AskUserQuestion` tool to ask if user wants to preview the report with `/preview` slash command.
+
+## Output Requirements
+How to write reports:
+- Format: Use clear, structured Markdown with headers, lists, and code blocks where appropriate
+- Include the test results summary, key findings, and screenshot references
+- **IMPORTANT:** Ensure token efficiency while maintaining high quality.
+- **IMPORTANT:** Sacrifice grammar for the sake of concision when writing reports.
+- **IMPORTANT:** In reports, list any unresolved questions at the end, if any.
+
+**IMPORTANT**: **Do not** start implementing the fixes.
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

package/templates/claude/commands/test.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Run tests locally and analyze the summary report.
+---
+
+Use the `tester` subagent to run tests locally and analyze the summary report.
+
+**IMPORTANT**: **Do not** start implementing.
+**IMPORTANT:** Analyze the skills catalog and activate the skills that are needed for the task during the process.

package/templates/claude/commands/use-mcp.md

@@ -0,0 +1,34 @@
+---
+description: Utilize tools of Model Context Protocol (MCP) servers
+argument-hint: [task]
+---
+Execute MCP operations via **Gemini CLI** to preserve context budget.
+
+## Execution Steps
+
+1. **Execute task via Gemini CLI** (using stdin pipe for MCP support):
+   ```bash
+   # IMPORTANT: Use stdin piping, NOT -p flag (deprecated, skips MCP init)
+   echo "$ARGUMENTS. Return JSON only per GEMINI.md instructions." | gemini -y -m gemini-2.5-flash
+   ```
+
+2. **Fallback to mcp-manager subagent** (if Gemini CLI unavailable):
+   - Use `mcp-manager` subagent to discover and execute tools
+   - If the subagent got issues with the scripts of `mcp-management` skill, use `mcp-builder` skill to fix them
+   - **DO NOT** create ANY new scripts
+   - The subagent can only use MCP tools if any to achieve this task
+   - If the subagent can't find any suitable tools, just report it back to the main agent to move on to the next step
+
+## Important Notes
+
+- **MUST use stdin piping** - the deprecated `-p` flag skips MCP initialization
+- Use `-y` flag to auto-approve tool execution
+- **GEMINI.md auto-loaded**: Gemini CLI automatically loads `GEMINI.md` from project root, enforcing JSON-only response format
+- **Parseable output**: Responses are structured JSON: `{"server":"name","tool":"name","success":true,"result":<data>,"error":null}`
+
+## Anti-Pattern (DO NOT USE)
+
+```bash
+# BROKEN - deprecated -p flag skips MCP server connections!
+gemini -y -m gemini-2.5-flash -p "..."
+```

package/templates/claude/commands/watzup.md

@@ -0,0 +1,8 @@
+---
+description: ⚡ Review recent changes and wrap up the work
+---
+Review my current branch and the most recent commits. 
+Provide a detailed summary of all changes, including what was modified, added, or removed. 
+Analyze the overall impact and quality of the changes.
+
+**IMPORTANT**: **Do not** start implementing.

package/templates/claude/commands/worktree.md

@@ -0,0 +1,126 @@
+---
+description: Create isolated git worktree for parallel development
+argument-hint: [feature-description] OR [project] [feature] (monorepo)
+---
+
+Create an isolated git worktree for parallel feature development.
+
+## Workflow
+
+### Step 1: Get Repository Info
+
+```bash
+node .claude/scripts/worktree.cjs info --json
+```
+
+**Response fields:**
+- `repoType`: "monorepo" or "standalone"
+- `baseBranch`: detected base branch
+- `projects`: array of {name, path} for monorepo
+- `envFiles`: array of .env* files found
+- `dirtyState`: boolean
+
+### Step 2: Gather Info via AskUserQuestion
+
+**Detect branch prefix from user's description:**
+- Keywords "fix", "bug", "error", "issue" → prefix = `fix`
+- Keywords "refactor", "restructure", "rewrite" → prefix = `refactor`
+- Keywords "docs", "documentation", "readme" → prefix = `docs`
+- Keywords "test", "spec", "coverage" → prefix = `test`
+- Keywords "chore", "cleanup", "deps" → prefix = `chore`
+- Keywords "perf", "performance", "optimize" → prefix = `perf`
+- Everything else → prefix = `feat`
+
+**For MONOREPO:** Use AskUserQuestion if project not specified:
+```javascript
+// If user said "/worktree add auth" but multiple projects exist
+AskUserQuestion({
+  questions: [{
+    header: "Project",
+    question: "Which project should the worktree be created for?",
+    options: projects.map(p => ({ label: p.name, description: p.path })),
+    multiSelect: false
+  }]
+})
+```
+
+**For env files:** Always ask which to copy:
+```javascript
+AskUserQuestion({
+  questions: [{
+    header: "Env files",
+    question: "Which environment files should be copied to the worktree?",
+    options: envFiles.map(f => ({ label: f, description: "Copy to worktree" })),
+    multiSelect: true
+  }]
+})
+```
+
+### Step 3: Convert Description to Slug
+
+- "add authentication system" → `add-auth`
+- "fix login bug" → `login-bug`
+- Remove filler words, kebab-case, max 50 chars
+
+### Step 4: Execute Command
+
+**Monorepo:**
+```bash
+node .claude/scripts/worktree.cjs create "<PROJECT>" "<SLUG>" --prefix <TYPE> --env "<FILES>"
+```
+
+**Standalone:**
+```bash
+node .claude/scripts/worktree.cjs create "<SLUG>" --prefix <TYPE> --env "<FILES>"
+```
+
+**Options:**
+- `--prefix` - Branch type: feat|fix|refactor|docs|test|chore|perf
+- `--env` - Comma-separated .env files to copy
+- `--json` - Output JSON for parsing
+- `--dry-run` - Preview without executing
+
+## Commands
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `create` | `create [project] <feature>` | Create new worktree |
+| `remove` | `remove <name-or-path>` | Remove worktree and branch |
+| `info` | `info` | Get repo info |
+| `list` | `list` | List existing worktrees |
+
+## Error Codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `MISSING_ARGS` | Missing project/feature for monorepo | Ask for both |
+| `MISSING_FEATURE` | No feature name (standalone) | Ask for feature |
+| `PROJECT_NOT_FOUND` | Project not in .gitmodules | Show available projects |
+| `MULTIPLE_PROJECTS_MATCH` | Ambiguous project name | Use AskUserQuestion |
+| `MULTIPLE_WORKTREES_MATCH` | Ambiguous worktree for remove | Use AskUserQuestion |
+| `BRANCH_CHECKED_OUT` | Branch in use elsewhere | Suggest different name |
+| `WORKTREE_EXISTS` | Path already exists | Suggest use or remove |
+| `WORKTREE_CREATE_FAILED` | Git command failed | Show git error |
+| `WORKTREE_REMOVE_FAILED` | Cannot remove worktree | Check uncommitted changes |
+
+## Example Session
+
+```
+User: /worktree fix the login validation bug
+
+Claude: [Runs: node .claude/scripts/worktree.cjs info --json]
+        [Detects: standalone repo, envFiles: [".env.example"]]
+        [Detects prefix from "fix" keyword: fix]
+        [Converts slug: "login-validation-bug"]
+
+Claude: [Uses AskUserQuestion for env files]
+        "Which environment files should be copied?"
+        Options: .env.example
+
+User: .env.example
+
+Claude: [Runs: node .claude/scripts/worktree.cjs create "login-validation-bug" --prefix fix --env ".env.example"]
+
+Output: Worktree created at ../worktrees/myrepo-login-validation-bug
+        Branch: fix/login-validation-bug
+```

package/templates/claude/hooks/dev-rules-reminder.cjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * Development Rules Reminder - UserPromptSubmit Hook (Optimized)
+ *
+ * Injects context: session info, rules, modularization reminders, and Plan Context.
+ * Static env info (Node, Python, OS) now comes from SessionStart env vars.
+ *
+ * Exit Codes:
+ *   0 - Success (non-blocking, allows continuation)
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execSync } = require('child_process');
+const {
+  loadConfig,
+  resolvePlanPath,
+  getReportsPath,
+  resolveNamingPattern,
+  normalizePath
+} = require('./lib/cctk-config-utils.cjs');
+
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+function execSafe(cmd) {
+  try {
+    return execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+  } catch (e) {
+    return null;
+  }
+}
+
+function resolveWorkflowPath(filename) {
+  const localPath = path.join(process.cwd(), '.claude', 'workflows', filename);
+  const globalPath = path.join(os.homedir(), '.claude', 'workflows', filename);
+  if (fs.existsSync(localPath)) return `.claude/workflows/${filename}`;
+  if (fs.existsSync(globalPath)) return `~/.claude/workflows/${filename}`;
+  return null;
+}
+
+function resolveScriptPath(filename) {
+  const localPath = path.join(process.cwd(), '.claude', 'scripts', filename);
+  const globalPath = path.join(os.homedir(), '.claude', 'scripts', filename);
+  if (fs.existsSync(localPath)) return `.claude/scripts/${filename}`;
+  if (fs.existsSync(globalPath)) return `~/.claude/scripts/${filename}`;
+  return null;
+}
+
+function resolveSkillsVenv() {
+  const localVenv = path.join(process.cwd(), '.claude', 'skills', '.venv', 'bin', 'python3');
+  const globalVenv = path.join(os.homedir(), '.claude', 'skills', '.venv', 'bin', 'python3');
+
+  if (fs.existsSync(localVenv)) {
+    return '.claude/skills/.venv/bin/python3';
+  }
+  if (fs.existsSync(globalVenv)) {
+    return '~/.claude/skills/.venv/bin/python3';
+  }
+  return null;
+}
+
+function buildPlanContext(sessionId, config) {
+  const { plan, paths } = config;
+  const gitBranch = execSafe('git branch --show-current');
+  const resolved = resolvePlanPath(sessionId, config);
+  const reportsPath = getReportsPath(resolved.path, resolved.resolvedBy, plan, paths);
+
+  // Compute naming pattern directly for reliable injection
+  const namePattern = resolveNamingPattern(plan, gitBranch);
+
+  const planLine = resolved.resolvedBy === 'session'
+    ? `- Plan: ${resolved.path}`
+    : resolved.resolvedBy === 'branch'
+      ? `- Plan: none | Suggested: ${resolved.path}`
+      : `- Plan: none`;
+
+  // Validation config (injected so LLM can reference it)
+  const validation = plan.validation || {};
+  const validationMode = validation.mode || 'prompt';
+  const validationMin = validation.minQuestions || 3;
+  const validationMax = validation.maxQuestions || 8;
+
+  return { reportsPath, gitBranch, planLine, namePattern, validationMode, validationMin, validationMax };
+}
+
+function wasRecentlyInjected(transcriptPath) {
+  try {
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) return false;
+    const transcript = fs.readFileSync(transcriptPath, 'utf-8');
+    // Check last 150 lines (hook output is ~30 lines, so this covers ~5 user prompts)
+    return transcript.split('\n').slice(-150).some(line => line.includes('[IMPORTANT] Consider Modularization'));
+  } catch (e) {
+    return false;
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// REMINDER TEMPLATE (all output in one place for visibility)
+// ═══════════════════════════════════════════════════════════════════════════
+
+function buildReminder({ thinkingLanguage, responseLanguage, devRulesPath, catalogScript, skillsVenv, reportsPath, plansPath, docsPath, docsMaxLoc, planLine, gitBranch, namePattern, validationMode, validationMin, validationMax }) {
+  // Build language instructions based on config
+  // Auto-default thinkingLanguage to 'en' when only responseLanguage is set
+  const effectiveThinking = thinkingLanguage || (responseLanguage ? 'en' : null);
+  const hasThinking = effectiveThinking && effectiveThinking !== responseLanguage;
+  const hasResponse = responseLanguage;
+  const languageLines = [];
+
+  if (hasThinking || hasResponse) {
+    languageLines.push(`## Language`);
+    if (hasThinking) {
+      languageLines.push(`- Thinking: Use ${effectiveThinking} for reasoning (logic, precision).`);
+    }
+    if (hasResponse) {
+      languageLines.push(`- Response: Respond in ${responseLanguage} (natural, fluent).`);
+    }
+    languageLines.push(``);
+  }
+
+  const memUsed = Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
+  const memTotal = Math.round(os.totalmem() / 1024 / 1024);
+  const memPercent = Math.round((memUsed / memTotal) * 100);
+
+  const cpuUsage = Math.round((process.cpuUsage().user / 1000000) * 100);
+  const cpuSystem = Math.round((process.cpuUsage().system / 1000000) * 100);
+
+  return [
+    // ─────────────────────────────────────────────────────────────────────────
+    // LANGUAGE (thinking + response, if configured)
+    // ─────────────────────────────────────────────────────────────────────────
+    ...languageLines,
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // SESSION CONTEXT
+    // ─────────────────────────────────────────────────────────────────────────
+    `## Session`,
+    `- DateTime: ${new Date().toLocaleString()}`,
+    `- CWD: ${process.cwd()}`,
+    `- Timezone: ${Intl.DateTimeFormat().resolvedOptions().timeZone}`,
+    `- Working directory: ${process.cwd()}`,
+    `- OS: ${process.platform}`,
+    `- User: ${process.env.USERNAME}`,
+    `- Locale: ${process.env.LANG}`,
+    `- Memory usage: ${memUsed}MB/${memTotal}MB (${memPercent}%)`,
+    `- CPU usage: ${cpuUsage}% user / ${cpuSystem}% system`,
+    `- Spawning multiple subagents can cause performance issues, spawn and delegate tasks intelligently based on the available system resources.`,
+    `- Remember that each subagent only has 200K tokens in context window, spawn and delegate tasks intelligently to make sure their context windows don't get bloated.`,
+    `- IMPORTANT: Include these environment information when prompting subagents to perform tasks.`,
+    ``,
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // RULES
+    // ─────────────────────────────────────────────────────────────────────────
+    `## Rules`,
+    ...(devRulesPath ? [`- Read and follow development rules: "${devRulesPath}"`] : []),
+    `- Markdown files are organized in: Plans → "plans/" directory, Docs → "docs/" directory`,
+    `- **IMPORTANT:** DO NOT create markdown files out of "plans/" or "docs/" directories UNLESS the user explicitly requests it.`,
+    ...(catalogScript ? [
+      `- Activate skills: Run \`node ${catalogScript} --skills\` to generate a skills catalog and analyze it, then activate the relevant skills that are needed for the task during the process.`,
+      `- Execute commands: Run \`node ${catalogScript} --commands\` to generate a commands catalog and analyze it, then execute the relevant SlashCommands that are needed for the task during the process.`
+    ] : []),
+    ...(skillsVenv ? [`- Python scripts in .claude/skills/: Use \`${skillsVenv}\``] : []),
+    `- When skills' scripts are failed to execute, always fix them and run again, repeat until success.`,
+    `- Follow **YAGNI (You Aren't Gonna Need It) - KISS (Keep It Simple, Stupid) - DRY (Don't Repeat Yourself)** principles`,
+    `- Sacrifice grammar for the sake of concision when writing reports.`,
+    `- In reports, list any unresolved questions at the end, if any.`,
+    `- IMPORTANT: Ensure token consumption efficiency while maintaining high quality.`,
+    ``,
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // MODULARIZATION
+    // ─────────────────────────────────────────────────────────────────────────
+    `## **[IMPORTANT] Consider Modularization:**`,
+    `- Check existing modules before creating new`,
+    `- Analyze logical separation boundaries (functions, classes, concerns)`,
+    `- Use kebab-case naming with descriptive names, it's fine if the file name is long because this ensures file names are self-documenting for LLM tools (Grep, Glob, Search)`,
+    `- Write descriptive code comments`,
+    `- After modularization, continue with main task`,
+    `- When not to modularize: Markdown files, plain text files, bash scripts, configuration files, environment variables files, etc.`,
+    ``,
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // PATHS
+    // ─────────────────────────────────────────────────────────────────────────
+    `## Paths`,
+    `Reports: ${reportsPath} | Plans: ${plansPath}/ | Docs: ${docsPath}/ | docs.maxLoc: ${docsMaxLoc}`,
+    ``,
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // PLAN CONTEXT
+    // ─────────────────────────────────────────────────────────────────────────
+    `## Plan Context`,
+    planLine,
+    `- Reports: ${reportsPath}`,
+    ...(gitBranch ? [`- Branch: ${gitBranch}`] : []),
+    `- Validation: mode=${validationMode}, questions=${validationMin}-${validationMax}`,
+    ``,
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // NAMING (computed pattern for consistent file naming)
+    // ─────────────────────────────────────────────────────────────────────────
+    `## Naming`,
+    `- Report: \`${reportsPath}{type}-${namePattern}.md\``,
+    `- Plan dir: \`${plansPath}/${namePattern}/\``,
+    `- Replace \`{type}\` with: agent name, report type, or context`,
+    `- Replace \`{slug}\` in pattern with: descriptive-kebab-slug`
+  ];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// MAIN EXECUTION
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function main() {
+  try {
+    const stdin = fs.readFileSync(0, 'utf-8').trim();
+    if (!stdin) process.exit(0);
+
+    const payload = JSON.parse(stdin);
+    if (wasRecentlyInjected(payload.transcript_path)) process.exit(0);
+
+    const sessionId = process.env.CCTK_SESSION_ID || null;
+    const config = loadConfig({ includeProject: false, includeAssertions: false });
+    const devRulesPath = resolveWorkflowPath('development-rules.md');
+    const catalogScript = resolveScriptPath('generate-catalogs.cjs');
+    const skillsVenv = resolveSkillsVenv();
+    const { reportsPath, gitBranch, planLine, namePattern, validationMode, validationMin, validationMax } = buildPlanContext(sessionId, config);
+
+    const output = buildReminder({
+      thinkingLanguage: config.locale?.thinkingLanguage,
+      responseLanguage: config.locale?.responseLanguage,
+      devRulesPath,
+      catalogScript,
+      skillsVenv,
+      reportsPath,
+      plansPath: normalizePath(config.paths?.plans) || 'plans',
+      docsPath: normalizePath(config.paths?.docs) || 'docs',
+      docsMaxLoc: Math.max(1, parseInt(config.docs?.maxLoc, 10) || 800),
+      planLine,
+      gitBranch,
+      namePattern,
+      validationMode,
+      validationMin,
+      validationMax
+    });
+
+    console.log(output.join('\n'));
+    process.exit(0);
+  } catch (error) {
+    console.error(`Dev rules hook error: ${error.message}`);
+    process.exit(0);
+  }
+}
+
+main();

package/templates/claude/hooks/docs/README.md

@@ -0,0 +1,42 @@
+# Claude Code Hooks
+
+This directory contains hooks for Claude Code sessions.
+
+## Hooks Overview
+
+| Hook | Location | Description |
+|------|----------|-------------|
+| **Scout Block** | `scout-block.cjs` | Blocks heavy directories (node_modules, .git, etc.) |
+| **Privacy Block** | `privacy-block.cjs` | Prevents access to sensitive files |
+| **Modularization** | `modularization-hook.js` | Suggests code modularization for large files |
+| **Session Init** | `session-init.cjs` | Session startup initialization |
+| **Dev Rules** | `dev-rules-reminder.cjs` | Development rules injection |
+
+
+## Scout Block Hook
+
+Cross-platform hook blocking heavy directories to improve Claude performance.
+
+**Blocked Patterns** (configured in `.claude/.cctkignore`):
+- `node_modules`, `__pycache__`, `.git`, `dist`, `build`
+
+**Testing:**
+```bash
+echo '{"tool_input":{"command":"ls node_modules"}}' | node .claude/hooks/scout-block.cjs
+```
+
+## Security
+
+1. **Never commit tokens** - Add `.env` to `.gitignore`
+2. **Use environment variables** - Never hardcode credentials
+3. **Rotate tokens regularly** - Regenerate periodically
+
+## Troubleshooting
+
+**Provider throttled:**
+- Wait 5 minutes or delete `/tmp/cctk-noti-throttle.json`
+
+**Hooks not triggering:**
+- Verify hooks are added to `.claude/settings.json`
+- Check Claude Code is using correct settings file
+