sinapse-ai 1.0.0

package/squad-claude/knowledge-base/claude-code-hooks-reference.md

@@ -0,0 +1,415 @@
+# Claude Code Hooks Reference
+
+## Overview
+
+Claude Code hooks are user-defined shell commands that execute at specific points during the Claude Code lifecycle. They enable automation, enforcement, and integration without modifying Claude Code itself. Hooks are configured in `.claude/settings.json` under the `hooks` key.
+
+## Configuration Location
+
+Hooks can be defined at multiple levels:
+- **Project:** `.claude/settings.json` (shared with team, committed to git)
+- **User:** `~/.claude/settings.json` (personal, not committed)
+- **Managed policies:** Enterprise-level (cannot be overridden)
+
+## Hook Configuration Schema
+
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "optional_pattern",
+        "command": "shell_command_to_execute",
+        "timeout": 5000,
+        "on_error": "warn"
+      }
+    ]
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `matcher` | string (regex) | No | Pattern to match against the tool name or event context. If omitted, hook fires for ALL events of this type. |
+| `command` | string | Yes | Shell command to execute. Receives event payload via stdin as JSON. |
+| `timeout` | number (ms) | No | Maximum execution time. Default varies by event type. |
+| `on_error` | string | No | Behavior on command failure: `"warn"` (log and continue), `"error"` (block and report), `"ignore"` (silent). Default: `"warn"`. |
+
+---
+
+## Hook Events Reference
+
+### PreToolUse
+
+**Trigger:** Before any tool is executed.
+**Purpose:** Gate/block tool execution, validate inputs, enforce policies.
+**Timing:** Synchronous — Claude Code waits for the hook to complete before proceeding.
+
+**Payload (stdin JSON):**
+```json
+{
+  "session_id": "uuid",
+  "tool_name": "Bash",
+  "tool_input": {
+    "command": "rm -rf /tmp/test",
+    "description": "Delete test directory"
+  }
+}
+```
+
+**Return behavior:**
+- Exit code 0: Tool execution proceeds
+- Exit code non-0: Tool execution is BLOCKED, error message shown to user
+- Stdout: If non-empty and exit 0, replaces the tool input (advanced usage)
+
+**Use Cases:**
+- Block dangerous commands (`rm -rf`, `git push --force`)
+- Validate file paths before Write/Edit operations
+- Enforce naming conventions on file creation
+- Log all tool invocations for audit trail
+- Rate-limit expensive operations
+
+**Example: Block destructive git commands**
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "command": "python .claude/hooks/block-dangerous-git.py",
+        "timeout": 3000,
+        "on_error": "error"
+      }
+    ]
+  }
+}
+```
+
+### PostToolUse
+
+**Trigger:** After a tool completes execution successfully.
+**Purpose:** React to tool outputs, trigger side effects, chain automations.
+**Timing:** Synchronous — Claude Code waits before presenting the result.
+
+**Payload (stdin JSON):**
+```json
+{
+  "session_id": "uuid",
+  "tool_name": "Write",
+  "tool_input": {
+    "file_path": "/path/to/file.ts",
+    "content": "..."
+  },
+  "tool_output": {
+    "success": true,
+    "file_path": "/path/to/file.ts"
+  }
+}
+```
+
+**Return behavior:**
+- Exit code 0: Normal continuation
+- Exit code non-0: Warning logged (does not undo the tool execution)
+- Stdout: If non-empty, appended to the tool output as additional context
+
+**Use Cases:**
+- Auto-lint after file Write/Edit operations
+- Auto-run tests after code changes
+- Update dependency graphs after package changes
+- Notify external systems of file changes
+- Auto-format code after generation
+
+**Example: Auto-lint on file write**
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "node .claude/hooks/auto-lint.js",
+        "timeout": 10000,
+        "on_error": "warn"
+      }
+    ]
+  }
+}
+```
+
+### Notification
+
+**Trigger:** When Claude Code generates a notification (e.g., task complete, error encountered, waiting for input).
+**Purpose:** Route notifications to external channels, log events, trigger alerts.
+**Timing:** Asynchronous — does not block Claude Code operation.
+
+**Payload (stdin JSON):**
+```json
+{
+  "session_id": "uuid",
+  "type": "notification",
+  "title": "Task Complete",
+  "message": "Successfully refactored auth module",
+  "severity": "info"
+}
+```
+
+**Use Cases:**
+- Send Slack/Discord messages on task completion
+- Email notifications for long-running operations
+- Desktop notifications via OS notification system
+- Log notifications to a monitoring dashboard
+- Trigger CI/CD pipelines on specific events
+
+**Example: Desktop notification**
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "command": "python .claude/hooks/desktop-notify.py",
+        "timeout": 5000,
+        "on_error": "ignore"
+      }
+    ]
+  }
+}
+```
+
+### Stop
+
+**Trigger:** When Claude Code completes a turn (finishes responding).
+**Purpose:** Cleanup, logging, state persistence, post-turn automation.
+**Timing:** Synchronous — runs before control returns to user.
+
+**Payload (stdin JSON):**
+```json
+{
+  "session_id": "uuid",
+  "type": "stop",
+  "reason": "end_of_turn",
+  "stop_reason": "natural",
+  "token_usage": {
+    "input": 5000,
+    "output": 2000
+  }
+}
+```
+
+**Use Cases:**
+- Log token usage for cost tracking
+- Persist session state to disk
+- Run comprehensive tests after a coding session
+- Generate session summary reports
+- Clean up temporary files created during the turn
+
+**Example: Token usage tracker**
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "command": "node .claude/hooks/track-tokens.js",
+        "timeout": 5000,
+        "on_error": "ignore"
+      }
+    ]
+  }
+}
+```
+
+### SubagentStop
+
+**Trigger:** When a subagent (spawned by the main agent) completes its task.
+**Purpose:** Aggregate subagent results, trigger follow-up actions, manage agent lifecycle.
+**Timing:** Synchronous — runs before the main agent processes the subagent's result.
+
+**Payload (stdin JSON):**
+```json
+{
+  "session_id": "uuid",
+  "type": "subagent_stop",
+  "subagent_id": "uuid",
+  "result": "...",
+  "status": "completed"
+}
+```
+
+**Use Cases:**
+- Aggregate results from parallel subagents
+- Trigger next subagent in a chain
+- Log subagent performance metrics
+- Clean up subagent worktrees
+- Validate subagent output before accepting
+
+### PreToolUseOutput
+
+**Trigger:** Before tool output is presented to the model.
+**Purpose:** Filter, transform, or redact tool output before Claude processes it.
+**Timing:** Synchronous.
+
+**Use Cases:**
+- Redact sensitive information from command output
+- Truncate overly large outputs to save context tokens
+- Transform output format for better model comprehension
+- Add annotations or metadata to output
+
+### PostToolUseOutput
+
+**Trigger:** After tool output has been processed by the model.
+**Purpose:** Log final tool results, update external tracking, chain reactions.
+**Timing:** Asynchronous.
+
+**Use Cases:**
+- Log all tool results for compliance
+- Update project dashboards with operation results
+- Trigger external webhook on specific outcomes
+
+---
+
+## Hook Patterns
+
+### Pattern 1: Auto-Lint Pipeline
+
+Chain PostToolUse with a linter to automatically fix code after generation:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); npx eslint --fix \"$FILE\" 2>/dev/null || true'",
+        "timeout": 15000,
+        "on_error": "warn"
+      }
+    ]
+  }
+}
+```
+
+### Pattern 2: Security Gate
+
+Block execution of dangerous commands using PreToolUse:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "command": "bash -c 'INPUT=$(cat); CMD=$(echo $INPUT | jq -r .tool_input.command); echo \"$CMD\" | grep -qE \"rm -rf /|:(){ :|:& };:|dd if=/dev|mkfs|> /dev/sd\" && exit 1 || exit 0'",
+        "timeout": 2000,
+        "on_error": "error"
+      }
+    ]
+  }
+}
+```
+
+### Pattern 3: Notification Router
+
+Route notifications to different channels based on severity:
+
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "command": "python .claude/hooks/route-notification.py",
+        "timeout": 10000,
+        "on_error": "ignore"
+      }
+    ]
+  }
+}
+```
+
+Where `route-notification.py` reads severity from payload and sends to Slack (critical), email (warning), or log file (info).
+
+### Pattern 4: Auto-Test on Change
+
+Run relevant tests after code changes:
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "command": "bash -c 'INPUT=$(cat); FILE=$(echo $INPUT | jq -r .tool_input.file_path); if [[ \"$FILE\" == *.test.* ]]; then npx jest \"$FILE\" --passWithNoTests 2>&1 | tail -5; elif [[ \"$FILE\" == *.ts || \"$FILE\" == *.tsx ]]; then TEST=\"${FILE%.ts*}.test${FILE##*.ts}\"; [ -f \"$TEST\" ] && npx jest \"$TEST\" --passWithNoTests 2>&1 | tail -5; fi'",
+        "timeout": 30000,
+        "on_error": "warn"
+      }
+    ]
+  }
+}
+```
+
+### Pattern 5: Pre-Commit Quality Gate
+
+Run quality checks before any git commit:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "command": "bash -c 'INPUT=$(cat); CMD=$(echo $INPUT | jq -r .tool_input.command); if echo \"$CMD\" | grep -q \"git commit\"; then npm run lint --silent && npm run typecheck --silent || (echo \"Quality checks failed\" && exit 1); fi'",
+        "timeout": 60000,
+        "on_error": "error"
+      }
+    ]
+  }
+}
+```
+
+### Pattern 6: Token Budget Monitor
+
+Track cumulative token usage and warn when approaching limits:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "command": "node .claude/hooks/token-budget.js",
+        "timeout": 3000,
+        "on_error": "ignore"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### Performance
+- PreToolUse hooks MUST be fast (< 500ms) — they block tool execution
+- PostToolUse hooks should complete within 10s — they block result display
+- Notification and Stop hooks can be slower — they run at natural pauses
+- Use `timeout` to prevent hung hooks from blocking the session
+
+### Reliability
+- Always set `on_error` explicitly — don't rely on defaults
+- Use `"error"` only for security-critical PreToolUse gates
+- Use `"warn"` for automation that should not block work
+- Use `"ignore"` for optional enhancements (notifications, logging)
+
+### Security
+- Never pass untrusted data directly to shell commands — always sanitize
+- Use `jq` to extract specific fields rather than eval-ing the entire payload
+- Keep hook scripts in version control for auditability
+- Test hooks in a sandbox before deploying to production
+
+### Ordering
+- Multiple hooks on the same event execute in array order
+- If hook A must run before hook B, place A first in the array
+- Hooks do NOT have explicit dependency declarations — order is implicit
+
+### Debugging
+- Add `set -x` to shell commands temporarily for debug output
+- Check stderr for hook execution errors
+- Use a logging hook on Stop to capture session diagnostics
+- Test hooks independently with `echo '{"tool_name":"Bash"}' | your_hook_command`

package/squad-claude/knowledge-base/context-engineering-guide.md

@@ -0,0 +1,277 @@
+# Context Engineering Guide
+
+## Overview
+
+Context engineering is the practice of designing, optimizing, and maintaining the information that Claude Code receives in its context window. Every token matters — wasted tokens reduce capacity for actual work, while missing tokens cause misunderstandings and errors.
+
+## The Context Budget
+
+Claude Code's context window is shared across multiple sources:
+
+```
+Total Context = System Prompt + CLAUDE.md + Rules + Conversation + Tool Outputs + MCP Tools
+```
+
+| Source | Typical Size | Control Level |
+|--------|-------------|---------------|
+| System Prompt | ~2-4K tokens | None (fixed by Claude Code) |
+| CLAUDE.md (all levels) | 1-10K tokens | Full control |
+| .claude/rules/ (loaded) | 0.5-5K tokens | Full control (conditional loading) |
+| Conversation history | Grows per turn | Partial (prompt design) |
+| Tool outputs | Variable | Partial (output filtering hooks) |
+| MCP tool schemas | ~100-500 per server | Partial (choose which servers) |
+
+**Key insight:** CLAUDE.md and rules are the highest-leverage optimization targets because you have full control over them and they are loaded on every turn.
+
+---
+
+## CLAUDE.md Best Practices
+
+### What to Include (High Value)
+
+1. **Project identity** — One sentence: what this project is and does
+2. **Technology stack** — Framework, language, key libraries (as a table, not paragraphs)
+3. **Directory structure** — Only non-obvious directories and their purposes
+4. **Coding conventions** — Only conventions that differ from standard practices
+5. **Anti-patterns** — What Claude Code should NOT do (high-value, prevents costly mistakes)
+6. **Common commands** — Build, test, lint, deploy commands
+7. **Known gotchas** — Non-obvious project-specific traps
+
+### What to Omit (Low Value)
+
+1. **Generic programming advice** — Claude already knows how to write clean code
+2. **Standard framework conventions** — Claude knows React, Next.js, Express conventions
+3. **Obvious file purposes** — Don't explain that `package.json` manages dependencies
+4. **Long code examples** — Use one-liners or references, not full implementations
+5. **Historical context** — Why decisions were made matters less than what the current state is
+6. **Duplicate information** — If it's in a rule file, don't repeat it in CLAUDE.md
+
+### Structure Template
+
+```markdown
+# {Project Name}
+
+{One sentence description}
+
+## Stack
+| Layer | Technology |
+|-------|-----------|
+| Frontend | React 18 + TypeScript |
+| Backend | Node.js + Express |
+| Database | PostgreSQL via Supabase |
+| Testing | Jest + RTL |
+
+## Structure
+- `src/components/` — React components (PascalCase)
+- `src/api/` — API routes (kebab-case)
+- `src/lib/` — Shared utilities
+
+## Commands
+- `npm run dev` — Start dev server (port 3000)
+- `npm test` — Run tests
+- `npm run lint` — ESLint + Prettier
+
+## Anti-Patterns
+- NEVER use `any` type — always define explicit types
+- NEVER import from `src/` using relative paths — use `@/` alias
+- NEVER commit .env files
+
+## Gotchas
+- Auth middleware must be applied before route handlers
+- Supabase RLS policies apply even in server-side contexts
+```
+
+### CLAUDE.md Hierarchy
+
+Claude Code loads CLAUDE.md files hierarchically:
+
+1. **Root CLAUDE.md** — Always loaded. Contains project-wide instructions.
+2. **Directory CLAUDE.md** — Loaded when files in that directory are being edited. Contains directory-specific instructions.
+
+**Strategy:** Put universal instructions in root, put context-specific instructions in directory-level files or .claude/rules/.
+
+---
+
+## Rules Architecture
+
+### Global Rules (No paths: frontmatter)
+
+Files in `.claude/rules/` without `paths:` frontmatter load on every interaction. Use sparingly — each global rule consumes context on every turn.
+
+**Good candidates for global rules:**
+- Git conventions
+- Code review standards
+- Security policies
+- Agent authority matrix
+
+### Contextual Rules (With paths: frontmatter)
+
+Files with `paths:` frontmatter only load when matching files are being edited. This is the key to context efficiency.
+
+```yaml
+---
+paths:
+  - "src/components/**/*.tsx"
+  - "src/components/**/*.ts"
+---
+
+# React Component Rules
+
+- Use functional components with hooks
+- Export components as named exports
+- Co-locate component tests as ComponentName.test.tsx
+- Use CSS Modules for styling (ComponentName.module.css)
+```
+
+### Rule Organization Strategy
+
+```
+.claude/rules/
+├── git-conventions.md          # Global (no paths:)
+├── security-policies.md        # Global (no paths:)
+├── react-components.md         # paths: src/components/**
+├── api-routes.md               # paths: src/api/**
+├── database-queries.md         # paths: src/db/**, src/lib/db/**
+├── testing-standards.md        # paths: **/*.test.*, **/*.spec.*
+└── ci-cd-workflows.md          # paths: .github/workflows/**
+```
+
+**Token impact:** If a project has 5 contextual rules at ~500 tokens each, only 1-2 load per interaction instead of all 5. That's 1.5-2K tokens saved per turn.
+
+---
+
+## Context Compression Strategies
+
+### Strategy 1: Tables Over Prose
+
+**Before (85 tokens):**
+> When writing API routes, you should always use the Express router pattern. Each route should be in its own file. The file name should use kebab-case. The route handler function should use camelCase. Always include error handling middleware.
+
+**After (45 tokens):**
+
+| API Convention | Rule |
+|---------------|------|
+| Pattern | Express router, one route per file |
+| File naming | kebab-case |
+| Function naming | camelCase |
+| Error handling | Always include middleware |
+
+### Strategy 2: Reference Over Reproduce
+
+**Before (200+ tokens):**
+```typescript
+// Full example of how to create a component
+import React from 'react';
+import styles from './Button.module.css';
+
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  variant?: 'primary' | 'secondary';
+}
+
+export const Button: React.FC<ButtonProps> = ({ label, onClick, variant = 'primary' }) => {
+  return (
+    <button className={styles[variant]} onClick={onClick}>
+      {label}
+    </button>
+  );
+};
+```
+
+**After (30 tokens):**
+> Components: See `src/components/Button/Button.tsx` for reference pattern (named export, CSS Modules, typed props).
+
+### Strategy 3: Conditional Loading
+
+Move specialized knowledge to `.claude/rules/` with `paths:` frontmatter instead of keeping it in the always-loaded CLAUDE.md.
+
+**Before:** 8K token CLAUDE.md with React, API, database, and testing sections all loading every time.
+
+**After:** 2K token CLAUDE.md (universal) + 4 rule files at 1.5K each, loading only when relevant. Typical turn loads 2K + 1.5K = 3.5K instead of 8K.
+
+### Strategy 4: Eliminate Redundancy
+
+Common duplications to consolidate:
+- Same coding standards in CLAUDE.md AND in rules files
+- Same anti-patterns listed in multiple rule files
+- Same command references in CLAUDE.md AND in CI/CD rules
+- Same directory descriptions in CLAUDE.md AND in directory-level CLAUDE.md files
+
+---
+
+## Memory Management
+
+### Session Memory
+
+Claude Code maintains conversation context within a session. To manage it:
+
+1. **Front-load important context** — Put critical instructions early in the conversation
+2. **Avoid repetition** — Don't re-explain what's in CLAUDE.md each turn
+3. **Use tool outputs wisely** — Don't Read files unless needed; each Read consumes tokens
+4. **Batch operations** — Multiple parallel tool calls in one turn instead of sequential turns
+
+### Cross-Session Memory
+
+Claude Code does not retain memory across sessions. To maintain continuity:
+
+1. **CLAUDE.md** — Persistent project knowledge
+2. **Agent MEMORY.md files** — Agent-specific state per squad
+3. **Story files** — Task progress tracking
+4. **Git history** — Code change context
+
+### Context Window Overflow
+
+When the context window fills up:
+- Claude Code truncates oldest conversation messages
+- CLAUDE.md and rules are always preserved (they reload fresh)
+- Tool outputs from early in the conversation may be lost
+
+**Mitigation:** Keep CLAUDE.md concise so more room is available for conversation.
+
+---
+
+## Context Rot Detection
+
+### Indicators of Context Rot
+
+| Indicator | Description | Detection Method |
+|-----------|-------------|-----------------|
+| **Staleness** | References to files, commands, or features that no longer exist | Compare references against current project state |
+| **Redundancy** | Same information in multiple places | Diff CLAUDE.md against rules files |
+| **Contradiction** | Conflicting instructions across files | Cross-reference rules for conflicts |
+| **Bloat** | Information Claude Code already knows generically | Review for standard framework conventions |
+| **Orphaned rules** | Rules with `paths:` patterns matching no files | Validate glob patterns against file tree |
+
+### Maintenance Schedule
+
+| Frequency | Action |
+|-----------|--------|
+| Per sprint | Check for staleness (removed features, changed paths) |
+| Monthly | Full redundancy and contradiction scan |
+| Per major refactor | Update all file path references |
+| Quarterly | Full context rot audit (all indicators) |
+
+---
+
+## Measuring Context Efficiency
+
+### Tokens Per Value Unit
+
+Calculate how many tokens are spent per unit of value:
+
+- **Essential tokens:** Content Claude Code cannot function correctly without
+- **Helpful tokens:** Content that improves quality but is not critical
+- **Waste tokens:** Content that adds no value (redundant, stale, generic)
+
+**Target ratio:** >= 80% essential + helpful, < 20% waste.
+
+### Context Load per Interaction
+
+Monitor the average number of tokens loaded per interaction:
+
+- Base load: System prompt + root CLAUDE.md + global rules
+- Variable load: Contextual rules + conversation
+- Tool load: MCP schemas + tool outputs
+
+**Target:** Base load should be < 30% of total context capacity, leaving >= 70% for conversation and tool outputs.