sinapse-ai 7.1.0 → 7.3.0

package/squads/claude-code-mastery/scripts/validate-setup.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+/**
+ * validate-setup.js
+ * Quick validation of Claude Code setup in a project.
+ * Used by audit-setup.md task.
+ *
+ * Usage: node squads/claude-code-mastery/scripts/validate-setup.js [project-path]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const projectPath = process.argv[2] || process.cwd();
+
+const checks = [
+  {
+    name: '.claude/ directory exists',
+    weight: 15,
+    check: () => fs.existsSync(path.join(projectPath, '.claude')),
+  },
+  {
+    name: 'CLAUDE.md exists',
+    weight: 15,
+    check: () =>
+      fs.existsSync(path.join(projectPath, 'CLAUDE.md')) ||
+      fs.existsSync(path.join(projectPath, '.claude', 'CLAUDE.md')),
+  },
+  {
+    name: 'settings.json exists',
+    weight: 15,
+    check: () =>
+      fs.existsSync(path.join(projectPath, '.claude', 'settings.json')),
+  },
+  {
+    name: 'settings.json has deny rules',
+    weight: 10,
+    check: () => {
+      const settingsPath = path.join(projectPath, '.claude', 'settings.json');
+      if (!fs.existsSync(settingsPath)) return false;
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        const deny = settings.permissions?.deny || [];
+        return deny.length > 0;
+      } catch {
+        return false;
+      }
+    },
+  },
+  {
+    name: '.claude/rules/ directory exists',
+    weight: 10,
+    check: () => fs.existsSync(path.join(projectPath, '.claude', 'rules')),
+  },
+  {
+    name: 'At least 1 rule file',
+    weight: 5,
+    check: () => {
+      const rulesDir = path.join(projectPath, '.claude', 'rules');
+      if (!fs.existsSync(rulesDir)) return false;
+      const files = fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md'));
+      return files.length > 0;
+    },
+  },
+  {
+    name: 'Hooks configured',
+    weight: 10,
+    check: () => {
+      const settingsPath = path.join(projectPath, '.claude', 'settings.json');
+      if (!fs.existsSync(settingsPath)) return false;
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        return settings.hooks && Object.keys(settings.hooks).length > 0;
+      } catch {
+        return false;
+      }
+    },
+  },
+  {
+    name: 'MCP servers configured',
+    weight: 10,
+    check: () => {
+      const settingsPath = path.join(projectPath, '.claude', 'settings.json');
+      if (!fs.existsSync(settingsPath)) return false;
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        return (
+          settings.mcpServers && Object.keys(settings.mcpServers).length > 0
+        );
+      } catch {
+        return false;
+      }
+    },
+  },
+  {
+    name: 'CLAUDE.md under 200 lines',
+    weight: 5,
+    check: () => {
+      const claudeMdPath =
+        fs.existsSync(path.join(projectPath, '.claude', 'CLAUDE.md'))
+          ? path.join(projectPath, '.claude', 'CLAUDE.md')
+          : path.join(projectPath, 'CLAUDE.md');
+      if (!fs.existsSync(claudeMdPath)) return false;
+      const lines = fs.readFileSync(claudeMdPath, 'utf8').split('\n').length;
+      return lines <= 200;
+    },
+  },
+  {
+    name: '.env in deny rules',
+    weight: 5,
+    check: () => {
+      const settingsPath = path.join(projectPath, '.claude', 'settings.json');
+      if (!fs.existsSync(settingsPath)) return false;
+      try {
+        const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+        const deny = settings.permissions?.deny || [];
+        return deny.some(
+          (rule) =>
+            typeof rule === 'string'
+              ? rule.includes('.env')
+              : rule.pattern && rule.pattern.includes('.env')
+        );
+      } catch {
+        return false;
+      }
+    },
+  },
+];
+
+let totalScore = 0;
+let maxScore = 0;
+
+console.log(`\nClaude Code Setup Validation`);
+console.log(`Project: ${projectPath}`);
+console.log(`${'='.repeat(60)}\n`);
+
+for (const check of checks) {
+  const passed = check.check();
+  const icon = passed ? 'PASS' : 'FAIL';
+  const score = passed ? check.weight : 0;
+  totalScore += score;
+  maxScore += check.weight;
+  console.log(`  [${icon}] ${check.name} (${score}/${check.weight})`);
+}
+
+const percentage = Math.round((totalScore / maxScore) * 100);
+const grade =
+  percentage >= 90
+    ? 'A'
+    : percentage >= 80
+      ? 'B'
+      : percentage >= 70
+        ? 'C'
+        : percentage >= 60
+          ? 'D'
+          : 'F';
+
+console.log(`\n${'='.repeat(60)}`);
+console.log(`  Score: ${totalScore}/${maxScore} (${percentage}%)`);
+console.log(`  Grade: ${grade}`);
+console.log(`${'='.repeat(60)}\n`);
+
+process.exit(percentage >= 70 ? 0 : 1);

package/squads/claude-code-mastery/squad.yaml

@@ -0,0 +1,205 @@
+# ═══════════════════════════════════════════════════════════════════════════════
+# Squad: Claude Code Mastery
+# Domain: Claude Code — Full Spectrum Expertise
+# Created: 2026-03-01
+# Version: 1.0.0
+# ═══════════════════════════════════════════════════════════════════════════════
+
+squad:
+  name: claude-code-mastery
+  display_name: "Claude Code Mastery Squad"
+  version: "1.0.0"
+  domain: "Claude Code — Full Spectrum Expertise"
+  description: |
+    Squad especialista em todas as dimensões do Claude Code: hooks, skills,
+    subagents, MCP, plugins, agent teams, customização, integração com projetos,
+    roadmap tracking, e SINAPSE architecture awareness.
+
+  philosophy: |
+    "Master the tool to master the craft."
+    Cada agent é baseado em elite minds reais com frameworks documentados
+    no ecossistema Claude Code. O squad cobre desde automação com hooks
+    até orquestração multi-agente e engenharia de contexto.
+
+  keywords:
+    - claude-code
+    - hooks
+    - skills
+    - subagents
+    - mcp
+    - plugins
+    - agent-teams
+    - customization
+    - integration
+    - context-engineering
+    - roadmap
+    - sinapse
+
+  entry_agent: claude-mastery-chief
+  created_by: "squad-creator-pro"
+  created_at: "2026-03-01"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# TIER ARCHITECTURE
+# ─────────────────────────────────────────────────────────────────────────────
+
+tiers:
+  tier_0:
+    name: "Diagnosis & Routing"
+    agents:
+      - claude-mastery-chief
+    purpose: "Triage requests, route to specialist, maintain squad coherence"
+
+  tier_1:
+    name: "Core Mastery"
+    agents:
+      - hooks-architect
+      - mcp-integrator
+      - swarm-orqx
+      - config-engineer
+    purpose: "Deep expertise in Claude Code feature domains"
+
+  tier_2:
+    name: "Strategic & Context"
+    agents:
+      - skill-craftsman
+      - project-integrator
+      - roadmap-sentinel
+    purpose: "Cross-cutting expertise: skills, project integration, roadmap awareness"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# AGENT REGISTRY
+# ─────────────────────────────────────────────────────────────────────────────
+
+agents:
+  claude-mastery-chief:
+    file: agents/claude-mastery-chief.md
+    tier: 0
+    based_on: "Original (Orchestrator)"
+    icon: "🧠"
+    focus: "Triage, routing, SINAPSE awareness"
+
+  hooks-architect:
+    file: agents/hooks-architect.md
+    tier: 1
+    based_on: "disler (Hooks Mastery)"
+    icon: "🪝"
+    focus: "17 hook events, automation pipelines, meta-agent patterns"
+
+  mcp-integrator:
+    file: agents/mcp-integrator.md
+    tier: 1
+    based_on: "Peter Steinberger (@steipete)"
+    icon: "🔌"
+    focus: "MCP servers, tool discovery, agent-as-MCP, integration patterns"
+
+  swarm-orqx:
+    file: agents/swarm-orqx.md
+    tier: 1
+    based_on: "Kieran Klaassen + Reuven Cohen"
+    icon: "🐝"
+    focus: "Agent Teams, subagents, multi-session coordination, worktrees"
+
+  config-engineer:
+    file: agents/config-engineer.md
+    tier: 1
+    based_on: "SuperClaude-Org"
+    icon: "⚙️"
+    focus: "Settings, permissions, CLAUDE.md, rules, managed policies, personas"
+
+  skill-craftsman:
+    file: agents/skill-craftsman.md
+    tier: 2
+    based_on: "BMAD-CODE-ORG + community"
+    icon: "🛠️"
+    focus: "Skills, commands, plugins, context engineering, spec-driven dev"
+
+  project-integrator:
+    file: agents/project-integrator.md
+    tier: 2
+    based_on: "Daniel Miessler (PAI)"
+    icon: "📦"
+    focus: "Project integration, repository setup, SINAPSE awareness, Unix philosophy"
+
+  roadmap-sentinel:
+    file: agents/roadmap-sentinel.md
+    tier: 2
+    based_on: "Boris Cherny (philosophy) + Official sources"
+    icon: "🔭"
+    focus: "Roadmap tracking, changelog monitoring, feature adoption, plan-first"
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HANDOFF MATRIX
+# ─────────────────────────────────────────────────────────────────────────────
+
+handoffs:
+  claude-mastery-chief:
+    routes_to: [hooks-architect, mcp-integrator, swarm-orqx, config-engineer, skill-craftsman, project-integrator, roadmap-sentinel]
+
+  hooks-architect:
+    collaborates_with: [config-engineer, skill-craftsman]
+    escalates_to: [claude-mastery-chief]
+
+  mcp-integrator:
+    collaborates_with: [hooks-architect, project-integrator]
+    escalates_to: [claude-mastery-chief]
+
+  swarm-orqx:
+    collaborates_with: [hooks-architect, config-engineer]
+    escalates_to: [claude-mastery-chief]
+
+  config-engineer:
+    collaborates_with: [hooks-architect, skill-craftsman, project-integrator]
+    escalates_to: [claude-mastery-chief]
+
+  skill-craftsman:
+    collaborates_with: [hooks-architect, config-engineer]
+    escalates_to: [claude-mastery-chief]
+
+  project-integrator:
+    collaborates_with: [config-engineer, mcp-integrator, roadmap-sentinel]
+    escalates_to: [claude-mastery-chief]
+
+  roadmap-sentinel:
+    collaborates_with: [project-integrator, claude-mastery-chief]
+    escalates_to: [claude-mastery-chief]
+
+# ─────────────────────────────────────────────────────────────────────────────
+# CROSS-CUTTING CONCERNS
+# ─────────────────────────────────────────────────────────────────────────────
+
+cross_cutting:
+  sinapse_awareness:
+    description: "ALL agents understand SINAPSE architecture"
+    context_files:
+      - ".claude/CLAUDE.md"
+      - ".sinapse-ai/core-config.yaml"
+      - ".sinapse-ai/data/entity-registry.yaml"
+
+  update_knowledge:
+    description: "Command to refresh from Claude Code changelog and roadmap"
+    command: "*update-knowledge"
+    sources:
+      - "https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md"
+      - "https://code.claude.com/docs/en/overview"
+      - "https://github.com/anthropics/claude-code/releases"
+
+  quality_standards:
+    min_score: 7.0
+    smoke_tests: 3
+    voice_dna_required: true
+    thinking_dna_required: true
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SETTINGS
+# ─────────────────────────────────────────────────────────────────────────────
+
+settings:
+  greeting:
+    level: archetypal
+    show_project_status: true
+    show_sinapse_context: true
+
+  activation:
+    prefix: "claude-code-mastery"
+    example: "@claude-code-mastery:hooks-architect"

package/squads/claude-code-mastery/tasks/audit-integration.md

@@ -0,0 +1,219 @@
+# Task: Audit Existing Claude Code Integration
+
+**Task ID:** CCM-PI-002
+**Version:** 1.0.0
+**Command:** `*audit-integration`
+**Agent:** Conduit (project-integrator)
+**Purpose:** Audit an existing Claude Code integration in a project, checking completeness, consistency, health, and generating an actionable score with recommendations.
+
+---
+
+## Overview
+
+```
+  Target Project
+       |
+       v
+  +--------------------+
+  | 1. Check .claude/   |
+  |    Completeness     |
+  +--------------------+
+       |
+       v
+  +--------------------+
+  | 2. Validate Settings|
+  |    Consistency      |
+  +--------------------+
+       |
+       v
+  +--------------------+
+  | 3. Check Rule       |
+  |    Coverage         |
+  +--------------------+
+       |
+       v
+  +--------------------+
+  | 4. Verify Hook      |
+  |    Health           |
+  +--------------------+
+       |
+       v
+  +--------------------+
+  | 5. Test MCP         |
+  |    Connectivity     |
+  +--------------------+
+       |
+       v
+  +--------------------+
+  | 6. Generate Score   |
+  |    & Recommendations|
+  +--------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_path | string | User or cwd | Yes | Must contain .claude/ directory |
+| deep_scan | boolean | User | No | Default false; true scans all source files for consistency |
+
+---
+
+## Preconditions
+
+- `.claude/` directory exists in the target project
+- Read access to all project files
+
+---
+
+## Execution Phases
+
+### Phase 1: Check .claude/ Completeness
+
+Scan the `.claude/` directory and check for expected components:
+
+| Component | Required | Path | Weight |
+|-----------|----------|------|--------|
+| CLAUDE.md | Yes | `.claude/CLAUDE.md` | 25 |
+| settings.json | Yes | `.claude/settings.json` | 20 |
+| settings.local.json | Recommended | `.claude/settings.local.json` | 5 |
+| rules/ directory | Recommended | `.claude/rules/` | 15 |
+| At least 1 rule file | Recommended | `.claude/rules/*.md` | 10 |
+| commands/ directory | Optional | `.claude/commands/` | 5 |
+| skills/ directory | Optional | `.claude/skills/` | 5 |
+
+For each component, record: present/missing, file size, last modified date.
+
+### Phase 2: Validate Settings Consistency
+
+Parse `.claude/settings.json` and check:
+
+1. **JSON validity**: parseable without errors
+2. **Permission coherence**: no contradictions between allow and deny rules
+3. **Path accuracy**: all referenced paths in deny/allow actually exist
+4. **Dangerous gaps**: common dangerous commands not explicitly denied
+   - `rm -rf /`, `git push --force`, `DROP TABLE`, `sudo`
+5. **Overly permissive**: check for `bash("*")` or wildcard allows
+6. **SINAPSE compatibility**: if SINAPSE project, verify L1/L2 protection rules present
+
+Flag each finding as: PASS, WARN, FAIL.
+
+### Phase 3: Check Rule Coverage
+
+For each rule file in `.claude/rules/`:
+
+1. Validate frontmatter format (paths: array present if contextual)
+2. Check rule content is non-empty and actionable
+3. Verify path globs in frontmatter match actual project files
+4. Identify coverage gaps:
+   - Source code edited but no coding-standards rule
+   - Tests present but no testing rule
+   - CI/CD files present but no workflow rule
+   - Database files present but no database rule
+
+### Phase 4: Verify Hook Health
+
+Check hook configuration and health:
+
+1. **Registration**: Are hooks registered in settings.json or ~/.claude/settings.json?
+2. **File existence**: Do referenced hook scripts exist?
+3. **Syntax**: Can hook scripts be parsed without errors?
+4. **Permissions**: Are hook scripts executable?
+5. **Timeout risk**: Do hooks have operations that could hang (network calls without timeout)?
+
+For each hook, classify as: HEALTHY, DEGRADED, BROKEN, MISSING.
+
+### Phase 5: Test MCP Connectivity
+
+If MCP servers are configured:
+
+1. List all configured MCP servers from settings
+2. For each server, check:
+   - Configuration is complete (command, args, env present)
+   - Binary/command exists on PATH
+   - No obvious credential issues (empty env vars)
+3. Categorize: CONNECTED, CONFIGURED, MISCONFIGURED, MISSING
+
+If no MCP configured, note as N/A with recommendation.
+
+### Phase 6: Generate Score and Recommendations
+
+Calculate integration health score (0-100):
+
+```
+Score = sum(component_weight * component_score) / max_possible_score * 100
+
+Where component_score:
+  PASS = 1.0
+  WARN = 0.5
+  FAIL = 0.0
+  N/A  = excluded from calculation
+```
+
+**Grade thresholds:**
+| Score | Grade | Label |
+|-------|-------|-------|
+| 90-100 | A | Excellent integration |
+| 75-89 | B | Good, minor improvements possible |
+| 60-74 | C | Functional, notable gaps |
+| 40-59 | D | Significant issues, recommend remediation |
+| 0-39 | F | Critical gaps, integration not effective |
+
+---
+
+## Output Format
+
+```markdown
+## Claude Code Integration Audit
+
+**Project:** {project_path}
+**Date:** {YYYY-MM-DD}
+**Score:** {score}/100 (Grade: {grade})
+
+### Component Status
+
+| Component | Status | Details |
+|-----------|--------|---------|
+| CLAUDE.md | PASS/WARN/FAIL | {detail} |
+| settings.json | PASS/WARN/FAIL | {detail} |
+| Rules | PASS/WARN/FAIL | {N} files, {coverage}% coverage |
+| Hooks | PASS/WARN/FAIL/N/A | {N} healthy, {N} broken |
+| MCP | PASS/WARN/FAIL/N/A | {N} connected |
+
+### Findings
+
+#### Critical (Must Fix)
+1. {finding} -- {recommendation}
+
+#### Warnings (Should Fix)
+1. {finding} -- {recommendation}
+
+#### Info (Nice to Have)
+1. {finding} -- {recommendation}
+
+### Quick Fixes
+
+{Numbered list of commands or actions to fix top issues}
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** modify any project files during audit -- this is read-only analysis
+- **NEVER** execute hook scripts to test them -- only static analysis
+- **NEVER** attempt MCP connections that could trigger side effects
+- **NEVER** report credentials or secrets found in configuration files
+
+---
+
+## Completion Criteria
+
+- [ ] All 6 phases executed
+- [ ] Score calculated with weighted components
+- [ ] Grade assigned from threshold table
+- [ ] Critical findings listed with specific recommendations
+- [ ] Quick fixes provided for top issues
+- [ ] Audit report presented in standard format