sinapse-ai 7.1.0 → 7.2.0

package/squads/claude-code-mastery/tasks/integrate-project.md

@@ -0,0 +1,304 @@
+# Task: Integrate Claude Code into Existing Project
+
+**Task ID:** integrate-project
+**Version:** 1.0
+**Purpose:** Set up Claude Code infrastructure in an existing project with tailored configuration
+**Orchestrator:** @project-integrator (Conduit)
+**Mode:** Interactive (elicit: true)
+**Quality Standard:** Integration passes smoke test, all config files valid, CLAUDE.md under 200 lines
+
+---
+
+## Overview
+
+This task integrates Claude Code into an existing project by detecting the project's tech stack, generating appropriate configuration, setting up rules, hooks, and MCP servers. Follows Unix philosophy: do one thing well, compose small tools.
+
+```
+INPUT (project_root)
+    |
+[PHASE 1: PROJECT DETECTION]
+    -> Scan for package.json, requirements.txt, go.mod, etc.
+    -> Identify frameworks, languages, and patterns
+    -> Detect existing CI/CD, linting, testing setup
+    |
+[PHASE 2: CLAUDE.MD GENERATION]
+    -> Generate CLAUDE.md tailored to project
+    -> Include code standards, testing, git conventions
+    -> Keep under 200 lines
+    |
+[PHASE 3: SETTINGS CONFIGURATION]
+    -> Create .claude/settings.json
+    -> Configure deny/allow rules for critical paths
+    -> Set up permissions appropriate to project
+    |
+[PHASE 4: RULES SETUP]
+    -> Create .claude/rules/ directory
+    -> Write path-based contextual rules
+    -> Configure auto-loading behavior
+    |
+[PHASE 5: HOOKS CONFIGURATION]
+    -> Identify project workflow integration points
+    -> Set up pre-tool-use guards if needed
+    -> Configure notification hooks
+    |
+[PHASE 6: MCP SETUP]
+    -> Identify useful MCP servers for the stack
+    -> Configure project-specific MCPs
+    -> Validate tool availability
+    |
+[PHASE 7: AGENTS SETUP]
+    -> Create project-specific subagent definitions
+    -> Configure agents for project's domain
+    -> Test agent execution
+    |
+[PHASE 8: SMOKE TEST]
+    -> Verify all config files parse correctly
+    -> Test Claude Code can read and understand the project
+    -> Validate rules load in correct contexts
+    |
+OUTPUT: Complete Claude Code integration + smoke test results
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_root | string | Auto-detect | yes | Valid directory with source code |
+| project_name | string | Auto or user | no | Human-readable project name |
+| primary_language | string | Auto-detect | no | Main programming language |
+| team_size | string | User | no | solo / small / medium / large |
+| existing_ci | boolean | Auto-detect | no | Whether CI/CD is already configured |
+
+---
+
+## Preconditions
+
+1. Project directory exists with source code
+2. Claude Code CLI is installed
+3. User has write access to project directory
+4. Git is initialized in the project (or will be)
+
+---
+
+## Phase 1: Project Detection
+
+**Goal:** Understand the project's tech stack and conventions.
+
+### Detection Signals
+
+| File | Indicates |
+|------|-----------|
+| `package.json` | Node.js project -- check scripts, dependencies |
+| `tsconfig.json` | TypeScript usage |
+| `next.config.*` | Next.js framework |
+| `requirements.txt` / `pyproject.toml` | Python project |
+| `go.mod` | Go project |
+| `Cargo.toml` | Rust project |
+| `.eslintrc*` / `eslint.config.*` | ESLint configured |
+| `.prettierrc*` | Prettier configured |
+| `jest.config.*` / `vitest.config.*` | Test framework |
+| `Dockerfile` / `docker-compose.yml` | Containerized |
+| `.github/workflows/` | GitHub Actions CI/CD |
+| `supabase/` | Supabase database |
+
+### Steps
+
+1.1. Scan project root for all detection signals above.
+1.2. Read `package.json` (if exists) for scripts and dependencies.
+1.3. Identify the project structure pattern (monorepo, single-app, library).
+1.4. Detect existing code formatting and linting rules.
+1.5. Document findings:
+
+```yaml
+detection:
+  language: "TypeScript"
+  framework: "Next.js 14"
+  package_manager: "npm"
+  test_framework: "Jest"
+  linter: "ESLint"
+  formatter: "Prettier"
+  ci: "GitHub Actions"
+  database: "Supabase"
+  structure: "single-app"
+```
+
+---
+
+## Phase 2: CLAUDE.md Generation
+
+**Goal:** Create a concise, effective CLAUDE.md file.
+
+### Guidelines
+
+- Keep under 200 lines (auto-memory compatibility)
+- Focus on what Claude needs to know, not general documentation
+- Include: code standards, testing commands, git conventions, key architecture decisions
+- Use managed sections (`<!-- SINAPSE-MANAGED-START -->`) for auto-updatable content
+
+### Steps
+
+2.1. Generate CLAUDE.md with these sections:
+   - Project overview (2-3 sentences)
+   - Tech stack summary (table)
+   - Code standards (from detected linter/formatter config)
+   - Testing commands (from package.json scripts)
+   - Git conventions (from existing commit history)
+   - Key directories and their purposes
+   - Common commands reference
+
+2.2. Verify line count is under 200.
+2.3. If over 200, move detailed sections to `.claude/rules/` files.
+
+---
+
+## Phase 3: Settings Configuration
+
+**Goal:** Create `.claude/settings.json` with appropriate rules.
+
+### Steps
+
+3.1. Create `.claude/settings.json` with:
+
+```json
+{
+  "permissions": {
+    "allow": [],
+    "deny": []
+  }
+}
+```
+
+3.2. Add deny rules for sensitive paths:
+   - `.env*` files (secrets)
+   - `credentials*` files
+   - `**/node_modules/**`
+   - Production config files
+
+3.3. Add allow rules for common development operations:
+   - Build commands
+   - Test commands
+   - Lint/format commands
+
+---
+
+## Phase 4: Rules Setup
+
+**Goal:** Create contextual rules that load based on file paths.
+
+### Steps
+
+4.1. Create `.claude/rules/` directory.
+4.2. Create rules based on project structure:
+
+| Rule File | Activates When | Content |
+|-----------|----------------|---------|
+| `frontend.md` | Editing `src/components/**` | Component patterns, styling conventions |
+| `api.md` | Editing `src/api/**` or `pages/api/**` | API patterns, error handling |
+| `testing.md` | Editing `**/*.test.*` | Testing conventions, mock patterns |
+| `database.md` | Editing `supabase/**` or `prisma/**` | Migration patterns, schema rules |
+
+4.3. Each rule file should use frontmatter to specify activation paths:
+
+```markdown
+---
+paths:
+  - "src/components/**"
+---
+# Component Rules
+...
+```
+
+---
+
+## Phase 5: Hooks Configuration
+
+**Goal:** Integrate Claude Code hooks with the project's workflow.
+
+### Steps
+
+5.1. Assess which hooks would benefit the project:
+   - `PreToolUse` -- guard against modifying protected files
+   - `PostToolUse` -- log tool usage for audit
+   - `Notification` -- alert on specific events
+5.2. Create hooks in `.claude/hooks/` if project needs custom behavior.
+5.3. Register hooks in `.claude/settings.json`.
+
+---
+
+## Phase 6: MCP Setup
+
+**Goal:** Configure MCP servers relevant to the project.
+
+### Steps
+
+6.1. Based on detected tech stack, recommend MCP servers.
+6.2. Delegate to mcp-workflow task for full configuration.
+6.3. Document configured MCPs in CLAUDE.md.
+
+---
+
+## Phase 7: Agents Setup
+
+**Goal:** Create project-specific subagent definitions.
+
+### Steps
+
+7.1. Based on project complexity, create agents:
+   - For simple projects: no custom agents needed
+   - For medium projects: 1-2 specialized agents (e.g., code-reviewer, test-writer)
+   - For large projects: full agent team with topology
+
+7.2. Create agent files in `.claude/agents/`.
+7.3. Delegate to create-agent-definition task for each agent.
+
+---
+
+## Phase 8: Smoke Test
+
+**Goal:** Verify the integration works end-to-end.
+
+### Steps
+
+8.1. Verify all config files are valid JSON/YAML.
+8.2. Verify CLAUDE.md is under 200 lines and contains key sections.
+8.3. Test that rules load when editing relevant files.
+8.4. Test that MCP servers connect (if configured).
+8.5. Run a simple Claude Code command to verify everything works:
+   - Ask Claude to read a source file and explain it
+   - Verify it follows the conventions in CLAUDE.md
+
+---
+
+## Output Format
+
+```yaml
+integration_result:
+  project_type: "Next.js TypeScript"
+  files_created:
+    - "CLAUDE.md"
+    - ".claude/settings.json"
+    - ".claude/rules/frontend.md"
+    - ".claude/rules/testing.md"
+  mcp_configured: ["context7"]
+  agents_created: []
+  smoke_test:
+    config_valid: true
+    rules_load: true
+    mcp_connected: true
+    claude_responds: true
+  overall_status: "PASS"
+```
+
+---
+
+## Veto Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Project root has no source code files | HALT -- nothing to integrate with |
+| CLAUDE.md already exists and has managed sections | WARN -- merge instead of overwrite |
+| .claude/settings.json exists with custom rules | WARN -- merge, do not overwrite |
+| No write access to project directory | HALT -- cannot create config files |
+| Project uses unsupported language (no detection signals) | WARN -- generate generic CLAUDE.md |

package/squads/claude-code-mastery/tasks/mcp-integration-plan.md

@@ -0,0 +1,229 @@
+# Task: Plan MCP Server Integration
+
+**Task ID:** CCM-PI-005
+**Version:** 1.0.0
+**Command:** `*mcp-integration-plan`
+**Agent:** Conduit (project-integrator)
+**Purpose:** Plan MCP server integration for a project by analyzing needs, mapping capabilities to available servers, estimating context budget impact, and prioritizing by ROI.
+
+---
+
+## Overview
+
+```
+  Project Analysis
+       |
+       v
+  +---------------------+
+  | 1. Analyze Project   |
+  |    Needs             |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 2. Map Capabilities  |
+  |    to Available MCPs |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 3. Estimate Context  |
+  |    Budget Impact     |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 4. Prioritize by ROI |
+  +---------------------+
+       |
+       v
+  +---------------------+
+  | 5. Create Integration|
+  |    Plan              |
+  +---------------------+
+```
+
+---
+
+## Inputs
+
+| Field | Type | Source | Required | Validation |
+|-------|------|--------|----------|------------|
+| project_path | string | User or cwd | Yes | Valid project directory |
+| budget | enum | User | No | `minimal` (1-2 MCPs), `standard` (3-5), `full` (no limit) |
+| priorities | string[] | User | No | e.g., ["documentation", "web search", "database", "browser testing"] |
+
+---
+
+## Preconditions
+
+- Project directory accessible for analysis
+- Understanding of available MCP ecosystem (official + community)
+
+---
+
+## Execution Phases
+
+### Phase 1: Analyze Project Needs
+
+Examine the project to identify where MCP servers would add value:
+
+1. **Technology stack**: what frameworks, languages, databases are used
+2. **External dependencies**: APIs consumed, services integrated
+3. **Development workflow**: what tasks developers repeat frequently
+4. **Documentation needs**: which libraries lack good inline docs
+5. **Testing needs**: browser testing, API testing, E2E scenarios
+6. **Data needs**: web search, scraping, research tasks
+
+Produce a needs matrix:
+
+| Need Category | Specific Need | Frequency | Current Solution |
+|---------------|---------------|-----------|-----------------|
+| Documentation | React docs lookup | Daily | Manual browser search |
+| Database | Query execution | Hourly | Copy-paste to psql |
+| Search | Find code examples | Daily | Manual Google search |
+
+### Phase 2: Map Capabilities to Available MCPs
+
+Match identified needs to available MCP servers:
+
+**Official/Stable MCPs:**
+| MCP Server | Capabilities | Transport | Best For |
+|------------|-------------|-----------|----------|
+| context7 | Library documentation | stdio | Framework/library docs |
+| playwright | Browser automation | stdio | Web testing, screenshots |
+| postgres/supabase | Database queries | stdio | DB operations |
+| filesystem | File operations | stdio | Cross-directory access |
+
+**Community MCPs:**
+| MCP Server | Capabilities | Maturity | Best For |
+|------------|-------------|----------|----------|
+| exa | Web search | Stable | Research, finding examples |
+| apify | Web scraping | Stable | Data extraction |
+| github | GitHub API | Stable | Issue/PR management |
+| linear/jira | Project management | Varies | Task tracking |
+
+For each need, list candidate MCPs with fit score (1-5).
+
+### Phase 3: Estimate Context Budget Impact
+
+Each MCP server has a context cost. Estimate:
+
+1. **Tool registration cost**: number of tools exposed, description token count
+2. **Per-call cost**: average input/output size of tool calls
+3. **Startup latency**: time to initialize the server
+4. **Memory footprint**: resources consumed while running
+
+Calculate context budget:
+```
+Total context overhead = sum(tools_per_mcp * avg_description_tokens)
+% of 200K context window used by MCP registrations
+```
+
+**Budget guidelines:**
+| Budget Level | Max MCP Overhead | Max Servers |
+|-------------|-----------------|-------------|
+| Minimal | < 2% context window | 1-2 servers |
+| Standard | < 5% context window | 3-5 servers |
+| Full | < 10% context window | No hard limit |
+
+Flag any MCP that registers more than 20 tools (context-heavy).
+
+### Phase 4: Prioritize by ROI
+
+Score each candidate MCP:
+
+```
+ROI = (frequency_of_need * time_saved_per_use) / (context_cost + setup_effort)
+```
+
+Where:
+- **frequency_of_need**: daily=5, weekly=3, monthly=1
+- **time_saved_per_use**: minutes saved vs manual approach
+- **context_cost**: token overhead (normalized 1-5)
+- **setup_effort**: configuration difficulty (1=trivial, 5=complex)
+
+Rank all candidates by ROI score descending.
+
+### Phase 5: Create Integration Plan
+
+Produce the final plan with phased rollout:
+
+**Phase A (Day 1)**: highest ROI MCPs, zero or minimal configuration
+**Phase B (Week 1)**: medium ROI MCPs, moderate setup required
+**Phase C (As needed)**: lower ROI MCPs, add when specific need arises
+
+For each MCP in the plan:
+1. Configuration snippet for settings.json
+2. Required environment variables or credentials
+3. Verification command to test connectivity
+4. Expected context budget impact
+
+---
+
+## Output Format
+
+```markdown
+## MCP Integration Plan
+
+**Project:** {project_path}
+**Budget:** {budget_level}
+**Date:** {YYYY-MM-DD}
+
+### Needs Analysis
+
+| Need | Frequency | Matched MCP | ROI Score |
+|------|-----------|-------------|-----------|
+| {need} | {freq} | {mcp} | {score} |
+
+### Context Budget
+
+| MCP Server | Tools | Est. Tokens | % Window |
+|------------|-------|-------------|----------|
+| {mcp} | {N} | {N} | {N}% |
+| **Total** | | | {N}% |
+
+### Rollout Plan
+
+#### Phase A: Immediate (Day 1)
+1. **{mcp_name}**: {reason}
+   - ROI: {score}
+   - Config:
+     ```json
+     { "mcpServers": { "{name}": { ... } } }
+     ```
+   - Verify: {command}
+
+#### Phase B: Short-term (Week 1)
+1. **{mcp_name}**: {reason}
+
+#### Phase C: On-demand
+1. **{mcp_name}**: {reason}
+
+### Excluded MCPs
+
+| MCP | Reason for Exclusion |
+|-----|---------------------|
+| {mcp} | {reason} |
+```
+
+---
+
+## Veto Conditions
+
+- **NEVER** recommend MCPs that require credentials the user has not agreed to provide
+- **NEVER** exceed the stated budget level without explicit user approval
+- **NEVER** recommend experimental or abandoned MCPs without flagging maturity risk
+- **NEVER** install or configure MCPs in this task -- this task produces a plan only
+
+---
+
+## Completion Criteria
+
+- [ ] Project needs analyzed with frequency assessment
+- [ ] Available MCPs mapped to identified needs
+- [ ] Context budget estimated for each candidate
+- [ ] ROI scores calculated and ranked
+- [ ] Phased integration plan created with configuration snippets
+- [ ] Budget compliance verified
+- [ ] Plan delivered in standard format