sinapse-ai 7.1.0 → 7.2.0

package/squads/claude-code-mastery/tasks/optimize-context.md

@@ -0,0 +1,217 @@
+# Task: Optimize Context Window Usage
+
+**Task ID:** CCM-CONFIG-004
+**Version:** 1.0.0
+**Command:** `*optimize-context`
+**Orchestrator:** Sigil (config-engineer)
+**Purpose:** Optimize context window usage by analyzing CLAUDE.md size, moving detailed instructions to conditional `.claude/rules/`, configuring auto-compaction, and reviewing auto-memory files for efficiency.
+
+---
+
+## Overview
+
+```
+  +------------------+     +------------------+     +------------------+
+  | 1. Analyze       | --> | 2. Move Detailed | --> | 3. Configure     |
+  |    CLAUDE.md     |     |    Instructions  |     |    Conditional   |
+  |    Size          |     |    to rules/     |     |    Loading       |
+  +------------------+     +------------------+     +------------------+
+       |                                                    |
+       v                                                    v
+  +------------------+     +------------------+     +------------------+
+  | 4. Review Auto-  | --> | 5. Configure     | --> |    BUDGET        |
+  |    Memory Files  |     |    Compaction    |     |    REPORT        |
+  +------------------+     +------------------+     +------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Working directory | Yes | Must contain CLAUDE.md or .claude/CLAUDE.md |
+| target_lines | number | User parameter | No | Target max lines for CLAUDE.md (default: 200) |
+| dry_run | boolean | User parameter | No | If true, only report without making changes |
+
+---
+
+## Preconditions
+
+- At least one CLAUDE.md file exists (project root or .claude/)
+- Read access to .claude/rules/ directory
+- Read access to auto-memory directory (~/.claude/projects/)
+
+---
+
+## Execution Phases
+
+### Phase 1: Analyze CLAUDE.md Size
+
+1. Locate all CLAUDE.md files:
+   - `./CLAUDE.md` (project root)
+   - `./.claude/CLAUDE.md` (claude directory)
+   - `./CLAUDE.local.md` (local overrides)
+   - `~/.claude/CLAUDE.md` (user-level)
+2. For each file, measure:
+   - Total line count
+   - Section count (by markdown headers)
+   - Estimated token count (lines x ~4 tokens average)
+   - @import count and what they reference
+3. Categorize content sections by purpose:
+   - **Core instructions** (must stay): Project overview, key commands, agent system
+   - **Conditional content** (can move to rules/): Framework-specific, path-scoped
+   - **Reference material** (should use @imports): Architecture docs, API specs
+   - **Redundant content** (can remove): Duplicated across files, outdated
+4. Generate the analysis table:
+
+| Section | Lines | Category | Recommendation |
+|---------|-------|----------|----------------|
+| {header} | {N} | {core/conditional/reference/redundant} | {keep/move/import/remove} |
+
+### Phase 2: Move Detailed Instructions to .claude/rules/
+
+For each section categorized as "conditional":
+
+1. Identify the file paths this section applies to:
+   - API instructions -> `src/api/**`, `server/**`
+   - Component patterns -> `src/components/**/*.tsx`
+   - Test conventions -> `tests/**`, `**/*.test.*`
+   - Database rules -> `migrations/**`, `supabase/**`
+2. Create a new `.claude/rules/{section-name}.md` file:
+   - Add `paths:` YAML frontmatter with appropriate glob patterns
+   - Move the section content into the rule file
+   - Preserve formatting and code examples
+3. Remove the moved section from CLAUDE.md
+4. Add a brief reference comment where the section was:
+   ```markdown
+   <!-- API conventions: see .claude/rules/api-conventions.md -->
+   ```
+
+### Phase 3: Configure Conditional Loading
+
+1. Verify all new rule files have proper frontmatter:
+   ```yaml
+   ---
+   paths:
+     - "src/api/**/*.ts"
+   ---
+   ```
+2. Test glob patterns match actual project files
+3. Organize rules into subdirectories if many rules exist:
+   ```
+   .claude/rules/
+     frontend/
+       component-patterns.md
+       styling-rules.md
+     backend/
+       api-conventions.md
+       database-rules.md
+     testing/
+       test-patterns.md
+   ```
+4. Remove any existing always-on rules that should be conditional
+
+### Phase 4: Review Auto-Memory Files
+
+1. Check the auto-memory directory:
+   - `~/.claude/projects/{project-hash}/memory/`
+2. If auto-memory files exist:
+   - List all memory files and their sizes
+   - Check for outdated or irrelevant memories
+   - Flag memories that duplicate CLAUDE.md content
+   - Suggest cleanup of stale memories
+3. If auto-memory is not active:
+   - Inform the user about auto-memory (Claude creates it automatically)
+   - No action needed
+
+### Phase 5: Configure Compaction
+
+1. Assess the current compaction settings:
+   - Check for `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` env variable
+   - Default trigger is ~95% context capacity
+2. Recommend compaction threshold based on project size:
+
+| Project Size | CLAUDE.md Lines | Recommended PCT | Rationale |
+|-------------|----------------|-----------------|-----------|
+| Small (<100 files) | <100 | Default (95%) | Rarely hits limit |
+| Medium (100-500 files) | 100-200 | 80% | Some headroom needed |
+| Large (500+ files) | 200+ | 50-60% | Frequent compaction needed |
+
+3. Check for PreCompact hook:
+   - If missing: recommend adding one for context preservation
+   - If present: verify it has reasonable timeout (5-10 seconds)
+4. Check `CLAUDE_CODE_MAX_OUTPUT_TOKENS` setting:
+   - Default: 32000, Maximum: 64000
+   - Higher values reduce available context window
+   - Recommend default unless user needs long outputs
+
+---
+
+## Output Format
+
+```markdown
+## Context Optimization Report
+
+**Project:** {project-name}
+**Date:** {YYYY-MM-DD}
+**Mode:** {dry-run | applied}
+
+### CLAUDE.md Analysis
+
+| Metric | Before | After | Change |
+|--------|--------|-------|--------|
+| Total lines | {N} | {N} | {-N (-X%)} |
+| Sections | {N} | {N} | {-N} |
+| Est. tokens | {N} | {N} | {-N (-X%)} |
+| @imports | {N} | {N} | {+N} |
+
+### Content Redistribution
+
+| Section | Lines | Action | Destination |
+|---------|-------|--------|-------------|
+| {section} | {N} | {moved/imported/removed/kept} | {.claude/rules/X.md | @import | --} |
+
+### Context Budget
+
+| Component | Lines | Tokens (est.) | Loading |
+|-----------|-------|---------------|---------|
+| CLAUDE.md | {N} | {N} | Always |
+| .claude/rules/ (total) | {N} | {N} | Conditional |
+| Auto-memory | {N} | {N} | Always |
+| **Total always-loaded** | {N} | {N} | -- |
+
+### Compaction Settings
+
+- **Current trigger:** {N}% (default | override)
+- **Recommended trigger:** {N}%
+- **PreCompact hook:** {configured | missing}
+- **Max output tokens:** {N}
+
+### Savings Summary
+
+- **Context saved per interaction:** ~{N} tokens ({X}% reduction)
+- **Conditional content:** {N} lines loaded only when relevant
+- **Files optimized:** {N}
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** delete content from CLAUDE.md without moving it to .claude/rules/ or confirming with the user that it is redundant.
+- **NEVER** set CLAUDE_AUTOCOMPACT_PCT_OVERRIDE below 30. Values too low cause excessive compaction that degrades session quality.
+- **NEVER** create always-on rules for content that is path-specific. Always use paths: frontmatter for conditional loading.
+- **NEVER** modify auto-memory files directly. They are managed by Claude Code automatically.
+- **NEVER** reduce CLAUDE.md below a functional minimum. Core instructions (project overview, key commands, essential conventions) must remain.
+
+---
+
+## Completion Criteria
+
+- [ ] All CLAUDE.md files analyzed with line counts and section categorization
+- [ ] Conditional content identified and moved to .claude/rules/
+- [ ] Glob patterns validated against project structure
+- [ ] Auto-memory files reviewed for staleness
+- [ ] Compaction threshold recommended with rationale
+- [ ] Before/after comparison generated showing token savings

