sinapse-ai 7.1.0 → 7.2.0

package/squads/claude-code-mastery/tasks/context-rot-audit.md

@@ -0,0 +1,329 @@
+# Task: Context Rot Audit
+
+**Task ID:** context-rot-audit
+**Version:** 1.0
+**Purpose:** Audit CLAUDE.md, rules, and auto-memory for stale, incorrect, or bloated context that degrades Claude Code performance
+**Orchestrator:** @project-integrator (Conduit)
+**Mode:** Autonomous (elicit: false)
+**Quality Standard:** Rot score calculated, all stale references identified, remediation plan generated
+
+---
+
+## Overview
+
+Context rot occurs when CLAUDE.md, rules files, and auto-memory accumulate outdated instructions, references to deleted files, deprecated patterns, and bloated content. This audit systematically detects rot and produces a remediation plan.
+
+```
+INPUT (project_root)
+    |
+[PHASE 1: CLAUDE.MD SIZE AUDIT]
+    -> Measure line count and section sizes
+    -> Flag if over 500 lines
+    -> Identify largest sections
+    |
+[PHASE 2: REFERENCE VALIDATION]
+    -> Check every file path referenced in CLAUDE.md
+    -> Check every file path referenced in rules
+    -> Report missing/moved files
+    |
+[PHASE 3: INSTRUCTION STALENESS]
+    -> Check for outdated API references
+    -> Check for deprecated package mentions
+    -> Check for patterns that conflict with current code
+    |
+[PHASE 4: RULES STRUCTURE AUDIT]
+    -> Verify rules match current directory structure
+    -> Check for orphaned rules (paths no longer exist)
+    -> Validate frontmatter path patterns
+    |
+[PHASE 5: AUTO-MEMORY AUDIT]
+    -> Check .claude/agent-memory/ for stale entries
+    -> Verify referenced files still exist
+    -> Check for contradictory entries
+    |
+[PHASE 6: ROT SCORE AND REMEDIATION]
+    -> Calculate overall rot score
+    -> Generate prioritized fix list
+    -> Produce remediation plan
+    |
+OUTPUT: Rot score + findings report + remediation plan
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Auto-detect | yes | Valid directory with .claude/ or CLAUDE.md |
+| fix_automatically | boolean | User | no | Whether to auto-fix simple issues (default: false) |
+| verbose | boolean | User | no | Show all checks including passing (default: false) |
+
+---
+
+## Preconditions
+
+1. Project has Claude Code configured (CLAUDE.md or .claude/ exists)
+2. Git repository for change history analysis
+3. Read access to all project files
+
+---
+
+## Phase 1: CLAUDE.md Size Audit
+
+**Goal:** Check if CLAUDE.md has grown beyond effective size.
+
+### Size Thresholds
+
+| Lines | Status | Impact |
+|-------|--------|--------|
+| < 100 | Lean | Optimal for auto-memory |
+| 100-200 | Normal | Good for most projects |
+| 200-500 | Growing | Consider splitting into rules |
+| 500+ | Bloated | Actively degrades performance |
+
+### Steps
+
+1.1. Count total lines in CLAUDE.md.
+1.2. Measure each section's line count.
+1.3. Identify the top 3 largest sections.
+1.4. Flag any section over 50 lines as candidate for extraction to rules file.
+1.5. Check for duplicate information across sections.
+
+### Findings Format
+
+```yaml
+size_audit:
+  total_lines: 347
+  status: "growing"
+  largest_sections:
+    - name: "Code Standards"
+      lines: 89
+      recommendation: "Extract to .claude/rules/code-standards.md"
+    - name: "API Reference"
+      lines: 67
+      recommendation: "Extract to .claude/rules/api.md"
+  duplicates_found: 2
+```
+
+---
+
+## Phase 2: Reference Validation
+
+**Goal:** Verify every file/directory referenced in context files actually exists.
+
+### Steps
+
+2.1. Extract all file paths from CLAUDE.md (look for backtick-quoted paths, code blocks).
+2.2. Extract all file paths from `.claude/rules/*.md`.
+2.3. For each path, check if it exists in the project:
+
+```
+Reference: `src/components/Button.tsx`
+Status: EXISTS / MISSING / MOVED
+
+Reference: `npm run test:e2e`
+Status: VALID (in package.json scripts) / INVALID
+```
+
+2.4. Check command references against package.json scripts.
+2.5. Report all missing references with suggested fixes.
+
+### Findings Format
+
+```yaml
+reference_audit:
+  total_references: 45
+  valid: 38
+  missing: 5
+  likely_moved: 2
+  missing_details:
+    - path: "src/lib/api-client.ts"
+      referenced_in: "CLAUDE.md:42"
+      suggestion: "File was renamed to src/lib/http-client.ts"
+```
+
+---
+
+## Phase 3: Instruction Staleness
+
+**Goal:** Detect outdated instructions that could cause Claude to do the wrong thing.
+
+### Staleness Indicators
+
+| Signal | Detection Method |
+|--------|-----------------|
+| Deprecated package | Check if version in instructions differs from package.json |
+| Old API patterns | Instructions mention patterns not found in current code |
+| Removed scripts | Referenced npm scripts no longer in package.json |
+| Old directory structure | Instructions reference paths that were restructured |
+| Version-specific instructions | Instructions tied to old framework version |
+
+### Steps
+
+3.1. Cross-reference CLAUDE.md instructions with current package.json:
+   - Are referenced dependencies still installed?
+   - Do version numbers match?
+3.2. Check if code patterns described in CLAUDE.md exist in the codebase:
+   - Grep for the pattern in source files
+   - If not found, the instruction is stale
+3.3. Check for tech-specific staleness:
+   - React class components mentioned but none exist
+   - Old import paths referenced
+   - Deprecated API methods mentioned
+
+### Findings Format
+
+```yaml
+staleness_audit:
+  total_instructions_checked: 23
+  current: 18
+  stale: 4
+  uncertain: 1
+  stale_details:
+    - instruction: "Use getServerSideProps for data fetching"
+      location: "CLAUDE.md:78"
+      issue: "Project uses App Router with server components"
+      fix: "Update to describe server component patterns"
+```
+
+---
+
+## Phase 4: Rules Structure Audit
+
+**Goal:** Verify rules files match the current project structure.
+
+### Steps
+
+4.1. List all `.claude/rules/*.md` files.
+4.2. For each rule with path-based frontmatter:
+   - Extract the `paths:` patterns
+   - Verify at least one file matches the glob pattern
+   - If no files match, the rule is orphaned
+
+4.3. Check for missing rules:
+   - Are there important directories with no corresponding rule?
+   - Compare rule coverage against project structure
+
+4.4. Check for conflicting rules:
+   - Do any rules give contradictory instructions for the same paths?
+
+### Findings Format
+
+```yaml
+rules_audit:
+  total_rules: 6
+  active: 4
+  orphaned: 1
+  missing_coverage: 2
+  orphaned_details:
+    - file: ".claude/rules/graphql.md"
+      paths_pattern: "src/graphql/**"
+      issue: "No graphql directory exists (removed in v2 migration)"
+  missing_coverage:
+    - directory: "src/middleware/"
+      suggestion: "Create middleware.md rule for auth and validation patterns"
+```
+
+---
+
+## Phase 5: Auto-Memory Audit
+
+**Goal:** Check agent memory files for stale entries.
+
+### Steps
+
+5.1. Scan `.claude/agent-memory/` for all memory files.
+5.2. For each memory file:
+   - Check if referenced files still exist
+   - Check if referenced patterns are still valid
+   - Check for contradictions with current CLAUDE.md
+5.3. Check MEMORY.md line count (should be under 200 for auto-loading).
+5.4. Identify entries that are session-specific (should not be in persistent memory).
+
+---
+
+## Phase 6: Rot Score and Remediation
+
+**Goal:** Calculate overall health and produce a fix plan.
+
+### Rot Score Calculation
+
+```
+Rot Score = (missing_refs * 3) + (stale_instructions * 5) + (orphaned_rules * 2) +
+            (size_penalty) + (memory_issues * 2)
+
+Size Penalty:
+  < 200 lines: 0 points
+  200-500 lines: 5 points
+  500+ lines: 15 points
+
+Score Interpretation:
+  0-5:   Healthy (green)
+  6-15:  Minor rot (yellow) -- schedule cleanup
+  16-30: Significant rot (orange) -- clean up soon
+  31+:   Critical rot (red) -- clean up now
+```
+
+### Remediation Plan
+
+6.1. Generate prioritized fix list:
+
+| Priority | Fix | Effort | Impact |
+|----------|-----|--------|--------|
+| P0 | Remove references to deleted files | Low | High |
+| P1 | Update stale instructions | Medium | High |
+| P2 | Remove orphaned rules | Low | Medium |
+| P3 | Extract large CLAUDE.md sections to rules | Medium | Medium |
+| P4 | Clean stale memory entries | Low | Low |
+
+6.2. If `fix_automatically` is true, apply P0 fixes automatically.
+6.3. Generate a summary report.
+
+---
+
+## Output Format
+
+```yaml
+context_rot_audit_result:
+  rot_score: 12
+  severity: "yellow"
+  summary:
+    total_checks: 89
+    passed: 76
+    warnings: 8
+    failures: 5
+  phases:
+    size_audit:
+      lines: 234
+      status: "growing"
+    reference_validation:
+      total: 45
+      missing: 3
+    instruction_staleness:
+      total: 23
+      stale: 2
+    rules_structure:
+      total: 6
+      orphaned: 1
+    auto_memory:
+      total: 3
+      stale_entries: 1
+  remediation:
+    auto_fixed: 0
+    manual_fixes_needed: 7
+    priority_list: [...]
+  overall_status: "NEEDS_ATTENTION"
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| No CLAUDE.md and no .claude/ directory | HALT -- nothing to audit |
+| Project has no git history (cannot determine staleness) | WARN -- skip staleness checks |
+| Rot score exceeds 50 | HALT -- critical rot, needs immediate human attention |
+| Auto-fix would modify more than 10 files | HALT -- too many changes, require manual review |
+| CLAUDE.md has SINAPSE-managed sections | WARN -- do not modify managed sections |

package/squads/claude-code-mastery/tasks/create-agent-definition.md

@@ -0,0 +1,278 @@
+# Task: Create Custom Subagent Definition
+
+**Task ID:** create-agent-definition
+**Version:** 1.0
+**Purpose:** Create a purpose-built subagent definition file for use with the Agent tool
+**Orchestrator:** @swarm-orqx (Nexus)
+**Mode:** Interactive (elicit: true)
+**Quality Standard:** Agent file passes lint, loads correctly, and executes test prompt
+
+---
+
+## Overview
+
+This task creates a custom subagent definition in `.claude/agents/` that can be invoked via the Agent tool. Subagents are specialized Claude instances with scoped instructions, model selection, and optional tool restrictions.
+
+```
+INPUT (agent_purpose + scope + complexity)
+    |
+[PHASE 1: PURPOSE DEFINITION]
+    -> Define what the agent does and does not do
+    -> Identify required tools and knowledge
+    -> Determine isolation needs
+    |
+[PHASE 2: TYPE SELECTION]
+    -> Choose subagent type (general, explore, plan)
+    -> Select model (opus, sonnet, haiku)
+    -> Define tool restrictions
+    |
+[PHASE 3: FILE CREATION]
+    -> Create .claude/agents/{name}.md
+    -> Write YAML frontmatter
+    -> Write instruction body in markdown
+    |
+[PHASE 4: INSTRUCTION ENGINEERING]
+    -> Write clear behavioral instructions
+    -> Define output format expectations
+    -> Add guardrails and constraints
+    |
+[PHASE 5: MODEL SELECTION]
+    -> Match complexity to model tier
+    -> Configure cost/quality tradeoff
+    -> Set max_turns if needed
+    |
+[PHASE 6: VALIDATION]
+    -> Test agent with Agent tool
+    -> Verify tool access works as expected
+    -> Check output quality
+    |
+OUTPUT: Agent definition file + test results
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| agent_name | string | User | yes | Kebab-case, no spaces (e.g., code-reviewer) |
+| agent_purpose | string | User | yes | One-sentence description of what the agent does |
+| complexity | enum | User or auto | yes | simple / standard / complex |
+| tools_needed | array | User | no | List of tools the agent needs access to |
+| output_format | string | User | no | Expected output structure (markdown, json, yaml) |
+
+---
+
+## Preconditions
+
+1. `.claude/agents/` directory exists (create if not)
+2. Understanding of the task the agent will perform
+3. Claude Code is operational for testing
+
+---
+
+## Phase 1: Purpose Definition
+
+**Goal:** Clearly scope what the agent will and will not do.
+
+### Steps
+
+1.1. Define the agent's primary responsibility in one sentence.
+1.2. List 3-5 specific tasks the agent should handle.
+1.3. List 2-3 things the agent should NOT do (anti-scope).
+1.4. Identify what context the agent needs (files, project knowledge, etc.).
+
+### Purpose Template
+
+```
+Agent: {name}
+Does: {primary responsibility}
+Tasks: {task1}, {task2}, {task3}
+Does NOT: {anti1}, {anti2}
+Needs: {context1}, {context2}
+```
+
+---
+
+## Phase 2: Type Selection
+
+**Goal:** Choose the right subagent configuration.
+
+### Subagent Types
+
+| Type | Tools Available | Best For |
+|------|----------------|----------|
+| **General-purpose** (default) | All tools | Implementation, analysis, complex tasks |
+| **Explore** | Read, Glob, Grep, Bash(read-only) | Research, code search, documentation lookup |
+| **Plan** | Read, Glob, Grep (no write) | Design, architecture, planning tasks |
+
+### Steps
+
+2.1. Match the agent's purpose to a type.
+2.2. If none fit, use general-purpose with explicit `allowed-tools` restrictions.
+2.3. Document the type decision and rationale.
+
+---
+
+## Phase 3: File Creation
+
+**Goal:** Create the agent definition file with proper structure.
+
+### Agent File Template
+
+```markdown
+---
+name: {agent-name}
+description: {one-line description}
+model: {opus-4|sonnet-4|haiku-4}
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+---
+
+# {Agent Name}
+
+## Role
+{Detailed description of agent's role and expertise}
+
+## Instructions
+{Step-by-step behavioral instructions}
+
+## Constraints
+{What the agent must NOT do}
+
+## Output Format
+{Expected output structure}
+```
+
+### Steps
+
+3.1. Create `.claude/agents/{name}.md` using the template above.
+3.2. Fill in YAML frontmatter with name, description, model, and allowed-tools.
+3.3. The frontmatter fields are:
+   - `name`: Display name for the agent
+   - `description`: Brief description shown in agent listings
+   - `model`: Which Claude model to use (see Phase 5)
+   - `allowed-tools`: Array of tools the agent can access (omit for all tools)
+
+---
+
+## Phase 4: Instruction Engineering
+
+**Goal:** Write clear, effective instructions in the markdown body.
+
+### Instruction Best Practices
+
+1. **Be specific** -- "Analyze imports and suggest barrel files" not "Help with code"
+2. **Set output expectations** -- Describe the exact format you want
+3. **Add examples** -- Show input/output pairs when possible
+4. **Define boundaries** -- What the agent should refuse or escalate
+5. **Include context loading** -- Tell the agent what files to read first
+
+### Instruction Sections
+
+```markdown
+## Role
+You are a {role} specialized in {domain}. Your job is to {primary task}.
+
+## Process
+1. First, read {relevant files}
+2. Then, analyze {what to look for}
+3. Finally, produce {output format}
+
+## Rules
+- ALWAYS {mandatory behavior}
+- NEVER {prohibited behavior}
+- When unsure, {fallback behavior}
+
+## Output Format
+Return your analysis as:
+{format specification}
+```
+
+4.1. Write the Role section with clear identity.
+4.2. Write the Process section with numbered steps.
+4.3. Write the Rules section with ALWAYS/NEVER constraints.
+4.4. Write the Output Format section with structure specification.
+
+---
+
+## Phase 5: Model Selection
+
+**Goal:** Choose the right model for cost and quality balance.
+
+### Model Selection Guide
+
+| Model | Cost | Speed | Best For |
+|-------|------|-------|----------|
+| **claude-opus-4** | High | Slow | Complex analysis, architecture decisions, nuanced writing |
+| **claude-sonnet-4** | Medium | Medium | Standard tasks, code review, implementation |
+| **claude-haiku-4** | Low | Fast | Simple lookups, formatting, repetitive tasks |
+
+### Decision Matrix
+
+```
+Is the task complex with ambiguous inputs?
+  YES -> opus
+  NO  -> Does it require code generation or analysis?
+    YES -> sonnet
+    NO  -> Is it a simple lookup or formatting task?
+      YES -> haiku
+      NO  -> sonnet (safe default)
+```
+
+5.1. Evaluate task complexity against the matrix.
+5.2. Set the `model` field in frontmatter.
+5.3. Consider that subagents incur per-call costs -- haiku for high-frequency agents.
+
+---
+
+## Phase 6: Validation
+
+**Goal:** Test that the agent works correctly.
+
+### Steps
+
+6.1. Invoke the agent using the Agent tool with a representative prompt.
+6.2. Verify the agent:
+   - Uses only its allowed tools
+   - Follows its instructions
+   - Produces output in the expected format
+   - Stays within its defined scope
+6.3. If the agent fails, iterate on instructions (most common fix).
+6.4. Run 2-3 different test prompts to cover edge cases.
+
+---
+
+## Output Format
+
+```yaml
+agent_definition_result:
+  file: ".claude/agents/{name}.md"
+  name: "{agent-name}"
+  type: "{general|explore|plan}"
+  model: "{opus-4|sonnet-4|haiku-4}"
+  tools_allowed: [...]
+  test_results:
+    - prompt: "Test prompt 1"
+      status: "pass"
+    - prompt: "Test prompt 2"
+      status: "pass"
+  ready: true
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Agent purpose is too broad (covers 5+ unrelated domains) | HALT -- split into multiple agents |
+| No clear output format defined | HALT -- define expected output before creation |
+| Agent requires tools that do not exist | HALT -- verify tool availability first |
+| Test prompts all fail | HALT -- rewrite instructions, do not ship broken agent |
+| Agent name conflicts with existing agent | HALT -- choose unique name |