package/squads/claude-code-mastery/tasks/optimize-workflow.md

@@ -0,0 +1,226 @@
+# Task: Optimize Claude Code Workflow
+
+**Task ID:** CCM-PI-003
+**Version:** 1.0.0
+**Command:** `*optimize-workflow`
+**Agent:** Conduit (project-integrator)
+**Purpose:** Optimize Claude Code workflow for maximum productivity by analyzing usage patterns, identifying bottlenecks, and configuring permissions, shortcuts, and automation.
+
+---
+
+## Overview
+
+```
+  Current Setup
+       |
+       v
+  +---------------------+
+  | 1. Analyze Usage     |
+  |    Patterns          |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 2. Identify          |
+  |    Bottlenecks       |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 3. Optimize          |
+  |    Permissions       |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 4. Set Up Keyboard   |
+  |    Shortcuts         |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 5. Configure         |
+  |    Auto-Memory       |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 6. Generate          |
+  |    Optimization Plan |
+  +---------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_path | string | User or cwd | Yes | Must contain .claude/ directory |
+| pain_points | string[] | User | No | Described bottlenecks (e.g., "too many permission prompts") |
+| workflow_type | enum | User | No | `solo-dev`, `team-review`, `ci-cd`, `exploratory` |
+
+---
+
+## Preconditions
+
+- Claude Code integration exists (.claude/ directory present)
+- User has used Claude Code on this project at least once
+
+---
+
+## Execution Phases
+
+### Phase 1: Analyze Usage Patterns
+
+Examine current configuration to infer usage patterns:
+
+1. **CLAUDE.md analysis**: what instructions are present, what is missing
+2. **settings.json review**: current allow/deny rules, how restrictive
+3. **Rules inventory**: how many rules, what domains they cover
+4. **Hook presence**: what automation exists
+5. **Command/skill inventory**: custom commands and skills defined
+6. **Project size estimation**: file count, language distribution
+
+Classify the current configuration maturity:
+| Level | Description | Typical Signs |
+|-------|-------------|---------------|
+| Starter | Minimal setup | Only CLAUDE.md, no rules, no hooks |
+| Intermediate | Functional | CLAUDE.md + settings + some rules |
+| Advanced | Optimized | Full rules, hooks, skills, MCP configured |
+| Expert | Fully automated | CI/CD integration, custom hooks, agent teams |
+
+### Phase 2: Identify Bottlenecks
+
+Check for common productivity killers:
+
+1. **Permission prompts**: overly restrictive settings forcing repeated approvals
+   - Look for missing allow rules for common commands (npm, git, build tools)
+   - Check if `Bash` tool has no allows (causes prompt on every command)
+2. **Slow tool execution**: MCP servers with high latency, missing caching
+3. **Context bloat**: CLAUDE.md over 150 lines, too many always-loaded rules
+4. **Missing automation**: repetitive tasks that could be hooks or skills
+5. **Context rot**: long sessions without compaction strategy
+6. **Redundant instructions**: duplicated guidance between CLAUDE.md and rules
+
+For each bottleneck found, estimate impact: HIGH, MEDIUM, LOW.
+
+### Phase 3: Optimize Permission Strategy
+
+Design a permission strategy that balances safety and speed:
+
+1. **Safe allows** (add to settings.json allow list):
+   - Build commands: `npm run build`, `npm run dev`, `npm test`
+   - Lint commands: `npm run lint`, `npm run typecheck`
+   - Git read commands: `git status`, `git diff`, `git log`
+   - Language servers and formatters
+2. **Smart denies** (keep or add to deny list):
+   - Destructive commands: `rm -rf`, `DROP`, `git push --force`
+   - Production access: database URLs, deployment commands
+   - Sensitive paths: `.env`, credentials, secrets
+3. **Contextual permissions**: use path-based rules for directory-specific allows
+
+Present before/after comparison of expected permission prompts.
+
+### Phase 4: Set Up Keyboard Shortcuts
+
+Recommend keyboard shortcut configuration for the user's workflow:
+
+1. **Essential shortcuts** (all workflows):
+   - Quick escape: cancel current operation
+   - Accept suggestion: fast-approve tool use
+   - Compact context: trigger manual compaction
+2. **Development shortcuts**:
+   - Run tests: one-key test execution
+   - Quick commit: stage + commit flow
+   - Toggle agent: switch between agent modes
+3. **Review shortcuts**:
+   - Next file: navigate changed files
+   - Approve/reject: fast review actions
+
+Provide configuration snippets for VS Code keybindings.json if applicable.
+
+### Phase 5: Configure Auto-Memory
+
+Set up persistent memory for cross-session efficiency:
+
+1. **Agent memory**: create `.claude/agent-memory/` structure
+   - MEMORY.md for session-persistent patterns
+   - Topic files for domain knowledge
+2. **Memory hygiene rules**:
+   - What to save: confirmed patterns, user preferences, debugging solutions
+   - What NOT to save: session-specific state, speculative conclusions
+   - Size limits: MEMORY.md under 200 lines
+3. **Memory templates**: pre-populate with project conventions if detectable
+
+### Phase 6: Generate Optimization Plan
+
+Produce a prioritized optimization plan:
+
+1. Sort all recommendations by impact (HIGH first)
+2. Group by effort: Quick Wins (< 5 min), Medium (5-30 min), Investment (30+ min)
+3. For each recommendation, provide exact implementation steps
+4. Estimate total time saved per week after optimization
+
+---
+
+## Output Format
+
+```markdown
+## Workflow Optimization Report
+
+**Project:** {project_path}
+**Current Maturity:** {level}
+**Estimated Improvement:** {X}% fewer interruptions
+
+### Bottlenecks Found
+
+| Bottleneck | Impact | Fix Effort |
+|------------|--------|------------|
+| {description} | HIGH/MED/LOW | Quick/Medium/Investment |
+
+### Quick Wins (Apply Now)
+
+1. **{title}**: {description}
+   ```json
+   // Exact config change
+   ```
+
+### Medium Effort
+
+1. **{title}**: {description}
+   - Step 1: ...
+   - Step 2: ...
+
+### Investment Items
+
+1. **{title}**: {description}
+   - Estimated time: {X} minutes
+   - Expected benefit: {description}
+
+### Permission Optimization
+
+**Before:** {N} expected prompts per session
+**After:** {M} expected prompts per session
+**Reduction:** {X}%
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** add allow rules for destructive operations to reduce prompts
+- **NEVER** disable security hooks for convenience
+- **NEVER** remove deny rules without explaining the security tradeoff
+- **NEVER** make changes without presenting the plan first -- this task produces a plan, user applies it
+
+---
+
+## Completion Criteria
+
+- [ ] Usage patterns analyzed and maturity level classified
+- [ ] Bottlenecks identified with impact assessment
+- [ ] Permission strategy designed with before/after comparison
+- [ ] Keyboard shortcuts recommended for workflow type
+- [ ] Memory configuration suggested
+- [ ] Prioritized optimization plan delivered